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
17package android.service.gatekeeper;
18
19import android.service.gatekeeper.GateKeeperResponse;
20
21/**
22 * Interface for communication with GateKeeper, the
23 * secure password storage daemon.
24 *
25 * This must be kept manually in sync with system/core/gatekeeperd
26 * until AIDL can generate both C++ and Java bindings.
27 *
28 * @hide
29 */
30interface IGateKeeperService {
31    /**
32     * Enrolls a password, returning the handle to the enrollment to be stored locally.
33     * @param uid The Android user ID associated to this enrollment
34     * @param currentPasswordHandle The previously enrolled handle, or null if none
35     * @param currentPassword The previously enrolled plaintext password, or null if none.
36     *                        If provided, must verify against the currentPasswordHandle.
37     * @param desiredPassword The new desired password, for which a handle will be returned
38     *                        upon success.
39     * @return an EnrollResponse or null on failure
40     */
41    GateKeeperResponse enroll(int uid, in byte[] currentPasswordHandle, in byte[] currentPassword,
42            in byte[] desiredPassword);
43
44    /**
45     * Verifies an enrolled handle against a provided, plaintext blob.
46     * @param uid The Android user ID associated to this enrollment
47     * @param enrolledPasswordHandle The handle against which the provided password will be
48     *                               verified.
49     * @param The plaintext blob to verify against enrolledPassword.
50     * @return a VerifyResponse, or null on failure.
51     */
52    GateKeeperResponse verify(int uid, in byte[] enrolledPasswordHandle, in byte[] providedPassword);
53
54    /**
55     * Verifies an enrolled handle against a provided, plaintext blob.
56     * @param uid The Android user ID associated to this enrollment
57     * @param challenge a challenge to authenticate agaisnt the device credential. If successful
58     *                  authentication occurs, this value will be written to the returned
59     *                  authentication attestation.
60     * @param enrolledPasswordHandle The handle against which the provided password will be
61     *                               verified.
62     * @param The plaintext blob to verify against enrolledPassword.
63     * @return a VerifyResponse with an attestation, or null on failure.
64     */
65    GateKeeperResponse verifyChallenge(int uid, long challenge, in byte[] enrolledPasswordHandle,
66            in byte[] providedPassword);
67
68    /**
69     * Retrieves the secure identifier for the user with the provided Android ID,
70     * or 0 if none is found.
71     * @param uid the Android user id
72     */
73    long getSecureUserId(int uid);
74
75    /**
76     * Clears secure user id associated with the provided Android ID.
77     * Must be called when password is set to NONE.
78     * @param uid the Android user id.
79     */
80    void clearSecureUserId(int uid);
81}
82