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