1 /* SPDX-License-Identifier: BSD-2-Clause */ 2 /* 3 * Copyright (c) 2017-2020, Linaro Limited 4 */ 5 6 #ifndef PKCS11_TA_PKCS11_ATTRIBUTES_H 7 #define PKCS11_TA_PKCS11_ATTRIBUTES_H 8 9 #include <inttypes.h> 10 #include <pkcs11_ta.h> 11 12 #include "serializer.h" 13 14 struct obj_attrs; 15 struct pkcs11_object; 16 struct pkcs11_session; 17 18 /* 19 * PKCS#11 directives on object attributes. 20 * Those with a '*' are optional, other must be defined, either by caller 21 * or by some known default value. 22 * 23 * [all] objects: class 24 * 25 * [stored] objects: persistent, need_authen, modifiable, copyable, 26 * destroyable, label*. 27 * 28 * [data] objects: [all], [stored], application_id*, object_id*, value. 29 * 30 * [key] objects: [all], [stored], type, id*, start_date/end_date*, 31 * derive, local, allowed_mechanisms*. 32 * 33 * [symm-key]: [key], sensitive, encrypt, decrypt, sign, verify, wrap, 34 * unwrap, extractable, wrap_with_trusted, trusted, 35 * wrap_template, unwrap_template, derive_template. 36 */ 37 38 /* 39 * Utils to check compliance of attributes at various processing steps. 40 * Any processing operation is exclusively one of the following. 41 * 42 * Case 1: Create a secret from some local random value (C_CreateKey & friends) 43 * - client provides an attributes list template, PKCS11 TA completes with 44 * default attribute values. Object is created if attributes are 45 * consistent and comply token/session state. 46 * - PKCS11 sequence: 47 * - check/set token/session state 48 * - create an attribute list from client template and default values. 49 * - check new secret attributes complies requested mechanism. 50 * - check new secret attributes complies token/session state. 51 * - Generate the value for the secret. 52 * - Set some runtime attributes in the new secret. 53 * - Register the new secret and return a handle for it. 54 * 55 * Case 2: Create a secret from a client clear data (C_CreateObject) 56 * - client provides an attributes list template, PKCS11 TA completes with 57 * default attribute values. Object is created if attributes are 58 * consistent and comply token/session state. 59 * - check/set token/session state 60 * - create an attribute list from client template and default values. 61 * - check new secret attributes complies requested mechanism (raw-import). 62 * - check new secret attributes complies token/session state. 63 * - Set some runtime attributes in the new secret. 64 * - Register the new secret and return a handle for it. 65 66 * Case 3: Use a secret for data processing 67 * - client provides a mechanism ID and the secret handle. 68 * - PKCS11 checks mechanism and secret comply, if mechanism and token/session 69 * state comply and last if secret and token/session state comply. 70 * - check/set token/session state 71 * - check secret's parent attributes complies requested processing. 72 * - check secret's parent attributes complies token/session state. 73 * - check new secret attributes complies secret's parent attributes. 74 * - check new secret attributes complies requested mechanism. 75 * - check new secret attributes complies token/session state. 76 * 77 * Case 4: Create a secret from a client template and a secret's parent 78 * (i.e derive a symmetric key) 79 * - client args: new-key template, mechanism ID, parent-key handle. 80 * - PKCS11 create a new-key attribute list based on template + default values + 81 * inheritance from the parent key attributes. 82 * - PKCS11 checks: 83 * - token/session state 84 * - parent-key vs mechanism 85 * - parent-key vs token/session state 86 * - parent-key vs new-key 87 * - new-key vs mechanism 88 * - new-key vs token/session state 89 * - then do processing 90 * - then finalize object creation 91 */ 92 93 enum processing_func { 94 PKCS11_FUNCTION_DIGEST, 95 PKCS11_FUNCTION_GENERATE, 96 PKCS11_FUNCTION_GENERATE_PAIR, 97 PKCS11_FUNCTION_DERIVE, 98 PKCS11_FUNCTION_WRAP, 99 PKCS11_FUNCTION_UNWRAP, 100 PKCS11_FUNCTION_ENCRYPT, 101 PKCS11_FUNCTION_DECRYPT, 102 PKCS11_FUNCTION_SIGN, 103 PKCS11_FUNCTION_VERIFY, 104 PKCS11_FUNCTION_SIGN_RECOVER, 105 PKCS11_FUNCTION_VERIFY_RECOVER, 106 PKCS11_FUNCTION_IMPORT, 107 PKCS11_FUNCTION_COPY, 108 PKCS11_FUNCTION_MODIFY, 109 PKCS11_FUNCTION_DESTROY, 110 PKCS11_FUNCTION_UNKNOWN, 111 }; 112 113 enum processing_step { 114 PKCS11_FUNC_STEP_INIT, 115 PKCS11_FUNC_STEP_ONESHOT, 116 PKCS11_FUNC_STEP_UPDATE, 117 PKCS11_FUNC_STEP_UPDATE_KEY, 118 PKCS11_FUNC_STEP_FINAL, 119 }; 120 121 /* Create an attribute list for a new object */ 122 enum pkcs11_rc 123 create_attributes_from_template(struct obj_attrs **out, void *template, 124 size_t template_size, struct obj_attrs *parent, 125 enum processing_func func, 126 enum pkcs11_mechanism_id proc_mecha, 127 enum pkcs11_class_id template_class); 128 129 /* 130 * The various checks to be performed before a processing: 131 * - create a new object in the current token state 132 * - use a parent object in the processing 133 * - use a mechanism with provided configuration 134 */ 135 enum pkcs11_rc check_created_attrs_against_token(struct pkcs11_session *session, 136 struct obj_attrs *head); 137 138 enum pkcs11_rc check_created_attrs_against_processing(uint32_t proc_id, 139 struct obj_attrs *head); 140 141 enum pkcs11_rc check_created_attrs(struct obj_attrs *key1, 142 struct obj_attrs *key2); 143 144 /* 145 * Check the attributes of the parent secret (key) used in the processing 146 * do match the target processing. 147 * 148 * @proc_id - PKCS11_CKM_xxx 149 * @func - identifier of the processing function operated with @proc_id. 150 * @head - head of the attributes of parent object. 151 */ 152 enum pkcs11_rc 153 check_parent_attrs_against_processing(enum pkcs11_mechanism_id proc_id, 154 enum processing_func func, 155 struct obj_attrs *head); 156 157 enum pkcs11_rc check_access_attrs_against_token(struct pkcs11_session *session, 158 struct obj_attrs *head); 159 160 enum pkcs11_rc 161 check_mechanism_against_processing(struct pkcs11_session *session, 162 enum pkcs11_mechanism_id mechanism_type, 163 enum processing_func function, 164 enum processing_step step); 165 166 static inline bool attribute_is_hidden(struct pkcs11_attribute_head *req_attr) 167 { 168 return (req_attr->id & PKCS11_CKA_OPTEE_FLAGS_HIDDEN) == 169 PKCS11_CKA_OPTEE_FLAGS_HIDDEN; 170 } 171 172 bool attribute_is_exportable(struct pkcs11_attribute_head *req_attr, 173 struct pkcs11_object *obj); 174 175 bool object_is_private(struct obj_attrs *head); 176 177 bool object_is_token(struct obj_attrs *head); 178 179 bool object_is_modifiable(struct obj_attrs *head); 180 181 bool object_is_copyable(struct obj_attrs *head); 182 183 /* 184 * Check the attributes passed in template against the attributes which can be 185 * modified. These are the attributes marked with * 8,10,11 or 12 in Table 10 186 * in PKCS #11 Cryptographic Token InterfaceBase Specification Version 2.40. 187 * Few attributes not with this marking but explicitly specified as modifiable 188 * in footnote of their tables are also considered to be modifiable 189 */ 190 enum pkcs11_rc check_attrs_against_modification(struct pkcs11_session *session, 191 struct obj_attrs *head, 192 struct pkcs11_object *obj, 193 enum processing_func function); 194 195 enum pkcs11_rc set_key_data(struct obj_attrs **head, void *data, 196 size_t key_size); 197 198 /* 199 * Get an allocated copy of key data to be wrapped from @head 200 * @head: Object attribute where to find key data to be wrapped 201 * @data: Output allocated and filled buffer upon success 202 * @sz: Key output data size in bytes upon success 203 * Return a pkcs11_rv compliant value 204 */ 205 enum pkcs11_rc alloc_key_data_to_wrap(struct obj_attrs *head, void **data, 206 uint32_t *sz); 207 208 /* 209 * Adds CKA_ID attribute from paired object if missing. 210 * 211 * @pub_head - Public key object attributes 212 * @priv_head - Private key object attributes 213 * Return a PKCS11 return code 214 */ 215 enum pkcs11_rc add_missing_attribute_id(struct obj_attrs **pub_head, 216 struct obj_attrs **priv_head); 217 218 #endif /*PKCS11_TA_PKCS11_ATTRIBUTES_H*/ 219