doc/man3/SCT_new.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SCT_new, SCT_new_from_base64, SCT_free, SCT_LIST_free,
   6 SCT_get_version, SCT_set_version,
   7 SCT_get_log_entry_type, SCT_set_log_entry_type,
   8 SCT_get0_log_id, SCT_set0_log_id, SCT_set1_log_id,
   9 SCT_get_timestamp, SCT_set_timestamp,
  10 SCT_get_signature_nid, SCT_set_signature_nid,
  11 SCT_get0_signature, SCT_set0_signature, SCT_set1_signature,
  12 SCT_get0_extensions, SCT_set0_extensions, SCT_set1_extensions,
  13 SCT_get_source, SCT_set_source
  14 - A Certificate Transparency Signed Certificate Timestamp
  15
  16 =head1 SYNOPSIS
  17
  18  #include <openssl/ct.h>
  19
  20  typedef enum {
  21      CT_LOG_ENTRY_TYPE_NOT_SET = -1,
  22      CT_LOG_ENTRY_TYPE_X509 = 0,
  23      CT_LOG_ENTRY_TYPE_PRECERT = 1
  24  } ct_log_entry_type_t;
  25
  26  typedef enum {
  27      SCT_VERSION_NOT_SET = -1,
  28      SCT_VERSION_V1 = 0
  29  } sct_version_t;
  30
  31  typedef enum {
  32      SCT_SOURCE_UNKNOWN,
  33      SCT_SOURCE_TLS_EXTENSION,
  34      SCT_SOURCE_X509V3_EXTENSION,
  35      SCT_SOURCE_OCSP_STAPLED_RESPONSE
  36  } sct_source_t;
  37
  38  SCT *SCT_new(void);
  39  SCT *SCT_new_from_base64(unsigned char version,
  40                           const char *logid_base64,
  41                           ct_log_entry_type_t entry_type,
  42                           uint64_t timestamp,
  43                           const char *extensions_base64,
  44                           const char *signature_base64);
  45
  46  void SCT_free(SCT *sct);
  47  void SCT_LIST_free(STACK_OF(SCT) *a);
  48
  49  sct_version_t SCT_get_version(const SCT *sct);
  50  int SCT_set_version(SCT *sct, sct_version_t version);
  51
  52  ct_log_entry_type_t SCT_get_log_entry_type(const SCT *sct);
  53  int SCT_set_log_entry_type(SCT *sct, ct_log_entry_type_t entry_type);
  54
  55  size_t SCT_get0_log_id(const SCT *sct, unsigned char **log_id);
  56  int SCT_set0_log_id(SCT *sct, unsigned char *log_id, size_t log_id_len);
  57  int SCT_set1_log_id(SCT *sct, const unsigned char *log_id, size_t log_id_len);
  58
  59  uint64_t SCT_get_timestamp(const SCT *sct);
  60  void SCT_set_timestamp(SCT *sct, uint64_t timestamp);
  61
  62  int SCT_get_signature_nid(const SCT *sct);
  63  int SCT_set_signature_nid(SCT *sct, int nid);
  64
  65  size_t SCT_get0_signature(const SCT *sct, unsigned char **sig);
  66  void SCT_set0_signature(SCT *sct, unsigned char *sig, size_t sig_len);
  67  int SCT_set1_signature(SCT *sct, const unsigned char *sig, size_t sig_len);
  68
  69  size_t SCT_get0_extensions(const SCT *sct, unsigned char **ext);
  70  void SCT_set0_extensions(SCT *sct, unsigned char *ext, size_t ext_len);
  71  int SCT_set1_extensions(SCT *sct, const unsigned char *ext, size_t ext_len);
  72
  73  sct_source_t SCT_get_source(const SCT *sct);
  74  int SCT_set_source(SCT *sct, sct_source_t source);
  75
  76 =head1 DESCRIPTION
  77
  78 Signed Certificate Timestamps (SCTs) are defined by RFC 6962, Section 3.2.
  79 They constitute a promise by a Certificate Transparency (CT) log to publicly
  80 record a certificate. By cryptographically verifying that a log did indeed issue
  81 an SCT, some confidence can be gained that the certificate is publicly known.
  82
  83 An internal representation of an SCT can be created in one of two ways.
  84 The first option is to create a blank SCT, using SCT_new(), and then populate
  85 it using:
  86
  87 =over 2
  88
  89 =item *
  90
  91 SCT_set_version() to set the SCT version.
  92
  93 Only SCT_VERSION_V1 is currently supported.
  94
  95 =item *
  96
  97 SCT_set_log_entry_type() to set the type of certificate the SCT was issued for:
  98
  99 B<CT_LOG_ENTRY_TYPE_X509> for a normal certificate.
 100 B<CT_LOG_ENTRY_TYPE_PRECERT> for a pre-certificate.
 101
 102 =item *
 103
 104 SCT_set0_log_id() or SCT_set1_log_id() to set the LogID of the CT log that the SCT came from.
 105
 106 The former takes ownership, whereas the latter makes a copy.
 107 See RFC 6962, Section 3.2 for the definition of LogID.
 108
 109 =item *
 110
 111 SCT_set_timestamp() to set the time the SCT was issued (time in milliseconds
 112 since the Unix Epoch).
 113
 114 =item *
 115
 116 SCT_set_signature_nid() to set the NID of the signature.
 117
 118 =item *
 119
 120 SCT_set0_signature() or SCT_set1_signature() to set the raw signature value.
 121
 122 The former takes ownership, whereas the latter makes a copy.
 123
 124 =item *
 125
 126 SCT_set0_extensions() or B<SCT_set1_extensions> to provide SCT extensions.
 127
 128 The former takes ownership, whereas the latter makes a copy.
 129
 130 =back
 131
 132 Alternatively, the SCT can be pre-populated from the following data using
 133 SCT_new_from_base64():
 134
 135 =over 2
 136
 137 =item *
 138
 139 The SCT version (only SCT_VERSION_V1 is currently supported).
 140
 141 =item *
 142
 143 The LogID (see RFC 6962, Section 3.2), base64 encoded.
 144
 145 =item *
 146
 147 The type of certificate the SCT was issued for:
 148 B<CT_LOG_ENTRY_TYPE_X509> for a normal certificate.
 149 B<CT_LOG_ENTRY_TYPE_PRECERT> for a pre-certificate.
 150
 151 =item *
 152
 153 The time that the SCT was issued (time in milliseconds since the Unix Epoch).
 154
 155 =item *
 156
 157 The SCT extensions, base64 encoded.
 158
 159 =item *
 160
 161 The SCT signature, base64 encoded.
 162
 163 =back
 164
 165 SCT_set_source() can be used to record where the SCT was found
 166 (TLS extension, X.509 certificate extension or OCSP response). This is not
 167 required for verifying the SCT.
 168
 169 =head1 NOTES
 170
 171 Some of the setters return int, instead of void. These will all return 1 on
 172 success, 0 on failure. They will not make changes on failure.
 173
 174 All of the setters will reset the validation status of the SCT to
 175 SCT_VALIDATION_STATUS_NOT_SET (see L<SCT_validate(3)>).
 176
 177 SCT_set_source() will call SCT_set_log_entry_type() if the type of
 178 certificate the SCT was issued for can be inferred from where the SCT was found.
 179 For example, an SCT found in an X.509 extension must have been issued for a pre-
 180 certificate.
 181
 182 SCT_set_source() will not refuse unknown values.
 183
 184 =head1 RETURN VALUES
 185
 186 SCT_set_version() returns 1 if the specified version is supported, 0 otherwise.
 187
 188 SCT_set_log_entry_type() returns 1 if the specified log entry type is supported, 0 otherwise.
 189
 190 SCT_set0_log_id() and B<SCT_set1_log_id> return 1 if the specified LogID is a
 191 valid SHA-256 hash, 0 otherwise. Additionally, B<SCT_set1_log_id> returns 0 if
 192 malloc fails.
 193
 194 B<SCT_set_signature_nid> returns 1 if the specified NID is supported, 0 otherwise.
 195
 196 B<SCT_set1_extensions> and B<SCT_set1_signature> return 1 if the supplied buffer
 197 is copied successfully, 0 otherwise (i.e. if malloc fails).
 198
 199 B<SCT_set_source> returns 1 on success, 0 otherwise.
 200
 201 =head1 SEE ALSO
 202
 203 L<ct(7)>,
 204 L<SCT_validate(3)>,
 205 L<OBJ_nid2obj(3)>
 206
 207 =head1 HISTORY
 208
 209 These functions were added in OpenSSL 1.1.0.
 210
 211 =head1 COPYRIGHT
 212
 213 Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.
 214
 215 Licensed under the Apache License 2.0 (the "License").  You may not use
 216 this file except in compliance with the License.  You can obtain a copy
 217 in the file LICENSE in the source distribution or at
 218 L<https://www.openssl.org/source/license.html>.
 219
 220 =cut