1=pod 2 3=head1 NAME 4 5SCT_new, SCT_new_from_base64, SCT_free, SCT_LIST_free, 6SCT_get_version, SCT_set_version, 7SCT_get_log_entry_type, SCT_set_log_entry_type, 8SCT_get0_log_id, SCT_set0_log_id, SCT_set1_log_id, 9SCT_get_timestamp, SCT_set_timestamp, 10SCT_get_signature_nid, SCT_set_signature_nid, 11SCT_get0_signature, SCT_set0_signature, SCT_set1_signature, 12SCT_get0_extensions, SCT_set0_extensions, SCT_set1_extensions, 13SCT_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 78Signed Certificate Timestamps (SCTs) are defined by RFC 6962, Section 3.2. 79They constitute a promise by a Certificate Transparency (CT) log to publicly 80record a certificate. By cryptographically verifying that a log did indeed issue 81an SCT, some confidence can be gained that the certificate is publicly known. 82 83An internal representation of an SCT can be created in one of two ways. 84The first option is to create a blank SCT, using SCT_new(), and then populate 85it using: 86 87=over 2 88 89=item * 90 91SCT_set_version() to set the SCT version. 92 93Only SCT_VERSION_V1 is currently supported. 94 95=item * 96 97SCT_set_log_entry_type() to set the type of certificate the SCT was issued for: 98 99B<CT_LOG_ENTRY_TYPE_X509> for a normal certificate. 100B<CT_LOG_ENTRY_TYPE_PRECERT> for a pre-certificate. 101 102=item * 103 104SCT_set0_log_id() or SCT_set1_log_id() to set the LogID of the CT log that the SCT came from. 105 106The former takes ownership, whereas the latter makes a copy. 107See RFC 6962, Section 3.2 for the definition of LogID. 108 109=item * 110 111SCT_set_timestamp() to set the time the SCT was issued (epoch time in milliseconds). 112 113=item * 114 115SCT_set_signature_nid() to set the NID of the signature. 116 117=item * 118 119SCT_set0_signature() or SCT_set1_signature() to set the raw signature value. 120 121The former takes ownership, whereas the latter makes a copy. 122 123=item * 124 125SCT_set0_extensions() or B<SCT_set1_extensions> to provide SCT extensions. 126 127The former takes ownership, whereas the latter makes a copy. 128 129=back 130 131Alternatively, the SCT can be pre-populated from the following data using 132SCT_new_from_base64(): 133 134=over 2 135 136=item * 137 138The SCT version (only SCT_VERSION_V1 is currently supported). 139 140=item * 141 142The LogID (see RFC 6962, Section 3.2), base64 encoded. 143 144=item * 145 146The type of certificate the SCT was issued for: 147B<CT_LOG_ENTRY_TYPE_X509> for a normal certificate. 148B<CT_LOG_ENTRY_TYPE_PRECERT> for a pre-certificate. 149 150=item * 151 152The time that the SCT was issued (epoch time in milliseconds). 153 154=item * 155 156The SCT extensions, base64 encoded. 157 158=item * 159 160The SCT signature, base64 encoded. 161 162=back 163 164SCT_set_source() can be used to record where the SCT was found 165(TLS extension, X.509 certificate extension or OCSP response). This is not 166required for verifying the SCT. 167 168=head1 NOTES 169 170Some of the setters return int, instead of void. These will all return 1 on 171success, 0 on failure. They will not make changes on failure. 172 173All of the setters will reset the validation status of the SCT to 174SCT_VALIDATION_STATUS_NOT_SET (see L<SCT_validate(3)>). 175 176SCT_set_source() will call SCT_set_log_entry_type() if the type of 177certificate the SCT was issued for can be inferred from where the SCT was found. 178For example, an SCT found in an X.509 extension must have been issued for a pre- 179certificate. 180 181SCT_set_source() will not refuse unknown values. 182 183=head1 RETURN VALUES 184 185SCT_set_version() returns 1 if the specified version is supported, 0 otherwise. 186 187SCT_set_log_entry_type() returns 1 if the specified log entry type is supported, 0 otherwise. 188 189SCT_set0_log_id() and B<SCT_set1_log_id> return 1 if the specified LogID is a 190valid SHA-256 hash, 0 otherwise. Additionally, B<SCT_set1_log_id> returns 0 if 191malloc fails. 192 193B<SCT_set_signature_nid> returns 1 if the specified NID is supported, 0 otherwise. 194 195B<SCT_set1_extensions> and B<SCT_set1_signature> return 1 if the supplied buffer 196is copied successfully, 0 otherwise (i.e. if malloc fails). 197 198B<SCT_set_source> returns 1 on success, 0 otherwise. 199 200=head1 SEE ALSO 201 202L<ct(7)>, 203L<SCT_validate(3)>, 204L<OBJ_nid2obj(3)> 205 206=head1 HISTORY 207 208These functions were added in OpenSSL 1.1.0. 209 210=head1 COPYRIGHT 211 212Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved. 213 214Licensed under the OpenSSL license (the "License"). You may not use 215this file except in compliance with the License. You can obtain a copy 216in the file LICENSE in the source distribution or at 217L<https://www.openssl.org/source/license.html>. 218 219=cut 220