doc/crypto/SCT_new.pod

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