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`. The method MUST be the value `key`. 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 .
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 .
   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 .
10. Return document.

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

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. 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.
   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 .
13. Return verificationMethod.

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.

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.

Address RSA encoding for DER encoded RSA keys.

Address BLS12381 Encoding.

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. 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 .
13. Return verificationMethod.

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.

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:

   `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.