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