Package: android.hardware.gatekeeper@1.0

IGatekeeper

interface IGatekeeper

Methods

enroll

enroll (uint32_t uid, vec<uint8_t> currentPasswordHandle, vec<uint8_t> currentPassword, vec<uint8_t> desiredPassword)
generates (GatekeeperResponse response)

Enrolls desiredPassword, which may be derived from a user selected pin or password, with the private key used only for enrolling authentication factor data.

If there was already a password enrolled, current password handle must be passed in currentPasswordHandle, and current password must be passed in currentPassword.Valid currentPassword must verify() against currentPasswordHandle.

Details
Parameters
uid
The Android user identifier
currentPasswordHandle
The currently enrolled password handle the user wants to replace.May be empty only if there's no currently enrolled password.Otherwise must be non-empty.
currentPassword
The user's current password in plain text.it MUST verify against current_password_handle if the latter is not-empty
desiredPassword
The new password the user wishes to enroll in plaintext.
Generates
response
On success, data buffer must contain the new password handle referencing the password provided in desiredPassword.This buffer can be used on subsequent calls to enroll or verify.On error, this buffer must be empty.response.code must always contain operation completion status.This method may return ERROR_GENERAL_FAILURE or ERROR_RETRY_TIMEOUT on failure.It must return STATUS_OK on success.If ERROR_RETRY_TIMEOUT is returned, response.timeout must be non-zero.

verify

verify (uint32_t uid, uint64_t challenge, vec<uint8_t> enrolledPasswordHandle, vec<uint8_t> providedPassword)
generates (GatekeeperResponse response)

Verifies that providedPassword matches enrolledPasswordHandle.

Implementations of this module may retain the result of this call to attest to the recency of authentication.

On success, returns verification token in response.data, which shall be usable to attest password verification to other trusted services.

Details
Parameters
uid
The Android user identifier
challenge
An optional challenge to authenticate against, or 0.Used when a separate authenticator requests password verification, or for transactional password authentication.
enrolledPasswordHandle
The currently enrolled password handle that user wishes to verify against.Must be non-empty.
providedPassword
The plaintext password to be verified against the enrolledPasswordHandle
Generates
response
On success, a non-empty data buffer containing the authentication token resulting from this verification is returned.On error, data buffer must be empty.response.code must always contain operation completion status.This method may return ERROR_GENERAL_FAILURE or ERROR_RETRY_TIMEOUT on failure.It must return STATUS_OK on success.If password re-enrollment is necessary, it must return STATUS_REENROLL.If ERROR_RETRY_TIMEOUT is returned, response.timeout must be non-zero.

deleteUser

deleteUser (uint32_t uid)
generates (GatekeeperResponse response)

Deletes the enrolledPasswordHandle associated with the uid.Once deleted the user cannot be verified anymore.This is an optional method.

Details
Parameters
uid
The Android user identifier
Generates
response
response.code must always contain operation completion status.This method may return ERROR_GENERAL_FAILURE or ERROR_RETRY_TIMEOUT on failure.It must return STATUS_OK on success.If not implemented, it must return ERROR_NOT_IMPLEMENTED.If ERROR_RETRY_TIMEOUT is returned, response.timeout must be non-zero.

deleteAllUsers

deleteAllUsers ()
generates (GatekeeperResponse response)

Deletes all the enrolled_password_handles for all uid's.Once called, no users must be enrolled on the device.This is an optional method.

Details
Generates
response
response.code must always contain operation completion status.This method may return ERROR_GENERAL_FAILURE or ERROR_RETRY_TIMEOUT on failure.It must return STATUS_OK on success.If not implemented, it must return ERROR_NOT_IMPLEMENTED.If ERROR_RETRY_TIMEOUT is returned, response.timeout must be non-zero.