xref: /openssl/doc/man3/SCT_new.pod (revision 7ed6de99)
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 (time in milliseconds
112since the Unix Epoch).
113
114=item *
115
116SCT_set_signature_nid() to set the NID of the signature.
117
118=item *
119
120SCT_set0_signature() or SCT_set1_signature() to set the raw signature value.
121
122The former takes ownership, whereas the latter makes a copy.
123
124=item *
125
126SCT_set0_extensions() or B<SCT_set1_extensions> to provide SCT extensions.
127
128The former takes ownership, whereas the latter makes a copy.
129
130=back
131
132Alternatively, the SCT can be pre-populated from the following data using
133SCT_new_from_base64():
134
135=over 2
136
137=item *
138
139The SCT version (only SCT_VERSION_V1 is currently supported).
140
141=item *
142
143The LogID (see RFC 6962, Section 3.2), base64 encoded.
144
145=item *
146
147The type of certificate the SCT was issued for:
148B<CT_LOG_ENTRY_TYPE_X509> for a normal certificate.
149B<CT_LOG_ENTRY_TYPE_PRECERT> for a pre-certificate.
150
151=item *
152
153The time that the SCT was issued (time in milliseconds since the Unix Epoch).
154
155=item *
156
157The SCT extensions, base64 encoded.
158
159=item *
160
161The SCT signature, base64 encoded.
162
163=back
164
165SCT_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
167required for verifying the SCT.
168
169SCT_free() frees the specified SCT.
170If the argument is NULL, nothing is done.
171
172SCT_LIST_free() frees the specified stack of SCTs.
173If the argument is NULL, nothing is done.
174
175=head1 NOTES
176
177Some of the setters return int, instead of void. These will all return 1 on
178success, 0 on failure. They will not make changes on failure.
179
180All of the setters will reset the validation status of the SCT to
181SCT_VALIDATION_STATUS_NOT_SET (see L<SCT_validate(3)>).
182
183SCT_set_source() will call SCT_set_log_entry_type() if the type of
184certificate the SCT was issued for can be inferred from where the SCT was found.
185For example, an SCT found in an X.509 extension must have been issued for a pre-
186certificate.
187
188SCT_set_source() will not refuse unknown values.
189
190=head1 RETURN VALUES
191
192SCT_set_version() returns 1 if the specified version is supported, 0 otherwise.
193
194SCT_set_log_entry_type() returns 1 if the specified log entry type is supported, 0 otherwise.
195
196SCT_set0_log_id() and B<SCT_set1_log_id> return 1 if the specified LogID is a
197valid SHA-256 hash, 0 otherwise. Additionally, B<SCT_set1_log_id> returns 0 if
198malloc fails.
199
200B<SCT_set_signature_nid> returns 1 if the specified NID is supported, 0 otherwise.
201
202B<SCT_set1_extensions> and B<SCT_set1_signature> return 1 if the supplied buffer
203is copied successfully, 0 otherwise (i.e. if malloc fails).
204
205B<SCT_set_source> returns 1 on success, 0 otherwise.
206
207=head1 SEE ALSO
208
209L<ct(7)>,
210L<SCT_validate(3)>,
211L<OBJ_nid2obj(3)>
212
213=head1 HISTORY
214
215These functions were added in OpenSSL 1.1.0.
216
217=head1 COPYRIGHT
218
219Copyright 2016-2024 The OpenSSL Project Authors. All Rights Reserved.
220
221Licensed under the Apache License 2.0 (the "License").  You may not use
222this file except in compliance with the License.  You can obtain a copy
223in the file LICENSE in the source distribution or at
224L<https://www.openssl.org/source/license.html>.
225
226=cut
227