The did:key Method v0.7

3.1.1 Document Creation Algorithm

The following algorithm can be used for expanding a did:key identifier to a DID Document. An identifier and options are the required inputs. Implementations are expected to set a reasonable default for the options.publicKeyFormat value such as JsonWebKey2020 or Multikey. The options.enableExperimentalPublicKeyTypes value SHOULD be set to false. The options.defaultContext value SHOULD be set to an array where the first element is the string value https://www.w3.org/ns/did/v1. Defaults MAY be overridden by the caller of this algorithm. A document is the resulting output.

1. Initialize document to an empty object.
2. Using a colon (:) as the delimiter, split the identifier into its components: a scheme, a method, a version, and a multibaseValue. If there are only three components set the version to the string value 1 and use the last value as the multibaseValue.
3. Check the validity of the input identifier. The scheme MUST be the value did. If this requirement fails, an invalidDid error MUST be raised. The method MUST be the value key. If this requirement fails, a methodNotSupported error MUST be raised. The version MUST be convertible to a positive integer value. The multibaseValue MUST be a string and begin with the letter z. If any of these requirements fail, an invalidDid error MUST be raised.
4. Initialize the signatureVerificationMethod to the result of passing identifier, multibaseValue, and options to § 3.1.2 Signature Method Creation Algorithm.
5. Set document.id to identifier. If document.id is not a valid DID, an invalidDid error MUST be raised.
6. Initialize the verificationMethod property in document to an array where the first value is the signatureVerificationMethod.
7. Initialize the authentication, assertionMethod, capabilityInvocation, and the capabilityDelegation properties in document to an array where the first item is the value of the id property in signatureVerificationMethod.
8. If options.enableEncryptionKeyDerivation is set to true:
   1. Initialize the encryptionVerificationMethod to the result of passing identifier, multibaseValue, and options to § 3.1.5 Encryption Method Creation Algorithm.
   2. Add the encryptionVerificationMethod value to the verificationMethod array.
   3. Initialize the keyAgreement property in document to an array where the first item is the value of the id property in encryptionVerificationMethod.
9. Initialize the @context property in document to the result of passing document and options to the § 3.1.7 Context Creation Algorithm.
10. Return document.

Any alternative algorithm can be used that produces an equivalent result to the output from the algorithm above.

3.1.2 Signature Method Creation Algorithm

The following algorithm can be used for decoding a multibase-encoded multicodec value into a verification method that is suitable for verifying digital signatures. An identifier, multibaseValue, and options are the required inputs. A verificationMethod is the resulting output.

1. Initialize verificationMethod to an empty object.
2. Set multicodecValue and rawPublicKeyBytes to the result of passing multibaseValue and options to § 3.1.3 Decode Public Key Algorithm.
3. Ensure the proper key length of rawPublicKeyBytes based on the multicodecValue table provided below:

   Multicodec hexadecimal value	public key byte length	Description
   0xe7	33 bytes	secp256k1-pub - Secp256k1 public key (compressed)
   0xec	32 bytes	x25519-pub - Curve25519 public key
   0xed	32 bytes	ed25519-pub - Ed25519 public key
   0x1200	33 bytes	p256-pub - P-256 public key (compressed)
   0x1201	49 bytes	p384-pub - P-384 public key (compressed)
   0x1202	?? bytes	p521-pub - P-521 public key (compressed)
   0x1205	?? bytes	rsa-pub - RSA public key. DER-encoded ASN.1 type RSAPublicKey according to IETF RFC 8017 (PKCS #1)

   If the byte length of rawPublicKeyBytes does not match the expected public key length for the associated multicodecValue, an invalidPublicKeyLength error MUST be raised.
4. Ensure the rawPublicKeyBytes are a proper encoding of the public key type as specified by the multicodecValue. This validation is often done by a cryptographic library when importing the public key by, for example, ensuring that an Elliptic Curve public key is a specific coordinate that exists on the elliptic curve. If an invalid public key value is detected, an invalidPublicKey error MUST be raised.
   Issue: Request for feedback on implementability

   It is not clear if this particular check is implementable across all public key types. The group is accepting feedback on the implementability of this particular feature.
5. Set the verificationMethod.id value by concatenating identifier, a hash character (#), and the multicodecValue. If verificationMethod.id is not a valid DID URL, an invalidDidUrl error MUST be raised.
6. Set the publicKeyFormat value to the options.publicKeyFormat value.
7. If publicKeyFormat is not known to the implementation, an unsupportedPublicKeyType error MUST be raised.
8. If options.enableExperimentalPublicKeyTypes is set to false and publicKeyFormat is not Multikey, JsonWebKey2020, or Ed25519VerificationKey2020, an invalidPublicKeyType error MUST be raised.
9. Set verificationMethod.type to the publicKeyFormat value.
10. Set verificationMethod.controller to the identifier value. If verificationMethod.controller is not a valid DID, an invalidDid error MUST be raised.
11. If publicKeyFormat is Multikey or Ed25519VerificationKey2020, set the verificationMethod.publicKeyMultibase value to multibaseValue.
12. If publicKeyFormat is JsonWebKey2020, set the verificationMethod.publicKeyJwk value to the result of passing multicodecValue and rawPublicKeyBytes to § 3.1.4 Encode JWK Algorithm.
13. Return verificationMethod.

3.1.3 Decode Public Key Algorithm

The following algorithm can be used for expanding a multibase-encoded multicodec value to decoded public key components. A multibaseValue and options are the required inputs. A decodedPublicKey is the output.

1. Set decodedPublicKey to an empty object.
2. Decode multibaseValue using the base58-btc multibase alphabet and set multicodecValue to the multicodec header for the decoded value. Implementers are cautioned to ensure that the multicodecValue is set to the result after performing varint decoding.
3. Set the rawPublicKeyBytes to the bytes remaining after the multicodec header.
4. Return multicodecValue and rawPublicKeyBytes as the decodedPublicKey.

3.1.4 Encode JWK Algorithm

There are 2 categories of JWK expressions for multicodec encoded public keys.

Standard JWK representations can be found under the IANA registry for JSON Object Signing and Encryption (JOSE) .

In cases where a key type has not been formally standardized yet a specification describing the key encoding is provided.

BLS12381 is the only instance of such a key type in the current method specification. See this document tracking its proposed standardization at IETF. See draft-looker-cose-bls-key-representations.

Implementations MUST conform to the normative requirements of the RFCs and specifications above.

The following algorithm can be used to encode a multicodec value to a JSON Web Key. A multicodecValue, rawPublicKeyBytes are the required inputs. An encodedJWK is the output.

1. Obtain the associated kty, crv, n,e values for the JWK representation of the key type identified by multicodecValue.
2. If y is required member of the public key, perform elliptic curve expansion by applying decompression algorithm specified here. to obtain y and x. Otherwise simply encode x according to the associated RFCs.
3. Encode the final JWK object by including the members required for the given key type identified by multicodecValue, according to the requirements defined by the relevant RFC.
4. Ensure that d is NOT present.

3.1.5 Encryption Method Creation Algorithm

The following algorithm can be used for decoding a multibase-encoded multicodec value into a verification method that is suitable for verifying that encrypted information will be received by the intended recipient. An identifier, multibaseValue, and options are the required inputs. A verificationMethod is the resulting output.

1. Initialize verificationMethod to an empty object.
2. Set multicodecValue and rawPublicKeyBytes to the result of passing multibaseValue and options to § 3.1.6 Derive Encryption Key Algorithm.
3. Ensure the proper key length of rawPublicKeyBytes based on the multicodecValue table provided below:

   Multicodec hexadecimal value	public key byte length	Description
   0xec	32 bytes	x25519-pub - Curve25519 public key

   If the byte length of rawPublicKeyBytes does not match the expected public key length for the associated multicodecValue, an invalidPublicKeyLength error MUST be raised.
4. Create the multibaseValue by concatenating the letter 'z' and the base58-btc encoding of the concatenation of the multicodecValue and the rawPublicKeyBytes.
5. Set the verificationMethod.id value by concatenating identifier, a hash character (#), and the multibaseValue. If verificationMethod.id is not a valid DID URL, an invalidDidUrl error MUST be raised.
6. Set the publicKeyFormat value to the options.publicKeyFormat value.
7. If publicKeyFormat is not known to the implementation, an unsupportedPublicKeyType error MUST be raised.
8. If options.enableExperimentalPublicKeyTypes is set to false and publicKeyFormat is not Multikey, JsonWebKey2020, or X25519KeyAgreementKey2020, an invalidPublicKeyType error MUST be raised.
9. Set verificationMethod.type to the publicKeyFormat value.
10. Set verificationMethod.controller to identifier. If verificationMethod.controller is not a valid DID, an invalidDid error MUST be raised.
11. If publicKeyFormat is Multikey or X25519KeyAgreementKey2020, set the verificationMethod.publicKeyMultibase value to multibaseValue.
12. If publicKeyFormat is JsonWebKey2020, set the verificationMethod.publicKeyJwk value to the result of passing multicodecValue and rawPublicKeyBytes to § 3.1.4 Encode JWK Algorithm.
13. Return verificationMethod.

3.1.6 Derive Encryption Key Algorithm

The following algorithm can be used to 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 [THORMARKER]. A multibaseValue and options are the required inputs. A publicEncryptionKey is the output.

1. Set publicEncryptionKey to an empty object.
2. Decode multibaseValue using the base58-btc multibase alphabet and set multicodecValue to the multicodec header for the decoded value. Implementers are cautioned to ensure that the multicodecValue is set to the result after performing varint decoding.
3. Set the rawPublicKeyBytes to the bytes remaining after the multicodec header.
4. If the multicodecValue is 0xed, derive a public X25519 encryption key by using the rawPublicKeyBytes and the algorithm defined in [OSCORE] for Curve25519 in Section 2.4.2: ECDH with Montgomery Coordinates and set generatedPublicEncryptionKeyBytes to the result.
5. Set multicodecValue in publicEncryptionKey to 0xec.
6. Set rawPublicKeyBytes in publicEncryptionKey to generatedPublicEncryptionKeyBytes.
7. Return publicEncryptionKey.

3.1.7 Context Creation Algorithm

The following algorithm is used to generate the array for the @context property in the DID Document. A document and options are the required inputs. A contextArray is the output.

1. Set contextArray to an array that is initialized to options.defaultContext.
2. For every object in every verification relationship listed in document, add a string value to the contextArray based on the object type value, if it doesn't already exist, according to the following table:
   Issue

   type value	Context URL
   Ed25519VerificationKey2020	https://w3id.org/security/suites/ed25519-2020/v1
   X25519KeyAgreementKey2020	https://w3id.org/security/suites/x25519-2020/v1
   JsonWebKey2020	https://w3id.org/security/suites/jws-2020/v1
   Multikey	There is currently no JSON-LD Context that defines the Multikey type. This is expected to be defined by the VC2WG in 2022 or 2023.

3. Return contextArray.