1 /*
2 * Copyright (C) 2015 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_HARDWARE_GATEKEEPER_H
18 #define ANDROID_HARDWARE_GATEKEEPER_H
19
20 #include <sys/cdefs.h>
21 #include <sys/types.h>
22 #include <hardware/hardware.h>
23
24 __BEGIN_DECLS
25
26 #define GATEKEEPER_HARDWARE_MODULE_ID "gatekeeper"
27
28 #define GATEKEEPER_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1)
29
30 #define HARDWARE_GATEKEEPER "gatekeeper"
31
32 struct gatekeeper_module {
33 /**
34 * Comon methods of the gatekeeper module. This *must* be the first member of
35 * gatekeeper_module as users of this structure will cast a hw_module_t to
36 * a gatekeeper_module pointer in the appropriate context.
37 */
38 hw_module_t common;
39 };
40
41 struct gatekeeper_device {
42 /**
43 * Common methods of the gatekeeper device. As above, this must be the first
44 * member of keymaster_device.
45 */
46 hw_device_t common;
47
48 /**
49 * Enrolls desired_password, which should be derived from a user selected pin or password,
50 * with the authentication factor private key used only for enrolling authentication
51 * factor data.
52 *
53 * If there was already a password enrolled, it should be provided in
54 * current_password_handle, along with the current password in current_password
55 * that should validate against current_password_handle.
56 *
57 * Parameters:
58 * - dev: pointer to gatekeeper_device acquired via calls to gatekeeper_open
59 * - uid: the Android user identifier
60 *
61 * - current_password_handle: the currently enrolled password handle the user
62 * wants to replace. May be null if there's no currently enrolled password.
63 * - current_password_handle_length: the length in bytes of the buffer pointed
64 * at by current_password_handle. Must be 0 if current_password_handle is NULL.
65 *
66 * - current_password: the user's current password in plain text. If presented,
67 * it MUST verify against current_password_handle.
68 * - current_password_length: the size in bytes of the buffer pointed at by
69 * current_password. Must be 0 if the current_password is NULL.
70 *
71 * - desired_password: the new password the user wishes to enroll in plain-text.
72 * Cannot be NULL.
73 * - desired_password_length: the length in bytes of the buffer pointed at by
74 * desired_password.
75 *
76 * - enrolled_password_handle: on success, a buffer will be allocated with the
77 * new password handle referencing the password provided in desired_password.
78 * This buffer can be used on subsequent calls to enroll or verify.
79 * The caller is responsible for deallocating this buffer via a call to delete[]
80 * - enrolled_password_handle_length: pointer to the length in bytes of the buffer allocated
81 * by this function and pointed to by *enrolled_password_handle_length.
82 *
83 * Returns:
84 * - 0 on success
85 * - An error code < 0 on failure, or
86 * - A timeout value T > 0 if the call should not be re-attempted until T milliseconds
87 * have elapsed.
88 *
89 * On error, enrolled_password_handle will not be allocated.
90 */
91 int (*enroll)(const struct gatekeeper_device *dev, uint32_t uid,
92 const uint8_t *current_password_handle, uint32_t current_password_handle_length,
93 const uint8_t *current_password, uint32_t current_password_length,
94 const uint8_t *desired_password, uint32_t desired_password_length,
95 uint8_t **enrolled_password_handle, uint32_t *enrolled_password_handle_length);
96
97 /**
98 * Verifies provided_password matches enrolled_password_handle.
99 *
100 * Implementations of this module may retain the result of this call
101 * to attest to the recency of authentication.
102 *
103 * On success, writes the address of a verification token to auth_token,
104 * usable to attest password verification to other trusted services. Clients
105 * may pass NULL for this value.
106 *
107 * Parameters:
108 * - dev: pointer to gatekeeper_device acquired via calls to gatekeeper_open
109 * - uid: the Android user identifier
110 *
111 * - challenge: An optional challenge to authenticate against, or 0. Used when a separate
112 * authenticator requests password verification, or for transactional
113 * password authentication.
114 *
115 * - enrolled_password_handle: the currently enrolled password handle that the
116 * user wishes to verify against.
117 * - enrolled_password_handle_length: the length in bytes of the buffer pointed
118 * to by enrolled_password_handle
119 *
120 * - provided_password: the plaintext password to be verified against the
121 * enrolled_password_handle
122 * - provided_password_length: the length in bytes of the buffer pointed to by
123 * provided_password
124 *
125 * - auth_token: on success, a buffer containing the authentication token
126 * resulting from this verification is assigned to *auth_token. The caller
127 * is responsible for deallocating this memory via a call to delete[]
128 * - auth_token_length: on success, the length in bytes of the authentication
129 * token assigned to *auth_token will be assigned to *auth_token_length
130 *
131 * - request_reenroll: a request to the upper layers to re-enroll the verified
132 * password due to a version change. Not set if verification fails.
133 *
134 * Returns:
135 * - 0 on success
136 * - An error code < 0 on failure, or
137 * - A timeout value T > 0 if the call should not be re-attempted until T milliseconds
138 * have elapsed.
139 * On error, auth token will not be allocated
140 */
141 int (*verify)(const struct gatekeeper_device *dev, uint32_t uid, uint64_t challenge,
142 const uint8_t *enrolled_password_handle, uint32_t enrolled_password_handle_length,
143 const uint8_t *provided_password, uint32_t provided_password_length,
144 uint8_t **auth_token, uint32_t *auth_token_length, bool *request_reenroll);
145
146 /*
147 * Deletes the enrolled_password_handle associated wth the uid. Once deleted
148 * the user cannot be verified anymore.
149 * This function is optional and should be set to NULL if it is not implemented.
150 *
151 * Parameters
152 * - dev: pointer to gatekeeper_device acquired via calls to gatekeeper_open
153 * - uid: the Android user identifier
154 *
155 * Returns:
156 * - 0 on success
157 * - An error code < 0 on failure
158 */
159 int (*delete_user)(const struct gatekeeper_device *dev, uint32_t uid);
160
161 /*
162 * Deletes all the enrolled_password_handles for all uid's. Once called,
163 * no users will be enrolled on the device.
164 * This function is optional and should be set to NULL if it is not implemented.
165 *
166 * Parameters
167 * - dev: pointer to gatekeeper_device acquired via calls to gatekeeper_open
168 *
169 * Returns:
170 * - 0 on success
171 * - An error code < 0 on failure
172 */
173 int (*delete_all_users)(const struct gatekeeper_device *dev);
174 };
175
176 typedef struct gatekeeper_device gatekeeper_device_t;
177
gatekeeper_open(const struct hw_module_t * module,gatekeeper_device_t ** device)178 static inline int gatekeeper_open(const struct hw_module_t *module,
179 gatekeeper_device_t **device) {
180 return module->methods->open(module, HARDWARE_GATEKEEPER,
181 (struct hw_device_t **) device);
182 }
183
gatekeeper_close(gatekeeper_device_t * device)184 static inline int gatekeeper_close(gatekeeper_device_t *device) {
185 return device->common.close(&device->common);
186 }
187
188 __END_DECLS
189
190 #endif // ANDROID_HARDWARE_GATEKEEPER_H
191