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