Add KeyStoreBackedSecretKeyProvider, Fixes AB#3274176 (#2674)

## Summary
This PR has two main goals: to seamlessly update the encryption padding
used in the Android KeyStore, and to lay the groundwork for integrating
future cryptographic requirements with minimal changes.

---

### Phase 1: Replace `AndroidWrappedKeyProvider` with
`KeyStoreBackedSecretKeyProvider`

- **Controller Flag:** `ENABLE_KEYSTORE_BACKED_SECRET_KEY_PROVIDER`

- **Behavior When Enabled:**
- The factory will return `KeyStoreBackedSecretKeyProvider` instead of
`AndroidWrappedKeyProvider`.
- The new class behaves similarly to the previous one but introduces the
ability to:
    - Retrieve the paddings supported by the KeyStore `KeyPair`
- Maintain a list of available ciphers (`oaepCipherSpec` and
`pkcs1CipherSpec`)
- Select a compatible cipher for encryption/decryption based on what the
`KeyPair` supports.
- In this case, if the `KeyPair` only supports `PKCS1`, then all keys
will be encrypted and decrypted using `PKCS1`.


- **Goal:**
- Validate that the new provider functions equivalently to the existing
one.
  > Note: No encryption changes are introduced in this phase.

### Tests

- `AndroidWrappedKeyProviderTest` has been parameterized to confirm both
providers behave identically.
- `KeyStoreBackedSecretKeyProviderRolloutTest.java` includes test to
validate migration and rollback


---

### Phase 2: Enable New Wrapped Secret Key Format with Metadata Support
Before introducing new key types, we need to ensure that all new keys
include additional metadata that specifies how they were encrypted.

- **Controller Flag:** `ENABLE_NEW_WRAPPED_SECRET_KEY_FORMAT`

- **Behavior When Enabled:**
- `WrappedSecretKey` will use an enhanced binary format with the
following structure:
    - MAGIC BYTES (4 bytes)
    - SERIALIZER ID (4bytes)
    - Metadata length (4 bytes)
    - Metadata (format is decided by the serializer)
    - Raw encrypted key bytes

- **Goal:**
  - Future-proof the wrapped key by including metadata that specifies:
    - Key size
    - Algorithm
    - Transformation used for encryption
    - Key version  
- This allows the system to handle multiple key types if formats change
in the future.
  - Validate `WrappedSecretKey` can read both new and old keys.

### Tests
  - `WrappedSecretKeyTest`

---

### Phase 3: Add OAEP encryption padding.

- **Controller Flag:** `ENABLE_OAEP_WITH_SHA_AND_MGF1_PADDING`

- **Behavior When Enabled:**
- `CryptoParameterSpecFactory` will now return two paddings:
`ENCRYPTION_PADDING_RSA_PKCS1` and `ENCRYPTION_PADDING_RSA_OAEP` for the
KeyGen specifications.
- `KeyStoreBackedSecretKeyProvider` will generate a `KeyPair` that
supports `ENCRYPTION_PADDING_RSA_OAEP`.
- As a result, when a `SecretKey` needs to be wrapped, the provider will
select OAEP, since the `KeyPair` now supports this padding and OAEP
cipher support was already introduced in Phase 1.

- **Goal:**
  - All new keys will be encrypted /decrypted with OAEP
  - Existing keys will still be encrypted /decrypted with PKCS1

### Tests
- `KeyStoreBackedSecretKeyProviderRolloutTest.java` includes test to
validate migration and rollback

---

### Telemetry
| span_name | key_pair_gen_successful_method |
elapsed_time_keypair_generation | secret_key_wrapping_cipher |
secret_key_wrapping_operation |

|-------------------|----------------------------------------------------------------------------------------------|----------------------------------|------------------------------------------------------------|--------------------------------------------------------------|
| SecretKeyWrapping | null | |
CipherSpec(transformation='RSA/ECB/PKCS1Padding') |
KeyStoreBackedSecretKeyProvider:unwrapSecretKey |
| KeyPairGeneration |
KeyGenSpec(description='modern_spec_with_wrap_key', algorithm='RSA',
encryptionPaddings='[PKCS1Padding]') | 581 | | |
| KeyPairGeneration |
KeyGenSpec(description='modern_spec_with_wrap_key', algorithm='RSA',
encryptionPaddings='[PKCS1Padding]') | 294 | | |


[AB#3274176](https://identitydivision.visualstudio.com/fac9d424-53d2-45c0-91b5-ef6ba7a6bf26/_workitems/edit/3274176)
AzureAD/ad-accounts-for-android#3166

---------

Co-authored-by: Copilot <[email protected]>
Co-authored-by: Sowmya Malayanur <[email protected]>

Author: 3 people

changelog.txt

@@ -1,5 +1,6 @@
 vNext
 ----------
+- [MAJOR] Add KeyStoreBackedSecretKeyProvider (#2674)
 - [MINOR] Add Open Id configuration issuer validation reporting in OpenIdProviderConfigurationClient (#2751)
 - [MINOR] Add helper method to record elapsed time (#2768)
 - [MINOR] Implement TenantUtil (#2761)

common/src/androidTest/java/com/microsoft/identity/common/crypto/AndroidWrappedKeyProviderTest.java

@@ -31,26 +31,90 @@
 
 import com.microsoft.identity.common.adal.internal.AuthenticationSettings;
 import com.microsoft.identity.common.internal.util.AndroidKeyStoreUtil;
+import com.microsoft.identity.common.java.crypto.key.ISecretKeyProvider;
 import com.microsoft.identity.common.java.exception.ClientException;
 import com.microsoft.identity.common.java.util.FileUtil;
 
 import org.junit.Assert;
 import org.junit.Before;
 import org.junit.Ignore;
 import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.Parameterized;
 
 import java.io.File;
 import java.math.BigInteger;
 import java.security.KeyPair;
 import java.security.spec.AlgorithmParameterSpec;
 import java.util.Arrays;
+import java.util.Collection;
 import java.util.Date;
 
 import javax.crypto.SecretKey;
 import javax.security.auth.x500.X500Principal;
 
+@RunWith(Parameterized.class)
 public class AndroidWrappedKeyProviderTest {
 
+    @Parameterized.Parameter(0)
+    public String providerType;
+
+    @Parameterized.Parameters(name = "{0}")
+    public static Collection<Object[]> data() {
+        return Arrays.asList(new Object[][] {
+                {"KEYSTORE_BACKED"},
+                {"ANDROID_WRAPPED"}
+                // Add other provider types here as keywords
+        });
+    }
+
+    private ISecretKeyProvider createProvider() {
+        if ("KEYSTORE_BACKED".equals(providerType)) {
+            return new KeyStoreBackedSecretKeyProvider(context, MOCK_KEY_ALIAS, MOCK_KEY_FILE_PATH);
+        } else if ("ANDROID_WRAPPED".equals(providerType)) {
+            return new AndroidWrappedKeyProvider(MOCK_KEY_ALIAS, MOCK_KEY_FILE_PATH, context);
+        } else {
+            throw new IllegalArgumentException("Unsupported provider type: " + providerType);
+        }
+    }
+
+    private SecretKey getKeyFromCache(ISecretKeyProvider keyProvider) {
+        if (keyProvider instanceof AndroidWrappedKeyProvider) {
+            return ((AndroidWrappedKeyProvider) keyProvider).getKeyFromCache();
+        } else if (keyProvider instanceof KeyStoreBackedSecretKeyProvider) {
+            return ((KeyStoreBackedSecretKeyProvider) keyProvider).getKeyFromCache();
+        }
+        throw new IllegalArgumentException("Unsupported key provider type: " + keyProvider.getClass().getName());
+    }
+
+    private void clearKeyFromCache(ISecretKeyProvider keyProvider) {
+        if (keyProvider instanceof AndroidWrappedKeyProvider) {
+            ((AndroidWrappedKeyProvider) keyProvider).clearKeyFromCache();
+        } else if (keyProvider instanceof KeyStoreBackedSecretKeyProvider) {
+            ((KeyStoreBackedSecretKeyProvider) keyProvider).clearKeyFromCache();
+        } else {
+            throw new IllegalArgumentException("Unsupported key provider type: " + keyProvider.getClass().getName());
+        }
+    }
+
+    private SecretKey readSecretKeyFromStorage(ISecretKeyProvider keyProvider) throws ClientException {
+        if (keyProvider instanceof AndroidWrappedKeyProvider) {
+            return ((AndroidWrappedKeyProvider) keyProvider).readSecretKeyFromStorage();
+        } else if (keyProvider instanceof KeyStoreBackedSecretKeyProvider) {
+            return ((KeyStoreBackedSecretKeyProvider) keyProvider).readSecretKeyFromStorage();
+        }
+        throw new IllegalArgumentException("Unsupported key provider type: " + keyProvider.getClass().getName());
+    }
+
+    private SecretKey generateNewSecretKey(ISecretKeyProvider keyProvider) throws ClientException {
+        if (keyProvider instanceof AndroidWrappedKeyProvider) {
+            return ((AndroidWrappedKeyProvider) keyProvider).generateRandomKey();
+        } else if (keyProvider instanceof KeyStoreBackedSecretKeyProvider) {
+            return ((KeyStoreBackedSecretKeyProvider) keyProvider).generateNewSecretKey();
+        }
+        throw new IllegalArgumentException("Unsupported key provider type: " + keyProvider.getClass().getName());
+    }
+
     final Context context = ApplicationProvider.getApplicationContext();
     final String MOCK_KEY_ALIAS = "MOCK_KEY_ALIAS";
     final String MOCK_KEY_FILE_PATH = "MOCK_KEY_FILE_PATH";
@@ -111,17 +175,17 @@ private AlgorithmParameterSpec getMockKeyPairGeneratorSpec(final String alias) {
 
     @Test
     public void testGenerateKey() throws ClientException {
-        final AndroidWrappedKeyProvider keyProvider = new AndroidWrappedKeyProvider(MOCK_KEY_ALIAS, MOCK_KEY_FILE_PATH, context);
-        final SecretKey secretKey = keyProvider.generateRandomKey();
+        final ISecretKeyProvider keyProvider = createProvider();
+        final SecretKey secretKey = generateNewSecretKey(keyProvider);
 
         Assert.assertEquals(AES_ALGORITHM, secretKey.getAlgorithm());
     }
 
     @Test
     public void testReadKeyDirectly() throws ClientException {
-        final AndroidWrappedKeyProvider keyProvider = initkeyProviderWithKeyEntry();
+        final ISecretKeyProvider keyProvider = initkeyProviderWithKeyEntry();
         final SecretKey secretKey = keyProvider.getKey();
-        final SecretKey storedSecretKey = keyProvider.readSecretKeyFromStorage();
+        final SecretKey storedSecretKey = readSecretKeyFromStorage(keyProvider);
 
         // They're not the same object!
         Assert.assertNotSame(secretKey, storedSecretKey);
@@ -139,12 +203,12 @@ public void testReadKeyDirectly() throws ClientException {
     public void testLoadKey() throws ClientException {
         // Nothing exists. This load key function should generate a key if the key hasn't exist.
         Assert.assertNull(AndroidKeyStoreUtil.readKey(MOCK_KEY_ALIAS));
-        Assert.assertNull(FileUtil.readFromFile(getKeyFile(), AndroidWrappedKeyProvider.KEY_FILE_SIZE));
+        Assert.assertNull(FileUtil.readFromFile(getKeyFile(), KeyStoreBackedSecretKeyProvider.KEY_FILE_SIZE));
 
-        final AndroidWrappedKeyProvider keyProvider = new AndroidWrappedKeyProvider(MOCK_KEY_ALIAS, MOCK_KEY_FILE_PATH, context);
+        final ISecretKeyProvider keyProvider = createProvider();
         final SecretKey secretKey = keyProvider.getKey();
 
-        final SecretKey key = keyProvider.getKeyFromCache();
+        final SecretKey key = getKeyFromCache(keyProvider);
         Assert.assertNotNull(key);
         Assert.assertEquals(AES_ALGORITHM, secretKey.getAlgorithm());
         Assert.assertArrayEquals(secretKey.getEncoded(), key.getEncoded());
@@ -154,18 +218,18 @@ public void testLoadKey() throws ClientException {
     @Test
     public void testLoadKeyFromCorruptedFile_TruncatedExisingKey() throws ClientException {
         // Create a new Keystore-wrapped key.
-        final AndroidWrappedKeyProvider keyProvider = new AndroidWrappedKeyProvider(MOCK_KEY_ALIAS, MOCK_KEY_FILE_PATH, context);
-        keyProvider.generateRandomKey();
+        final ISecretKeyProvider keyProvider = createProvider();
+        generateNewSecretKey(keyProvider);
 
-        final byte[] wrappedKey = FileUtil.readFromFile(getKeyFile(), AndroidWrappedKeyProvider.KEY_FILE_SIZE);
+        final byte[] wrappedKey = FileUtil.readFromFile(getKeyFile(), KeyStoreBackedSecretKeyProvider.KEY_FILE_SIZE);
         Assert.assertNotNull(wrappedKey);
 
         // Overwrite the key file with corrupted data.
         FileUtil.writeDataToFile(Arrays.copyOfRange(wrappedKey, 0, wrappedKey.length/2), getKeyFile());
 
         // It should fail to read, with an exception, and everything should be wiped.
         try{
-            keyProvider.readSecretKeyFromStorage();
+            readSecretKeyFromStorage(keyProvider);
             Assert.fail();
         } catch (ClientException e){
             Assert.assertEquals(INVALID_KEY, e.getErrorCode());
@@ -175,24 +239,24 @@ public void testLoadKeyFromCorruptedFile_TruncatedExisingKey() throws ClientExce
         Assert.assertFalse(getKeyFile().exists());
 
         // the next read should be unblocked.
-        Assert.assertNull(keyProvider.readSecretKeyFromStorage());
+        Assert.assertNull(readSecretKeyFromStorage(keyProvider));
     }
 
     @Test
     public void testLoadKeyFromCorruptedFile_InjectGarbage() throws ClientException {
         // Create a new Keystore-wrapped key.
-        final AndroidWrappedKeyProvider keyProvider = new AndroidWrappedKeyProvider(MOCK_KEY_ALIAS, MOCK_KEY_FILE_PATH, context);
-        keyProvider.generateRandomKey();
+        final ISecretKeyProvider keyProvider = createProvider();
+        generateNewSecretKey(keyProvider);
 
-        final byte[] wrappedKey = FileUtil.readFromFile(getKeyFile(), AndroidWrappedKeyProvider.KEY_FILE_SIZE);
+        final byte[] wrappedKey = FileUtil.readFromFile(getKeyFile(), KeyStoreBackedSecretKeyProvider.KEY_FILE_SIZE);
         Assert.assertNotNull(wrappedKey);
 
         // Overwrite the key file with corrupted data.
         FileUtil.writeDataToFile(new byte[]{10, 20, 30, 40}, getKeyFile());
 
         // It should fail to read, with an exception, and everything should be wiped.
         try{
-            keyProvider.readSecretKeyFromStorage();
+            readSecretKeyFromStorage(keyProvider);
             Assert.fail();
         } catch (ClientException e){
             Assert.assertEquals(INVALID_KEY, e.getErrorCode());
@@ -202,14 +266,14 @@ public void testLoadKeyFromCorruptedFile_InjectGarbage() throws ClientException
         Assert.assertFalse(getKeyFile().exists());
 
         // the next read should be unblocked.
-        Assert.assertNull(keyProvider.readSecretKeyFromStorage());
+        Assert.assertNull(readSecretKeyFromStorage(keyProvider));
     }
 
     // 1s With Google Pixel XL, OS Version 29 (100 loop)
     @Test
     @Ignore
     public void testPerf_WithCachedKey() throws ClientException {
-        final AndroidWrappedKeyProvider keyProvider = new AndroidWrappedKeyProvider(MOCK_KEY_ALIAS, MOCK_KEY_FILE_PATH, context);
+        final ISecretKeyProvider keyProvider = createProvider();
 
         long timeStartLoop = System.nanoTime();
         for (int i = 0; i < TEST_LOOP; i++) {
@@ -224,11 +288,11 @@ public void testPerf_WithCachedKey() throws ClientException {
     @Test
     @Ignore("Performance test, ignore in normal test run")
     public void testPerf_NoCachedKey() throws ClientException {
-        final AndroidWrappedKeyProvider keyProvider = new AndroidWrappedKeyProvider(MOCK_KEY_ALIAS, MOCK_KEY_FILE_PATH, context);
+        final ISecretKeyProvider keyProvider = createProvider();
 
         long timeStartLoopNotCached = System.nanoTime();
         for (int i = 0; i < 100; i++) {
-            keyProvider.clearKeyFromCache();
+            clearKeyFromCache(keyProvider);
             keyProvider.getKey();
         }
         long timeFinishLoopNotCached = System.nanoTime();
@@ -241,31 +305,31 @@ public void testPerf_NoCachedKey() throws ClientException {
      */
     @Test
     public void testLoadDeletedKeyStoreKey() throws ClientException {
-        final AndroidWrappedKeyProvider keyProvider = initkeyProviderWithKeyEntry();
+        final ISecretKeyProvider keyProvider = initkeyProviderWithKeyEntry();
 
         AndroidKeyStoreUtil.deleteKey(MOCK_KEY_ALIAS);
 
         // Cached key also be wiped.
-        final SecretKey key = keyProvider.getKeyFromCache();
+        final SecretKey key = getKeyFromCache(keyProvider);
         Assert.assertNull(key);
     }
 
     @Test
     public void testLoadDeletedKeyFile() throws ClientException {
-        final AndroidWrappedKeyProvider keyProvider = initkeyProviderWithKeyEntry();
+        final ISecretKeyProvider keyProvider = initkeyProviderWithKeyEntry();
 
         FileUtil.deleteFile(getKeyFile());
 
         // Cached key also be wiped.
-        final SecretKey key = keyProvider.getKeyFromCache();
+        final SecretKey key = getKeyFromCache(keyProvider);
         Assert.assertNull(key);
     }
 
-    private AndroidWrappedKeyProvider initkeyProviderWithKeyEntry() throws ClientException {
-        final AndroidWrappedKeyProvider keyProvider = new AndroidWrappedKeyProvider(MOCK_KEY_ALIAS, MOCK_KEY_FILE_PATH, context);
+    private ISecretKeyProvider initkeyProviderWithKeyEntry() throws ClientException {
+        final ISecretKeyProvider keyProvider = createProvider();
         final SecretKey key = keyProvider.getKey();
         Assert.assertNotNull(key);
-        Assert.assertNotNull(keyProvider.getKeyFromCache());
+        Assert.assertNotNull(getKeyFromCache(keyProvider));
         return keyProvider;
     }
 }