Copyright © 2013-2017 FIDO Alliance All Rights Reserved.
UAF Authenticators may take different forms. Implementations may range from a secure application running inside tamper-resistant hardware to software-only solutions on consumer devices.
This document defines normative aspects of UAF Authenticators and offers security and implementation guidelines for authenticator implementors.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current FIDO Alliance publications and the latest revision of this technical report can be found in the FIDO Alliance specifications index at https://www.fidoalliance.org/specifications/.
This document was published by the FIDO Alliance as a Implementation Draft. This document is intended to become a FIDO Alliance Proposed Standard. If you wish to make comments regarding this document, please Contact Us. All comments are welcome.
This Implementation Draft Specification has been prapared by FIDO Alliance, Inc. Permission is hereby granted to use the Specification solely for the purpose of implementing the Specification. No rights are granted to prepare derivative works of this Specification. Entities seeking permission to reproduce portions of this Specification for other uses must contact the FIDO Alliance to determine whether an appropriate license for such use is available.
Implementation of certain elements of this Specification may require licenses under third party intellectual property rights, including without limitation, patent rights. The FIDO Alliance, Inc. and its Members and any other contributors to the Specification are not, and shall not be held, responsible in any manner for identifying or failing to identify any or all such third party intellectual property rights.
THIS FIDO ALLIANCE SPECIFICATION IS PROVIDED “AS IS” AND WITHOUT ANY WARRANTY OF ANY KIND, INCLUDING, WITHOUT LIMITATION, ANY EXPRESS OR IMPLIED WARRANTY OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Type names, attribute names and element names are written as
code.
String literals are enclosed in "", e.g. "UAF-TLV".
In formulas we use "|" to denote byte wise concatenation operations.
UAF specific terminology used in this document is defined in [FIDOGlossary].
All diagrams, examples, notes in this specification are non-normative.
Unless otherwise specified all data described in this document MUST be encoded in little-endian format.
All TLV structures can be parsed using a "recursive-descent" parsing approach. In some cases multiple occurrences of a single tag MAY be allowed within a structure, in which case all values MUST be preserved.
All fields in TLV structures are mandatory, unless explicitly mentioned as otherwise.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in [RFC2119].
This section is non-normative.
This document specifies low-level functionality which UAF Authenticators should implement in order to support the UAF protocol. It has the following goals:
UAFV1TLV assertion scheme-specific structures which will be parsed by a FIDO Server
The UAF Protocol supports various assertion schemes.
Commands and structures defined in this document assume that
an authenticator supports the UAFV1TLV assertion scheme.
Authenticators implementing a different assertion scheme do
not have to follow requirements specified
in this document.
The overall architecture of the UAF protocol and its various operations is described in [UAFProtocol]. The following simplified architecture diagram illustrates the interactions and actors this document is concerned with:
This section is non-normative.
The UAF Authenticator is an authentication component that meets the UAF protocol requirements as described in [UAFProtocol]. The main functions to be provided by UAF Authenticators are:
Some examples of UAF Authenticators:
There are four types of authenticators defined in this document. These definitions are not normative (unless otherwise stated) and are provided merely for simplifying some of the descriptions.
The following is the rationale for considering only these 4 types of authenticators:
Vendors, however, are not limited to these constraints. For example a bound authenticator which has internal storage for storing key handles is possible. Vendors are free to design and implement such authenticators as long as their design follows the normative requirements described in this document.
Throughout the document there will be special conditions applying to these types of authenticators.
In some deployments, the combination of ASM and a bound authenticator can act as a roaming authenticator (for example when an ASM with an embedded authenticator on a mobile device acts as a roaming authenticator for another device). When this happens such an authenticator MUST follow the requirements applying to bound authenticators within the boundary of the system the authenticator is bound to, and follow the requirements that apply to roaming authenticators in any other system it connects to externally.
Conforming authenticators MUST implement at least one attestation type defined in [UAFRegistry], as well as one authentication algorithm and one key format listed in [FIDORegistry].
As stated above, the bound authenticator does not store key handles and roaming authenticators do store them. In the example above the ASM would store the key handles of the bound authenticator and hence meets these assumptions.
This section is normative.
In this document UAF Authenticators use "Tag-Length-Value" (TLV) format to communicate with the outside world. All requests and response data MUST be encoded as TLVs.
Commands and existing predefined TLV tags can be extended by appending other TLV tags (custom or predefined).
Refer to [UAFRegistry] for information about predefined TLV tags.
TLV formatted data has the following simple structure:
| 2 bytes | 2 bytes | Length bytes |
| Tag | Length in bytes | Data |
All lengths are in bytes. e.g. a UINT32[4] will have length 16.
Although 2 bytes are allotted for the tag, only the first 14 bits (values up to 0x3FFF) should be used to accommodate the limitations of some hardware platforms.
Arrays are implicit. The description of some structures indicates where multiple values are permitted, and in these cases, if same tag appears more than once, all values are signifanct and should be treated as an array.
For convenience in decoding TLV-formatted messages, all composite tags - those with values that must be parsed by recursive descent - have the 13th bit (0x1000) set.
A tag that has the 14th bit (0x2000) set indicates that it is critical and a receiver MUST abort processing the entire message if it cannot process that tag.
Since UAF Authenticators may have extremely constrained processing environments, an ASM MUST follow a normative ordering of structures when sending commands.
It is assumed that ASM and Server have sufficient resources to handle parsing tags in any order so structures send from authenticator MAY use tags in any order.
| Name | Value | Description |
|---|---|---|
| UAF_CMD_STATUS_OK | 0x00 | Success. |
| UAF_CMD_STATUS_ERR_UNKNOWN | 0x01 | An unknown error. |
| UAF_CMD_STATUS_ACCESS_DENIED | 0x02 | Access to this operation is denied. |
| UAF_CMD_STATUS_USER_NOT_ENROLLED | 0x03 | User is not enrolled with the authenticator and the authenticator cannot automatically trigger enrollment. |
| UAF_CMD_STATUS_CANNOT_RENDER_TRANSACTION_CONTENT | 0x04 | Transaction content cannot be rendered. |
| UAF_CMD_STATUS_USER_CANCELLED | 0x05 | User has cancelled the operation. |
| UAF_CMD_STATUS_CMD_NOT_SUPPORTED | 0x06 | Command not supported. |
| UAF_CMD_STATUS_ATTESTATION_NOT_SUPPORTED | 0x07 | Required attestation not supported. |
| UAF_CMD_STATUS_PARAMS_INVALID | 0x08 | The parameters for the command received by the authenticator are malformed/invalid. |
| UAF_CMD_STATUS_KEY_DISAPPEARED_PERMANENTLY | 0x09 | The UAuth key which is relevant for this command disappeared from the authenticator and cannot be restored. On some authenticators this error occurs when the user verification reference data set was modified (e.g. new fingerprint template added). |
| UAF_CMD_STATUS_TIMEOUT | 0x0a | The operation in the authenticator took longer than expected (due to technical issues) and it was finally aborted. |
| UAF_CMD_STATUS_USER_NOT_RESPONSIVE | 0x0e | The user took too long to follow an instruction, e.g. didn't swipe the finger within the accepted time. |
| UAF_CMD_STATUS_INSUFFICIENT_RESOURCES | 0x0f | Insufficient resources in the authenticator to perform the requested task. |
| UAF_CMD_STATUS_USER_LOCKOUT | 0x10 |
The operation failed because the user is locked out and the authenticator
cannot automatically trigger an action to change that.
Typically the user would have to enter an alternative
password (formally: undergo some other alternative user verification method) to re-enable the use
of the main user verification method.
Note Any method the user can use to (re-) enable the main user verification method is considered an alternative user verification method and must be properly declared as such. For example, if the user can enter an alternative password to re-enable the use of fingerprints or to add additional fingers, the authenticator obviously supports fingerprint or password based user verification. |
Table 4.4.1: UAF Authenticator Status Codes (0x00 - 0xFF)
This section is normative.
RawKeyHandle is a structure generated and parsed by the authenticator. Authenticators MAY define RawKeyHandle in different ways and the internal structure is relevant only to the specific authenticator implementation.
RawKeyHandle for a typical first-factor bound authenticator has the following structure.
| Depends on hashing algorithm (e.g. 32 bytes) |
Depends on key type. (e.g. 32 bytes) |
Username Size (1 byte) |
Max 128 bytes |
| KHAccessToken | UAuth.priv | Size | Username |
Table 5.1: RawKeyHandle Structure
First Factor authenticators MUST store Usernames in the authenticator and they MUST link the Username to the related key. This MAY be achieved by storing the Username inside the RawKeyHandle. Second Factor authenticators MUST NOT store the Username.
The ability to support Usernames is a key difference between first-, and second-factor authenticators.
The RawKeyHandle MUST be cryptographically wrapped before leaving the authenticator boundary since it typically contains sensitive information, e.g. the user authentication private key (UAuth.priv).
The structures defined in this section are created by UAF Authenticators and parsed by FIDO Servers.
Authenticators MUST generate these structures if they implement "UAFV1TLV" assertion scheme.
"UAFV1TLV" assertion scheme assumes that the authenticator has exclusive control over all data included inside TAG_UAFV1_KRD and TAG_UAFV1_SIGNED_DATA.
The nesting structure MUST be preserved, but the order of tags within a composite tag is not normative. FIDO Servers MUST be prepared to handle tags appearing in any order.
The following TLV structure is generated by the authenticator during processing of a Register command. It is then delivered to FIDO Server intact, and parsed by the server. The structure embeds a TAG_UAFV1_KRD tag which among other data contains the newly generated UAuth.pub.
If the authenticator wants to append custom data to TAG_UAFV1_KRD structure (and thus sign with Attestation Key) - this data MUST be included as TAG_EXTENSION_DATA in a TAG_EXTENSION object inside TAG_UAFV1_KRD.
If the authenticator wants to send additional data to FIDO Server without signing it - this data MUST be included as TAG_EXTENSION_DATA in a TAG_EXTENSION object inside TAG_UAFV1_REG_ASSERTION and not inside TAG_UAFV1_KRD.
Currently this document only specifies TAG_ATTESTATION_BASIC_FULL, TAG_ATTESTATION_BASIC_SURROGATE and TAG_ATTESTATION_ECDAA. In case if the authenticator is required to perform "Some_Other_Attestation" on TAG_UAFV1_KRD - it MUST use the TLV tag and content defined for "Some_Other_Attestation" (defined in [UAFRegistry]).
| TLV Structure | Description | |
|---|---|---|
| 1 | UINT16 Tag | TAG_UAFV1_REG_ASSERTION |
| 1.1 | UINT16 Length | Length of the structure |
| 1.2 | UINT16 Tag | TAG_UAFV1_KRD |
| 1.2.1 | UINT16 Length | Length of the structure |
| 1.2.2 | UINT16 Tag | TAG_AAID |
| 1.2.2.1 | UINT16 Length | Length of AAID |
| 1.2.2.2 | UINT8[] AAID | Authenticator Attestation ID |
| 1.2.3 | UINT16 Tag | TAG_ASSERTION_INFO |
| 1.2.3.1 | UINT16 Length | Length of Assertion Information |
| 1.2.3.2 | UINT16 AuthenticatorVersion | Vendor assigned authenticator version |
| 1.2.3.3 | UINT8 AuthenticationMode | For Registration this must be 0x01 indicating that the user has explicitly verified the action. |
| 1.2.3.4 | UINT16 SignatureAlgAndEncoding |
Signature Algorithm and Encoding of the attestation signature.
Refer to [FIDORegistry] for information on supported algorithms and their values. |
| 1.2.3.5 | UINT16 PublicKeyAlgAndEncoding |
Public Key algorithm and encoding of the newly generated Refer to [FIDORegistry] for information on supported algorithms and their values. |
| 1.2.4 | UINT16 Tag | TAG_FINAL_CHALLENGE_HASH |
| 1.2.4.1 | UINT16 Length | Final Challenge Hash length |
| 1.2.4.2 | UINT8[] FinalChallengeHash | (binary value of) Final Challenge Hash provided in the Command |
| 1.2.5 | UINT16 Tag | TAG_KEYID |
| 1.2.5.1 | UINT16 Length | Length of KeyID |
| 1.2.5.2 | UINT8[] KeyID | (binary value of) KeyID generated by Authenticator |
| 1.2.6 | UINT16 Tag | TAG_COUNTERS |
| 1.2.6.1 | UINT16 Length | Length of Counters |
| 1.2.6.2 | UINT32 SignCounter |
Signature Counter.
Indicates how many times this authenticator has performed signatures in the past. |
| 1.2.6.3 | UINT32 RegCounter |
Registration Counter.
Indicates how many times this authenticator has performed registrations in the past. |
| 1.2.7 | UINT16 Tag | TAG_PUB_KEY |
| 1.2.7.1 | UINT16 Length | Length of UAuth.pub |
| 1.2.7.2 | UINT8[] PublicKey | User authentication public key (UAuth.pub) newly generated by authenticator |
| 1.3 (choice 1) | UINT16 Tag | TAG_ATTESTATION_BASIC_FULL |
| 1.3.1 | UINT16 Length | Length of structure |
| 1.3.2 | UINT16 Tag | TAG_SIGNATURE |
| 1.3.2.1 | UINT16 Length | Length of signature |
| 1.3.2.2 | UINT8[] Signature |
Signature calculated with Basic Attestation Private
Key over TAG_UAFV1_KRD content.
The entire TAG_UAFV1_KRD content, including the tag and it's length field, MUST be included during signature computation. |
| 1.3.3 | UINT16 Tag | TAG_ATTESTATION_CERT (multiple occurrences possible)
Multiple occurrences must be ordered. The attestation certificate MUST occur first.
Each subsequent occurrence (if exists) MUST be the issuing certificate of
the previous occurrence.
The last occurence MUST be chained to one of the certificates included
in field |
| 1.3.3.1 | UINT16 Length | Length of Attestation Cert |
| 1.3.3.2 | UINT8[] Certificate | Single X.509 DER-encoded [ITU-X690-2008] Attestation Certificate or a single certificate from the attestation certificate chain (see description above). |
| 1.3 (choice 2) | UINT16 Tag | TAG_ATTESTATION_BASIC_SURROGATE |
| 1.3.1 | UINT16 Length | Length of structure |
| 1.3.2 | UINT16 Tag | TAG_SIGNATURE |
| 1.3.2.1 | UINT16 Length | Length of signature |
| 1.3.2.2 | UINT8[] Signature |
Signature calculated with newly generated UAuth.priv key over TAG_UAFV1_KRD content.
The entire TAG_UAFV1_KRD content, including the tag and it's length field, MUST be included during signature computation. |
| 1.3 (choice 3) | UINT16 Tag | TAG_ATTESTATION_ECDAA |
| 1.3.1 | UINT16 Length | Length of structure |
| 1.3.2 | UINT16 Tag | TAG_SIGNATURE |
| 1.3.2.1 | UINT16 Length | Length of signature |
| 1.3.2.2 | UINT8[] Signature | The binary ECDAA signature as specified in [FIDOEcdaaAlgorithm]. |
The following TLV structure is generated by an authenticator during processing of a Sign command. It is then delivered to FIDO Server intact and parsed by the server. The structure embeds a TAG_UAFV1_SIGNED_DATA tag.
If the authenticator wants to append custom data to TAG_UAFV1_SIGNED_DATA structure (and thus sign with Attestation Key) - this data MUST be included as an additional tag inside TAG_UAFV1_SIGNED_DATA.
If the authenticator wants to send additional data to FIDO Server without signing it - this data MUST be included as an additional tag inside TAG_UAFV1_AUTH_ASSERTION and not inside TAG_UAFV1_SIGNED_DATA.
| TLV Structure | Description | |
|---|---|---|
| 1 | UINT16 Tag | TAG_UAFV1_AUTH_ASSERTION |
| 1.1 | UINT16 Length | Length of the structure. |
| 1.2 | UINT16 Tag | TAG_UAFV1_SIGNED_DATA |
| 1.2.1 | UINT16 Length | Length of the structure. |
| 1.2.2 | UINT16 Tag | TAG_AAID |
| 1.2.2.1 | UINT16 Length | Length of AAID |
| 1.2.2.2 | UINT8[] AAID | Authenticator Attestation ID |
| 1.2.3 | UINT16 Tag | TAG_ASSERTION_INFO |
| 1.2.3.1 | UINT16 Length | Length of Assertion Information |
| 1.2.3.2 | UINT16 AuthenticatorVersion | Vendor assigned authenticator version. |
| 1.2.3.3 | UINT8 AuthenticationMode |
Authentication Mode indicating whether user
explicitly verified or not and indicating if there
is a transaction content or not.
|
| 1.2.3.4 | UINT16 SignatureAlgAndEncoding |
Signature algorithm and encoding format.
Refer to [FIDORegistry] for information on supported algorithms and their values. |
| 1.2.4 | UINT16 Tag | TAG_AUTHENTICATOR_NONCE |
| 1.2.4.1 | UINT16 Length | Length of authenticator Nonce - MUST be at least 8 bytes |
| 1.2.4.2 | UINT8[] AuthnrNonce | (binary value of) A nonce randomly generated by Authenticator |
| 1.2.5 | UINT16 Tag | TAG_FINAL_CHALLENGE_HASH |
| 1.2.5.1 | UINT16 Length | Length of Final Challenge Hash |
| 1.2.5.2 | UINT8[] FinalChallengeHash | (binary value of) Final Challenge Hash provided in the Command |
| 1.2.6 | UINT16 Tag | TAG_TRANSACTION_CONTENT_HASH |
| 1.2.6.1 | UINT16 Length | Length of Transaction Content Hash. This length is 0 if AuthenticationMode == 0x01, i.e. authentication, not transaction confirmation. |
| 1.2.6.2 | UINT8[] TCHash | (binary value of) Transaction Content Hash |
| 1.2.7 | UINT16 Tag | TAG_KEYID |
| 1.2.7.1 | UINT16 Length | Length of KeyID |
| 1.2.7.2 | UINT8[] KeyID | (binary value of) KeyID |
| 1.2.8 | UINT16 Tag | TAG_COUNTERS |
| 1.2.8.1 | UINT16 Length | Length of Counters |
| 1.2.8.2 | UINT32 SignCounter |
Signature Counter.
Indicates how many times this authenticator has performed signatures in the past. |
| 1.3 | UINT16 Tag | TAG_SIGNATURE |
| 1.3.1 | UINT16 Length | Length of Signature |
| 1.3.2 | UINT8[] Signature |
Signature calculated using UAuth.priv over
TAG_UAFV1_SIGNED_DATA structure.
The entire TAG_UAFV1_SIGNED_DATA content, including the tag and it's length field, MUST be included during signature computation. |
This specification doesn't specify how exactly user verification must be performed inside the authenticator. Verification is considered to be an authenticator, and vendor, specific operation.
This document provides an example on how the "vendor_specific_UserVerify" command (a command which
verifies the user using Authenticator's built-in technology) could be securely bound to
UAF Register and Sign commands. This binding is done through a concept called UserVerificationToken.
Such a binding allows decoupling "vendor_specific_UserVerify" and "UAF Register/Sign" commands
from each other.
Here is how it is defined:
UserVerificationToken back.
UserVerificationToken to it.
The authenticator verifies the validity of UserVerificationToken and
performs the FIDO operation if it is valid.
The concept of UserVerificationToken is non-normative. An authenticator might decide to implement this binding in a very different way. For example an authenticator vendor may decide to append a UAF Register request directly to their "vendor_specific_UserVerify" command and process both as a single command.
If UserVerificationToken binding is implemented, it should either meet one of the
following criteria or implement a mechanism providing similar, or better security:
UserVerificationToken must allow performing only a single UAF Register or UAF Sign operation.
UserVerificationToken must be time bound, and allow performing multiple UAF operations
within the specified time.
This section is non-normative.
UAF Authenticators which are designed to be interoperable with ASMs from different vendors MUST implement the command interface defined in this section. Examples of such authenticators:
UAF Authenticators which are tightly integrated with a custom ASM (typically bound authenticators) MAY implement a different command interface.
All UAF Authenticator commands and responses are semantically similar - they are all represented as TLV-encoded blobs. The first 2 bytes of each command is the command code. After receiving a command, the authenticator must parse the first TLV tag and figure out which command is being issued.
This command returns information about the connected authenticators. It may return 0 or more authenticators. Each
authenticator has an assigned authenticatorIndex which is used in other commands as an
authenticator reference.
| TLV Structure | Description | |
|---|---|---|
| 1 | UINT16 Tag | TAG_UAFV1_GETINFO_CMD |
| 1.1 | UINT16 Length | Entire Command Length - must be 0 for this command |
| TLV Structure | Description | |
|---|---|---|
| 1 | UINT16 Tag | TAG_UAFV1_GETINFO_CMD_RESPONSE |
| 1.1 | UINT16 Length | Response length |
| 1.2 | UINT16 Tag | TAG_STATUS_CODE |
| 1.2.1 | UINT16 Length | Status Code Length |
| 1.2.2 | UINT16 Value | Status Code returned by Authenticator |
| 1.3 | UINT16 Tag | TAG_API_VERSION |
| 1.3.1 | UINT16 Length | Length of API Version (must be 0x0001) |
| 1.3.2 | UINT8 Version | Authenticator API Version (must be 0x01). This version indicates the types of commands, and formatting associated with them, that are supported by the authenticator. |
| 1.4 | UINT16 Tag | TAG_AUTHENTICATOR_INFO (multiple occurrences possible) |
| 1.4.1 | UINT16 Length | Length of Authenticator Info |
| 1.4.2 | UINT16 Tag | TAG_AUTHENTICATOR_INDEX |
| 1.4.2.1 | UINT16 Length | Length of AuthenticatorIndex (must be 0x0001) |
| 1.4.2.2 | UINT8 AuthenticatorIndex | Authenticator Index |
| 1.4.3 | UINT16 Tag | TAG_AAID |
| 1.4.3.1 | UINT16 Length | Length of AAID |
| 1.4.3.2 | UINT8[] AAID | Vendor assigned AAID |
| 1.4.4 | UINT16 Tag | TAG_AUTHENTICATOR_METADATA |
| 1.4.4.1 | UINT16 Length | Length of Authenticator Metadata |
| 1.4.4.2 | UINT16 AuthenticatorType | Indicates whether the authenticator is bound or roaming, and whether
it is first-, or second-factor only.
The ASM must use this information to understand how to work with the authenticator.
Predefined values:
|
| 1.4.4.3 | UINT8 MaxKeyHandles | Indicates maximum number of key handles this authenticator can receive and process in a single command. This information will be used by the ASM when invoking SIGN command with multiple key handles. |
| 1.4.4.4 | UINT32 UserVerification | User Verification method (as defined in [FIDORegistry]) |
| 1.4.4.5 | UINT16 KeyProtection | Key Protection type (as defined in [FIDORegistry]). |
| 1.4.4.6 | UINT16 MatcherProtection | Matcher Protection type (as defined in [FIDORegistry]). |
| 1.4.4.7 | UINT16 TransactionConfirmationDisplay | Transaction Confirmation type (as defined in [FIDORegistry]).
Note
If Authenticator doesn't support Transaction Confirmation - this value must be set to 0.
|
| 1.4.4.8 | UINT16 AuthenticationAlg | Authentication Algorithm (as defined in [FIDORegistry]). |
| 1.4.5 | UINT16 Tag | TAG_TC_DISPLAY_CONTENT_TYPE (optional) |
| 1.4.5.1 | UINT16 Length | Length of content type. |
| 1.4.5.2 | UINT8[] ContentType | Transaction Confirmation Display Content Type. See [FIDOMetadataStatement] for additional information on the format of this field. |
| 1.4.6 | UINT16 Tag | TAG_TC_DISPLAY_PNG_CHARACTERISTICS (optional,multiple occurrences permitted) |
| 1.4.6.1 | UINT16 Length | Length of display characteristics information. |
| 1.4.6.2 | UINT32 Width | See [FIDOMetadataStatement] for additional information. |
| 1.4.6.3 | UINT32 Height | See [FIDOMetadataStatement] for additional information. |
| 1.4.6.4 | UINT8 BitDepth | See [FIDOMetadataStatement] for additional information. |
| 1.4.6.5 | UINT8 ColorType | See [FIDOMetadataStatement] for additional information. |
| 1.4.6.6 | UINT8 Compression | See [FIDOMetadataStatement] for additional information. |
| 1.4.6.7 | UINT8 Filter | See [FIDOMetadataStatement] for additional information. |
| 1.4.6.8 | UINT8 Interlace | See [FIDOMetadataStatement] for additional information. |
| 1.4.6.9 | UINT8[] PLTE | See [FIDOMetadataStatement] for additional information. |
| 1.4.7 | UINT16 Tag | TAG_ASSERTION_SCHEME |
| 1.4.7.1 | UINT16 Length | Length of Assertion Scheme |
| 1.4.7.2 | UINT8[] AssertionScheme | Assertion Scheme (as defined in [UAFRegistry]) |
| 1.4.8 | UINT16 Tag | TAG_ATTESTATION_TYPE (multiple occurrences possible) |
| 1.4.8.1 | UINT16 Length | Length of AttestationType |
| 1.4.8.2 | UINT16 AttestationType | Attestation Type values are defined in [UAFRegistry] by the
constants with the prefix TAG_ATTESTATION.
|
| 1.4.9 | UINT16 Tag | TAG_SUPPORTED_EXTENSION_ID (optional, multiple occurrences possible) |
| 1.4.9.1 | UINT16 Length | Length of SupportedExtensionID |
| 1.4.9.2 | UINT8[] SupportedExtensionID | SupportedExtensionID as a UINT8[] encoding of a UTF-8 string |
UAF_CMD_STATUS_OKUAF_CMD_STATUS_ERR_UNKNOWNUAF_CMD_STATUS_PARAMS_INVALIDThis command generates a UAF registration assertion. This assertion can be used to register the authenticator with a FIDO Server.
| TLV Structure | Description | |
|---|---|---|
| 1 | UINT16 Tag | TAG_UAFV1_REGISTER_CMD |
| 1.1 | UINT16 Length | Command Length |
| 1.2 | UINT16 Tag | TAG_AUTHENTICATOR_INDEX |
| 1.2.1 | UINT16 Length | Length of AuthenticatorIndex (must be 0x0001) |
| 1.2.2 | UINT8 AuthenticatorIndex | Authenticator Index |
| 1.3 | UINT16 Tag | TAG_APPID (optional) |
| 1.3.1 | UINT16 Length | Length of AppID |
| 1.3.2 | UINT8[] AppID | AppID (max 512 bytes) |
| 1.4 | UINT16 Tag | TAG_FINAL_CHALLENGE_HASH |
| 1.4.1 | UINT16 Length | Final Challenge Hash Length |
| 1.4.2 | UINT8[] FinalChallengeHash | Final Challenge Hash provided by ASM (max 32 bytes) |
| 1.5 | UINT16 Tag | TAG_USERNAME |
| 1.5.1 | UINT16 Length | Length of Username |
| 1.5.2 | UINT8[] Username | Username provided by ASM (max 128 bytes) |
| 1.6 | UINT16 Tag | TAG_ATTESTATION_TYPE |
| 1.6.1 | UINT16 Length | Length of AttestationType |
| 1.6.2 | UINT16 AttestationType | Attestation Type to be used |
| 1.7 | UINT16 Tag | TAG_KEYHANDLE_ACCESS_TOKEN |
| 1.7.1 | UINT16 Length | Length of KHAccessToken |
| 1.7.2 | UINT8[] KHAccessToken | KHAccessToken provided by ASM (max 32 bytes) |
| 1.8 | UINT16 Tag | TAG_USERVERIFY_TOKEN (optional) |
| 1.8.1 | UINT16 Length | Length of VerificationToken |
| 1.8.2 | UINT8[] VerificationToken | User verification token |
| TLV Structure | Description | |
|---|---|---|
| 1 | UINT16 Tag | TAG_UAFV1_REGISTER_CMD_RESPONSE |
| 1.1 | UINT16 Length | Command Length |
| 1.2 | UINT16 Tag | TAG_STATUS_CODE |
| 1.2.1 | UINT16 Length | Status Code Length |
| 1.2.2 | UINT16 Value | Status code returned by Authenticator |
| 1.3 | UINT16 Tag | TAG_AUTHENTICATOR_ASSERTION |
| 1.3.1 | UINT16 Length | Length of Assertion |
| 1.3.2 | UINT8[] Assertion | Registration Assertion (see section TAG_UAFV1_REG_ASSERTION). |
| 1.4 | UINT16 Tag | TAG_KEYHANDLE (optional) |
| 1.4.1 | UINT16 Length | Length of key handle |
| 1.4.2 | UINT8[] Value | (binary value of) key handle |
UAF_CMD_STATUS_OKUAF_CMD_STATUS_ERR_UNKNOWNUAF_CMD_STATUS_ACCESS_DENIEDUAF_CMD_STATUS_USER_NOT_ENROLLEDUAF_CMD_STATUS_USER_CANCELLEDUAF_CMD_STATUS_ATTESTATION_NOT_SUPPORTEDUAF_CMD_STATUS_PARAMS_INVALIDUAF_CMD_STATUS_TIMEOUTUAF_CMD_STATUS_USER_NOT_RESPONSIVEUAF_CMD_STATUS_INSUFFICIENT_RESOURCESUAF_CMD_STATUS_USER_LOCKOUTThe authenticator must perform the following steps (see below table for command structure):
If the command structure is invalid (e.g. cannot be parsed correctly),
return UAF_CMD_STATUS_PARAMS_INVALID.
Command.TAG_APPID is provided, and show its
content on the display when verifying the user. Return
UAF_CMD_STATUS_PARAMS_INVALID if Command.TAG_APPID
is not provided in such case. Update Command.KHAccessToken with TAG_APPID:
This method allows us to avoid storing the AppID separately in the RawKeyHandle.
If the user is locked out (e.g. too many failed attempts to get verified) and
the authenticator cannot automatically trigger unblocking,
return UAF_CMD_STATUS_USER_LOCKOUT.
UAF_CMD_STATUS_USER_NOT_RESPONSIVEUAF_CMD_STATUS_ACCESS_DENIEDUAF_CMD_STATUS_USER_CANCELLEDUAF_CMD_STATUS_USER_NOT_ENROLLED.
UAF_CMD_STATUS_USER_NOT_RESPONSIVEUAF_CMD_STATUS_ACCESS_DENIEDUAF_CMD_STATUS_USER_CANCELLEDUAF_CMD_STATUS_ATTESTATION_NOT_SUPPORTEDUAF_CMD_STATUS_TIMEOUT
UAF_CMD_STATUS_INSUFFICIENT_RESOURCES.
UAF_CMD_STATUS_OK as status codeThe authenticator MUST NOT process a Register command without verifying the user
(or enrolling the user, if this is the first time the user has used the authenticator).
The authenticator MUST generate a unique UAuth key pair each time the Register command is called.
The authenticator SHOULD either store key handle in its internal secure storage or cryptographically wrap it and export it to the ASM.
For silent authenticators, the key handle MUST never be stored on a FIDO Server, otherwise this would enable tracking of users without providing the ability for users to clear key handles from the local device.
If KeyID is not the key handle itself (e.g. such as in case of a second-factor roaming authenticator) - it MUST be a unique and unguessable byte array with a maximum length of 32 bytes. It MUST be unique within the scope of the AAID.
If the KeyID is generated randomly (instead of, for example, being derived from a key handle) - it should be stored inside RawKeyHandle so that it can be accessed by the authenticator while processing the Sign command.
If the authenticator doesn't support SignCounter or RegCounter
it MUST set these to 0 in TAG_UAFV1_KRD. The RegCounter MUST be set to 0 when a factory reset
for the authenticator is performed. The SignCounter MUST be set to 0 when a factory reset
for the authenticator is performed.
This command generates a UAF assertion. This assertion can be further verified by a FIDO Server which has a prior registration with this authenticator.
| TLV Structure | Description | |
|---|---|---|
| 1 | UINT16 Tag | TAG_UAFV1_SIGN_CMD |
| 1.1 | UINT16 Length | Length of Command |
| 1.2 | UINT16 Tag | TAG_AUTHENTICATOR_INDEX |
| 1.2.1 | UINT16 Length | Length of AuthenticatorIndex (must be 0x0001) |
| 1.2.2 | UINT8 AuthenticatorIndex | Authenticator Index |
| 1.3 | UINT16 Tag | TAG_APPID (optional) |
| 1.3.1 | UINT16 Length | Length of AppID |
| 1.3.2 | UINT8[] AppID | AppID (max 512 bytes) |
| 1.4 | UINT16 Tag | TAG_FINAL_CHALLENGE_HASH |
| 1.4.1 | UINT16 Length | Length of Final Challenge Hash |
| 1.4.2 | UINT8[] FinalChallengeHash | (binary value of) Final Challenge Hash provided by ASM (max 32 bytes) |
| 1.5 | UINT16 Tag | TAG_TRANSACTION_CONTENT (optional) |
| 1.5.1 | UINT16 Length | Length of Transaction Content |
| 1.5.2 | UINT8[] TransactionContent | (binary value of) Transaction Content provided by the ASM |
| 1.5 | UINT16 Tag | TAG_TRANSACTION_CONTENT_HASH (optional and mutually exclusive with TAG_TRANSACTION_CONTENT).
This TAG is only allowed for authenticators not able to display the transaction text, i.e.
authenticator with tcDisplay=0x0003 (i.e. flags
TRANSACTION_CONFIRMATION_DISPLAY_ANY and
TRANSACTION_CONFIRMATION_DISPLAY_PRIVILEGED_SOFTWARE are set).
|
| 1.5.1 | UINT16 Length | Length of Transaction Content Hash |
| 1.5.2 | UINT8[] TransactionContentHash | (binary value of) Transaction Content Hash provided by the ASM |
| 1.6 | UINT16 Tag | TAG_KEYHANDLE_ACCESS_TOKEN |
| 1.6.1 | UINT16 Length | Length of KHAccessToken |
| 1.6.2 | UINT8[] KHAccessToken | (binary value of) KHAccessToken provided by ASM (max 32 bytes) |
| 1.7 | UINT16 Tag | TAG_USERVERIFY_TOKEN (optional) |
| 1.7.1 | UINT16 Length | Length of the User Verification Token |
| 1.7.2 | UINT8[] VerificationToken | User Verification Token |
| 1.8 | UINT16 Tag | TAG_KEYHANDLE (optional, multiple occurrences permitted) |
| 1.8.1 | UINT16 Length | Length of KeyHandle |
| 1.8.2 | UINT8[] KeyHandle | (binary value of) key handle |
| TLV Structure | Description | |
|---|---|---|
| 1 | UINT16 Tag | TAG_UAFV1_SIGN_CMD_RESPONSE |
| 1.1 | UINT16 Length | Entire Length of Command Response |
| 1.2 | UINT16 Tag | TAG_STATUS_CODE |
| 1.2.1 | UINT16 Length | Status Code Length |
| 1.2.2 | UINT16 Value | Status code returned by authenticator |
| 1.3 (choice 1) | UINT16 Tag |
TAG_USERNAME_AND_KEYHANDLE (optional, multiple occurances)
This TLV tag can be used to convey multiple (>=1) {Username, Keyhandle} entries. Each occurance of TAG_USERNAME_AND_KEYHANDLE contains one pair. If this tag is present, TAG_AUTHENTICATOR_ASSERTION must not be present |
| 1.3.1 | UINT16 Length | Length of the structure |
| 1.3.2 | UINT16 Tag | TAG_USERNAME |
| 1.3.2.1 | UINT16 Length | Length of Username |
| 1.3.2.2 | UINT8[] Username | Username |
| 1.3.3 | UINT16 Tag | TAG_KEYHANDLE |
| 1.3.3.1 | UINT16 Length | Length of KeyHandle |
| 1.3.3.2 | UINT8[] KeyHandle | (binary value of) key handle |
| 1.3 (choice 2) | UINT16 Tag | TAG_AUTHENTICATOR_ASSERTION (optional)
If this tag is present, TAG_USERNAME_AND_KEYHANDLE must not be present |
| 1.3.1 | UINT16 Length | Assertion Length |
| 1.3.2 | UINT8[] Assertion | Authentication assertion generated by the authenticator (see section TAG_UAFV1_AUTH_ASSERTION). |
UAF_CMD_STATUS_OKUAF_CMD_STATUS_ERR_UNKNOWNUAF_CMD_STATUS_ACCESS_DENIEDUAF_CMD_STATUS_USER_NOT_ENROLLEDUAF_CMD_STATUS_USER_CANCELLEDUAF_CMD_STATUS_CANNOT_RENDER_TRANSACTION_CONTENTUAF_CMD_STATUS_PARAMS_INVALIDUAF_CMD_STATUS_KEY_DISAPPEARED_PERMANENTLYUAF_CMD_STATUS_TIMEOUTUAF_CMD_STATUS_USER_NOT_RESPONSIVEUAF_CMD_STATUS_USER_LOCKOUTFirst-factor authenticators should implement this command in two stages.
If a second-factor authenticator is presented with more than one valid key handles, it must exercise only the first one and ignore the rest.
The command is implemented in two stages to ensure that only one assertion can be generated for each command invocation.
Authenticators must take the following steps:
If the command structure is invalid (e.g. cannot be parsed correctly),
return UAF_CMD_STATUS_PARAMS_INVALID.
UAF_CMD_STATUS_PARAMS_INVALID if Command.TAG_APPID
is not provided in such case.
Command.TAG_USERVERIFY_TOKEN is a valid
token.
If the user is locked out (e.g. too many failed attempts to get verified) and
the authenticator cannot automatically trigger unblocking,
return UAF_CMD_STATUS_USER_LOCKOUT.
UAF_CMD_STATUS_USER_NOT_RESPONSIVEUAF_CMD_STATUS_ACCESS_DENIEDUAF_CMD_STATUS_USER_CANCELLEDUAF_CMD_STATUS_USER_NOT_ENROLLED
This should not occur as the Uauth key must be protected by the authenticator's user verification method. If the authenticator supports alternative user verification methods (e.g. alternative password and finger print verification and the alternative password must be provided before enrolling a finger and only the finger print is verified as part of the Register or Sign operation, then the authenticator should automatically and implicitly ask the user to enroll the modality required in the operation (instead of just returning an error).
If no RawKeyHandles are found - return UAF_CMD_STATUS_KEY_DISAPPEARED_PERMANENTLY.
UAF_CMD_STATUS_ACCESS_DENIEDIf two or more key handles with the same username are found, a first-factor roaming authenticator may only keep the one that is registered most recently and delete the rest. This avoids having unusable (old) private key in the authenticator which (surprisingly) might become active after deregistering the newly generated one.
UAF_CMD_STATUS_KEY_DISAPPEARED_PERMANENTLY.
TransactionContent is not empty
UAF_CMD_STATUS_ACCESS_DENIEDTransactionConfirmationDisplay to 0 in the response to a
GetInfo Command), then return UAF_CMD_STATUS_ACCESS_DENIEDCommand.TransactionContent and
Command.TAG_APPID (optional) on display and wait
for the user to confirm it:
UAF_CMD_STATUS_USER_NOT_RESPONSIVE if the user doesn't respond.UAF_CMD_STATUS_USER_CANCELLED if the user
cancels the transaction.UAF_CMD_STATUS_CANNOT_RENDER_TRANSACTION_CONTENT if
the provided transaction content cannot be rendered.TransactionContent is not set, but TransactionContentHash is not empty
UAF_CMD_STATUS_ACCESS_DENIEDTransactionConfirmationDisplay is
NOT set to 0x0003 in the response to a
GetInfo Command), then return UAF_CMD_STATUS_PARAMS_INVALIDUAF_CMD_STATUS_TIMEOUT.
Authenticator MUST NOT process Sign command without verifying the user first.
Authenticator MUST NOT reveal Username without verifying the user first.
Bound authenticators MUST NOT process Sign command without validating KHAccessToken first.
UAuth.priv keys MUST never leave Authenticator's security boundary in plaintext form.
UAuth.priv protection boundary is specified in Metadata.keyProtection field in Metadata
[FIDOMetadataStatement]).
If Authenticator's Metadata indicates that it does support Transaction Confirmation Display - it MUST display provided transaction content in this display and include the hash of content inside TAG_UAFV1_SIGNED_DATA structure.
Silent Authenticators MUST NOT operate in first-factor mode in order to follow the assumptions made in [FIDOSecRef].
If Authenticator doesn't support SignCounter, then it MUST
set it to 0 in TAG_UAFV1_SIGNED_DATA.
The SignCounter MUST be set to 0 when a factory reset
for the Authenticator is performed, in order to follow the
assumptions made in [FIDOSecRef].
Some Authenticators might support Transaction Confirmation display functionality not inside the Authenticator but within the boundaries of ASM. Typically these are software based Transaction Confirmation displays. When processing the Sign command with a given transaction such Authenticators should assume that they do have a builtin Transaction Confirmation display and should include the hash of transaction content in the final assertion without displaying anything to the user. Also, such Authenticator's Metadata file MUST clearly indicate the type of Transaction Confirmation display. Typically the flag of Transaction Confirmation display will be TRANSACTION_CONFIRMATION_DISPLAY_ANY or TRANSACTION_CONFIRMATION_DISPLAY_PRIVILEGED_SOFTWARE. See [FIDORegistry] for flags describing Transaction Confirmation Display type.
This command deletes a registered UAF credential from Authenticator.
| TLV Structure | Description | |
|---|---|---|
| 1 | UINT16 Tag | TAG_UAFV1_DEREGISTER_CMD |
| 1.1 | UINT16 Length | Entire Command Length |
| 1.2 | UINT16 Tag | TAG_AUTHENTICATOR_INDEX |
| 1.2.1 | UINT16 Length | Length of AuthenticatorIndex (must be 0x0001) |
| 1.2.2 | UINT8 AuthenticatorIndex | Authenticator Index |
| 1.3 | UINT16 Tag | TAG_APPID (optional) |
| 1.3.1 | UINT16 Length | Length of AppID |
| 1.3.2 | UINT8[] AppID | AppID (max 512 bytes) |
| 1.4 | UINT16 Tag | TAG_KEYID |
| 1.4.1 | UINT16 Length | Length of KeyID |
| 1.4.2 | UINT8[] KeyID | (binary value of) KeyID provided by ASM |
| 1.5 | UINT16 Tag | TAG_KEYHANDLE_ACCESS_TOKEN |
| 1.5.1 | UINT16 Length | Length of KeyHandle Access Token |
| 1.5.2 | UINT8[] KHAccessToken | (binary value of) KeyHandle Access Token provided by ASM (max 32 bytes) |
| TLV Structure | Description | |
|---|---|---|
| 1 | UINT16 Tag | TAG_UAFV1_DEREGISTER_CMD_RESPONSE |
| 1.1 | UINT16 Length | Entire Length of Command Response |
| 1.2 | UINT16 Tag | TAG_STATUS_CODE |
| 1.2.1 | UINT16 Length | Status Code Length |
| 1.2.2 | UINT16 StatusCode | StatusCode returned by Authenticator |
UAF_CMD_STATUS_OKUAF_CMD_STATUS_ERR_UNKNOWNUAF_CMD_STATUS_ACCESS_DENIEDUAF_CMD_STATUS_CMD_NOT_SUPPORTEDUAF_CMD_STATUS_PARAMS_INVALIDAuthenticator must take the following steps:
If the command structure is invalid (e.g. cannot be parsed correctly),
return UAF_CMD_STATUS_PARAMS_INVALID.
UAF_CMD_STATUS_PARAMS_INVALID if Command.TAG_APPID
is not provided in such case.
UAF_CMD_STATUS_CMD_NOT_SUPPORTEDTAG_KEYID is zero (i.e., 0000 Hex), then
TAG_APPID is provided, then
TAG_APPID do
TAG_APPID is not provided, then delete all KeyHandles
from internal storage where RawKeyHandle.KHAccessToken == Command.KHAccessToken
TAG_KEYID is NOT zero, then
UAF_CMD_STATUS_ACCESS_DENIEDUAF_CMD_STATUS_OKThe authenticator must unwrap the relevant KeyHandles using Wrap.sym as needed.
Bound authenticators MUST NOT process Deregister command without validating KHAccessToken first.
Deregister command SHOULD NOT explicitly reveal whether the provided keyID was registered or not.
UAF_CMD_STATUS_KEY_DISAPPEARED_PERMANENTLY as
this could reveal the keyID registration status.
The Authenticator must return UAF_CMD_STATUS_CMD_NOT_SUPPORTED if
it doesn't support such functionality.
If the command structure is invalid (e.g. cannot be parsed correctly), the authenticator must
return UAF_CMD_STATUS_PARAMS_INVALID.
| TLV Structure | Description | |
|---|---|---|
| 1 | UINT16 Tag | TAG_UAFV1_OPEN_SETTINGS_CMD |
| 1.1 | UINT16 Length | Entire Command Length |
| 1.2 | UINT16 Tag | TAG_AUTHENTICATOR_INDEX |
| 1.2.1 | UINT16 Length | Length of AuthenticatorIndex (must be 0x0001) |
| 1.2.2 | UINT8 AuthenticatorIndex | Authenticator Index |
| TLV Structure | Description | |
|---|---|---|
| 1 | UINT16 Tag | TAG_UAFV1_OPEN_SETTINGS_CMD_RESPONSE |
| 1.1 | UINT16 Length | Entire Length of Command Response |
| 1.2 | UINT16 Tag | TAG_STATUS_CODE |
| 1.2.1 | UINT16 Length | Status Code Length |
| 1.2.2 | UINT16 StatusCode | StatusCode returned by Authenticator |
UAF_CMD_STATUS_OKUAF_CMD_STATUS_ERR_UNKNOWNUAF_CMD_STATUS_CMD_NOT_SUPPORTEDUAF_CMD_STATUS_PARAMS_INVALIDThis section is non-normative.
There are 4 types of Authenticators defined in this document and due to their specifics they behave differently while processing commands. One of the main differences between them is how they store and process key handles. This section tries to clarify it by describing the behavior of every type of Authenticator during the processing of relevant command.
| Register Command |
Authenticator doesn't store key handles. Instead KeyHandle is always returned to ASM and stored
in ASM database.
KeyID is a randomly generated 32 bytes number (or simply the hash of KeyHandle). |
| Sign Command |
When there is no user session (no cookies, a clear machine) the Server doesn't provide any KeyID (since it doesn't know which KeyIDs to provide). In this scenario the ASM selects all key handles and passes them to Authenticator. During step-up authentication (when there is a user session) Server provides relevant KeyIDs. ASM selects key handles that correspond to provided KeyIDs and pass to Authenticator. |
| Deregister Command |
Since Authenticator doesn't store key handles, then there is nothing to delete inside Authenticator. ASM finds the KeyHandle corresponding to provided KeyID and deletes it. |
| Register Command |
Authenticator doesn't store key handles. Instead KeyHandle is always returned to ASM and stored
in ASM database.
KeyID is a randomly generated 32 bytes number (or simply the hash of KeyHandle). |
| Sign Command |
This Authenticator cannot operate without Server providing KeyIDs. Thus it can't be used when there is no user session (no cookies, a clear machine). During step-up authentication (when there is a user session) Server provides relevant KeyIDs. ASM selects key handles that correspond to provided KeyIDs and pass to Authenticator. |
| Deregister Command |
Since Authenticator doesn't store key handles, then there is nothing to delete inside it. ASM finds the KeyHandle corresponding to provided KeyID and deletes it. |
| Register Command |
Authenticator stores key handles inside its internal storage. KeyHandle is never returned back to ASM.
KeyID is a randomly generated 32 bytes number (or simply the hash of KeyHandle) |
| Sign Command |
When there is no user session (no cookies, a clear machine) Server doesn't provide any KeyID (since it doesn't know which KeyIDs to provide). In this scenario Authenticator uses all key handles that correspond to the provided AppID. During step-up authentication (when there is a user session) Server provides relevant KeyIDs. Authenticator selects key handles that correspond to provided KeyIDs and uses them. |
| Deregister Command |
Authenticator finds the right KeyHandle and deletes it from its storage. |
| Register Command | Neither Authenticator nor ASM store key handles. Instead KeyHandle is sent to the Server (in place of KeyID) and stored in User's record. From Server's perspective it's a KeyID. In fact KeyID is the KeyHandle. |
| Sign Command |
This Authenticator cannot operate without Server providing KeyIDs. Thus it can't be used when there is no user session (no cookies, a clear machine). During step-up authentication Server provides KeyIDs which are in fact key handles. Authenticator finds the right KeyHandle and uses it. |
| Deregister Command |
Since Authenticator and ASM don't store key handles, then there is nothing to delete on client side. |
This section is normative.
FIDO Authenticators may implement various mechanisms to guard access to privileged commands.
The following table summarizes the access control requirements for each command.
All UAF Authenticators MUST satisfy the access control requirements defined below.
Authenticator vendors MAY offer additional security mechanisms.
Terms used in the table:
| Command | First-factor Bound Authenticator | 2ndF Bound Authenticator | First-factor Roaming Authenticator | 2ndF Roaming Authenticator |
|---|---|---|---|---|
| GetInfo | NoAuth | NoAuth | NoAuth | NoAuth |
| OpenSettings | NoAuth | NoAuth | NoAuth | NoAuth |
| Register | UserVerify | UserVerify | UserVerify | UserVerify |
| Sign | UserVerify KHAccessToken KeyHandleList |
UserVerify KHAccessToken KeyHandleList |
UserVerify KHAccessToken |
UserVerify KHAccessToken KeyHandleList |
| Deregister | KHAccessToken KeyID |
KHAccessToken KeyID |
KHAccessToken KeyID |
KHAccessToken KeyID |
Table 1: Access Control for Commands
This section is non-normative.
The proposed algorithms and key sizes are chosen such that compatibility to TPMv2 is possible.
Some authenticators (e.g. TPMv2) do not have the ability to include their model identifier (i.e. vendor ID and model name) in attested messages (i.e. the to-be-signed part of the registration assertion). The TPM's endorsement key certificate typically contains that information directly or at least it allows the model to be derived from the endorsement key certificate.
In FIDO, the relying party expects the ability to cryptographically verify the authenticator model (i.e. AAID).
If the authenticator cannot securely include its model (i.e. AAID) in the registration assertion (i.e. in the KRD object), we require the ECDAA-Issuers public key (ipkk) to be dedicated to one single authenticator model (identified by its AAID).
Using this method, the issuer public key is uniquely related to one entry in the Metadata Statement and can be used by the FIDO server to get a cryptographic proof of the Authenticator model.
This section is non-normative.
The existing standard specifications most relevant to UAF authenticator are [TPM], [TEE] and [SecureElement].
Hardware modules implementing these standards may be extended to incorporate UAF functionality through their extensibility mechanisms such as by loading secure applications (trustlets, applets, etc) into them. Modules which do not support such extensibility mechanisms cannot be fully leveraged within UAF framework.
In order to support UAF inside TEE a special Trustlet (trusted application running inside TEE) may be designed which implements UAF Authenticator functionality specified in this document and also implements some kind of user verification technology (biometric verification, PIN or anything else).
An additional ASM must be created which knows how to work with the Trustlet.
In order to support UAF inside Secure Element (SE) a special Applet (trusted application running inside SE) may be designed which implements UAF Authenticator functionality specified in this document and also implements some kind of user verification technology (biometric verification, PIN or similar mechanisms).
An additional ASM must be created which knows how to work the Applet.
TPMs typically have a built-in attestation capability however the attestation model supported in TPMs is currently incompatible with UAF's basic attestation model. The future enhancements of UAF may include compatible attestation schemes.
Typically TPMs also have a built-in PIN verification functionality which may be leveraged for UAF. In order to support UAF with an existing TPM module, the vendor should write an ASM which:
A special AssertionScheme, designed for TPMs, must be also created (see [FIDOMetadataStatement]) and published by FIDO Alliance. When FIDO Server receives an assertion with this AssertionScheme it will treat the received data as TPM-generated data and will parse/validate it accordingly.
The command structures described in this document assume a reliable transport and provide no support at the application-layer to detect or correct for issues such as unreliable ordering, duplication, dropping or modification of messages. If the transport layer(s) between the ASM and Authenticator are not reliable, the non-normative private contract between the ASM and Authenticator may need to provide a means to detect and correct such errors.
This section is non-normative.
| Category | Guidelines |
|---|---|
| AppIDs and KeyIDs |
Registered AppIDs and KeyIDs must not be returned by an authenticator in plaintext, without first performing user verification. If an attacker gets physical access to a roaming authenticator, then it should not be easy to read out AppIDs and KeyIDs. |
| Attestation Private Key |
Authenticators must protect the attestation private key as a very sensitive asset. The overall security of the authenticator depends on the protection level of this key. It is highly recommended to store and operate this key inside a tamper-resistant hardware module, e.g. [SecureElement]. It is assumed by registration assertion schemes, that the authenticator has exclusive control over the data being signed with the attestation key. FIDO Authenticators must ensure that the attestation private key:
Attestation must be implemented in a way such that two different relying parties cannot link registrations, authentications or other transactions (see [UAFProtocol]). |
| Certifications |
Vendors should strive to pass common security standard certifications with authenticators, such as [FIPS140-2], [CommonCriteria] and similar. Passing such certifications will positively impact the UAF implementation of the authenticator. |
| Cryptographic (Crypto) Kernel |
The crypto kernel is a module of the authenticator implementing cryptographic functions (key generation, signing, wrapping, etc) necessary for UAF, and having access to UAuth.priv, Attestation Private Key and Wrap.sym. For optimal security, this module should reside within the same security boundary as the UAuth.priv, Att.priv and Wrap.sym keys. If it resides within a different security boundary, then the implementation must guarantee the same level of security as if they would reside within the same module. It is highly recommended to generate, store and operate this key inside a trusted execution environment [TEE]. In situations where physical attacks and side channel attacks are considered in the threat model, it is highly recommended to use a tamper-resistant hardware module. Software-based authenticators must make sure to use state of the art code protection and obfuscation techniques to protect this module, and whitebox encryption techniques to protect the associated keys. Authenticators need good random number generators using a high quality entropy source, for:
The authenticator's random number generator (RNG) should be such that it cannot be disabled or controlled in a way that may cause it to generate predictable outputs. If the authenticator doesn't have sufficient entropy for generating strong random numbers, it should fail safely. See the section of this table regarding random numbers |
| KeyHandle |
It is highly recommended to use authenticated encryption while wrapping key handles with Wrap.sym. Algorithms such as AES-GCM and AES-CCM are most suitable for this operation. |
| Liveness Detection / Presentation Attack Detection |
The user verification method should include liveness detection [NSTCBiometrics], i.e. a technique to ensure that the sample submitted is actually from a (live) user. In the case of PIN-based matching, this could be implemented using [TEESecureDisplay] in order to ensure that malware can't emulate PIN entry. |
| Matcher |
By definition, the matcher component is part of the authenticator. This does not impose any restrictions on the authenticator implementation, but implementers need to make sure that there is a proper security boundary binding the matcher and the other parts of the authenticator together. Tampering with the matcher module may have significant security consequences. It is highly recommended for this module to reside within the integrity boundaries of the authenticator, and be capable of detecting tampering. It is highly recommended to run this module inside a trusted execution environment [TEE] or inside a secure element [SecureElement]. Authenticators which have separated matcher and CryptoKernel modules should implement mechanisms which would allow the CryptoKernel to securely receive assertions from the matcher module indicating the user's local verification status. Software based Authenticators (if not in trusted execution environment) must make sure to use state of the art code protection and obfuscation techniques to protect this module. When an Authenticator receives an invalid UserVerificationToken it should treat this as an attack, and invalidate the cached UserVerificationToken. A UserVerificationToken should have a lifetime not exceeding 10 seconds. Authenticators must implement anti-hammering protections for their matchers. Biometrics based authenticators must protect the captured biometrics data (such as fingerprints) as well as the reference data (templates), and make sure that the biometric data never leaves the security boundaries of authenticators. Matchers must only accept verification reference data enrolled by the user, i.e. they must not include any default PINs or default biometric reference data. |
| Private Keys (UAuth.priv and Attestation Private Key) |
This document requires (a) the attestation key to be used for attestation purposes only and (b) the authentication keys to be used for FIDO authentication purposes only. The related to-be-signed objects (i.e. Key Registration Data and SignData) are designed to reduce the likelihood of such attacks:
|
| Random Numbers |
The FIDO Authenticator uses its random number generator to generate authentication key pairs, client side challenges, and potentially for creating ECDSA signatures. Weak random numbers will make FIDO vulnerable to certain attacks. It is important for the FIDO Authenticator to work with good random numbers only. The (pseudo-)random numbers used by authenticators should successfully pass the randomness test specified in [Coron99] and they should follow the guidelines given in [SP800-90b]. Additionally, authenticators may choose to
incorporate entropy provided by the FIDO Server via
the When mixing multiple entropy sources, a suitable mixing function should be used, such as those described in [RFC4086]. |
| RegCounter |
The If the
A registration counter should be implemented as a global counter, i.e. one covering registrations to all AppIDs. This global counter should be increased by 1 upon any registration operation. Note: The RegCounter value should not be decreased by |
| SignCounter |
When an attacker is able to extract a Uauth.priv key from a registered authenticator, this key can be used independently from the original authenticator. This is considered cloning of an authenticator. Good protection measures of the Uauth private keys is one method to prevent cloning authenticators. In some situations the protection measures might not be sufficient. If the Authenticator maintains a signature counter
If the
Signature counters should be implemented that are dedicated for each private key in order to preserve the user's privacy. A per-key A per-key If the authenticator is not able to handle
many different signature counters, then a global
signature counter covering all private keys should be
implemented. A global Note There are multiple reasons why the |
| Transaction Confirmation Display |
A transaction confirmation display must ensure that the user is presented with the provided transaction content, e.g. not overlaid by other display elements and clearly recognizable. See [CLICKJACKING] for some examples of threats and potential counter-measures For more guidelines refer to [TEESecureDisplay]. |
| UAuth.priv |
An authenticator must protect all UAuth.priv keys as its most sensitive assets. The overall security of the authenticator depends significantly on the protection level of these keys. It is highly recommended that this key is generated, stored and operated inside a trusted execution environment. In situations where physical attacks and side channel attacks are considered within the threat model, it is highly recommended to use a tamper-resistant hardware module. FIDO Authenticators must ensure that UAuth.priv keys:
|
| Username |
A username must not be returned in plaintext in any
condition other than the conditions described for the
SIGN command. In all other conditions usernames must
be stored within a |
| Verification Reference Data |
The verification reference data, such as fingerprint templates or the reference value of a PIN, are by definition part of the authenticator. This does not impose any particular restrictions on the authenticator implementation, but implementers need to make sure that there is a proper security boundary binding all parts of the authenticator together. |
| Wrap.sym |
If the authenticator has a wrapping key (Wrap.sym), then the authenticator must protect this key as its most sensitive asset. The overall security of the authenticator depends on the protection of this key. Wrap.sym key strength must be equal or higher than the strength of secrets stored in a RawKeyHandle. Refer to [SP800-57] and [SP800-38F] publications for more information about choosing the right wrapping algorithm and implementing it correctly. It is highly recommended to generate, store and operate this key inside a trusted execution environment. In situations where physical attacks and side channel attacks are considered in the threat model, it is highly recommended to use a tamper-resistant hardware module. If the authenticator uses Wrap.sym, it must ensure that unwrapping corrupted KeyHandle and unwrapping data which has invalid contents (e.g. KeyHandle from invalid origin) are indistinguishable to the caller. |