Copyright © 2013-2016 FIDO Alliance All Rights Reserved.
This document defines all the strings and constants reserved by UAF protocols. The values defined in this document are referenced by various UAF specifications.
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 Review 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 is a Review Draft Specification and is not intended to be a basis for any implementations as the Specification may change. Permission is hereby granted to use the Specification solely for the purpose of reviewing 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.
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 document defines the registry of UAF-specific constants that are used and referenced in various UAF specifications. It is expected that, over time, new constants will be added to this registry. For example new authentication algorithms and new types of authenticator characteristics will require new constants to be defined for use within the specifications.
FIDO-specific constants that are common to multiple protocol families are defined in [FIDORegistry].
This section is normative.
Names of assertion schemes are strings with a length of 8 characters.
UAF TLV based assertion scheme “UAFV1TLV”
ALG_
). This assertion scheme is using a compact
Tag Length Value (TLV) encoding for the KRD and SignData messages generated
by the authenticators. This is the default assertion scheme for the UAF protocol.This section is normative.
The internal structure of UAF authenticator commands is a “Tag-Length-Value” (TLV) sequence. The tag is a 2-byte unique unsigned value describing the type of field the data represents, the length is a 2-byte unsigned value indicating the size of the value in bytes, and the value is the variable-sized series of bytes which contain data for this item in the sequence.
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.
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.
A tag that has the 13th bit (0x1000) set indicates a composite tag that can be parsed by recursive descent.
This section is normative.
OperationHeader
in order to
trigger generation of the related response extension.
exts
array in the ASMResponse
object (response extension).
exts
array in either the OperationHeader
, or
the AuthenticatorRegistrationAssertion
,
or the AuthenticatorSignAssertion
of the UAF Response object (response extension).
false
, i.e. this (request and response) extension can safely be ignored by all entities.data
valuedata
value
in order to trigger the generation of this extension for the UAF Response.
"exts": [{"id": "fido.uaf.safetynet", "data": "", "fail_if_unknown": false}]
data
value
is set to the JSON Web Signature attestation result as returned by the call to
com.google.android.gms.safetynet.SafetyNetApi.AttestationResult
.
data
value
is set to the string "p" (i.e. platform issue).
"exts": [{"id": "fido.uaf.safetynet", "data": "p", "fail_if_unknown": false}]
data
value
is set to the string "a" (i.e. availability issue).
"exts": [{"id": "fido.uaf.safetynet", "data": "a", "fail_if_unknown": false}]
If neither the FIDO Client nor the ASM support this extension, it won't be present in the response object.
FIDO Clients running on Android should support processing of this extension.
If the FIDO Client finds this (request) extension with emptydata
value
in the UAF Request and it supports processing this extension, then the FIDO Client
SafetyNet.SafetyNetApi.attest(mGoogleApiClient, nonce)
(see SafetyNet
online documentation) and add the response (or an error code as described above)
as extension to the response object.
If the FIDO Client does not support this extension it MUST copy this extension from the UAF Request to the ASM Request object (according to the general rule in [UAFProtocol], section 3.4.6.2 and 3.5.7.2).
If the ASM supports this extension it MUST call the SafetyNet API (see above) and add the response as extension to the ASM Response object. The FIDO Client MUST copy the extension in the ASM Response to the UAF Response object (according to sections 3.4.6.4. and 3.5.7.4 step 4 in [UAFProtocol]).
When calling the Android API, the nonce parameter MUST be set to the serialized JSON object with the following structure:
{ "hashAlg": "S256", // the hash algorithm "fcHash": "..." // the finalChallengeHash }Where
hashAlg
identifies the hash algorithm according
to [FIDOSignatureFormat], section IANA Considerations.fcHash
is the base64url encoded hash value of
FinalChallenge (see section 3.6.3 and
3.7.4 in [UAFASM] for details on how to compute finalChallengeHash
).
Only hash algorithms belonging to the Authentication Algorithms
mentioned in [FIDORegistry] SHALL be used (e.g. SHA256 because
it belongs to ALG_SIGN_SECP256R1_ECDSA_SHA256_RAW
).
The package name in AttestationResult might relate to either the FIDO Client or the ASM.
The response extension is not part of the signed assertion generated by the authenticator. If an MITM or MITB attacker would remove the response extension, the FIDO server might not be able to distinguish this from the "SafetyNet extension not supported by FIDO Client/ASM" case.
OperationHeader
in order to
trigger generation of the related response extension.
exts
array in the ASMResponse
object (response extension).
exts
array in either the OperationHeader
, or
the AuthenticatorRegistrationAssertion
,
or the AuthenticatorSignAssertion
of the UAF Response object (response extension).
false
, i.e. this (request and response) extension can safely be ignored by all entities.data
valuedata
value
in order to trigger the generation of this extension for the UAF Response.
"exts": [{"id": "fido.uaf.android.key_attestation", "data": "", "fail_if_unknown": false}]
data
value
is set to a JSON array containing the base64 encoded entries of the array returned by the call to the
KeyStore API function getCertificateChain.
KeyPairGenerator kpGenerator = KeyPairGenerator.getInstance( KeyProperties.KEY_ALGORITHM_EC, "AndroidKeyStore"); kpGenerator.initialize( new KeyGenParameterSpec.Builder(keyUUID, KeyProperties.PURPOSE_SIGN) .setDigests(KeyProperties.DIGEST_SHA256) .setAlgorithmParameterSpec(new ECGenParameterSpec("prime256v1")) .setCertificateSubject( new X500Principal(String.format("CN=%s, OU=%s", keyUUID, aContext.getPackageName()))) .setCertificateSerialNumber(BigInteger.ONE) .setCertificateNotBefore(notBefore.getTime()) .setCertificateNotAfter(notAfter.getTime()) .setUserAuthenticationRequired(true) .setAttestationChallenge(fcHash) -- bind to Final Challenge .build()); kpGenerator.generateKeyPair(); // generate Uauth key pair Certificate[] certarray=myKeyStore.getCertificateChain(keyUUID); String certArray[]=new String[certarray.length]; int i=0; for (Certificate cert : certarray) { byte[] buf = cert.getEncoded(); certArray[i] = new String(Base64.encode(buf, Base64.DEFAULT)); i++; } JSONArray jarray=new JSONArray(certArray); String key_attestation_data=jarray.toString();
data
value
is set to the string "p" (i.e. platform issue).
"exts": [{"id": "fido.uaf.android.key_attestation", "data": "p", "fail_if_unknown": false}]
data
value
is set to the string "a".
"exts": [{"id": "fido.uaf.android.key_attestation", "data": "a", "fail_if_unknown": false}]
If neither the FIDO Client nor the ASM support this extension, it won't be present in the response object.
FIDO Clients running on Android MUST pass this (request) extension
with empty data
value to the ASM.
If the ASM supports this extension it MUST call the KeyStore API (see above) and add the response as extension to the ASM Response object. The FIDO Client MUST copy the extension in the ASM Response to the UAF Response object (according to sections 3.4.6.4. and 3.5.7.4 step 4 in [UAFProtocol]).
More details on Android key attestation can be found at:
The response extension is not part of the signed assertion generated by the authenticator. If an MITM or MITB attacker would remove the response extension, the FIDO server might not be able to distinguish this from the "KeyAttestation extension not supported by ASM/Authenticator" case.
data
value (for Metadata Statement)Each array element is a base64-encoded (section 4 of [RFC4648]), DER-encoded [ITU-X690-2008] PKIX certificate value.
A certificate listed here is either a root certificate or an intermediate CA certificate.
supportedExtensions
field in the Metadata Statement could look as follows:
"supportedExtensions": [{ "id": "fido.uaf.android.key_attestation", "data": { "attestationRootCertificates": [ "MIICPTCCAeOgAwIBAgIJAOuexvU3Oy2wMAoGCCqGSM49BAMCMHsxIDAeBgNVBAMM F1NhbXBsZSBBdHRlc3RhdGlvbiBSb290MRYwFAYDVQQKDA1GSURPIEFsbGlhbmNl MREwDwYDVQQLDAhVQUYgVFdHLDESMBAGA1UEBwwJUGFsbyBBbHRvMQswCQYDVQQI DAJDQTELMAkGA1UEBhMCVVMwHhcNMTQwNjE4MTMzMzMyWhcNNDExMTAzMTMzMzMy WjB7MSAwHgYDVQQDDBdTYW1wbGUgQXR0ZXN0YXRpb24gUm9vdDEWMBQGA1UECgwN RklETyBBbGxpYW5jZTERMA8GA1UECwwIVUFGIFRXRywxEjAQBgNVBAcMCVBhbG8g QWx0bzELMAkGA1UECAwCQ0ExCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZI zj0DAQcDQgAEH8hv2D0HXa59/BmpQ7RZehL/FMGzFd1QBg9vAUpOZ3ajnuQ94PR7 aMzH33nUSBr8fHYDrqOBb58pxGqHJRyX/6NQME4wHQYDVR0OBBYEFPoHA3CLhxFb C0It7zE4w8hk5EJ/MB8GA1UdIwQYMBaAFPoHA3CLhxFbC0It7zE4w8hk5EJ/MAwG A1UdEwQFMAMBAf8wCgYIKoZIzj0EAwIDSAAwRQIhAJ06QSXt9ihIbEKYKIjsPkri VdLIgtfsbDSu7ErJfzr4AiBqoYCZf0+zI55aQeAHjIzA9Xm63rruAxBZ9ps9z2XN lQ=="] }, "fail_if_unknown": false }]
This AID [ISOIEC-7816-5] is used to identify FIDO UAF authenticator applications in a Secure Element.
The FIDO UAF AID consists of the following fields:
|