Debian Codegraph @

upstream/debian-unstable/man3/SCT_new.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SCT_NEW 3SSL"
58 .TH SCT_NEW 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 SCT_new, SCT_new_from_base64, SCT_free, SCT_LIST_free,
65 SCT_get_version, SCT_set_version,
66 SCT_get_log_entry_type, SCT_set_log_entry_type,
67 SCT_get0_log_id, SCT_set0_log_id, SCT_set1_log_id,
68 SCT_get_timestamp, SCT_set_timestamp,
69 SCT_get_signature_nid, SCT_set_signature_nid,
70 SCT_get0_signature, SCT_set0_signature, SCT_set1_signature,
71 SCT_get0_extensions, SCT_set0_extensions, SCT_set1_extensions,
72 SCT_get_source, SCT_set_source
73 \&\- A Certificate Transparency Signed Certificate Timestamp
74 .SH SYNOPSIS
75 .IX Header "SYNOPSIS"
76 .Vb 1
77 \& #include <openssl/ct.h>
78 \&
79 \& typedef enum {
80 \& CT_LOG_ENTRY_TYPE_NOT_SET = \-1,
81 \& CT_LOG_ENTRY_TYPE_X509 = 0,
82 \& CT_LOG_ENTRY_TYPE_PRECERT = 1
83 \& } ct_log_entry_type_t;
84 \&
85 \& typedef enum {
86 \& SCT_VERSION_NOT_SET = \-1,
87 \& SCT_VERSION_V1 = 0
88 \& } sct_version_t;
89 \&
90 \& typedef enum {
91 \& SCT_SOURCE_UNKNOWN,
92 \& SCT_SOURCE_TLS_EXTENSION,
93 \& SCT_SOURCE_X509V3_EXTENSION,
94 \& SCT_SOURCE_OCSP_STAPLED_RESPONSE
95 \& } sct_source_t;
96 \&
97 \& SCT *SCT_new(void);
98 \& SCT *SCT_new_from_base64(unsigned char version,
99 \& const char *logid_base64,
100 \& ct_log_entry_type_t entry_type,
101 \& uint64_t timestamp,
102 \& const char *extensions_base64,
103 \& const char *signature_base64);
104 \&
105 \& void SCT_free(SCT *sct);
106 \& void SCT_LIST_free(STACK_OF(SCT) *a);
107 \&
108 \& sct_version_t SCT_get_version(const SCT *sct);
109 \& int SCT_set_version(SCT *sct, sct_version_t version);
110 \&
111 \& ct_log_entry_type_t SCT_get_log_entry_type(const SCT *sct);
112 \& int SCT_set_log_entry_type(SCT *sct, ct_log_entry_type_t entry_type);
113 \&
114 \& size_t SCT_get0_log_id(const SCT *sct, unsigned char **log_id);
115 \& int SCT_set0_log_id(SCT *sct, unsigned char *log_id, size_t log_id_len);
116 \& int SCT_set1_log_id(SCT *sct, const unsigned char *log_id, size_t log_id_len);
117 \&
118 \& uint64_t SCT_get_timestamp(const SCT *sct);
119 \& void SCT_set_timestamp(SCT *sct, uint64_t timestamp);
120 \&
121 \& int SCT_get_signature_nid(const SCT *sct);
122 \& int SCT_set_signature_nid(SCT *sct, int nid);
123 \&
124 \& size_t SCT_get0_signature(const SCT *sct, unsigned char **sig);
125 \& void SCT_set0_signature(SCT *sct, unsigned char *sig, size_t sig_len);
126 \& int SCT_set1_signature(SCT *sct, const unsigned char *sig, size_t sig_len);
127 \&
128 \& size_t SCT_get0_extensions(const SCT *sct, unsigned char **ext);
129 \& void SCT_set0_extensions(SCT *sct, unsigned char *ext, size_t ext_len);
130 \& int SCT_set1_extensions(SCT *sct, const unsigned char *ext, size_t ext_len);
131 \&
132 \& sct_source_t SCT_get_source(const SCT *sct);
133 \& int SCT_set_source(SCT *sct, sct_source_t source);
134 .Ve
135 .SH DESCRIPTION
136 .IX Header "DESCRIPTION"
137 Signed Certificate Timestamps (SCTs) are defined by RFC 6962, Section 3.2.
138 They constitute a promise by a Certificate Transparency (CT) log to publicly
139 record a certificate. By cryptographically verifying that a log did indeed issue
140 an SCT, some confidence can be gained that the certificate is publicly known.
141 .PP
142 An internal representation of an SCT can be created in one of two ways.
143 The first option is to create a blank SCT, using \fBSCT_new()\fR, and then populate
144 it using:
145 .IP \(bu 2
146 \&\fBSCT_set_version()\fR to set the SCT version.
147 .Sp
148 Only SCT_VERSION_V1 is currently supported.
149 .IP \(bu 2
150 \&\fBSCT_set_log_entry_type()\fR to set the type of certificate the SCT was issued for:
151 .Sp
152 \&\fBCT_LOG_ENTRY_TYPE_X509\fR for a normal certificate.
153 \&\fBCT_LOG_ENTRY_TYPE_PRECERT\fR for a pre-certificate.
154 .IP \(bu 2
155 \&\fBSCT_set0_log_id()\fR or \fBSCT_set1_log_id()\fR to set the LogID of the CT log that the SCT came from.
156 .Sp
157 The former takes ownership, whereas the latter makes a copy.
158 See RFC 6962, Section 3.2 for the definition of LogID.
159 .IP \(bu 2
160 \&\fBSCT_set_timestamp()\fR to set the time the SCT was issued (time in milliseconds
161 since the Unix Epoch).
162 .IP \(bu 2
163 \&\fBSCT_set_signature_nid()\fR to set the NID of the signature.
164 .IP \(bu 2
165 \&\fBSCT_set0_signature()\fR or \fBSCT_set1_signature()\fR to set the raw signature value.
166 .Sp
167 The former takes ownership, whereas the latter makes a copy.
168 .IP \(bu 2
169 \&\fBSCT_set0_extensions()\fR or \fBSCT_set1_extensions\fR to provide SCT extensions.
170 .Sp
171 The former takes ownership, whereas the latter makes a copy.
172 .PP
173 Alternatively, the SCT can be pre-populated from the following data using
174 \&\fBSCT_new_from_base64()\fR:
175 .IP \(bu 2
176 The SCT version (only SCT_VERSION_V1 is currently supported).
177 .IP \(bu 2
178 The LogID (see RFC 6962, Section 3.2), base64 encoded.
179 .IP \(bu 2
180 The type of certificate the SCT was issued for:
181 \&\fBCT_LOG_ENTRY_TYPE_X509\fR for a normal certificate.
182 \&\fBCT_LOG_ENTRY_TYPE_PRECERT\fR for a pre-certificate.
183 .IP \(bu 2
184 The time that the SCT was issued (time in milliseconds since the Unix Epoch).
185 .IP \(bu 2
186 The SCT extensions, base64 encoded.
187 .IP \(bu 2
188 The SCT signature, base64 encoded.
189 .PP
190 \&\fBSCT_set_source()\fR can be used to record where the SCT was found
191 (TLS extension, X.509 certificate extension or OCSP response). This is not
192 required for verifying the SCT.
193 .PP
194 \&\fBSCT_free()\fR frees the specified SCT.
195 If the argument is NULL, nothing is done.
196 .PP
197 \&\fBSCT_LIST_free()\fR frees the specified stack of SCTs.
198 If the argument is NULL, nothing is done.
199 .SH NOTES
200 .IX Header "NOTES"
201 Some of the setters return int, instead of void. These will all return 1 on
202 success, 0 on failure. They will not make changes on failure.
203 .PP
204 All of the setters will reset the validation status of the SCT to
205 SCT_VALIDATION_STATUS_NOT_SET (see \fBSCT_validate\fR\|(3)).
206 .PP
207 \&\fBSCT_set_source()\fR will call \fBSCT_set_log_entry_type()\fR if the type of
208 certificate the SCT was issued for can be inferred from where the SCT was found.
209 For example, an SCT found in an X.509 extension must have been issued for a pre\-
210 certificate.
211 .PP
212 \&\fBSCT_set_source()\fR will not refuse unknown values.
213 .SH "RETURN VALUES"
214 .IX Header "RETURN VALUES"
215 \&\fBSCT_set_version()\fR returns 1 if the specified version is supported, 0 otherwise.
216 .PP
217 \&\fBSCT_set_log_entry_type()\fR returns 1 if the specified log entry type is supported, 0 otherwise.
218 .PP
219 \&\fBSCT_set0_log_id()\fR and \fBSCT_set1_log_id\fR return 1 if the specified LogID is a
220 valid SHA\-256 hash, 0 otherwise. Additionally, \fBSCT_set1_log_id\fR returns 0 if
221 malloc fails.
222 .PP
223 \&\fBSCT_set_signature_nid\fR returns 1 if the specified NID is supported, 0 otherwise.
224 .PP
225 \&\fBSCT_set1_extensions\fR and \fBSCT_set1_signature\fR return 1 if the supplied buffer
226 is copied successfully, 0 otherwise (i.e. if malloc fails).
227 .PP
228 \&\fBSCT_set_source\fR returns 1 on success, 0 otherwise.
229 .SH "SEE ALSO"
230 .IX Header "SEE ALSO"
231 \&\fBct\fR\|(7),
232 \&\fBSCT_validate\fR\|(3),
233 \&\fBOBJ_nid2obj\fR\|(3)
234 .SH HISTORY
235 .IX Header "HISTORY"
236 These functions were added in OpenSSL 1.1.0.
237 .SH COPYRIGHT
238 .IX Header "COPYRIGHT"
239 Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved.
240 .PP
241 Licensed under the Apache License 2.0 (the "License"). You may not use
242 this file except in compliance with the License. You can obtain a copy
243 in the file LICENSE in the source distribution or at
244 <https://www.openssl.org/source/license.html>.