Optional params: LocalKeyManagerParamsPrivate _algorithmA private map that stores instances of cryptographic algorithm implementations. Each key in
this map is an AlgorithmConstructor, and its corresponding value is an instance of a class
that implements a specific cryptographic algorithm. This map is used to cache and reuse
instances for performance optimization, ensuring that each algorithm is instantiated only once.
Private _keyThe _keyStore private variable in LocalKeyManager is a KeyValueStore instance used for
storing and managing cryptographic keys. It allows the LocalKeyManager class to save,
retrieve, and handle keys efficiently within the local Key Management System (KMS) context.
This variable can be configured to use different storage backends, like in-memory storage or
persistent storage, providing flexibility in key management according to the application's
requirements.
Generates a hash digest of the provided data.
The parameters for the digest operation.
A Promise which will be fulfilled with the hash digest.
A digest is the output of the hash function. It's a fixed-size string of bytes that uniquely represents the data input into the hash function. The digest is often used for data integrity checks, as any alteration in the input data results in a significantly different digest.
It takes the algorithm identifier of the hash function and data to digest as input and returns the digest of the data.
const keyManager = new LocalKeyManager();
const data = new Uint8Array([...]);
const digest = await keyManager.digest({ algorithm: 'SHA-256', data });
Exports a private key identified by the provided key URI from the local KMS.
Parameters for exporting the key.
A Promise resolving to the JWK representation of the exported key.
This method retrieves the key from the key store and returns it. It is primarily used for extracting keys for backup or transfer purposes.
const keyManager = new LocalKeyManager();
const keyUri = await keyManager.generateKey({ algorithm: 'Ed25519' });
const privateKey = await keyManager.exportKey({ keyUri });
Generates a new cryptographic key in the local KMS with the specified algorithm and returns a unique key URI which can be used to reference the key in subsequent operations.
The parameters for key generation.
A Promise that resolves to the key URI, a unique identifier for the generated key.
const keyManager = new LocalKeyManager();
const keyUri = await keyManager.generateKey({ algorithm: 'Ed25519' });
console.log(keyUri); // Outputs the key URI
Private getRetrieves an algorithm implementation instance based on the provided algorithm name.
The parameters for retrieving the algorithm implementation.
The name of the algorithm to retrieve.
An instance of the requested algorithm implementation.
This method checks if the requested algorithm is supported and returns a cached instance if available. If an instance does not exist, it creates and caches a new one. This approach optimizes performance by reusing algorithm instances across cryptographic operations.
const signer = this.getAlgorithm({ algorithm: 'Ed25519' });
Error if the requested algorithm is not supported.
Private getDetermines the name of the algorithm based on the key's properties.
The parameters for determining the algorithm name.
A JWK containing the alg or crv properties.
Optional alg?: stringOptional crv?: stringThe name of the algorithm associated with the key.
This method facilitates the identification of the correct algorithm for cryptographic
operations based on the alg or crv properties of a JWK.
const publicKey = { ... }; // Public key in JWK format
const algorithm = this.getAlgorithmName({ key: publicKey });
Error if the algorithm cannot be determined from the provided input.
Computes the Key URI for a given public JWK (JSON Web Key).
The parameters for getting the key URI.
A Promise that resolves to the key URI as a string.
This method generates a URI
(Uniform Resource Identifier) for the given JWK, which uniquely identifies the key across all
CryptoApi implementations. The key URI is constructed by appending the
JWK thumbprint to the prefix
urn:jwk:. The JWK thumbprint is deterministically computed from the JWK and is consistent
regardless of property order or optional property inclusion in the JWK. This ensures that the
same key material represented as a JWK will always yield the same thumbprint, and therefore,
the same key URI.
const keyManager = new LocalKeyManager();
const keyUri = await keyManager.generateKey({ algorithm: 'Ed25519' });
const publicKey = await keyManager.getPublicKey({ keyUri });
const keyUriFromPublicKey = await keyManager.getKeyUri({ key: publicKey });
console.log(keyUri === keyUriFromPublicKey); // Outputs `true`
Private getRetrieves a private key from the key store based on the provided key URI.
Parameters for retrieving the private key.
The key URI identifying the private key to retrieve.
A Promise resolving to the JWK representation of the private key.
const privateKey = this.getPrivateKey({ keyUri: 'urn:jwk:...' });
Error if the key is not found in the key store.
Retrieves the public key associated with a previously generated private key, identified by the provided key URI.
The parameters for retrieving the public key.
A Promise that resolves to the public key in JWK format.
const keyManager = new LocalKeyManager();
const keyUri = await keyManager.generateKey({ algorithm: 'Ed25519' });
const publicKey = await keyManager.getPublicKey({ keyUri });
Imports a private key into the local KMS.
Parameters for importing the key.
A Promise resolving to the key URI, uniquely identifying the imported key.
This method stores the provided JWK in the key store, making it available for subsequent cryptographic operations. It is particularly useful for initializing the KMS with pre-existing keys or for restoring keys from backups.
Note that, if defined, the kid (key ID) property of the JWK is used as the key URI for the
imported key. If the kid property is not provided, the key URI is computed from the JWK
thumbprint of the key.
const keyManager = new LocalKeyManager();
const privateKey = { ... } // A private key in JWK format
const keyUri = await keyManager.importKey({ key: privateKey });
Signs the provided data using the private key identified by the provided key URI.
The parameters for the signing operation.
A Promise resolving to the digital signature as a Uint8Array.
This method uses the signature algorithm determined by the alg and/or crv properties of the
private key identified by the provided key URI to sign the provided data. The signature can
later be verified by parties with access to the corresponding public key, ensuring that the
data has not been tampered with and was indeed signed by the holder of the private key.
const keyManager = new LocalKeyManager();
const keyUri = await keyManager.generateKey({ algorithm: 'Ed25519' });
const data = new TextEncoder().encode('Message to sign');
const signature = await keyManager.sign({ keyUri, data });
Verifies a digital signature associated the provided data using the provided key.
The parameters for the verification operation.
A Promise resolving to a boolean indicating whether the signature is valid.
This method uses the signature algorithm determined by the alg and/or crv properties of the
provided key to check the validity of a digital signature against the original data. It
confirms whether the signature was created by the holder of the corresponding private key and
that the data has not been tampered with.
const keyManager = new LocalKeyManager();
const keyUri = await keyManager.generateKey({ algorithm: 'Ed25519' });
const data = new TextEncoder().encode('Message to sign');
const signature = await keyManager.sign({ keyUri, data });
const isSignatureValid = await keyManager.verify({ keyUri, data, signature });
The
CryptoApiinterface integrates key generation, hashing, and signing functionalities, designed for use with a Key Management System (KMS). It extendsAsymmetricKeyGeneratorfor generating asymmetric keys,Hasherfor hash digest computations, andSignerfor signing and verifying operations.Concrete implementations of this interface are intended to be used with a KMS, which is responsible for generating and storing cryptographic keys. The KMS is also responsible for performing cryptographic operations using the keys it manages. The KMS is typically a cloud service, but it can also be a hardware device or software application.
Guidelines for implementing this interface:
KeyIdentifier. Implementations can use any string as the key identifier (e.g. JWK thumbprint, UUID generated by hosted KMS, etc.).CryptoApiinterface can be passed as an argument to the public API methods of Web5 libraries that involve key material (e.g., DID creation, VC signing, arbitrary data signing/verification, etc.).