relaycorp / webcrypto-kms-js

WebCrypto-compatible client for Key Management Services like GCP KMS

WebCrypto-compatible client for Key Management Services like GCP KMS

This library extends 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 and AWS KMS, and we welcome PRs to support additional KMSs.

This is an alternative to:

• The Key Management Interoperability Protocol (KMIP), if you don't want to run another server.
• 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.

Usage

The library is available on NPM as @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:

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_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (optional when running on AWS infrastructure).
  • AWS_KMS_ENDPOINT (optional when running on AWS infrastructure).
  • AWS_KMS_REGION (optional when running on AWS infrastructure).
• GCP adapter:
  • GOOGLE_APPLICATION_CREDENTIALS (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 members

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.

Private keys from this library additionally expose their respective provider in the property provider. This may be useful when you don't want to or can't manage a global registry of providers. This functionality is supported by @relaycorp/veraid, for example.

Integration test suite

The integration tests aren't currently run on CI, and can be run with npm run test:integration:local.

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.

Before running the AWS KMS tests, you need to start a mock AWS KMS server locally using docker:

docker run --rm -p 8080:8080 nsmithuk/local-kms

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.

webcrypto-kms-js's Issues

Implement key destruction

export abstract class CloudRsaPssProvider extends RsaPssProvider {
  public abstract destroyKey(key: CryptoKey): Promise<void>;
}

Note that GCP KMS keys can't be deleted... we can only delete their versions.

Implement signature verification

Simply using @peculiar/webcrypto.

We don't need it but will welcome a PR to support it.

Integrate functional tests in CI

• AWS: Use Local KMS.
• GCP: Use real service because there's no mock server.

Verification of AWS KMS signature fails

https://stackoverflow.com/questions/75857686/how-do-i-verify-a-digital-signature-produced-by-aws-kms-outside-aws-kms

Write functional tests with mock AWS KMS server

https://github.com/nsmithuk/local-kms/issues

Client can be initialised with:

import { KMSClient } from '@aws-sdk/client-kms';

  const client = new KMSClient({
    credentials: { accessKeyId: 'accessKeyId', secretAccessKey: 'secretAccessKey' },
    endpoint: 'http://localhost:8080',
    region: 'eu-west-2',
  });

Add suppor for Azure Key Vault

We're not planning to implement this, but will welcome a PR from a third party that's willing to maintain it.

https://azure.microsoft.com/en-gb/products/key-vault

GCP KMS: Implement private key "import" and "export"

• Import input:
  • Format: "raw"
  • Value: ArrayBuffer representing key and key version.
• Export output:
  • Format: "raw"
  • Value: ArrayBuffer representing key and key version.

Implement function to generate GCP KMS keys

Port functional tests for GCP KMS

Implement disconnection from backing service(s)

export abstract class CloudRsaPssProvider extends RsaPssProvider {
  public abstract disconnect(): Promise<void>;
}

Port GCP adapter

From https://github.com/relaycorp/awala-keystore-cloud-js

Implement function to initialise correct adapter from env vars

Port Vault adapter

From https://github.com/relaycorp/awala-keystore-cloud-js