From b344f29f5c2ace15b2e7b48b43d5efd20fdab173 Mon Sep 17 00:00:00 2001
From: Gus Narea <gnarea@users.noreply.github.com>
Date: Wed, 5 Apr 2023 01:36:30 +0900
Subject: [PATCH] docs: Write README (#30)

---
 README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 47 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 7d1e166..84d6134 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,56 @@
 # WebCrypto-compatible client for Key Management Services like GCP KMS
 
-This library extends [`webcrypto-core`](https://www.npmjs.com/package/webcrypto-core) to abstract the communication with KMSs (e.g., [GCP KMS](https://cloud.google.com/security-key-management)), allowing you to use the same code to communicate with different KMSs.
+This library extends [`webcrypto-core`](https://www.npmjs.com/package/webcrypto-core) to abstract the communication with KMSs, allowing you to use the same code to communicate with different KMSs. We currently support [GCP KMS](https://cloud.google.com/security-key-management) and [AWS KMS](https://aws.amazon.com/kms/), and we welcome PRs to support additional KMSs.
 
-This is an alternative to the Key Management Interoperability Protocol (KMIP) and PKCS#11. TODO: Explain why.
+This is an alternative to:
 
-### Integration test suite
+- The [Key Management Interoperability Protocol (KMIP)](https://en.wikipedia.org/wiki/Key_Management_Interoperability_Protocol), if you don't want to run another server.
+- [PKCS#11](https://en.wikipedia.org/wiki/PKCS_11), if you prefer to use official cloud SDKs instead of C libraries. This configures authentication automatically, and makes it possible to use telemetry.
 
-The integration tests aren't currently run on CI, and can be run with `npm run test:integration:local`. Note that some environments variables must be set, and others are optional:
+## Usage
+
+The library is available on NPM as [`@relaycorp/webcrypto-kms`](https://www.npmjs.com/package/@relaycorp/webcrypto-kms), and you can install it as follows:
+
+```
+npm i @relaycorp/webcrypto-kms
+```
+
+### Initialising the private key store
+
+The configuration of the adapter is done via environment variables, so the actual initialisation of the store is done with a simple function call:
+
+```typescript
+import { initKmsProviderFromEnv, KmsRsaPssProvider } from '@relaycorp/webcrypto-kms';
+
+async function init(): Promise<KmsRsaPssProvider> {
+  return initKmsProviderFromEnv(process.env.KMS_ADAPTER);
+}
+```
+
+`initKmsProviderFromEnv()` can be called with `'AWS'` or `'GCP'`.
 
+The following environment variables must be defined depending on the adapter:
+
+- AWS adapter:
+  - `AWS_KMS_ENDPOINT` (optional).
+  - `AWS_KMS_REGION` (optional).
 - GCP adapter:
-  - [`GOOGLE_APPLICATION_CREDENTIALS`](https://cloud.google.com/docs/authentication/getting-started) (required), using a service account. All GCP resources will be created within the same project where the service account lives. The GCP service account should be allowed to manage KMS resources.
-  - `GCP_KMS_KEYRING`.
-  - `GCP_KMS_LOCATION` (e.g., `europe-west3`).
-  - `GCP_KMS_PROTECTION_LEVEL` (e.g., `SOFTWARE`).
+  - [`GOOGLE_APPLICATION_CREDENTIALS`](https://cloud.google.com/docs/authentication/getting-started) (optional when running on GCP infrastructure).
+  - `GCP_KMS_KEYRING` (required).
+  - `GCP_KMS_LOCATION` (required; e.g., `europe-west3`).
+  - `GCP_KMS_PROTECTION_LEVEL` (required; i.e., `SOFTWARE` or `HSM`).
+
+## Additional methods
+
+`KmsRsaPssProvider` exposes the following additional methods:
+
+- `destroyKey(privateKey)`: Destroys the specified private key.
+- `close()`: Closes the underlying network resources, when the provider is no longer needed.
+
+## Integration test suite
+
+The integration tests aren't currently run on CI, and can be run with `npm run test:integration:local`. Note that some environments variables must be set, and others are optional:
+
+All GCP resources will be created within the same project where the service account lives. The GCP service account should be allowed to manage KMS resources.
 
 The test suite will automatically delete all the resources it created, except for those that can't be deleted (e.g., GPC KMS key rings). Existing resources are not modified. However, this may not always be true due to bugs, so **always create a brand new, temporary GCP project**.