Add some guidance documentation to the emulator
Because fingerprint HAL is vendor-specific due to the
Trusted Execution Environment (TEE) requirements, source
is not provided in AOSP. As such, this example is a
reasonable place to document some of the requirements
and expectations.
Fixes bug 23045367
Change-Id: Iacf14d6d32b468464215320b411ef7ff1a387ff0
diff --git a/fingerprint/fingerprint.c b/fingerprint/fingerprint.c
index c3dc787..1b26b8f 100644
--- a/fingerprint/fingerprint.c
+++ b/fingerprint/fingerprint.c
@@ -14,10 +14,24 @@
* limitations under the License.
*/
+/**
+ * This is a very basic implementation of fingerprint to allow testing on the emulator. It
+ * is *not* meant to be the final implementation on real devices. For example, it does *not*
+ * implement all of the required features, such as secure template storage and recognition
+ * inside a Trusted Execution Environment (TEE). However, this file is a reasonable starting
+ * point as developers add fingerprint support to their platform. See inline comments and
+ * recommendations for details.
+ *
+ * Please see the Android Compatibility Definition Document (CDD) for a full list of requirements
+ * and suggestions.
+ */
#define FINGERPRINT_LISTEN_SERVICE_NAME "fingerprintlisten"
#define FINGERPRINT_TXT_FILENAME "/data/fingerprint.txt"
#define LOG_TAG "FingerprintHal"
+
+// Typical devices will allow up to 5 fingerprints per user to maintain performance of
+// t < 500ms for recognition. This is the total number of fingerprints we'll store.
#define MAX_NUM_FINGERS 32
#include <errno.h>
@@ -30,11 +44,19 @@
#include <hardware/fingerprint.h>
#include <hardware/qemud.h>
+/**
+ * Most devices will have an internal state machine resembling this. There are 3 basic states, as
+ * shown below. When device is not authenticating or enrolling, it is expected to be in
+ * the idle state.
+ *
+ * Note that this is completely independent of device wake state. If the hardware device was in
+ * the "scan" state when the device drops into power collapse, it should resume scanning when power
+ * is restored. This is to facilitate rapid touch-to-unlock from keyguard.
+ */
typedef enum worker_state_t {
STATE_ENROLL = 1,
STATE_SCAN = 2,
STATE_IDLE = 3,
- STATE_EXIT = 4
} worker_state_t;
typedef struct worker_thread_t {
@@ -63,6 +85,9 @@
} emu_fingerprint_hal_device_t;
static uint64_t get_64bit_rand() {
+ // This should use a cryptographically-secure random number generator like arc4random().
+ // It should be generated inside of the TEE where possible. Here we just use something
+ // very simple.
return (((uint64_t) rand()) << 32) | ((uint64_t) rand());
}
@@ -90,6 +115,9 @@
fflush(fp);
}
+/**
+ * This is the communication channel from the HAL layer to fingerprintd.
+ */
static void listener_send_notice(emu_fingerprint_hal_device_t* dev)
{
fingerprint_msg_t message = {0};
@@ -103,11 +131,13 @@
dev->authenticator_id = get_64bit_rand();
dev->listener.state = STATE_SCAN;
if (!finger_already_enrolled(dev)) {
- dev->listener.all_fingerids[dev->listener.num_fingers_enrolled % MAX_NUM_FINGERS] = dev->listener.fingerid;
- dev->listener.all_secureids[dev->listener.num_fingers_enrolled % MAX_NUM_FINGERS] = dev->secure_user_id;
- dev->listener.all_authenids[dev->listener.num_fingers_enrolled % MAX_NUM_FINGERS] = dev->authenticator_id;
+ const int n = dev->listener.num_fingers_enrolled % MAX_NUM_FINGERS;
+ dev->listener.all_fingerids[n] = dev->listener.fingerid;
+ dev->listener.all_secureids[n] = dev->secure_user_id;
+ dev->listener.all_authenids[n] = dev->authenticator_id;
++ dev->listener.num_fingers_enrolled;
- save_fingerid(dev->listener.fp_write, dev->listener.fingerid, dev->secure_user_id, dev->authenticator_id);
+ save_fingerid(dev->listener.fp_write, dev->listener.fingerid, dev->secure_user_id,
+ dev->authenticator_id);
is_valid_finger = true;
}
} else {
@@ -141,6 +171,29 @@
pthread_mutex_unlock(&dev->lock);
}
+/**
+ * This a very simple event loop for the fingerprint sensor. For a given state (enroll, scan),
+ * this would receive events from the sensor and forward them to fingerprintd using the
+ * notify() method.
+ *
+ * In this simple example, we open a qemu channel (a pipe) where the developer can inject events to
+ * exercise the API and test application code.
+ *
+ * The scanner should remain in the scanning state until either an error occurs or the operation
+ * completes.
+ *
+ * Recoverable errors such as EINTR should be handled locally; they should not
+ * be propagated unless there's something the user can do about it (e.g. "clean sensor"). Such
+ * messages should go through the onAcquired() interface.
+ *
+ * If an unrecoverable error occurs, an acquired message (e.g. ACQUIRED_PARTIAL) should be sent,
+ * followed by an error message (e.g. FINGERPRINT_ERROR_UNABLE_TO_PROCESS).
+ *
+ * Note that this event loop would typically run in TEE since it must interact with the sensor
+ * hardware and handle raw fingerprint data and encrypted templates. It is expected that
+ * this code monitors the TEE for resulting events, such as enrollment and authentication status.
+ * Here we just have a very simple event loop that monitors a qemu channel for pseudo events.
+ */
static void* listenerFunction(void* data)
{
emu_fingerprint_hal_device_t* dev = (emu_fingerprint_hal_device_t*) data;
@@ -171,9 +224,10 @@
uint64_t secureid = 0;
uint64_t authenid = 0;
if(fscanf(fp_stored, "%d %" SCNu64 " %" SCNu64, &fingerid, &secureid, &authenid) == 3) {
- dev->listener.all_fingerids[dev->listener.num_fingers_enrolled % MAX_NUM_FINGERS] = fingerid;
- dev->listener.all_secureids[dev->listener.num_fingers_enrolled % MAX_NUM_FINGERS] = secureid;
- dev->listener.all_authenids[dev->listener.num_fingers_enrolled % MAX_NUM_FINGERS] = authenid;
+ const int n = dev->listener.num_fingers_enrolled % MAX_NUM_FINGERS;
+ dev->listener.all_fingerids[n] = fingerid;
+ dev->listener.all_secureids[n] = secureid;
+ dev->listener.all_authenids[n] = authenid;
++ dev->listener.num_fingers_enrolled;
} else {
break;
@@ -243,16 +297,28 @@
}
static uint64_t fingerprint_get_auth_id(struct fingerprint_device __unused *device) {
+ // This should return the authentication_id generated when the fingerprint template database
+ // was created. Though this isn't expected to be secret, it is reasonable to expect it to be
+ // cryptographically generated to avoid replay attacks.
emu_fingerprint_hal_device_t* dev = (emu_fingerprint_hal_device_t*) device;
return dev->authenticator_id;
}
static int fingerprint_set_active_group(struct fingerprint_device __unused *device, uint32_t gid,
const char *path) {
- // TODO: implements me
+ // Groups are a future feature. For now, the framework sends the profile owner's id (userid)
+ // as the primary group id for the user. This code should create a tuple (groupId, fingerId)
+ // that represents a single fingerprint entity in the database. For now we just generate
+ // globally unique ids.
return 0;
}
+/**
+ * If fingerprints are enrolled, then this function is expected to put the sensor into a
+ * "scanning" state where it's actively scanning and recognizing fingerprint features.
+ * Actual authentication must happen in TEE and should be monitored in a separate thread
+ * since this function is expected to return immediately.
+ */
static int fingerprint_authenticate(struct fingerprint_device __unused *device,
uint64_t __unused operation_id, __unused uint32_t gid)
{
@@ -266,6 +332,15 @@
return 0;
}
+/**
+ * This is expected to put the sensor into an "enroll" state where it's actively scanning and
+ * working towards a finished fingerprint database entry. Authentication must happen in
+ * a separate thread since this function is expected to return immediately.
+ *
+ * Note: This method should always generate a new random authenticator_id.
+ *
+ * Note: As with fingerprint_authenticate(), this would run in TEE on a real device.
+ */
static int fingerprint_enroll(struct fingerprint_device *device,
const hw_auth_token_t *hat,
uint32_t __unused gid,
@@ -273,6 +348,9 @@
ALOGD("fingerprint_enroll");
emu_fingerprint_hal_device_t* dev = (emu_fingerprint_hal_device_t*) device;
if (hat && hat->challenge == dev->challenge) {
+ // The secure_user_id retrieved from the auth token should be stored
+ // with the enrolled fingerprint template and returned in the auth result
+ // for a successful authentication with that finger.
dev->secure_user_id = hat->user_id;
} else {
ALOGW("%s: invalid or null auth token", __func__);
@@ -293,13 +371,26 @@
}
+/**
+ * The pre-enrollment step is simply to get an authentication token that can be wrapped and
+ * verified at a later step. The primary purpose is to return a token that protects against
+ * spoofing and replay attacks. It is passed to password authentication where it is wrapped and
+ * propagated to the enroll step.
+ */
static uint64_t fingerprint_pre_enroll(struct fingerprint_device *device) {
ALOGD("fingerprint_pre_enroll");
emu_fingerprint_hal_device_t* dev = (emu_fingerprint_hal_device_t*) device;
+ // The challenge will typically be a cryptographically-secure key
+ // coming from the TEE so it can be verified at a later step. For now we just generate a
+ // random value.
dev->challenge = get_64bit_rand();
return dev->challenge;
}
+/**
+ * Cancel is called by the framework to cancel an outstanding event. This should *not* be called
+ * by the driver since it will cause the framework to stop listening for fingerprints.
+ */
static int fingerprint_cancel(struct fingerprint_device __unused *device) {
ALOGD("fingerprint_cancel");
emu_fingerprint_hal_device_t* dev = (emu_fingerprint_hal_device_t*) device;
@@ -357,6 +448,10 @@
dev->device.set_notify = set_notify_callback;
dev->device.notify = NULL;
+ // This is typically a cryptographically-secure token generated when the private fingerprint
+ // template database is created. For simplicity of this driver, we store a recognizable value.
+ //
+ // Real devices should *not* use this token!
dev->authenticator_id = 0xdeadbeef;
pthread_mutex_init(&dev->lock, NULL);
