Added a convenience method to key clients to create a cryptography client. (Azure#24503)

* Added a new convenience method to KeyClient and KeyAsyncClient to obtain a CryptographyClient and CryptographyAsyncClient (respectively) for a given key.

* Added tests.

* Updated crypto code snippets.

* Updated CHANGELOG.

* Added test recordings.

* Applied PR feedback.

* Fixed CheckStyle issues.

* Fixed test issues.

* Fixed test and samples issues, updated test-resources.json template and re-recorded tests.

* Updated documentation.

* Fixed yet another CheckStyle issue.

Author: vcolin7

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

@@ -3,10 +3,27 @@
 ## 4.4.0-beta.4 (Unreleased)
 
 ### Features Added
-
-### Breaking Changes
-
-### Bugs Fixed
+- Added new functions to key clients to enable key rotation:
+  - `KeyClient`
+    - `rotateKey(String name)`
+    - `rotateKeyWithResponse(String name, Context context)`
+    - `getKeyRotationPolicy(String name)`
+    - `getKeyRotationPolicyWithResponse(String name, Context context)`
+    - `updateKeyRotationPolicy(String name, KeyRotationPolicyProperties keyRotationPolicyProperties)`
+    - `updateKeyRotationPolicyWithResponse(String name, KeyRotationPolicyProperties keyRotationPolicyProperties, Context context)`
+  - `KeyAsyncClient`
+    - `rotateKey(String name)`
+    - `rotateKeyWithResponse(String name)`
+    - `getKeyRotationPolicy(String name)`
+    - `getKeyRotationPolicyWithResponse(String name)`
+    - `updateKeyRotationPolicy(String name, KeyRotationPolicyProperties keyRotationPolicyProperties)`
+    - `updateKeyRotationPolicyWithResponse(String name, KeyRotationPolicyProperties keyRotationPolicyProperties)`
+- Added convenience methods to create cryptography clients using key clients:
+  - `KeyClient.getCryptographyClient(String keyName)`
+  - `KeyClient.getCryptographyClient(String keyName, String keyVersion)`
+  - `KeyAsyncClient.getCryptographyAsyncClient(String keyName)`
+  - `KeyAsyncClient.getCryptographyAsyncClient(String keyName, String keyVersion)`
+- `CryptographyClientBuilder` does not require `keyIdentifier` to a include a key version. If no version is provided, cryptographic operations will be made using the latest version of the key.
 
 ### Other Changes
 

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

@@ -14,6 +14,8 @@
 import com.azure.core.http.rest.Response;
 import com.azure.core.util.Context;
 import com.azure.core.util.polling.SyncPoller;
+import com.azure.security.keyvault.keys.cryptography.CryptographyClient;
+import com.azure.security.keyvault.keys.cryptography.CryptographyClientBuilder;
 import com.azure.security.keyvault.keys.models.CreateEcKeyOptions;
 import com.azure.security.keyvault.keys.models.CreateKeyOptions;
 import com.azure.security.keyvault.keys.models.CreateOctKeyOptions;
@@ -66,6 +68,44 @@ public String getVaultUrl() {
         return client.getVaultUrl();
     }
 
+    /**
+     * Creates a {@link CryptographyClient} for the latest version of a given key.
+     *
+     * <p>To ensure correct behavior when performing operations such as {@code Decrypt}, {@code Unwrap} and
+     * {@code Verify}, it is recommended to use a {@link CryptographyClient} created for the specific key
+     * version that was used for the corresponding inverse operation: {@code Encrypt}, {@code Wrap}, or
+     * {@code Sign}, respectively.</p>
+     *
+     * <p>You can provide a key version either via {@link KeyClient#getCryptographyClient(String, String)} or by
+     * ensuring it is included in the {@code keyIdentifier} passed to
+     * {@link CryptographyClientBuilder#keyIdentifier(String)} before building a client.</p>
+     *
+     * @param keyName The name of the key.
+     *
+     * @return An instance of {@link CryptographyClient} associated with the latest version of a key with the
+     * provided name.
+     *
+     * @throws IllegalArgumentException If {@code keyName} is {@code null} or empty.
+     */
+    public CryptographyClient getCryptographyClient(String keyName) {
+        return client.getCryptographyClientBuilder(keyName, null).buildClient();
+    }
+
+    /**
+     * Creates a {@link CryptographyClient} for a given key version.
+     *
+     * @param keyName The name of the key.
+     * @param keyVersion The key version.
+     *
+     * @return An instance of {@link CryptographyClient} associated with a key with the provided name and version.
+     * If {@code keyVersion} is {@code null} or empty, the client will use the latest version of the key.
+     *
+     * @throws IllegalArgumentException If {@code keyName} is {@code null} or empty.
+     */
+    public CryptographyClient getCryptographyClient(String keyName, String keyVersion) {
+        return client.getCryptographyClientBuilder(keyName, keyVersion).buildClient();
+    }
+
     /**
      * Creates a new {@link KeyVaultKey key} and stores it in the key vault. The create key operation can be used to
      * create any {@link KeyType keyType} in Azure Key Vault. If a {@link KeyVaultKey key} with the provided name

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

@@ -53,17 +53,15 @@
  *
  * {@codesnippet com.azure.security.keyvault.keys.cryptography.CryptographyAsyncClient.instantiation}
  * {@codesnippet com.azure.security.keyvault.keys.cryptography.CryptographyAsyncClient.withJsonWebKey.instantiation}
- * {@codesnippet com.azure.security.keyvault.keys.cryptography.CryptographyAsyncClient.withHttpClient.instantiation}
- * {@codesnippet com.azure.security.keyvault.keys.cryptography.CryptographyAsyncClient.withPipeline.instantiation}
  *
  * @see CryptographyClientBuilder
  */
 @ServiceClient(builder = CryptographyClientBuilder.class, isAsync = true, serviceInterfaces = CryptographyService.class)
 public class CryptographyAsyncClient {
-    static final String SECRETS_COLLECTION = "secrets";
     // Please see <a href=https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/azure-services-resource-providers>here</a>
     // for more information on Azure resource provider namespaces.
     static final String KEYVAULT_TRACING_NAMESPACE_VALUE = "Microsoft.KeyVault";
+    static final String SECRETS_COLLECTION = "secrets";
 
     JsonWebKey key;
 
@@ -792,15 +790,14 @@ Mono<VerifyResult> verifyData(SignatureAlgorithm algorithm, byte[] data, byte[]
 
     private void unpackAndValidateId(String keyId) {
         if (CoreUtils.isNullOrEmpty(keyId)) {
-            throw logger.logExceptionAsError(new IllegalArgumentException("Key Id is invalid"));
+            throw logger.logExceptionAsError(new IllegalArgumentException("'keyId' cannot be null or empty."));
         }
 
         try {
             URL url = new URL(keyId);
             String[] tokens = url.getPath().split("/");
             String endpoint = url.getProtocol() + "://" + url.getHost();
             String keyName = (tokens.length >= 3 ? tokens[2] : null);
-            String version = (tokens.length >= 4 ? tokens[3] : null);
             this.keyCollection = (tokens.length >= 2 ? tokens[1] : null);
 
             if (Strings.isNullOrEmpty(endpoint)) {
@@ -809,9 +806,6 @@ private void unpackAndValidateId(String keyId) {
             } else if (Strings.isNullOrEmpty(keyName)) {
                 throw logger.logExceptionAsError(
                     new IllegalArgumentException("Key name in key identifier is invalid."));
-            } else if (Strings.isNullOrEmpty(version)) {
-                throw logger.logExceptionAsError(
-                    new IllegalArgumentException("Key version in key identifier is invalid."));
             }
         } catch (MalformedURLException e) {
             throw logger.logExceptionAsError(new IllegalArgumentException("The key identifier is malformed.", e));

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

@@ -37,8 +37,13 @@
  * It constructs an instance of the desired client.
  *
  * <p>The minimal configuration options required by {@link CryptographyClientBuilder cryptographyClientBuilder} to build
- * {@link CryptographyAsyncClient} are {@link JsonWebKey jsonWebKey} or {@link String Azure Key Vault key identifier}
- * and {@link TokenCredential credential}.</p>
+ * a {@link CryptographyAsyncClient} or a {@link CryptographyClient} are a {@link TokenCredential credential} and either
+ * a {@link JsonWebKey JSON Web Key} or a {@code Azure Key Vault key identifier}.</p>
+ *
+ * <p>To ensure correct behavior when performing operations such as {@code Decrypt}, {@code Unwrap} and
+ * {@code Verify}, it is recommended to use a {@link CryptographyAsyncClient} or {@link CryptographyClient} created
+ * for the specific key version that was used for the corresponding inverse operation: {@code Encrypt},
+ * {@code Wrap}, or {@code Sign}, respectively.</p>
  *
  * {@codesnippet com.azure.security.keyvault.keys.cryptography.CryptographyAsyncClient.instantiation}
  * {@codesnippet com.azure.security.keyvault.keys.cryptography.CryptographyAsyncClient.withJsonWebKey.instantiation}
@@ -227,6 +232,11 @@ CryptographyServiceVersion getServiceVersion() {
     /**
      * Sets the Azure Key Vault key identifier of the JSON Web Key to be used for cryptography operations.
      *
+     * <p>To ensure correct behavior when performing operations such as {@code Decrypt}, {@code Unwrap} and
+     * {@code Verify}, it is recommended to use a {@link CryptographyAsyncClient} or {@link CryptographyClient} created
+     * for the specific key version that was used for the corresponding inverse operation: {@code Encrypt}
+     * {@code Wrap}, or {@code Sign}, respectively.</p>
+     *
      * @param keyId The Azure Key Vault key identifier of the JSON Web Key stored in the key vault.
      *
      * @return The updated {@link CryptographyClientBuilder} object.