secure/lib/libcrypto/man/man3/SCT_new.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "SCT_NEW 3"
 136 .TH SCT_NEW 3 "2020-09-22" "1.1.1h" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 SCT_new, SCT_new_from_base64, SCT_free, SCT_LIST_free, SCT_get_version, SCT_set_version, SCT_get_log_entry_type, SCT_set_log_entry_type, SCT_get0_log_id, SCT_set0_log_id, SCT_set1_log_id, SCT_get_timestamp, SCT_set_timestamp, SCT_get_signature_nid, SCT_set_signature_nid, SCT_get0_signature, SCT_set0_signature, SCT_set1_signature, SCT_get0_extensions, SCT_set0_extensions, SCT_set1_extensions, SCT_get_source, SCT_set_source \&\- A Certificate Transparency Signed Certificate Timestamp
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ct.h>
 147 \&
 148 \& typedef enum {
 149 \&     CT_LOG_ENTRY_TYPE_NOT_SET = \-1,
 150 \&     CT_LOG_ENTRY_TYPE_X509 = 0,
 151 \&     CT_LOG_ENTRY_TYPE_PRECERT = 1
 152 \& } ct_log_entry_type_t;
 153 \&
 154 \& typedef enum {
 155 \&     SCT_VERSION_NOT_SET = \-1,
 156 \&     SCT_VERSION_V1 = 0
 157 \& } sct_version_t;
 158 \&
 159 \& typedef enum {
 160 \&     SCT_SOURCE_UNKNOWN,
 161 \&     SCT_SOURCE_TLS_EXTENSION,
 162 \&     SCT_SOURCE_X509V3_EXTENSION,
 163 \&     SCT_SOURCE_OCSP_STAPLED_RESPONSE
 164 \& } sct_source_t;
 165 \&
 166 \& SCT *SCT_new(void);
 167 \& SCT *SCT_new_from_base64(unsigned char version,
 168 \&                          const char *logid_base64,
 169 \&                          ct_log_entry_type_t entry_type,
 170 \&                          uint64_t timestamp,
 171 \&                          const char *extensions_base64,
 172 \&                          const char *signature_base64);
 173 \&
 174 \& void SCT_free(SCT *sct);
 175 \& void SCT_LIST_free(STACK_OF(SCT) *a);
 176 \&
 177 \& sct_version_t SCT_get_version(const SCT *sct);
 178 \& int SCT_set_version(SCT *sct, sct_version_t version);
 179 \&
 180 \& ct_log_entry_type_t SCT_get_log_entry_type(const SCT *sct);
 181 \& int SCT_set_log_entry_type(SCT *sct, ct_log_entry_type_t entry_type);
 182 \&
 183 \& size_t SCT_get0_log_id(const SCT *sct, unsigned char **log_id);
 184 \& int SCT_set0_log_id(SCT *sct, unsigned char *log_id, size_t log_id_len);
 185 \& int SCT_set1_log_id(SCT *sct, const unsigned char *log_id, size_t log_id_len);
 186 \&
 187 \& uint64_t SCT_get_timestamp(const SCT *sct);
 188 \& void SCT_set_timestamp(SCT *sct, uint64_t timestamp);
 189 \&
 190 \& int SCT_get_signature_nid(const SCT *sct);
 191 \& int SCT_set_signature_nid(SCT *sct, int nid);
 192 \&
 193 \& size_t SCT_get0_signature(const SCT *sct, unsigned char **sig);
 194 \& void SCT_set0_signature(SCT *sct, unsigned char *sig, size_t sig_len);
 195 \& int SCT_set1_signature(SCT *sct, const unsigned char *sig, size_t sig_len);
 196 \&
 197 \& size_t SCT_get0_extensions(const SCT *sct, unsigned char **ext);
 198 \& void SCT_set0_extensions(SCT *sct, unsigned char *ext, size_t ext_len);
 199 \& int SCT_set1_extensions(SCT *sct, const unsigned char *ext, size_t ext_len);
 200 \&
 201 \& sct_source_t SCT_get_source(const SCT *sct);
 202 \& int SCT_set_source(SCT *sct, sct_source_t source);
 203 .Ve
 204 .SH "DESCRIPTION"
 205 .IX Header "DESCRIPTION"
 206 Signed Certificate Timestamps (SCTs) are defined by \s-1RFC 6962,\s0 Section 3.2.
 207 They constitute a promise by a Certificate Transparency (\s-1CT\s0) log to publicly
 208 record a certificate. By cryptographically verifying that a log did indeed issue
 209 an \s-1SCT,\s0 some confidence can be gained that the certificate is publicly known.
 210 .PP
 211 An internal representation of an \s-1SCT\s0 can be created in one of two ways.
 212 The first option is to create a blank \s-1SCT,\s0 using \fBSCT_new()\fR, and then populate
 213 it using:
 214 .IP "\(bu" 2
 215 \&\fBSCT_set_version()\fR to set the \s-1SCT\s0 version.
 216 .Sp
 217 Only \s-1SCT_VERSION_V1\s0 is currently supported.
 218 .IP "\(bu" 2
 219 \&\fBSCT_set_log_entry_type()\fR to set the type of certificate the \s-1SCT\s0 was issued for:
 220 .Sp
 221 \&\fB\s-1CT_LOG_ENTRY_TYPE_X509\s0\fR for a normal certificate.
 222 \&\fB\s-1CT_LOG_ENTRY_TYPE_PRECERT\s0\fR for a pre-certificate.
 223 .IP "\(bu" 2
 224 \&\fBSCT_set0_log_id()\fR or \fBSCT_set1_log_id()\fR to set the LogID of the \s-1CT\s0 log that the \s-1SCT\s0 came from.
 225 .Sp
 226 The former takes ownership, whereas the latter makes a copy.
 227 See \s-1RFC 6962,\s0 Section 3.2 for the definition of LogID.
 228 .IP "\(bu" 2
 229 \&\fBSCT_set_timestamp()\fR to set the time the \s-1SCT\s0 was issued (epoch time in milliseconds).
 230 .IP "\(bu" 2
 231 \&\fBSCT_set_signature_nid()\fR to set the \s-1NID\s0 of the signature.
 232 .IP "\(bu" 2
 233 \&\fBSCT_set0_signature()\fR or \fBSCT_set1_signature()\fR to set the raw signature value.
 234 .Sp
 235 The former takes ownership, whereas the latter makes a copy.
 236 .IP "\(bu" 2
 237 \&\fBSCT_set0_extensions()\fR or \fBSCT_set1_extensions\fR to provide \s-1SCT\s0 extensions.
 238 .Sp
 239 The former takes ownership, whereas the latter makes a copy.
 240 .PP
 241 Alternatively, the \s-1SCT\s0 can be pre-populated from the following data using
 242 \&\fBSCT_new_from_base64()\fR:
 243 .IP "\(bu" 2
 244 The \s-1SCT\s0 version (only \s-1SCT_VERSION_V1\s0 is currently supported).
 245 .IP "\(bu" 2
 246 The LogID (see \s-1RFC 6962,\s0 Section 3.2), base64 encoded.
 247 .IP "\(bu" 2
 248 The type of certificate the \s-1SCT\s0 was issued for:
 249 \&\fB\s-1CT_LOG_ENTRY_TYPE_X509\s0\fR for a normal certificate.
 250 \&\fB\s-1CT_LOG_ENTRY_TYPE_PRECERT\s0\fR for a pre-certificate.
 251 .IP "\(bu" 2
 252 The time that the \s-1SCT\s0 was issued (epoch time in milliseconds).
 253 .IP "\(bu" 2
 254 The \s-1SCT\s0 extensions, base64 encoded.
 255 .IP "\(bu" 2
 256 The \s-1SCT\s0 signature, base64 encoded.
 257 .PP
 258 \&\fBSCT_set_source()\fR can be used to record where the \s-1SCT\s0 was found
 259 (\s-1TLS\s0 extension, X.509 certificate extension or \s-1OCSP\s0 response). This is not
 260 required for verifying the \s-1SCT.\s0
 261 .SH "NOTES"
 262 .IX Header "NOTES"
 263 Some of the setters return int, instead of void. These will all return 1 on
 264 success, 0 on failure. They will not make changes on failure.
 265 .PP
 266 All of the setters will reset the validation status of the \s-1SCT\s0 to
 267 \&\s-1SCT_VALIDATION_STATUS_NOT_SET\s0 (see \fBSCT_validate\fR\|(3)).
 268 .PP
 269 \&\fBSCT_set_source()\fR will call \fBSCT_set_log_entry_type()\fR if the type of
 270 certificate the \s-1SCT\s0 was issued for can be inferred from where the \s-1SCT\s0 was found.
 271 For example, an \s-1SCT\s0 found in an X.509 extension must have been issued for a pre\-
 272 certificate.
 273 .PP
 274 \&\fBSCT_set_source()\fR will not refuse unknown values.
 275 .SH "RETURN VALUES"
 276 .IX Header "RETURN VALUES"
 277 \&\fBSCT_set_version()\fR returns 1 if the specified version is supported, 0 otherwise.
 278 .PP
 279 \&\fBSCT_set_log_entry_type()\fR returns 1 if the specified log entry type is supported, 0 otherwise.
 280 .PP
 281 \&\fBSCT_set0_log_id()\fR and \fBSCT_set1_log_id\fR return 1 if the specified LogID is a
 282 valid \s-1SHA\-256\s0 hash, 0 otherwise. Additionally, \fBSCT_set1_log_id\fR returns 0 if
 283 malloc fails.
 284 .PP
 285 \&\fBSCT_set_signature_nid\fR returns 1 if the specified \s-1NID\s0 is supported, 0 otherwise.
 286 .PP
 287 \&\fBSCT_set1_extensions\fR and \fBSCT_set1_signature\fR return 1 if the supplied buffer
 288 is copied successfully, 0 otherwise (i.e. if malloc fails).
 289 .PP
 290 \&\fBSCT_set_source\fR returns 1 on success, 0 otherwise.
 291 .SH "SEE ALSO"
 292 .IX Header "SEE ALSO"
 293 \&\fBct\fR\|(7),
 294 \&\fBSCT_validate\fR\|(3),
 295 \&\fBOBJ_nid2obj\fR\|(3)
 296 .SH "HISTORY"
 297 .IX Header "HISTORY"
 298 These functions were added in OpenSSL 1.1.0.
 299 .SH "COPYRIGHT"
 300 .IX Header "COPYRIGHT"
 301 Copyright 2016\-2017 The OpenSSL Project Authors. All Rights Reserved.
 302 .PP
 303 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 304 this file except in compliance with the License.  You can obtain a copy
 305 in the file \s-1LICENSE\s0 in the source distribution or at
 306 <https://www.openssl.org/source/license.html>.