Board Review: Azure.Security.KeyVault.Keys

[heaths]

Contacts and Timeline

• Responsible service team: Managed HSM
• Main contacts: @amitbapat @vickm @herveyw-msft @heaths
• Expected code complete date: 2021-02-09
• Expected release date: 2021-02-23

About the Service

• Link to documentation introducing/describing the service:
• Link to the service REST APIs: https://github.com/Azure/azure-rest-api-specs/blob/bac7543173839db476a0871cf6c2261f7a445790/specification/keyvault/data-plane/Microsoft.KeyVault/preview/7.2-preview/keys.json#L1572-L1583
• Link to GitHub issue for previous review sessions, if applicable: N/A

About the client library

• Name of the client library: Azure.Security.KeyVault.Keys
• Languages for this review: C#, Java

Artifacts required (per language)

Please read through “API Review” section here to understand how these artifacts are generated. It is critical that these artifacts are present and are in the right format. If not, the language architects cannot review them with the SDK Team’s API review tool.

.NET

• APIView Link: https://apiview.dev/Assemblies/Review/d2d05cf175c7478184662d580a300e68
  (was https://apiview.dev/Assemblies/Review/d74052731cb94759804beaa492b7a17a/8e114ef64afd4a6584ca4ec16e2ebc30?diffRevisionId=c941dc7b59ba45f483f8cad9a34e98bf&doc=False#Azure.Security.KeyVault.Keys.Cryptography.CryptographyClient) but more comments were recently left on the auto-review)
• Link to Champion Scenarios/Quickstart samples: I opened an issue to track updating our samples with these new methods. In the meantime, a use case would look like:

byte[] Encrypt(KeyVaultKey key, byte[] plaintext)
{
  EncryptResult result = await _cryptographyClient.EncryptAsync(EncryptOptions.A256GcmOptions(plaintext), _cts.Token);
  return result.Ciphertext;
}

Java

• APIView Link: https://apiview.dev/Assemblies/Review/b774f0eced8a435d81e270780c8a5b48?diffRevisionId=981f2f368f884550b64b9a1e8baf358d&doc=False#com.azure.security.keyvault.keys.cryptography.CryptographyClient
• Link to Champion Scenarios/Quickstart samples: There's an open issue to track updating our samples with these new methods. In the meantime, the current samples can be found here. Additionally, a use case would look like:

EncryptOptions encryptOptions = EncryptOptions.createAes128CbcOptions(myPlainText, iv);
EncryptResult encryptedResult = cryptographyClient.encrypt(encryptOptions, context);

System.out.printf("Received encrypted content of length %d with algorithm %s \n",
    encryptedResult.getCipherText().length, encryptedResult.getAlgorithm().toString());

Additional notes

Effectively, we use factory methods to help enforce certain options for certain algorithms. For example, AES-GCM support takes optional "AdditionalAuthenticatedData", while AES-CBC and AES-CBCPAD take an optional IV (we generate one if not provided; IV is required by the service but treated as an nonce in some cases). This design had been previously discussed with @KrzysztofCwalina and reviewed by the Microsoft Crypto Board.

[lilyjma]

scheduled for 1/14

[lilyjma]

Recording[MS INTERNAL ONLY]