1.\" $OpenBSD: X509_cmp.3,v 1.3 2021/07/02 10:50:39 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: July 2 2021 $ 69.Dt X509_CMP 3 70.Os 71.Sh NAME 72.Nm X509_cmp , 73.Nm X509_NAME_cmp , 74.\" The alias X509_name_cmp(3) is intentionally undocumented 75.\" because it is almost unused in real-world code. 76.Nm X509_issuer_and_serial_cmp , 77.Nm X509_issuer_name_cmp , 78.Nm X509_subject_name_cmp , 79.Nm X509_CRL_cmp , 80.Nm X509_CRL_match 81.Nd compare X.509 certificates and related values 82.\" The function name_cmp() is intentionally undocumented. 83.\" It was a mistake to make it public in the first place, 84.\" and it is no longer part of the public API in OpenSSL 1.1. 85.Sh SYNOPSIS 86.In openssl/x509.h 87.Ft int 88.Fo X509_cmp 89.Fa "const X509 *a" 90.Fa "const X509 *b" 91.Fc 92.Ft int 93.Fo X509_NAME_cmp 94.Fa "const X509_NAME *a" 95.Fa "const X509_NAME *b" 96.Fc 97.Ft int 98.Fo X509_issuer_and_serial_cmp 99.Fa "const X509 *a" 100.Fa "const X509 *b" 101.Fc 102.Ft int 103.Fo X509_issuer_name_cmp 104.Fa "const X509 *a" 105.Fa "const X509 *b" 106.Fc 107.Ft int 108.Fo X509_subject_name_cmp 109.Fa "const X509 *a" 110.Fa "const X509 *b" 111.Fc 112.Ft int 113.Fo X509_CRL_cmp 114.Fa "const X509_CRL *a" 115.Fa "const X509_CRL *b" 116.Fc 117.Ft int 118.Fo X509_CRL_match 119.Fa "const X509_CRL *a" 120.Fa "const X509_CRL *b" 121.Fc 122.Sh DESCRIPTION 123.Fn X509_cmp 124compares two X.509 certificates using 125.Xr memcmp 3 126on the SHA1 hashes of their canonical (DER) representations as generated with 127.Xr X509_digest 3 . 128.Pp 129.Fn X509_NAME_cmp 130compares two X.501 131.Vt Name 132objects using their canonical (DER) representations generated with 133.Xr i2d_X509_NAME 3 . 134.Pp 135.Fn X509_issuer_and_serial_cmp 136compares the 137.Fa issuer 138and 139.Fa serialNumber 140fields of two 141.Vt TBSCertificate 142structures, using 143.Fn X509_NAME_cmp 144for the 145.Fa issuer 146fields. 147.Pp 148.Fn X509_issuer_name_cmp 149compares the 150.Fa issuer 151fields of two 152.Vt TBSCertificate 153structures using 154.Fn X509_NAME_cmp . 155.Pp 156.Fn X509_subject_name_cmp 157compares the 158.Fa subject 159fields of two 160.Vt TBSCertificate 161structures using 162.Fn X509_NAME_cmp . 163.Pp 164.Fn X509_CRL_cmp 165is misnamed; it only compares the 166.Fa issuer 167fields of two 168.Vt TBSCertList 169structures using 170.Fn X509_NAME_cmp . 171.Pp 172.Fn X509_CRL_match 173compares two certificate revocation lists using 174.Xr memcmp 3 175on the SHA1 hashes of their canonical (DER) representations as generated with 176.Xr X509_CRL_digest 3 . 177.Sh RETURN VALUES 178All these functions return 0 to indicate a match or a non-zero value 179to indicate a mismatch. 180.Pp 181.Fn X509_NAME_cmp , 182.Fn X509_issuer_and_serial_cmp , 183.Fn X509_issuer_name_cmp , 184.Fn X509_subject_name_cmp 185and 186.Fn X509_CRL_cmp 187may return -2 to indicate an error. 188.Sh SEE ALSO 189.Xr i2d_X509_NAME 3 , 190.Xr X509_CRL_new 3 , 191.Xr X509_digest 3 , 192.Xr X509_NAME_new 3 , 193.Xr X509_new 3 194.Sh STANDARDS 195RFC 5280: Internet X.509 Public Key Infrastructure Certificate 196and Certificate Revocation List (CRL) Profile 197.Bl -dash -compact -offset indent 198.It 199section 4.1: Basic Certificate Fields 200.It 201section 5.1: CRL Fields 202.El 203.Sh HISTORY 204.Fn X509_issuer_and_serial_cmp , 205.Fn X509_issuer_name_cmp , 206and 207.Fn X509_subject_name_cmp 208first appeared in SSLeay 0.5.1 and 209.Fn X509_NAME_cmp 210and 211.Fn X509_CRL_cmp 212in SSLeay 0.8.0. 213These functions have been available since 214.Ox 2.4 . 215.Pp 216.Fn X509_cmp 217first appeared in OpenSSL 0.9.5 and has been available since 218.Ox 2.7 . 219.Pp 220.Fn X509_CRL_match 221first appeared in OpenSSL 1.0.0 and has been available since 222.Ox 4.9 . 223.Sh BUGS 224For 225.Fn X509_NAME_cmp , 226.Fn X509_issuer_and_serial_cmp , 227.Fn X509_issuer_name_cmp , 228.Fn X509_subject_name_cmp 229and 230.Fn X509_CRL_cmp , 231the return value -2 sometimes indicates a mismatch and sometimes an error. 232