1.\" $OpenBSD: X509_PUBKEY_new.3,v 1.17 2021/10/26 10:01:23 schwarze Exp $ 2.\" full 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) 2016 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: October 26 2021 $ 69.Dt X509_PUBKEY_NEW 3 70.Os 71.Sh NAME 72.Nm X509_PUBKEY_new , 73.Nm X509_PUBKEY_free , 74.Nm X509_PUBKEY_set , 75.Nm X509_PUBKEY_get0 , 76.Nm X509_PUBKEY_get , 77.Nm d2i_X509_PUBKEY , 78.Nm i2d_X509_PUBKEY , 79.Nm d2i_PUBKEY , 80.Nm i2d_PUBKEY , 81.Nm d2i_PUBKEY_bio , 82.Nm d2i_PUBKEY_fp , 83.Nm i2d_PUBKEY_fp , 84.Nm i2d_PUBKEY_bio , 85.Nm X509_PUBKEY_set0_param , 86.Nm X509_PUBKEY_get0_param 87.Nd X.509 SubjectPublicKeyInfo structure 88.Sh SYNOPSIS 89.In openssl/x509.h 90.Ft X509_PUBKEY * 91.Fn X509_PUBKEY_new void 92.Ft void 93.Fo X509_PUBKEY_free 94.Fa "X509_PUBKEY *a" 95.Fc 96.Ft int 97.Fo X509_PUBKEY_set 98.Fa "X509_PUBKEY **x" 99.Fa "EVP_PKEY *pkey" 100.Fc 101.Ft EVP_PKEY * 102.Fo X509_PUBKEY_get0 103.Fa "X509_PUBKEY *key" 104.Fc 105.Ft EVP_PKEY * 106.Fo X509_PUBKEY_get 107.Fa "X509_PUBKEY *key" 108.Fc 109.Ft X509_PUBKEY * 110.Fo d2i_X509_PUBKEY 111.Fa "X509_PUBKEY **val_out" 112.Fa "const unsigned char **der_in" 113.Fa "long length" 114.Fc 115.Ft int 116.Fo i2d_X509_PUBKEY 117.Fa "X509_PUBKEY *val_in" 118.Fa "unsigned char **der_out" 119.Fc 120.Ft EVP_PKEY * 121.Fo d2i_PUBKEY 122.Fa "EVP_PKEY **val_out" 123.Fa "const unsigned char **der_in" 124.Fa "long length" 125.Fc 126.Ft int 127.Fo i2d_PUBKEY 128.Fa "EVP_PKEY *val_in" 129.Fa "unsigned char **der_out" 130.Fc 131.Ft EVP_PKEY * 132.Fo d2i_PUBKEY_bio 133.Fa "BIO *bp" 134.Fa "EVP_PKEY **val_out" 135.Fc 136.Ft EVP_PKEY * 137.Fo d2i_PUBKEY_fp 138.Fa "FILE *fp" 139.Fa "EVP_PKEY **val_out" 140.Fc 141.Ft int 142.Fo i2d_PUBKEY_fp 143.Fa "FILE *fp" 144.Fa "EVP_PKEY *val_in" 145.Fc 146.Ft int 147.Fo i2d_PUBKEY_bio 148.Fa "BIO *bp" 149.Fa "EVP_PKEY *val_in" 150.Fc 151.Ft int 152.Fo X509_PUBKEY_set0_param 153.Fa "X509_PUBKEY *pub" 154.Fa "ASN1_OBJECT *aobj" 155.Fa "int ptype" 156.Fa "void *pval" 157.Fa "unsigned char *penc" 158.Fa "int penclen" 159.Fc 160.Ft int 161.Fo X509_PUBKEY_get0_param 162.Fa "ASN1_OBJECT **ppkalg" 163.Fa "const unsigned char **pk" 164.Fa "int *ppklen" 165.Fa "X509_ALGOR **pa" 166.Fa "X509_PUBKEY *pub" 167.Fc 168.Sh DESCRIPTION 169The 170.Vt X509_PUBKEY 171structure represents the ASN.1 172.Vt SubjectPublicKeyInfo 173structure defined in RFC 5280 section 4.1 and used in certificates 174and certificate requests. 175.Pp 176.Fn X509_PUBKEY_new 177allocates and initializes an 178.Vt X509_PUBKEY 179structure. 180.Pp 181.Fn X509_PUBKEY_free 182frees up the 183.Vt X509_PUBKEY 184structure 185.Fa a . 186If 187.Fa a 188is a 189.Dv NULL 190pointer, no action occurs. 191.Pp 192.Fn X509_PUBKEY_set 193sets the public key in 194.Pf * Fa x 195to the public key contained in the 196.Vt EVP_PKEY 197structure 198.Fa pkey . 199If 200.Pf * Fa x 201is not 202.Dv NULL , 203any existing public key structure will be freed. 204.Pp 205.Fn X509_PUBKEY_get0 206returns the public key contained in 207.Fa key . 208The returned value is an internal pointer which must not be freed after use. 209.Pp 210.Fn X509_PUBKEY_get 211is similar to 212.Fn X509_PUBKEY_get0 213except that the reference 214count on the returned key is incremented so it must be freed using 215.Xr EVP_PKEY_free 3 216after use. 217.Pp 218.Fn d2i_X509_PUBKEY , 219.Fn i2d_X509_PUBKEY , 220.Fn d2i_PUBKEY , 221and 222.Fn i2d_PUBKEY 223decode and encode an ASN.1 224.Vt SubjectPublicKeyInfo 225structure using either the 226.Vt X509_PUBKEY 227or the 228.Vt EVP_PKEY 229object type, respectively. 230For details about the semantics, examples, caveats, and bugs, see 231.Xr ASN1_item_d2i 3 . 232.Fn d2i_PUBKEY_bio , 233.Fn d2i_PUBKEY_fp , 234.Fn i2d_PUBKEY_bio 235and 236.Fn i2d_PUBKEY_fp 237are similar to 238.Fn d2i_PUBKEY 239and 240.Fn i2d_PUBKEY 241except they decode or encode using a 242.Vt BIO 243or 244.Vt FILE 245pointer. 246.Pp 247.Fn X509_PUBKEY_set0_param 248sets the public key parameters of 249.Fa pub . 250The OID associated with the algorithm is set to 251.Fa aobj . 252The type of the algorithm parameters is set to 253.Fa ptype 254using the structure 255.Fa pval . 256The encoding of the public key itself is set to the 257.Fa penclen 258bytes contained in buffer 259.Fa penc . 260On success ownership of all the supplied parameters is passed to 261.Fa pub 262so they must not be freed after the call. 263.Pp 264.Fn X509_PUBKEY_get0_param 265retrieves the public key parameters from 266.Fa pub , 267.Pf * Fa ppkalg 268is set to the associated OID and the encoding consists of 269.Pf * Fa ppklen 270bytes at 271.Pf * Fa pk , 272and 273.Pf * Fa pa 274is set to the associated 275.Vt AlgorithmIdentifier 276for the public key. 277If the value of any of these parameters is not required, 278it can be set to 279.Dv NULL . 280All of the retrieved pointers are internal and must not be freed after 281the call. 282.Sh RETURN VALUES 283If the allocation fails, 284.Fn X509_PUBKEY_new 285returns 286.Dv NULL 287and sets an error code that can be obtained by 288.Xr ERR_get_error 3 . 289Otherwise it returns a pointer to the newly allocated structure. 290.Pp 291.Fn X509_PUBKEY_get0 292returns an internal pointer or 293.Dv NULL 294if an error occurs. 295.Pp 296.Fn X509_PUBKEY_get 297returns a pointer to an object that had its reference count incremented or 298.Dv NULL 299if an error occurs. 300.Pp 301.Fn d2i_X509_PUBKEY , 302.Fn d2i_PUBKEY , 303.Fn d2i_PUBKEY_bio , 304and 305.Fn d2i_PUBKEY_fp 306return a pointer to a valid object or 307.Dv NULL 308if an error occurs. 309.Pp 310.Fn i2d_X509_PUBKEY 311and 312.Fn i2d_PUBKEY 313return the number of bytes successfully encoded or a negative value 314if an error occurs. 315.Pp 316.Fn X509_PUBKEY_set , 317.Fn X509_PUBKEY_set0_param , 318.Fn X509_PUBKEY_get0_param , 319.Fn i2d_PUBKEY_fp , 320and 321.Fn i2d_PUBKEY_bio 322return 1 for success and 0 if an error occurred. 323.Sh ERRORS 324After failure of 325.Fn X509_PUBKEY_get0 326or 327.Fn X509_PUBKEY_get , 328one of the following diagnostics can be retrieved with 329.Xr ERR_get_error 3 , 330.Xr ERR_GET_REASON 3 , 331and 332.Xr ERR_reason_error_string 3 : 333.Bl -tag -width Ds 334.It Dv X509_R_UNSUPPORTED_ALGORITHM Qq "unsupported algorithm" 335The public key uses an algorithm unsupported by 336.Xr EVP_PKEY_set_type 3 . 337.It X509_R_METHOD_NOT_SUPPORTED Qq "method not supported" 338While the algorithm is known to 339.Xr EVP_PKEY_set_type 3 , 340using it for decoding is not supported. 341.It X509_R_PUBLIC_KEY_DECODE_ERROR Qq "public key decode error" 342Decoding the public key failed. 343.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure" 344Memory was exhausted when trying to allocate the new 345.Vt EVP_PKEY 346object. 347.El 348.Pp 349If 350.Fa key 351is 352.Dv NULL 353or does not contain a public key, 354these functions fail but no error is pushed onto the stack. 355.Sh SEE ALSO 356.Xr d2i_X509 3 , 357.Xr EVP_PKEY_asn1_set_public 3 , 358.Xr X509_ALGOR_new 3 , 359.Xr X509_get_pubkey 3 , 360.Xr X509_new 3 361.Sh STANDARDS 362RFC 5280: Internet X.509 Public Key Infrastructure Certificate and 363Certificate Revocation List (CRL) Profile 364.Sh HISTORY 365.Fn X509_PUBKEY_new 366and 367.Fn X509_PUBKEY_free 368appeared in SSLeay 0.4 or earlier. 369.Fn d2i_X509_PUBKEY 370and 371.Fn i2d_X509_PUBKEY 372first appeared in SSLeay 0.5.1. 373.Fn X509_PUBKEY_set 374and 375.Fn X509_PUBKEY_get 376first appeared in SSLeay 0.8.0. 377These functions have been available since 378.Ox 2.4 . 379.Pp 380.Fn d2i_PUBKEY 381and 382.Fn i2d_PUBKEY 383first appeared in OpenSSL 0.9.5 and have been available since 384.Ox 2.7 . 385.Pp 386.Fn d2i_PUBKEY_bio , 387.Fn d2i_PUBKEY_fp , 388.Fn i2d_PUBKEY_fp , 389and 390.Fn i2d_PUBKEY_bio 391first appeared in OpenSSL 0.9.6 and have been available since 392.Ox 2.9 . 393.Pp 394.Fn X509_PUBKEY_set0_param 395and 396.Fn X509_PUBKEY_get0_param 397first appeared in OpenSSL 1.0.0 and have been available since 398.Ox 4.9 . 399.Pp 400.Fn X509_PUBKEY_get0 401first appeared in OpenSSL 1.1.0 and has been available since 402.Ox 6.3 . 403