The English version of this specification is the only normative version. Non-normative translations may also be available.
Copyright © 2013-2020 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://fidoalliance.org/specifications/.
This document was published by the FIDO Alliance as a Proposed Standard. If you wish to make comments regarding this document, please Contact Us. All comments are welcome.
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.
This document has been reviewed by FIDO Aliance Members and is endorsed as a Proposed Standard. It is a stable document and may be used as reference material or cited from another document. FIDO Alliance's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment.
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
ask the authenticator for using a specific user verification method and confirm that
in the related response extension.
The client SHOULD pass the (request) extension through to the Authenticator.
The payload of this extension is an array of:
UINT32 userVerificationMethod
The array can have multiple entries. Each entry SHALL have a single bit flag set. In this case the authenticator SHALL verify the user using all (multiple) methods as indicated.
The semantics of the fields are as follows:
The payload of this extension is an array of the following structure:
UINT32 userVerificationMethod UINT16 keyProtection UINT16 matcherProtection
The array can have multiple entries describing all user verification methods used.
The semantics of the fields are as follows:
OperationHeader.
TAG_UAFV1_REGISTER_CMD object using TAG_EXTENSION
(request extension).
TAG_EXTENSION
(response extension).
The main purpose of this extension is to allow relying parties finding the related user record by an existing index (i.e. the user ID). This user ID is not intended to be displayed.
Authenticators SHOULD truthfully indicate support for this extension in their Metadata Statement.
false, i.e. this (request and response) extension can safely be ignored by all entities.data valueOperationHeader 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 response as returned by the call to
com.google.android.gms.safetynet.SafetyNetApi.AttestationResponse.
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 AttestationResponse 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 related to a registration response (response extension).
exts
array in either the OperationHeader, or
the AuthenticatorRegistrationAssertion
of the UAF Registration 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.
Calendar notBefore = Calendar.getInstance();
Calendar notAfter = Calendar.getInstance();
notAfter.add(Calendar.YEAR, 10);
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)
.setKeyValidityStart(notBefore.getTime())
.setKeyValidityEnd(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))
.replace("\n", "");
i++;
}
JSONArray jarray=new JSONArray(certArray);
String key_attestation_data=jarray.toString();"exts": [{"id": "fido.uaf.android.key_attestation", "data": "[\"MIIClDCCAjugAwIBAgIBATAKBggqhkjOPQQD
AjCBiDELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFTATBgNVBAoMDEdvb2dsZSwgSW5jLjEQMA4GA1UECwwHQW5k
cm9pZDE7MDkGA1UEAwwyQW5kcm9pZCBLZXlzdG9yZSBTb2Z0d2FyZSBBdHRlc3RhdGlvbiBJbnRlcm1lZGlhdGUwIBcNNzAwMTAx
MDAwMDAwWhgPMjEwNjAyMDcwNjI4MTVaMB8xHTAbBgNVBAMMFEFuZHJvaWQgS2V5c3RvcmUgS2V5MFkwEwYHKoZIzj0CAQYIKoZI
zj0DAQcDQgAEJ/As4L+Kgbcxwcx+5LPQi35quIxg981k/TeWr2IPBLh8+NJ+buDBhQ9O5ln6B7JjbJc4Fvko1Pdz7spKTQdWpKOB
+zCB+DALBgNVHQ8EBAMCB4AwgccGCisGAQQB1nkCAREEgbgwgbUCAQIKAQACAQEKAQEEBkZDSEFTSAQAMGm/hT0IAgYBXtPjz6C/
hUVZBFcwVTEvMC0EKGNvbS5hbmRyb2lkLmtleXN0b3JlLmFuZHJvaWRrZXlzdG9yZWRlbW8CAQExIgQgdM/LUHSI9SkQhZHHpQWR
nzJ3MvvB2ANSauqYAAbS2JgwMqEFMQMCAQKiAwIBA6MEAgIBAKUFMQMCAQSqAwIBAb+DeAMCAQK/hT4DAgEAv4U/AgUAMB8GA1Ud
IwQYMBaAFD/8rNYasTqegSC41SUcxWW7HpGpMAoGCCqGSM49BAMCA0cAMEQCICgYLmk24alwS9Lm06y2lLiqWDddrWh4gmUUv4+A
5k2TAiAEttheSBBaNbQJGQCh3mY92v8nP5obU60IKjpPetRswQ==\",\"MIICeDCCAh6gAwIBAgICEAEwCgYIKoZIzj0EAwIwgZg
xCzAJBgNVBAYTAlVTMRMwEQYDVQQIDApDYWxpZm9ybmlhMRYwFAYDVQQHDA1Nb3VudGFpbiBWaWV3MRUwEwYDVQQKDAxHb29nbGU
sIEluYy4xEDAOBgNVBAsMB0FuZHJvaWQxMzAxBgNVBAMMKkFuZHJvaWQgS2V5c3RvcmUgU29mdHdhcmUgQXR0ZXN0YXRpb24gUm9
vdDAeFw0xNjAxMTEwMDQ2MDlaFw0yNjAxMDgwMDQ2MDlaMIGIMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEVMBM
GA1UECgwMR29vZ2xlLCBJbmMuMRAwDgYDVQQLDAdBbmRyb2lkMTswOQYDVQQDDDJBbmRyb2lkIEtleXN0b3JlIFNvZnR3YXJlIEF
0dGVzdGF0aW9uIEludGVybWVkaWF0ZTBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABOueefhCY1msyyqRTImGzHCtkGaTgqlzJhP
+rMv4ISdMIXSXSir+pblNf2bU4GUQZjW8U7ego6ZxWD7bPhGuEBSjZjBkMB0GA1UdDgQWBBQ//KzWGrE6noEguNUlHMVlux6RqTA
fBgNVHSMEGDAWgBTIrel3TEXDo88NFhDkeUM6IVowzzASBgNVHRMBAf8ECDAGAQH/AgEAMA4GA1UdDwEB/wQEAwIChDAKBggqhkj
OPQQDAgNIADBFAiBLipt77oK8wDOHri/AiZi03cONqycqRZ9pDMfDktQPjgIhAO7aAV229DLp1IQ7YkyUBO86fMy9Xvsiu+f+uXc
/WT/7\",\"MIICizCCAjKgAwIBAgIJAKIFntEOQ1tXMAoGCCqGSM49BAMCMIGYMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaW
Zvcm5pYTEWMBQGA1UEBwwNTW91bnRhaW4gVmlldzEVMBMGA1UECgwMR29vZ2xlLCBJbmMuMRAwDgYDVQQLDAdBbmRyb2lkMTMwMQ
YDVQQDDCpBbmRyb2lkIEtleXN0b3JlIFNvZnR3YXJlIEF0dGVzdGF0aW9uIFJvb3QwHhcNMTYwMTExMDA0MzUwWhcNMzYwMTA2MD
A0MzUwWjCBmDELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDU1vdW50YWluIFZpZXcxFTATBgNVBA
oMDEdvb2dsZSwgSW5jLjEQMA4GA1UECwwHQW5kcm9pZDEzMDEGA1UEAwwqQW5kcm9pZCBLZXlzdG9yZSBTb2Z0d2FyZSBBdHRlc3
RhdGlvbiBSb290MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE7l1ex+HA220Dpn7mthvsTWpdamguD/9/SQ59dx9EIm29sa/6Fs
vHrcV30lacqrewLVQBXT5DKyqO107sSHVBpKNjMGEwHQYDVR0OBBYEFMit6XdMRcOjzw0WEOR5QzohWjDPMB8GA1UdIwQYMBaAFM
it6XdMRcOjzw0WEOR5QzohWjDPMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgKEMAoGCCqGSM49BAMCA0cAMEQCIDUho+
+LNEYenNVg8x1YiSBq3KNlQfYNns6KGYxmSGB7AiBNC/NR2TB8fVvaNTQdqEcbY6WFZTytTySn502vQX3xvw==\"]", "fail_if_unknown": false}]Line-breaks been added for readibility.
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 section 3.4.6.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.
The field data is specified with type DOMString in [FIDOMetadataStatement] and hence will contain the
serialized object as described above.
supportedExtensions field in the Metadata Statement could look as follows
(with line breaks to improve readability):
"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
}]In several cases it is good enough for the relying party to know whether the user was verified by the authenticator "some time" ago. This extension allows an app to specify such user verification caching time, i.e. the time for which the user verification status can be "cached" by the authenticator.
For example: Do not ask the user for a fresh user verification to authorize a payment of 4€ if the user was verified by this authenticator within the past 300 seconds.
This extension allows the authenticator to bridge the gap between a "silent" authenticator, i.e. an authenticator never verifying the user and a "traditional" authenticator, i.e. an authenticator always asking for fresh user verification.
We formally define one extension for the request and a separate extension for the response as the request extension can be safely ignored, but the response extension cannot.
Authenticator supporting this extension MUST truthfully specify both,
the UVC Request and UVC Response extension in the supportedExtensions list
of the related Metadata Statement [FIDOMetadataStatement].
The TAG of the UVC Response extension must be specified in that list.
This extension can be added by FIDO Servers to the UAF Request object (request extension)
in the OperationHeader in order to trigger generation of the related response extension.
false, i.e. the request extension can safely be ignored by all entities.
TAG_USER_VERIFICATION_CACHING.
In the UVC Extension provided through the DOM API [UAFAppAPIAndTransport],
the field verifyIfExceeded MAY NOT be present. The FIDO Client MAY add the field
verifyIfExceeded in order to improve processing.
Same TLV object as defined in "Extension data value", but as binary object included in the Registration / Authentication command.
verifyIfExceeded) is not allowed in a registration request.
If the authenticator does not support specifying user verification caching time in a sign request, this extension will be ignored by the authenticator. This will be detected by the server since no extension output will be generated by the authenticator.
This extension can be added by the Authenticator to the
AuthenticatorRegistrationAssertion, or the AuthenticatorSignAssertion
of the UAF Response object (response extension).
true, i.e. the response extension (included in the UAF assertion)
MAY NOT be ignored if unknown. If the server is not prepared to
process the UVC response extension, it MUST fail.
TAG_USER_VERIFICATION_CACHING will be included in the
assertion generated by the Authenticator.
Where the field maxUVC contains an upper bound of trueUVC and where the
field verifyIfExceeded will not be present.
The upper bound value is to be computed as follows:
Where command.maxUVC refers to the maxUVC value of
the related UVC Request.
Where regMaxUVC is the maxUVC value specified in the related registration call (see above) or 0 if no such value was provided at registration time.
For example, use min(maxUVC, createMaxUVC) or min(round trueUVC to 5 seconds, maxUVC, createMaxUVC).
supportedExtensionsIf the FIDO Server did not request the UVC extension (but encounters it in the response) or if the server doesn't understand the UVC response extension, it MUST fail.
Using the UVC Request extension with verifyIfExceeded set to FALSE might allow the
caller to triage the last time the user was verified without requiring any input from the user and without
notifying the user. We do not allow this field to be set through
the DOM API (i.e. by web pages). However, native applications can use this field and hence could be
able to determine the last time the user was verified. Native applications have substantially more
permissions and hence can have more detailed knowledge about the user's behavior than web pages
(e.g. track whether the device is used by evaluating accelerometers).
In the UVC Response extension the Authenticator can provide an upper bound of the trueUVC
value in order to prevent disclosure of exact time of user verification.
FIDO Servers not expecting user verification being used, might expect a fresh user verification and an explicit user consent being provided. Authenticators supporting this extension shall only use it when they are asked for that (i.e. UVC Request extension is present). Additionally the authenticator must indicate if the user was not freshly verified using the UVC Response extension. This response extension is marked with "fail-if-unknown" set to true, to make sure that servers receiving this extension know that the user might not have been freshly verified.
This extension is intended to simplify the integration of authenticators implementing [FIDOCTAP] with FIDO UAF [UAFProtocol].
false, i.e. the extension MAY be ignored if unknown.
isSecondFactorOnly=false in their Metadata
Statement will persistently store the credential's cryptographic key material internally if the extension is missing.isSecondFactorOnly=true in their Metadata
Statement will NOT persistently store the credential's cryptographic key material internally if the extension is missing.fido.uaf.rk set to false indicates that the FIDO Server needs to provide a keyHandle for triggering authentication. This means that the authenticator
can only be used as a second factor (see also isSecondFactorOnly in [FIDOMetadataStatement].
If the FIDO Server did not request the fido.uaf.rk extension (but encounters it in the response) or
if the server doesn't understand the fido.uaf.rk response extension, it can silently ignore the extension.
This extension is intended to simplify the integration of authenticators implementing [FIDOCTAP] with FIDO UAF [UAFProtocol].
false, i.e. the extension MAY be ignored if unknown.
If the FIDO Server specified ac='none', but received an attestation statement, it can silently ignore it.
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:
|