Copyright © 2022 the Contributors to the ECDSA Cryptosuite v2019 Specification, published by the Credentials Community Group under the W3C Community Final Specification Agreement (FSA). A human-readable summary is available.
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). The approach is accepted by the U.S. National Institute of Standards and meets U.S. Federal Information Processing requirements when using cryptography to secure digital information.
This specification was published by the Credentials Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Final Specification Agreement (FSA) other conditions apply. Learn more about W3C Community and Business Groups.
This is an experimental specification and is undergoing regular revisions. It is not fit for production deployment.
If you wish to make comments regarding this document, please send them to public-credentials@w3.org (subscribe, archives).
This specification describes the EcdsaSecp384r1Signature and EcdsaSecp256r1Signature created in 2019 for the Data Integrity [DATA-INTEGRITY] specification. It uses the RDF Dataset Canonicalization Algorithm [RDF-DATASET-CANONICALIZATION] 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-4] as the signature algorithm, or SHA-384 [RFC6234] as the message digest algorithm and ECDSA with Curve P-384 defined in [FIPS-186-4] as the signature algorithm.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key word MUST in this document is to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
The following terms are used throughout this document:
This specification defines a data model for a number of key formats and signature formats.
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 extensbility mechanism and registry for new values as
they are added to the Multicodec Registry.
The following two key formats are defined by this specification:
A Curve P-256 compressed public key as defined in [FIPS-186-4]. The key MUST
contain a type set to EcdsaSecp256r1VerificationKey2019, controller, and
publicKeyMultibase value as defined by this specification.
A Curve P-384 compressed public key. The key MUST contain a type set to
EcdsaSecp384r1VerificationKey2019, controller, and publicKeyMultibase
value as defined by this specification.
An encoded Curve P-384 public key:
{
"@context": ["https://w3id.org/security/suites/ecdsa-2019/v1"],
"id": "did:example:123456789abcdefghi#keys-1",
"type": "EcdsaSecp384r1VerificationKey2019",
"controller": "did:example:123456789abcdefghi",
"publicKeyMultibase" : "zsJV1eTDACogBS8FMj5vXSa51g1CY1y88DR2DGDwTsMTotTG
ELVH1XTEsFP8ok9q22ssAaqHN5fMgm1kweTABZZNRSc"
}The pattern that Data Integrity Verification Keys use presently leads to an proliferation in key types and JSON-LD Contexts. This proliferation can be avoided without any loss of the single-field precision benefits of a multibase-encoded multicodec public key. The only downside for the approach demonstrated below is the loss of human-readable key type information. It could be argued that developers shouldn't be provided such affordances to ensure that they do not meddle with the values. Software libraries would ensure that the multicodec header information matches the expected header based on the cryptosuite that is utilizing the key for verification. See the section on 2.2.3 Signature Format Examples for more information.
{
"@context": ["https://w3id.org/security/multikey/v1"],
"id": "did:example:123456789abcdefghi#keys-1",
"type": "MulticodecVerificationKey",
"controller": "did:example:123456789abcdefghi",
"publicKeyMultibase" : "zsJV1eTDACogBS8FMj5vXSa51g1CY1y88DR2DGDwTsMTotTG
ELVH1XTEsFP8ok9q22ssAaqHN5fMgm1kweTABZZNRSc"
}The signature suites listed in this specification MUST be used in conjunction with the signing and verification algorithms in the Data Integrity [DATA-INTEGRITY] specification. The following two signature formats are defined by this specification.
A document that complies with the Data Integrity specification has been signed
with EcdsaSecp256r1Signature2019 when it contains a proof value, and that
value contains a type set to EcdsaSecp256r1Signature2019, a proofPurpose,
verificationMethod, and proofValue, as is defined by this specification.
The suite consists of the following algorithms:
| Parameter | Value | Specification |
|---|---|---|
| canonicalizationAlgorithm | https://w3id.org/security#GCA2015 | [RDF-DATASET-CANONICALIZATION] |
| digestAlgorithm | https://www.iana.org/assignments/cose/cose.xhtml#SHA-256 | [RFC6234] |
| signatureAlgorithm | https://www.iana.org/assignments/cose/cose.xhtml#P-256 | [RFC8422] |
A document that complies with the Data Integrity specification has been signed
with EcdsaSecp384r1Signature2019 when it contains a proof value, and that
value contains a type set to EcdsaSecp384r1Signature2019, a proofPurpose,
verificationMethod, and proofValue, as is defined by this specification.
The suite consists of the following algorithms:
| Parameter | Value | Specification |
|---|---|---|
| canonicalizationAlgorithm | https://w3id.org/security#GCA2015 | [RDF-DATASET-CANONICALIZATION] |
| digestAlgorithm | https://www.iana.org/assignments/cose/cose.xhtml#SHA-384 | [RFC6234] |
| signatureAlgorithm | https://www.iana.org/assignments/cose/cose.xhtml#P-384 | [RFC8422] |
An data integrity digital signature using ECDSA with Curve P-384:
{
"@context": ["https://w3id.org/security/suites/ecdsa-2019/v1"],
"type": "EcdsaSecp384r1Signature2019",
"created": "2022-01-29T20:35:38Z",
"verificationMethod": "did:example:123456789abcdefghi#keys-1",
"proofPurpose": "assertionMethod",
"proofValue": "z2rb7doJxczUFBTdV5F5pehtbUXPDUgKVugZZ99jniVXCUpojJ9PqLYV
evMeB1gCyJ4HqpnTyQwaoRPWaD3afEZboXCBTdV5F5pehtbUXPDUgKVugUpoj"
}The pattern that Data Integrity Signatures use presently leads to an proliferation in signature types and JSON-LD Contexts. This proliferation can be avoided without any loss of the security characteristics of tightly binding a cryptography suite version to one or more acceptable public keys. See 2.1.3 Key Format Examples for more information on what the matching MulticodecVerificationKey format could look like. The following signature suites are currently being contemplated: Eddsa2022, NistEcdsa2022, KoblitzEcdsa2022, Pgp2022, GostDsa2022, Sm9Ibsa2022, and Jws2022.
{
"@context": ["https://w3id.org/security/data-integrity/v1"],
"type": "DataIntegritySignature",
"cryptosuite": "NistEcdsa2022",
"created": "2021-11-29T20:35:38Z",
"verificationMethod": "did:example:123456789abcdefghi#keys-1",
"proofPurpose": "assertionMethod",
"proofValue": "z2rb7doJxczUFBTdV5F5pehtbUXPDUgKVugZZ99jniVXCUpojJ9PqLYV
evMeB1gCyJ4HqpnTyQwaoRPWaD3afEZboXCBTdV5F5pehtbUXPDUgKVugUpoj"
}This signature suite uses ECDSA over Curve P-256 or Curve P-384 as described in [FIPS-186-4]. The steps to construct and verify the digital signature are defined below.
The digital signature algorithm takes tbs, a privateKey, and options as inputs and produces a signatureValue as output.
The digital signature algorithm defined Signature Verification Algorithm takes the value to be verified, tbv, the public key to the signature algorithm and returns a boolean value.
true,
otherwise return false.
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.