This specification describes a Data Integrity Cryptosuite for use when generating a digital signature using the Elliptic Curve Digital Signature Algorithm (ECDSA) based on the Standards for Efficient Cryptography over prime fields using a verifiably random Elliptic Curve (secpr1).
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 secpr1 ECDSA signatures in conformance with the Data Integrity [[VC-DATA-INTEGRITY]] specification. The approach is accepted by the U.S. National Institute of Standards in the latest FIPS 186-5 publication and meets U.S. Federal Information Processing requirements when using cryptography to secure digital information. It 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 defined in [[FIPS-186-5]] as the signature algorithm, or SHA-384 [[RFC6234]] as the message digest algorithm and ECDSA with Curve P-384 defined in [[FIPS-186-5]] as the signature algorithm.
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 secpr1 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 secpr1 (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 secpr1 (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) based on the Standards for Efficient Cryptography over prime fields using a verifiably random Elliptic Curve (secpr1).
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 .
The required inputs to this algorithm are a transformed data document (transformedDocument) and proof configuration (proofConfig). 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 following section describes security considerations that developers implementing this specification should be aware of in order to create secure software.
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.