From ab431f995249a5bb884b1a999a12242f56e82f9a Mon Sep 17 00:00:00 2001 From: Victor Colin Amador Date: Sun, 17 Jul 2022 23:33:11 -0700 Subject: [PATCH] Added a disclaimer about the use of CBC to cryptographic clients and encrypt/decrypt parameter models. Also added details to guide users to ensure they are providing cryptographically random IVs for encrypting data. --- .../cryptography/CryptographyAsyncClient.java | 8 +++-- .../keys/cryptography/CryptographyClient.java | 12 +++++-- .../models/DecryptParameters.java | 24 +++++++++---- .../models/EncryptParameters.java | 35 +++++++++++++++---- 4 files changed, 61 insertions(+), 18 deletions(-) diff --git a/sdk/keyvault/azure-security-keyvault-keys/src/main/java/com/azure/security/keyvault/keys/cryptography/CryptographyAsyncClient.java b/sdk/keyvault/azure-security-keyvault-keys/src/main/java/com/azure/security/keyvault/keys/cryptography/CryptographyAsyncClient.java index 526fcbf86ca3..291593ea0066 100644 --- a/sdk/keyvault/azure-security-keyvault-keys/src/main/java/com/azure/security/keyvault/keys/cryptography/CryptographyAsyncClient.java +++ b/sdk/keyvault/azure-security-keyvault-keys/src/main/java/com/azure/security/keyvault/keys/cryptography/CryptographyAsyncClient.java @@ -430,7 +430,9 @@ Mono encrypt(EncryptParameters encryptParameters, Context context * * * @param algorithm The algorithm to be used for decryption. - * @param ciphertext The content to be decrypted. + * @param 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. * * @return A {@link Mono} containing the decrypted blob. * @@ -487,7 +489,9 @@ public Mono decrypt(EncryptionAlgorithm algorithm, byte[] ciphert * * * - * @param decryptParameters The parameters to use in the decryption operation. + * @param 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. * * @return A {@link Mono} containing the decrypted blob. * diff --git a/sdk/keyvault/azure-security-keyvault-keys/src/main/java/com/azure/security/keyvault/keys/cryptography/CryptographyClient.java b/sdk/keyvault/azure-security-keyvault-keys/src/main/java/com/azure/security/keyvault/keys/cryptography/CryptographyClient.java index c6094868d616..7fb22e69e9ef 100644 --- a/sdk/keyvault/azure-security-keyvault-keys/src/main/java/com/azure/security/keyvault/keys/cryptography/CryptographyClient.java +++ b/sdk/keyvault/azure-security-keyvault-keys/src/main/java/com/azure/security/keyvault/keys/cryptography/CryptographyClient.java @@ -314,7 +314,9 @@ public EncryptResult encrypt(EncryptParameters encryptParameters, Context contex * * * @param algorithm The algorithm to be used for decryption. - * @param ciphertext The content to be decrypted. + * @param 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. * * @return The {@link DecryptResult} whose {@link DecryptResult#getPlainText() plain text} contains the decrypted * content. @@ -364,7 +366,9 @@ public DecryptResult decrypt(EncryptionAlgorithm algorithm, byte[] ciphertext) { * * * @param algorithm The algorithm to be used for decryption. - * @param ciphertext The content to be decrypted. + * @param 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. * @param context Additional context that is passed through the {@link HttpPipeline} during the service call. * * @return The {@link DecryptResult} whose {@link DecryptResult#getPlainText() plain text} contains the decrypted @@ -418,7 +422,9 @@ public DecryptResult decrypt(EncryptionAlgorithm algorithm, byte[] ciphertext, C * * * - * @param decryptParameters The parameters to use in the decryption operation. + * @param 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. * @param context Additional context that is passed through the {@link HttpPipeline} during the service call. * * @return The {@link DecryptResult} whose {@link DecryptResult#getPlainText() plain text} contains the decrypted diff --git a/sdk/keyvault/azure-security-keyvault-keys/src/main/java/com/azure/security/keyvault/keys/cryptography/models/DecryptParameters.java b/sdk/keyvault/azure-security-keyvault-keys/src/main/java/com/azure/security/keyvault/keys/cryptography/models/DecryptParameters.java index 1c39c138a8b9..c2843de03bcc 100644 --- a/sdk/keyvault/azure-security-keyvault-keys/src/main/java/com/azure/security/keyvault/keys/cryptography/models/DecryptParameters.java +++ b/sdk/keyvault/azure-security-keyvault-keys/src/main/java/com/azure/security/keyvault/keys/cryptography/models/DecryptParameters.java @@ -40,7 +40,9 @@ public final class DecryptParameters { * Factory method to create an instance of {@link DecryptParameters} with the given parameters for * {@link EncryptionAlgorithm#A128CBC}. * - * @param ciphertext The content to be decrypted. + * @param 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. * @param iv Initialization vector for the decryption operation. * * @return The {@link DecryptParameters}. @@ -53,7 +55,9 @@ public static DecryptParameters createA128CbcParameters(byte[] ciphertext, byte[ * Factory method to create an instance of {@link DecryptParameters} with the given parameters for * {@link EncryptionAlgorithm#A128CBCPAD}. * - * @param ciphertext The content to be decrypted. + * @param 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. * @param iv Initialization vector for the decryption operation. * * @return The {@link DecryptParameters}. @@ -97,7 +101,9 @@ public static DecryptParameters createA128GcmParameters(byte[] ciphertext, byte[ * Factory method to create an instance of {@link DecryptParameters} with the given parameters for * {@link EncryptionAlgorithm#A192CBC}. * - * @param ciphertext The content to be decrypted. + * @param 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. * @param iv Initialization vector for the decryption operation. * * @return The {@link DecryptParameters}. @@ -110,7 +116,9 @@ public static DecryptParameters createA192CbcParameters(byte[] ciphertext, byte[ * Factory method to create an instance of {@link DecryptParameters} with the given parameters for * {@link EncryptionAlgorithm#A192CBCPAD}. * - * @param ciphertext The content to be decrypted. + * @param 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. * @param iv Initialization vector for the decryption operation. * * @return The {@link DecryptParameters}. @@ -154,7 +162,9 @@ public static DecryptParameters createA192GcmParameters(byte[] ciphertext, byte[ * Factory method to create an instance of {@link DecryptParameters} with the given parameters for * {@link EncryptionAlgorithm#A256CBC}. * - * @param ciphertext The content to be decrypted. + * @param 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. * @param iv Initialization vector for the decryption operation. * * @return The {@link DecryptParameters}. @@ -167,7 +177,9 @@ public static DecryptParameters createA256CbcParameters(byte[] ciphertext, byte[ * Factory method to create an instance of {@link DecryptParameters} with the given parameters for * {@link EncryptionAlgorithm#A256CBCPAD}. * - * @param ciphertext The content to be decrypted. + * @param 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. * @param iv Initialization vector for the decryption operation. * * @return The {@link DecryptParameters}. diff --git a/sdk/keyvault/azure-security-keyvault-keys/src/main/java/com/azure/security/keyvault/keys/cryptography/models/EncryptParameters.java b/sdk/keyvault/azure-security-keyvault-keys/src/main/java/com/azure/security/keyvault/keys/cryptography/models/EncryptParameters.java index e894ba36512d..da09ed96720e 100644 --- a/sdk/keyvault/azure-security-keyvault-keys/src/main/java/com/azure/security/keyvault/keys/cryptography/models/EncryptParameters.java +++ b/sdk/keyvault/azure-security-keyvault-keys/src/main/java/com/azure/security/keyvault/keys/cryptography/models/EncryptParameters.java @@ -48,7 +48,10 @@ public static EncryptParameters createA128CbcParameters(byte[] plaintext) { * {@link EncryptionAlgorithm#A128CBC}. * * @param plaintext The content to be encrypted. - * @param iv Initialization vector for the encryption operation. + * @param iv Optional initialization vector for the encryption operation. If you pass your own IV, make sure you + * use a cryptographically random, non-repeating IV. If {@code null}, a cryptographically random IV will be + * generated by Key Vault for service-side operations. For client-side operations, + * {@link java.security.SecureRandom} will be used instead. * * @return The {@link EncryptParameters}. */ @@ -73,7 +76,10 @@ public static EncryptParameters createA128CbcPadParameters(byte[] plaintext) { * {@link EncryptionAlgorithm#A128CBCPAD}. * * @param plaintext The content to be encrypted. - * @param iv Initialization vector for the encryption operation. + * @param iv Optional initialization vector for the encryption operation. If you pass your own IV, make sure you + * use a cryptographically random, non-repeating IV. If {@code null}, a cryptographically random IV will be + * generated by Key Vault for service-side operations. For client-side operations, + * {@link java.security.SecureRandom} will be used instead. * * @return The {@link EncryptParameters}. */ @@ -123,7 +129,10 @@ public static EncryptParameters createA192CbcParameters(byte[] plaintext) { * {@link EncryptionAlgorithm#A192CBC}. * * @param plaintext The content to be encrypted. - * @param iv Initialization vector for the encryption operation. + * @param iv Optional initialization vector for the encryption operation. If you pass your own IV, make sure you + * use a cryptographically random, non-repeating IV. If {@code null}, a cryptographically random IV will be + * generated by Key Vault for service-side operations. For client-side operations, + * {@link java.security.SecureRandom} will be used instead. * * @return The {@link EncryptParameters}. */ @@ -148,7 +157,10 @@ public static EncryptParameters createA192CbcPadParameters(byte[] plaintext) { * {@link EncryptionAlgorithm#A192CBCPAD}. * * @param plaintext The content to be encrypted. - * @param iv Initialization vector for the encryption operation. + * @param iv Optional initialization vector for the encryption operation. If you pass your own IV, make sure you + * use a cryptographically random, non-repeating IV. If {@code null}, a cryptographically random IV will be + * generated by Key Vault for service-side operations. For client-side operations, + * {@link java.security.SecureRandom} will be used instead. * * @return The {@link EncryptParameters}. */ @@ -198,7 +210,10 @@ public static EncryptParameters createA256CbcParameters(byte[] plaintext) { * {@link EncryptionAlgorithm#A256CBC}. * * @param plaintext The content to be encrypted. - * @param iv Initialization vector for the encryption operation. + * @param iv Optional initialization vector for the encryption operation. If you pass your own IV, make sure you + * use a cryptographically random, non-repeating IV. If {@code null}, a cryptographically random IV will be + * generated by Key Vault for service-side operations. For client-side operations, + * {@link java.security.SecureRandom} will be used instead. * * @return The {@link EncryptParameters}. */ @@ -223,7 +238,10 @@ public static EncryptParameters createA256CbcPadParameters(byte[] plaintext) { * {@link EncryptionAlgorithm#A256CBCPAD}. * * @param plaintext The content to be encrypted. - * @param iv Initialization vector for the encryption operation. + * @param iv Optional initialization vector for the encryption operation. If you pass your own IV, make sure you + * use a cryptographically random, non-repeating IV. If {@code null}, a cryptographically random IV will be + * generated by Key Vault for service-side operations. For client-side operations, + * {@link java.security.SecureRandom} will be used instead. * * @return The {@link EncryptParameters}. */ @@ -297,7 +315,10 @@ public static EncryptParameters createRsaOaep256Parameters(byte[] plaintext) { * * @param algorithm The algorithm to be used for encryption. * @param plaintext The content to be encrypted. - * @param iv Initialization vector for the encryption operation. + * @param iv Optional initialization vector for the encryption operation. If you pass your own IV, make sure you + * use a cryptographically random, non-repeating IV. If {@code null}, a cryptographically random IV will be + * generated by Key Vault for service-side operations. For client-side operations, + * {@link java.security.SecureRandom} will be used instead. * @param additionalAuthenticatedData Additional data to authenticate when using authenticated crypto algorithms. */ EncryptParameters(EncryptionAlgorithm algorithm, byte[] plaintext, byte[] iv, byte[] additionalAuthenticatedData) {