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
attribute_is_hidden(struct pkcs11_attribute_head * req_attr)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