1 /* 2 * Copyright (C) 2015 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef ANDROID_HARDWARE_GATEKEEPER_H 18 #define ANDROID_HARDWARE_GATEKEEPER_H 19 20 #include <sys/cdefs.h> 21 #include <sys/types.h> 22 #include <hardware/hardware.h> 23 24 __BEGIN_DECLS 25 26 #define GATEKEEPER_HARDWARE_MODULE_ID "gatekeeper" 27 28 #define GATEKEEPER_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) 29 30 #define HARDWARE_GATEKEEPER "gatekeeper" 31 32 struct gatekeeper_module { 33 /** 34 * Comon methods of the gatekeeper module. This *must* be the first member of 35 * gatekeeper_module as users of this structure will cast a hw_module_t to 36 * a gatekeeper_module pointer in the appropriate context. 37 */ 38 hw_module_t common; 39 }; 40 41 struct gatekeeper_device { 42 /** 43 * Common methods of the gatekeeper device. As above, this must be the first 44 * member of keymaster_device. 45 */ 46 hw_device_t common; 47 48 /** 49 * Enrolls desired_password, which should be derived from a user selected pin or password, 50 * with the authentication factor private key used only for enrolling authentication 51 * factor data. 52 * 53 * If there was already a password enrolled, it should be provided in 54 * current_password_handle, along with the current password in current_password 55 * that should validate against current_password_handle. 56 * 57 * Parameters: 58 * - dev: pointer to gatekeeper_device acquired via calls to gatekeeper_open 59 * - uid: the Android user identifier 60 * 61 * - current_password_handle: the currently enrolled password handle the user 62 * wants to replace. May be null if there's no currently enrolled password. 63 * - current_password_handle_length: the length in bytes of the buffer pointed 64 * at by current_password_handle. Must be 0 if current_password_handle is NULL. 65 * 66 * - current_password: the user's current password in plain text. If presented, 67 * it MUST verify against current_password_handle. 68 * - current_password_length: the size in bytes of the buffer pointed at by 69 * current_password. Must be 0 if the current_password is NULL. 70 * 71 * - desired_password: the new password the user wishes to enroll in plain-text. 72 * Cannot be NULL. 73 * - desired_password_length: the length in bytes of the buffer pointed at by 74 * desired_password. 75 * 76 * - enrolled_password_handle: on success, a buffer will be allocated with the 77 * new password handle referencing the password provided in desired_password. 78 * This buffer can be used on subsequent calls to enroll or verify. 79 * The caller is responsible for deallocating this buffer via a call to delete[] 80 * - enrolled_password_handle_length: pointer to the length in bytes of the buffer allocated 81 * by this function and pointed to by *enrolled_password_handle_length. 82 * 83 * Returns: 84 * - 0 on success 85 * - An error code < 0 on failure, or 86 * - A timeout value T > 0 if the call should not be re-attempted until T milliseconds 87 * have elapsed. 88 * 89 * On error, enrolled_password_handle will not be allocated. 90 */ 91 int (*enroll)(const struct gatekeeper_device *dev, uint32_t uid, 92 const uint8_t *current_password_handle, uint32_t current_password_handle_length, 93 const uint8_t *current_password, uint32_t current_password_length, 94 const uint8_t *desired_password, uint32_t desired_password_length, 95 uint8_t **enrolled_password_handle, uint32_t *enrolled_password_handle_length); 96 97 /** 98 * Verifies provided_password matches enrolled_password_handle. 99 * 100 * Implementations of this module may retain the result of this call 101 * to attest to the recency of authentication. 102 * 103 * On success, writes the address of a verification token to auth_token, 104 * usable to attest password verification to other trusted services. Clients 105 * may pass NULL for this value. 106 * 107 * Parameters: 108 * - dev: pointer to gatekeeper_device acquired via calls to gatekeeper_open 109 * - uid: the Android user identifier 110 * 111 * - challenge: An optional challenge to authenticate against, or 0. Used when a separate 112 * authenticator requests password verification, or for transactional 113 * password authentication. 114 * 115 * - enrolled_password_handle: the currently enrolled password handle that the 116 * user wishes to verify against. 117 * - enrolled_password_handle_length: the length in bytes of the buffer pointed 118 * to by enrolled_password_handle 119 * 120 * - provided_password: the plaintext password to be verified against the 121 * enrolled_password_handle 122 * - provided_password_length: the length in bytes of the buffer pointed to by 123 * provided_password 124 * 125 * - auth_token: on success, a buffer containing the authentication token 126 * resulting from this verification is assigned to *auth_token. The caller 127 * is responsible for deallocating this memory via a call to delete[] 128 * - auth_token_length: on success, the length in bytes of the authentication 129 * token assigned to *auth_token will be assigned to *auth_token_length 130 * 131 * - request_reenroll: a request to the upper layers to re-enroll the verified 132 * password due to a version change. Not set if verification fails. 133 * 134 * Returns: 135 * - 0 on success 136 * - An error code < 0 on failure, or 137 * - A timeout value T > 0 if the call should not be re-attempted until T milliseconds 138 * have elapsed. 139 * On error, auth token will not be allocated 140 */ 141 int (*verify)(const struct gatekeeper_device *dev, uint32_t uid, uint64_t challenge, 142 const uint8_t *enrolled_password_handle, uint32_t enrolled_password_handle_length, 143 const uint8_t *provided_password, uint32_t provided_password_length, 144 uint8_t **auth_token, uint32_t *auth_token_length, bool *request_reenroll); 145 146 /* 147 * Deletes the enrolled_password_handle associated wth the uid. Once deleted 148 * the user cannot be verified anymore. 149 * This function is optional and should be set to NULL if it is not implemented. 150 * 151 * Parameters 152 * - dev: pointer to gatekeeper_device acquired via calls to gatekeeper_open 153 * - uid: the Android user identifier 154 * 155 * Returns: 156 * - 0 on success 157 * - An error code < 0 on failure 158 */ 159 int (*delete_user)(const struct gatekeeper_device *dev, uint32_t uid); 160 161 /* 162 * Deletes all the enrolled_password_handles for all uid's. Once called, 163 * no users will be enrolled on the device. 164 * This function is optional and should be set to NULL if it is not implemented. 165 * 166 * Parameters 167 * - dev: pointer to gatekeeper_device acquired via calls to gatekeeper_open 168 * 169 * Returns: 170 * - 0 on success 171 * - An error code < 0 on failure 172 */ 173 int (*delete_all_users)(const struct gatekeeper_device *dev); 174 }; 175 176 typedef struct gatekeeper_device gatekeeper_device_t; 177 178 static inline int gatekeeper_open(const struct hw_module_t *module, 179 gatekeeper_device_t **device) { 180 return module->methods->open(module, HARDWARE_GATEKEEPER, 181 (struct hw_device_t **) device); 182 } 183 184 static inline int gatekeeper_close(gatekeeper_device_t *device) { 185 return device->common.close(&device->common); 186 } 187 188 __END_DECLS 189 190 #endif // ANDROID_HARDWARE_GATEKEEPER_H 191
