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 }; 110 111 enum processing_step { 112 PKCS11_FUNC_STEP_INIT, 113 PKCS11_FUNC_STEP_ONESHOT, 114 PKCS11_FUNC_STEP_UPDATE, 115 PKCS11_FUNC_STEP_FINAL, 116 }; 117 118 /* Create an attribute list for a new object */ 119 enum pkcs11_rc 120 create_attributes_from_template(struct obj_attrs **out, void *template, 121 size_t template_size, struct obj_attrs *parent, 122 enum processing_func func, 123 enum pkcs11_mechanism_id proc_mecha, 124 enum pkcs11_class_id template_class); 125 126 /* 127 * The various checks to be performed before a processing: 128 * - create a new object in the current token state 129 * - use a parent object in the processing 130 * - use a mechanism with provided configuration 131 */ 132 enum pkcs11_rc check_created_attrs_against_token(struct pkcs11_session *session, 133 struct obj_attrs *head); 134 135 enum pkcs11_rc check_created_attrs_against_processing(uint32_t proc_id, 136 struct obj_attrs *head); 137 138 enum pkcs11_rc check_created_attrs(struct obj_attrs *key1, 139 struct obj_attrs *key2); 140 141 /* 142 * Check the attributes of the parent secret (key) used in the processing 143 * do match the target processing. 144 * 145 * @proc_id - PKCS11_CKM_xxx 146 * @func - identifier of the processing function operated with @proc_id. 147 * @head - head of the attributes of parent object. 148 */ 149 enum pkcs11_rc 150 check_parent_attrs_against_processing(enum pkcs11_mechanism_id proc_id, 151 enum processing_func func, 152 struct obj_attrs *head); 153 154 enum pkcs11_rc check_access_attrs_against_token(struct pkcs11_session *session, 155 struct obj_attrs *head); 156 157 enum pkcs11_rc 158 check_mechanism_against_processing(struct pkcs11_session *session, 159 enum pkcs11_mechanism_id mechanism_type, 160 enum processing_func function, 161 enum processing_step step); 162 163 bool attribute_is_exportable(struct pkcs11_attribute_head *req_attr, 164 struct pkcs11_object *obj); 165 166 bool object_is_private(struct obj_attrs *head); 167 168 #endif /*PKCS11_TA_PKCS11_ATTRIBUTES_H*/ 169