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