Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[KeyVault] README improvements #7664

Merged
merged 8 commits into from
Mar 10, 2020
Merged

[KeyVault] README improvements #7664

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
157cb7d
[KeyVault] README improvements
sadasant Mar 5, 2020
3b29666
Update README.md
sadasant Mar 5, 2020
dc8f7d7
more README changes
sadasant Mar 5, 2020
9e4d8ea
main readme improvements
sadasant Mar 5, 2020
2e44031
root keyvault readme shortened
sadasant Mar 6, 2020
83fcd05
only relative paths
sadasant Mar 6, 2020
787383c
Merge remote-tracking branch 'Azure/master' into keyvault/readme-impr…
sadasant Mar 10, 2020
b0d1712
KeyVault to Key Vault
sadasant Mar 10, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 19 additions & 88 deletions sdk/keyvault/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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

Expand Down Expand Up @@ -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/)
Copy link
Member

@richardpark-msft richardpark-msft Mar 9, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we consider these "samples" grade (meaning consumers can read them and get started)? Might be worth just removing it.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, most of our tests are thought as samples. In fact, our samples are almost copies of our tests.


## Contributing

Expand Down
124 changes: 94 additions & 30 deletions sdk/keyvault/keyvault-certificates/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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 KeyVault certificate](#getting-a-keyvault-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).
Expand Down Expand Up @@ -301,7 +303,7 @@ async function main() {
main();
```

### Get a certificate
### Getting a KeyVault certificate
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: the product is "Key Vault", not "KeyVault".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lots of instances all over docs that should change.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good! I'll do these changes.


The simplest way to read certificates back from the vault is to get a
certificate by name. `getCertificate` will retrieve the most recent
Expand Down Expand Up @@ -339,32 +341,94 @@ 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 KeyVault service's Certificates
features were designed making use of it's Keys and Secrets capabilities.
Let's evaluate the composition of a KeyVault 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 KeyVault 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 KeyVault 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);
```

main();
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:

openssl pkcs12 -in myCertificate.p12 -out myCertificate.crt.pem -clcerts -nokeys
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be a code block using triple backticks. Doesn't need a language i.e. can just be preformatted text.


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 KeyVault 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 KeyVault 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

`listPropertiesOfCertificates` will list all certificates in the Key Vault.
Expand Down Expand Up @@ -582,21 +646,21 @@ main();

## Troubleshooting

### Enable logs

You can set the following environment variable to get the debug logs when using this library.
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`:

- 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

Expand Down
20 changes: 10 additions & 10 deletions sdk/keyvault/keyvault-certificates/samples/javascript/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
20 changes: 10 additions & 10 deletions sdk/keyvault/keyvault-certificates/samples/typescript/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,18 +78,18 @@ 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/typescript/src/backupAndRestore.ts
[contacts]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-certificates/samples/typescript/src/contacts.ts
[deleteandrecover]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-certificates/samples/typescript/src/deleteAndRecover.ts
[helloworld]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-certificates/samples/typescript/src/helloWorld.ts
[issuers]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-certificates/samples/typescript/src/issuers.ts
[listcertificates]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-certificates/samples/typescript/src/listCertificates.ts
[mergecertificate]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-certificates/samples/typescript/src/mergeCertificate.ts
[operations]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-certificates/samples/typescript/src/operations.ts
[purgeAllCertificates]: src/purgeAllCertificates.ts
[backupandrestore]: ./src/backupAndRestore.ts
[contacts]: ./src/contacts.ts
[deleteandrecover]: ./src/deleteAndRecover.ts
[helloworld]: ./src/helloWorld.ts
[issuers]: ./src/issuers.ts
[listcertificates]: ./src/listCertificates.ts
[mergecertificate]: ./src/mergeCertificate.ts
[operations]: ./src/operations.ts
[purgeAllCertificates]: ./src/purgeAllCertificates.ts
[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
[typescript]: https://www.typescriptlang.org/docs/home.html
Loading