1.\" $OpenBSD: X509_get_pubkey.3,v 1.9 2021/06/30 10:06:43 schwarze Exp $ 2.\" selective merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 3.\" X509_REQ_get0_pubkey and X509_REQ_get_X509_PUBKEY not yet in LibreSSL 4.\" 5.\" This file is a derived work. 6.\" The changes are covered by the following Copyright and license: 7.\" 8.\" Copyright (c) 2020, 2021 Ingo Schwarze <schwarze@openbsd.org> 9.\" 10.\" Permission to use, copy, modify, and distribute this software for any 11.\" purpose with or without fee is hereby granted, provided that the above 12.\" copyright notice and this permission notice appear in all copies. 13.\" 14.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 15.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 16.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 17.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 18.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 19.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 20.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 21.\" 22.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>. 23.\" Copyright (c) 2015 The OpenSSL Project. All rights reserved. 24.\" 25.\" Redistribution and use in source and binary forms, with or without 26.\" modification, are permitted provided that the following conditions 27.\" are met: 28.\" 29.\" 1. Redistributions of source code must retain the above copyright 30.\" notice, this list of conditions and the following disclaimer. 31.\" 32.\" 2. Redistributions in binary form must reproduce the above copyright 33.\" notice, this list of conditions and the following disclaimer in 34.\" the documentation and/or other materials provided with the 35.\" distribution. 36.\" 37.\" 3. All advertising materials mentioning features or use of this 38.\" software must display the following acknowledgment: 39.\" "This product includes software developed by the OpenSSL Project 40.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 41.\" 42.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 43.\" endorse or promote products derived from this software without 44.\" prior written permission. For written permission, please contact 45.\" openssl-core@openssl.org. 46.\" 47.\" 5. Products derived from this software may not be called "OpenSSL" 48.\" nor may "OpenSSL" appear in their names without prior written 49.\" permission of the OpenSSL Project. 50.\" 51.\" 6. Redistributions of any form whatsoever must retain the following 52.\" acknowledgment: 53.\" "This product includes software developed by the OpenSSL Project 54.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 55.\" 56.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 57.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 58.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 59.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 60.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 61.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 62.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 63.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 64.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 65.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 66.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 67.\" OF THE POSSIBILITY OF SUCH DAMAGE. 68.\" 69.Dd $Mdocdate: June 30 2021 $ 70.Dt X509_GET_PUBKEY 3 71.Os 72.Sh NAME 73.Nm X509_get_pubkey , 74.Nm X509_get0_pubkey , 75.Nm X509_set_pubkey , 76.Nm X509_get_X509_PUBKEY , 77.Nm X509_get0_pubkey_bitstr , 78.Nm X509_REQ_get_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 "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 int 111.Fo X509_REQ_set_pubkey 112.Fa "X509_REQ *x" 113.Fa "EVP_PKEY *pkey" 114.Fc 115.Ft EVP_PKEY * 116.Fo X509_extract_key 117.Fa "X509 *x" 118.Fc 119.Ft EVP_PKEY * 120.Fo X509_REQ_extract_key 121.Fa "X509_REQ *req" 122.Fc 123.Sh DESCRIPTION 124.Fn X509_get_pubkey 125attempts to decode the public key for certificate 126.Fa x . 127If successful it returns the public key as an 128.Vt EVP_PKEY 129pointer with its reference count incremented: this means the returned 130key must be freed up after use. 131.Fn X509_get0_pubkey 132is similar except that it does not increment the reference count 133of the returned 134.Vt EVP_PKEY , 135so it must not be freed up after use. 136.Pp 137.Fn X509_get_X509_PUBKEY 138returns an internal pointer to the 139.Vt SubjectPublicKeyInfo 140structure contained in 141.Fa x . 142The returned value must not be freed up after use. 143.Fn X509_get_X509_PUBKEY 144is implemented as a macro. 145.Pp 146.Fn X509_get0_pubkey_bitstr 147returns an internal pointer to just the public key contained in this 148.Vt SubjectPublicKeyInfo 149structure, without the information about the algorithm used. 150.Pp 151.Fn X509_set_pubkey 152attempts to set the public key for certificate 153.Fa x 154to 155.Fa pkey . 156The key 157.Fa pkey 158should be freed up after use. 159.Pp 160.Fn X509_REQ_get_pubkey 161and 162.Fn X509_REQ_set_pubkey 163are similar but operate on certificate request 164.Fa req . 165.Pp 166The first time a public key is decoded, the 167.Vt EVP_PKEY 168structure is cached in the certificate or certificate request itself. 169Subsequent calls return the cached structure with its reference count 170incremented to improve performance. 171.Pp 172.Fn X509_extract_key 173and 174.Fn X509_REQ_extract_key 175are deprecated aliases for 176.Fn X509_get_pubkey 177and 178.Fn X509_REQ_get_pubkey , 179respectively, implemented as macros. 180.Sh RETURN VALUES 181.Fn X509_get_pubkey , 182.Fn X509_get0_pubkey , 183.Fn X509_get_X509_PUBKEY , 184.Fn X509_get0_pubkey_bitstr , 185.Fn X509_REQ_get_pubkey , 186.Fn X509_extract_key , 187and 188.Fn X509_REQ_extract_key 189return a public key or 190.Dv NULL 191if an error occurred. 192.Pp 193.Fn X509_set_pubkey 194and 195.Fn X509_REQ_set_pubkey 196return 1 for success or 0 for failure. 197.Pp 198In some cases of failure of 199.Fn X509_get0_pubkey , 200.Fn X509_set_pubkey , 201.Fn X509_REQ_get_pubkey , 202and 203.Fn X509_REQ_set_pubkey , 204the reason can be determined with 205.Xr ERR_get_error 3 . 206.Sh ERRORS 207.Fn X509_get_pubkey , 208.Fn X509_get0_pubkey , 209.Fn X509_REQ_get_pubkey , 210.Fn X509_extract_key , 211and 212.Fn X509_REQ_extract_key 213provide diagnostics as documented for 214.Xr X509_PUBKEY_get 3 . 215If 216.Fa x 217or 218.Fa req 219is 220.Dv NULL 221or contains no certificate information, 222they fail without pushing an error onto the stack. 223.Pp 224.Fn X509_get_X509_PUBKEY 225provides no diagnostics and crashes by accessing a 226.Dv NULL 227pointer if 228.Fa x 229is 230.Dv NULL 231or contains no certificate information, 232.Pp 233.Fn X509_get0_pubkey_bitstr 234provides no diagnostics 235and fails without pushing an error onto the stack if 236.Fa x 237is 238.Dv NULL , 239but it crashes by accessing a 240.Dv NULL 241pointer if 242.Fa x 243contains no certificate information. 244.Sh SEE ALSO 245.Xr d2i_X509 3 , 246.Xr X509_CRL_get0_by_serial 3 , 247.Xr X509_NAME_add_entry_by_txt 3 , 248.Xr X509_NAME_ENTRY_get_object 3 , 249.Xr X509_NAME_get_index_by_NID 3 , 250.Xr X509_NAME_print_ex 3 , 251.Xr X509_new 3 , 252.Xr X509_PUBKEY_new 3 , 253.Xr X509_REQ_new 3 , 254.Xr X509_sign 3 , 255.Xr X509_verify_cert 3 , 256.Xr X509V3_get_d2i 3 257.Sh STANDARDS 258RFC 5280, Internet X.509 Public Key Infrastructure Certificate 259and Certificate Revocation List (CRL) Profile, 260section 4.1 Basic Certificate Fields 261.Pp 262RFC 2986: PKCS #10: Certification Request Syntax Specification, 263section 4.1 CertificationRequestInfo 264.Sh HISTORY 265.Fn X509_extract_key 266and 267.Fn X509_REQ_extract_key 268first appeared in SSLeay 0.5.1 but returned a pointer to an 269.Vt RSA 270object before SSLeay 0.6.0. 271.Fn X509_get_pubkey , 272.Fn X509_set_pubkey , 273.Fn X509_REQ_get_pubkey , 274and 275.Fn X509_REQ_set_pubkey 276first appeared in SSLeay 0.6.5. 277.Fn X509_get_X509_PUBKEY 278first appeared in SSLeay 0.8.0. 279These functions have been available since 280.Ox 2.4 . 281.Pp 282.Fn X509_get0_pubkey_bitstr 283first appeared in OpenSSL 0.9.7 and has been available since 284.Ox 3.4 . 285.Pp 286.Fn X509_get0_pubkey 287first appeared in OpenSSL 1.1.0 and has been available since 288.Ox 6.3 . 289