1 /* 2 * Copyright (C) 2014 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_INCLUDE_HARDWARE_FINGERPRINT_H 18 #define ANDROID_INCLUDE_HARDWARE_FINGERPRINT_H 19 20 #include <hardware/hw_auth_token.h> 21 22 #define FINGERPRINT_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0) 23 #define FINGERPRINT_MODULE_API_VERSION_2_0 HARDWARE_MODULE_API_VERSION(2, 0) 24 #define FINGERPRINT_HARDWARE_MODULE_ID "fingerprint" 25 26 typedef enum fingerprint_msg_type { 27 FINGERPRINT_ERROR = -1, 28 FINGERPRINT_ACQUIRED = 1, 29 FINGERPRINT_TEMPLATE_ENROLLING = 3, 30 FINGERPRINT_TEMPLATE_REMOVED = 4, 31 FINGERPRINT_AUTHENTICATED = 5 32 } fingerprint_msg_type_t; 33 34 /* 35 * Fingerprint errors are meant to tell the framework to terminate the current operation and ask 36 * for the user to correct the situation. These will almost always result in messaging and user 37 * interaction to correct the problem. 38 * 39 * For example, FINGERPRINT_ERROR_CANCELED should follow any acquisition message that results in 40 * a situation where the current operation can't continue without user interaction. For example, 41 * if the sensor is dirty during enrollment and no further enrollment progress can be made, 42 * send FINGERPRINT_ACQUIRED_IMAGER_DIRTY followed by FINGERPRINT_ERROR_CANCELED. 43 */ 44 typedef enum fingerprint_error { 45 FINGERPRINT_ERROR_HW_UNAVAILABLE = 1, /* The hardware has an error that can't be resolved. */ 46 FINGERPRINT_ERROR_UNABLE_TO_PROCESS = 2, /* Bad data; operation can't continue */ 47 FINGERPRINT_ERROR_TIMEOUT = 3, /* The operation has timed out waiting for user input. */ 48 FINGERPRINT_ERROR_NO_SPACE = 4, /* No space available to store a template */ 49 FINGERPRINT_ERROR_CANCELED = 5, /* The current operation can't proceed. See above. */ 50 FINGERPRINT_ERROR_UNABLE_TO_REMOVE = 6, /* fingerprint with given id can't be removed */ 51 FINGERPRINT_ERROR_VENDOR_BASE = 1000 /* vendor-specific error messages start here */ 52 } fingerprint_error_t; 53 54 /* 55 * Fingerprint acquisition info is meant as feedback for the current operation. Anything but 56 * FINGERPRINT_ACQUIRED_GOOD will be shown to the user as feedback on how to take action on the 57 * current operation. For example, FINGERPRINT_ACQUIRED_IMAGER_DIRTY can be used to tell the user 58 * to clean the sensor. If this will cause the current operation to fail, an additional 59 * FINGERPRINT_ERROR_CANCELED can be sent to stop the operation in progress (e.g. enrollment). 60 * In general, these messages will result in a "Try again" message. 61 */ 62 typedef enum fingerprint_acquired_info { 63 FINGERPRINT_ACQUIRED_GOOD = 0, 64 FINGERPRINT_ACQUIRED_PARTIAL = 1, /* sensor needs more data, i.e. longer swipe. */ 65 FINGERPRINT_ACQUIRED_INSUFFICIENT = 2, /* image doesn't contain enough detail for recognition*/ 66 FINGERPRINT_ACQUIRED_IMAGER_DIRTY = 3, /* sensor needs to be cleaned */ 67 FINGERPRINT_ACQUIRED_TOO_SLOW = 4, /* mostly swipe-type sensors; not enough data collected */ 68 FINGERPRINT_ACQUIRED_TOO_FAST = 5, /* for swipe and area sensors; tell user to slow down*/ 69 FINGERPRINT_ACQUIRED_VENDOR_BASE = 1000 /* vendor-specific acquisition messages start here */ 70 } fingerprint_acquired_info_t; 71 72 typedef struct fingerprint_finger_id { 73 uint32_t gid; 74 uint32_t fid; 75 } fingerprint_finger_id_t; 76 77 typedef struct fingerprint_enroll { 78 fingerprint_finger_id_t finger; 79 /* samples_remaining goes from N (no data collected, but N scans needed) 80 * to 0 (no more data is needed to build a template). */ 81 uint32_t samples_remaining; 82 uint64_t msg; /* Vendor specific message. Used for user guidance */ 83 } fingerprint_enroll_t; 84 85 typedef struct fingerprint_removed { 86 fingerprint_finger_id_t finger; 87 } fingerprint_removed_t; 88 89 typedef struct fingerprint_acquired { 90 fingerprint_acquired_info_t acquired_info; /* information about the image */ 91 } fingerprint_acquired_t; 92 93 typedef struct fingerprint_authenticated { 94 fingerprint_finger_id_t finger; 95 hw_auth_token_t hat; 96 } fingerprint_authenticated_t; 97 98 typedef struct fingerprint_msg { 99 fingerprint_msg_type_t type; 100 union { 101 fingerprint_error_t error; 102 fingerprint_enroll_t enroll; 103 fingerprint_removed_t removed; 104 fingerprint_acquired_t acquired; 105 fingerprint_authenticated_t authenticated; 106 } data; 107 } fingerprint_msg_t; 108 109 /* Callback function type */ 110 typedef void (*fingerprint_notify_t)(const fingerprint_msg_t *msg); 111 112 /* Synchronous operation */ 113 typedef struct fingerprint_device { 114 /** 115 * Common methods of the fingerprint device. This *must* be the first member 116 * of fingerprint_device as users of this structure will cast a hw_device_t 117 * to fingerprint_device pointer in contexts where it's known 118 * the hw_device_t references a fingerprint_device. 119 */ 120 struct hw_device_t common; 121 122 /* 123 * Client provided callback function to receive notifications. 124 * Do not set by hand, use the function above instead. 125 */ 126 fingerprint_notify_t notify; 127 128 /* 129 * Set notification callback: 130 * Registers a user function that would receive notifications from the HAL 131 * The call will block if the HAL state machine is in busy state until HAL 132 * leaves the busy state. 133 * 134 * Function return: 0 if callback function is successfuly registered 135 * or a negative number in case of error, generally from the errno.h set. 136 */ 137 int (*set_notify)(struct fingerprint_device *dev, fingerprint_notify_t notify); 138 139 /* 140 * Fingerprint pre-enroll enroll request: 141 * Generates a unique token to upper layers to indicate the start of an enrollment transaction. 142 * This token will be wrapped by security for verification and passed to enroll() for 143 * verification before enrollment will be allowed. This is to ensure adding a new fingerprint 144 * template was preceded by some kind of credential confirmation (e.g. device password). 145 * 146 * Function return: 0 if function failed 147 * otherwise, a uint64_t of token 148 */ 149 uint64_t (*pre_enroll)(struct fingerprint_device *dev); 150 151 /* 152 * Fingerprint enroll request: 153 * Switches the HAL state machine to collect and store a new fingerprint 154 * template. Switches back as soon as enroll is complete 155 * (fingerprint_msg.type == FINGERPRINT_TEMPLATE_ENROLLING && 156 * fingerprint_msg.data.enroll.samples_remaining == 0) 157 * or after timeout_sec seconds. 158 * The fingerprint template will be assigned to the group gid. User has a choice 159 * to supply the gid or set it to 0 in which case a unique group id will be generated. 160 * 161 * Function return: 0 if enrollment process can be successfully started 162 * or a negative number in case of error, generally from the errno.h set. 163 * A notify() function may be called indicating the error condition. 164 */ 165 int (*enroll)(struct fingerprint_device *dev, const hw_auth_token_t *hat, 166 uint32_t gid, uint32_t timeout_sec); 167 168 /* 169 * Finishes the enroll operation and invalidates the pre_enroll() generated challenge. 170 * This will be called at the end of a multi-finger enrollment session to indicate 171 * that no more fingers will be added. 172 * 173 * Function return: 0 if the request is accepted 174 * or a negative number in case of error, generally from the errno.h set. 175 */ 176 int (*post_enroll)(struct fingerprint_device *dev); 177 178 /* 179 * get_authenticator_id: 180 * Returns a token associated with the current fingerprint set. This value will 181 * change whenever a new fingerprint is enrolled, thus creating a new fingerprint 182 * set. 183 * 184 * Function return: current authenticator id or 0 if function failed. 185 */ 186 uint64_t (*get_authenticator_id)(struct fingerprint_device *dev); 187 188 /* 189 * Cancel pending enroll or authenticate, sending FINGERPRINT_ERROR_CANCELED 190 * to all running clients. Switches the HAL state machine back to the idle state. 191 * Unlike enroll_done() doesn't invalidate the pre_enroll() challenge. 192 * 193 * Function return: 0 if cancel request is accepted 194 * or a negative number in case of error, generally from the errno.h set. 195 */ 196 int (*cancel)(struct fingerprint_device *dev); 197 198 /* 199 * Enumerate all the fingerprint templates found in the directory set by 200 * set_active_group() 201 * This is a synchronous call. The function takes: 202 * - A pointer to an array of fingerprint_finger_id_t. 203 * - The size of the array provided, in fingerprint_finger_id_t elements. 204 * Max_size is a bi-directional parameter and returns the actual number 205 * of elements copied to the caller supplied array. 206 * In the absence of errors the function returns the total number of templates 207 * in the user directory. 208 * If the caller has no good guess on the size of the array he should call this 209 * function witn *max_size == 0 and use the return value for the array allocation. 210 * The caller of this function has a complete list of the templates when *max_size 211 * is the same as the function return. 212 * 213 * Function return: Total number of fingerprint templates in the current storage directory. 214 * or a negative number in case of error, generally from the errno.h set. 215 */ 216 int (*enumerate)(struct fingerprint_device *dev, fingerprint_finger_id_t *results, 217 uint32_t *max_size); 218 219 /* 220 * Fingerprint remove request: 221 * Deletes a fingerprint template. 222 * Works only within a path set by set_active_group(). 223 * notify() will be called with details on the template deleted. 224 * fingerprint_msg.type == FINGERPRINT_TEMPLATE_REMOVED and 225 * fingerprint_msg.data.removed.id indicating the template id removed. 226 * 227 * Function return: 0 if fingerprint template(s) can be successfully deleted 228 * or a negative number in case of error, generally from the errno.h set. 229 */ 230 int (*remove)(struct fingerprint_device *dev, uint32_t gid, uint32_t fid); 231 232 /* 233 * Restricts the HAL operation to a set of fingerprints belonging to a 234 * group provided. 235 * The caller must provide a path to a storage location within the user's 236 * data directory. 237 * 238 * Function return: 0 on success 239 * or a negative number in case of error, generally from the errno.h set. 240 */ 241 int (*set_active_group)(struct fingerprint_device *dev, uint32_t gid, 242 const char *store_path); 243 244 /* 245 * Authenticates an operation identifed by operation_id 246 * 247 * Function return: 0 on success 248 * or a negative number in case of error, generally from the errno.h set. 249 */ 250 int (*authenticate)(struct fingerprint_device *dev, uint64_t operation_id, uint32_t gid); 251 252 /* Reserved for backward binary compatibility */ 253 void *reserved[4]; 254 } fingerprint_device_t; 255 256 typedef struct fingerprint_module { 257 /** 258 * Common methods of the fingerprint module. This *must* be the first member 259 * of fingerprint_module as users of this structure will cast a hw_module_t 260 * to fingerprint_module pointer in contexts where it's known 261 * the hw_module_t references a fingerprint_module. 262 */ 263 struct hw_module_t common; 264 } fingerprint_module_t; 265 266 #endif /* ANDROID_INCLUDE_HARDWARE_FINGERPRINT_H */ 267