This specification describes a Data Integrity Cryptosuite for use when generating a digital signature using the Elliptic Curve Digital Signature Algorithm (ECDSA).
This is an experimental specification and is undergoing regular revisions. It is not fit for production deployment.
This specification defines a cryptographic suite for the purpose of creating, and verifying proofs for ECDSA signatures in conformance with the Data Integrity [[VC-DATA-INTEGRITY]] specification. ECDSA signatures are specified in [[FIPS-186-5]] with elliptic curves P-256 and P-384 specified in [[NIST-SP-800-186]]. [[FIPS-186-5]] includes the deterministic ECDSA algorithm which is also specified in [[RFC6979]].
This specification uses either the RDF Dataset Canonicalization Algorithm [[RDF-CANON]] or the JSON Canonicalization Scheme [[RFC8785]] to transform the input document into its canonical form. It uses one of two mechanisms to digest and sign: SHA-256 [[RFC6234]] as the message digest algorithm and ECDSA with Curve P-256 as the signature algorithm, or SHA-384 [[RFC6234]] as the message digest algorithm and ECDSA with Curve P-384 as the signature algorithm.
The elliptic curves P-256 and P-384 of [[NIST-SP-800-186]] are referred to as secp256r1 and secp384r1 respectively in [[SECG2]]. In addition, this notation is sometimes used in ECDSA software libraries.
A conforming proof is any concrete expression of the data model that complies with the normative statements in this specification. Specifically, all relevant normative statements in Sections and of this document MUST be enforced.
A conforming processor is any algorithm realized as software and/or hardware that generates or consumes a conforming proof. Conforming processors MUST produce errors when non-conforming documents are consumed.
This document also contains examples that contain JSON and JSON-LD content. Some of these examples contain characters that are invalid JSON, such as inline comments (`//`) and the use of ellipsis (`...`) to denote information that adds little value to the example. Implementers are cautioned to remove this content if they desire to use the information as valid JSON or JSON-LD.
The following sections outline the data model that is used by this specification for verification methods and data integrity proof formats.
The cryptographic material used to verify a data integrity proof is called the verification method. This suite relies on public key material represented using [[MULTIBASE]] and [[MULTICODEC]]. This suite supports public key use for both digital signature generation and verification, according to [[FIPS-186-5]].
This suite MAY be used to verify Data Integrity Proofs [[VC-DATA-INTEGRITY]] produced by ECDSA public key material encoded as a Multikey. Loss-less key transformation processes that result in equivalent cryptographic material MAY be utilized.
This definition should go in the Data Integrity specification and referenced from there.
The `type` of the verification method MUST be `Multikey`.
The `controller` of the verification method MUST be a URL.
The `publicKeyMultibase` property of the verification method MUST be a public key encoded according to [[MULTICODEC]] and formatted according to [[MULTIBASE]]. The multicodec encoding of a P-256 public key is the two-byte prefix `0x1200` followed by the 33-byte compressed public key data. The 35 byte value is then encoded using base58-btc (`z`) as the prefix. The multicodec encoding of a P-384 public key is the two-byte prefix `0x1201` followed by the 49-byte compressed public key data. The 51 byte value is then encoded using base58-btc (`z`) as the prefix. Any other encodings MUST NOT be allowed.
Developers are advised to not accidentally publish a representation of a private key. Implementations of this specification will raise errors in the event of a [[MULTICODEC]] value other than `0x1200` or `0x1201` being used in a `publicKeyMultibase` value.
{
"id": "https://example.com/issuer/123#key-0",
"type": "Multikey",
"controller": "https://example.com/issuer/123",
"publicKeyMultibase": "zDnaerx9CtbPJ1q36T5Ln5wYt3MQYeGRG5ehnPAmxcf5mDZpv"
}
{
"id": "https://example.com/issuer/123#key-0",
"type": "Multikey",
"controller": "https://example.com/issuer/123",
"publicKeyMultibase": "z82LkvCwHNreneWpsgPEbV3gu1C6NFJEBg4srfJ5gdxEsMGRJ
Uz2sG9FE42shbn2xkZJh54"
}
{
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/data-integrity/v1"
],
"id": "did:example:123",
"verificationMethod": [{
"id": "https://example.com/issuer/123#key-1",
"type": "Multikey",
"controller": "https://example.com/issuer/123",
"publicKeyMultibase": "zDnaerx9CtbPJ1q36T5Ln5wYt3MQYeGRG5ehnPAmxcf5mDZpv"
}, {
"id": "https://example.com/issuer/123#key-2",
"type": "Multikey",
"controller": "https://example.com/issuer/123",
"publicKeyMultibase": "z82LkvCwHNreneWpsgPEbV3gu1C6NFJEBg4srfJ5gdxEsMGRJ
Uz2sG9FE42shbn2xkZJh54"
}],
"authentication": [
"did:example:123#key-1"
],
"assertionMethod": [
"did:example:123#key-2"
],
"capabilityDelegation": [
"did:example:123#key-2"
],
"capabilityInvocation": [
"did:example:123#key-2"
]
}
This specification should not specify multikey formats. It should, instead, point to a multikey registry and/or specification. Examples of these sorts of documents include the DID Specification Registries for Verification Method Types, the key types in the Multikey2021 JSON-LD Context, and key definitions in the Security Vocabulary. Ideally, the specification that this one points to would define all possible multikeys listed in the Multicodec Registry and define how to encode them as multibase values in fields such as `publicKeyMultibase` and `secretKeyMultibase`. The referenced specification should also include an extensibility mechanism and registry for new values as they are added to the Multicodec Registry.
This suite relies on detached digital signatures represented using [[MULTIBASE]] and [[MULTICODEC]].
The `verificationMethod` property of the proof MUST be a URL. Dereferencing the `verificationMethod` MUST result in an object containing a `type` property with the value set to `Multikey`.
The `type` property of the proof MUST be `DataIntegrityProof`.
The `cryptosuite` property of the proof MUST be `ecdsa-2019`.
The `created` property of the proof MUST be an [[XMLSCHEMA11-2]] formatted date string.
The `proofPurpose` property of the proof MUST be a string, and MUST match the verification relationship expressed by the verification method `controller`.
The `proofValue` property of the proof MUST be a detached ECDSA produced according to [[FIPS-186-5]], encoded according to [[MULTIBASE]] using the base58-btc base encoding.
{
"@context": [
{"title": "https://schema.org/title"},
"https://w3id.org/security/data-integrity/v1"
],
"title": "Hello world!",
"proof": {
"type": "DataIntegrityProof",
"cryptosuite": "ecdsa-2019",
"created": "2020-11-05T19:23:24Z",
"verificationMethod": "https://example.com/issuer/123#key-2",
"proofPurpose": "assertionMethod",
"proofValue": "z4oey5q2M3XKaxup3tmzN4DRFTLVqpLMweBrSxMY2xHX5XTYVQeVbY8nQA
VHMrXFkXJpmEcqdoDwLWxaqA3Q1geV6"
}
}
The following section describes multiple Data Integrity cryptographic suites that utilize the Elliptic Curve Digital Signature Algorithm (ECDSA) [[FIPS-186-5]].
The `ecdsa-2019` cryptographic suite takes an input document, canonicalizes the document using the Universal RDF Dataset Canonicalization Algorithm [[RDF-CANON]], and then cryptographically hashes and signs the output resulting in the production of a data integrity proof. The algorithms in this section also include the verification of such a data integrity proof.
To generate a proof, the algorithm in Section 4.1: Add Proof in the Data Integrity [[VC-DATA-INTEGRITY]] specification MUST be executed. For that algorithm, the cryptographic suite specific transformation algorithm is defined in Section , the hashing algorithm is defined in Section , and the proof serialization algorithm is defined in Section .
To verify a proof, the algorithm in Section 4.2: Verify Proof in the Data Integrity [[VC-DATA-INTEGRITY]] specification MUST be executed. For that algorithm, the cryptographic suite specific transformation algorithm is defined in Section , the hashing algorithm is defined in Section , and the proof verification algorithm is defined in Section .
The following algorithm specifies how to transform an unsecured input document into a transformed document that is ready to be provided as input to the hashing algorithm in Section .
Required inputs to this algorithm are an unsecured data document (unsecuredDocument) and transformation options (options). The transformation options MUST contain a type identifier for the cryptographic suite (type) and a cryptosuite identifier (cryptosuite). A transformed data document is produced as output. Whenever this algorithm encodes strings, it MUST use UTF-8 encoding.
The following algorithm specifies how to cryptographically hash a transformed data document and proof configuration into cryptographic hash data that is ready to be provided as input to the algorithms in Section or Section . One must use the hash algorithm appropriate in security level to the curve used, i.e., for curve P-256 one uses SHA-256 and for curve P-384 one uses SHA-384.
The required inputs to this algorithm are a transformed data document (transformedDocument) and canonical proof configuration (canonicalProofConfig). A single hash data value represented as series of bytes is produced as output.
The following algorithm specifies how to generate a proof configuration from a set of proof options that is used as input to the proof hashing algorithm.
The required inputs to this algorithm are proof options (options). The proof options MUST contain a type identifier for the cryptographic suite (type) and MUST contain a cryptosuite identifier (cryptosuite). A proof configuration object is produced as output.
The following algorithm specifies how to serialize a digital signature from a set of cryptographic hash data. This algorithm is designed to be used in conjunction with the algorithms defined in the Data Integrity [[VC-DATA-INTEGRITY]] specification, Section 4: Algorithms. Required inputs are cryptographic hash data (hashData) and proof options (options). The proof options MUST contain a type identifier for the cryptographic suite (type) and MAY contain a cryptosuite identifier (cryptosuite). A single digital proof value represented as series of bytes is produced as output.
The following algorithm specifies how to verify a digital signature from a set of cryptographic hash data. This algorithm is designed to be used in conjunction with the algorithms defined in the Data Integrity [[VC-DATA-INTEGRITY]] specification, Section 4: Algorithms. Required inputs are cryptographic hash data (hashData), a digital signature (proofBytes) and proof options (options). A verification result represented as a boolean value is produced as output.
The `jcs-ecdsa-2019` cryptographic suite takes an input document, canonicalizes the document using the JSON Canonicalization Scheme [[RFC8785]], and then cryptographically hashes and signs the output resulting in the production of a data integrity proof. The algorithms in this section also include the verification of such a data integrity proof.
To generate a proof, the algorithm in Section 4.1: Add Proof of the Data Integrity [[VC-DATA-INTEGRITY]] specification MUST be executed. For that algorithm, the cryptographic suite-specific transformation algorithm is defined in Section , the hashing algorithm is defined in Section , and the proof serialization algorithm is defined in Section .
To verify a proof, the algorithm in Section 4.2: Verify Proof of the Data Integrity [[VC-DATA-INTEGRITY]] specification MUST be executed. For that algorithm, the cryptographic suite-specific transformation algorithm is defined in Section , the hashing algorithm is defined in Section , and the proof verification algorithm is defined in Section .
The following algorithm specifies how to transform an unsecured input document into a transformed document that is ready to be provided as input to the hashing algorithm in Section .
Required inputs to this algorithm are an unsecured data document (unsecuredDocument) and transformation options (options). The transformation options MUST contain a type identifier for the cryptographic suite (type) and a cryptosuite identifier (cryptosuite). A transformed data document is produced as output. Whenever this algorithm encodes strings, it MUST use UTF-8 encoding.
The following algorithm specifies how to cryptographically hash a transformed data document and proof configuration into cryptographic hash data that is ready to be provided as input to the algorithms in Section or Section . One must use the hash algorithm appropriate in security level to the curve used, i.e., for curve P-256 one uses SHA-256, and for curve P-384 one uses SHA-384.
The required inputs to this algorithm are a transformed data document (transformedDocument) and a canonical proof configuration (canonicalProofConfig). A single hash data value represented as series of bytes is produced as output.
The following algorithm specifies how to generate a proof configuration from a set of proof options that is used as input to the proof hashing algorithm.
The required inputs to this algorithm are proof options (options). The proof options MUST contain a type identifier for the cryptographic suite (type) and MUST contain a cryptosuite identifier (cryptosuite). A proof configuration object is produced as output.
The following algorithm specifies how to serialize a digital signature from a set of cryptographic hash data. This algorithm is designed to be used in conjunction with the algorithms defined in the Data Integrity [[VC-DATA-INTEGRITY]] specification, Section 4: Algorithms. Required inputs are cryptographic hash data (hashData) and proof options (options). The proof options MUST contain a type identifier for the cryptographic suite (type) and MAY contain a cryptosuite identifier (cryptosuite). A single digital proof value represented as series of bytes is produced as output.
The following algorithm specifies how to verify a digital signature from a set of cryptographic hash data. This algorithm is designed to be used in conjunction with the algorithms defined in the Data Integrity [[VC-DATA-INTEGRITY]] specification, Section 4: Algorithms. Required inputs are cryptographic hash data (hashData), a digital signature (proofBytes), and proof options (options). A verification result represented as a boolean value is produced as output.
The security (integrity/authenticity) of a verifiable credential signed by a digital signature algorithm is dependent on a number of factors including:
In the following sections, we review these important points and direct the reader to additional information.
The ECDSA signature scheme has the EUF-CMA (existential unforgeability under chosen message attacks) security property. This property guarantees that any efficient adversary who has the public key pk of the signer and received an arbitrary number of signatures on messages of its choice (in an adaptive manner) cannot output a valid signature for a new message (except with negligible probability).
SUF-CMA (strong unforgeability under chosen message attacks) is a stronger notion than EUF-CMA. It guarantees that for any efficient adversary who has the public key pk of the signer and received an arbitrary number of signatures on messages of its choice, it cannot output a new valid signature pair for a new message nor a new signature for an old message (except with negligible probability). ECDSA signature scheme does not have the SUF-CMA property, while other schemes such as EdDSA [[FIPS-186-5]] do.
Per [[NIST-SP-800-57-Part-1]] in the absence of large scale quantum computers a security strength level of 128 bits requires a key size of approximately 256 bits while a security strength level of 192 bits requires a key size of 384 bits. [[NIST-SP-800-186]] recommendations includes curves P-256 and P-384 at these respective security strength levels.
The ECDSA algorithm as detailed in [[FIPS-186-5]] states: "A new secret random number k, 0 < k < n, shall be generated prior to the generation of each digital signature for use during the signature generation process." The failure to properly generate this k value has lead to some highly publicized integrity breaches in widely deployed systems. To counter this problem, a hash-based method of determining the secret number k, called Deterministic ECDSA, is given in [[FIPS-186-5]] and [[RFC6979]]. Verification of a ECDSA signature is independent of the method of generating k. Hence it is generally recommended to use Deterministic ECDSA unless other requirements dictate otherwise.
The security of the ECDSA algorithm is dependent on the quality and protection of its private signing key. Guidance in the management of cryptographic keys is a large subject and the reader is referred to [[NIST-SP-800-57-Part-1]] for more extensive recommendations and discussion. As strongly recommended in both [[FIPS-186-5]] and [[NIST-SP-800-57-Part-1]], an ECDSA private signing key is not to be used for any other purpose than ECDSA signatures.
ECDSA private signing keys and public verification keys are strongly advised to have limited cryptoperiods [[NIST-SP-800-57-Part-1]], where a cryptoperiod is "the time span during which a specific key is authorized for use by legitimate entities or the keys for a given system will remain in effect." [[NIST-SP-800-57-Part-1]] gives extensive guidance on cryptoperiods for different key types under different situations and generally recommends a 1-3 year cryptoperiod for a private signing key.
To deal with potential private key compromises, [[NIST-SP-800-57-Part-1]] gives recommendations for protective measures, harm reduction, and revocation. Although we have been emphasizing the security of the private signing key, assurance of public key validity is highly recommended on all public keys before using them, per [[NIST-SP-800-57-Part-1]].
Ensuring that cryptographic suites are versioned and tightly scoped to a very small set of possible key types and signature schemes (ideally one key type and size and one signature output type) is a design goal for most Data Integrity cryptographic suites. Historically, this has been done by defining both the key type and the cryptographic suite that uses the key type in the same specification. The downside of doing so, however, is that there might be a proliferation of different key types in multikey that result in different cryptosuites defining the same key material differently. For example, one cryptosuite might use compressed Curve P-256 keys while another uses uncompressed values. If that occurs, it will harm interoperability. It will be important in the coming months to years to ensure that this does not happen by fully defining the multikey format in a separate specification so cryptosuite specifications, such as this one, can refer to the multikey specification, thus reducing the chances of multikey type proliferation and improving the chances of maximum interoperability for the multikey format.
The following section describes privacy considerations that developers implementing this specification should be aware of in order to avoid violating privacy assumptions.
This cryptography suite does not provide for selective disclosure or unlinkability. If signatures are re-used, they can be used as correlatable data.
All test vectors are produced using Deterministic ECDSA. The implementation was validated against the test vectors in [[RFC6979]].
The group is debating the names used for the cryptosuite identifiers in VC Data Integrity issue #38. Cryptosuite identifiers might change in the future.
The signer needs to generate a private/public key pair with the private key used
for signing and the public key made available for verification. The
[[MULTIBASE]]/[[MULTICODEC]] representation for the public key, p256-pub,
and the representation for the private key, p256-priv, are shown below.
Signing begins with a credential without an attached proof, which is converted to canonical form, which is then hashed, as shown in the following three examples.
The next step is to take the proof options document, convert it to canonical form, and obtain its hash, as shown in the next three examples.
Finally, we concatenate the hash of the proof options followed by the hash of the credential without proof, use the private key with the combined hash to compute the ECDSA signature, and then base58-btc encode the signature.
Assemble the signed credential with the following two steps:
proofValue field with the previously computed base58-btc
value to the proof options document.
proof field of the credential to the augmented proof
option document.
The signer needs to generate a private/public key pair with the private key used
for signing and the public key made available for verification. The
[[MULTIBASE]]/[[MULTICODEC]] representation for the public key, p384-pub,
and the representation for the private key, p384-priv, are shown below.
Signing begins with a credential without an attached proof, which is converted to canonical form, and then hashed, as shown in the following three examples.
The next step is to take the proof options document, convert it to canonical form, and obtain its hash, as shown in the next three examples.
Finally, we concatenate the hash of the proof options followed by the hash of the credential without proof, use the private key with the combined hash to compute the ECDSA signature, and then base58-btc encode the signature.
Assemble the signed credential with the following two steps:
proofValue field with the previously computed base58-btc
value to the proof options document.
proof field of the credential to the augmented proof
option document.
The signer needs to generate a private/public key pair with the private key used
for signing and the public key made available for verification. The
[[MULTIBASE]]/[[MULTICODEC]] representation for the public key, p256-pub,
and the representation for the private key, p256-priv, are shown below.
Signing begins with a credential without an attached proof, which is converted to canonical form, which is then hashed, as shown in the following three examples.
The next step is to take the proof options document, convert it to canonical form, and obtain its hash, as shown in the next three examples.
Finally, we concatenate the hash of the proof options followed by the hash of the credential without proof, use the private key with the combined hash to compute the ECDSA signature, and then base58-btc encode the signature.
Assemble the signed credential with the following two steps:
proofValue field with the previously computed base58-btc
value to the proof options document.
proof field of the credential to the augmented proof
option document.
The signer needs to generate a private/public key pair with the private key used
for signing and the public key made available for verification. The
[[MULTIBASE]]/[[MULTICODEC]] representation for the public key, p384-pub,
and the representation for the private key, p384-priv, are shown below.
Signing begins with a credential without an attached proof, which is converted to canonical form, which is then hashed, as shown in the following three examples.
The next step is to take the proof options document, convert it to canonical form, and obtain its hash, as shown in the next three examples.
Finally, we concatenate the hash of the proof options followed by the hash of the credential without proof, use the private key with the combined hash to compute the ECDSA signature, and then base58-btc encode the signature.
Assemble the signed credential with the following two steps:
proofValue field with the previously computed base58-btc
value to the proof options document.
proof field of the credential to the augmented proof
option document.