Copyright © 2013-2018 FIDO Alliance All Rights Reserved.
This specification defines a mapping of FIDO UAF Authenticator commands to Application Protocol Data Units (APDUs) thus facilitating UAF authenticators based on Secure Elements.
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.
The notation base64url(byte[8..64]) reads as 8-64 bytes of data
encoded in base64url, "Base 64 Encoding with URL and Filename
Safe Alphabet" [RFC4648] without padding.
UAF specific terminology used in this document is defined in [FIDOGlossary].
All diagrams, examples, notes in this specification are non-normative.
All TLV structures defined in this document MUST be encoded in little-endian format.
All APDU defined in this document MUST be encoded as defined in [ISOIEC-7816-4-2013].
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].
This section is non-normative.
This specification defines the interface between the FIDO UAF Authenticator Specific Module (ASM) [UAFASM] and authenticators based upon "Secure Element" technology. The applicable secure element form factors are UICC (SIM card), embedded Secure Element (eSE), µSD, NFC card, and USB token. Their common characteristic is they communicate using Application Programming Data Units (APDU) in compliance with [ISOIEC-7816-4-2013].
Implementation of this specification is optional in the UAF framework, however, products claiming to implement the transport of UAF messages over APDUs should implement it.
This specification first describes the various fashions in which Secure Elements can be incorporated into UAF authenticator implementations — known as SE-based authenticators or just SE authenticators — and which components are responsible for handling user verification as well as cryptographic operations. The specification then describes the overall architecture of an SE-based authenticator stack from the ASM down to the secure element, the role of the "UAF Applet" running in the secure element, and outlines the nominal communication flow between the ASM and the SE. It then defines the mapping of UAF Authenticator commands to APDUs, as well as the FIDO-specific variants of the VERIFY APDU command.
This specification does not define how an SE-based authenticator stack may be implemented, e.g., its integration with TEE or biometric sensors. However, SE-based authenticator vendors should reflect such implementation characteristics in the authenticator metadata such that FIDO Relying Parties wishing to be informed of said characteristics may have access to it.
This section is non-normative.
Secure elements can be leveraged in different scenarios in the UAF technology. It can support user gestures (used to unlock access to FIDO credentials) or it can be involved in the actual cryptographic operations related to FIDO authentication. In this specification, we will be considering the following SE-based authenticator implementation use cases:
In FIDO UAF, the access to credentials for performing the actual authentication can be protected by a user verification step. This user verification step can be based on a PIN, a biometric or other methods. The authenticator functionality might be implemented in different components, including combinations such as TEE and SE, or fingerprint sensor and SE. In that case the SE implements only a part of the authenticator functionality.
The reason for using such hybrid configuration is that Secure Elements do not have any user interface and hence cannot directly distinguish physical user interaction from programmatic communication (e.g. by malware). The ability to require a physical user interaction that cannot be emulated by malware is essential for protecting against scalable attacks (see [FIDOSecRef]). On the other hand, TEEs (or biometric sensors implemented in separate hardware) which can provide a trusted user interface typically do not offer the same level of key protection as Secure Elements.
Strictly spoken, a Hybrid SE Authenticator (voluntarily) uses the Authenticator Command interface [UAFAuthnrCommands] inside the authenticator, e.g. between the crypto kernel and the user verification component.
Examples of Hybrid SE authenticators are:
In all those cases, the hybrid nature of the authenticator will be managed by the software-based host, regardless of its nature (TEE, SW, Biometric sensor..). There are a number of possible interactions between the ASM and the SE actually implementing the verification and the cryptographic operations to consider within those use cases.
In order to support an Hybrid SE Authenticator, a dedicated software-based host MUST be created which knows how the SE applet works. The communication between the SE applet and the host is defined based on [ISOIEC-7816-4-2013]. Whether a PC or mobile device the architecture is still the same, as defined below:
Application Layer : This component is responsible for acquiring
the user verification sample and mapping UAF commands to APDU
commands.Communication layer : This is the [ISOIEC-7816-4-2013] APDUs
interface, which provides methods to list and select readers,
connect to a Secure Element and interact with it.SE Access OS APIs : OMA, PC/SC, NFC API, CCID…Secure Element : UICC, micro SD, eSE, Dual Interface card…
APDU command-response paire are handled as indicated in [ISOIEC-7816-4-2013].
The host is the entity communicating with the SE and which knows how the SE and the applet running in the SE can be accessed. The host could be a Trusted Application (TA) which runs inside a TEE or simply an application which runs in the normal world.
The following diagram illustrates how the Host of the Hybrid SE Authenticator MAY map the UAF commands to APDU commands. In this diagram, the User Verification Module is considered inside the SE applet.
If the User Verification Module is inside the Host, for
example in the context of the TEE, the UserVerificationToken
shall be generated in the Host and not in the SE. As a
result step 6 (Figure 2) should be executed in the Host instead of the SE.
This section is normative.
The User verification is based on the submission of a PIN/password (i.e., knowledge based) or a biometric template (i.e., biometric based).
In this document, the envisaged user verification methods are PIN and biometric based.
The SE applet must be able to perform a set of cryptographic operations, such as key generation and signature computation. The cryptographic operations are defined in [UAFAuthnrCommands]. The SE applet must be able also to create data structures that can be parsed by FIDO Server. The SE applet SHALL use the cryptographic algorithms indicated in [UAFRegistry].
CLA indicates the class of the command.
|
If the payload of an APDU command is longer than 255 bytes, command chaining as described in [ISOIEC-7816-4-2013] should be used, even though CLA is proprietary.
This section describes the mapping between FIDO UAF authenticator commands and APDU commands.
The mapping consists of encapsulating the entire UAF Authenticator Command in the payload of the APDU command, and the UAF Authenticator Command response in the payload of the APDU Response.
The host SHALL set the INS byte to “0x36” for all UAF commands The SE SHALL read the UAF command number and data from the payload in the data part of the command.
The payload of the APDU command is encoded according to [UAFAuthnrCommands], the first 2 bytes of each command are the UAF command number. Upon command reception, the SE applet MUST parse the first TLV tag (2 bytes) and figure out which UAF command is being issued. The SE applet SHALL parse the rest of the FIDO Authenticator Command payload according to [UAFAuthnrCommands].
The mapping of UAF Authenticator Commands to APDU commands is defined in the following table:
|
The UAF Authenticator Command structures are defined in part 6.2 of [UAFAuthnrCommands].
If the UserVerificationToken is
supported, The ASM must set the TAG_USERVERIFY_TOKEN flag in the
value of the UserVerificationToken, received previously
contained in either a Register or Sign command. Please
refer to the FIG 1 in Use-Case section.
The status word of an "UAF" APDU response is handled at the Host level; the host must interpret and map the status word based on the table below.
If the status word is equals to “9000”, the host shall return
back to the ASM the entire data field of the APDU response. It
the status word is “61xx”, the host shall issue GET RESPONSE
(see below) until no more data is available, concatenate these
response parts and then return the entire response. Otherwise,
the host has to build an UAF TLV response with the mapped status
codes TAG_STATUS_CODE, using the following table.
For example, if the status word returned by the Applet is
“6A88”, the host shall put UAF_CMD_STATUS_USER_NOT_ENROLLED
in the status codes of the UAF TLV response.
| APDU STATUS CODE | FIDO UAF STATUS CODE | NAME | DESCRIPTION |
|---|---|---|---|
| 9000 | 0x00 | UAF_CMD_STATUS_OK | Success. |
| 61xx | 0x00 | UAF_CMD_STATUS_OK | Success, xx bytes available for GET RESPONSE. |
| 6982 | 0x02 | UAF_CMD_STATUS_ACCESS_DENIED | Access to this operation is denied. |
| 6A88 | 0x03 | UAF_CMD_STATUS_USER_NOT_ENROLLED | User is not enrolled with the authenticator. |
| N/A | 0x04 | UAF_CMD_STATUS_CANNOT_RENDER_TRANSACTION_CONTENT | Transaction content cannot be rendered. |
| N/A | 0x05 | UAF_CMD_STATUS_USER_CANCELLED | User has cancelled the operation. |
| 6400 | 0x06 | UAF_CMD_STATUS_CMD_NOT_SUPPORTED | Command not supported. |
| 6A81 | 0x07 | UAF_CMD_STATUS_ATTESTATION_NOT_SUPPORTED | Required attestation not supported. |
| 6A80 | 0x08 | UAF_CMD_STATUS_PARAMS_INVALID | The request was rejected due to an incorrect data field. |
| 6983 | 0x09 | UAF_CMD_STATUS_KEY_DISAPPEARED_PERMANENTLY | The UAuth key which is relevant for this command disappeared from the authenticator and cannot be restored. |
| N/A | 0x0a | UAF_CMD_STATUS_TIMEOUT | The operation in the authenticator took longer than expected. |
| N/A | 0x0e | UAF_CMD_STATUS_USER_NOT_RESPONSIVE | The user took too long to follow an instruction. |
| 6A84 | 0x0f | UAF_CMD_STATUS_INSUFFICIENT_RESOURCES | Insufficient resources in the authenticator to perform the requested task. |
| 63C0 | 0x10 | UAF_CMD_STATUS_USER_LOCKOUT | The operation failed because the user is locked out and the authenticator cannot automatically trigger an action to change that. |
| All other codes | 0x01 | UAF_CMD_STATUS_ERR_UNKNOWN | An unknown error |
The response message of an UAF APDU command is defined in the following table :
| Data field | SW1 - SW2 |
|---|---|
| not present | “6982” – The request was rejected due to user verification being required. “6A80” – The request was rejected due to an incorrect data field. “6A81” – Required attestation not supported “6A88” – The user is not enrolled with the SE “6400” – Execution error, undefined UAF command “6983” – Authentication data not usable, Auth key disappeared |
| UAF Authenticator Command response [UAFAuthnrCommands] | “61xx” – Success, xx bytes available for GET RESPONSE. “9000” – Success |
A successful SELECT AID allows the host to know that the applet is active in the SE, and to open a logical channel with this end.
In Android smartphones apps are not allowed to use the basic channel to the SIM because this channel is reserved for the baseband processor and the GSM/UMTS/LTE activities. In this case the app must select the applet in a logical channel.
The host must send a SELECT APDU command to the SE applet before
any others commands.
As a result, the command for selecting the applet using the FIDO UAF AID is :
|
This command is used to request access rights using a PIN or Biometric sample. The SE applet shall verify the sample data given by the Host against the reference PIN or Biometric held in the SE.
Please refer to [ISOIEC-7816-4-2013] and [ISOIEC-19794] for Personal verification through biometric methods.
If the verification is successful and UserVerificationToken is
supported by the SE applet, a token SHALL be generated and
sent to the Host. Without having this token, the Host cannot
invoke special UAF commands such as Register or Sign.
The support of UserVerificationToken can be checked by
examining the contents of the GetInfo response
in the AuthenticatorType TAG or the response of SELECT APDU
command [UAFAuthnrCommands].
UserVerificationToken.
| CLA | INS | P1 | P2 | Lc | Data In | Le |
|---|---|---|---|---|---|---|
| ISO or Proprietary: see [ISOIEC-7816-4-2013] | 0x20 (for PIN) or 0x21 (for biometry) | 0x00 | 0x00 | Variable | Verification data | None or expected Le for UserVerificationToken |
| Data Out | SW1 - SW2 |
|---|---|
Absent (ISO-Variant) or UserVerificationToken (proprietary) |
See [ISOIEC-7816-4-2013] |
An SE applet that does not support UserVerificationToken,
may use the [ISOIEC-7816-4-2013] VERIFY command. In this case,
the VERIFY command must be securely bound to Register and
Sign commands, so a secure bound method shall be implemented in
the SE applet, such as Secure Messaging.
If a Secure Element is able to send a complete response
(e.g. extended length APDU, block chaining), GET RESPONSE
APDU command SHALL be used, as defined in ISO Variant section.
Otherwise, the proprietary solution SHALL be used, as defined in
section Proprietary Variant.
The [ISOIEC-7816-4-2013] GET RESPONSE command is used in order to retrieve big data returned by APDU command "UAF".
In order to avoid using Get Response APDU command which is not supported by all devices and terminals, a propriatry method is defined for managing the long data answers at application level.
When using the proprietary variant, the response to the UAF APDU command SHALL include the Tag "0x2813", that specifies the length of the response.
Response Data Out description
In the case where the data does not fit into a single Data Out message, the host SHALL repeat the "UAF" command with P2 = 1 value mentioning this is a repetition of the incoming APDU to get all the data. This process SHALL be repeated until the entire data are collected by the host.
Here is an example of an APDU Response which contains more than 255 bytes in the payload.
The host shall support both versions of Get Response APDU command, and figure out which command must be sent to the Applet by parsing the response of the UAF APDU command. If the UAF APDU command response contains the Tag "0x2813", the host must send a proprietary Get Response APDU command, otherwise the host must send the ISO variant of Get Response APDU command.
This section is non-normative.
Guaranteeing trust and security in a fragmented architecture such as the one levering on SE is a challenge that the Host has to address regardless of its nature (TEE or Software based), which results in different challenges from a security and architecture perspective. One could list the following ones:Hence, we will only consider here, security challenges affecting the interface between the Host and the SE.
A possible way to maintain the integrity and confidentiality when APDUs commands are exchanged is to enable a secure channel between the Host and the SE. While this is left to implementation, there are several technologies allowing to build a secure channel between a SE and a devices, that may be implemented.