Check for errors allocating the error strings.
[openssl.git] / include / openssl / ct.h
1 /*
2  * Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
3  *
4  * Licensed under the OpenSSL license (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 HEADER_CT_H
11 # define HEADER_CT_H
12
13 # include <openssl/opensslconf.h>
14
15 # ifndef OPENSSL_NO_CT
16 # include <openssl/ossl_typ.h>
17 # include <openssl/safestack.h>
18 # include <openssl/x509.h>
19 # ifdef  __cplusplus
20 extern "C" {
21 # endif
22
23
24 /* Minimum RSA key size, from RFC6962 */
25 # define SCT_MIN_RSA_BITS 2048
26
27 /* All hashes are SHA256 in v1 of Certificate Transparency */
28 # define CT_V1_HASHLEN SHA256_DIGEST_LENGTH
29
30 typedef enum {
31     CT_LOG_ENTRY_TYPE_NOT_SET = -1,
32     CT_LOG_ENTRY_TYPE_X509 = 0,
33     CT_LOG_ENTRY_TYPE_PRECERT = 1
34 } ct_log_entry_type_t;
35
36 typedef enum {
37     SCT_VERSION_NOT_SET = -1,
38     SCT_VERSION_V1 = 0
39 } sct_version_t;
40
41 typedef enum {
42     SCT_SOURCE_UNKNOWN,
43     SCT_SOURCE_TLS_EXTENSION,
44     SCT_SOURCE_X509V3_EXTENSION,
45     SCT_SOURCE_OCSP_STAPLED_RESPONSE
46 } sct_source_t;
47
48 typedef enum {
49     SCT_VALIDATION_STATUS_NOT_SET,
50     SCT_VALIDATION_STATUS_UNKNOWN_LOG,
51     SCT_VALIDATION_STATUS_VALID,
52     SCT_VALIDATION_STATUS_INVALID,
53     SCT_VALIDATION_STATUS_UNVERIFIED,
54     SCT_VALIDATION_STATUS_UNKNOWN_VERSION
55 } sct_validation_status_t;
56
57 DEFINE_STACK_OF(SCT)
58 DEFINE_STACK_OF(CTLOG)
59
60 /******************************************
61  * CT policy evaluation context functions *
62  ******************************************/
63
64 /* Creates a new, empty policy evaluation context */
65 CT_POLICY_EVAL_CTX *CT_POLICY_EVAL_CTX_new(void);
66
67 /* Deletes a policy evaluation context */
68 void CT_POLICY_EVAL_CTX_free(CT_POLICY_EVAL_CTX *ctx);
69
70 /* Gets the peer certificate that the SCTs are for */
71 X509* CT_POLICY_EVAL_CTX_get0_cert(const CT_POLICY_EVAL_CTX *ctx);
72
73 /* Sets the certificate associated with the received SCTs */
74 void CT_POLICY_EVAL_CTX_set0_cert(CT_POLICY_EVAL_CTX *ctx, X509 *cert);
75
76 /* Gets the issuer of the aforementioned certificate */
77 X509* CT_POLICY_EVAL_CTX_get0_issuer(const CT_POLICY_EVAL_CTX *ctx);
78
79 /* Sets the issuer of the certificate associated with the received SCTs */
80 void CT_POLICY_EVAL_CTX_set0_issuer(CT_POLICY_EVAL_CTX *ctx, X509 *issuer);
81
82 /* Gets the CT logs that are trusted sources of SCTs */
83 const CTLOG_STORE *CT_POLICY_EVAL_CTX_get0_log_store(const CT_POLICY_EVAL_CTX *ctx);
84
85 /* Sets the log store that is in use */
86 void CT_POLICY_EVAL_CTX_set0_log_store(CT_POLICY_EVAL_CTX *ctx,
87                                        CTLOG_STORE *log_store);
88
89 /*****************
90  * SCT functions *
91  *****************/
92
93 /*
94  * Creates a new, blank SCT.
95  * The caller is responsible for calling SCT_free when finished with the SCT.
96  */
97 SCT *SCT_new(void);
98
99 /*
100  * Creates a new SCT from some base64-encoded strings.
101  * The caller is responsible for calling SCT_free when finished with the SCT.
102  */
103 SCT *SCT_new_from_base64(unsigned char version,
104                          const char *logid_base64,
105                          ct_log_entry_type_t entry_type,
106                          uint64_t timestamp,
107                          const char *extensions_base64,
108                          const char *signature_base64);
109
110 /*
111  * Frees the SCT and the underlying data structures.
112  */
113 void SCT_free(SCT *sct);
114
115 /*
116  * Free a stack of SCTs, and the underlying SCTs themselves.
117  * Intended to be compatible with X509V3_EXT_FREE.
118  */
119 void SCT_LIST_free(STACK_OF(SCT) *a);
120
121 /*
122  * Returns the version of the SCT.
123  */
124 sct_version_t SCT_get_version(const SCT *sct);
125
126 /*
127  * Set the version of an SCT.
128  * Returns 1 on success, 0 if the version is unrecognized.
129  */
130 __owur int SCT_set_version(SCT *sct, sct_version_t version);
131
132 /*
133  * Returns the log entry type of the SCT.
134  */
135 ct_log_entry_type_t SCT_get_log_entry_type(const SCT *sct);
136
137 /*
138  * Set the log entry type of an SCT.
139  * Returns 1 on success, 0 otherwise.
140  */
141 __owur int SCT_set_log_entry_type(SCT *sct, ct_log_entry_type_t entry_type);
142
143 /*
144  * Gets the ID of the log that an SCT came from.
145  * Ownership of the log ID remains with the SCT.
146  * Returns the length of the log ID.
147  */
148 size_t SCT_get0_log_id(const SCT *sct, unsigned char **log_id);
149
150 /*
151  * Set the log ID of an SCT to point directly to the *log_id specified.
152  * The SCT takes ownership of the specified pointer.
153  * Returns 1 on success, 0 otherwise.
154  */
155 __owur int SCT_set0_log_id(SCT *sct, unsigned char *log_id, size_t log_id_len);
156
157 /*
158  * Set the log ID of an SCT.
159  * This makes a copy of the log_id.
160  * Returns 1 on success, 0 otherwise.
161  */
162 __owur int SCT_set1_log_id(SCT *sct, const unsigned char *log_id,
163                            size_t log_id_len);
164
165 /*
166  * Returns the timestamp for the SCT (epoch time in milliseconds).
167  */
168 uint64_t SCT_get_timestamp(const SCT *sct);
169
170 /*
171  * Set the timestamp of an SCT (epoch time in milliseconds).
172  */
173 void SCT_set_timestamp(SCT *sct, uint64_t timestamp);
174
175 /*
176  * Return the NID for the signature used by the SCT.
177  * For CT v1, this will be either NID_sha256WithRSAEncryption or
178  * NID_ecdsa_with_SHA256 (or NID_undef if incorrect/unset).
179  */
180 int SCT_get_signature_nid(const SCT *sct);
181
182 /*
183  * Set the signature type of an SCT
184  * For CT v1, this should be either NID_sha256WithRSAEncryption or
185  * NID_ecdsa_with_SHA256.
186  * Returns 1 on success, 0 otherwise.
187  */
188 __owur int SCT_set_signature_nid(SCT *sct, int nid);
189
190 /*
191  * Set *ext to point to the extension data for the SCT. ext must not be NULL.
192  * The SCT retains ownership of this pointer.
193  * Returns length of the data pointed to.
194  */
195 size_t SCT_get0_extensions(const SCT *sct, unsigned char **ext);
196
197 /*
198  * Set the extensions of an SCT to point directly to the *ext specified.
199  * The SCT takes ownership of the specified pointer.
200  */
201 void SCT_set0_extensions(SCT *sct, unsigned char *ext, size_t ext_len);
202
203 /*
204  * Set the extensions of an SCT.
205  * This takes a copy of the ext.
206  * Returns 1 on success, 0 otherwise.
207  */
208 __owur int SCT_set1_extensions(SCT *sct, const unsigned char *ext,
209                                size_t ext_len);
210
211 /*
212  * Set *sig to point to the signature for the SCT. sig must not be NULL.
213  * The SCT retains ownership of this pointer.
214  * Returns length of the data pointed to.
215  */
216 size_t SCT_get0_signature(const SCT *sct, unsigned char **sig);
217
218 /*
219  * Set the signature of an SCT to point directly to the *sig specified.
220  * The SCT takes ownership of the specified pointer.
221  */
222 void SCT_set0_signature(SCT *sct, unsigned char *sig, size_t sig_len);
223
224 /*
225  * Set the signature of an SCT to be a copy of the *sig specified.
226  * Returns 1 on success, 0 otherwise.
227  */
228 __owur int SCT_set1_signature(SCT *sct, const unsigned char *sig,
229                               size_t sig_len);
230
231 /*
232  * The origin of this SCT, e.g. TLS extension, OCSP response, etc.
233  */
234 sct_source_t SCT_get_source(const SCT *sct);
235
236 /*
237  * Set the origin of this SCT, e.g. TLS extension, OCSP response, etc.
238  * Returns 1 on success, 0 otherwise.
239  */
240 __owur int SCT_set_source(SCT *sct, sct_source_t source);
241
242 /*
243  * Returns a text string describing the validation status of |sct|.
244  */
245 const char *SCT_validation_status_string(const SCT *sct);
246
247 /*
248  * Pretty-prints an |sct| to |out|.
249  * It will be indented by the number of spaces specified by |indent|.
250  * If |logs| is not NULL, it will be used to lookup the CT log that the SCT came
251  * from, so that the log name can be printed.
252  */
253 void SCT_print(const SCT *sct, BIO *out, int indent, const CTLOG_STORE *logs);
254
255 /*
256  * Pretty-prints an |sct_list| to |out|.
257  * It will be indented by the number of spaces specified by |indent|.
258  * SCTs will be delimited by |separator|.
259  * If |logs| is not NULL, it will be used to lookup the CT log that each SCT
260  * came from, so that the log names can be printed.
261  */
262 void SCT_LIST_print(const STACK_OF(SCT) *sct_list, BIO *out, int indent,
263                     const char *separator, const CTLOG_STORE *logs);
264
265 /*
266  * Verifies an SCT with the given context.
267  * Returns 1 if the SCT verifies successfully, 0 otherwise.
268  */
269 __owur int SCT_verify(const SCT_CTX *sctx, const SCT *sct);
270
271 /*
272  * Verifies an SCT against the provided data.
273  * Returns 1 if the SCT verifies successfully, 0 otherwise.
274  */
275 __owur int SCT_verify_v1(SCT *sct, X509 *cert, X509 *preissuer,
276                   X509_PUBKEY *log_pubkey, X509 *issuer_cert);
277
278 /*
279  * Gets the last result of validating this SCT.
280  * If it has not been validated yet, returns SCT_VALIDATION_STATUS_NOT_SET.
281  */
282 sct_validation_status_t SCT_get_validation_status(const SCT *sct);
283
284 /*
285  * Validates the given SCT with the provided context.
286  * Sets the "validation_status" field of the SCT.
287  * Returns 1 if the SCT is valid and the signature verifies.
288  * Returns 0 if the SCT is invalid or could not be verified.
289  * Returns -1 if an error occurs.
290  */
291 __owur int SCT_validate(SCT *sct, const CT_POLICY_EVAL_CTX *ctx);
292
293 /*
294  * Validates the given list of SCTs with the provided context.
295  * Populates the "good_scts" and "bad_scts" of the evaluation context.
296  * Returns 1 if there are no invalid SCTs and all signatures verify.
297  * Returns 0 if at least one SCT is invalid or could not be verified.
298  * Returns a negative integer if an error occurs.
299  */
300 __owur int SCT_LIST_validate(const STACK_OF(SCT) *scts,
301                              CT_POLICY_EVAL_CTX *ctx);
302
303
304 /*********************************
305  * SCT parsing and serialisation *
306  *********************************/
307
308 /*
309  * Serialize (to TLS format) a stack of SCTs and return the length.
310  * "a" must not be NULL.
311  * If "pp" is NULL, just return the length of what would have been serialized.
312  * If "pp" is not NULL and "*pp" is null, function will allocate a new pointer
313  * for data that caller is responsible for freeing (only if function returns
314  * successfully).
315  * If "pp" is NULL and "*pp" is not NULL, caller is responsible for ensuring
316  * that "*pp" is large enough to accept all of the serialized data.
317  * Returns < 0 on error, >= 0 indicating bytes written (or would have been)
318  * on success.
319  */
320 __owur int i2o_SCT_LIST(const STACK_OF(SCT) *a, unsigned char **pp);
321
322 /*
323  * Convert TLS format SCT list to a stack of SCTs.
324  * If "a" or "*a" is NULL, a new stack will be created that the caller is
325  * responsible for freeing (by calling SCT_LIST_free).
326  * "**pp" and "*pp" must not be NULL.
327  * Upon success, "*pp" will point to after the last bytes read, and a stack
328  * will be returned.
329  * Upon failure, a NULL pointer will be returned, and the position of "*pp" is
330  * not defined.
331  */
332 STACK_OF(SCT) *o2i_SCT_LIST(STACK_OF(SCT) **a, const unsigned char **pp,
333                             size_t len);
334
335 /*
336  * Serialize (to DER format) a stack of SCTs and return the length.
337  * "a" must not be NULL.
338  * If "pp" is NULL, just returns the length of what would have been serialized.
339  * If "pp" is not NULL and "*pp" is null, function will allocate a new pointer
340  * for data that caller is responsible for freeing (only if function returns
341  * successfully).
342  * If "pp" is NULL and "*pp" is not NULL, caller is responsible for ensuring
343  * that "*pp" is large enough to accept all of the serialized data.
344  * Returns < 0 on error, >= 0 indicating bytes written (or would have been)
345  * on success.
346  */
347 __owur int i2d_SCT_LIST(const STACK_OF(SCT) *a, unsigned char **pp);
348
349 /*
350  * Parses an SCT list in DER format and returns it.
351  * If "a" or "*a" is NULL, a new stack will be created that the caller is
352  * responsible for freeing (by calling SCT_LIST_free).
353  * "**pp" and "*pp" must not be NULL.
354  * Upon success, "*pp" will point to after the last bytes read, and a stack
355  * will be returned.
356  * Upon failure, a NULL pointer will be returned, and the position of "*pp" is
357  * not defined.
358  */
359 STACK_OF(SCT) *d2i_SCT_LIST(STACK_OF(SCT) **a, const unsigned char **pp,
360                             long len);
361
362 /*
363  * Serialize (to TLS format) an |sct| and write it to |out|.
364  * If |out| is null, no SCT will be output but the length will still be returned.
365  * If |out| points to a null pointer, a string will be allocated to hold the
366  * TLS-format SCT. It is the responsibility of the caller to free it.
367  * If |out| points to an allocated string, the TLS-format SCT will be written
368  * to it.
369  * The length of the SCT in TLS format will be returned.
370  */
371 __owur int i2o_SCT(const SCT *sct, unsigned char **out);
372
373 /*
374  * Parses an SCT in TLS format and returns it.
375  * If |psct| is not null, it will end up pointing to the parsed SCT. If it
376  * already points to a non-null pointer, the pointer will be free'd.
377  * |in| should be a pointer to a string containing the TLS-format SCT.
378  * |in| will be advanced to the end of the SCT if parsing succeeds.
379  * |len| should be the length of the SCT in |in|.
380  * Returns NULL if an error occurs.
381  * If the SCT is an unsupported version, only the SCT's 'sct' and 'sct_len'
382  * fields will be populated (with |in| and |len| respectively).
383  */
384 SCT *o2i_SCT(SCT **psct, const unsigned char **in, size_t len);
385
386 /*
387 * Serialize (to TLS format) an |sct| signature and write it to |out|.
388 * If |out| is null, no signature will be output but the length will be returned.
389 * If |out| points to a null pointer, a string will be allocated to hold the
390 * TLS-format signature. It is the responsibility of the caller to free it.
391 * If |out| points to an allocated string, the signature will be written to it.
392 * The length of the signature in TLS format will be returned.
393 */
394 __owur int i2o_SCT_signature(const SCT *sct, unsigned char **out);
395
396 /*
397 * Parses an SCT signature in TLS format and populates the |sct| with it.
398 * |in| should be a pointer to a string containing the TLS-format signature.
399 * |in| will be advanced to the end of the signature if parsing succeeds.
400 * |len| should be the length of the signature in |in|.
401 * Returns the number of bytes parsed, or a negative integer if an error occurs.
402 */
403 __owur int o2i_SCT_signature(SCT *sct, const unsigned char **in, size_t len);
404
405 /********************
406  * CT log functions *
407  ********************/
408
409 /*
410  * Creates a new CT log instance with the given |public_key| and |name|.
411  * Should be deleted by the caller using CTLOG_free when no longer needed.
412  */
413 CTLOG *CTLOG_new(EVP_PKEY *public_key, const char *name);
414
415 /*
416  * Creates a new, blank CT log instance.
417  * Should be deleted by the caller using CTLOG_free when no longer needed.
418  */
419 CTLOG *CTLOG_new_null(void);
420
421 /*
422  * Creates a new CT |ct_log| instance with the given base64 public_key and |name|.
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  * See internal/cryptlib.h for the environment variable and file path that are
473  * consulted to find the default file.
474  * Returns 1 if loading is successful, or 0 otherwise.
475  */
476 __owur int CTLOG_STORE_load_default_file(CTLOG_STORE *store);
477
478 /* BEGIN ERROR CODES */
479 /*
480  * The following lines are auto generated by the script mkerr.pl. Any changes
481  * made after this point may be overwritten when the script is next run.
482  */
483
484 int ERR_load_CT_strings(void);
485
486 /* Error codes for the CT functions. */
487
488 /* Function codes. */
489 # define CT_F_CTLOG_NEW                                   117
490 # define CT_F_CTLOG_NEW_FROM_BASE64                       118
491 # define CT_F_CTLOG_NEW_FROM_CONF                         119
492 # define CT_F_CTLOG_NEW_NULL                              120
493 # define CT_F_CTLOG_STORE_LOAD_CTX_NEW                    122
494 # define CT_F_CTLOG_STORE_LOAD_FILE                       123
495 # define CT_F_CTLOG_STORE_LOAD_LOG                        130
496 # define CT_F_CTLOG_STORE_NEW                             131
497 # define CT_F_CT_BASE64_DECODE                            124
498 # define CT_F_CT_POLICY_EVAL_CTX_NEW                      133
499 # define CT_F_CT_V1_LOG_ID_FROM_PKEY                      125
500 # define CT_F_I2O_SCT                                     107
501 # define CT_F_I2O_SCT_LIST                                108
502 # define CT_F_I2O_SCT_SIGNATURE                           109
503 # define CT_F_O2I_SCT                                     110
504 # define CT_F_O2I_SCT_LIST                                111
505 # define CT_F_O2I_SCT_SIGNATURE                           112
506 # define CT_F_SCT_CTX_NEW                                 126
507 # define CT_F_SCT_NEW                                     100
508 # define CT_F_SCT_NEW_FROM_BASE64                         127
509 # define CT_F_SCT_SET0_LOG_ID                             101
510 # define CT_F_SCT_SET1_EXTENSIONS                         114
511 # define CT_F_SCT_SET1_LOG_ID                             115
512 # define CT_F_SCT_SET1_SIGNATURE                          116
513 # define CT_F_SCT_SET_LOG_ENTRY_TYPE                      102
514 # define CT_F_SCT_SET_SIGNATURE_NID                       103
515 # define CT_F_SCT_SET_VERSION                             104
516 # define CT_F_SCT_VERIFY                                  128
517 # define CT_F_SCT_VERIFY_V1                               129
518
519 /* Reason codes. */
520 # define CT_R_BASE64_DECODE_ERROR                         108
521 # define CT_R_INVALID_LOG_ID_LENGTH                       100
522 # define CT_R_LOG_CONF_INVALID                            109
523 # define CT_R_LOG_CONF_INVALID_KEY                        110
524 # define CT_R_LOG_CONF_MISSING_DESCRIPTION                111
525 # define CT_R_LOG_CONF_MISSING_KEY                        112
526 # define CT_R_LOG_KEY_INVALID                             113
527 # define CT_R_SCT_INVALID                                 104
528 # define CT_R_SCT_INVALID_SIGNATURE                       107
529 # define CT_R_SCT_LIST_INVALID                            105
530 # define CT_R_SCT_LOG_ID_MISMATCH                         114
531 # define CT_R_SCT_NOT_SET                                 106
532 # define CT_R_SCT_UNSUPPORTED_VERSION                     115
533 # define CT_R_UNRECOGNIZED_SIGNATURE_NID                  101
534 # define CT_R_UNSUPPORTED_ENTRY_TYPE                      102
535 # define CT_R_UNSUPPORTED_VERSION                         103
536
537 #  ifdef  __cplusplus
538 }
539 #  endif
540 # endif
541 #endif