Changes to Key Vault Keys to align with other languages for GA. (#21734)

* Re-ordered parameters in EncryptResult to show authenticationTag before additionalAuthenticatedData to match other classes like DecryptParameters.

* Removed EXPORT from the KeyOperation enum.

* Added factory methods for RSA algorithms in DecryptParameters and EncryptParameters.

* Added createOctKey() and createOctKeyWithResponse() to KeyClient and KeyAsyncClient.

* Fixed CheckStyle issue.

* Updated CHANGELOG.

* Changed usages of AES key to symmetric key in KeyClient, KeyAsyncClient and CreateOctKeyOptions. Corrected a small mistake in CreateRsaKeyOptions.

sdk/keyvault/azure-security-keyvault-keys/CHANGELOG.md

@@ -5,7 +5,18 @@
 ### Bug Fixes
 - Ensured that `RetryPolicy` and `HttpLogOptions` use a default implementation when creating Key Vault clients if not set or set to `null`.
 
-### Changes
+### New Features
+- Added `createOctKey()` and `createOctKeyWithResponse()` to `KeyClient` and `KeyAsyncClient`.
+- Added factory methods for RSA algorithms in `DecryptParameters` and `EncryptParameters`:
+    - `createRsa15Parameters()`
+    - `createRsaOaepParameters()`
+    - `createRsaOaep256Parameters()`
+
+### Breaking Changes
+- Removed `EXPORT` from the `KeyOperation` enum.
+- Re-ordered parameters in the `EncryptResult` constructor to show `authenticationTag` before `additionalAuthenticatedData` to align with classes like `DecryptParameters`.
+
+#### Other Changes
 - Renamed `keyId` to `id` in `KeyVaultKeyIdentifier`.
 - Added the `@ServiceMethod` annotation to all public methods that call the Key Vault service in `KeyClient`, `KeyAsyncClient`, `CryptographyClient` and `CryptographyAsyncClient`.
 

sdk/keyvault/azure-security-keyvault-keys/src/main/java/com/azure/security/keyvault/keys/KeyAsyncClient.java

@@ -24,6 +24,7 @@
 import com.azure.core.util.polling.PollingContext;
 import com.azure.security.keyvault.keys.models.CreateEcKeyOptions;
 import com.azure.security.keyvault.keys.models.CreateKeyOptions;
+import com.azure.security.keyvault.keys.models.CreateOctKeyOptions;
 import com.azure.security.keyvault.keys.models.CreateRsaKeyOptions;
 import com.azure.security.keyvault.keys.models.DeletedKey;
 import com.azure.security.keyvault.keys.models.ImportKeyOptions;
@@ -404,6 +405,92 @@ Mono<Response<KeyVaultKey>> createEcKeyWithResponse(CreateEcKeyOptions createEcK
             .doOnError(error -> logger.warning("Failed to create Ec key - {}", createEcKeyOptions.getName(), error));
     }
 
+    /**
+     * Creates and stores a new symmetric key in Key Vault. If the named key already exists, Azure Key Vault creates a
+     * new version of the key. This operation requires the keys/create permission.
+     *
+     * <p>The {@link CreateOctKeyOptions} parameter is required. The {@link CreateOctKeyOptions#getExpiresOn() expires}
+     * and {@link CreateOctKeyOptions#getNotBefore() notBefore} values are optional. The
+     * {@link CreateOctKeyOptions#isEnabled() enabled} field is set to true by Azure Key Vault, if not specified.</p>
+     *
+     * <p>The {@link CreateOctKeyOptions#getKeyType() keyType} indicates the type of key to create.
+     * Possible values include: {@link KeyType#OCT OCT} and {@link KeyType#OCT_HSM OCT-HSM}.</p>
+     *
+     * <p><strong>Code Samples</strong></p>
+     * <p>Creates a new symmetric key. The key activates in one day and expires in one year. Subscribes to the call
+     * asynchronously and prints out the details of the newly created key when a response has been received.</p>
+     *
+     * {@codesnippet com.azure.security.keyvault.keys.async.keyAsyncClient.createOctKey#CreateOctKeyOptions}
+     *
+     * @param createOctKeyOptions The key options object containing information about the ec key being created.
+     *
+     * @return A {@link Mono} containing the {@link KeyVaultKey created key}.
+     *
+     * @throws NullPointerException If {@code ecKeyCreateOptions} is {@code null}.
+     * @throws ResourceModifiedException If {@code ecKeyCreateOptions} is malformed.
+     */
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    public Mono<KeyVaultKey> createOctKey(CreateOctKeyOptions createOctKeyOptions) {
+        try {
+            return createOctKeyWithResponse(createOctKeyOptions).flatMap(FluxUtil::toMono);
+        } catch (RuntimeException ex) {
+            return monoError(logger, ex);
+        }
+    }
+
+    /**
+     * Creates and stores a new symmetric key in Key Vault. If the named key already exists, Azure Key Vault creates
+     * a new version of the key. This operation requires the keys/create permission.
+     *
+     * <p>The {@link CreateOctKeyOptions} parameter is required. The {@link CreateOctKeyOptions#getExpiresOn() expires}
+     * and {@link CreateOctKeyOptions#getNotBefore() notBefore} values are optional. The
+     * {@link CreateOctKeyOptions#isEnabled() enabled} field is set to true by Azure Key Vault, if not specified.</p>
+     *
+     * <p>The {@link CreateOctKeyOptions#getKeyType() keyType} indicates the type of key to create.
+     * Possible values include: {@link KeyType#OCT OCT} and {@link KeyType#OCT_HSM OCT-HSM}.</p>
+     *
+     * <p><strong>Code Samples</strong></p>
+     * <p>Creates a new symmetric key. The key activates in one day and expires in one year. Subscribes to the call
+     * asynchronously and prints out the details of the newly created key when a response has been received.</p>
+     *
+     * {@codesnippet com.azure.security.keyvault.keys.async.keyAsyncClient.createOctKeyWithResponse#CreateOctKeyOptions}
+     *
+     * @param createOctKeyOptions The key options object containing information about the ec key being created.
+     *
+     * @return A {@link Mono} containing a {@link Response} whose {@link Response#getValue() value} contains the {@link
+     * KeyVaultKey created key}.
+     *
+     * @throws NullPointerException If {@code createOctKeyOptions} is {@code null}.
+     * @throws ResourceModifiedException If {@code createOctKeyOptions} is malformed.
+     */
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    public Mono<Response<KeyVaultKey>> createOctKeyWithResponse(CreateOctKeyOptions createOctKeyOptions) {
+        try {
+            return withContext(context -> createOctKeyWithResponse(createOctKeyOptions, context));
+        } catch (RuntimeException ex) {
+            return monoError(logger, ex);
+        }
+    }
+
+    Mono<Response<KeyVaultKey>> createOctKeyWithResponse(CreateOctKeyOptions createOctKeyOptions, Context context) {
+        Objects.requireNonNull(createOctKeyOptions, "The create key options cannot be null.");
+
+        context = context == null ? Context.NONE : context;
+
+        KeyRequestParameters parameters = new KeyRequestParameters()
+            .setKty(createOctKeyOptions.getKeyType())
+            .setKeyOps(createOctKeyOptions.getKeyOperations())
+            .setKeyAttributes(new KeyRequestAttributes(createOctKeyOptions))
+            .setTags(createOctKeyOptions.getTags());
+
+        return service.createKey(vaultUrl, createOctKeyOptions.getName(), apiVersion, ACCEPT_LANGUAGE, parameters,
+            CONTENT_TYPE_HEADER_VALUE, context.addData(AZ_TRACING_NAMESPACE_KEY, KEYVAULT_TRACING_NAMESPACE_VALUE))
+            .doOnRequest(ignored -> logger.verbose("Creating symmetric key - {}", createOctKeyOptions.getName()))
+            .doOnSuccess(response -> logger.verbose("Created symmetric key - {}", response.getValue().getName()))
+            .doOnError(error ->
+                logger.warning("Failed to create symmetric key - {}", createOctKeyOptions.getName(), error));
+    }
+
     /**
      * Imports an externally created key and stores it in key vault. The import key operation may be used to import any
      * key type into the Azure Key Vault. If the named key already exists, Azure Key Vault creates a new version of the

sdk/keyvault/azure-security-keyvault-keys/src/main/java/com/azure/security/keyvault/keys/KeyClient.java

@@ -13,6 +13,7 @@
 import com.azure.core.annotation.ServiceClient;
 import com.azure.core.util.Context;
 import com.azure.core.util.polling.SyncPoller;
+import com.azure.security.keyvault.keys.models.CreateOctKeyOptions;
 import com.azure.security.keyvault.keys.models.DeletedKey;
 import com.azure.security.keyvault.keys.models.CreateEcKeyOptions;
 import com.azure.security.keyvault.keys.models.KeyVaultKey;
@@ -242,7 +243,8 @@ public KeyVaultKey createEcKey(CreateEcKeyOptions createEcKeyOptions) {
      *
      * <p><strong>Code Samples</strong></p>
      * <p>Creates a new EC key with P-384 web key curve. The key activates in one day and expires in one year. Prints
-     * out the details of the created key.</p>
+     * out the details of the newly created key.</p>
+     *
      * {@codesnippet com.azure.keyvault.keys.keyclient.createEcKeyWithResponse#keyOptions-Context}
      *
      * @param createEcKeyOptions The key options object containing information about the ec key being created.
@@ -256,6 +258,64 @@ public Response<KeyVaultKey> createEcKeyWithResponse(CreateEcKeyOptions createEc
         return client.createEcKeyWithResponse(createEcKeyOptions, context).block();
     }
 
+    /**
+     * Creates and stores a new symmetric key in Key Vault. If the named key already exists, Azure Key Vault creates
+     * a new version of the key. This operation requires the keys/create permission.
+     *
+     * <p>The {@link CreateOctKeyOptions} parameter is required. The {@link CreateOctKeyOptions#getExpiresOn() expires}
+     * and {@link CreateOctKeyOptions#getNotBefore() notBefore} values are optional. The
+     * {@link CreateOctKeyOptions#isEnabled() enabled} field is set to true by Azure Key Vault, if not specified.</p>
+     *
+     * <p>The {@link CreateOctKeyOptions#getKeyType() keyType} indicates the type of key to create.
+     * Possible values include: {@link KeyType#OCT OCT} and {@link KeyType#OCT_HSM OCT-HSM}.</p>
+     *
+     * <p><strong>Code Samples</strong></p>
+     * <p>Creates a new symmetric key. The key activates in one day and expires in one year. Prints out the details of
+     * the newly created key.</p>
+     *
+     * {@codesnippet com.azure.security.keyvault.keys.async.keyClient.createOctKey#CreateOctKeyOptions}
+     *
+     * @param createOctKeyOptions The key options object containing information about the ec key being created.
+     *
+     * @return The {@link KeyVaultKey created key}.
+     *
+     * @throws NullPointerException If {@code ecKeyCreateOptions} is {@code null}.
+     * @throws ResourceModifiedException If {@code ecKeyCreateOptions} is malformed.
+     */
+    public KeyVaultKey createOctKey(CreateOctKeyOptions createOctKeyOptions) {
+        return createOctKeyWithResponse(createOctKeyOptions, Context.NONE).getValue();
+    }
+
+    /**
+     * Creates and stores a new symmetric key in Key Vault. If the named key already exists, Azure Key Vault creates a
+     * new version of the key. This operation requires the keys/create permission.
+     *
+     * <p>The {@link CreateOctKeyOptions} parameter is required. The {@link CreateOctKeyOptions#getExpiresOn() expires}
+     * and {@link CreateOctKeyOptions#getNotBefore() notBefore} values are optional. The
+     * {@link CreateOctKeyOptions#isEnabled() enabled} field is set to true by Azure Key Vault, if not specified.</p>
+     *
+     * <p>The {@link CreateOctKeyOptions#getKeyType() keyType} indicates the type of key to create.
+     * Possible values include: {@link KeyType#OCT OCT} and {@link KeyType#OCT_HSM OCT-HSM}.</p>
+     *
+     * <p><strong>Code Samples</strong></p>
+     * <p>Creates a new symmetric key. The key activates in one day and expires in one year. Prints out the details of
+     * the
+     * created key.</p>
+     *
+     * {@codesnippet com.azure.security.keyvault.keys.async.keyClient.createOctKey#CreateOctKeyOptions-Context}
+     *
+     * @param createOctKeyOptions The key options object containing information about the ec key being created.
+     * @param context Additional context that is passed through the Http pipeline during the service call.
+     *
+     * @return A {@link Response} whose {@link Response#getValue() value} contains the {@link KeyVaultKey created key}.
+     *
+     * @throws NullPointerException If {@code ecKeyCreateOptions} is {@code null}.
+     * @throws ResourceModifiedException If {@code ecKeyCreateOptions} is malformed.
+     */
+    public Response<KeyVaultKey> createOctKeyWithResponse(CreateOctKeyOptions createOctKeyOptions, Context context) {
+        return client.createOctKeyWithResponse(createOctKeyOptions, context).block();
+    }
+
     /**
      * Imports an externally created key and stores it in key vault. The import key operation may be used to import any
      * key type into the Azure Key Vault. If the named key already exists, Azure Key Vault creates a new version of the

sdk/keyvault/azure-security-keyvault-keys/src/main/java/com/azure/security/keyvault/keys/cryptography/AesKeyCryptographyClient.java

@@ -110,8 +110,8 @@ Mono<EncryptResult> encryptAsync(EncryptParameters encryptParameters, Context co
                 new IllegalStateException("Encryption algorithm provided is not supported: " + algorithm));
         }
 
-        return Mono.just(new EncryptResult(ciphertext, algorithm, jsonWebKey.getId(), iv, additionalAuthenticatedData,
-            null));
+        return Mono.just(new EncryptResult(ciphertext, algorithm, jsonWebKey.getId(), iv, null,
+            additionalAuthenticatedData));
     }
 
     @Override

sdk/keyvault/azure-security-keyvault-keys/src/main/java/com/azure/security/keyvault/keys/cryptography/CryptographyServiceClient.java

@@ -145,8 +145,8 @@ Mono<EncryptResult> encrypt(EncryptParameters encryptParameters, Context context
                 KeyOperationResult keyOperationResult = keyOperationResultResponse.getValue();
 
                 return new EncryptResult(keyOperationResult.getResult(), algorithm, keyId,
-                    keyOperationResult.getIv(), keyOperationResult.getAdditionalAuthenticatedData(),
-                    keyOperationResult.getAuthenticationTag());
+                    keyOperationResult.getIv(), keyOperationResult.getAuthenticationTag(),
+                    keyOperationResult.getAdditionalAuthenticatedData());
             });
     }
 

sdk/keyvault/azure-security-keyvault-keys/src/main/java/com/azure/security/keyvault/keys/cryptography/DecryptParameters.java

@@ -208,6 +208,45 @@ public static DecryptParameters createA256GcmParameters(byte[] ciphertext, byte[
             additionalAuthenticatedData);
     }
 
+    /**
+     * Factory method to create an instance of {@link DecryptParameters} with the given parameters for
+     * {@link EncryptionAlgorithm#RSA1_5}.
+     *
+     * @param ciphertext The content to be decrypted.
+     *
+     * @return The {@link DecryptParameters}.
+     */
+    public static DecryptParameters createRsa15Parameters(byte[] ciphertext) {
+        return new DecryptParameters(EncryptionAlgorithm.RSA1_5, ciphertext, null, null,
+            null);
+    }
+
+    /**
+     * Factory method to create an instance of {@link DecryptParameters} with the given parameters for
+     * {@link EncryptionAlgorithm#RSA_OAEP}.
+     *
+     * @param ciphertext The content to be decrypted.
+     *
+     * @return The {@link DecryptParameters}.
+     */
+    public static DecryptParameters createRsaOaepParameters(byte[] ciphertext) {
+        return new DecryptParameters(EncryptionAlgorithm.RSA_OAEP, ciphertext, null, null,
+            null);
+    }
+
+    /**
+     * Factory method to create an instance of {@link DecryptParameters} with the given parameters for
+     * {@link EncryptionAlgorithm#RSA_OAEP_256}.
+     *
+     * @param ciphertext The content to be decrypted.
+     *
+     * @return The {@link DecryptParameters}.
+     */
+    public static DecryptParameters createRsaOaep256Parameters(byte[] ciphertext) {
+        return new DecryptParameters(EncryptionAlgorithm.RSA_OAEP_256, ciphertext, null, null,
+            null);
+    }
+
     /**
      * Creates an instance of {@link DecryptParameters} with the given parameters.
      *