Class CryptographyAsyncClient

java.lang.Object
com.azure.security.keyvault.keys.cryptography.CryptographyAsyncClient
Direct Known Subclasses:
KeyEncryptionKeyAsyncClient

public class CryptographyAsyncClient extends Object
The CryptographyAsyncClient provides asynchronous methods to perform cryptographic operations using asymmetric and symmetric keys. The client supports encrypt, decrypt, wrap key, unwrap key, sign and verify operations using the configured key.

Samples to construct the sync client

 CryptographyAsyncClient cryptographyAsyncClient = new CryptographyClientBuilder()
     .keyIdentifier("<your-key-id>")
     .credential(new DefaultAzureCredentialBuilder().build())
     .buildAsyncClient();
 
 JsonWebKey jsonWebKey = new JsonWebKey().setId("SampleJsonWebKey");
 CryptographyAsyncClient cryptographyAsyncClient = new CryptographyClientBuilder()
     .jsonWebKey(jsonWebKey)
     .buildAsyncClient();
 
See Also:
  • Method Details

    • getKey

      public Mono<KeyVaultKey> getKey()
      Gets the public part of the configured key. The get key operation is applicable to all key types and it requires the keys/get permission for non-local operations.

      Code Samples

      Gets the configured key in the client. Subscribes to the call asynchronously and prints out the returned key details when a response has been received.

       cryptographyAsyncClient.getKey()
           .contextWrite(Context.of("key1", "value1", "key2", "value2"))
           .subscribe(key ->
               System.out.printf("Key returned with name: %s, and id: %s.%n", key.getName(), key.getId()));
       
      Returns:
      A Mono containing the requested key.
      Throws:
      ResourceNotFoundException - When the configured key doesn't exist in the key vault.
    • getKeyWithResponse

      public Mono<Response<KeyVaultKey>> getKeyWithResponse()
      Gets the public part of the configured key. The get key operation is applicable to all key types and it requires the keys/get permission for non-local operations.

      Code Samples

      Gets the configured key in the client. Subscribes to the call asynchronously and prints out the returned key details when a response has been received.

       cryptographyAsyncClient.getKeyWithResponse()
           .contextWrite(Context.of("key1", "value1", "key2", "value2"))
           .subscribe(keyResponse ->
               System.out.printf("Key returned with name: %s, and id: %s.%n", keyResponse.getValue().getName(),
                   keyResponse.getValue().getId()));
       
      Returns:
      A Mono containing a Response whose value contains the requested key.
      Throws:
      ResourceNotFoundException - When the configured key doesn't exist in the key vault.
    • encrypt

      public Mono<EncryptResult> encrypt(EncryptionAlgorithm algorithm, byte[] plaintext)
      Encrypts an arbitrary sequence of bytes using the configured key. Note that the encrypt operation only supports a single block of data, the size of which is dependent on the target key and the encryption algorithm to be used. The encrypt operation is supported for both symmetric keys and asymmetric keys. In case of asymmetric keys, the public portion of the key is used for encryption. This operation requires the keys/encrypt permission for non-local operations.

      The encryption algorithm indicates the type of algorithm to use for encrypting the specified plaintext. Possible values for asymmetric keys include: RSA1_5, RSA_OAEP and RSA_OAEP_256. Possible values for symmetric keys include: A128CBC, A128CBCPAD, A128CBC-HS256, A128GCM, A192CBC, A192CBCPAD, A192CBC-HS384, A192GCM, A256CBC, A256CBPAD, A256CBC-HS512 and A256GCM.

      Code Samples

      Encrypts the content. Subscribes to the call asynchronously and prints out the encrypted content details when a response has been received.

       byte[] plaintext = new byte[100];
       new Random(0x1234567L).nextBytes(plaintext);
      
       cryptographyAsyncClient.encrypt(EncryptionAlgorithm.RSA_OAEP, plaintext)
           .contextWrite(Context.of("key1", "value1", "key2", "value2"))
           .subscribe(encryptResult ->
               System.out.printf("Received encrypted content of length: %d, with algorithm: %s.%n",
                   encryptResult.getCipherText().length, encryptResult.getAlgorithm().toString()));
       
      Parameters:
      algorithm - The algorithm to be used for encryption.
      plaintext - The content to be encrypted.
      Returns:
      A Mono containing a EncryptResult whose cipher text contains the encrypted content.
      Throws:
      NullPointerException - If algorithm or plaintext are null.
      ResourceNotFoundException - If the key cannot be found for encryption.
      UnsupportedOperationException - If the encrypt operation is not supported or configured on the key.
    • encrypt

      public Mono<EncryptResult> encrypt(EncryptParameters encryptParameters)
      Encrypts an arbitrary sequence of bytes using the configured key. Note that the encrypt operation only supports a single block of data, the size of which is dependent on the target key and the encryption algorithm to be used. The encrypt operation is supported for both symmetric keys and asymmetric keys. In case of asymmetric keys, the public portion of the key is used for encryption. This operation requires the keys/encrypt permission for non-local operations.

      The encryption algorithm indicates the type of algorithm to use for encrypting the specified plaintext. Possible values for asymmetric keys include: RSA1_5, RSA_OAEP and RSA_OAEP_256. Possible values for symmetric keys include: A128CBC, A128CBCPAD, A128CBC-HS256, A128GCM, A192CBC, A192CBCPAD, A192CBC-HS384, A192GCM, A256CBC, A256CBPAD, A256CBC-HS512 and A256GCM.

      Code Samples

      Encrypts the content. Subscribes to the call asynchronously and prints out the encrypted content details when a response has been received.

       byte[] plaintextBytes = new byte[100];
       new Random(0x1234567L).nextBytes(plaintextBytes);
       byte[] iv = {
           (byte) 0x1a, (byte) 0xf3, (byte) 0x8c, (byte) 0x2d, (byte) 0xc2, (byte) 0xb9, (byte) 0x6f, (byte) 0xfd,
           (byte) 0xd8, (byte) 0x66, (byte) 0x94, (byte) 0x09, (byte) 0x23, (byte) 0x41, (byte) 0xbc, (byte) 0x04
       };
      
       EncryptParameters encryptParameters = EncryptParameters.createA128CbcParameters(plaintextBytes, iv);
      
       cryptographyAsyncClient.encrypt(encryptParameters)
           .contextWrite(Context.of("key1", "value1", "key2", "value2"))
           .subscribe(encryptResult ->
               System.out.printf("Received encrypted content of length: %d, with algorithm: %s.%n",
                   encryptResult.getCipherText().length, encryptResult.getAlgorithm().toString()));
       
      Parameters:
      encryptParameters - The parameters to use in the encryption operation.
      Returns:
      A Mono containing a EncryptResult whose cipher text contains the encrypted content.
      Throws:
      NullPointerException - If algorithm or plaintext are null.
      ResourceNotFoundException - If the key cannot be found for encryption.
      UnsupportedOperationException - If the encrypt operation is not supported or configured on the key.
    • decrypt

      public Mono<DecryptResult> decrypt(EncryptionAlgorithm algorithm, byte[] ciphertext)
      Decrypts a single block of encrypted data using the configured key and specified algorithm. Note that only a single block of data may be decrypted, the size of this block is dependent on the target key and the algorithm to be used. The decrypt operation is supported for both asymmetric and symmetric keys. This operation requires the keys/decrypt permission for non-local operations.

      The encryption algorithm indicates the type of algorithm to use for decrypting the specified encrypted content. Possible values for asymmetric keys include: RSA1_5, RSA_OAEP and RSA_OAEP_256. Possible values for symmetric keys include: A128CBC, A128CBCPAD, A128CBC-HS256, A128GCM, A192CBC, A192CBCPAD, A192CBC-HS384, A192GCM, A256CBC, A256CBPAD, A256CBC-HS512 and A256GCM.

      Code Samples

      Decrypts the encrypted content. Subscribes to the call asynchronously and prints out the decrypted content details when a response has been received.

       byte[] ciphertext = new byte[100];
       new Random(0x1234567L).nextBytes(ciphertext);
      
       cryptographyAsyncClient.decrypt(EncryptionAlgorithm.RSA_OAEP, ciphertext)
           .contextWrite(Context.of("key1", "value1", "key2", "value2"))
           .subscribe(decryptResult ->
               System.out.printf("Received decrypted content of length: %d%n", decryptResult.getPlainText().length));
       
      Parameters:
      algorithm - The algorithm to be used for decryption.
      ciphertext - The content to be decrypted. Microsoft recommends you not use CBC without first ensuring the integrity of the ciphertext using an HMAC, for example. See https://docs.microsoft.com/dotnet/standard/security/vulnerabilities-cbc-mode for more information.
      Returns:
      A Mono containing the decrypted blob.
      Throws:
      NullPointerException - If algorithm or ciphertext are null.
      ResourceNotFoundException - If the key cannot be found for decryption.
      UnsupportedOperationException - If the decrypt operation is not supported or configured on the key.
    • decrypt

      public Mono<DecryptResult> decrypt(DecryptParameters decryptParameters)
      Decrypts a single block of encrypted data using the configured key and specified algorithm. Note that only a single block of data may be decrypted, the size of this block is dependent on the target key and the algorithm to be used. The decrypt operation is supported for both asymmetric and symmetric keys. This operation requires the keys/decrypt permission for non-local operations.

      The encryption algorithm indicates the type of algorithm to use for decrypting the specified encrypted content. Possible values for asymmetric keys include: RSA1_5, RSA_OAEP and RSA_OAEP_256. Possible values for symmetric keys include: A128CBC, A128CBCPAD, A128CBC-HS256, A128GCM, A192CBC, A192CBCPAD, A192CBC-HS384, A192GCM, A256CBC, A256CBPAD, A256CBC-HS512 and A256GCM.

      Code Samples

      Decrypts the encrypted content. Subscribes to the call asynchronously and prints out the decrypted content details when a response has been received.

       byte[] ciphertextBytes = new byte[100];
       new Random(0x1234567L).nextBytes(ciphertextBytes);
       byte[] iv = {
           (byte) 0x1a, (byte) 0xf3, (byte) 0x8c, (byte) 0x2d, (byte) 0xc2, (byte) 0xb9, (byte) 0x6f, (byte) 0xfd,
           (byte) 0xd8, (byte) 0x66, (byte) 0x94, (byte) 0x09, (byte) 0x23, (byte) 0x41, (byte) 0xbc, (byte) 0x04
       };
      
       DecryptParameters decryptParameters = DecryptParameters.createA128CbcParameters(ciphertextBytes, iv);
      
       cryptographyAsyncClient.decrypt(decryptParameters)
           .contextWrite(Context.of("key1", "value1", "key2", "value2"))
           .subscribe(decryptResult ->
               System.out.printf("Received decrypted content of length: %d.%n", decryptResult.getPlainText().length));
       
      Parameters:
      decryptParameters - The parameters to use in the decryption operation. Microsoft recommends you not use CBC without first ensuring the integrity of the ciphertext using an HMAC, for example. See https://docs.microsoft.com/dotnet/standard/security/vulnerabilities-cbc-mode for more information.
      Returns:
      A Mono containing the decrypted blob.
      Throws:
      NullPointerException - If algorithm or ciphertext are null.
      ResourceNotFoundException - If the key cannot be found for decryption.
      UnsupportedOperationException - If the decrypt operation is not supported or configured on the key.
    • sign

      public Mono<SignResult> sign(SignatureAlgorithm algorithm, byte[] digest)
      Creates a signature from a digest using the configured key. The sign operation supports both asymmetric and symmetric keys. This operation requires the keys/sign permission for non-local operations.

      The signature algorithm indicates the type of algorithm to use to create the signature from the digest. Possible values include: ES256, E384, ES512, ES246K, PS256, RS384, RS512, RS256, RS384 and RS512

      Code Samples

      Sings the digest. Subscribes to the call asynchronously and prints out the signature details when a response has been received.

       byte[] data = new byte[100];
       new Random(0x1234567L).nextBytes(data);
       MessageDigest md = MessageDigest.getInstance("SHA-256");
       md.update(data);
       byte[] digest = md.digest();
      
       cryptographyAsyncClient.sign(SignatureAlgorithm.ES256, digest)
           .contextWrite(Context.of("key1", "value1", "key2", "value2"))
           .subscribe(signResult ->
               System.out.printf("Received signature of length: %d, with algorithm: %s.%n",
                   signResult.getSignature().length, signResult.getAlgorithm()));
       
      Parameters:
      algorithm - The algorithm to use for signing.
      digest - The content from which signature is to be created.
      Returns:
      A Mono containing a SignResult whose signature contains the created signature.
      Throws:
      NullPointerException - If algorithm or digest is null.
      ResourceNotFoundException - If the key cannot be found for signing.
      UnsupportedOperationException - If the sign operation is not supported or configured on the key.
    • verify

      public Mono<VerifyResult> verify(SignatureAlgorithm algorithm, byte[] digest, byte[] signature)
      Verifies a signature using the configured key. The verify operation supports both symmetric keys and asymmetric keys. In case of asymmetric keys public portion of the key is used to verify the signature. This operation requires the keys/verify permission for non-local operations.

      The signature algorithm indicates the type of algorithm to use to verify the signature. Possible values include: ES256, E384, ES512, ES246K, PS256, RS384, RS512, RS256, RS384 and RS512

      Code Samples

      Verifies the signature against the specified digest. Subscribes to the call asynchronously and prints out the verification details when a response has been received.

       byte[] myData = new byte[100];
       new Random(0x1234567L).nextBytes(myData);
       MessageDigest messageDigest = MessageDigest.getInstance("SHA-256");
       messageDigest.update(myData);
       byte[] myDigest = messageDigest.digest();
      
       // A signature can be obtained from the SignResult returned by the CryptographyAsyncClient.sign() operation.
       cryptographyAsyncClient.verify(SignatureAlgorithm.ES256, myDigest, signature)
           .contextWrite(Context.of("key1", "value1", "key2", "value2"))
           .subscribe(verifyResult ->
               System.out.printf("Verification status: %s.%n", verifyResult.isValid()));
       
      Parameters:
      algorithm - The algorithm to use for signing.
      digest - The content from which signature was created.
      signature - The signature to be verified.
      Returns:
      A Mono containing a VerifyResult indicating the signature verification result.
      Throws:
      NullPointerException - If algorithm, digest or signature is null.
      ResourceNotFoundException - If the key cannot be found for verifying.
      UnsupportedOperationException - If the verify operation is not supported or configured on the key.
    • wrapKey

      public Mono<WrapResult> wrapKey(KeyWrapAlgorithm algorithm, byte[] key)
      Wraps a symmetric key using the configured key. The wrap operation supports wrapping a symmetric key with both symmetric and asymmetric keys. This operation requires the keys/wrapKey permission for non-local operations.

      The wrap algorithm indicates the type of algorithm to use for wrapping the specified key content. Possible values include: RSA1_5, RSA_OAEP and RSA_OAEP_256. Possible values for symmetric keys include: A128KW, A192KW and A256KW.

      Code Samples

      Wraps the key content. Subscribes to the call asynchronously and prints out the wrapped key details when a response has been received.

       byte[] key = new byte[100];
       new Random(0x1234567L).nextBytes(key);
      
       cryptographyAsyncClient.wrapKey(KeyWrapAlgorithm.RSA_OAEP, key)
           .contextWrite(Context.of("key1", "value1", "key2", "value2"))
           .subscribe(wrapResult ->
               System.out.printf("Received encrypted key of length: %d, with algorithm: %s.%n",
                   wrapResult.getEncryptedKey().length, wrapResult.getAlgorithm().toString()));
       
      Parameters:
      algorithm - The encryption algorithm to use for wrapping the key.
      key - The key content to be wrapped.
      Returns:
      A Mono containing a WrapResult whose encrypted key contains the wrapped key result.
      Throws:
      NullPointerException - If algorithm or key are null.
      ResourceNotFoundException - If the key cannot be found for wrap operation.
      UnsupportedOperationException - If the wrap operation is not supported or configured on the key.
    • unwrapKey

      public Mono<UnwrapResult> unwrapKey(KeyWrapAlgorithm algorithm, byte[] encryptedKey)
      Unwraps a symmetric key using the configured key that was initially used for wrapping that key. This operation is the reverse of the wrap operation. The unwrap operation supports asymmetric and symmetric keys to unwrap. This operation requires the keys/unwrapKey permission for non-local operations.

      The wrap algorithm indicates the type of algorithm to use for unwrapping the specified encrypted key content. Possible values for asymmetric keys include: RSA1_5, RSA_OAEP and RSA_OAEP_256. Possible values for symmetric keys include: A128KW, A192KW and A256KW.

      Code Samples

      Unwraps the key content. Subscribes to the call asynchronously and prints out the unwrapped key details when a response has been received.

       byte[] keyToWrap = new byte[100];
       new Random(0x1234567L).nextBytes(key);
      
       cryptographyAsyncClient.wrapKey(KeyWrapAlgorithm.RSA_OAEP, keyToWrap)
           .contextWrite(Context.of("key1", "value1", "key2", "value2"))
           .subscribe(wrapResult ->
               cryptographyAsyncClient.unwrapKey(KeyWrapAlgorithm.RSA_OAEP, wrapResult.getEncryptedKey())
                   .subscribe(keyUnwrapResult ->
                       System.out.printf("Received key of length: %d.%n", keyUnwrapResult.getKey().length)));
       
      Parameters:
      algorithm - The encryption algorithm to use for wrapping the key.
      encryptedKey - The encrypted key content to unwrap.
      Returns:
      A Mono containing an UnwrapResult whose decrypted key contains the unwrapped key result.
      Throws:
      NullPointerException - If algorithm or encryptedKey are null.
      ResourceNotFoundException - If the key cannot be found for wrap operation.
      UnsupportedOperationException - If the unwrap operation is not supported or configured on the key.
    • signData

      public Mono<SignResult> signData(SignatureAlgorithm algorithm, byte[] data)
      Creates a signature from the raw data using the configured key. The sign data operation supports both asymmetric and symmetric keys. This operation requires the keys/sign permission for non-local operations.

      The signature algorithm indicates the type of algorithm to use to sign the digest. Possible values include: ES256, E384, ES512, ES246K, PS256, RS384, RS512, RS256, RS384 and RS512

      Code Samples

      Signs the raw data. Subscribes to the call asynchronously and prints out the signature details when a response has been received.

       byte[] data = new byte[100];
       new Random(0x1234567L).nextBytes(data);
      
       cryptographyAsyncClient.sign(SignatureAlgorithm.ES256, data)
           .contextWrite(Context.of("key1", "value1", "key2", "value2"))
           .subscribe(signResult ->
               System.out.printf("Received signature of length: %d, with algorithm: %s.%n",
                   signResult.getSignature().length, signResult.getAlgorithm()));
       
      Parameters:
      algorithm - The algorithm to use for signing.
      data - The content from which signature is to be created.
      Returns:
      A Mono containing a SignResult whose signature contains the created signature.
      Throws:
      NullPointerException - If algorithm or data is null.
      ResourceNotFoundException - If the key cannot be found for signing.
      UnsupportedOperationException - If the sign operation is not supported or configured on the key.
    • verifyData

      public Mono<VerifyResult> verifyData(SignatureAlgorithm algorithm, byte[] data, byte[] signature)
      Verifies a signature against the raw data using the configured key. The verify operation supports both symmetric keys and asymmetric keys. In case of asymmetric keys public portion of the key is used to verify the signature. This operation requires the keys/verify permission for non-local operations.

      The signature algorithm indicates the type of algorithm to use to verify the signature. Possible values include: ES256, E384, ES512, ES246K, PS256, RS384, RS512, RS256, RS384 and RS512

      Code Samples

      Verifies the signature against the raw data. Subscribes to the call asynchronously and prints out the verification details when a response has been received.

       byte[] myData = new byte[100];
       new Random(0x1234567L).nextBytes(myData);
      
       // A signature can be obtained from the SignResult returned by the CryptographyAsyncClient.sign() operation.
       cryptographyAsyncClient.verify(SignatureAlgorithm.ES256, myData, signature)
           .contextWrite(Context.of("key1", "value1", "key2", "value2"))
           .subscribe(verifyResult ->
               System.out.printf("Verification status: %s.%n", verifyResult.isValid()));
       
      Parameters:
      algorithm - The algorithm to use for signing.
      data - The raw content against which signature is to be verified.
      signature - The signature to be verified.
      Returns:
      A Mono containing a VerifyResult indicating the signature verification result.
      Throws:
      NullPointerException - If algorithm, data or signature is null.
      ResourceNotFoundException - If the key cannot be found for verifying.
      UnsupportedOperationException - If the verify operation is not supported or configured on the key.