1.\" $OpenBSD: X509_cmp.3,v 1.4 2024/06/07 14:00:09 job 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: June 7 2024 $ 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 hashes of their canonical (DER) representations as generated with 127.Xr X509_digest 3 . 128The digest function is implementation-specific: LibreSSL uses SHA-512, other 129implementations use SHA-1. 130.Pp 131.Fn X509_NAME_cmp 132compares two X.501 133.Vt Name 134objects using their canonical (DER) representations generated with 135.Xr i2d_X509_NAME 3 . 136.Pp 137.Fn X509_issuer_and_serial_cmp 138compares the 139.Fa issuer 140and 141.Fa serialNumber 142fields of two 143.Vt TBSCertificate 144structures, using 145.Fn X509_NAME_cmp 146for the 147.Fa issuer 148fields. 149.Pp 150.Fn X509_issuer_name_cmp 151compares the 152.Fa issuer 153fields of two 154.Vt TBSCertificate 155structures using 156.Fn X509_NAME_cmp . 157.Pp 158.Fn X509_subject_name_cmp 159compares the 160.Fa subject 161fields of two 162.Vt TBSCertificate 163structures using 164.Fn X509_NAME_cmp . 165.Pp 166.Fn X509_CRL_cmp 167is misnamed; it only compares the 168.Fa issuer 169fields of two 170.Vt TBSCertList 171structures using 172.Fn X509_NAME_cmp . 173.Pp 174.Fn X509_CRL_match 175compares two certificate revocation lists using 176.Xr memcmp 3 177on the hashes of their canonical (DER) representations as generated with 178.Xr X509_CRL_digest 3 . 179The digest function is implementation-specific: LibreSSL uses SHA-512, other 180implementations use SHA-1. 181.Sh RETURN VALUES 182All these functions return 0 to indicate a match or a non-zero value 183to indicate a mismatch. 184.Pp 185.Fn X509_NAME_cmp , 186.Fn X509_issuer_and_serial_cmp , 187.Fn X509_issuer_name_cmp , 188.Fn X509_subject_name_cmp 189and 190.Fn X509_CRL_cmp 191may return -2 to indicate an error. 192.Sh SEE ALSO 193.Xr i2d_X509_NAME 3 , 194.Xr X509_CRL_new 3 , 195.Xr X509_digest 3 , 196.Xr X509_NAME_new 3 , 197.Xr X509_new 3 198.Sh STANDARDS 199RFC 5280: Internet X.509 Public Key Infrastructure Certificate 200and Certificate Revocation List (CRL) Profile 201.Bl -dash -compact -offset indent 202.It 203section 4.1: Basic Certificate Fields 204.It 205section 5.1: CRL Fields 206.El 207.Sh HISTORY 208.Fn X509_issuer_and_serial_cmp , 209.Fn X509_issuer_name_cmp , 210and 211.Fn X509_subject_name_cmp 212first appeared in SSLeay 0.5.1 and 213.Fn X509_NAME_cmp 214and 215.Fn X509_CRL_cmp 216in SSLeay 0.8.0. 217These functions have been available since 218.Ox 2.4 . 219.Pp 220.Fn X509_cmp 221first appeared in OpenSSL 0.9.5 and has been available since 222.Ox 2.7 . 223.Pp 224.Fn X509_CRL_match 225first appeared in OpenSSL 1.0.0 and has been available since 226.Ox 4.9 . 227.Sh BUGS 228For 229.Fn X509_NAME_cmp , 230.Fn X509_issuer_and_serial_cmp , 231.Fn X509_issuer_name_cmp , 232.Fn X509_subject_name_cmp 233and 234.Fn X509_CRL_cmp , 235the return value -2 sometimes indicates a mismatch and sometimes an error. 236