This specification describes the EcdsaSecp384r1Signature and EcdsaSecp256r1Signature created in 2019 for the Data Integrity specification.

This is an experimental specification and is undergoing regular revisions. It is not fit for production deployment.

Introduction

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.

Terminology

The following terms are used throughout this document:

signature suite
A specified set of cryptographic primitives typically consisting of a canonicalization algorithm, a message digest algorithm, and a signature algorithm that are bundled together by cryptographers for developers for the purposes of safety and convenience.
canonicalization algorithm
An algorithm that takes an input document that has more than one possible representation and always transforms it into a canonical form. This process is sometimes also called normalization.
message digest algorithm
An algorithm that takes an input message and produces a cryptographic output message that is often many orders of magnitude smaller than the input message. These algorithms are often 1) very fast, 2) non-reversible, 3) cause the output to change significantly when even one bit of the input message changes, and 4) make it infeasible to find two different inputs for the same output.
signature algorithm
An algorithm that takes an input message and produces an output value where the receiver of the message can mathematically verify that the message has not been modified in transit and came from someone possessing a particular secret.

Data Model

This specification defines a data model for a number of key formats and signature formats.

Key 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:

EcdsaSecp256r1VerificationKey2019

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.

EcdsaSecp384r1VerificationKey2019

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.

Key Format Examples

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 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"
}
          

Signature Formats

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.

EcdsaSecp256r1Signature2019

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]]

EcdsaSecp384r1Signature2019

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]]

Signature Format Examples

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 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"
}
      

Algorithms

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.

Modifications to Signature Algorithm

The digital signature algorithm takes tbs, a privateKey, and options as inputs and produces a signatureValue as output.

  1. Take tbs, which is the cryptographic hash of the data to be signed, a set of raw privateKey bytes, and an options dictionary as input to the signature suite.
  2. Perform the digital signature on tbs using the ECDSA digital signature algorithm using the requested curve (either Curve P-256 or P-384), as defined in [[FIPS-186-4]] and store the result as signatureValue.
  3. Update signatureValue by multibase-encoding the value using the the base58btc encoding.

Modifications to Signature Verification Algorithm

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.

  1. Multibase decode tbv using the base58btc alphabet and store the result in rawSignature.
  2. Take rawSignature and perform the digital signature verification algorithm associated with the provided public key as specified in [[FIPS-186-4]]. If the result is a valid signature, return true, otherwise return false.

Security Considerations

The following section describes security considerations that developers implementing this specification should be aware of in order to create secure software.

Split Key Formats From Cryptosuites

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.

TODO: We need to add a complete list of security considerations.