Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

slip-0022: Add algorithm field. #816

Merged
merged 2 commits into from
Dec 4, 2019
Merged

slip-0022: Add algorithm field. #816

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
76daffa
slip-0022: Add algorithm field.
andrewkozlik Nov 12, 2019
1c0f6c9
slip-0022: Clarify useSignCount field for U2F.
andrewkozlik Nov 20, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 10 additions & 3 deletions slip-0022.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,11 @@ userName | 4 | Text string (CBOR major type 3). | Optional.
userDisplayName | 5 | Text string (CBOR major type 3). | Optional. | User account display name. The "displayName" member of the user parameter from the authenticatorMakeCredential request. In case of U2F the user may be prompted to enter a custom display name during registration.
creationTime | 6 | Unsigned integer (CBOR major type 0). | Required for FIDO2. | Any value which allows credentials to be sorted by the time of their creation, such as the UNIX timestamp or the value of an incremental counter at the moment of creation.
hmacSecret | 7 | Boolean (CBOR simple value 20 or 21). | Optional. False by default. | Indicates whether the credential was created with the hmac-secret extension set to true.
useSignCount | 8 | Boolean (CBOR simple value 20 or 21). | Optional. False by default. | If false, all operations with the credential must use zero as the signature counter value. If true, the credential must use a signature counter which is incremented for each successful authenticatorGetAssertion operation.
useSignCount | 8 | Boolean (CBOR simple value 20 or 21). | Optional. False by default for FIDO2. Absent for U2F. | If false, all operations with the credential must use zero as the signature counter value. If true, the credential must use a signature counter which is incremented for each successful authenticatorGetAssertion operation.
algorithm | 9 | Integer (CBOR major type 0 or 1) | Required if the "curve" field is present, otherwise optional. | The COSE identifier of the algorithm to be used for generating assertion signatures, as specified in the IANA COSE Algorithms Registry [IANA-COSE-ALGS-REG](https://www.iana.org/assignments/cose/cose.xhtml#algorithms).
curve | 10 | Integer (CBOR major type 0 or 1) | Required if the "algorithm" field specifies an elliptic curve signature algorithm. | The COSE identifier of the elliptic curve to be used for generating assertion signatures, as specified in the IANA COSE Elliptic Curves Registry [IANA-COSE-EC-REG](https://www.iana.org/assignments/cose/cose.xhtml#elliptic-curves).

If the "algorithm" field is not present, then the algorithm defaults to ES256 (-7) and the curve defaults to P-256 (1).

Credential data MUST be encoded using the CTAP2 canonical CBOR encoding form as specified in [Section 6](https://fidoalliance.org/specs/fido-v2.0-ps-20190130/fido-client-to-authenticator-protocol-v2.0-ps-20190130.html#message-encoding) of the FIDO Client to Authenticator Protocol (CTAP) v2.0.

Expand Down Expand Up @@ -99,7 +103,7 @@ where *version* is the first four bytes of the credential ID, for example "`\xf1

## Derivation of the credential key pair

The NIST P-256 credential key pair is derived from a master secret and the version and authentication tag of the credential ID using the [SLIP-0010](https://github.com/satoshilabs/slips/blob/master/slip-0010.md) key derivation scheme. The key path is computed from the authentication tag by splitting it into four 4-byte values A, B, C and D which are interpreted as 32-bit integers in big-endian byte order. The highest bit in each integer is set and the key path is:
The credential key pair used for generating assertion signatures is derived from a master secret and from the version and authentication tag of the credential ID using the [SLIP-0010](https://github.com/satoshilabs/slips/blob/master/slip-0010.md) key derivation scheme. The key path is computed from the authentication tag by splitting it into four 4-byte values A, B, C and D which are interpreted as 32-bit integers in big-endian byte order. The highest bit in each integer is set and the key path is:

```
m/10022'/version'/A'/B'/C'/D'
Expand All @@ -119,7 +123,9 @@ where *version* is the first four bytes of the credential ID.

## Signature counter

The purpose of the signature counter is to aid relying parties in detecting cloned authenticators. Hierarchical deterministic wallets use a master secret, which can be backed-up and used for device recovery or legitimately used to create a clone of the device. Implementation of a signature counter impedes these use cases. Fortunately, FIDO2 allows authenticators to choose whether a credential will or will not use a signature counter. In the latter case the value of the signature counter remains constant at zero in all authenticatorMakeCredential responses and authenticatorGetAssertion responses. It is therefore recommended that authenticators do not create FIDO2 credentials with useSignCount true, unless required by the relying party. This does not apply to U2F key handles, since U2F requires the implementation of a signature counter.
The purpose of the signature counter is to aid relying parties in detecting cloned authenticators. Hierarchical deterministic wallets use a master secret, which can be backed-up and used for device recovery or legitimately used to create a clone of the device. Implementation of a signature counter impedes these use cases. Fortunately, FIDO2 allows authenticators to choose whether a credential will or will not use a signature counter. In the latter case the value of the signature counter remains constant at zero in all authenticatorMakeCredential responses and authenticatorGetAssertion responses. It is therefore recommended that authenticators do not create FIDO2 credentials with the "useSignCount" field set to true, unless required by the relying party.

The above does not apply to U2F key handles, because the U2F protocol requires the implementation of a signature counter. In case of U2F key handles the "useSignCount" field MUST NOT be present.

## Example

Expand Down Expand Up @@ -186,6 +192,7 @@ The rationale behind using the authentication tag for the SLIP-0010 key path is

* [Web Authentication](https://www.w3.org/TR/webauthn/): An API for accessing Public Key Credentials Level 1, W3C Recommendation, 4 March 2019
* [FIDO Client to Authenticator Protocol (CTAP) v2.0](https://fidoalliance.org/specs/fido-v2.0-ps-20190130/fido-client-to-authenticator-protocol-v2.0-ps-20190130.html#sctn-hmac-secret-extension), Proposed Standard, January 30, 2019
* [IANA-COSE-REG](https://www.iana.org/assignments/cose/cose.xhtml): IANA CBOR Object Signing and Encryption (COSE) Registries.
* [RFC 7049](https://tools.ietf.org/html/rfc7049): Concise Binary Object Representation (CBOR)
* [SLIP-0010](https://github.com/satoshilabs/slips/blob/master/slip-0010.md): Universal private key derivation from master private key
* [SLIP-0021](https://github.com/satoshilabs/slips/blob/master/slip-0021.md): Hierarchical derivation of symmetric keys