Document that SCT_set_source returns 0 on failure.
[openssl.git] / doc / crypto / SCT_new.pod
1 =pod
2
3 =head1 NAME
4
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
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
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.
84 The first option is to create a blank SCT, using SCT_new(), and then populate
85 it using:
86
87 =over
88
89 =item * SCT_set_version() to set the SCT version.
90
91 Only SCT_VERSION_V1 is currently supported.
92
93 =item * SCT_set_log_entry_type() to set the type of certificate the SCT was issued for:
94
95 B<CT_LOG_ENTRY_TYPE_X509> for a normal certificate.
96 B<CT_LOG_ENTRY_TYPE_PRECERT> for a pre-certificate.
97
98 =item * SCT_set0_log_id() or SCT_set1_log_id() to set the LogID of the CT log that the SCT came from.
99
100 The former takes ownership, whereas the latter makes a copy.
101 See RFC 6962, Section 3.2 for the definition of LogID.
102
103 =item * SCT_set_timestamp() to set the time the SCT was issued (epoch time in milliseconds).
104
105 =item * SCT_set_signature_nid() to set the NID of the signature.
106
107 =item * SCT_set0_signature() or SCT_set1_signature() to set the raw signature value.
108
109 The former takes ownership, whereas the latter makes a copy.
110
111 =item * SCT_set0_extensions() or B<SCT_set1_extensions> to provide SCT extensions.
112
113 The former takes ownership, whereas the latter makes a copy.
114
115 =back
116
117 Alternatively, the SCT can be pre-populated from the following data using
118 SCT_new_from_base64():
119
120 =over
121
122 =item * The SCT version (only SCT_VERSION_V1 is currently supported).
123
124 =item * The LogID (see RFC 6962, Section 3.2), base64 encoded.
125
126 =item * The type of certificate the SCT was issued for:
127
128 B<CT_LOG_ENTRY_TYPE_X509> for a normal certificate.
129 B<CT_LOG_ENTRY_TYPE_PRECERT> for a pre-certificate.
130
131 =item * The time that the SCT was issued (epoch time in milliseconds).
132
133 =item * The SCT extensions, base64 encoded.
134
135 =item * The SCT signature, base64 encoded.
136
137 =back
138
139 SCT_set_source() can be used to record where the SCT was found
140 (TLS extension, X.509 certificate extension or OCSP response). This is not
141 required for verifying the SCT.
142
143 =head1 NOTES
144
145 Some of the setters return int, instead of void. These will all return 1 on
146 success, 0 on failure. They will not make changes on failure.
147
148 Most of the setters will reset the validation status of the SCT to
149 SCT_VALIDATION_STATUS_NOT_SET (see L<SCT_verify(3)>).
150
151 SCT_set_source() will call SCT_set_log_entry_type() if the type of
152 certificate the SCT was issued for can be inferred from where the SCT was found.
153 For example, an SCT found in an X.509 extension must have been issued for a pre-
154 certificate.
155
156 SCT_set_source() will not refuse unknown values.
157
158 =head1 RETURN VALUES
159
160 SCT_set_version() returns 1 if the specified version is supported, 0 otherwise.
161
162 SCT_set_log_entry_type() returns 1 if the specified log entry type is supported, 0 otherwise.
163
164 SCT_set0_log_id() and B<SCT_set1_log_id> return 1 if the specified LogID is a
165 valid SHA-256 hash, 0 otherwise. Aditionally, B<SCT_set1_log_id> returns 0 if
166 malloc fails.
167
168 B<SCT_set_signature_nid> returns 1 if the specified NID is supported, 0 otherwise.
169
170 B<SCT_set1_extensions> and B<SCT_set1_signature> return 1 if the supplied buffer
171 is copied successfully, 0 otherwise (i.e. if malloc fails).
172
173 B<SCT_set_source> returns 1 on success, 0 otherwise.
174
175 =head1 SEE ALSO
176
177 L<ct(3)>,
178 L<SCT_verify(3)>,
179 L<OBJ_nid2obj(3)>
180
181 =head1 HISTORY
182
183 These functions were added in OpenSSL 1.1.0.
184
185 =head1 COPYRIGHT
186
187 Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
188
189 Licensed under the OpenSSL license (the "License").  You may not use
190 this file except in compliance with the License.  You can obtain a copy
191 in the file LICENSE in the source distribution or at
192 L<https://www.openssl.org/source/license.html>.
193
194 =cut