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.

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 ASM version MUST be 1.0 (i.e. major version is 1 and minor version 0).

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_ERROR.
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 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 enrollment fails, return UAF_ASM_STATUS_ACCESS_DENIED
4. Construct KHAccessToken (see section KHAccessToken for more details)
5. 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.

6. 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.
7. Invoke the command and receive the response
8. Parse TAG_UAFV1_REGISTER_CMD_RESP
   1. Parse the content of TAG_AUTHENTICATOR_ASSERTION (e.g. TAG_UAFV1_REG_ASSERTION) and extract TAG_KEYID
9. 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.

10. 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
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 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_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
9. Invoke the command and receive the response
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 equal usernames are found, then choose the one which has registered most recently
      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 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
   • Lookup the authenticator related data in the ASM database and delete the record associated with DeregisterIn.appID and DeregisterIn.keyID
4. Create the TAG_UAFV1_DEREGISTER_CMD structure, copy KHAccessToken, DeregisterIn.keyID and pass it to the authenticator.
5. Invoke the command and receive the response

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. 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.