2 * Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
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
14 # include <openssl/macros.h>
15 # ifndef OPENSSL_NO_DEPRECATED_3_0
19 # include <openssl/opensslconf.h>
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>
31 /* Minimum RSA key size, from RFC6962 */
32 # define SCT_MIN_RSA_BITS 2048
34 /* All hashes are SHA256 in v1 of Certificate Transparency */
35 # define CT_V1_HASHLEN SHA256_DIGEST_LENGTH
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
;
44 SCT_VERSION_NOT_SET
= -1,
50 SCT_SOURCE_TLS_EXTENSION
,
51 SCT_SOURCE_X509V3_EXTENSION
,
52 SCT_SOURCE_OCSP_STAPLED_RESPONSE
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
;
65 DEFINE_STACK_OF(CTLOG
)
67 /******************************************
68 * CT policy evaluation context functions *
69 ******************************************/
72 * Creates a new, empty policy evaluation context associated with the given
73 * library context and property query string.
74 * The caller is responsible for calling CT_POLICY_EVAL_CTX_free when finished
75 * with the CT_POLICY_EVAL_CTX.
77 CT_POLICY_EVAL_CTX
*CT_POLICY_EVAL_CTX_new_with_libctx(OPENSSL_CTX
*libctx
,
81 * The same as CT_POLICY_EVAL_CTX_new_with_libctx() but the default library
82 * context and property query string is used.
84 CT_POLICY_EVAL_CTX
*CT_POLICY_EVAL_CTX_new(void);
86 /* Deletes a policy evaluation context and anything it owns. */
87 void CT_POLICY_EVAL_CTX_free(CT_POLICY_EVAL_CTX
*ctx
);
89 /* Gets the peer certificate that the SCTs are for */
90 X509
* CT_POLICY_EVAL_CTX_get0_cert(const CT_POLICY_EVAL_CTX
*ctx
);
93 * Sets the certificate associated with the received SCTs.
94 * Increments the reference count of cert.
95 * Returns 1 on success, 0 otherwise.
97 int CT_POLICY_EVAL_CTX_set1_cert(CT_POLICY_EVAL_CTX
*ctx
, X509
*cert
);
99 /* Gets the issuer of the aforementioned certificate */
100 X509
* CT_POLICY_EVAL_CTX_get0_issuer(const CT_POLICY_EVAL_CTX
*ctx
);
103 * Sets the issuer of the certificate associated with the received SCTs.
104 * Increments the reference count of issuer.
105 * Returns 1 on success, 0 otherwise.
107 int CT_POLICY_EVAL_CTX_set1_issuer(CT_POLICY_EVAL_CTX
*ctx
, X509
*issuer
);
109 /* Gets the CT logs that are trusted sources of SCTs */
110 const CTLOG_STORE
*CT_POLICY_EVAL_CTX_get0_log_store(const CT_POLICY_EVAL_CTX
*ctx
);
112 /* Sets the log store that is in use. It must outlive the CT_POLICY_EVAL_CTX. */
113 void CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE(CT_POLICY_EVAL_CTX
*ctx
,
114 CTLOG_STORE
*log_store
);
117 * Gets the time, in milliseconds since the Unix epoch, that will be used as the
118 * current time when checking whether an SCT was issued in the future.
119 * Such SCTs will fail validation, as required by RFC6962.
121 uint64_t CT_POLICY_EVAL_CTX_get_time(const CT_POLICY_EVAL_CTX
*ctx
);
124 * Sets the time to evaluate SCTs against, in milliseconds since the Unix epoch.
125 * If an SCT's timestamp is after this time, it will be interpreted as having
126 * been issued in the future. RFC6962 states that "TLS clients MUST reject SCTs
127 * whose timestamp is in the future", so an SCT will not validate in this case.
129 void CT_POLICY_EVAL_CTX_set_time(CT_POLICY_EVAL_CTX
*ctx
, uint64_t time_in_ms
);
136 * Creates a new, blank SCT.
137 * The caller is responsible for calling SCT_free when finished with the SCT.
142 * Creates a new SCT from some base64-encoded strings.
143 * The caller is responsible for calling SCT_free when finished with the SCT.
145 SCT
*SCT_new_from_base64(unsigned char version
,
146 const char *logid_base64
,
147 ct_log_entry_type_t entry_type
,
149 const char *extensions_base64
,
150 const char *signature_base64
);
153 * Frees the SCT and the underlying data structures.
155 void SCT_free(SCT
*sct
);
158 * Free a stack of SCTs, and the underlying SCTs themselves.
159 * Intended to be compatible with X509V3_EXT_FREE.
161 void SCT_LIST_free(STACK_OF(SCT
) *a
);
164 * Returns the version of the SCT.
166 sct_version_t
SCT_get_version(const SCT
*sct
);
169 * Set the version of an SCT.
170 * Returns 1 on success, 0 if the version is unrecognized.
172 __owur
int SCT_set_version(SCT
*sct
, sct_version_t version
);
175 * Returns the log entry type of the SCT.
177 ct_log_entry_type_t
SCT_get_log_entry_type(const SCT
*sct
);
180 * Set the log entry type of an SCT.
181 * Returns 1 on success, 0 otherwise.
183 __owur
int SCT_set_log_entry_type(SCT
*sct
, ct_log_entry_type_t entry_type
);
186 * Gets the ID of the log that an SCT came from.
187 * Ownership of the log ID remains with the SCT.
188 * Returns the length of the log ID.
190 size_t SCT_get0_log_id(const SCT
*sct
, unsigned char **log_id
);
193 * Set the log ID of an SCT to point directly to the *log_id specified.
194 * The SCT takes ownership of the specified pointer.
195 * Returns 1 on success, 0 otherwise.
197 __owur
int SCT_set0_log_id(SCT
*sct
, unsigned char *log_id
, size_t log_id_len
);
200 * Set the log ID of an SCT.
201 * This makes a copy of the log_id.
202 * Returns 1 on success, 0 otherwise.
204 __owur
int SCT_set1_log_id(SCT
*sct
, const unsigned char *log_id
,
208 * Returns the timestamp for the SCT (epoch time in milliseconds).
210 uint64_t SCT_get_timestamp(const SCT
*sct
);
213 * Set the timestamp of an SCT (epoch time in milliseconds).
215 void SCT_set_timestamp(SCT
*sct
, uint64_t timestamp
);
218 * Return the NID for the signature used by the SCT.
219 * For CT v1, this will be either NID_sha256WithRSAEncryption or
220 * NID_ecdsa_with_SHA256 (or NID_undef if incorrect/unset).
222 int SCT_get_signature_nid(const SCT
*sct
);
225 * Set the signature type of an SCT
226 * For CT v1, this should be either NID_sha256WithRSAEncryption or
227 * NID_ecdsa_with_SHA256.
228 * Returns 1 on success, 0 otherwise.
230 __owur
int SCT_set_signature_nid(SCT
*sct
, int nid
);
233 * Set *ext to point to the extension data for the SCT. ext must not be NULL.
234 * The SCT retains ownership of this pointer.
235 * Returns length of the data pointed to.
237 size_t SCT_get0_extensions(const SCT
*sct
, unsigned char **ext
);
240 * Set the extensions of an SCT to point directly to the *ext specified.
241 * The SCT takes ownership of the specified pointer.
243 void SCT_set0_extensions(SCT
*sct
, unsigned char *ext
, size_t ext_len
);
246 * Set the extensions of an SCT.
247 * This takes a copy of the ext.
248 * Returns 1 on success, 0 otherwise.
250 __owur
int SCT_set1_extensions(SCT
*sct
, const unsigned char *ext
,
254 * Set *sig to point to the signature for the SCT. sig must not be NULL.
255 * The SCT retains ownership of this pointer.
256 * Returns length of the data pointed to.
258 size_t SCT_get0_signature(const SCT
*sct
, unsigned char **sig
);
261 * Set the signature of an SCT to point directly to the *sig specified.
262 * The SCT takes ownership of the specified pointer.
264 void SCT_set0_signature(SCT
*sct
, unsigned char *sig
, size_t sig_len
);
267 * Set the signature of an SCT to be a copy of the *sig specified.
268 * Returns 1 on success, 0 otherwise.
270 __owur
int SCT_set1_signature(SCT
*sct
, const unsigned char *sig
,
274 * The origin of this SCT, e.g. TLS extension, OCSP response, etc.
276 sct_source_t
SCT_get_source(const SCT
*sct
);
279 * Set the origin of this SCT, e.g. TLS extension, OCSP response, etc.
280 * Returns 1 on success, 0 otherwise.
282 __owur
int SCT_set_source(SCT
*sct
, sct_source_t source
);
285 * Returns a text string describing the validation status of |sct|.
287 const char *SCT_validation_status_string(const SCT
*sct
);
290 * Pretty-prints an |sct| to |out|.
291 * It will be indented by the number of spaces specified by |indent|.
292 * If |logs| is not NULL, it will be used to lookup the CT log that the SCT came
293 * from, so that the log name can be printed.
295 void SCT_print(const SCT
*sct
, BIO
*out
, int indent
, const CTLOG_STORE
*logs
);
298 * Pretty-prints an |sct_list| to |out|.
299 * It will be indented by the number of spaces specified by |indent|.
300 * SCTs will be delimited by |separator|.
301 * If |logs| is not NULL, it will be used to lookup the CT log that each SCT
302 * came from, so that the log names can be printed.
304 void SCT_LIST_print(const STACK_OF(SCT
) *sct_list
, BIO
*out
, int indent
,
305 const char *separator
, const CTLOG_STORE
*logs
);
308 * Gets the last result of validating this SCT.
309 * If it has not been validated yet, returns SCT_VALIDATION_STATUS_NOT_SET.
311 sct_validation_status_t
SCT_get_validation_status(const SCT
*sct
);
314 * Validates the given SCT with the provided context.
315 * Sets the "validation_status" field of the SCT.
316 * Returns 1 if the SCT is valid and the signature verifies.
317 * Returns 0 if the SCT is invalid or could not be verified.
318 * Returns -1 if an error occurs.
320 __owur
int SCT_validate(SCT
*sct
, const CT_POLICY_EVAL_CTX
*ctx
);
323 * Validates the given list of SCTs with the provided context.
324 * Sets the "validation_status" field of each SCT.
325 * Returns 1 if there are no invalid SCTs and all signatures verify.
326 * Returns 0 if at least one SCT is invalid or could not be verified.
327 * Returns a negative integer if an error occurs.
329 __owur
int SCT_LIST_validate(const STACK_OF(SCT
) *scts
,
330 CT_POLICY_EVAL_CTX
*ctx
);
333 /*********************************
334 * SCT parsing and serialisation *
335 *********************************/
338 * Serialize (to TLS format) a stack of SCTs and return the length.
339 * "a" must not be NULL.
340 * If "pp" is NULL, just return the length of what would have been serialized.
341 * If "pp" is not NULL and "*pp" is null, function will allocate a new pointer
342 * for data that caller is responsible for freeing (only if function returns
344 * If "pp" is NULL and "*pp" is not NULL, caller is responsible for ensuring
345 * that "*pp" is large enough to accept all of the serialized data.
346 * Returns < 0 on error, >= 0 indicating bytes written (or would have been)
349 __owur
int i2o_SCT_LIST(const STACK_OF(SCT
) *a
, unsigned char **pp
);
352 * Convert TLS format SCT list to a stack of SCTs.
353 * If "a" or "*a" is NULL, a new stack will be created that the caller is
354 * responsible for freeing (by calling SCT_LIST_free).
355 * "**pp" and "*pp" must not be NULL.
356 * Upon success, "*pp" will point to after the last bytes read, and a stack
358 * Upon failure, a NULL pointer will be returned, and the position of "*pp" is
361 STACK_OF(SCT
) *o2i_SCT_LIST(STACK_OF(SCT
) **a
, const unsigned char **pp
,
365 * Serialize (to DER format) a stack of SCTs and return the length.
366 * "a" must not be NULL.
367 * If "pp" is NULL, just returns the length of what would have been serialized.
368 * If "pp" is not NULL and "*pp" is null, function will allocate a new pointer
369 * for data that caller is responsible for freeing (only if function returns
371 * If "pp" is NULL and "*pp" is not NULL, caller is responsible for ensuring
372 * that "*pp" is large enough to accept all of the serialized data.
373 * Returns < 0 on error, >= 0 indicating bytes written (or would have been)
376 __owur
int i2d_SCT_LIST(const STACK_OF(SCT
) *a
, unsigned char **pp
);
379 * Parses an SCT list in DER format and returns it.
380 * If "a" or "*a" is NULL, a new stack will be created that the caller is
381 * responsible for freeing (by calling SCT_LIST_free).
382 * "**pp" and "*pp" must not be NULL.
383 * Upon success, "*pp" will point to after the last bytes read, and a stack
385 * Upon failure, a NULL pointer will be returned, and the position of "*pp" is
388 STACK_OF(SCT
) *d2i_SCT_LIST(STACK_OF(SCT
) **a
, const unsigned char **pp
,
392 * Serialize (to TLS format) an |sct| and write it to |out|.
393 * If |out| is null, no SCT will be output but the length will still be returned.
394 * If |out| points to a null pointer, a string will be allocated to hold the
395 * TLS-format SCT. It is the responsibility of the caller to free it.
396 * If |out| points to an allocated string, the TLS-format SCT will be written
398 * The length of the SCT in TLS format will be returned.
400 __owur
int i2o_SCT(const SCT
*sct
, unsigned char **out
);
403 * Parses an SCT in TLS format and returns it.
404 * If |psct| is not null, it will end up pointing to the parsed SCT. If it
405 * already points to a non-null pointer, the pointer will be free'd.
406 * |in| should be a pointer to a string containing the TLS-format SCT.
407 * |in| will be advanced to the end of the SCT if parsing succeeds.
408 * |len| should be the length of the SCT in |in|.
409 * Returns NULL if an error occurs.
410 * If the SCT is an unsupported version, only the SCT's 'sct' and 'sct_len'
411 * fields will be populated (with |in| and |len| respectively).
413 SCT
*o2i_SCT(SCT
**psct
, const unsigned char **in
, size_t len
);
415 /********************
417 ********************/
420 * Creates a new CT log instance with the given |public_key| and |name| and
421 * associates it with the give library context |libctx| and property query
423 * Takes ownership of |public_key| but copies |name|.
424 * Returns NULL if malloc fails or if |public_key| cannot be converted to DER.
425 * Should be deleted by the caller using CTLOG_free when no longer needed.
427 CTLOG
*CTLOG_new_with_libctx(EVP_PKEY
*public_key
, const char *name
,
428 OPENSSL_CTX
*libctx
, const char *propq
);
431 * The same as CTLOG_new_with_libctx except that the default library context and
432 * property query string are used.
434 CTLOG
*CTLOG_new(EVP_PKEY
*public_key
, const char *name
);
437 * Creates a new CTLOG instance with the base64-encoded SubjectPublicKeyInfo DER
438 * in |pkey_base64| and associated with the given library context |libctx| and
439 * property query string |propq|. The |name| is a string to help users identify
441 * Returns 1 on success, 0 on failure.
442 * Should be deleted by the caller using CTLOG_free when no longer needed.
444 int CTLOG_new_from_base64_with_libctx(CTLOG
**ct_log
, const char *pkey_base64
,
445 const char *name
, OPENSSL_CTX
*libctx
,
449 * The same as CTLOG_new_from_base64_with_libctx() except that the default
450 * library context and property query string are used.
451 * Returns 1 on success, 0 on failure.
453 int CTLOG_new_from_base64(CTLOG
** ct_log
,
454 const char *pkey_base64
, const char *name
);
457 * Deletes a CT log instance and its fields.
459 void CTLOG_free(CTLOG
*log
);
461 /* Gets the name of the CT log */
462 const char *CTLOG_get0_name(const CTLOG
*log
);
463 /* Gets the ID of the CT log */
464 void CTLOG_get0_log_id(const CTLOG
*log
, const uint8_t **log_id
,
466 /* Gets the public key of the CT log */
467 EVP_PKEY
*CTLOG_get0_public_key(const CTLOG
*log
);
469 /**************************
470 * CT log store functions *
471 **************************/
474 * Creates a new CT log store and associates it with the given libctx and
475 * property query string.
476 * Should be deleted by the caller using CTLOG_STORE_free when no longer needed.
478 CTLOG_STORE
*CTLOG_STORE_new_with_libctx(OPENSSL_CTX
*libctx
, const char *propq
);
481 * Same as CTLOG_STORE_new_with_libctx except that the default libctx and
482 * property query string are used.
483 * Should be deleted by the caller using CTLOG_STORE_free when no longer needed.
485 CTLOG_STORE
*CTLOG_STORE_new(void);
488 * Deletes a CT log store and all of the CT log instances held within.
490 void CTLOG_STORE_free(CTLOG_STORE
*store
);
493 * Finds a CT log in the store based on its log ID.
494 * Returns the CT log, or NULL if no match is found.
496 const CTLOG
*CTLOG_STORE_get0_log_by_id(const CTLOG_STORE
*store
,
497 const uint8_t *log_id
,
501 * Loads a CT log list into a |store| from a |file|.
502 * Returns 1 if loading is successful, or 0 otherwise.
504 __owur
int CTLOG_STORE_load_file(CTLOG_STORE
*store
, const char *file
);
507 * Loads the default CT log list into a |store|.
508 * Returns 1 if loading is successful, or 0 otherwise.
510 __owur
int CTLOG_STORE_load_default_file(CTLOG_STORE
*store
);