1 /* 2 * Copyright (C) 2016 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 KEYSTORE_PERMISSIONS_H_ 18 #define KEYSTORE_PERMISSIONS_H_ 19 20 #include <unistd.h> 21 22 /* Here are the permissions, actions, users, and the main function. */ 23 enum perm_t { 24 P_GET_STATE = 1 << 0, 25 P_GET = 1 << 1, 26 P_INSERT = 1 << 2, 27 P_DELETE = 1 << 3, 28 P_EXIST = 1 << 4, 29 P_LIST = 1 << 5, 30 P_RESET = 1 << 6, 31 P_PASSWORD = 1 << 7, 32 P_LOCK = 1 << 8, 33 P_UNLOCK = 1 << 9, 34 P_IS_EMPTY = 1 << 10, 35 P_SIGN = 1 << 11, 36 P_VERIFY = 1 << 12, 37 P_GRANT = 1 << 13, 38 P_DUPLICATE = 1 << 14, 39 P_CLEAR_UID = 1 << 15, 40 P_ADD_AUTH = 1 << 16, 41 P_USER_CHANGED = 1 << 17, 42 P_GEN_UNIQUE_ID = 1 << 18, 43 }; 44 45 const char* get_perm_label(perm_t perm); 46 47 /** 48 * Returns the UID that the callingUid should act as. This is here for 49 * legacy support of the WiFi and VPN systems and should be removed 50 * when WiFi can operate in its own namespace. 51 */ 52 uid_t get_keystore_euid(uid_t uid); 53 54 /** 55 * Returns true if the uid/pid/sid has a permission. Checks based on sid if available. 56 * 57 * sid may be null on older kernels 58 */ 59 bool has_permission(uid_t uid, perm_t perm, pid_t spid, const char* sid); 60 61 /** 62 * Returns true if the callingUid is allowed to interact in the targetUid's 63 * namespace. 64 */ 65 bool is_granted_to(uid_t callingUid, uid_t targetUid); 66 67 int configure_selinux(); 68 69 /* 70 * Keystore grants. 71 * 72 * What are keystore grants? 73 * 74 * Keystore grants are a mechanism that allows an app to grant the permission to use one of its 75 * keys to an other app. 76 * 77 * Liftime of a grant: 78 * 79 * A keystore grant is ephemeral in that is never persistently stored. When the keystore process 80 * exits, all grants are lost. Also, grants can be explicitly revoked by the granter by invoking 81 * the ungrant operation. 82 * 83 * What happens when a grant is created? 84 * 85 * The grant operation expects a valid key alias and the uid of the grantee, i.e., the app that 86 * shall be allowed to use the key denoted by the alias. It then makes an entry in the grant store 87 * which generates a new alias of the form <alias>_KEYSTOREGRANT_<random_grant_no_>. This grant 88 * alias is returned to the caller which can pass the new alias to the grantee. For every grantee, 89 * the grant store keeps a set of grants, an entry of which holds the following information: 90 * - the owner of the key by uid, aka granter uid, 91 * - the original alias of the granted key, and 92 * - the random grant number. 93 * (See "grant_store.h:class Grant") 94 * 95 * What happens when a grant is used? 96 * 97 * Upon any keystore operation that expects an alias, the alias and the caller's uid are used 98 * to retrieve a key file. If that fails some operations try to retrieve a key file indirectly 99 * through a grant. These operations include: 100 * - attestKey 101 * - begin 102 * - exportKey 103 * - get 104 * - getKeyCharacteristics 105 * - del 106 * - exist 107 * - getmtime 108 * Operations that DO NOT follow the grant indirection are: 109 * - import 110 * - generate 111 * - grant 112 * - ungrant 113 * Especially, the latter two mean that neither can a grantee transitively grant a granted key 114 * to a third, nor can they relinquish access to the key or revoke access to the key by a third. 115 */ 116 117 #endif // KEYSTORE_PERMISSIONS_H_ 118