[KeyVault] README improvements (#7664)

Here's an attempt to improve our READMEs. I'm taking feedback from the docs team and I'm also mentioning information relevant to #7647.
Azure · Mar 10, 2020 · 2afdad1 · 2afdad1
1 parent 00c61a0
commit 2afdad1
Show file tree

Hide file tree

Showing 10 changed files with 186 additions and 192 deletions.
diff --git a/sdk/keyvault/README.md b/sdk/keyvault/README.md
@@ -4,9 +4,9 @@ Azure Key Vault is a Microsoft-managed service providing cloud keys, secrets, an
 
 This project provides client libraries in JavaScript that makes it easy to consume Microsoft Azure Key Vault service.
 
-- [Source Code - Keys](https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-keys)
-- [Source Code - Secrets](https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-secrets)
-- [Source Code - Certificates](https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-certificates)
+- [Source Code - Keys](./keyvault-keys)
+- [Source Code - Secrets](./keyvault-secrets)
+- [Source Code - Certificates](./keyvault-certificates)
 - [Product documentation](https://docs.microsoft.com/en-us/azure/key-vault)
 - @azure/keyvault-keys [Package (npm)](https://www.npmjs.com/package/@azure/keyvault-keys)
 - @azure/keyvault-secrets [Package (npm)](https://www.npmjs.com/package/@azure/keyvault-secrets)
@@ -20,37 +20,23 @@ This project provides client libraries in JavaScript that makes it easy to consu
 
 - Key Vault Keys
   - Create keys using elliptic curve or RSA encryption, optionally backed by Hardware Security Modules (HSM).
-  - Import keys.
-  - Delete keys.
-  - Update keys.
-  - Get one or more keys.
-  - Get one or more deleted keys.
-  - Recover a deleted key.
-  - Restore a backed up key.
-  - Get the versions of a key.
-  - As well as obtaining the attributes of a key.
-  - Encrypting
-  - Decrypting
-  - Signing
-  - Verifying
-  - Wrapping keys
-  - Unwrapping keys
+  - Import, delete and update keys.
+  - Get one or more keys and deleted keys.
+  - Recover a deleted key and restore a backed up key.
+  - Get the versions and the attributes of a key.
+  - Encrypting, decrypting, signing, verifying, wrapping and unwrapping data with keys.
 - Key Vault Secrets
   - Get, set and delete a secret.
   - Update a secret and it's attributes.
   - Backup and restore a secret.
   - Get, purge or recover a deleted secret.
-  - Get all the versions of a secret.
-  - Get all secrets.
-  - Get all deleted secrets.
+  - Get all the versions of a secret, or secrets, or deleted secrets.
 - Key Vault Certificates
   - Get, set and delete a certificate.
   - Update a certificate, its attributes, issuer, policy, operation and contacts.
   - Backup and restore a certificate.
   - Get, purge or recover a deleted certificate.
-  - Get all the versions of a certificate.
-  - Get all certificates.
-  - Get all deleted certificates.
+  - Get all the versions of a certificate, or certificates, or deleted certificates.
 
 ### Compatibility
 
@@ -99,70 +85,15 @@ const KeyVaultSecrets = require("@azure/keyvault-secrets");
 
 ## Code Samples
 
-```typescript
-import { SecretClient } from "@azure/keyvault-secrets";
-import { DefaultAzureCredential } from "@azure/identity";
-
-async function main(): Promise<void> {
-  // DefaultAzureCredential 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 DefaultAzureCredential();
-
-  const vaultName = process.env["KEYVAULT_NAME"] || "<keyvault-name>";
-  const url = `https://${vaultName}.vault.azure.net`;
-
-  const client = new SecretClient(url, credential);
-
-  // Create a secret
-  const secretName = "MySecretName";
-  const result = await client.setSecret(secretName, "MySecretValue");
-  console.log("result: ", result);
-
-  // Read the secret we created
-  const secret = await client.getSecret(secretName);
-  console.log("secret: ", secret);
-
-  // Update the secret with different attributes
-  const updatedSecret = await client.updateSecretProperties(
-    secretName,
-    result.properties.version!,
-    {
-      enabled: false
-    }
-  );
-  console.log("updated secret: ", updatedSecret);
-
-  // Delete the secret
-  // If we don't want to purge the secret later, we don't need to wait until this finishes
-  await client.beginDeleteSecret(secretName);
-}
-
-main().catch((err) => {
-  console.log("error code: ", err.code);
-  console.log("error message: ", err.message);
-  console.log("error stack: ", err.stack);
-});
-```
-
-## Troubleshooting
-
-Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the `AZURE_LOG_LEVEL` environment variable to `info`. Alternatively, logging can be enabled at runtime by calling `setLogLevel` in the `@azure/logger`:
-
-```javascript
-import { setLogLevel } from "@azure/logger";
-
-setLogLevel("info");
-```
-
-## Next steps
-
-More samples
-
-- [Key Vault Keys Examples](https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-keys/samples)
-- [Key Vault Secrets Examples](https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-secrets/samples)
-- [Key Vault Certificates Examples](https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-certificates/samples)
+- [KeyVault Keys Samples (JavaScript)](./keyvault-keys/samples/javascript)
+- [KeyVault Keys Samples (TypeScript)](./keyvault-keys/samples/typescript)
+- [KeyVault Keys Test Cases](./keyvault-keys/test/)
+- [KeyVault Secrets Samples (JavaScript)](./keyvault-secrets/samples/javascript)
+- [KeyVault Secrets Samples (TypeScript)](./keyvault-secrets/samples/typescript)
+- [KeyVault Secrets Test Cases](./keyvault-secrets/test/)
+- [KeyVault Certificates Samples (JavaScript)](./keyvault-certificates/samples/javascript)
+- [KeyVault Certificates Samples (TypeScript)](./keyvault-certificates/samples/typescript)
+- [KeyVault Certificates Test Cases](./keyvault-certificates/test/)
 
 ## Contributing
 

diff --git a/sdk/keyvault/keyvault-certificates/README.md b/sdk/keyvault/keyvault-certificates/README.md
@@ -16,7 +16,7 @@ Use the client library for Azure Key Vault Certificates in your Node.js applicat
 - Get all certificates.
 - Get all deleted certificates.
 
-[Source code](https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-certificates) | [Package (npm)](https://www.npmjs.com/package/@azure/keyvault-certificates) | [API Reference Documentation](https://docs.microsoft.com/javascript/api/@azure/keyvault-certificates) | [Product documentation](https://azure.microsoft.com/en-us/services/key-vault/) | [Samples](https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-certificates/samples)
+[Source code](https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-certificates) | [Package (npm)](https://www.npmjs.com/package/@azure/keyvault-certificates) | [API Reference Documentation](https://docs.microsoft.com/javascript/api/@azure/keyvault-certificates) | [Product documentation](https://azure.microsoft.com/en-us/services/key-vault/) | [Samples](./samples)
 
 ## Getting started
 
@@ -149,9 +149,11 @@ The following sections provide code snippets that cover some of the common
 tasks using Azure Key Vault Certificates. The scenarios that are covered here consist of:
 
 - [Creating and setting a certificate](#creating-and-setting-a-certificate).
-- [Getting a certificate](#get-a-certificate).
-- [Getting the versions of a certificate](#list-all-versions-of-a-certificate).
-- [Listing all the available certificates](#list-all-certificates).
+- [Getting a Key Vault certificate](#getting-a-key-vault-certificate).
+- [Getting the full information of a certificate](#getting-the-full-information-of-a-certificate).
+- [Certificates in PEM format](#certificates-in-pem-format).
+- [List all versions of a certificate](#list-all-versions-of-a-certificate).
+- [List all certificates](#list-all-certificates).
 - [Updating a certificate](#updating-a-certificate).
 - [Deleting a certificate](#deleting-a-certificate).
 - [Iterating lists of certificates](#iterating-lists-of-certificates).
@@ -301,7 +303,7 @@ async function main() {
 main();
 ```
 
-### Get a certificate
+### Getting a Key Vault certificate
 
 The simplest way to read certificates back from the vault is to get a
 certificate by name. `getCertificate` will retrieve the most recent
@@ -339,31 +341,97 @@ async function main() {
 main();
 ```
 
-### List all versions of a certificate
+### Getting the full information of a certificate
 
-`listPropertiesOfCertificateVersions` will list versions of the given certificate.
+Azure's KeyVault's design makes sharp distinctions between Keys,
+Secrets and Certificates. The Key Vault service's Certificates
+features were designed making use of it's Keys and Secrets capabilities.
+Let's evaluate the composition of a Key Vault Certificate:
 
-```javascript
-const { DefaultAzureCredential } = require("@azure/identity");
-const { CertificateClient } = require("@azure/keyvault-certificates");
+> When a Key Vault certificate is created, an addressable key
+> and secret are also created with the same name. The Key Vault
+> key allows key operations and the Key Vault secret allows retrieval
+> of the certificate value as a secret. A Key Vault certificate
+> also contains public x509 certificate metadata.  
+> _Source: [Composition of a Certificate][Composition-of-a-Certificate]._
 
-const credential = new DefaultAzureCredential();
+Knowing that the private key is stored in a Key Vault Secret,
+with the public certificate included, we can retrieve it
+by using the [KeyVault Secrets client][KeyVault-Secrets-client].
 
-const vaultName = "<YOUR KEYVAULT NAME>";
-const url = `https://${vaultName}.vault.azure.net`;
+```ts
+// Using the same credential object we used before,
+// and the same keyVaultUrl,
+// let's create a SecretClient
+const secretClient = new SecretClient(keyVaultUrl, credential);
 
-const client = new CertificateClient(url, credential);
+// Assuming you've already created a Key Vault certificate,
+// and that certificateName contains the name of your certificate
+const certificateSecret = await secretClient.getSecret(certificateName);
 
-const certificateName = "MyCertificateName";
+// Here we can find both the private key and the public certificate, in PKCS 12 format:
+const PKCS12Certificate = certificateSecret.value!;
 
-async function main() {
-  for await (let certificateProperties of client.listPropertiesOfCertificateVersions(certificateName)) {
-    console.log("version: ", certificateProperties.version);
-  }
-}
+// You can write this into a file:
+fs.writeFileSync("myCertificate.p12", PKCS12Certificate);
+```
+
+Note that, by default, the content type of the certificates
+is [PKCS 12][PKCS_12]. By specifying the content type
+of your certificate, you'll be able to retrieve it in PEM format.
+Before showing how to create PEM certificates,
+let's first explore how to retrieve a PEM secret key
+from a PKCS 12 certificate first.
+
+Using `openssl`, you can retrieve the public certificate in
+PEM format by using the following command:
 
-main();
 ```
+openssl pkcs12 -in myCertificate.p12 -out myCertificate.crt.pem -clcerts -nokeys
+```
+
+You can also use `openssl` to retrieve the private key, as follows:
+
+```
+openssl pkcs12 -in myCertificate.p12 -out myCertificate.key.pem -nocerts -nodes
+```
+
+Note that in both cases, openssl will ask you for the
+password used to create the certificate. The sample code we've used
+so far hasn't specified a password, so you can append ` -passin 'pass:' `
+to the end of each command.
+
+### Certificates in PEM format
+
+If you want to work with certificates in PEM format,
+you can tell Azure's Key Vault service to create and manage your
+certificates in PEM format by providing the `contentType` property
+at the moment of creating the certificates.
+
+The following example shows how to create and retrieve
+the public and the private parts of a PEM formatted certificate
+using the Key Vault clients for Certificates and Secrets:
+
+```ts
+// Creating the certificate
+const certificateName = "MyCertificate";
+const createPoller = await client.beginCreateCertificate(certificateName, {
+  issuerName: "Self",
+  subject: "cn=MyCert",
+  contentType: "application/x-pem-file" // Here you specify you want to work with PEM certificates.
+});
+const keyVaultCertificate = await createPoller.pollUntilDone();
+
+// Getting the PEM formatted private key and public certificate:
+const certificateSecret = await secretClient.getSecret(certificateName);
+const PEMPair = certificateSecret.value!;
+
+console.log(PEMPair);
+```
+
+Keep in mind that your public certificate will
+be in the same blob of content as your private key.
+You can use the PEM headers to extract them accordingly.
 
 ### List all certificates
 
@@ -488,7 +556,7 @@ async function main() {
   // const recoverPoller = await client.beginRecoverDeletedCertificate(certificateName);
   // await recoverPoller.pollUntilDone();
 
-  // If a certificate is done and the KeyVault has soft-delete enabled, the certificate can be purged with:
+  // If a certificate is done and the Key Vault has soft-delete enabled, the certificate can be purged with:
   await client.purgeDeletedCertificate(certificateName);
 }
 
@@ -582,21 +650,21 @@ main();
 
 ## Troubleshooting
 
-### Enable logs
+Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the `AZURE_LOG_LEVEL` environment variable to `info`. Alternatively, logging can be enabled at runtime by calling `setLogLevel` in the `@azure/logger`:
 
-You can set the following environment variable to get the debug logs when using this library.
-
-- Getting debug logs from the Key Vault Certificates SDK
+```javascript
+import { setLogLevel } from "@azure/logger";
 
-```bash
-export DEBUG=azure*
+setLogLevel("info");
 ```
 
 ## Next steps
 
-Please take a look at the
-[samples](https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-certificates/samples)
-directory for detailed examples on how to use this library.
+You can find more code samples through the following links:
+
+- [KeyVault Certificates Samples (JavaScript)](./samples/javascript)
+- [KeyVault Certificates Samples (TypeScript)](./samples/typescript)
+- [KeyVault Certificates Test Cases](./test/)
 
 ## Testing
 

diff --git a/sdk/keyvault/keyvault-certificates/samples/javascript/README.md b/sdk/keyvault/keyvault-certificates/samples/javascript/README.md
@@ -22,7 +22,7 @@ These sample programs show how to use the JavaScript client libraries for Azure
 | [listCertificates.js][listcertificates]         | lists previously created certificates in a single chunk and by page, then changes one of them and lists all the versions of that certificate, then deletes them and lists the deleted certificates.    |
 | [mergeCertificate.js][mergecertificate]         | creates a certificate with an Unknown issuer, then signs this certificate using a fake certificate authority and the mergeCertificate API method                                                       |
 | [operations.js][operations]                     | creates, updates and deletes a certificate's operation                                                                                                                                                 |
-| [purgeAllCertificates.js][purgeAllCertificates] | purges all the certificates of a KeyVault (useful for repeated tests)                                                                                                                                  |
+| [purgeAllCertificates.js][purgeAllCertificates] | purges all the certificates of a Key Vault (useful for repeated tests)                                                                                                                                  |
 
 ## Prerequisites
 
@@ -66,17 +66,17 @@ npx cross-env KEYVAULT_NAME="<key vault name>" AZURE_TENANT_ID="<AAD tenant id>"
 
 Take a look at our [API Documentation][apiref] for more information about the APIs that are available in the clients.
 
-[backupandrestore]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-certificates/samples/javascript/backupAndRestore.js
-[contacts]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-certificates/samples/javascript/contacts.js
-[deleteandrecover]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-certificates/samples/javascript/deleteAndRecover.js
-[helloworld]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-certificates/samples/javascript/helloWorld.js
-[issuers]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-certificates/samples/javascript/issuers.js
-[listcertificates]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-certificates/samples/javascript/listCertificates.js
-[mergecertificate]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-certificates/samples/javascript/mergeCertificate.js
-[operations]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-certificates/samples/javascript/operations.js
-[purgeAllCertificates]: purgeAllCertificates.js
+[backupandrestore]: ./backupAndRestore.js
+[contacts]: ./contacts.js
+[deleteandrecover]: ./deleteAndRecover.js
+[helloworld]: ./helloWorld.js
+[issuers]: ./issuers.js
+[listcertificates]: ./listCertificates.js
+[mergecertificate]: ./mergeCertificate.js
+[operations]: ./operations.js
+[purgeAllCertificates]: ./purgeAllCertificates.js
 [apiref]: https://docs.microsoft.com/javascript/api/@azure/keyvault-certificates
 [azkeyvault]: https://docs.microsoft.com/azure/key-vault/quick-create-portal
 [kvsoftdelete]: https://docs.microsoft.com/azure/key-vault/key-vault-soft-delete-cli
 [freesub]: https://azure.microsoft.com/free/
-[package]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-certificates/README.md
+[package]: ../README.md