include/hardware/fingerprint.h

   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 typedef enum fingerprint_error {
  35     FINGERPRINT_ERROR_HW_UNAVAILABLE = 1,
  36     FINGERPRINT_ERROR_UNABLE_TO_PROCESS = 2,
  37     FINGERPRINT_ERROR_TIMEOUT = 3,
  38     FINGERPRINT_ERROR_NO_SPACE = 4, /* No space available to store a template */
  39     FINGERPRINT_ERROR_CANCELED = 5,
  40     FINGERPRINT_ERROR_UNABLE_TO_REMOVE = 6, /* fingerprint id can't be removed */
  41     FINGERPRINT_ERROR_VENDOR_BASE = 1000 /* vendor-specific error messages start here */
  42 } fingerprint_error_t;
  43
  44 typedef enum fingerprint_acquired_info {
  45     FINGERPRINT_ACQUIRED_GOOD = 0,
  46     FINGERPRINT_ACQUIRED_PARTIAL = 1,
  47     FINGERPRINT_ACQUIRED_INSUFFICIENT = 2,
  48     FINGERPRINT_ACQUIRED_IMAGER_DIRTY = 3,
  49     FINGERPRINT_ACQUIRED_TOO_SLOW = 4,
  50     FINGERPRINT_ACQUIRED_TOO_FAST = 5,
  51     FINGERPRINT_ACQUIRED_VENDOR_BASE = 1000 /* vendor-specific acquisition messages start here */
  52 } fingerprint_acquired_info_t;
  53
  54 typedef struct fingerprint_finger_id {
  55     uint32_t gid;
  56     uint32_t fid;
  57 } fingerprint_finger_id_t;
  58
  59 /* The progress indication may be augmented by a bitmap encoded indication
  60 * of what finger area is considered as collected.
  61 * Bit numbers mapped to physical location:
  62 *
  63 *             distal
  64 *        +--+--+--+--+--+
  65 *        | 4| 3| 2| 1| 0|
  66 *        | 9| 8| 7| 6| 5|
  67 * medial |14|13|12|11|10| lateral
  68 *        |19|18|17|16|15|
  69 *        |24|23|22|21|20|
  70 *        +--+--+--+--+--+
  71 *            proximal
  72 *
  73 */
  74 typedef uint32_t finger_map_bmp;
  75
  76 typedef enum fingerprint_enroll_msg_type {
  77     FINGERPRINT_ENROLL_MSG_NONE = 0,
  78     FINGERPRINT_ENROLL_MSG_PREDEFINED = 1,  /* TODO: define standard enroll cues */
  79     FINGERPRINT_ENROLL_MSG_BITMAP = 2,  /* typeof(fingerprint_enroll.msg) == *finger_map_bmp */
  80     FINGERPRINT_ENROLL_MSG_VENDOR = 3
  81 } fingerprint_enroll_msg_type_t;
  82
  83 typedef struct fingerprint_enroll {
  84     fingerprint_finger_id_t finger;
  85     /* samples_remaining goes from N (no data collected, but N scans needed)
  86      * to 0 (no more data is needed to build a template). */
  87     uint32_t samples_remaining;
  88     fingerprint_enroll_msg_type_t msg_type;
  89     size_t msg_size;
  90     void *msg;
  91 } fingerprint_enroll_t;
  92
  93 typedef struct fingerprint_removed {
  94     fingerprint_finger_id_t finger;
  95 } fingerprint_removed_t;
  96
  97 typedef struct fingerprint_acquired {
  98     fingerprint_acquired_info_t acquired_info; /* information about the image */
  99 } fingerprint_acquired_t;
 100
 101 typedef struct fingerprint_authenticated {
 102     fingerprint_finger_id_t finger;
 103     hw_auth_token_t hat;
 104 } fingerprint_authenticated_t;
 105
 106 typedef struct fingerprint_msg {
 107     fingerprint_msg_type_t type;
 108     union {
 109         fingerprint_error_t error;
 110         fingerprint_enroll_t enroll;
 111         fingerprint_removed_t removed;
 112         fingerprint_acquired_t acquired;
 113         fingerprint_authenticated_t authenticated;
 114     } data;
 115 } fingerprint_msg_t;
 116
 117 /* Callback function type */
 118 typedef void (*fingerprint_notify_t)(fingerprint_msg_t msg);
 119
 120 /* Synchronous operation */
 121 typedef struct fingerprint_device {
 122     /**
 123      * Common methods of the fingerprint device. This *must* be the first member
 124      * of fingerprint_device as users of this structure will cast a hw_device_t
 125      * to fingerprint_device pointer in contexts where it's known
 126      * the hw_device_t references a fingerprint_device.
 127      */
 128     struct hw_device_t common;
 129
 130     /*
 131      * Fingerprint enroll request:
 132      * Switches the HAL state machine to collect and store a new fingerprint
 133      * template. Switches back as soon as enroll is complete
 134      * (fingerprint_msg.type == FINGERPRINT_TEMPLATE_ENROLLING &&
 135      *  fingerprint_msg.data.enroll.samples_remaining == 0)
 136      * or after timeout_sec seconds.
 137      * The fingerprint template will be assigned to the group gid. User has a choice
 138      * to supply the gid or set it to 0 in which case a unique group id will be generated.
 139      *
 140      * Function return: 0 if enrollment process can be successfully started
 141      *                 -1 otherwise. A notify() function may be called
 142      *                    indicating the error condition.
 143      */
 144     int (*enroll)(struct fingerprint_device *dev, const hw_auth_token_t *hat,
 145                     uint32_t gid, uint32_t timeout_sec);
 146
 147     /*
 148      * Fingerprint pre-enroll enroll request:
 149      * Generates a unique token to upper layers to indicate the start of an enrollment transaction.
 150      * This token will be wrapped by security for verification and passed to enroll() for
 151      * verification before enrollment will be allowed. This is to ensure adding a new fingerprint
 152      * template was preceded by some kind of credential confirmation (e.g. device password).
 153      *
 154      * Function return: 0 if function failed
 155      *                  otherwise, a uint64_t of token
 156      */
 157     uint64_t (*pre_enroll)(struct fingerprint_device *dev);
 158
 159     /*
 160      * get_authenticator_id:
 161      * Returns a token associated with the current fingerprint set. This value will
 162      * change whenever a new fingerprint is enrolled, thus creating a new fingerprint
 163      * set.
 164      *
 165      * Function return: current authenticator id.
 166      */
 167     uint64_t (*get_authenticator_id)(struct fingerprint_device *dev);
 168
 169     /*
 170      * Cancel pending enroll or authenticate, sending FINGERPRINT_ERROR_CANCELED
 171      * to all running clients. Switches the HAL state machine back to the idle state.
 172      * will indicate switch back to the scan mode.
 173      *
 174      * Function return: 0 if cancel request is accepted
 175      *                 -1 otherwise.
 176      */
 177     int (*cancel)(struct fingerprint_device *dev);
 178
 179     /*
 180      * Enumerate all the fingerprint templates found in the directory set by
 181      * set_active_group()
 182      * This is a synchronous call. The function takes:
 183      * - A pointer to an array of fingerprint_finger_id_t.
 184      * - The size of the array provided, in fingerprint_finger_id_t elements.
 185      * Max_size is a bi-directional parameter and returns the actual number
 186      * of elements copied to the caller supplied array.
 187      * In the absence of errors the function returns the total number of templates
 188      * in the user directory.
 189      * If the caller has no good guess on the size of the array he should call this
 190      * function witn *max_size == 0 and use the return value for the array allocation.
 191      * The caller of this function has a complete list of the templates when *max_size
 192      * is the same as the function return.
 193      *
 194      * Function return: Total number of fingerprint templates in the current
 195                         storage directory.
 196      *                 -1 on error.
 197      */
 198     int (*enumerate)(struct fingerprint_device *dev, fingerprint_finger_id_t *results,
 199         uint32_t *max_size);
 200
 201     /*
 202      * Fingerprint remove request:
 203      * deletes a fingerprint template.
 204      * If the fingerprint id is 0 and the group is 0 then the entire template
 205      * database will be removed. A combinaiton of fingerprint id 0 and a valid
 206      * group id deletes all fingreprints in that group.
 207      * notify() will be called for each template deleted with
 208      * fingerprint_msg.type == FINGERPRINT_TEMPLATE_REMOVED and
 209      * fingerprint_msg.data.removed.id indicating each template id removed.
 210      *
 211      * Function return: 0 if fingerprint template(s) can be successfully deleted
 212      *                 -1 otherwise.
 213      */
 214     int (*remove)(struct fingerprint_device *dev, fingerprint_finger_id_t finger);
 215
 216     /*
 217      * Restricts the HAL operation to a set of fingerprints belonging to a
 218      * group provided.
 219      * The caller must provide a path to a storage location within the user's
 220      * data directory.
 221      *
 222      * Function return: 0 on success
 223      *                 -1 if the group does not exist.
 224      */
 225     int (*set_active_group)(struct fingerprint_device *dev, uint32_t gid,
 226                             const char *store_path);
 227
 228     /*
 229      * Authenticates an operation identifed by operation_id
 230      *
 231      * Function return: 0 on success
 232      *                 -1 if the operation cannot be completed
 233      */
 234     int (*authenticate)(struct fingerprint_device *dev, uint64_t operation_id, uint32_t gid);
 235
 236     /*
 237      * Set notification callback:
 238      * Registers a user function that would receive notifications from the HAL
 239      * The call will block if the HAL state machine is in busy state until HAL
 240      * leaves the busy state.
 241      *
 242      * Function return: 0 if callback function is successfuly registered
 243      *                 -1 otherwise.
 244      */
 245     int (*set_notify)(struct fingerprint_device *dev, fingerprint_notify_t notify);
 246
 247     /*
 248      * Client provided callback function to receive notifications.
 249      * Do not set by hand, use the function above instead.
 250      */
 251     fingerprint_notify_t notify;
 252 } fingerprint_device_t;
 253
 254 typedef struct fingerprint_module {
 255     /**
 256      * Common methods of the fingerprint module. This *must* be the first member
 257      * of fingerprint_module as users of this structure will cast a hw_module_t
 258      * to fingerprint_module pointer in contexts where it's known
 259      * the hw_module_t references a fingerprint_module.
 260      */
 261     struct hw_module_t common;
 262 } fingerprint_module_t;
 263
 264 #endif  /* ANDROID_INCLUDE_HARDWARE_FINGERPRINT_H */