gatekeeper_device Struct Reference

Data Fields
gatekeeper_device Struct Reference

#include < gatekeeper.h >

Data Fields

hw_device_t   common
 
int(*  enroll )(const struct gatekeeper_device *dev, uint32_t uid, const uint8_t *current_password_handle, uint32_t current_password_handle_length, const uint8_t *current_password, uint32_t current_password_length, const uint8_t *desired_password, uint32_t desired_password_length, uint8_t **enrolled_password_handle, uint32_t *enrolled_password_handle_length)
 
int(*  verify )(const struct gatekeeper_device *dev, uint32_t uid, uint64_t challenge, const uint8_t *enrolled_password_handle, uint32_t enrolled_password_handle_length, const uint8_t *provided_password, uint32_t provided_password_length, uint8_t **auth_token, uint32_t *auth_token_length, bool *request_reenroll)
 
int(*  delete_user )(const struct gatekeeper_device *dev, uint32_t uid)
 
int(*  delete_all_users )(const struct gatekeeper_device *dev)
 

Detailed Description

Definition at line 41 of file gatekeeper.h .

Field Documentation

hw_device_t common

Common methods of the gatekeeper device. As above, this must be the first member of keymaster_device.

Definition at line 46 of file gatekeeper.h .

int(* delete_all_users)(const struct gatekeeper_device *dev)

Definition at line 173 of file gatekeeper.h .

int(* delete_user)(const struct gatekeeper_device *dev, uint32_t uid)

Definition at line 159 of file gatekeeper.h .

int(* enroll)(const struct gatekeeper_device *dev, uint32_t uid, const uint8_t *current_password_handle, uint32_t current_password_handle_length, const uint8_t *current_password, uint32_t current_password_length, const uint8_t *desired_password, uint32_t desired_password_length, uint8_t **enrolled_password_handle, uint32_t *enrolled_password_handle_length)

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

If there was already a password enrolled, it should be provided in current_password_handle, along with the current password in current_password that should validate against current_password_handle.

Parameters:

  • dev: pointer to gatekeeper_device acquired via calls to gatekeeper_open
  • uid: the Android user identifier
  • current_password_handle: the currently enrolled password handle the user wants to replace. May be null if there's no currently enrolled password.
  • current_password_handle_length: the length in bytes of the buffer pointed at by current_password_handle. Must be 0 if current_password_handle is NULL.
  • current_password: the user's current password in plain text. If presented, it MUST verify against current_password_handle.
  • current_password_length: the size in bytes of the buffer pointed at by current_password. Must be 0 if the current_password is NULL.
  • desired_password: the new password the user wishes to enroll in plain-text. Cannot be NULL.
  • desired_password_length: the length in bytes of the buffer pointed at by desired_password.
  • enrolled_password_handle: on success, a buffer will be allocated with the new password handle referencing the password provided in desired_password. This buffer can be used on subsequent calls to enroll or verify. The caller is responsible for deallocating this buffer via a call to delete[]
  • enrolled_password_handle_length: pointer to the length in bytes of the buffer allocated by this function and pointed to by *enrolled_password_handle_length.

Returns:

  • 0 on success
  • An error code < 0 on failure, or
  • A timeout value T > 0 if the call should not be re-attempted until T milliseconds have elapsed.

On error, enrolled_password_handle will not be allocated.

Definition at line 91 of file gatekeeper.h .

int(* verify)(const struct gatekeeper_device *dev, uint32_t uid, uint64_t challenge, const uint8_t *enrolled_password_handle, uint32_t enrolled_password_handle_length, const uint8_t *provided_password, uint32_t provided_password_length, uint8_t **auth_token, uint32_t *auth_token_length, bool *request_reenroll)

Verifies provided_password matches enrolled_password_handle.

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

On success, writes the address of a verification token to auth_token, usable to attest password verification to other trusted services. Clients may pass NULL for this value.

Parameters:

  • dev: pointer to gatekeeper_device acquired via calls to gatekeeper_open
  • 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.
  • enrolled_password_handle: the currently enrolled password handle that the user wishes to verify against.
  • enrolled_password_handle_length: the length in bytes of the buffer pointed to by enrolled_password_handle
  • provided_password: the plaintext password to be verified against the enrolled_password_handle
  • provided_password_length: the length in bytes of the buffer pointed to by provided_password
  • auth_token: on success, a buffer containing the authentication token resulting from this verification is assigned to *auth_token. The caller is responsible for deallocating this memory via a call to delete[]
  • auth_token_length: on success, the length in bytes of the authentication token assigned to *auth_token will be assigned to *auth_token_length
  • request_reenroll: a request to the upper layers to re-enroll the verified password due to a version change. Not set if verification fails.

Returns:

  • 0 on success
  • An error code < 0 on failure, or
  • A timeout value T > 0 if the call should not be re-attempted until T milliseconds have elapsed. On error, auth token will not be allocated

Definition at line 141 of file gatekeeper.h .

The documentation for this struct was generated from the following file: