(WebPKI.org Support)

Signature Support

The CBOR library contains support for creating and validating signatures using a specific scheme called "CBOR Signature Format" (CSF).

Note that unlike COSE [RFC 8152], CSF leverages deterministic serialization, enabling constructs like the following:

{
  1: {
    1: "Space Shop",
    2: "435.00",
    3: "USD"
  },
  2: "spaceshop.com",
  3: "FR7630002111110020050014382",
  4: "https://banknet2.org",
  5: "05768401",
  6: "2022-09-29T09:34:08-05:00",
  7: {
    1: 38.8882,
    2: 77.0199
  },

/ Enveloped signature object /
-1: {

/ Signature algorithm = ES256 /
1: -7,

/ Public key descriptor in COSE format /
4: {

/ kty = EC /
1: 2,

/ crv = P-256 /
-1: 1,

/ x /
-2: h'e812b1a6dcbc708f9ec43cc2921fa0a14e9d5eadcc6dc63471dd4b680c6236b5',

      / y /
      -3: h'9826dcbd4ce6e388f72edd9be413f2425a10f75b5fd83d95fa0cde53159a51d8'
    },

    / Signature value /
    6: h'5f21112b9f5c1a93743409596421e673f88e59cf34610d53a7cd00f4017327c8f603ea7344a9286db26c52c2a661dff6e4fabc0f2384fe7d1de6c0a23a3f5c21'
  }
}

The same object expressed as hex-encoded CBOR:

a801a3016a53706163652053686f7002663433352e30300363555344026d737061636573686f702e636f6d03781b465237363330303032313131313130303230303530303134333832047468747470733a2f2f62616e6b6e6574322e6f726705683035373638343031067819323032322d30392d32395430393a33343a30382d30353a303007a201fb404371b089a0275202fb405341460aa64c3020a3012604a401022001215820e812b1a6dcbc708f9ec43cc2921fa0a14e9d5eadcc6dc63471dd4b680c6236b52258209826dcbd4ce6e388f72edd9be413f2425a10f75b5fd83d95fa0cde53159a51d80658405f21112b9f5c1a93743409596421e673f88e59cf34610d53a7cd00f4017327c8f603ea7344a9286db26c52c2a661dff6e4fabc0f2384fe7d1de6c0a23a3f5c21

Explanation: Labels 1-7 represent application data (which must be supplied in a CBOR map), while the application-specific label -1 holds an associated enveloped signature.

Note that the application-specific labels (including the one holding the signature object), may be of any CBOR type. The only requirement is that they are unique.

Signatures must for compatibility with CSF, be provided as a CBOR map having a fixed set of labels according to the following table:

Label	Name	Argument	Function
`1`	`algorithm`	`integer`	Signature algorithm using COSE identifiers.
`3`	`keyId`	"Any"	Optional key identifier using any valid CBOR object. Note that `keyId` must not be used together with `publicKey` or `certificatePath`. A compliant `keyId` must uniquely identify a specific signature key.
`4`	`publicKey`	`map`	Optional public key in COSE format. Note that ECDSA public keys must be supplied with a value parameter for the y-coordinate as well.
`5`	`certificatePath`	`array`	Optional certificate path supplied as an array of `byte string` objects holding X.509 certificates in DER format, where the first object must be the signature certificate. Signature objects must not contain both `certificatePath` and `publicKey` elements.
`6`	`signature`	`byte string`	Signature value.

CSF signatures are validated by running the signature validation algorithm over the CBOR binary representation of the map holding the application data including the enveloped signature object, with the highlighted signature (label 6) and its associated argument as the sole exception. Note that the length of the signature object map must be updated (to reflect the removal of an element) during validation.

The sample was signed using the following private key (here in JWK format):

{
  "kty": "EC",
  "crv": "P-256",
  "x": "6BKxpty8cI-exDzCkh-goU6dXq3MbcY0cd1LaAxiNrU",
  "y": "mCbcvUzm44j3Lt2b5BPyQloQ91tf2D2V-gzeUxWaUdg",
  "d": "6XxMFXhcYT5QN9w5TIg2aSKsbcj-pj4BnZkK7ZOt4B8"
}

Tagged and Custom Signature Data

The CSF container can be enhanced through a couple of options described in crypto options. Such options are included in the data to be signed.

Signature Algorithms

Currently supported signature algorithms:

Name	Identifier	Compatibility
`HS256`	5	COSE, JOSE
`HS384`	6	COSE, JOSE
`HS512`	7	COSE, JOSE
`Ed25519`	-8	FIDO, PKIX [1]
`Ed448`	-9	PKIX [2]
`ES256`	-7	COSE, JOSE
`ES384`	-35	COSE, JOSE
`ES512`	-36	COSE, JOSE
`PS256`	-37	COSE, JOSE
`PS384`	-38	COSE, JOSE
`PS512`	-39	COSE, JOSE
`RS256`	-257	COSE, JOSE
`RS384`	-258	COSE, JOSE
`RS512`	-259	COSE, JOSE

[1] Unfortunately, different standards groups did not in due time realize that existing cryptographic APIs only rarely accept "EdDSA" as a valid signature algorithm. In current FIDO alliance specifications the COSE EdDSA algorithm identifier has therefore been redefined to rather mean EdDSA with an Ed25519 key which is also what CSF follows. PKIX' RFC 8410 makes the same distinction.

[2] CSF extends the scheme used for Ed25519 to Ed448 as well.

Test Vectors

An extensive set of test vectors is currently available at: https://github.com/cyberphone/openkeystore/tree/master/testdata/cbor-signatures .

Use CBORPrinter to list contents in a human.friendly way.