[Cryptography] Add README for CryptographyClient and samples to API docs

sdk/keyvault/keyvault-keys/README.md

@@ -207,6 +207,113 @@ const updatedKey = await client.updateKey(keyName, result.version, { enabled: fa
 await client.deleteKey(keyName);
 ```
 
+## Cryptography
+
+This library also offers a set of cryptographic utilities available through `CryptographyClient`. Similar to the `KeysClient`, `CryptographyClient` will connect to Azure Key Vault with the provided set of credentials. Once connected, `CryptographyClient` can encrypt, decrypt, sign, verify, wrap keys, and unwrap keys.
+
+### Authenticate the client
+
+```typescript
+import { EnvironmentCredential } from "@azure/identity";
+import { KeysClient, CryptographyClient } from "@azure/keyvault-keys";
+```
+
+Once these are imported, we can next connect to the key vault service. To do this, we'll need to copy some settings from the key vault we are connecting to into our environment variables. Once they are in our environment, we can access them with the following code:
+
+```typescript
+// EnvironmentCredential expects the following three environment variables:
+// * AZURE_TENANT_ID: The tenant ID in Azure Active Directory
+// * AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
+// * AZURE_CLIENT_SECRET: The client secret for the registered application
+const credential = new EnvironmentCredential();
+
+// Build the URL to reach your key vault
+const vaultName = "<YOUR KEYVAULT NAME>";
+const url = `https://${vaultName}.vault.azure.net`;
+
+// Connect to the key vault service
+const keysClient = new KeysClient(url, credential);
+
+// Create or retrieve a key from the keyvault
+let myKey = await client.createKey("MyKey", "RSA");
+
+// Lastly, create our cryptography client and connect to the service
+// This example uses the URL that is part of the key we created (called key ID or kid)
+const cryptographyClient = new CryptographyClient(url, myKey.keyMaterial!.kid!, credential);
+```
+
+### Encrypt
+`encrypt` will encrypt a message. The following algorithms are currently supported: "RSA-OAEP", "RSA-OAEP-256", and "RSA1_5".
+
+```javascript
+const encrypt = await cryptographyClient.encrypt("RSA1_5", Buffer.from("My Message"));
+console.log("encrypt result: ", encrypt);
+```
+
+### Decrypt
+`decrypt` will decrypt an encrypted message. The following algorithms are currently supported: "RSA-OAEP", "RSA-OAEP-256", and "RSA1_5".
+
+```javascript
+const decrypt = await cryptographyClient.decrypt("RSA1_5", encrypt.result);
+console.log("decrypt: ", decrypt.toString());
+```
+
+### Sign
+`sign` will cryptographically sign the digest (hash) of a message with a signature. The following algorithms are currently supported: "PS256", "PS384", "PS512", "RS256", "RS384", "RS512", "ES256","ES256K", "ES384", and "ES512".
+
+```javascript
+const signatureValue = "MySignature";
+let hash = crypto.createHash("sha256");
+
+hash.update(signatureValue);
+let digest = hash.digest();
+console.log("digest: ", digest);
+
+const signature = await cryptoClient.sign("RS256", digest);
+console.log("sign result: ", signature);
+```
+
+### Sign Data
+`signData` will cryptographically sign a message with a signature. The following algorithms are currently supported: "PS256", "PS384", "PS512", "RS256", "RS384", "RS512", "ES256","ES256K", "ES384", and "ES512".
+
+```javascript
+const signature = await cryptoClient.signData("RS256", Buffer.from("My Message"));
+console.log("sign result: ", signature);
+```
+
+### Verify
+`verify` will cryptographically verify that the signed digest was signed with the given signature. The following algorithms are currently supported: "PS256", "PS384", "PS512", "RS256", "RS384", "RS512", "ES256","ES256K", "ES384", and "ES512".
+
+```javascript
+const verifyResult = await cryptoClient.verify("RS256", digest, signature.result);
+console.log("verify result: ", verifyResult);
+```
+
+### Verify Data
+`verifyData` will cryptographically verify that the signed message was signed with the given signature. The following algorithms are currently supported: "PS256", "PS384", "PS512", "RS256", "RS384", "RS512", "ES256","ES256K", "ES384", and "ES512".
+
+```javascript
+const verifyResult = await cryptoClient.verifyData("RS256", buffer, signature.result);
+console.log("verify result: ", verifyResult);
+```
+
+### Wrap Key
+`wrapKey` will wrap a key with an encryption layer. The following algorithms are currently supported: "RSA-OAEP", "RSA-OAEP-256", and "RSA1_5".
+
+```javascript
+const wrapped = await cryptoClient.wrapKey("RSA-OAEP", keyToWrap);
+console.log("wrap result:", wrapped);
+```
+
+### Unwrap Key
+`unwrapKey` will unwrap a wrapped key. The following algorithms are currently supported: "RSA-OAEP", "RSA-OAEP-256", and "RSA1_5".
+
+```javascript
+const unwrapped = await cryptoClient.unwrapKey("RSA-OAEP", wrapped.result);
+console.log("unwrap result: ", unwrapped);
+```
+
+
 ## Troubleshooting
 
 ### Enable logs

sdk/keyvault/keyvault-keys/samples/cryptography.ts

@@ -33,8 +33,8 @@ async function main(): Promise<void> {
   const signature = await cryptoClient.sign("RS256", digest);
   console.log("sign result: ", signature);
 
-  const verifyResult1 = await cryptoClient.verify("RS256", digest, signature.result);
-  console.log("remote verify result: ", verifyResult1);
+  const verifyResult = await cryptoClient.verify("RS256", digest, signature.result);
+  console.log("verify result: ", verifyResult);
 
   // Encrypt and decrypt
   const encrypt = await cryptoClient.encrypt("RSA1_5", Buffer.from("My Message"));
@@ -45,10 +45,10 @@ async function main(): Promise<void> {
 
   // Wrap and unwrap
   const wrapped = await cryptoClient.wrapKey("RSA-OAEP", Buffer.from("My Message"));
-  console.log("wrap result:", wrapped);
+  console.log("wrap result: ", wrapped);
 
   const unwrapped = await cryptoClient.unwrapKey("RSA-OAEP", wrapped.result);
-  console.log("unwrap result", unwrapped);
+  console.log("unwrap result: ", unwrapped);
 
   await client.deleteKey(keyName);
 }

sdk/keyvault/keyvault-keys/src/cryptographyClient.ts

@@ -1,5 +1,5 @@
 import { GetKeyOptions, RequestOptions } from "./keysModels";
-import { JsonWebKey, JsonWebKeyEncryptionAlgorithm, JsonWebKeySignatureAlgorithm } from "./core/models";
+import { JsonWebKey, JsonWebKeyEncryptionAlgorithm } from "./core/models";
 import {
   ServiceClientCredentials, TokenCredential, isNode, RequestPolicyFactory,
   isTokenCredential,
@@ -61,6 +61,12 @@ export class CryptographyClient {
 
   /**
    * Encrypts the given plaintext with the specified cryptography algorithm
+   *
+   * Example usage:
+   * ```ts
+   * let client = new CryptographyClient(url, key, credentials);
+   * let result = await client.encrypt("RSA1_5", Buffer.from("My Message"));
+   * ```
    * @param algorithm The algorithm to use
    * @param plaintext The text to encrypt
    * @param options Additional options
@@ -115,6 +121,12 @@ export class CryptographyClient {
 
   /**
    * Decrypts the given ciphertext with the specified cryptography algorithm
+   *
+   * Example usage:
+   * ```ts
+   * let client = new CryptographyClient(url, key, credentials);
+   * let result = await client.decrypt("RSA1_5", encryptedBuffer);
+   * ```
    * @param algorithm The algorithm to use
    * @param ciphertext The ciphertext to decrypt
    * @param options Additional options
@@ -130,6 +142,12 @@ export class CryptographyClient {
 
   /**
    * Wraps the given key using the specified cryptography algorithm
+   *
+   * Example usage:
+   * ```ts
+   * let client = new CryptographyClient(url, key, credentials);
+   * let result = await client.wrapKey("RSA1_5", keyToWrap);
+   * ```
    * @param algorithm The encryption algorithm to use to wrap the given key
    * @param key The key to wrap
    * @param options Additional options
@@ -184,6 +202,12 @@ export class CryptographyClient {
 
   /**
    * Unwraps the given wrapped key using the specified cryptography algorithm
+   *
+   * Example usage:
+   * ```ts
+   * let client = new CryptographyClient(url, key, credentials);
+   * let result = await client.unwrapKey("RSA1_5", keyToUnwrap);
+   * ```
    * @param algorithm The decryption algorithm to use to unwrap the key
    * @param encryptedKey The encrypted key to unwrap
    * @param options Additional options
@@ -199,12 +223,18 @@ export class CryptographyClient {
 
   /**
    * Cryptographically sign the digest of a message
+   *
+   * Example usage:
+   * ```ts
+   * let client = new CryptographyClient(url, key, credentials);
+   * let result = await client.sign("RS256", digest);
+   * ```
    * @param algorithm The signing algorithm to use
    * @param digest The digest of the data to sign
    * @param options Additional options
    */
   public async sign(
-    algorithm: JsonWebKeySignatureAlgorithm,
+    algorithm: KeySignatureAlgorithm,
     digest: Uint8Array,
     options?: RequestOptions
   ): Promise<SignResult> {
@@ -214,6 +244,12 @@ export class CryptographyClient {
 
   /**
    * Verify the signed message digest
+   *
+   * Example usage:
+   * ```ts
+   * let client = new CryptographyClient(url, key, credentials);
+   * let result = await client.verify("RS256", signedDigest, signature);
+   * ```
    * @param algorithm The signing algorithm to use to verify with
    * @param digest The digest to verify
    * @param signature The signature to verify the digest against
@@ -231,6 +267,12 @@ export class CryptographyClient {
 
   /**
    * Cryptographically sign a block of data
+   *
+   * Example usage:
+   * ```ts
+   * let client = new CryptographyClient(url, key, credentials);
+   * let result = await client.signData("RS256", message);
+   * ```
    * @param algorithm The signing algorithm to use
    * @param data The data to sign
    * @param options Additional options
@@ -269,13 +311,19 @@ export class CryptographyClient {
 
   /**
    * Verify the signed block of data
+   *
+   * Example usage:
+   * ```ts
+   * let client = new CryptographyClient(url, key, credentials);
+   * let result = await client.verifyData("RS256", signedMessage, signature);
+   * ```
    * @param algorithm The algorithm to use to verify with
    * @param data The signed block of data to verify
    * @param signature The signature to verify the block against
    * @param options Additional options
    */
   public async verifyData(
-    algorithm: JsonWebKeySignatureAlgorithm,
+    algorithm: KeySignatureAlgorithm,
     data: Uint8Array,
     signature: Uint8Array,
     options?: RequestOptions
@@ -501,6 +549,19 @@ export class CryptographyClient {
 
   /**
    * Constructs a new instance of the Cryptography client for the given key
+   *
+   * Example usage:
+   * ```ts
+   * import { CryptographyClient } from "@azure/keyvault-keys";
+   * import { EnvironmentCredential } from "@azure/identity";
+   *
+   * let url = `https://<MY KEYVAULT HERE>.vault.azure.net`;
+   * let credentials = new EnvironmentCredential();
+   *
+   * let client = new CryptographyClient(url, keyUrl, credentials);
+   * // or
+   * let client = new CryptographyClient(url, jsonWebKey, credentials);
+   * ```
    * @param url The url of the key vault service
    * @param key The key to use during cryptography tasks
    * @param credential The login credentials of the service

sdk/keyvault/keyvault-keys/src/index.ts

@@ -31,7 +31,6 @@ import {
   JsonWebKeyEncryptionAlgorithm,
   JsonWebKeyOperation,
   JsonWebKeyCurveName,
-  JsonWebKeySignatureAlgorithm,
   KeyItem,
   DeletionRecoveryLevel,
   KeyVaultClientGetKeysOptionalParams
@@ -92,7 +91,6 @@ export {
   JsonWebKeyCurveName,
   JsonWebKeyEncryptionAlgorithm,
   JsonWebKeyOperation,
-  JsonWebKeySignatureAlgorithm,
   JsonWebKeyType,
   Key,
   KeyAttributes,