1 /* 2 * Copyright (C) 2021 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 android.security.dice; 18 19 import android.hardware.security.dice.Bcc; 20 import android.hardware.security.dice.BccHandover; 21 import android.hardware.security.dice.InputValues; 22 import android.hardware.security.dice.Signature; 23 24 /** 25 * An implementation of IDiceNode provides access to DICE secrets to its clients. It 26 * uses binder's caller UID and security context to identify its callers and assures 27 * That clients can only access their specific DICE secrets. 28 * It may operate in two different modes, resident mode and proxy mode. 29 * 30 * ## Resident mode. 31 * In resident mode, the node is in possession of the secrets corresponding to its level in 32 * the dice tree. It can act as root of the sub tree that it serves. The secrets are memory 33 * resident in the node. It identifies its callers and prepends the caller's identity to the 34 * request's vector of input values. It then derives the required secrets by iterating through 35 * the request's vector of input values in ascending order. 36 * 37 * ## Proxy mode. 38 * In proxy mode, the node has a connection to a parent node. It serves its callers by verifying 39 * their identity, by prefixing the client's vector of input values with client's identity, and 40 * forwarding the request to the next level up. 41 * 42 * The modes are implementation details that are completely transparent to the clients. 43 * 44 * Privacy: Unprivileged apps may not use this service ever because it may provide access to a 45 * device specific id that is stable across reinstalls, reboots, and applications. 46 * 47 * @hide 48 */ 49 @SensitiveData 50 interface IDiceNode { 51 /** 52 * Uses the a key derived from the caller's attestation secret to sign the payload using 53 * RFC 8032 PureEd25519 and returns the signature. The payload is limited to 1024 bytes. 54 * 55 * ## Error as service specific exception: 56 * ResponseCode::PERMISSION_DENIED if the caller does not have the use_sign permission. 57 */ sign(in InputValues[] id, in byte[] payload)58 Signature sign(in InputValues[] id, in byte[] payload); 59 60 /** 61 * Returns the attestation certificate chain of the caller if `inputValues` is empty or the 62 * chain to the given child of the caller identified by the `inputValues` vector. 63 * 64 * ## Error as service specific exception: 65 * ResponseCode::PERMISSION_DENIED if the caller does not have the get_attestation_chain 66 * permission. 67 */ getAttestationChain(in InputValues[] inputValues)68 Bcc getAttestationChain(in InputValues[] inputValues); 69 70 /** 71 * This function allows a client to become a resident node. Called with empty InputValues 72 * vectors, an implementation returns the client's DICE secrets. If inputValues is 73 * not empty, the appropriate derivations are performed starting from the client's level. 74 * The function must never return secrets pertaining to the implementation or a parent 75 * thereof in the DICE hierarchy. 76 * 77 * ## Error as service specific exception: 78 * ResponseCode::PERMISSION_DENIED if the implementation does not allow resident nodes 79 * at the client's level. 80 */ derive(in InputValues[] inputValues)81 BccHandover derive(in InputValues[] inputValues); 82 83 /** 84 * The client demotes itself to the given identity. When serving the calling client, 85 * the implementation must append the given identities. Essentially, the client assumes 86 * the identity of one of its children. This operation is not reversible, i.e., there 87 * is no promotion. Further demotion is possible. 88 * 89 * If the operation fails for any reason. No further services must be provided. Ideally, 90 * a device shutdown/reboot is triggered. 91 * 92 * ## Error as service specific exception: 93 * ResponseCode::PERMISSION_DENIED if the caller does not have the demote permission. 94 */ demote(in InputValues[] inputValues)95 void demote(in InputValues[] inputValues); 96 } 97