1 /*
2  * Copyright (C) 2022 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 package com.android.rkpdapp;
18 
19 import com.android.rkpdapp.IGetKeyCallback;
20 import com.android.rkpdapp.IStoreUpgradedKeyCallback;
21 
22 /**
23  * This interface is associated with the registration of an
24  * IRemotelyProvisionedComponent. Each component has a unique database of keys
25  * and certificates that are provisioned to the device for attestation. An
26  * IRegistration binder is created by calling
27  * {@link IRemoteProvisioning#getRegistration()}.
28  *
29  * This interface is used to query for available keys and certificates for the
30  * registered component.
31  *
32  * @hide
33  */
34 oneway interface IRegistration {
35     /**
36      * Fetch a remotely provisioned key for the given keyId. Keys are unique
37      * per caller/keyId/registration tuple. This ensures that no two
38      * applications are able to correlate keys to uniquely identify a
39      * device/user. Callers receive their key via {@code callback}.
40      *
41      * If a key is available, this call immediately invokes {@code callback}.
42      *
43      * If no keys are immediately available, then this function contacts the
44      * remote provisioning server to provision a key. After provisioning is
45      * completed, the key is passed to {@code callback}.
46      *
47      * @param keyId This is a client-chosen key identifier, used to
48      * differentiate between keys for varying client-specific use-cases. For
49      * example, keystore2 passes the UID of the applications that call it as
50      * the keyId value here, so that each of keystore2's clients gets a unique
51      * key.
52      * @param callback Receives the result of the call. A callback must only
53      * be used with one {@code getKey} call at a time.
54      */
getKey(int keyId, IGetKeyCallback callback)55     void getKey(int keyId, IGetKeyCallback callback);
56 
57     /**
58      * Cancel an active request for a remotely provisioned key, as initiated via
59      * {@link getKey}. Upon cancellation, {@code callback.onCancel} will be invoked.
60      */
cancelGetKey(IGetKeyCallback callback)61     void cancelGetKey(IGetKeyCallback callback);
62 
63     /**
64      * Replace the key blob with the given key id with an upgraded key blob.
65      * In certain cases, such as security patch level upgrade, keys become "old".
66      * In these cases, the component which supports operations with the remotely
67      * provisioned key blobs must support upgrading the blobs to make them "new"
68      * and usable on the updated system.
69      *
70      * For an example of a remotely provisioned component that has an upgrade
71      * mechanism, see the documentation for IKeyMintDevice.upgradeKey.
72      *
73      * Once a key has been upgraded, the IRegistration where the key is stored
74      * needs to be told about the new blob. After calling storeUpgradedKeyAsync,
75      * getKey will return the new key blob instead of the old one.
76      *
77      * Note that this function does NOT extend the lifetime of key blobs. The
78      * certificate for the key is unchanged, and the key will still expire at
79      * the same time it would have if storeUpgradedKeyAsync had never been called.
80      *
81      * @param oldKeyBlob This key blob will be replaced by newKeyBlob in the
82      * rkpd data store. Future requests for the key will return newKeyBlob,
83      * and oldKeyBlob is forgotten.
84      * @param newKeyblob The new blob to replace the key blob currently indexed
85      * by keyId.
86      * @param callback Receives the result of the call. A callback must only
87      * be used with one {@code storeUpgradedKeyAsync} call at a time.
88      */
storeUpgradedKeyAsync( in byte[] oldKeyBlob, in byte[] newKeyBlob, IStoreUpgradedKeyCallback callback)89     void storeUpgradedKeyAsync(
90             in byte[] oldKeyBlob, in byte[] newKeyBlob, IStoreUpgradedKeyCallback callback);
91 }
92