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