1.\" $OpenBSD: X509_get_pubkey.3,v 1.13 2022/03/31 17:27:17 naddy Exp $ 2.\" selective merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2020, 2021 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 Dr. Stephen Henson <steve@openssl.org>. 22.\" Copyright (c) 2015 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: March 31 2022 $ 69.Dt X509_GET_PUBKEY 3 70.Os 71.Sh NAME 72.Nm X509_get_pubkey , 73.Nm X509_get0_pubkey , 74.Nm X509_set_pubkey , 75.Nm X509_get_X509_PUBKEY , 76.Nm X509_get0_pubkey_bitstr , 77.Nm X509_REQ_get_pubkey , 78.Nm X509_REQ_get0_pubkey , 79.Nm X509_REQ_set_pubkey , 80.Nm X509_extract_key , 81.Nm X509_REQ_extract_key 82.Nd get or set certificate or certificate request public key 83.Sh SYNOPSIS 84.In openssl/x509.h 85.Ft EVP_PKEY * 86.Fo X509_get_pubkey 87.Fa "X509 *x" 88.Fc 89.Ft EVP_PKEY * 90.Fo X509_get0_pubkey 91.Fa "const X509 *x" 92.Fc 93.Ft int 94.Fo X509_set_pubkey 95.Fa "X509 *x" 96.Fa "EVP_PKEY *pkey" 97.Fc 98.Ft X509_PUBKEY * 99.Fo X509_get_X509_PUBKEY 100.Fa "const X509 *x" 101.Fc 102.Ft ASN1_BIT_STRING * 103.Fo X509_get0_pubkey_bitstr 104.Fa "const X509 *x" 105.Fc 106.Ft EVP_PKEY * 107.Fo X509_REQ_get_pubkey 108.Fa "X509_REQ *req" 109.Fc 110.Ft EVP_PKEY * 111.Fo X509_REQ_get0_pubkey 112.Fa "X509_REQ *req" 113.Fc 114.Ft int 115.Fo X509_REQ_set_pubkey 116.Fa "X509_REQ *x" 117.Fa "EVP_PKEY *pkey" 118.Fc 119.Ft EVP_PKEY * 120.Fo X509_extract_key 121.Fa "X509 *x" 122.Fc 123.Ft EVP_PKEY * 124.Fo X509_REQ_extract_key 125.Fa "X509_REQ *req" 126.Fc 127.Sh DESCRIPTION 128.Fn X509_get_pubkey 129attempts to decode the public key for certificate 130.Fa x . 131If successful, it returns the public key as an 132.Vt EVP_PKEY 133pointer with its reference count incremented: this means the returned 134key must be freed up after use. 135.Fn X509_get0_pubkey 136is similar except that it does not increment the reference count 137of the returned 138.Vt EVP_PKEY , 139so it must not be freed up after use. 140.Pp 141.Fn X509_get_X509_PUBKEY 142returns an internal pointer to the 143.Vt SubjectPublicKeyInfo 144structure contained in 145.Fa x . 146The returned value must not be freed up after use. 147.Pp 148.Fn X509_get0_pubkey_bitstr 149returns an internal pointer to just the public key contained in this 150.Vt SubjectPublicKeyInfo 151structure, without the information about the algorithm used. 152.Pp 153.Fn X509_set_pubkey 154attempts to set the public key for certificate 155.Fa x 156to 157.Fa pkey . 158The key 159.Fa pkey 160should be freed up after use. 161.Pp 162.Fn X509_REQ_get_pubkey , 163.Fn X509_REQ_get0_pubkey , 164and 165.Fn X509_REQ_set_pubkey 166are similar but operate on certificate request 167.Fa req . 168.Pp 169The first time a public key is decoded, the 170.Vt EVP_PKEY 171structure is cached in the certificate or certificate request itself. 172Subsequent calls return the cached structure with its reference count 173incremented to improve performance. 174.Pp 175.Fn X509_extract_key 176and 177.Fn X509_REQ_extract_key 178are deprecated aliases for 179.Fn X509_get_pubkey 180and 181.Fn X509_REQ_get_pubkey , 182respectively, implemented as macros. 183.Sh RETURN VALUES 184.Fn X509_get_pubkey , 185.Fn X509_get0_pubkey , 186.Fn X509_get_X509_PUBKEY , 187.Fn X509_get0_pubkey_bitstr , 188.Fn X509_REQ_get_pubkey , 189.Fn X509_REQ_get0_pubkey , 190.Fn X509_extract_key , 191and 192.Fn X509_REQ_extract_key 193return a public key or 194.Dv NULL 195if an error occurred. 196.Pp 197.Fn X509_set_pubkey 198and 199.Fn X509_REQ_set_pubkey 200return 1 for success or 0 for failure. 201.Pp 202In some cases of failure of 203.Fn X509_get0_pubkey , 204.Fn X509_set_pubkey , 205.Fn X509_REQ_get_pubkey , 206.Fn X509_REQ_get0_pubkey , 207and 208.Fn X509_REQ_set_pubkey , 209the reason can be determined with 210.Xr ERR_get_error 3 . 211.Sh ERRORS 212.Fn X509_get_pubkey , 213.Fn X509_get0_pubkey , 214.Fn X509_REQ_get_pubkey , 215.Fn X509_extract_key , 216and 217.Fn X509_REQ_extract_key 218provide diagnostics as documented for 219.Xr X509_PUBKEY_get 3 . 220If 221.Fa x 222or 223.Fa req 224is 225.Dv NULL 226or contains no certificate information, 227they fail without pushing an error onto the stack. 228.Pp 229.Fn X509_get_X509_PUBKEY 230provides no diagnostics and crashes by accessing a 231.Dv NULL 232pointer if 233.Fa x 234is 235.Dv NULL 236or contains no certificate information, 237.Pp 238.Fn X509_get0_pubkey_bitstr 239provides no diagnostics 240and fails without pushing an error onto the stack if 241.Fa x 242is 243.Dv NULL , 244but it crashes by accessing a 245.Dv NULL 246pointer if 247.Fa x 248contains no certificate information. 249.Sh SEE ALSO 250.Xr d2i_X509 3 , 251.Xr X509_CRL_get0_by_serial 3 , 252.Xr X509_NAME_add_entry_by_txt 3 , 253.Xr X509_NAME_ENTRY_get_object 3 , 254.Xr X509_NAME_get_index_by_NID 3 , 255.Xr X509_NAME_print_ex 3 , 256.Xr X509_new 3 , 257.Xr X509_PUBKEY_new 3 , 258.Xr X509_REQ_new 3 , 259.Xr X509_sign 3 , 260.Xr X509_verify_cert 3 , 261.Xr X509V3_get_d2i 3 262.Sh STANDARDS 263RFC 5280, Internet X.509 Public Key Infrastructure Certificate 264and Certificate Revocation List (CRL) Profile, 265section 4.1 Basic Certificate Fields 266.Pp 267RFC 2986: PKCS #10: Certification Request Syntax Specification, 268section 4.1 CertificationRequestInfo 269.Sh HISTORY 270.Fn X509_extract_key 271and 272.Fn X509_REQ_extract_key 273first appeared in SSLeay 0.5.1 but returned a pointer to an 274.Vt RSA 275object before SSLeay 0.6.0. 276.Fn X509_get_pubkey , 277.Fn X509_set_pubkey , 278.Fn X509_REQ_get_pubkey , 279and 280.Fn X509_REQ_set_pubkey 281first appeared in SSLeay 0.6.5. 282.Fn X509_get_X509_PUBKEY 283first appeared in SSLeay 0.8.0. 284These functions have been available since 285.Ox 2.4 . 286.Pp 287.Fn X509_get0_pubkey_bitstr 288first appeared in OpenSSL 0.9.7 and has been available since 289.Ox 3.4 . 290.Pp 291.Fn X509_get0_pubkey 292first appeared in OpenSSL 1.1.0 and has been available since 293.Ox 6.3 . 294.Fn X509_REQ_get0_pubkey 295first appeared in OpenSSL 1.1.0 and has been available since 296.Ox 7.1 . 297