crypto/include/internal/ct_int.h

   1 /*
   2  * Written by Dr Stephen N Henson (steve@openssl.org) for the OpenSSL project
   3  * 2015.
   4  */
   5 /* ====================================================================
   6  * Copyright (c) 2015 The OpenSSL Project.  All rights reserved.
   7  *
   8  * Redistribution and use in source and binary forms, with or without
   9  * modification, are permitted provided that the following conditions
  10  * are met:
  11  *
  12  * 1. Redistributions of source code must retain the above copyright
  13  *    notice, this list of conditions and the following disclaimer.
  14  *
  15  * 2. Redistributions in binary form must reproduce the above copyright
  16  *    notice, this list of conditions and the following disclaimer in
  17  *    the documentation and/or other materials provided with the
  18  *    distribution.
  19  *
  20  * 3. All advertising materials mentioning features or use of this
  21  *    software must display the following acknowledgment:
  22  *    "This product includes software developed by the OpenSSL Project
  23  *    for use in the OpenSSL Toolkit. (http://www.OpenSSL.org/)"
  24  *
  25  * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  26  *    endorse or promote products derived from this software without
  27  *    prior written permission. For written permission, please contact
  28  *    licensing@OpenSSL.org.
  29  *
  30  * 5. Products derived from this software may not be called "OpenSSL"
  31  *    nor may "OpenSSL" appear in their names without prior written
  32  *    permission of the OpenSSL Project.
  33  *
  34  * 6. Redistributions of any form whatsoever must retain the following
  35  *    acknowledgment:
  36  *    "This product includes software developed by the OpenSSL Project
  37  *    for use in the OpenSSL Toolkit (http://www.OpenSSL.org/)"
  38  *
  39  * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  40  * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  41  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  42  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  43  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  44  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  45  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  46  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  47  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  48  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  49  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  50  * OF THE POSSIBILITY OF SUCH DAMAGE.
  51  * ====================================================================
  52  *
  53  */
  54 #ifndef HEADER_CT_LOCL_H
  55 # define HEADER_CT_LOCL_H
  56
  57 # ifdef __cplusplus
  58 extern "C" {
  59 # endif
  60
  61 # ifndef OPENSSL_NO_CT
  62
  63 # include <openssl/x509v3.h>
  64
  65 /* All hashes are currently SHA256 */
  66 #  define SCT_V1_HASHLEN  32
  67 /* Minimum RSA key size, from RFC6962 */
  68 #  define SCT_MIN_RSA_BITS 2048
  69
  70 /*
  71  * From RFC6962: opaque SerializedSCT<1..2^16-1>; struct { SerializedSCT
  72  * sct_list <1..2^16-1>; } SignedCertificateTimestampList;
  73  */
  74
  75 #  define MAX_SCT_SIZE            65535
  76 #  define MAX_SCT_LIST_SIZE       MAX_SCT_SIZE
  77
  78 typedef enum {
  79     UNSET_ENTRY = -1,
  80     X509_ENTRY = 0,
  81     PRECERT_ENTRY = 1
  82 } log_entry_type_t;
  83
  84 typedef enum {
  85     UNSET_VERSION = -1,
  86     SCT_V1 = 0
  87 } sct_version_t;
  88
  89 typedef struct {
  90     sct_version_t version;
  91     /* If version is not SCT_V1 this contains the encoded SCT */
  92     unsigned char *sct;
  93     size_t sct_len;
  94     /*
  95      * If version is SCT_V1, fields below contain components of the SCT.
  96      * "log_id", "ext" and "sig" point to buffers allocated with
  97      * OPENSSL_malloc().
  98      */
  99     unsigned char *log_id;
 100     size_t log_id_len;
 101
 102     /*
 103      * Note, we cannot distinguish between an unset timestamp, and one
 104      * that is set to 0.  However since CT didn't exist in 1970, no real
 105      * SCT should ever be set as such.
 106      */
 107     uint64_t timestamp;
 108     unsigned char *ext;
 109     size_t ext_len;
 110     /* TODO(robpercival): Extract the following 4 fields into a struct */
 111     unsigned char hash_alg;
 112     unsigned char sig_alg;
 113     unsigned char *sig;
 114     size_t sig_len;
 115     /* Log entry type */
 116     log_entry_type_t entry_type;
 117 } SCT;
 118
 119 DEFINE_STACK_OF(SCT)
 120
 121 extern const X509V3_EXT_METHOD v3_ct_scts[];
 122
 123 /*
 124  * Allocate new SCT.
 125  * Caller is responsible for calling SCT_free when done.
 126  */
 127 SCT *SCT_new(void);
 128
 129 /*
 130  * Free SCT and underlying datastructures.
 131  */
 132 void SCT_free(SCT *sct);
 133
 134 /*
 135  * Set the version of an SCT.
 136  * Returns 1 on success, 0 if the version is unrecognized.
 137  */
 138 int SCT_set_version(SCT *sct, sct_version_t version);
 139
 140 /*
 141  * Set the log entry type of an SCT.
 142  * Returns 1 on success.
 143  */
 144 int SCT_set_log_entry_type(SCT *sct, log_entry_type_t entry_type);
 145
 146 /*
 147  * Set the log ID of an SCT to point directly to the *log_id specified.
 148  * The SCT takes ownership of the specified pointer.
 149  * Returns 1 on success.
 150  */
 151 int SCT_set0_log_id(SCT *sct, unsigned char *log_id, size_t log_id_len);
 152
 153 /*
 154  * Set the log ID of an SCT.
 155  * This makes a copy of the log_id.
 156  * Returns 1 on success.
 157  */
 158 int SCT_set1_log_id(SCT *sct, const unsigned char *log_id, size_t log_id_len);
 159
 160 /*
 161  * Set the timestamp of an SCT.
 162  */
 163 void SCT_set_timestamp(SCT *sct, uint64_t timestamp);
 164
 165 /*
 166  * Set the signature type of an SCT
 167  * Currently NID_sha256WithRSAEncryption or NID_ecdsa_with_SHA256.
 168  * Returns 1 on success.
 169  */
 170 int SCT_set_signature_nid(SCT *sct, int nid);
 171
 172 /*
 173  * Set the extensions of an SCT to point directly to the *ext specified.
 174  * The SCT takes ownership of the specified pointer.
 175  */
 176 void SCT_set0_extensions(SCT *sct, unsigned char *ext, size_t ext_len);
 177
 178 /*
 179  * Set the extensions of an SCT.
 180  * This takes a copy of the ext.
 181  * Returns 1 on success.
 182  */
 183 int SCT_set1_extensions(SCT *sct, const unsigned char *ext, size_t ext_len);
 184
 185 /*
 186  * Set the signature of an SCT to point directly to the *sig specified.
 187  * The SCT takes ownership of the specified pointer.
 188  */
 189 void SCT_set0_signature(SCT *sct, unsigned char *sig, size_t sig_len);
 190
 191 /*
 192  * Set the signature of an SCT to be a copy of the *sig specified.
 193  * Returns 1 on success.
 194  */
 195 int SCT_set1_signature(SCT *sct, const unsigned char *sig, size_t sig_len);
 196
 197 /*
 198  * Returns the version of the SCT.
 199  */
 200 sct_version_t SCT_get_version(const SCT *sct);
 201
 202 /*
 203  * Returns the log entry type of the SCT.
 204  */
 205 log_entry_type_t SCT_get_log_entry_type(const SCT *sct);
 206
 207 /*
 208  * Set *log_id to point to the log id for the SCT. log_id must not be NULL.
 209  * The SCT retains ownership of this pointer.
 210  * Returns length of the data pointed to.
 211  */
 212 size_t SCT_get0_log_id(const SCT *sct, unsigned char **log_id);
 213
 214 /*
 215  * Returns the timestamp for the SCT.
 216  */
 217 uint64_t SCT_get_timestamp(const SCT *sct);
 218
 219 /*
 220  * Return the nid for the signature used by the SCT.
 221  * Currently NID_sha256WithRSAEncryption or NID_ecdsa_with_SHA256
 222  * (or NID_undef).
 223  */
 224 int SCT_get_signature_nid(const SCT *sct);
 225
 226 /*
 227  * Set *ext to point to the extension data for the SCT. ext must not be NULL.
 228  * The SCT retains ownership of this pointer.
 229  * Returns length of the data pointed to.
 230  */
 231 size_t SCT_get0_extensions(const SCT *sct, unsigned char **ext);
 232
 233 /*
 234  * Set *sig to point to the signature for the SCT. sig must not be NULL.
 235  * The SCT retains ownership of this pointer.
 236  * Returns length of the data pointed to.
 237  */
 238 size_t SCT_get0_signature(const SCT *sct, unsigned char **sig);
 239
 240 /*
 241  * Pretty-print debug information about a SCT, indented as specified.
 242  */
 243 void SCT_print(SCT *sct, BIO *out, int indent);
 244
 245 /*
 246  * Does this SCT have the minimum fields populated to be valid?
 247  * Returns 1 if so, 0 otherwise.
 248  * This does not verify the SCT signature.
 249  */
 250 int SCT_is_valid(const SCT *sct);
 251
 252 /*
 253  * Is the signature of this SCT valid?
 254  * Returns 1 if so, 0 otherwise.
 255  * This checks that the signature and hash algorithms are supported and that the
 256  * signature field is set.
 257  */
 258 int SCT_signature_is_valid(const SCT *sct);
 259
 260 /*
 261  * Free a stack of SCTs, and the underlying SCTs themselves.
 262  * Intended to be compatible with X509V3_EXT_FREE.
 263  */
 264 void SCT_LIST_free(STACK_OF(SCT) *a);
 265
 266 /*
 267  * Serialize (to TLS format) a stack of SCTs and return the length.
 268  * "a" must not be NULL.
 269  * If "pp" is NULL, just return the length of what would have been serialized.
 270  * If "pp" is not NULL and "*pp" is null, function will allocate a new pointer
 271  * for data that caller is responsible for freeing (only if function returns
 272  * successfully).
 273  * If "pp" is NULL and "*pp" is not NULL, caller is responsible for ensuring
 274  * that "*pp" is large enough to accept all of the serializied data.
 275  * Returns < 0 on error, >= 0 indicating bytes written (or would have been)
 276  * on success.
 277  */
 278 int i2o_SCT_LIST(STACK_OF(SCT) *a, unsigned char **pp);
 279
 280 /*
 281 * Parses an SCT signature in TLS format and populates the |sct| with it.
 282 * |in| should be a pointer to a string contianing the TLS-format signature.
 283 * |in| will be advanced to the end of the signature if parsing succeeds.
 284 * |len| should be the length of the signature in |in|.
 285 * Returns the number of bytes parsed, or a negative integer if an error occurs.
 286 */
 287 int o2i_SCT_signature(SCT *sct, const unsigned char **in, size_t len);
 288
 289 /*
 290  * Parses an SCT in TLS format and returns it.
 291  * If |psct| is not null, it will end up pointing to the parsed SCT. If it
 292  * already points to a non-null pointer, the pointer will be free'd.
 293  * |in| should be a pointer to a string contianing the TLS-format SCT.
 294  * |in| will be advanced to the end of the SCT if parsing succeeds.
 295  * |len| should be the length of the SCT in |in|.
 296  * Returns NULL if an error occurs.
 297  * If the SCT is an unsupported version, only the SCT's 'sct' and 'sct_len'
 298  * fields will be populated (with |in| and |len| respectively).
 299  */
 300 SCT *o2i_SCT(SCT **psct, const unsigned char **in, size_t len);
 301
 302 /*
 303 * Converts an |sct| signature into TLS format and writes it to |out|.
 304 * If |out| is null, no signature will be output but the length will be returned.
 305 * If |out| points to a null pointer, a string will be allocated to hold the
 306 * TLS-format signature. It is the responsibility of the caller to free it.
 307 * If |out| points to an allocated string, the signature will be written to it.
 308 * The length of the signature in TLS format will be returned.
 309 */
 310 int i2o_SCT_signature(const SCT *sct, unsigned char **out);
 311
 312 /*
 313  * Converts an |sct| into TLS format and writes it to |out|.
 314  * If |out| is null, no SCT will be output but the length will still be returned.
 315  * If |out| points to a null pointer, a string will be allocated to hold the
 316  * TLS-format SCT. It is the responsibility of the caller to free it.
 317  * If |out| points to an allocated string, the TLS-format SCT will be written
 318  * to it.
 319  * The length of the SCT in TLS format will be returned.
 320  */
 321 int i2o_SCT(const SCT *sct, unsigned char **out);
 322
 323 /*
 324  * Convert TLS format SCT list to a stack of SCTs.
 325  * If "a" or "*a" is NULL, a new stack will be created that the caller is
 326  * responsible for freeing (by calling SCT_LIST_free).
 327  * "**pp" and "*pp" must not be NULL.
 328  * Upon success, "*pp" will point to after the last bytes read, and a stack
 329  * will be returned.
 330  * Upon failure, a NULL pointer will be returned, and the position of "*p" is
 331  * not defined.
 332  */
 333 STACK_OF(SCT) *o2i_SCT_LIST(STACK_OF(SCT) **a, const unsigned char **pp,
 334                             size_t len);
 335
 336 # endif
 337
 338 /* BEGIN ERROR CODES */
 339 /*
 340  * The following lines are auto generated by the script mkerr.pl. Any changes
 341  * made after this point may be overwritten when the script is next run.
 342  */
 343 void ERR_load_CT_strings(void);
 344
 345 /* Error codes for the CT functions. */
 346
 347 /* Function codes. */
 348 # define CT_F_D2I_SCT_LIST                                105
 349 # define CT_F_I2D_SCT_LIST                                106
 350 # define CT_F_I2O_SCT                                     107
 351 # define CT_F_I2O_SCT_LIST                                108
 352 # define CT_F_I2O_SCT_SIGNATURE                           109
 353 # define CT_F_O2I_SCT                                     110
 354 # define CT_F_O2I_SCT_LIST                                111
 355 # define CT_F_O2I_SCT_SIGNATURE                           112
 356 # define CT_F_SCT_NEW                                     100
 357 # define CT_F_SCT_SET0_LOG_ID                             101
 358 # define CT_F_SCT_SET1_EXTENSIONS                         114
 359 # define CT_F_SCT_SET1_LOG_ID                             115
 360 # define CT_F_SCT_SET1_SIGNATURE                          116
 361 # define CT_F_SCT_SET_LOG_ENTRY_TYPE                      102
 362 # define CT_F_SCT_SET_SIGNATURE_NID                       103
 363 # define CT_F_SCT_SET_VERSION                             104
 364 # define CT_F_SCT_SIGNATURE_IS_VALID                      113
 365
 366 /* Reason codes. */
 367 # define CT_R_INVALID_LOG_ID_LENGTH                       100
 368 # define CT_R_SCT_INVALID                                 104
 369 # define CT_R_SCT_INVALID_SIGNATURE                       107
 370 # define CT_R_SCT_LIST_INVALID                            105
 371 # define CT_R_SCT_NOT_SET                                 106
 372 # define CT_R_UNRECOGNIZED_SIGNATURE_NID                  101
 373 # define CT_R_UNSUPPORTED_ENTRY_TYPE                      102
 374 # define CT_R_UNSUPPORTED_VERSION                         103
 375
 376 #ifdef  __cplusplus
 377 }
 378 #endif
 379 #endif