1.\" $OpenBSD: X509_cmp.3,v 1.1 2019/08/20 13:27:19 schwarze Exp $ 2.\" full merge up to: OpenSSL ea5d4b89 Jun 6 11:42:02 2019 +0800 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org> 8.\" 9.\" Permission to use, copy, modify, and distribute this software for any 10.\" purpose with or without fee is hereby granted, provided that the above 11.\" copyright notice and this permission notice appear in all copies. 12.\" 13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 20.\" 21.\" The original file was written by Paul Yang <yang.yang@baishancloud.com>. 22.\" Copyright (c) 2019 The OpenSSL Project. All rights reserved. 23.\" 24.\" Redistribution and use in source and binary forms, with or without 25.\" modification, are permitted provided that the following conditions 26.\" are met: 27.\" 28.\" 1. Redistributions of source code must retain the above copyright 29.\" notice, this list of conditions and the following disclaimer. 30.\" 31.\" 2. Redistributions in binary form must reproduce the above copyright 32.\" notice, this list of conditions and the following disclaimer in 33.\" the documentation and/or other materials provided with the 34.\" distribution. 35.\" 36.\" 3. All advertising materials mentioning features or use of this 37.\" software must display the following acknowledgment: 38.\" "This product includes software developed by the OpenSSL Project 39.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 40.\" 41.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 42.\" endorse or promote products derived from this software without 43.\" prior written permission. For written permission, please contact 44.\" openssl-core@openssl.org. 45.\" 46.\" 5. Products derived from this software may not be called "OpenSSL" 47.\" nor may "OpenSSL" appear in their names without prior written 48.\" permission of the OpenSSL Project. 49.\" 50.\" 6. Redistributions of any form whatsoever must retain the following 51.\" acknowledgment: 52.\" "This product includes software developed by the OpenSSL Project 53.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 54.\" 55.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 56.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 57.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 58.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 59.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 60.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 61.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 62.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 63.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 64.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 66.\" OF THE POSSIBILITY OF SUCH DAMAGE. 67.\" 68.Dd $Mdocdate: August 20 2019 $ 69.Dt X509_CMP 3 70.Os 71.Sh NAME 72.Nm X509_cmp , 73.Nm X509_NAME_cmp , 74.Nm X509_issuer_and_serial_cmp , 75.Nm X509_issuer_name_cmp , 76.Nm X509_subject_name_cmp , 77.Nm X509_CRL_cmp , 78.Nm X509_CRL_match 79.Nd compare X.509 certificates and related values 80.Sh SYNOPSIS 81.In openssl/x509.h 82.Ft int 83.Fo X509_cmp 84.Fa "const X509 *a" 85.Fa "const X509 *b" 86.Fc 87.Ft int 88.Fo X509_NAME_cmp 89.Fa "const X509_NAME *a" 90.Fa "const X509_NAME *b" 91.Fc 92.Ft int 93.Fo X509_issuer_and_serial_cmp 94.Fa "const X509 *a" 95.Fa "const X509 *b" 96.Fc 97.Ft int 98.Fo X509_issuer_name_cmp 99.Fa "const X509 *a" 100.Fa "const X509 *b" 101.Fc 102.Ft int 103.Fo X509_subject_name_cmp 104.Fa "const X509 *a" 105.Fa "const X509 *b" 106.Fc 107.Ft int 108.Fo X509_CRL_cmp 109.Fa "const X509_CRL *a" 110.Fa "const X509_CRL *b" 111.Fc 112.Ft int 113.Fo X509_CRL_match 114.Fa "const X509_CRL *a" 115.Fa "const X509_CRL *b" 116.Fc 117.Sh DESCRIPTION 118.Fn X509_cmp 119compares two X.509 certificates using 120.Xr memcmp 3 121on the SHA1 hashes of their canonical (DER) representations as generated with 122.Xr X509_digest 3 . 123.Pp 124.Fn X509_NAME_cmp 125compares two X.501 126.Vt Name 127objects using their canonical (DER) representations generated with 128.Xr i2d_X509_NAME 3 . 129.Pp 130.Fn X509_issuer_and_serial_cmp 131compares the 132.Fa issuer 133and 134.Fa serialNumber 135fields of two 136.Vt TBSCertificate 137structures, using 138.Fn X509_NAME_cmp 139for the 140.Fa issuer 141fields. 142.Pp 143.Fn X509_issuer_name_cmp 144compares the 145.Fa issuer 146fields of two 147.Vt TBSCertificate 148structures using 149.Fn X509_NAME_cmp . 150.Pp 151.Fn X509_subject_name_cmp 152compares the 153.Fa subject 154fields of two 155.Vt TBSCertificate 156structures using 157.Fn X509_NAME_cmp . 158.Pp 159.Fn X509_CRL_cmp 160is misnamed; it only compares the 161.Fa issuer 162fields of two 163.Vt TBSCertList 164structures using 165.Fn X509_NAME_cmp . 166.Pp 167.Fn X509_CRL_match 168compares two certificate revocation lists using 169.Xr memcmp 3 170on the SHA1 hashes of their canonical (DER) representations as generated with 171.Xr X509_CRL_digest 3 . 172.Sh RETURN VALUES 173All these functions return 0 to indicate a match or a non-zero value 174to indicate a mismatch. 175.Pp 176.Fn X509_NAME_cmp , 177.Fn X509_issuer_and_serial_cmp , 178.Fn X509_issuer_name_cmp , 179.Fn X509_subject_name_cmp 180and 181.Fn X509_CRL_cmp 182may return -2 to indicate an error. 183.Sh SEE ALSO 184.Xr i2d_X509_NAME 3 , 185.Xr X509_CRL_new 3 , 186.Xr X509_digest 3 , 187.Xr X509_NAME_new 3 , 188.Xr X509_new 3 189.Sh STANDARDS 190RFC 5280: Internet X.509 Public Key Infrastructure Certificate 191and Certificate Revocation List (CRL) Profile 192.Bl -dash -compact -offset indent 193.It 194section 4.1: Basic Certificate Fields 195.It 196section 5.1: CRL Fields 197.El 198.Sh HISTORY 199.Fn X509_issuer_and_serial_cmp , 200.Fn X509_issuer_name_cmp , 201and 202.Fn X509_subject_name_cmp 203first appeared in SSLeay 0.5.1 and 204.Fn X509_NAME_cmp 205and 206.Fn X509_CRL_cmp 207in SSLeay 0.8.0. 208These functions have been available since 209.Ox 2.4 . 210.Pp 211.Fn X509_cmp 212first appeared in OpenSSL 0.9.5 and has been available since 213.Ox 2.7 . 214.Pp 215.Fn X509_CRL_match 216first appeared in OpenSSL 1.0.0 and has been available since 217.Ox 4.9 . 218.Sh BUGS 219For 220.Fn X509_NAME_cmp , 221.Fn X509_issuer_and_serial_cmp , 222.Fn X509_issuer_name_cmp , 223.Fn X509_subject_name_cmp 224and 225.Fn X509_CRL_cmp , 226the return value -2 sometimes indicates a mismatch and sometimes an error. 227