1.\" $OpenBSD: d2i_PrivateKey.3,v 1.11 2024/10/24 21:42:10 tb Exp $ 2.\" full merge up to: OpenSSL b0edda11 Mar 20 13:00:17 2018 +0000 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2016, 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 24 2024 $ 69.Dt D2I_PRIVATEKEY 3 70.Os 71.Sh NAME 72.Nm d2i_PrivateKey , 73.Nm d2i_AutoPrivateKey , 74.Nm d2i_PrivateKey_bio , 75.Nm d2i_PrivateKey_fp , 76.Nm i2d_PrivateKey , 77.Nm i2d_PrivateKey_bio , 78.Nm i2d_PrivateKey_fp , 79.Nm i2d_PKCS8PrivateKeyInfo_bio , 80.Nm i2d_PKCS8PrivateKeyInfo_fp , 81.Nm d2i_PublicKey , 82.Nm i2d_PublicKey 83.Nd decode and encode EVP_PKEY objects 84.Sh SYNOPSIS 85.In openssl/evp.h 86.Ft EVP_PKEY * 87.Fo d2i_PrivateKey 88.Fa "int type" 89.Fa "EVP_PKEY **val_out" 90.Fa "const unsigned char **der_in" 91.Fa "long length" 92.Fc 93.Ft EVP_PKEY * 94.Fo d2i_AutoPrivateKey 95.Fa "EVP_PKEY **val_out" 96.Fa "const unsigned char **der_in" 97.Fa "long length" 98.Fc 99.Ft EVP_PKEY * 100.Fo d2i_PrivateKey_bio 101.Fa "BIO *in_bio" 102.Fa "EVP_PKEY **val_out" 103.Fc 104.Ft EVP_PKEY * 105.Fo d2i_PrivateKey_fp 106.Fa "FILE *in_fp" 107.Fa "EVP_PKEY **val_out" 108.Fc 109.Ft int 110.Fo i2d_PrivateKey 111.Fa "EVP_PKEY *val_in" 112.Fa "unsigned char **der_out" 113.Fc 114.Ft int 115.Fo i2d_PrivateKey_bio 116.Fa "BIO *out_bio" 117.Fa "EVP_PKEY *val_in" 118.Fc 119.Ft int 120.Fo i2d_PrivateKey_fp 121.Fa "FILE *out_fp" 122.Fa "EVP_PKEY *val_in" 123.Fc 124.Ft int 125.Fo i2d_PKCS8PrivateKeyInfo_bio 126.Fa "BIO *out_bio" 127.Fa "EVP_PKEY *val_in" 128.Fc 129.Ft int 130.Fo i2d_PKCS8PrivateKeyInfo_fp 131.Fa "FILE *out_fp" 132.Fa "EVP_PKEY *val_in" 133.Fc 134.Ft EVP_PKEY * 135.Fo d2i_PublicKey 136.Fa "int type" 137.Fa "EVP_PKEY **val_out" 138.Fa "const unsigned char **der_in" 139.Fa "long length" 140.Fc 141.Ft int 142.Fo i2d_PublicKey 143.Fa "EVP_PKEY *val_in" 144.Fa "unsigned char **der_out" 145.Fc 146.Sh DESCRIPTION 147These are algorithm-independent interfaces to decode and encode 148private and public keys. 149For details about the semantics, examples, caveats, and bugs, see 150.Xr ASN1_item_d2i 3 . 151.Pp 152.Fn d2i_PrivateKey 153decodes a private key using algorithm 154.Fa type . 155It attempts to use any algorithm specific format or the PKCS#8 unencrypted 156.Vt PrivateKeyInfo 157format defined in RFC 5208 section 5. 158The 159.Fa type 160parameter should be a public key algorithm constant such as 161.Dv EVP_PKEY_RSA . 162An error occurs if the decoded key does not match 163.Fa type . 164.Pp 165.Fn d2i_AutoPrivateKey 166is similar to 167.Fn d2i_PrivateKey 168except that it attempts to automatically detect the algorithm. 169.Pp 170.Fn d2i_PrivateKey_bio 171and 172.Fn d2i_PrivateKey_fp 173are similar to 174.Fn d2i_PrivateKey 175except that they read from a 176.Vt BIO 177or 178.Vt FILE 179pointer. 180.Pp 181.Fn i2d_PrivateKey 182encodes 183.Fa val_in . 184It uses an algorithm specific format or, if none is defined for 185that key type, the PKCS#8 unencrypted 186.Vt PrivateKeyInfo 187format. 188.Pp 189.Fn i2d_PrivateKey_bio 190and 191.Fn i2d_PrivateKey_fp 192are similar to 193.Fn i2d_PrivateKey 194except that they write to a 195.Vt BIO 196or 197.Vt FILE 198pointer and use a different convention for their return values. 199.Pp 200.Fn i2d_PKCS8PrivateKeyInfo_bio 201and 202.Fn i2d_PKCS8PrivateKeyInfo_fp 203encode 204.Fa val_in 205in PKCS#8 unencrypted 206.Vt PrivateKeyInfo 207format. 208They are similar to 209.Fn i2d_PrivateKey 210except that they don't use any algorithm-specific formats 211and that they write to a 212.Vt BIO 213or 214.Vt FILE 215pointer rather than to a buffer. 216.Pp 217All these functions use DER format and unencrypted keys. 218Applications wishing to encrypt or decrypt private keys should use other 219functions such as 220.Xr d2i_PKCS8PrivateKey_bio 3 221instead. 222.Pp 223If 224.Pf * Fa val_out 225is not 226.Dv NULL 227when calling 228.Fn d2i_PrivateKey 229or 230.Fn d2i_AutoPrivateKey 231(i.e. an existing structure is being reused) and the key format is 232PKCS#8, then 233.Pf * Fa val_out 234will be freed and replaced on a successful call. 235.Pp 236.Fn d2i_PublicKey 237calls 238.Xr d2i_DSAPublicKey 3 , 239.Xr o2i_ECPublicKey 3 , 240or 241.Xr d2i_RSAPublicKey 3 242depending on 243.Fa type 244and stores the result in the returned 245.Vt EVP_PKEY 246object. 247.Pp 248.Fn i2d_PublicKey 249calls 250.Xr i2d_DSAPublicKey 3 , 251.Xr i2o_ECPublicKey 3 , 252or 253.Xr i2d_RSAPublicKey 3 254depending on the algorithm used by 255.Fa val_in . 256.Sh RETURN VALUES 257.Fn d2i_PrivateKey , 258.Fn d2i_AutoPrivateKey , 259.Fn d2i_PrivateKey_bio , 260.Fn d2i_PrivateKey_fp , 261and 262.Fn d2i_PublicKey 263return a valid 264.Vt EVP_PKEY 265structure or 266.Dv NULL 267if an error occurs. 268.Pp 269.Fn i2d_PrivateKey 270and 271.Fn i2d_PublicKey 272return the number of bytes successfully encoded or a negative value if 273an error occurs. 274.Pp 275.Fn i2d_PrivateKey_bio , 276.Fn i2d_PrivateKey_fp , 277.Fn i2d_PKCS8PrivateKeyInfo_bio , 278and 279.Fn i2d_PKCS8PrivateKeyInfo_fp 280return 1 for success or 0 if an error occurs. 281.Pp 282For all functions, the error code can be obtained by calling 283.Xr ERR_get_error 3 . 284.Sh SEE ALSO 285.Xr d2i_PKCS8_PRIV_KEY_INFO 3 , 286.Xr d2i_PKCS8PrivateKey_bio 3 , 287.Xr EVP_PKEY_new 3 , 288.Xr EVP_PKEY_type 3 , 289.Xr PEM_write_PrivateKey 3 , 290.Xr PKCS8_PRIV_KEY_INFO_new 3 291.Sh STANDARDS 292RFC 5208: Public-Key Cryptography Standards (PKCS) #8: Private-Key 293Information Syntax Specification 294.Sh HISTORY 295.Fn d2i_PrivateKey , 296.Fn i2d_PrivateKey , 297.Fn d2i_PublicKey , 298and 299.Fn i2d_PublicKey 300first appeared in SSLeay 0.6.0 and have been available since 301.Ox 2.4 . 302.Pp 303.Fn d2i_AutoPrivateKey , 304.Fn d2i_PrivateKey_bio , 305.Fn d2i_PrivateKey_fp , 306.Fn i2d_PrivateKey_bio , 307.Fn i2d_PrivateKey_fp , 308.Fn i2d_PKCS8PrivateKeyInfo_bio , 309and 310.Fn i2d_PKCS8PrivateKeyInfo_fp 311first appeared in OpenSSL 0.9.5 and have been available since 312.Ox 2.7 . 313