From ef9999173c00f7173583e8e79100096f558c6972 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Tue, 20 Aug 2019 13:27:19 +0000 Subject: New manual page X509_cmp(3) documenting the same public functions as in OpenSSL 1.1.1. I rewrote most of the text for clarity, precision, and conciseness and added some additional information. A few sentences from Paul Yang remain. --- src/lib/libcrypto/man/Makefile | 3 +- src/lib/libcrypto/man/X509_CRL_new.3 | 5 +- src/lib/libcrypto/man/X509_NAME_new.3 | 5 +- src/lib/libcrypto/man/X509_cmp.3 | 226 ++++++++++++++++++++++++++++++++++ src/lib/libcrypto/man/X509_digest.3 | 7 +- src/lib/libcrypto/man/X509_new.3 | 5 +- 6 files changed, 241 insertions(+), 10 deletions(-) create mode 100644 src/lib/libcrypto/man/X509_cmp.3 diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index b14e5d015f..99536f65aa 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.151 2019/08/19 13:52:53 schwarze Exp $ +# $OpenBSD: Makefile,v 1.152 2019/08/20 13:27:19 schwarze Exp $ .include @@ -265,6 +265,7 @@ MAN= \ X509_check_host.3 \ X509_check_issued.3 \ X509_check_private_key.3 \ + X509_cmp.3 \ X509_cmp_time.3 \ X509_digest.3 \ X509_get_pubkey.3 \ diff --git a/src/lib/libcrypto/man/X509_CRL_new.3 b/src/lib/libcrypto/man/X509_CRL_new.3 index 183de5305c..1312469743 100644 --- a/src/lib/libcrypto/man/X509_CRL_new.3 +++ b/src/lib/libcrypto/man/X509_CRL_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_CRL_new.3,v 1.9 2019/08/19 13:52:53 schwarze Exp $ +.\" $OpenBSD: X509_CRL_new.3,v 1.10 2019/08/20 13:27:19 schwarze Exp $ .\" .\" Copyright (c) 2016, 2018 Ingo Schwarze .\" @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: August 19 2019 $ +.Dd $Mdocdate: August 20 2019 $ .Dt X509_CRL_NEW 3 .Os .Sh NAME @@ -111,6 +111,7 @@ returns 1 on success or 0 on error. .Xr X509_CRL_get_ext_d2i 3 , .Xr X509_CRL_get_issuer 3 , .Xr X509_CRL_get_version 3 , +.Xr X509_CRL_match 3 , .Xr X509_CRL_sign 3 , .Xr X509_EXTENSION_new 3 , .Xr X509_INFO_new 3 , diff --git a/src/lib/libcrypto/man/X509_NAME_new.3 b/src/lib/libcrypto/man/X509_NAME_new.3 index 19dd1066f5..5895dd5a10 100644 --- a/src/lib/libcrypto/man/X509_NAME_new.3 +++ b/src/lib/libcrypto/man/X509_NAME_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_NAME_new.3,v 1.7 2019/06/06 01:06:59 schwarze Exp $ +.\" $OpenBSD: X509_NAME_new.3,v 1.8 2019/08/20 13:27:19 schwarze Exp $ .\" .\" Copyright (c) 2016 Ingo Schwarze .\" @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: June 6 2019 $ +.Dd $Mdocdate: August 20 2019 $ .Dt X509_NAME_NEW 3 .Os .Sh NAME @@ -81,6 +81,7 @@ if an error occurred. .Xr SSL_load_client_CA_file 3 , .Xr X509_get_subject_name 3 , .Xr X509_NAME_add_entry_by_txt 3 , +.Xr X509_NAME_cmp 3 , .Xr X509_NAME_digest 3 , .Xr X509_NAME_ENTRY_new 3 , .Xr X509_NAME_get_index_by_NID 3 , diff --git a/src/lib/libcrypto/man/X509_cmp.3 b/src/lib/libcrypto/man/X509_cmp.3 new file mode 100644 index 0000000000..1734d6a74d --- /dev/null +++ b/src/lib/libcrypto/man/X509_cmp.3 @@ -0,0 +1,226 @@ +.\" $OpenBSD: X509_cmp.3,v 1.1 2019/08/20 13:27:19 schwarze Exp $ +.\" full merge up to: OpenSSL ea5d4b89 Jun 6 11:42:02 2019 +0800 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2019 Ingo Schwarze +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" The original file was written by Paul Yang . +.\" Copyright (c) 2019 The OpenSSL Project. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" 3. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: August 20 2019 $ +.Dt X509_CMP 3 +.Os +.Sh NAME +.Nm X509_cmp , +.Nm X509_NAME_cmp , +.Nm X509_issuer_and_serial_cmp , +.Nm X509_issuer_name_cmp , +.Nm X509_subject_name_cmp , +.Nm X509_CRL_cmp , +.Nm X509_CRL_match +.Nd compare X.509 certificates and related values +.Sh SYNOPSIS +.In openssl/x509.h +.Ft int +.Fo X509_cmp +.Fa "const X509 *a" +.Fa "const X509 *b" +.Fc +.Ft int +.Fo X509_NAME_cmp +.Fa "const X509_NAME *a" +.Fa "const X509_NAME *b" +.Fc +.Ft int +.Fo X509_issuer_and_serial_cmp +.Fa "const X509 *a" +.Fa "const X509 *b" +.Fc +.Ft int +.Fo X509_issuer_name_cmp +.Fa "const X509 *a" +.Fa "const X509 *b" +.Fc +.Ft int +.Fo X509_subject_name_cmp +.Fa "const X509 *a" +.Fa "const X509 *b" +.Fc +.Ft int +.Fo X509_CRL_cmp +.Fa "const X509_CRL *a" +.Fa "const X509_CRL *b" +.Fc +.Ft int +.Fo X509_CRL_match +.Fa "const X509_CRL *a" +.Fa "const X509_CRL *b" +.Fc +.Sh DESCRIPTION +.Fn X509_cmp +compares two X.509 certificates using +.Xr memcmp 3 +on the SHA1 hashes of their canonical (DER) representations as generated with +.Xr X509_digest 3 . +.Pp +.Fn X509_NAME_cmp +compares two X.501 +.Vt Name +objects using their canonical (DER) representations generated with +.Xr i2d_X509_NAME 3 . +.Pp +.Fn X509_issuer_and_serial_cmp +compares the +.Fa issuer +and +.Fa serialNumber +fields of two +.Vt TBSCertificate +structures, using +.Fn X509_NAME_cmp +for the +.Fa issuer +fields. +.Pp +.Fn X509_issuer_name_cmp +compares the +.Fa issuer +fields of two +.Vt TBSCertificate +structures using +.Fn X509_NAME_cmp . +.Pp +.Fn X509_subject_name_cmp +compares the +.Fa subject +fields of two +.Vt TBSCertificate +structures using +.Fn X509_NAME_cmp . +.Pp +.Fn X509_CRL_cmp +is misnamed; it only compares the +.Fa issuer +fields of two +.Vt TBSCertList +structures using +.Fn X509_NAME_cmp . +.Pp +.Fn X509_CRL_match +compares two certificate revocation lists using +.Xr memcmp 3 +on the SHA1 hashes of their canonical (DER) representations as generated with +.Xr X509_CRL_digest 3 . +.Sh RETURN VALUES +All these functions return 0 to indicate a match or a non-zero value +to indicate a mismatch. +.Pp +.Fn X509_NAME_cmp , +.Fn X509_issuer_and_serial_cmp , +.Fn X509_issuer_name_cmp , +.Fn X509_subject_name_cmp +and +.Fn X509_CRL_cmp +may return -2 to indicate an error. +.Sh SEE ALSO +.Xr i2d_X509_NAME 3 , +.Xr X509_CRL_new 3 , +.Xr X509_digest 3 , +.Xr X509_NAME_new 3 , +.Xr X509_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate +and Certificate Revocation List (CRL) Profile +.Bl -dash -compact -offset indent +.It +section 4.1: Basic Certificate Fields +.It +section 5.1: CRL Fields +.El +.Sh HISTORY +.Fn X509_issuer_and_serial_cmp , +.Fn X509_issuer_name_cmp , +and +.Fn X509_subject_name_cmp +first appeared in SSLeay 0.5.1 and +.Fn X509_NAME_cmp +and +.Fn X509_CRL_cmp +in SSLeay 0.8.0. +These functions have been available since +.Ox 2.4 . +.Pp +.Fn X509_cmp +first appeared in OpenSSL 0.9.5 and has been available since +.Ox 2.7 . +.Pp +.Fn X509_CRL_match +first appeared in OpenSSL 1.0.0 and has been available since +.Ox 4.9 . +.Sh BUGS +For +.Fn X509_NAME_cmp , +.Fn X509_issuer_and_serial_cmp , +.Fn X509_issuer_name_cmp , +.Fn X509_subject_name_cmp +and +.Fn X509_CRL_cmp , +the return value -2 sometimes indicates a mismatch and sometimes an error. diff --git a/src/lib/libcrypto/man/X509_digest.3 b/src/lib/libcrypto/man/X509_digest.3 index 63016427c0..7627e07731 100644 --- a/src/lib/libcrypto/man/X509_digest.3 +++ b/src/lib/libcrypto/man/X509_digest.3 @@ -1,5 +1,5 @@ -.\" $OpenBSD: X509_digest.3,v 1.7 2019/06/06 01:06:59 schwarze Exp $ -.\" OpenSSL X509_digest.pod 3ba4dac6 Mar 23 13:04:52 2017 -0400 +.\" $OpenBSD: X509_digest.3,v 1.8 2019/08/20 13:27:19 schwarze Exp $ +.\" full merge up to: OpenSSL 1212818e Sep 11 13:22:14 2018 +0100 .\" .\" This file was written by Rich Salz .\" Copyright (c) 2017 The OpenSSL Project. All rights reserved. @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: June 6 2019 $ +.Dd $Mdocdate: August 20 2019 $ .Dt X509_DIGEST 3 .Os .Sh NAME @@ -131,6 +131,7 @@ points to a place where the digest size will be stored. These functions return 1 for success or 0 for failure. .Sh SEE ALSO .Xr EVP_get_digestbyname 3 , +.Xr X509_cmp 3 , .Xr X509_CRL_new 3 , .Xr X509_NAME_new 3 , .Xr X509_new 3 , diff --git a/src/lib/libcrypto/man/X509_new.3 b/src/lib/libcrypto/man/X509_new.3 index 3ccd311e61..25b45b39bd 100644 --- a/src/lib/libcrypto/man/X509_new.3 +++ b/src/lib/libcrypto/man/X509_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_new.3,v 1.18 2019/08/19 13:52:53 schwarze Exp $ +.\" $OpenBSD: X509_new.3,v 1.19 2019/08/20 13:27:19 schwarze Exp $ .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 .\" .\" This file was written by Dr. Stephen Henson . @@ -49,7 +49,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: August 19 2019 $ +.Dd $Mdocdate: August 20 2019 $ .Dt X509_NEW 3 .Os .Sh NAME @@ -147,6 +147,7 @@ if an error occurs. .Xr X509_check_issued 3 , .Xr X509_check_private_key 3 , .Xr X509_CINF_new 3 , +.Xr X509_cmp 3 , .Xr X509_CRL_new 3 , .Xr X509_digest 3 , .Xr X509_EXTENSION_new 3 , -- cgit v1.2.3-55-g6feb