1/*
2 * Copyright (C) 2017 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
17package android.hardware.biometrics.fingerprint@2.1;
18
19import IBiometricsFingerprintClientCallback;
20
21interface IBiometricsFingerprint {
22  /**
23   * Set notification callback:
24   * Registers a user function that must receive notifications from the HAL
25   * This call must block if the HAL state machine is in busy state until HAL
26   * leaves the busy state.
27   *
28   * @return deviceId is a unique handle for this fingerprint device
29   */
30  @callflow(next={"setActiveGroup"})
31  @entry
32  setNotify(IBiometricsFingerprintClientCallback clientCallback)
33      generates (uint64_t deviceId);
34
35  /**
36   * Fingerprint pre-enroll enroll request:
37   * Generates a unique token to upper layers to indicate the start of
38   * an enrollment transaction. pre-enroll and post-enroll specify
39   * a pin/password cleared time window where enrollment is allowed.
40   * Pre-enroll only generates a challenge, a full hardwareAuthToken is
41   * generated by trustzone after verifying a pin/password/swipe. This is to
42   * ensure adding a new fingerprint template was preceded by some kind of
43   * credential confirmation (e.g. device password).
44   *
45   * @return 0 if function failed, a uint64_t of challenge otherwise.
46   */
47  @callflow(next={"enroll", "postEnroll"})
48  preEnroll() generates (uint64_t authChallenge);
49
50  /**
51   * Fingerprint enroll request:
52   * Switches the HAL state machine to collect and store a new fingerprint
53   * template. Switches back as soon as enroll is complete, signalled by
54   * (fingerprintMsg.type == FINGERPRINT_TEMPLATE_ENROLLING &&
55   *  fingerprintMsg.data.enroll.samplesRemaining == 0)
56   * or after timeoutSec seconds.
57   * The fingerprint template must be assigned to the group gid.
58   *
59   * @param hat a valid Hardware Authentication Token (HAT), generated
60   * as a result of a preEnroll() call.
61   * @param gid a framework defined fingerprint set (group) id.
62   * @param timeoutSec a timeout in seconds.
63   *
64   * @return debugErrno is a value the framework logs in case it is not 0.
65   *
66   * A notify() function may be called with a more detailed error structure.
67   */
68  @callflow(next={"cancel", "enroll", "postEnroll", "remove"})
69  enroll(uint8_t[69] hat, uint32_t gid, uint32_t timeoutSec)
70      generates (RequestStatus debugErrno);
71
72  /**
73   * Finishes the enroll operation and invalidates the preEnroll() generated
74   * challenge. This must be called at the end of a multi-finger enrollment
75   * session to indicate that no more fingers may be added.
76   *
77   * @return debugErrno is a value the framework logs in case it is not 0.
78   */
79  @callflow(next={"authenticate", "setActiveGroup", "enumerate", "remove"})
80  postEnroll() generates (RequestStatus debugErrno);
81
82  /**
83   * getAuthenticatorId:
84   * Returns a token associated with the current fingerprint set. This value
85   * must change whenever a new fingerprint is enrolled, thus creating a new
86   * fingerprint set.
87   *
88   * @return getAuthenticatorIdRet current authenticator id, 0 if function
89   * failed.
90   */
91  @callflow(next={"authenticate"})
92  getAuthenticatorId() generates (uint64_t AuthenticatorId);
93
94  /**
95   * Cancel pending enroll or authenticate, sending FINGERPRINT_ERROR_CANCELED
96   * to all running clients. Switches the HAL state machine back to the idle
97   * state. Unlike enrollDone() doesn't invalidate the preEnroll() challenge.
98   *
99   * @return debugErrno is a value the framework logs in case it is not 0.
100   */
101  @callflow(next={"authenticate", "enroll", "enumerate", "remove",
102    "setActiveGroup"})
103  cancel() generates (RequestStatus debugErrno);
104
105  /**
106   * Enumerate all the fingerprint templates found in the directory set by
107   * setActiveGroup():
108   * For each template found a notify() must be called with:
109   * fingerprintMsg.type == FINGERPRINT_TEMPLATE_ENUMERATED
110   * fingerprintMsg.data.enumerated.finger indicating a template id
111   * fingerprintMsg.data.enumerated.remainingTemplates indicating how many more
112   * enumeration messages to expect.
113   *
114   * @return debugErrno is a value the framework logs in case it is not 0.
115   */
116  @callflow(next={"remove", "enroll", "authenticate", "setActiveGroup"})
117  enumerate() generates (RequestStatus debugErrno);
118
119  /**
120   * Fingerprint remove request:
121   * Deletes fingerprint template(s).
122   * Works only within the path set by setActiveGroup().
123   * For each template found a notify() must be called with:
124   * fingerprintMsg.type == FINGERPRINT_TEMPLATE_REMOVED
125   * fingerprintMsg.data.removed.finger indicating the template id deleted
126   * fingerprintMsg.data.removed.remainingTemplates indicating how many more
127   * templates must be deleted by this operation.
128   *
129   * @param gid group id must match the last group set by setActiveGroup().
130   * @param fid template id to delete or 0 to delete all templates within the
131   * current group.
132   *
133   * @return debugErrno is a value the framework logs in case it is not 0.
134   */
135  @callflow(next={"enumerate", "authenticate", "cancel", "getAuthenticatorId",
136    "setActiveGroup"})
137  remove(uint32_t gid, uint32_t fid) generates (RequestStatus debugErrno);
138
139  /**
140   * Restricts the HAL operation to a set of fingerprints belonging to a group
141   * provided. The caller must provide a path to a storage location within the
142   * user's data directory.
143   *
144   * @param gid the fingerprint group (set) id.
145   * @param storePath filesystem path to the template storage directory.
146   *
147   * @return debugErrno is a value the framework logs in case it is not 0.
148   */
149  @callflow(next={"authenticate", "preEnroll", "enumerate", "remove"})
150  setActiveGroup(uint32_t gid, string storePath)
151      generates (RequestStatus debugErrno);
152
153  /**
154   * Authenticates an operation identified by operationId
155   *
156   * @param operationId operation id.
157   * @param gid fingerprint group id.
158   *
159   * @return debugErrno is a value the framework logs in case it is not 0.
160   */
161  @callflow(next={"cancel", "preEnroll", "remove"})
162  authenticate(uint64_t operationId, uint32_t gid)
163      generates (RequestStatus debugErrno);
164};
165