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