Debian Codegraph @

upstream/debian-unstable/man3/SSL_check_chain.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 "SSL_CHECK_CHAIN 3SSL"
58 .TH SSL_CHECK_CHAIN 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 SSL_check_chain \- check certificate chain suitability
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& #include <openssl/ssl.h>
69 \&
70 \& int SSL_check_chain(SSL *s, X509 *x, EVP_PKEY *pk, STACK_OF(X509) *chain);
71 .Ve
72 .SH DESCRIPTION
73 .IX Header "DESCRIPTION"
74 \&\fBSSL_check_chain()\fR checks whether certificate \fBx\fR, private key \fBpk\fR and
75 certificate chain \fBchain\fR is suitable for use with the current session
76 \&\fBs\fR.
77 .SH "RETURN VALUES"
78 .IX Header "RETURN VALUES"
79 \&\fBSSL_check_chain()\fR returns a bitmap of flags indicating the validity of the
80 chain.
81 .PP
82 \&\fBCERT_PKEY_VALID\fR: the chain can be used with the current session.
83 If this flag is \fBnot\fR set then the certificate will never be used even
84 if the application tries to set it because it is inconsistent with the
85 peer preferences.
86 .PP
87 \&\fBCERT_PKEY_SIGN\fR: the EE key can be used for signing.
88 .PP
89 \&\fBCERT_PKEY_EE_SIGNATURE\fR: the signature algorithm of the EE certificate is
90 acceptable.
91 .PP
92 \&\fBCERT_PKEY_CA_SIGNATURE\fR: the signature algorithms of all CA certificates
93 are acceptable.
94 .PP
95 \&\fBCERT_PKEY_EE_PARAM\fR: the parameters of the end entity certificate are
96 acceptable (e.g. it is a supported curve).
97 .PP
98 \&\fBCERT_PKEY_CA_PARAM\fR: the parameters of all CA certificates are acceptable.
99 .PP
100 \&\fBCERT_PKEY_EXPLICIT_SIGN\fR: the end entity certificate algorithm
101 can be used explicitly for signing (i.e. it is mentioned in the signature
102 algorithms extension).
103 .PP
104 \&\fBCERT_PKEY_ISSUER_NAME\fR: the issuer name is acceptable. This is only
105 meaningful for client authentication.
106 .PP
107 \&\fBCERT_PKEY_CERT_TYPE\fR: the certificate type is acceptable. Only meaningful
108 for client authentication.
109 .PP
110 \&\fBCERT_PKEY_SUITEB\fR: chain is suitable for Suite B use.
111 .SH NOTES
112 .IX Header "NOTES"
113 \&\fBSSL_check_chain()\fR must be called in servers after a client hello message or in
114 clients after a certificate request message. It will typically be called
115 in the certificate callback.
116 .PP
117 An application wishing to support multiple certificate chains may call this
118 function on each chain in turn: starting with the one it considers the
119 most secure. It could then use the chain of the first set which returns
120 suitable flags.
121 .PP
122 As a minimum the flag \fBCERT_PKEY_VALID\fR must be set for a chain to be
123 usable. An application supporting multiple chains with different CA signature
124 algorithms may also wish to check \fBCERT_PKEY_CA_SIGNATURE\fR too. If no
125 chain is suitable a server should fall back to the most secure chain which
126 sets \fBCERT_PKEY_VALID\fR.
127 .PP
128 The validity of a chain is determined by checking if it matches a supported
129 signature algorithm, supported curves and in the case of client authentication
130 certificate types and issuer names.
131 .PP
132 Since the supported signature algorithms extension is only used in TLS 1.2,
133 TLS 1.3 and DTLS 1.2 the results for earlier versions of TLS and DTLS may not
134 be very useful. Applications may wish to specify a different "legacy" chain
135 for earlier versions of TLS or DTLS.
136 .SH "SEE ALSO"
137 .IX Header "SEE ALSO"
138 \&\fBSSL_CTX_set_cert_cb\fR\|(3),
139 \&\fBssl\fR\|(7)
140 .SH COPYRIGHT
141 .IX Header "COPYRIGHT"
142 Copyright 2015\-2018 The OpenSSL Project Authors. All Rights Reserved.
143 .PP
144 Licensed under the Apache License 2.0 (the "License"). You may not use
145 this file except in compliance with the License. You can obtain a copy
146 in the file LICENSE in the source distribution or at
147 <https://www.openssl.org/source/license.html>.