3.2.1 Constants

UAF_ASM_STATUS_OK of type short

No error condition encountered.

UAF_ASM_STATUS_ERROR of type short

An unknown error has been encountered during the processing.

UAF_ASM_STATUS_ACCESS_DENIED of type short

Access to this request is denied.

UAF_ASM_STATUS_USER_CANCELLED of type short

Indicates that user explicitly canceled the request.

UAF_ASM_STATUS_CANNOT_RENDER_TRANSACTION_CONTENT of type short

Transaction content cannot be rendered, e.g. format doesn't fit authenticator's need.

UAF_ASM_STATUS_KEY_DISAPPEARED_PERMANENTLY of type short

Indicates that the UAuth key disappeared from the authenticator and canot be restored.

UAF_ASM_STATUS_AUTHENTICATOR_DISCONNECTED of type short

Indicates that the authenticator is no longer connected to the ASM.

UAF_ASM_STATUS_USER_NOT_RESPONSIVE of type short

The user took too long to follow an instruction, e.g. didn't swipe the finger within the accepted time.

UAF_ASM_STATUS_INSUFFICIENT_AUTHENTICATOR_RESOURCES of type short

Insufficient resources in the authenticator to perform the requested task.

UAF_ASM_STATUS_USER_LOCKOUT of type short

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.

UAF_ASM_STATUS_USER_NOT_ENROLLED of type short

The operation failed because the user is not enrolled to the authenticator and the authenticator cannot automatically trigger user enrollment.

UAF_ASM_STATUS_SYSTEM_INTERRUPTED of type short

Indicates that the system interrupted the operation. Retry might make sense.

3.2.2 Mapping Authenticator Status Codes to ASM Status Codes

Authenticators are returning a status code in their responses to the ASM. The ASM needs to act on those responses and also map the status code returned by the authenticator to an ASM status code.

The mapping of authenticator status codes to ASM status codes is specified here:

3.3.1 Dictionary ASMRequest Members

requestType of type required Request

Request type

asmVersion of type Version

ASM message version to be used with this request. For the definition of the Version dictionary see [UAFProtocol]. The asmVersion MUST be 1.2 (i.e. major version is 1 and minor version is 2) for this version of the specification.

authenticatorIndex of type unsigned short

Refer to the GetInfo request for more details. Field authenticatorIndex MUST NOT be set for GetInfo request.

args of type object

Request-specific arguments. If set, this attribute MAY take one of the following types:

• RegisterIn
• AuthenticateIn
• DeregisterIn

exts of type array of Extension

List of UAF extensions. For the definition of the Extension dictionary see [UAFProtocol].

3.4.1 Dictionary ASMResponse Members

statusCode of type required short

MUST contain one of the values defined in the StatusCode interface

responseData of type object

Request-specific response data. This attribute MUST have one of the following types:

• GetInfoOut
• RegisterOut
• AuthenticateOut
• GetRegistrationOut

exts of type array of Extension

List of UAF extensions. For the definition of the Extension dictionary see [UAFProtocol].

3.5.1 GetInfoOut Dictionary

dictionary GetInfoOut {
    required AuthenticatorInfo[] Authenticators;
};

3.5.2 AuthenticatorInfo Dictionary

dictionary AuthenticatorInfo {
    required unsigned short               authenticatorIndex;
    required Version[]                    asmVersions;
    required boolean                      isUserEnrolled;
    required boolean                      hasSettings;
    required AAID                         aaid;
    required DOMString                    assertionScheme;
    required unsigned short               authenticationAlgorithm;
    required unsigned short[]             attestationTypes;
    required unsigned long                userVerification;
    required unsigned short               keyProtection;
    required unsigned short               matcherProtection;
    required unsigned long                attachmentHint;
    required boolean                      isSecondFactorOnly;
    required boolean                      isRoamingAuthenticator;
    required DOMString[]                  supportedExtensionIDs;
    required unsigned short               tcDisplay;
    DOMString                             tcDisplayContentType;
    DisplayPNGCharacteristicsDescriptor[] tcDisplayPNGCharacteristics;
    DOMString                             title;
    DOMString                             description;
    DOMString                             icon;
};

3.6.1 RegisterIn Object

dictionary RegisterIn {
    required DOMString      appID;
    required DOMString      username;
    required DOMString      finalChallenge;
    required unsigned short attestationType;
};

3.6.2 RegisterOut Object

dictionary RegisterOut {
    required DOMString assertion;
    required DOMString assertionScheme;
};

3.6.3 Detailed Description for Processing the Register Request

Refer to [UAFAuthnrCommands] document for more information about the TAGs and structure mentioned in this paragraph.

1. Locate authenticator using authenticatorIndex. If the authenticator cannot be located, then fail with UAF_ASM_STATUS_AUTHENTICATOR_DISCONNECTED.
2. If a user is already enrolled with this authenticator (such as biometric enrollment, PIN setup, etc. for example) then the ASM MUST request that the authenticator verifies the user.
   Note

   If the authenticator supports UserVerificationToken (see [UAFAuthnrCommands]), then the ASM must obtain this token in order to later include it with the Register command.

   If the user is locked out (e.g. too many failed attempts to get verified) and the authenticator cannot automatically trigger unblocking, return UAF_ASM_STATUS_USER_LOCKOUT.

   • If verification fails, return UAF_ASM_STATUS_ACCESS_DENIED
3. If the user is not enrolled with the authenticator then take the user through the enrollment process.
   • If neither the ASM nor the Authenticator can trigger the enrollment process, return UAF_ASM_STATUS_USER_NOT_ENROLLED.
   • If enrollment fails, return UAF_ASM_STATUS_ACCESS_DENIED
4. Verify whether registerIn.appID and the appID included in the finalChallenge parameter are identical. The registerIn.finalChallenge value needs to be (1) base64url decoded and (2) parsed into a JSON object first.
   • If verification fails, return UAF_ASM_STATUS_ACCESS_DENIED
5. Construct KHAccessToken (see section KHAccessToken for more details)
6. Hash the provided RegisterIn.finalChallenge using the authenticator-specific hash function (FinalChallengeHash)

   An authenticator's preferred hash function information MUST meet the algorithm defined in the AuthenticatorInfo.authenticationAlgorithm field.

7. Create a TAG_UAFV1_REGISTER_CMD structure and pass it to the authenticator
   1. Copy FinalChallengeHash, KHAccessToken, RegisterIn.Username, UserVerificationToken, RegisterIn.AppID, RegisterIn.AttestationType
      1. Depending on AuthenticatorType some arguments may be optional. Refer to [UAFAuthnrCommands] for more information on authenticator types and their required arguments.
   2. Add the extensions from the ASMRequest.exts dictionary appropriately to the TAG_UAFV1_REGISTER_CMD as TAG_EXTENSION object.
8. Invoke the command and receive the response. If the authenticator returns an error, handle that error appropriately. If the connection to the authenticator gets lost and cannot be restored, return UAF_ASM_STATUS_AUTHENTICATOR_DISCONNECTED. If the operation finally fails, map the authenticator error code to the the appropriate ASM error code (see section 3.2.2 Mapping Authenticator Status Codes to ASM Status Codes for details).
9. Parse TAG_UAFV1_REGISTER_CMD_RESP
   1. Parse the content of TAG_AUTHENTICATOR_ASSERTION (e.g. TAG_UAFV1_REG_ASSERTION) and extract TAG_KEYID
10. If the authenticator is a bound authenticator
    1. Store CallerID, AppID, TAG_KEYHANDLE, TAG_KEYID and CurrentTimestamp in the ASM's database.
       Note

       What data an ASM will store at this stage depends on underlying authenticator's architecture. For example some authenticators might store AppID, KeyHandle, KeyID inside their own secure storage. In this case ASM doesn't have to store these data in its database.

11. Create a RegisterOut object
    1. Set RegisterOut.assertionScheme according to AuthenticatorInfo.assertionScheme
    2. Encode the content of TAG_AUTHENTICATOR_ASSERTION (e.g. TAG_UAFV1_REG_ASSERTION) in base64url format and set as RegisterOut.assertion.
    3. Return RegisterOut object

3.7.1 AuthenticateIn Object

dictionary AuthenticateIn {
    required DOMString appID;
    DOMString[]        keyIDs;
    required DOMString finalChallenge;
    Transaction[]      transaction;
};

3.7.2 Transaction Object

dictionary Transaction {
    required DOMString                  contentType;
    required DOMString                  content;
    DisplayPNGCharacteristicsDescriptor tcDisplayPNGCharacteristics;
};

3.7.3 AuthenticateOut Object

dictionary AuthenticateOut {
    required DOMString assertion;
    required DOMString assertionScheme;
};

3.7.4 Detailed Description for Processing the Authenticate Request

Refer to the [UAFAuthnrCommands] document for more information about the TAGs and structure mentioned in this paragraph.

1. Locate the authenticator using authenticatorIndex. If the authenticator cannot be located, then fail with UAF_ASM_STATUS_AUTHENTICATOR_DISCONNECTED.
2. If no user is enrolled with this authenticator (such as biometric enrollment, PIN setup, etc.), return UAF_ASM_STATUS_ACCESS_DENIED
3. The ASM MUST request the authenticator to verify the user.
   • If the user is locked out (e.g. too many failed attempts to get verified) and the authenticator cannot automatically trigger unblocking, return UAF_ASM_STATUS_USER_LOCKOUT.
   • If verification fails, return UAF_ASM_STATUS_ACCESS_DENIED
   Note

   If the authenticator supports UserVerificationToken (see [UAFAuthnrCommands]), the ASM must obtain this token in order to later pass to Sign command.

4. Construct KHAccessToken (see section KHAccessToken for more details)
5. Hash the provided AuthenticateIn.finalChallenge using an authenticator-specific hash function (FinalChallengeHash).

   The authenticator's preferred hash function information MUST meet the algorithm defined in the AuthenticatorInfo.authenticationAlgorithm field.

6. If this is a Second Factor authenticator and AuthenticateIn.keyIDs is empty, then return UAF_ASM_STATUS_ACCESS_DENIED
7. If AuthenticateIn.keyIDs is not empty,
   1. If this is a bound authenticator, then look up ASM's database with AuthenticateIn.appID and AuthenticateIn.keyIDs and obtain the KeyHandles associated with it.
      • Return UAF_ASM_STATUS_KEY_DISAPPEARED_PERMANENTLY if the related key disappeared permanently from the authenticator.
      • Return UAF_ASM_STATUS_ACCESS_DENIED if no entry has been found.
   2. If this is a roaming authenticator, then treat AuthenticateIn.keyIDs as KeyHandles
8. Create TAG_UAFV1_SIGN_CMD structure and pass it to the authenticator.
   1. Copy AuthenticateIn.AppID, AuthenticateIn.Transaction.content (if not empty), FinalChallengeHash, KHAccessToken, UserVerificationToken, KeyHandles
      • Depending on AuthenticatorType some arguments may be optional. Refer to [UAFAuthnrCommands] for more information on authenticator types and their required arguments.
      • If multiple transactions are provided, select the one that best matches the current display characteristics.
        Note

        This may, for example, depend on whether user's device is positioned horizontally or vertically at the moment of transaction.

      • Decode the base64url encoded AuthenticateIn.Transaction.content before passing it to the authenticator
   2. Add the extensions from the ASMRequest.exts dictionary appropriately to the TAG_UAFV1_REGISTER_CMD as TAG_EXTENSION object.
9. Invoke the command and receive the response. If the authenticator returns an error, handle that error appropriately. If the connection to the authenticator gets lost and cannot be restored, return UAF_ASM_STATUS_AUTHENTICATOR_DISCONNECTED. If the operation finally fails, map the authenticator error code to the appropriate ASM error code (see section 3.2.2 Mapping Authenticator Status Codes to ASM Status Codes for details).
10. Parse TAG_UAFV1_SIGN_CMD_RESP
    • If it's a first-factor authenticator and the response includes TAG_USERNAME_AND_KEYHANDLE, then
      1. Extract usernames from TAG_USERNAME_AND_KEYHANDLE fields
      2. If two or more equal usernames are found, then choose the one which has registered most recently
         Note

         After this step, a first-factor bound authenticator which stores KeyHandles inside the ASM's database may delete the redundant KeyHandles from the ASM's database. This avoids having unusable (old) private key in the authenticator which (surprisingly) might become active after deregistering the newly generated one.

      3. Show remaining distinct usernames and ask the user to choose a single username
      4. Set TAG_UAFV1_SIGN_CMD.KeyHandles to the single KeyHandle associated with the selected username.
      5. Go to step #8 and send a new TAG_UAFV1_SIGN_CMD command
11. Create the AuthenticateOut object
    1. Set AuthenticateOut.assertionScheme as AuthenticatorInfo.assertionScheme
    2. Encode the content of TAG_AUTHENTICATOR_ASSERTION (e.g. TAG_UAFV1_AUTH_ASSERTION) in base64url format and set as AuthenticateOut.assertion
    3. Return the AuthenticateOut object

The authenticator metadata statement MUST truly indicate the type of transaction confirmation display implementation. Typically the "Transaction Confirmation Display" flag will be set to TRANSACTION_CONFIRMATION_DISPLAY_ANY (bitwise) or TRANSACTION_CONFIRMATION_DISPLAY_PRIVILEGED_SOFTWARE.

3.8.1 DeregisterIn Object

dictionary DeregisterIn {
    required DOMString appID;
    required DOMString keyID;
};

3.8.2 Detailed Description for Processing the Deregister Request

Refer to [UAFAuthnrCommands] for more information about the TAGs and structures mentioned in this paragraph.

1. Locate the authenticator using authenticatorIndex
2. Construct KHAccessToken (see section KHAccessToken for more details).
3. If this is a bound authenticator, then
   • If the value of DeregisterIn.keyID is an empty string, then lookup all pairs of this appID and any keyID mapped to this authenticatorIndex and delete them. Go to step 4.
   • Otherwise, lookup the authenticator related data in the ASM database and delete the record associated with DeregisterIn.appID and DeregisterIn.keyID. Go to step 4.
4. Create the TAG_UAFV1_DEREGISTER_CMD structure, copy KHAccessToken and DeregisterIn.keyID and pass it to the authenticator.
   Note

   In the case of roaming authenticators, the keyID passed to the authenticator might be an empty string. The authenticator is supposed to deregister all keys related to this appID in this case.

5. Invoke the command and receive the response. If the authenticator returns an error, handle that error appropriately. If the connection to the authenticator gets lost and cannot be restored, return UAF_ASM_STATUS_AUTHENTICATOR_DISCONNECTED. If the operation finally fails, map the authenticator error code to the appropriate ASM error code (see section 3.2.2 Mapping Authenticator Status Codes to ASM Status Codes for details). Return proper ASMResponse.

3.9.1 GetRegistrationsOut Object

dictionary GetRegistrationsOut {
    required AppRegistration[] appRegs;
};

3.9.2 AppRegistration Object

dictionary AppRegistration {
    required DOMString   appID;
    required DOMString[] keyIDs;
};

3.9.3 Detailed Description for Processing the GetRegistrations Request

1. Locate the authenticator using authenticatorIndex
2. If this is bound authenticator, then
   • Lookup the registrations associated with CallerID and AppID in the ASM database and construct a list of AppRegistration objects
   Note

   Some ASMs might not store this information inside their own database. Instead it might have been stored inside the authenticator's secure storage area. In this case the ASM must send a proprietary command to obtain the necessary data.

3. If this is not a bound authenticator, then set the list to empty.
4. Create GetRegistrationsOut object and return

5.1.1 Discovering ASMs

FIDO UAF Clients can discover the ASMs available on the system by using PackageManager.queryIntentActivities(Intent intent, int flags) with the FIDO Intent described above to see if any activities are available.

A typical FIDO UAF Client will enumerate all ASM applications using this function and will invoke the GetInfo operation for each one discovered.

5.1.2 Alternate Android AIDL Service ASM Implementation

The Android Intent API can also be implemented using Android AIDL services as an alternative transport mechanism to Android Intents. Please see Android Intent API section [UAFAppAPIAndTransport] for differences between the Android AIDL service and Android Intent implementation.