Class DidKey

The DidKey class provides an implementation of the 'did:key' DID method.

Features:

  • DID Creation: Create new did:key DIDs.
  • DID Key Management: Instantiate a DID object from an existing verification method key set or or a key in a Key Management System (KMS). If supported by the KMS, a DID's key can be exported to a portable DID format.
  • DID Resolution: Resolve a did:key to its corresponding DID Document.
  • Signature Operations: Sign and verify messages using keys associated with a DID.

Remarks

The did:key DID method uses a single public key to generate a DID and does not rely on any external system such as a blockchain or centralized database. This characteristic makes it suitable for use cases where a assertions about a DID Subject can be self-verifiable by third parties.

The method-specific identifier is formed by Multibase base58-btc encoding the concatenation of the Multicodec identifier for the public key type and the raw public key bytes. To form the DID URI, the method-specific identifier is prefixed with the string 'did:key:'.

This method can optionally derive an encryption key from the public key used to create the DID if and only if the public key algorithm is Ed25519. This feature enables the same DID to be used for encrypted communication, in addition to signature verification. To enable this feature when calling DidKey.create(), first specify an algorithm of Ed25519 or provide a keySet referencing an Ed25519 key and then set the enableEncryptionKeyDerivation option to true.

Note:

  • The authors of the DID Key specification have indicated that use of this method for long-lived use cases is only recommended when accompanied with high confidence that private keys are securely protected by software or hardware isolation.

See

DID Key Specification

Example

// DID Creation
const did = await DidKey.create();

// DID Creation with a KMS
const keyManager = new LocalKeyManager();
const did = await DidKey.create({ keyManager });

// DID Resolution
const resolutionResult = await DidKey.resolve({ did: did.uri });

// Signature Operations
const signer = await did.getSigner();
const signature = await signer.sign({ data: new TextEncoder().encode('Message') });
const isValid = await signer.verify({ data: new TextEncoder().encode('Message'), signature });

// Key Management

// Instantiate a DID object from an existing key in a KMS
const did = await DidKey.fromKeyManager({
 didUri: 'did:key:z6MkpUzNmYVTGpqhStxK8yRKXWCRNm1bGYz8geAg2zmjYHKX',
 keyManager
});

// Instantiate a DID object from an existing verification method key
const did = await DidKey.fromKeys({
  verificationMethods: [{
    publicKeyJwk: {
      kty: 'OKP',
      crv: 'Ed25519',
      x: 'cHs7YMLQ3gCWjkacMURBsnEJBcEsvlsE5DfnsfTNDP4'
    },
    privateKeyJwk: {
      kty: 'OKP',
      crv: 'Ed25519',
      x: 'cHs7YMLQ3gCWjkacMURBsnEJBcEsvlsE5DfnsfTNDP4',
      d: 'bdcGE4KzEaekOwoa-ee3gAm1a991WvNj_Eq3WKyqTnE'
    }
  }]
});

// Convert a DID object to a portable format
const portableDid = await DidKey.toKeys({ did });

// Reconstruct a DID object from a portable format
const did = await DidKey.fromKeys(portableDid);

Hierarchy (view full)

Constructors

constructor

Properties

methodName

Methods

create createDocument createEncryptionMethod createSignatureMethod deriveEncryptionKey getSigningMethod import resolve validateIdentifier

Constructors

constructor

Properties

Static methodName

methodName: string = 'key'

Name of the DID method, as defined in the DID Key specification.

Methods

Static create

  • create<TKms>(params?): Promise<BearerDid>

  • Creates a new DID using the did:key method formed from a newly generated key.

    Type Parameters

    Parameters

    • params: {
          keyManager?: TKms;
          options?: DidKeyCreateOptions<TKms>;
      } = {}

      The parameters for the create operation.

      • Optional keyManager?: TKms

        Key Management System (KMS) used to generate keys and sign data.

      • Optional options?: DidKeyCreateOptions<TKms>

        Optional parameters that can be specified when creating a new DID.

    Returns Promise<BearerDid>

    A Promise resolving to a BearerDid object representing the new DID.

    Remarks

    The DID URI is formed by Multibase base58-btc encoding the Multicodec-encoded public key and prefixing with did:key:.

    This method can optionally derive an encryption key from the public key used to create the DID if and only if the public key algorithm is Ed25519. This feature enables the same DID to be used for encrypted communication, in addition to signature verification. To enable this feature, specify an algorithm of Ed25519 as either a top-level option or in a verificationMethod and set the enableEncryptionKeyDerivation option to true.

    Notes:

    • If no options are given, by default a new Ed25519 key will be generated.
    • The algorithm and verificationMethods options are mutually exclusive. If both are given, an error will be thrown.

    Example

    // DID Creation
    const did = await DidKey.create();

    // DID Creation with a KMS
    const keyManager = new LocalKeyManager();
    const did = await DidKey.create({ keyManager });

Private Static createDocument

Private Static createEncryptionMethod

Private Static createSignatureMethod

Private Static deriveEncryptionKey

  • deriveEncryptionKey(__namedParameters): Promise<RequireOnly<KeyWithMulticodec, "keyBytes" | "multicodecCode">>

  • Transform a multibase-encoded multicodec value to public encryption key components that are suitable for encrypting messages to a receiver. A mathematical proof elaborating on the safety of performing this operation is available in: On using the same key pair for Ed25519 and an X25519 based KEM

    Parameters

    • __namedParameters: {
          multibaseValue: string;
      }
      • multibaseValue: string

    Returns Promise<RequireOnly<KeyWithMulticodec, "keyBytes" | "multicodecCode">>

Static getSigningMethod

  • getSigningMethod(params): Promise<DidVerificationMethod>

  • Given the W3C DID Document of a did:key DID, return the verification method that will be used for signing messages and credentials. With DID Key, the first verification method in the authentication property in the DID Document is used.

    Note that for DID Key, only one verification method intended for signing can exist so specifying methodId could be considered redundant or unnecessary. The option is provided for consistency with other DID method implementations.

    Parameters

    • params: {
          didDocument: DidDocument;
          methodId?: string;
      }

      The parameters for the getSigningMethod operation.

      • didDocument: DidDocument

        DID Document to get the verification method from.

      • Optional methodId?: string

        ID of the verification method to use for signing.

    Returns Promise<DidVerificationMethod>

    Verification method to use for signing.

Static import

Static resolve

Private Static validateIdentifier

  • validateIdentifier(parsedDid): boolean

  • Validates the structure and components of a DID URI against the did:key method specification.

    Parameters

    • parsedDid: Did

      An object representing the parsed components of a DID URI, including the scheme, method, and method-specific identifier.

    Returns boolean

    true if the DID URI meets the did:key method's structural requirements, false otherwise.

Settings

Member Visibility

Theme

On This Page

constructormethodNamecreatecreateDocumentcreateEncryptionMethodcreateSignatureMethodderiveEncryptionKeygetSigningMethodimportresolvevalidateIdentifier