summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man')
-rw-r--r--src/lib/libcrypto/man/Makefile5
-rw-r--r--src/lib/libcrypto/man/X509_check_ca.393
-rw-r--r--src/lib/libcrypto/man/X509_check_host.3234
-rw-r--r--src/lib/libcrypto/man/X509_check_issued.3104
4 files changed, 435 insertions, 1 deletions
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 8491e94fa0..63b97d44ae 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
1# $OpenBSD: Makefile,v 1.63 2016/12/05 12:50:07 schwarze Exp $ 1# $OpenBSD: Makefile,v 1.64 2016/12/05 15:56:46 schwarze Exp $
2 2
3.include <bsd.own.mk> 3.include <bsd.own.mk>
4 4
@@ -186,6 +186,9 @@ MAN= \
186 X509_STORE_CTX_set_verify_cb.3 \ 186 X509_STORE_CTX_set_verify_cb.3 \
187 X509_STORE_set_verify_cb_func.3 \ 187 X509_STORE_set_verify_cb_func.3 \
188 X509_VERIFY_PARAM_set_flags.3 \ 188 X509_VERIFY_PARAM_set_flags.3 \
189 X509_check_ca.3 \
190 X509_check_host.3 \
191 X509_check_issued.3 \
189 X509_new.3 \ 192 X509_new.3 \
190 X509_verify_cert.3 \ 193 X509_verify_cert.3 \
191 bn.3 \ 194 bn.3 \
diff --git a/src/lib/libcrypto/man/X509_check_ca.3 b/src/lib/libcrypto/man/X509_check_ca.3
new file mode 100644
index 0000000000..67aac693e6
--- /dev/null
+++ b/src/lib/libcrypto/man/X509_check_ca.3
@@ -0,0 +1,93 @@
1.\" $OpenBSD: X509_check_ca.3,v 1.1 2016/12/05 15:56:46 schwarze Exp $
2.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
3.\"
4.\" This file was written by Victor B. Wagner <vitus@cryptocom.ru>.
5.\" Copyright (c) 2015, 2016 The OpenSSL Project. All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\"
11.\" 1. Redistributions of source code must retain the above copyright
12.\" notice, this list of conditions and the following disclaimer.
13.\"
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\" notice, this list of conditions and the following disclaimer in
16.\" the documentation and/or other materials provided with the
17.\" distribution.
18.\"
19.\" 3. All advertising materials mentioning features or use of this
20.\" software must display the following acknowledgment:
21.\" "This product includes software developed by the OpenSSL Project
22.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
23.\"
24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
25.\" endorse or promote products derived from this software without
26.\" prior written permission. For written permission, please contact
27.\" openssl-core@openssl.org.
28.\"
29.\" 5. Products derived from this software may not be called "OpenSSL"
30.\" nor may "OpenSSL" appear in their names without prior written
31.\" permission of the OpenSSL Project.
32.\"
33.\" 6. Redistributions of any form whatsoever must retain the following
34.\" acknowledgment:
35.\" "This product includes software developed by the OpenSSL Project
36.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
37.\"
38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
41.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49.\" OF THE POSSIBILITY OF SUCH DAMAGE.
50.\"
51.Dd $Mdocdate: December 5 2016 $
52.Dt X509_CHECK_CA 3
53.Os
54.Sh NAME
55.Nm X509_check_ca
56.Nd check whether a certificate is a CA certificate
57.Sh SYNOPSIS
58.In openssl/x509v3.h
59.Ft int
60.Fo X509_check_ca
61.Fa "X509 *cert"
62.Fc
63.Sh DESCRIPTION
64This function checks whether the given certificate is a CA certificate,
65that is, whether it can be used to sign other certificates.
66.Sh RETURN VALUE
67This functions returns non-zero if
68.Fa cert
69is a CA certificate or 0 otherwise.
70.Pp
71The following return values identify specific kinds of CA certificates:
72.Bl -tag -width 2n
73.It 1
74an X.509 v3 CA certificate with
75.Sy basicConstraints
76extension CA:TRUE
77.It 3
78a self-signed X.509 v1 certificate
79.It 4
80a certificate with
81.Sy keyUsage
82extension with bit
83.Sy keyCertSign
84set, but without
85.Sy basicConstraints
86.It 5
87a certificate with an outdated Netscape Certificate Type extension telling
88that it is a CA certificate
89.El
90.Sh SEE ALSO
91.Xr X509_check_issued 3 ,
92.Xr X509_check_purpose 3 ,
93.Xr X509_verify_cert 3
diff --git a/src/lib/libcrypto/man/X509_check_host.3 b/src/lib/libcrypto/man/X509_check_host.3
new file mode 100644
index 0000000000..1e6a44ffe1
--- /dev/null
+++ b/src/lib/libcrypto/man/X509_check_host.3
@@ -0,0 +1,234 @@
1.\" $OpenBSD: X509_check_host.3,v 1.1 2016/12/05 15:56:46 schwarze Exp $
2.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
3.\"
4.\" This file was written by Florian Weimer <fweimer@redhat.com> and
5.\" Viktor Dukhovni <openssl-users@dukhovni.org>.
6.\" Copyright (c) 2012, 2014, 2015, 2016 The OpenSSL Project. All rights reserved.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\"
12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer.
14.\"
15.\" 2. Redistributions in binary form must reproduce the above copyright
16.\" notice, this list of conditions and the following disclaimer in
17.\" the documentation and/or other materials provided with the
18.\" distribution.
19.\"
20.\" 3. All advertising materials mentioning features or use of this
21.\" software must display the following acknowledgment:
22.\" "This product includes software developed by the OpenSSL Project
23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
24.\"
25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
26.\" endorse or promote products derived from this software without
27.\" prior written permission. For written permission, please contact
28.\" openssl-core@openssl.org.
29.\"
30.\" 5. Products derived from this software may not be called "OpenSSL"
31.\" nor may "OpenSSL" appear in their names without prior written
32.\" permission of the OpenSSL Project.
33.\"
34.\" 6. Redistributions of any form whatsoever must retain the following
35.\" acknowledgment:
36.\" "This product includes software developed by the OpenSSL Project
37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
38.\"
39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
50.\" OF THE POSSIBILITY OF SUCH DAMAGE.
51.\"
52.Dd $Mdocdate: December 5 2016 $
53.Dt X509_CHECK_HOST 3
54.Os
55.Sh NAME
56.Nm X509_check_host ,
57.Nm X509_check_email ,
58.Nm X509_check_ip ,
59.Nm X509_check_ip_asc
60.Nd X.509 certificate matching
61.Sh SYNOPSIS
62.In openssl/x509v3.h
63.Ft int
64.Fo X509_check_host
65.Fa "X509 *x"
66.Fa "const char *name"
67.Fa "size_t namelen"
68.Fa "unsigned int flags"
69.Fa "char **peername"
70.Fc
71.Ft int
72.Fo X509_check_email
73.Fa "X509 *x"
74.Fa "const char *address"
75.Fa "size_t addresslen"
76.Fa "unsigned int flags"
77.Fc
78.Ft int
79.Fo X509_check_ip
80.Fa "X509 *x"
81.Fa "const unsigned char *address"
82.Fa "size_t addresslen"
83.Fa "unsigned int flags"
84.Fc
85.Ft int
86.Fo X509_check_ip_asc
87.Fa "X509 *x"
88.Fa "const char *address"
89.Fa "unsigned int flags"
90.Fc
91.Sh DESCRIPTION
92The certificate matching functions are used to check whether a
93certificate matches a given host name, email address, or IP address.
94The validity of the certificate and its trust level has to be checked by
95other means.
96.Pp
97.Fn X509_check_host
98checks if the certificate Subject Alternative Name (SAN) or Subject
99CommonName (CN) matches the specified host name, which must be encoded
100in the preferred name syntax described in section 3.5 of RFC 1034.
101By default, wildcards are supported and they match only in the
102left-most label; but they may match part of that label with an
103explicit prefix or suffix.
104For example, by default, the host
105.Fa name
106.Qq www.example.com
107would match a certificate with a SAN or CN value of
108.Qq *.example.com ,
109.Qq w*.example.com
110or
111.Qq *w.example.com .
112.Pp
113Per section 6.4.2 of RFC 6125,
114.Fa name
115values representing international domain names must be given in A-label
116form.
117The
118.Fa namelen
119argument must be the number of characters in the name string or zero, in
120which case the length is calculated with
121.Fn strlen name .
122When
123.Fa name
124starts with a dot (e.g.\&
125.Qq .example.com ) ,
126it will be matched by a certificate valid for any sub-domain of
127.Fa name ; see also
128.Fa X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS
129below.
130.Pp
131When the certificate is matched and
132.Fa peername
133is not
134.Dv NULL ,
135a pointer to a copy of the matching SAN or CN from the peer
136certificate is stored at the address passed in
137.Fa peername .
138The application is responsible for freeing the peername via
139.Xr free 3
140when it is no longer needed.
141.Pp
142.Fn X509_check_email
143checks if the certificate matches the specified email
144.Fa address .
145Only the mailbox syntax of RFC 822 is supported, comments are not
146allowed, and no attempt is made to normalize quoted characters.
147The
148.Fa addresslen
149argument must be the number of characters in the address string or zero
150in which case the length is calculated with
151.Fn strlen address .
152.Pp
153.Fn X509_check_ip
154checks if the certificate matches a specified IPv4 or IPv6 address.
155The
156.Fa address
157array is in binary format, in network byte order.
158The length is either 4 (IPv4) or 16 (IPv6).
159Only explicitly marked addresses in the certificates are considered;
160IP addresses stored in DNS names and Common Names are ignored.
161.Pp
162.Fn X509_check_ip_asc
163is similar, except that the NUL-terminated string
164.Fa address
165is first converted to the internal representation.
166.Pp
167The
168.Fa flags
169argument is usually 0, but it can be the bitwise OR of the following
170flags.
171.Pp
172The
173.Dv X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT
174flag causes the function to consider the subject DN even if the
175certificate contains at least one subject alternative name of the right
176type (DNS name or email address as appropriate); the default is to
177ignore the subject DN when at least one corresponding subject
178alternative names is present.
179.Pp
180The remaining flags are only meaningful for
181.Fn X509_check_host .
182.Pp
183The
184.Dv X509_CHECK_FLAG_NO_WILDCARDS
185flag disables wildcard expansion.
186.Pp
187The
188.Dv X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS
189flag suppresses support for
190.Qq *
191as a wildcard pattern in labels that have a
192prefix or suffix, such as
193.Qq www*
194or
195.Qq *www .
196.Pp
197The
198.Dv X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS
199flag allows a
200.Qq *
201that constitutes the complete label of a DNS name (e.g.\&
202.Qq *.example.com )
203to match more than one label in
204.Fa name .
205.Pp
206The
207.Dv X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS
208flag restricts
209.Fa name
210values which start with
211.Qq \&. ,
212that would otherwise match any sub-domain in the peer certificate,
213to only match direct child sub-domains.
214Thus, for instance, with this flag set a
215.Fa name
216of
217.Qq .example.com
218would match a peer certificate with a DNS name of
219.Qq www.example.com ,
220but would not match a peer certificate with a DNS name of
221.Qq www.sub.example.com .
222.Sh RETURN VALUES
223The functions return 1 for a successful match, 0 for a failed match and
224-1 for an internal error: typically a memory allocation failure or an
225ASN.1 decoding error.
226.Pp
227All functions can also return -2 if the input is malformed.
228For example,
229.Fn X509_check_host
230returns -2 if the provided
231.Fa name
232contains embedded NUL bytes.
233.Sh HISTORY
234These functions were added in OpenSSL 1.0.2.
diff --git a/src/lib/libcrypto/man/X509_check_issued.3 b/src/lib/libcrypto/man/X509_check_issued.3
new file mode 100644
index 0000000000..997dfe12f1
--- /dev/null
+++ b/src/lib/libcrypto/man/X509_check_issued.3
@@ -0,0 +1,104 @@
1.\" $OpenBSD: X509_check_issued.3,v 1.1 2016/12/05 15:56:46 schwarze Exp $
2.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
3.\"
4.\" This file was written by Victor B. Wagner <vitus@cryptocom.ru>.
5.\" Copyright (c) 2015 The OpenSSL Project. All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\"
11.\" 1. Redistributions of source code must retain the above copyright
12.\" notice, this list of conditions and the following disclaimer.
13.\"
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\" notice, this list of conditions and the following disclaimer in
16.\" the documentation and/or other materials provided with the
17.\" distribution.
18.\"
19.\" 3. All advertising materials mentioning features or use of this
20.\" software must display the following acknowledgment:
21.\" "This product includes software developed by the OpenSSL Project
22.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
23.\"
24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
25.\" endorse or promote products derived from this software without
26.\" prior written permission. For written permission, please contact
27.\" openssl-core@openssl.org.
28.\"
29.\" 5. Products derived from this software may not be called "OpenSSL"
30.\" nor may "OpenSSL" appear in their names without prior written
31.\" permission of the OpenSSL Project.
32.\"
33.\" 6. Redistributions of any form whatsoever must retain the following
34.\" acknowledgment:
35.\" "This product includes software developed by the OpenSSL Project
36.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
37.\"
38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
41.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49.\" OF THE POSSIBILITY OF SUCH DAMAGE.
50.\"
51.Dd $Mdocdate: December 5 2016 $
52.Dt X509_CHECK_ISSUED 3
53.Os
54.Sh NAME
55.Nm X509_check_issued
56.Nd check whether a certificate was issued using a given CA certificate
57.Sh SYNOPSIS
58.In openssl/x509v3.h
59.Ft int
60.Fo X509_check_issued
61.Fa "X509 *issuer"
62.Fa "X509 *subject"
63.Fc
64.Sh DESCRIPTION
65This function checks whether the certificate
66.Fa subject
67was issued using the CA certificate
68.Fa issuer .
69It does the following checks:
70.Bl -bullet
71.It
72match the issuer field of
73.Fa subject
74against the subject field of
75.Fa issuer
76.It
77if
78.Sy authorityKeyIdentifier
79is present in the
80.Fa subject
81certificate,
82compare it to the
83.Sy subjectKeyIdentifier
84of
85.Fa issuer
86.It
87check the
88.Sy keyUsage
89field of
90.Fa issuer .
91.El
92.Sh RETURN VALUE
93This function returns
94.Dv X509_V_OK
95if the certificate
96.Fa subject
97is issued by
98.Fa issuer ,
99or some
100.Dv X509_V_ERR*
101constant to indicate an error.
102.Sh SEE ALSO
103.Xr X509_check_ca 3 ,
104.Xr X509_verify_cert 3
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-11-28 09:02:37 +0000