Signature Support
The CBOR library contains support forcreating
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:
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.