Debian Codegraph @

upstream/debian-unstable/man3/SCT_validate.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_VALIDATE 3SSL"
58 .TH SCT_VALIDATE 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_validate, SCT_LIST_validate, SCT_get_validation_status \-
65 checks Signed Certificate Timestamps (SCTs) are valid
66 .SH SYNOPSIS
67 .IX Header "SYNOPSIS"
68 .Vb 1
69 \& #include <openssl/ct.h>
70 \&
71 \& typedef enum {
72 \& SCT_VALIDATION_STATUS_NOT_SET,
73 \& SCT_VALIDATION_STATUS_UNKNOWN_LOG,
74 \& SCT_VALIDATION_STATUS_VALID,
75 \& SCT_VALIDATION_STATUS_INVALID,
76 \& SCT_VALIDATION_STATUS_UNVERIFIED,
77 \& SCT_VALIDATION_STATUS_UNKNOWN_VERSION
78 \& } sct_validation_status_t;
79 \&
80 \& int SCT_validate(SCT *sct, const CT_POLICY_EVAL_CTX *ctx);
81 \& int SCT_LIST_validate(const STACK_OF(SCT) *scts, CT_POLICY_EVAL_CTX *ctx);
82 \& sct_validation_status_t SCT_get_validation_status(const SCT *sct);
83 .Ve
84 .SH DESCRIPTION
85 .IX Header "DESCRIPTION"
86 \&\fBSCT_validate()\fR will check that an SCT is valid and verify its signature.
87 \&\fBSCT_LIST_validate()\fR performs the same checks on an entire stack of SCTs.
88 The result of the validation checks can be obtained by passing the SCT to
89 \&\fBSCT_get_validation_status()\fR.
90 .PP
91 A CT_POLICY_EVAL_CTX must be provided that specifies:
92 .IP \(bu 2
93 The certificate the SCT was issued for.
94 .Sp
95 Failure to provide the certificate will result in the validation status being
96 SCT_VALIDATION_STATUS_UNVERIFIED.
97 .IP \(bu 2
98 The issuer of that certificate.
99 .Sp
100 This is only required if the SCT was issued for a pre-certificate
101 (see RFC 6962). If it is required but not provided, the validation status will
102 be SCT_VALIDATION_STATUS_UNVERIFIED.
103 .IP \(bu 2
104 A CTLOG_STORE that contains the CT log that issued this SCT.
105 .Sp
106 If the SCT was issued by a log that is not in this CTLOG_STORE, the validation
107 status will be SCT_VALIDATION_STATUS_UNKNOWN_LOG.
108 .PP
109 If the SCT is of an unsupported version (only v1 is currently supported), the
110 validation status will be SCT_VALIDATION_STATUS_UNKNOWN_VERSION.
111 .PP
112 If the SCT's signature is incorrect, its timestamp is in the future (relative to
113 the time in CT_POLICY_EVAL_CTX), or if it is otherwise invalid, the validation
114 status will be SCT_VALIDATION_STATUS_INVALID.
115 .PP
116 If all checks pass, the validation status will be SCT_VALIDATION_STATUS_VALID.
117 .SH NOTES
118 .IX Header "NOTES"
119 A return value of 0 from \fBSCT_LIST_validate()\fR should not be interpreted as a
120 failure. At a minimum, only one valid SCT may provide sufficient confidence
121 that a certificate has been publicly logged.
122 .SH "RETURN VALUES"
123 .IX Header "RETURN VALUES"
124 \&\fBSCT_validate()\fR returns a negative integer if an internal error occurs, 0 if the
125 SCT fails validation, or 1 if the SCT passes validation.
126 .PP
127 \&\fBSCT_LIST_validate()\fR returns a negative integer if an internal error occurs, 0
128 if any of SCTs fails validation, or 1 if they all pass validation.
129 .PP
130 \&\fBSCT_get_validation_status()\fR returns the validation status of the SCT.
131 If \fBSCT_validate()\fR or \fBSCT_LIST_validate()\fR have not been passed that SCT, the
132 returned value will be SCT_VALIDATION_STATUS_NOT_SET.
133 .SH "SEE ALSO"
134 .IX Header "SEE ALSO"
135 \&\fBct\fR\|(7)
136 .SH HISTORY
137 .IX Header "HISTORY"
138 These functions were added in OpenSSL 1.1.0.
139 .SH COPYRIGHT
140 .IX Header "COPYRIGHT"
141 Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
142 .PP
143 Licensed under the Apache License 2.0 (the "License"). You may not use
144 this file except in compliance with the License. You can obtain a copy
145 in the file LICENSE in the source distribution or at
146 <https://www.openssl.org/source/license.html>.