Web5 Crypto AWS KMS Extension

| An extension for the Web5 Crypto API to enable use of AWS KMS | | --------------------------------------------------------------------------------- |

• Introduction
  • Supported Algorithms & Key Types
• Getting Started
  • Node.js Package
  • Configure the AWS SDK
• Contributing
• Core Concepts
  • Key URIs
  • Using AWS KMS
• Customization
  • Configure the AWS SDK KMSClient

This JavaScript extension to the Web5 Crypto API provides an interface to leverage the cryptography capabilities offered by the Amazon Web Services (AWS) Key Management System (KMS) service. The extension was designed for building backend services and supports the Node.js runtime environment. The key generation, hashing, and signature algorithm functions can be used by other libraries in this monorepo when working with Decentralized Identifiers (DID) and Verifiable Credentials (VC).

Supported Algorithms & Key Types

The following algorithms and key types are currently supported, with plans to expand its offerings as the extension progresses towards a 1.0 release.

| Capability | Details | | ---------- | --------- | | Signature | ECDSA | | Hash | SHA-256 | | ECC Curves | secp256k1 |

Getting Started

The Web5 Crypto AWS KMS extension is distributed as @web5/crypto-aws-kms via npmjs.com and github.com.

Install the Node.js Package

This extension is designed and tested for the active (v20) and maintenance (v18) LTS releases of Node.js

Install the latest version of @web5/crypto-aws-kms using npm or your preferred package manager:

npm install @web5/crypto-aws-kms

Example ESM import:

import { AwsKeyManager } from "@web5/crypto-aws-kms";

Example CJS require:

const { AwsKeyManager } = require("@web5/crypto-aws-kms");

Configure the AWS SDK

Interacting with the AWS service APIs via AWS SDKs and tools like AWS CLI requires configuration with necessary credentials and settings. Credentials are essential for identity verification and encrypting requests. AWS uses these to authenticate and authorize actions based on associated permissions. Additionally, other configuration details determine request processing, endpoint routing, and response interpretation.

Commonly, credentials and settings are provided through shared config and credentials files or environment variables. These files support multiple profiles for various scenarios, with one set as the default. Environment variables offer an alternative, allowing dynamic modification during runtime.

Follow the steps in one of the following reference guides to supply the required credential and configuration information to the AWS SDK for JavaScript, which this extension uses for all communication with the AWS KMS API.

• Shared AWS config and credentials files
• Environment variables

Contributing

We welcome you to join our open source community. Whether you're new to open source or a seasoned contributor, there's a place for you here. From coding to documentation, every contribution matters. Check out our contribution guide for ways to get started.

For help, discussion about best practices, or to chat with others building on Web5 join our Discord Server:

Remember, contributing is not just about code; it's about building together. Join us in shaping the future of the Web!

Core Concepts

Key URIs

One of the core design principles for the SDKs in the Web5 ecosystem is the protection of private key material. Instead of directly handling sensitive key information, our SDKs interact with cryptographic keys through Key Management Systems (KMS) referenced by a unique identifier called a Key URI. This approach ensures that private keys remain secure, while still allowing for versatile cryptographic functionalities.

Each KMS assigns a unique identifier to a key when it is created. This identifier can be used to form a Uniform Resource Identifier (URI) by adding a prefix. The following table shows the format of supported Key URIs:

| Prefix | Key URI Format | | ------------- | ------------------------------------------------ | | urn:jwk | urn:jwk:<jwk-thumbprint> | | arn:aws:kms | arn:aws:kms:<region>:<account-id>:key/<key-id> |

All cryptographic keys are represented in JSON Web Key (JWK) format and the jwk-thumbprint, a standardized, deterministic, and unique hash of the key, acts as a fingerprint, enabling consistent key referencing across all Web5 libraries without exposing private key information. Additionally, AWS KMS assigns an Amazon Resource Name (ARN) to each customer-managed key, which can be used interchangeably as a key identifier.

[!INFORMATION] The advantage to using the urn:jwk Key URI format is that it enables interoperability between all Web5 SDKs and KMS providers. By using a standardized method to compute a thumbprint, different implementations will always generate the same thumbprint for any given JWK thereby ensuring consistent key referencing.

Using AWS KMS

This extension to the Web5 Crypto API enables use of the key management and cryptographic features of the AWS KMS service. Key generation and signing take place in the cloud, ensuring private keys never leave the secure AWS KMS environment. Signature verification and hash computations, being non-sensitive operations, are safely executed locally. This design choice balances security with flexibility, allowing for efficient verification and hashing without compromising the confidentiality and integrity of the private keys.

Start by instantiating an AWS KMS implementation of the CryptoApi interface:

import { AwsKeyManager } from "@web5/crypto-aws-kms";

const kms = new AwsKeyManager();

If not provided, a default instance of KMSClient from the AWS SDK for JavaScript will be used. This client signs and encrypts all communication with the AWS KMS API. See Configure the AWS SDK KMSClient for details on how modify KMSClient configuration parameters at runtime.

Generate a random private key:

const privateKeyUri = await kms.generateKey({ algorithm: "ES256K" });
console.log(privateKeyUri);
// Output: urn:jwk:U01_M3_A9vMLOWixG-rlfC-_f3LLdurttn7c7d3_upU

Create an ECDSA signature over arbitrary data using the private key:

const data = new TextEncoder().encode("Message");
const signature = await kms.sign({
  keyUri: privateKeyUri,
  data,
});
console.log(signature);
// Output:
// Uint8Array(64) [
//   136, 145, 145,  76,  67,  27, 170, 230, 130, 222, 252,
//    87, 254,   7,  76, 140, 183,   0, 247, 144, 215,  46,
//    42,  81,  71,  76, 202,  14, 224,  15, 170, 132, 174,
//    27, 157, 198, 164, 143,  74, 229,  25,  70, 114, 192,
//    82,  61, 204,  80, 108, 253, 135,  98, 197, 145,  69,
//   120, 146,  61, 183, 245,   9,  27, 157,  27
// ]

Get the public key in JWK format:

const publicKey = await kms.getPublicKey({ keyUri: privateKeyUri });
console.log(publicKey);
// Output:
// {
//   kty: "EC",
//   crv: "secp256k1",
//   alg: "ES256K",
//   kid: "U01_M3_A9vMLOWixG-rlfC-_f3LLdurttn7c7d3_upU",
//   x: "tgOFTPRSUPqMLu9pBTz5dLHNh_op4SZ6zmc6ZmF0CzQ",
//   y: "6qju4NwZFqlBW78fKMB4K0zJbfXYV3SA8UPAI-pWLe0"
// }

Verify the signature using the public key:

const isValid = await kms.verify({
  key: publicKey,
  signature,
  data,
});
console.log(isValid);
// Output: true

Compute the hash digest of arbitrary data:

const data = new TextEncoder().encode("Message");
const hash = await kms.digest({ algorithm: "SHA-256", data });
console.log(hash);
// Output:
// Uint8Array(32) [
//     8, 187,  94,  93, 110, 170, 193,  4,
//   158, 222,   8, 147, 211,  14, 208, 34,
//   177, 164, 217, 181, 180, 141, 180, 20,
//   135,  31,  81, 201, 203,  53,  40, 61
// ]

Customization

Configure the AWS SDK KMSClient

By default, AwsKeyManager creates an instance of KMSClient which uses the credential and configuration information supplied in shared AWS config and credentials files or environment variables. To set the region, credentials, and other options used by KMSClient at runtime, a custom instance can be passed to the AwsKeyManager constructor.

For example, to set the AWS region to which the client will send requests:

import { KMSClient } from "@aws-sdk/client-kms";
import { AwsKeyManager } from "@web5/crypto-aws-kms";

const kmsClient = new KMSClient({ region: "us-east-1" });
const kms = new AwsKeyManager({ kmsClient });

Additional configuration fields of the KMSClient class constructor are described in the KMSClientConfig configuration type.

Project Resources

| Resource | Description | | --------------------------------------- | ----------------------------------------------------------------------------- | | CODEOWNERS | Outlines the project lead(s) | | CODE OF CONDUCT | Expected behavior for project contributors, promoting a welcoming environment | | CONTRIBUTING | Developer guide to build, test, run, access CI, chat, discuss, file issues | | GOVERNANCE | Project governance | | LICENSE | Apache License, Version 2.0 |