This specification describes the Ecdsa Secp256k1 Signature created in 2019 for the Linked Data Signatures specification.

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

Introduction

This specification describes the Ecdsa Secp256k1 Signature created in 2019 for the Linked Data Signatures [[LD-SIGNATURES]] specification. It uses the RDF Dataset CANONICALIZATION Algorithm [[RDF-DATASET-CANONICALIZATION]] to transform the input document into its canonical form. It uses SHA-256 [[RFC6234]] as the message digest algorithm and ES256K JWS with Unencoded Payload Option defined in [[rfc7797]] as the signature algorithm.

Terminology

The following terms are used to describe concepts involved in the generation and verification of the Linked Data Signature 2019 signature suite.

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

Linked Data Signature Terms

The following terms are used to describe concepts involved in the generation and verification of signatures according to EcdsaSecp256k1Signature2019.

EcdsaSecp256k1Signature2019
A JSON-LD Document has been signed with EcdsaSecp256k1Signature2019, when it contains a proof field, and that proof field contains a jws, as is defined by this spec.
EcdsaSecp256k1VerificationKey2019
A secp256k1 public key. If the key is embedded in a controller with property name publicKeyJwk, the key must be a valid JWK. If the key is embeded as publicKeyHex, it must be a compressed public key, and must be converted to JWK before being used to verify signatures according to JWS.

Key Format

Examples

JWK encoded public key example: 

{
  "@context": ["https://w3id.org/security/v1"],
  "id": "did:example:123456789abcdefghi#keys-1",
  "type": "EcdsaSecp256k1VerificationKey2019",
  "controller": "did:example:123456789abcdefghi",
  "expires": "2017-02-08T16:02:20Z",
  "publicKeyJwk" : {
    "crv": "secp256k1",
    "kid": "JUvpllMEYUZ2joO59UNui_XYDqxVqiFLLAJ8klWuPBw",
    "kty": "EC",
    "x": "dWCvM4fTdeM0KmloF57zxtBPXTOythHPMm1HCLrdd3A",
    "y": "36uMVGM7hnw-N6GnjFcihWE3SkrhMLzzLCdPMXPEXlA",
  }
}

Note: The publicKeyJwk property contains a key in JWK format.

Hex encoded public key example: 

        {
          "@context": ["https://w3id.org/security/v1"],
          "id": "did:example:123456789abcdefghi#keys-1",
          "type": "EcdsaSecp256k1VerificationKey2019",
          "controller": "did:example:123456789abcdefghi",
          "expires": "2017-02-08T16:02:20Z",
          "publicKeyHex" : "034ee0f670fc96bb75e8b89c068a1665007a41c98513d6a911b6137e2d16f1d300"
        }

Note: The publicKeyHex MUST be converted to publicKeyJwk before it can be used to verify JWS.

Note: The publicKeyHex property contains a hex encoded compressed secp256k1 public key.

Signature Format

The 2019 Ecdsa Secp256k1 Signature signature suite MUST be used in conjunction with the signing and verification algorithms in the Linked Data Signatures [[LD-SIGNATURES]] specification. The suite consists of the following algorithms:

Parameter Value Specification
canonicalizationAlgorithm https://w3id.org/security#GCA2015 [[RDF-DATASET-CANONICALIZATION]]
digestAlgorithm https://www.ietf.org/assignments/jwa-parameters#SHA256 [[RFC6234]]
signatureAlgorithm ES256K [[rfc6979]]

Modification to Algorithms

This signature suite uses ECDSA over secp256k1 as described in [[rfc6979]]. The signature algorithm relies on JWK encoded keys, and this flexibility supports integration with JOSE. The steps to construct and verify the digital signature are defined below.

Modifications to Signature Algorithm

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

  1. Take tbs, which is the data to be signed, an private key and options dictionary as input to the signature suite.
  2. Perform the sign digital signature algorithm specified of [[rfc7797]] and return the result encoded as jws.
  3. The jws will contain ".." per [[rfc7797]]: WpQlDT-K5bSPQwFkEKszo0XE1esubvol3K6UMe_....

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. Take tbv and perform the Sign digital signature verification algorithm specified in ES26K JOSE DRAFT. 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.

TODO: We need to add a complete list of security considerations.
  1. This Signature Suite relies on the security and assumptions made by ECDSA over secp256k1. We assume specifcally that sign and verify are implemented safely.

Examples

A simple example: 

{
  "@context": "https://w3id.org/security/v2",
  "http://schema.org/action": "AuthenticateMe",
  "proof": {
    "challenge": "abc",
    "created": "2019-01-16T20:13:10Z",
    "domain": "example.com",
    "proofPurpose": "authentication",
    "verificationMethod": "https://example.com/i/alice/keys/2",
    "type": "EcdsaSecp256k1Signature2019",
    "jws": "eyJhbGciOiJFUzI1NksiLCJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdfQ..QgbRWT8w1LJet_KFofNfz_TVs27z4pwdPwUHhXYUaFlKicBQp6U1H5Kx-mST6uFvIyOqrYTJifDijZbtAfi0MA"
  }
}

An example using DIDs: 

        {
          "@context": "https://w3id.org/security/v2",
          "http://schema.org/action": "AuthenticateMe",
          "proof": {
            "challenge": "abc",
            "created": "2019-01-16T20:13:10Z",
            "domain": "example.com",
            "proofPurpose": "authentication",
            "verificationMethod": "did:example:123#kid=JUvpllMEYUZ2joO59UNui_XYDqxVqiFLLAJ8klWuPBw",
            "type": "EcdsaSecp256k1Signature2019",
            "jws": "eyJhbGciOiJFUzI1NksiLCJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdfQ..QgbRWT8w1LJet_KFofNfz_TVs27z4pwdPwUHhXYUaFlKicBQp6U1H5Kx-mST6uFvIyOqrYTJifDijZbtAfi0MA"
          }
        }