1 | /* |
2 | * Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved. |
3 | * |
4 | * Licensed under the Apache License 2.0 (the "License"). You may not use |
5 | * this file except in compliance with the License. You can obtain a copy |
6 | * in the file LICENSE in the source distribution or at |
7 | * https://www.openssl.org/source/license.html |
8 | */ |
9 | |
10 | #ifndef OPENSSL_CT_H |
11 | # define OPENSSL_CT_H |
12 | # pragma once |
13 | |
14 | # include <openssl/macros.h> |
15 | # ifndef OPENSSL_NO_DEPRECATED_3_0 |
16 | # define |
17 | # endif |
18 | |
19 | # include <openssl/opensslconf.h> |
20 | |
21 | # ifndef OPENSSL_NO_CT |
22 | # include <openssl/types.h> |
23 | # include <openssl/safestack.h> |
24 | # include <openssl/x509.h> |
25 | # include <openssl/cterr.h> |
26 | # ifdef __cplusplus |
27 | extern "C" { |
28 | # endif |
29 | |
30 | |
31 | /* Minimum RSA key size, from RFC6962 */ |
32 | # define SCT_MIN_RSA_BITS 2048 |
33 | |
34 | /* All hashes are SHA256 in v1 of Certificate Transparency */ |
35 | # define CT_V1_HASHLEN SHA256_DIGEST_LENGTH |
36 | |
37 | typedef enum { |
38 | CT_LOG_ENTRY_TYPE_NOT_SET = -1, |
39 | CT_LOG_ENTRY_TYPE_X509 = 0, |
40 | CT_LOG_ENTRY_TYPE_PRECERT = 1 |
41 | } ct_log_entry_type_t; |
42 | |
43 | typedef enum { |
44 | SCT_VERSION_NOT_SET = -1, |
45 | SCT_VERSION_V1 = 0 |
46 | } sct_version_t; |
47 | |
48 | typedef enum { |
49 | SCT_SOURCE_UNKNOWN, |
50 | SCT_SOURCE_TLS_EXTENSION, |
51 | SCT_SOURCE_X509V3_EXTENSION, |
52 | SCT_SOURCE_OCSP_STAPLED_RESPONSE |
53 | } sct_source_t; |
54 | |
55 | typedef enum { |
56 | SCT_VALIDATION_STATUS_NOT_SET, |
57 | SCT_VALIDATION_STATUS_UNKNOWN_LOG, |
58 | SCT_VALIDATION_STATUS_VALID, |
59 | SCT_VALIDATION_STATUS_INVALID, |
60 | SCT_VALIDATION_STATUS_UNVERIFIED, |
61 | SCT_VALIDATION_STATUS_UNKNOWN_VERSION |
62 | } sct_validation_status_t; |
63 | |
64 | DEFINE_STACK_OF(SCT) |
65 | DEFINE_STACK_OF(CTLOG) |
66 | |
67 | /****************************************** |
68 | * CT policy evaluation context functions * |
69 | ******************************************/ |
70 | |
71 | /* |
72 | * Creates a new, empty policy evaluation context. |
73 | * The caller is responsible for calling CT_POLICY_EVAL_CTX_free when finished |
74 | * with the CT_POLICY_EVAL_CTX. |
75 | */ |
76 | CT_POLICY_EVAL_CTX *CT_POLICY_EVAL_CTX_new(void); |
77 | |
78 | /* Deletes a policy evaluation context and anything it owns. */ |
79 | void CT_POLICY_EVAL_CTX_free(CT_POLICY_EVAL_CTX *ctx); |
80 | |
81 | /* Gets the peer certificate that the SCTs are for */ |
82 | X509* CT_POLICY_EVAL_CTX_get0_cert(const CT_POLICY_EVAL_CTX *ctx); |
83 | |
84 | /* |
85 | * Sets the certificate associated with the received SCTs. |
86 | * Increments the reference count of cert. |
87 | * Returns 1 on success, 0 otherwise. |
88 | */ |
89 | int CT_POLICY_EVAL_CTX_set1_cert(CT_POLICY_EVAL_CTX *ctx, X509 *cert); |
90 | |
91 | /* Gets the issuer of the aforementioned certificate */ |
92 | X509* CT_POLICY_EVAL_CTX_get0_issuer(const CT_POLICY_EVAL_CTX *ctx); |
93 | |
94 | /* |
95 | * Sets the issuer of the certificate associated with the received SCTs. |
96 | * Increments the reference count of issuer. |
97 | * Returns 1 on success, 0 otherwise. |
98 | */ |
99 | int CT_POLICY_EVAL_CTX_set1_issuer(CT_POLICY_EVAL_CTX *ctx, X509 *issuer); |
100 | |
101 | /* Gets the CT logs that are trusted sources of SCTs */ |
102 | const CTLOG_STORE *CT_POLICY_EVAL_CTX_get0_log_store(const CT_POLICY_EVAL_CTX *ctx); |
103 | |
104 | /* Sets the log store that is in use. It must outlive the CT_POLICY_EVAL_CTX. */ |
105 | void CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE(CT_POLICY_EVAL_CTX *ctx, |
106 | CTLOG_STORE *log_store); |
107 | |
108 | /* |
109 | * Gets the time, in milliseconds since the Unix epoch, that will be used as the |
110 | * current time when checking whether an SCT was issued in the future. |
111 | * Such SCTs will fail validation, as required by RFC6962. |
112 | */ |
113 | uint64_t CT_POLICY_EVAL_CTX_get_time(const CT_POLICY_EVAL_CTX *ctx); |
114 | |
115 | /* |
116 | * Sets the time to evaluate SCTs against, in milliseconds since the Unix epoch. |
117 | * If an SCT's timestamp is after this time, it will be interpreted as having |
118 | * been issued in the future. RFC6962 states that "TLS clients MUST reject SCTs |
119 | * whose timestamp is in the future", so an SCT will not validate in this case. |
120 | */ |
121 | void CT_POLICY_EVAL_CTX_set_time(CT_POLICY_EVAL_CTX *ctx, uint64_t time_in_ms); |
122 | |
123 | /***************** |
124 | * SCT functions * |
125 | *****************/ |
126 | |
127 | /* |
128 | * Creates a new, blank SCT. |
129 | * The caller is responsible for calling SCT_free when finished with the SCT. |
130 | */ |
131 | SCT *SCT_new(void); |
132 | |
133 | /* |
134 | * Creates a new SCT from some base64-encoded strings. |
135 | * The caller is responsible for calling SCT_free when finished with the SCT. |
136 | */ |
137 | SCT *SCT_new_from_base64(unsigned char version, |
138 | const char *logid_base64, |
139 | ct_log_entry_type_t entry_type, |
140 | uint64_t timestamp, |
141 | const char *extensions_base64, |
142 | const char *signature_base64); |
143 | |
144 | /* |
145 | * Frees the SCT and the underlying data structures. |
146 | */ |
147 | void SCT_free(SCT *sct); |
148 | |
149 | /* |
150 | * Free a stack of SCTs, and the underlying SCTs themselves. |
151 | * Intended to be compatible with X509V3_EXT_FREE. |
152 | */ |
153 | void SCT_LIST_free(STACK_OF(SCT) *a); |
154 | |
155 | /* |
156 | * Returns the version of the SCT. |
157 | */ |
158 | sct_version_t SCT_get_version(const SCT *sct); |
159 | |
160 | /* |
161 | * Set the version of an SCT. |
162 | * Returns 1 on success, 0 if the version is unrecognized. |
163 | */ |
164 | __owur int SCT_set_version(SCT *sct, sct_version_t version); |
165 | |
166 | /* |
167 | * Returns the log entry type of the SCT. |
168 | */ |
169 | ct_log_entry_type_t SCT_get_log_entry_type(const SCT *sct); |
170 | |
171 | /* |
172 | * Set the log entry type of an SCT. |
173 | * Returns 1 on success, 0 otherwise. |
174 | */ |
175 | __owur int SCT_set_log_entry_type(SCT *sct, ct_log_entry_type_t entry_type); |
176 | |
177 | /* |
178 | * Gets the ID of the log that an SCT came from. |
179 | * Ownership of the log ID remains with the SCT. |
180 | * Returns the length of the log ID. |
181 | */ |
182 | size_t SCT_get0_log_id(const SCT *sct, unsigned char **log_id); |
183 | |
184 | /* |
185 | * Set the log ID of an SCT to point directly to the *log_id specified. |
186 | * The SCT takes ownership of the specified pointer. |
187 | * Returns 1 on success, 0 otherwise. |
188 | */ |
189 | __owur int SCT_set0_log_id(SCT *sct, unsigned char *log_id, size_t log_id_len); |
190 | |
191 | /* |
192 | * Set the log ID of an SCT. |
193 | * This makes a copy of the log_id. |
194 | * Returns 1 on success, 0 otherwise. |
195 | */ |
196 | __owur int SCT_set1_log_id(SCT *sct, const unsigned char *log_id, |
197 | size_t log_id_len); |
198 | |
199 | /* |
200 | * Returns the timestamp for the SCT (epoch time in milliseconds). |
201 | */ |
202 | uint64_t SCT_get_timestamp(const SCT *sct); |
203 | |
204 | /* |
205 | * Set the timestamp of an SCT (epoch time in milliseconds). |
206 | */ |
207 | void SCT_set_timestamp(SCT *sct, uint64_t timestamp); |
208 | |
209 | /* |
210 | * Return the NID for the signature used by the SCT. |
211 | * For CT v1, this will be either NID_sha256WithRSAEncryption or |
212 | * NID_ecdsa_with_SHA256 (or NID_undef if incorrect/unset). |
213 | */ |
214 | int SCT_get_signature_nid(const SCT *sct); |
215 | |
216 | /* |
217 | * Set the signature type of an SCT |
218 | * For CT v1, this should be either NID_sha256WithRSAEncryption or |
219 | * NID_ecdsa_with_SHA256. |
220 | * Returns 1 on success, 0 otherwise. |
221 | */ |
222 | __owur int SCT_set_signature_nid(SCT *sct, int nid); |
223 | |
224 | /* |
225 | * Set *ext to point to the extension data for the SCT. ext must not be NULL. |
226 | * The SCT retains ownership of this pointer. |
227 | * Returns length of the data pointed to. |
228 | */ |
229 | size_t SCT_get0_extensions(const SCT *sct, unsigned char **ext); |
230 | |
231 | /* |
232 | * Set the extensions of an SCT to point directly to the *ext specified. |
233 | * The SCT takes ownership of the specified pointer. |
234 | */ |
235 | void SCT_set0_extensions(SCT *sct, unsigned char *ext, size_t ext_len); |
236 | |
237 | /* |
238 | * Set the extensions of an SCT. |
239 | * This takes a copy of the ext. |
240 | * Returns 1 on success, 0 otherwise. |
241 | */ |
242 | __owur int SCT_set1_extensions(SCT *sct, const unsigned char *ext, |
243 | size_t ext_len); |
244 | |
245 | /* |
246 | * Set *sig to point to the signature for the SCT. sig must not be NULL. |
247 | * The SCT retains ownership of this pointer. |
248 | * Returns length of the data pointed to. |
249 | */ |
250 | size_t SCT_get0_signature(const SCT *sct, unsigned char **sig); |
251 | |
252 | /* |
253 | * Set the signature of an SCT to point directly to the *sig specified. |
254 | * The SCT takes ownership of the specified pointer. |
255 | */ |
256 | void SCT_set0_signature(SCT *sct, unsigned char *sig, size_t sig_len); |
257 | |
258 | /* |
259 | * Set the signature of an SCT to be a copy of the *sig specified. |
260 | * Returns 1 on success, 0 otherwise. |
261 | */ |
262 | __owur int SCT_set1_signature(SCT *sct, const unsigned char *sig, |
263 | size_t sig_len); |
264 | |
265 | /* |
266 | * The origin of this SCT, e.g. TLS extension, OCSP response, etc. |
267 | */ |
268 | sct_source_t SCT_get_source(const SCT *sct); |
269 | |
270 | /* |
271 | * Set the origin of this SCT, e.g. TLS extension, OCSP response, etc. |
272 | * Returns 1 on success, 0 otherwise. |
273 | */ |
274 | __owur int SCT_set_source(SCT *sct, sct_source_t source); |
275 | |
276 | /* |
277 | * Returns a text string describing the validation status of |sct|. |
278 | */ |
279 | const char *SCT_validation_status_string(const SCT *sct); |
280 | |
281 | /* |
282 | * Pretty-prints an |sct| to |out|. |
283 | * It will be indented by the number of spaces specified by |indent|. |
284 | * If |logs| is not NULL, it will be used to lookup the CT log that the SCT came |
285 | * from, so that the log name can be printed. |
286 | */ |
287 | void SCT_print(const SCT *sct, BIO *out, int indent, const CTLOG_STORE *logs); |
288 | |
289 | /* |
290 | * Pretty-prints an |sct_list| to |out|. |
291 | * It will be indented by the number of spaces specified by |indent|. |
292 | * SCTs will be delimited by |separator|. |
293 | * If |logs| is not NULL, it will be used to lookup the CT log that each SCT |
294 | * came from, so that the log names can be printed. |
295 | */ |
296 | void SCT_LIST_print(const STACK_OF(SCT) *sct_list, BIO *out, int indent, |
297 | const char *separator, const CTLOG_STORE *logs); |
298 | |
299 | /* |
300 | * Gets the last result of validating this SCT. |
301 | * If it has not been validated yet, returns SCT_VALIDATION_STATUS_NOT_SET. |
302 | */ |
303 | sct_validation_status_t SCT_get_validation_status(const SCT *sct); |
304 | |
305 | /* |
306 | * Validates the given SCT with the provided context. |
307 | * Sets the "validation_status" field of the SCT. |
308 | * Returns 1 if the SCT is valid and the signature verifies. |
309 | * Returns 0 if the SCT is invalid or could not be verified. |
310 | * Returns -1 if an error occurs. |
311 | */ |
312 | __owur int SCT_validate(SCT *sct, const CT_POLICY_EVAL_CTX *ctx); |
313 | |
314 | /* |
315 | * Validates the given list of SCTs with the provided context. |
316 | * Sets the "validation_status" field of each SCT. |
317 | * Returns 1 if there are no invalid SCTs and all signatures verify. |
318 | * Returns 0 if at least one SCT is invalid or could not be verified. |
319 | * Returns a negative integer if an error occurs. |
320 | */ |
321 | __owur int SCT_LIST_validate(const STACK_OF(SCT) *scts, |
322 | CT_POLICY_EVAL_CTX *ctx); |
323 | |
324 | |
325 | /********************************* |
326 | * SCT parsing and serialisation * |
327 | *********************************/ |
328 | |
329 | /* |
330 | * Serialize (to TLS format) a stack of SCTs and return the length. |
331 | * "a" must not be NULL. |
332 | * If "pp" is NULL, just return the length of what would have been serialized. |
333 | * If "pp" is not NULL and "*pp" is null, function will allocate a new pointer |
334 | * for data that caller is responsible for freeing (only if function returns |
335 | * successfully). |
336 | * If "pp" is NULL and "*pp" is not NULL, caller is responsible for ensuring |
337 | * that "*pp" is large enough to accept all of the serialized data. |
338 | * Returns < 0 on error, >= 0 indicating bytes written (or would have been) |
339 | * on success. |
340 | */ |
341 | __owur int i2o_SCT_LIST(const STACK_OF(SCT) *a, unsigned char **pp); |
342 | |
343 | /* |
344 | * Convert TLS format SCT list to a stack of SCTs. |
345 | * If "a" or "*a" is NULL, a new stack will be created that the caller is |
346 | * responsible for freeing (by calling SCT_LIST_free). |
347 | * "**pp" and "*pp" must not be NULL. |
348 | * Upon success, "*pp" will point to after the last bytes read, and a stack |
349 | * will be returned. |
350 | * Upon failure, a NULL pointer will be returned, and the position of "*pp" is |
351 | * not defined. |
352 | */ |
353 | STACK_OF(SCT) *o2i_SCT_LIST(STACK_OF(SCT) **a, const unsigned char **pp, |
354 | size_t len); |
355 | |
356 | /* |
357 | * Serialize (to DER format) a stack of SCTs and return the length. |
358 | * "a" must not be NULL. |
359 | * If "pp" is NULL, just returns the length of what would have been serialized. |
360 | * If "pp" is not NULL and "*pp" is null, function will allocate a new pointer |
361 | * for data that caller is responsible for freeing (only if function returns |
362 | * successfully). |
363 | * If "pp" is NULL and "*pp" is not NULL, caller is responsible for ensuring |
364 | * that "*pp" is large enough to accept all of the serialized data. |
365 | * Returns < 0 on error, >= 0 indicating bytes written (or would have been) |
366 | * on success. |
367 | */ |
368 | __owur int i2d_SCT_LIST(const STACK_OF(SCT) *a, unsigned char **pp); |
369 | |
370 | /* |
371 | * Parses an SCT list in DER format and returns it. |
372 | * If "a" or "*a" is NULL, a new stack will be created that the caller is |
373 | * responsible for freeing (by calling SCT_LIST_free). |
374 | * "**pp" and "*pp" must not be NULL. |
375 | * Upon success, "*pp" will point to after the last bytes read, and a stack |
376 | * will be returned. |
377 | * Upon failure, a NULL pointer will be returned, and the position of "*pp" is |
378 | * not defined. |
379 | */ |
380 | STACK_OF(SCT) *d2i_SCT_LIST(STACK_OF(SCT) **a, const unsigned char **pp, |
381 | long len); |
382 | |
383 | /* |
384 | * Serialize (to TLS format) an |sct| and write it to |out|. |
385 | * If |out| is null, no SCT will be output but the length will still be returned. |
386 | * If |out| points to a null pointer, a string will be allocated to hold the |
387 | * TLS-format SCT. It is the responsibility of the caller to free it. |
388 | * If |out| points to an allocated string, the TLS-format SCT will be written |
389 | * to it. |
390 | * The length of the SCT in TLS format will be returned. |
391 | */ |
392 | __owur int i2o_SCT(const SCT *sct, unsigned char **out); |
393 | |
394 | /* |
395 | * Parses an SCT in TLS format and returns it. |
396 | * If |psct| is not null, it will end up pointing to the parsed SCT. If it |
397 | * already points to a non-null pointer, the pointer will be free'd. |
398 | * |in| should be a pointer to a string containing the TLS-format SCT. |
399 | * |in| will be advanced to the end of the SCT if parsing succeeds. |
400 | * |len| should be the length of the SCT in |in|. |
401 | * Returns NULL if an error occurs. |
402 | * If the SCT is an unsupported version, only the SCT's 'sct' and 'sct_len' |
403 | * fields will be populated (with |in| and |len| respectively). |
404 | */ |
405 | SCT *o2i_SCT(SCT **psct, const unsigned char **in, size_t len); |
406 | |
407 | /******************** |
408 | * CT log functions * |
409 | ********************/ |
410 | |
411 | /* |
412 | * Creates a new CT log instance with the given |public_key| and |name|. |
413 | * Takes ownership of |public_key| but copies |name|. |
414 | * Returns NULL if malloc fails or if |public_key| cannot be converted to DER. |
415 | * Should be deleted by the caller using CTLOG_free when no longer needed. |
416 | */ |
417 | CTLOG *CTLOG_new(EVP_PKEY *public_key, const char *name); |
418 | |
419 | /* |
420 | * Creates a new CTLOG instance with the base64-encoded SubjectPublicKeyInfo DER |
421 | * in |pkey_base64|. The |name| is a string to help users identify this log. |
422 | * Returns 1 on success, 0 on failure. |
423 | * Should be deleted by the caller using CTLOG_free when no longer needed. |
424 | */ |
425 | int CTLOG_new_from_base64(CTLOG ** ct_log, |
426 | const char *pkey_base64, const char *name); |
427 | |
428 | /* |
429 | * Deletes a CT log instance and its fields. |
430 | */ |
431 | void CTLOG_free(CTLOG *log); |
432 | |
433 | /* Gets the name of the CT log */ |
434 | const char *CTLOG_get0_name(const CTLOG *log); |
435 | /* Gets the ID of the CT log */ |
436 | void CTLOG_get0_log_id(const CTLOG *log, const uint8_t **log_id, |
437 | size_t *log_id_len); |
438 | /* Gets the public key of the CT log */ |
439 | EVP_PKEY *CTLOG_get0_public_key(const CTLOG *log); |
440 | |
441 | /************************** |
442 | * CT log store functions * |
443 | **************************/ |
444 | |
445 | /* |
446 | * Creates a new CT log store. |
447 | * Should be deleted by the caller using CTLOG_STORE_free when no longer needed. |
448 | */ |
449 | CTLOG_STORE *CTLOG_STORE_new(void); |
450 | |
451 | /* |
452 | * Deletes a CT log store and all of the CT log instances held within. |
453 | */ |
454 | void CTLOG_STORE_free(CTLOG_STORE *store); |
455 | |
456 | /* |
457 | * Finds a CT log in the store based on its log ID. |
458 | * Returns the CT log, or NULL if no match is found. |
459 | */ |
460 | const CTLOG *CTLOG_STORE_get0_log_by_id(const CTLOG_STORE *store, |
461 | const uint8_t *log_id, |
462 | size_t log_id_len); |
463 | |
464 | /* |
465 | * Loads a CT log list into a |store| from a |file|. |
466 | * Returns 1 if loading is successful, or 0 otherwise. |
467 | */ |
468 | __owur int CTLOG_STORE_load_file(CTLOG_STORE *store, const char *file); |
469 | |
470 | /* |
471 | * Loads the default CT log list into a |store|. |
472 | * Returns 1 if loading is successful, or 0 otherwise. |
473 | */ |
474 | __owur int CTLOG_STORE_load_default_file(CTLOG_STORE *store); |
475 | |
476 | # ifdef __cplusplus |
477 | } |
478 | # endif |
479 | # endif |
480 | #endif |
481 | |