SCT_new(3ossl)

1SCT_NEW(3ossl)                      OpenSSL                     SCT_NEW(3ossl)
2
3
4

NAME

6       SCT_new, SCT_new_from_base64, SCT_free, SCT_LIST_free, SCT_get_version,
7       SCT_set_version, SCT_get_log_entry_type, SCT_set_log_entry_type,
8       SCT_get0_log_id, SCT_set0_log_id, SCT_set1_log_id, SCT_get_timestamp,
9       SCT_set_timestamp, SCT_get_signature_nid, SCT_set_signature_nid,
10       SCT_get0_signature, SCT_set0_signature, SCT_set1_signature,
11       SCT_get0_extensions, SCT_set0_extensions, SCT_set1_extensions,
12       SCT_get_source, SCT_set_source - A Certificate Transparency Signed
13       Certificate Timestamp
14

SYNOPSIS

16        #include <openssl/ct.h>
17
18        typedef enum {
19            CT_LOG_ENTRY_TYPE_NOT_SET = -1,
20            CT_LOG_ENTRY_TYPE_X509 = 0,
21            CT_LOG_ENTRY_TYPE_PRECERT = 1
22        } ct_log_entry_type_t;
23
24        typedef enum {
25            SCT_VERSION_NOT_SET = -1,
26            SCT_VERSION_V1 = 0
27        } sct_version_t;
28
29        typedef enum {
30            SCT_SOURCE_UNKNOWN,
31            SCT_SOURCE_TLS_EXTENSION,
32            SCT_SOURCE_X509V3_EXTENSION,
33            SCT_SOURCE_OCSP_STAPLED_RESPONSE
34        } sct_source_t;
35
36        SCT *SCT_new(void);
37        SCT *SCT_new_from_base64(unsigned char version,
38                                 const char *logid_base64,
39                                 ct_log_entry_type_t entry_type,
40                                 uint64_t timestamp,
41                                 const char *extensions_base64,
42                                 const char *signature_base64);
43
44        void SCT_free(SCT *sct);
45        void SCT_LIST_free(STACK_OF(SCT) *a);
46
47        sct_version_t SCT_get_version(const SCT *sct);
48        int SCT_set_version(SCT *sct, sct_version_t version);
49
50        ct_log_entry_type_t SCT_get_log_entry_type(const SCT *sct);
51        int SCT_set_log_entry_type(SCT *sct, ct_log_entry_type_t entry_type);
52
53        size_t SCT_get0_log_id(const SCT *sct, unsigned char **log_id);
54        int SCT_set0_log_id(SCT *sct, unsigned char *log_id, size_t log_id_len);
55        int SCT_set1_log_id(SCT *sct, const unsigned char *log_id, size_t log_id_len);
56
57        uint64_t SCT_get_timestamp(const SCT *sct);
58        void SCT_set_timestamp(SCT *sct, uint64_t timestamp);
59
60        int SCT_get_signature_nid(const SCT *sct);
61        int SCT_set_signature_nid(SCT *sct, int nid);
62
63        size_t SCT_get0_signature(const SCT *sct, unsigned char **sig);
64        void SCT_set0_signature(SCT *sct, unsigned char *sig, size_t sig_len);
65        int SCT_set1_signature(SCT *sct, const unsigned char *sig, size_t sig_len);
66
67        size_t SCT_get0_extensions(const SCT *sct, unsigned char **ext);
68        void SCT_set0_extensions(SCT *sct, unsigned char *ext, size_t ext_len);
69        int SCT_set1_extensions(SCT *sct, const unsigned char *ext, size_t ext_len);
70
71        sct_source_t SCT_get_source(const SCT *sct);
72        int SCT_set_source(SCT *sct, sct_source_t source);
73

DESCRIPTION

75       Signed Certificate Timestamps (SCTs) are defined by RFC 6962, Section
76       3.2.  They constitute a promise by a Certificate Transparency (CT) log
77       to publicly record a certificate. By cryptographically verifying that a
78       log did indeed issue an SCT, some confidence can be gained that the
79       certificate is publicly known.
80
81       An internal representation of an SCT can be created in one of two ways.
82       The first option is to create a blank SCT, using SCT_new(), and then
83       populate it using:
84
85       • SCT_set_version() to set the SCT version.
86
87         Only SCT_VERSION_V1 is currently supported.
88
89       • SCT_set_log_entry_type() to set the type of certificate the SCT was
90         issued for:
91
92         CT_LOG_ENTRY_TYPE_X509 for a normal certificate.
93         CT_LOG_ENTRY_TYPE_PRECERT for a pre-certificate.
94
95       • SCT_set0_log_id() or SCT_set1_log_id() to set the LogID of the CT log
96         that the SCT came from.
97
98         The former takes ownership, whereas the latter makes a copy.  See RFC
99         6962, Section 3.2 for the definition of LogID.
100
101       • SCT_set_timestamp() to set the time the SCT was issued (time in
102         milliseconds since the Unix Epoch).
103
104       • SCT_set_signature_nid() to set the NID of the signature.
105
106       • SCT_set0_signature() or SCT_set1_signature() to set the raw signature
107         value.
108
109         The former takes ownership, whereas the latter makes a copy.
110
111       • SCT_set0_extensions() or SCT_set1_extensions to provide SCT
112         extensions.
113
114         The former takes ownership, whereas the latter makes a copy.
115
116       Alternatively, the SCT can be pre-populated from the following data
117       using SCT_new_from_base64():
118
119       • The SCT version (only SCT_VERSION_V1 is currently supported).
120
121       • The LogID (see RFC 6962, Section 3.2), base64 encoded.
122
123       • The type of certificate the SCT was issued for:
124         CT_LOG_ENTRY_TYPE_X509 for a normal certificate.
125         CT_LOG_ENTRY_TYPE_PRECERT for a pre-certificate.
126
127       • The time that the SCT was issued (time in milliseconds since the Unix
128         Epoch).
129
130       • The SCT extensions, base64 encoded.
131
132       • The SCT signature, base64 encoded.
133
134       SCT_set_source() can be used to record where the SCT was found (TLS
135       extension, X.509 certificate extension or OCSP response). This is not
136       required for verifying the SCT.
137

NOTES

139       Some of the setters return int, instead of void. These will all return
140       1 on success, 0 on failure. They will not make changes on failure.
141
142       All of the setters will reset the validation status of the SCT to
143       SCT_VALIDATION_STATUS_NOT_SET (see SCT_validate(3)).
144
145       SCT_set_source() will call SCT_set_log_entry_type() if the type of
146       certificate the SCT was issued for can be inferred from where the SCT
147       was found.  For example, an SCT found in an X.509 extension must have
148       been issued for a pre- certificate.
149
150       SCT_set_source() will not refuse unknown values.
151

RETURN VALUES

153       SCT_set_version() returns 1 if the specified version is supported, 0
154       otherwise.
155
156       SCT_set_log_entry_type() returns 1 if the specified log entry type is
157       supported, 0 otherwise.
158
159       SCT_set0_log_id() and SCT_set1_log_id return 1 if the specified LogID
160       is a valid SHA-256 hash, 0 otherwise. Additionally, SCT_set1_log_id
161       returns 0 if malloc fails.
162
163       SCT_set_signature_nid returns 1 if the specified NID is supported, 0
164       otherwise.
165
166       SCT_set1_extensions and SCT_set1_signature return 1 if the supplied
167       buffer is copied successfully, 0 otherwise (i.e. if malloc fails).
168
169       SCT_set_source returns 1 on success, 0 otherwise.
170

HISTORY

175       These functions were added in OpenSSL 1.1.0.
176

COPYRIGHT

178       Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.
179
180       Licensed under the Apache License 2.0 (the "License").  You may not use
181       this file except in compliance with the License.  You can obtain a copy
182       in the file LICENSE in the source distribution or at
183       <https://www.openssl.org/source/license.html>.
184
185
186
1873.0.5                             2022-07-05                    SCT_NEW(3ossl)