1.\" $OpenBSD: PEM_read.3,v 1.15 2023/09/18 15:26:46 schwarze Exp $ 2.\" full merge up to: OpenSSL 83cf7abf May 29 13:07:08 2018 +0100 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2020 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 Viktor Dukhovni 22.\" and by Rich Salz <rsalz@openssl.org>. 23.\" Copyright (c) 2016 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: September 18 2023 $ 70.Dt PEM_READ 3 71.Os 72.Sh NAME 73.Nm PEM_write , 74.Nm PEM_write_bio , 75.Nm PEM_read , 76.Nm PEM_read_bio , 77.Nm PEM_get_EVP_CIPHER_INFO , 78.Nm PEM_do_header , 79.Nm PEM_def_callback , 80.Nm pem_password_cb 81.Nd PEM encoding routines 82.Sh SYNOPSIS 83.In openssl/pem.h 84.Ft int 85.Fo PEM_write 86.Fa "FILE *fp" 87.Fa "const char *name" 88.Fa "const char *header" 89.Fa "const unsigned char *data" 90.Fa "long len" 91.Fc 92.Ft int 93.Fo PEM_write_bio 94.Fa "BIO *bp" 95.Fa "const char *name" 96.Fa "const char *header" 97.Fa "const unsigned char *data" 98.Fa "long len" 99.Fc 100.Ft int 101.Fo PEM_read 102.Fa "FILE *fp" 103.Fa "char **name" 104.Fa "char **header" 105.Fa "unsigned char **data" 106.Fa "long *len" 107.Fc 108.Ft int 109.Fo PEM_read_bio 110.Fa "BIO *bp" 111.Fa "char **name" 112.Fa "char **header" 113.Fa "unsigned char **data" 114.Fa "long *len" 115.Fc 116.Ft int 117.Fo PEM_get_EVP_CIPHER_INFO 118.Fa "char *header" 119.Fa "EVP_CIPHER_INFO *cinfo" 120.Fc 121.Ft int 122.Fo PEM_do_header 123.Fa "EVP_CIPHER_INFO *cinfo" 124.Fa "unsigned char *data" 125.Fa "long *len" 126.Fa "pem_password_cb *cb" 127.Fa "void *userdata" 128.Fc 129.Ft int 130.Fo PEM_def_callback 131.Fa "char *password" 132.Fa "int size" 133.Fa "int verify" 134.Fa "void *userdata" 135.Fc 136.Ft typedef int 137.Fo pem_password_cb 138.Fa "char *password" 139.Fa "int size" 140.Fa "int verify" 141.Fa "void *userdata" 142.Fc 143.Sh DESCRIPTION 144These functions read and write PEM-encoded objects, using the PEM type 145.Fa name , 146any additional 147.Fa header 148information, and the raw 149.Fa data 150of length 151.Fa len . 152.Pp 153PEM is the binary content encoding first defined in IETF RFC 1421. 154The content is a series of base64-encoded lines, surrounded by 155begin/end markers each on their own line. 156For example: 157.Bd -literal -offset indent 158-----BEGIN PRIVATE KEY----- 159MIICdg.... 160\&... bhTQ== 161-----END PRIVATE KEY----- 162.Ed 163.Pp 164Optional header line(s) may appear after the begin line, and their 165existence depends on the type of object being written or read. 166.Pp 167.Fn PEM_write 168writes to the file 169.Fa fp , 170while 171.Fn PEM_write_bio 172writes to the BIO 173.Fa bp . 174The 175.Fa name 176is the name to use in the marker, the 177.Fa header 178is the header value or 179.Dv NULL , 180and 181.Fa data 182and 183.Fa len 184specify the data and its length. 185.Pp 186The final 187.Fa data 188buffer is typically an ASN.1 object which can be decoded with the 189.Fn d2i_* 190function appropriate to the type 191.Fa name ; 192see 193.Xr d2i_X509 3 194for examples. 195.Pp 196.Fn PEM_read 197reads from the file 198.Fa fp , 199while 200.Fn PEM_read_bio 201reads from the BIO 202.Fa bp . 203Both skip any non-PEM data that precedes the start of the next PEM 204object. 205When an object is successfully retrieved, the type name from the 206"----BEGIN <type>-----" is returned via the 207.Fa name 208argument, any encapsulation headers are returned in 209.Fa header , 210and the base64-decoded content and its length are returned via 211.Fa data 212and 213.Fa len , 214respectively. 215The 216.Fa name , 217.Fa header , 218and 219.Fa data 220pointers should be freed by the caller when no longer needed. 221.Pp 222The remaining functions are deprecated because the underlying PEM 223encryption format is obsolete and should be avoided. 224It uses an encryption format with an OpenSSL-specific key-derivation 225function, which employs MD5 with an iteration count of 1. 226Instead, private keys should be stored in PKCS#8 form, with a strong 227PKCS#5 v2.0 PBE; see 228.Xr PEM_write_PrivateKey 3 229and 230.Xr d2i_PKCS8PrivateKey_bio 3 . 231.Pp 232.Fn PEM_get_EVP_CIPHER_INFO 233can be used to determine the 234.Fa data 235returned by 236.Fn PEM_read 237or 238.Fn PEM_read_bio 239is encrypted and to retrieve the associated cipher and IV. 240The caller passes a pointer to a structure of type 241.Vt EVP_CIPHER_INFO 242via the 243.Fa cinfo 244argument and the 245.Fa header 246returned via 247.Fn PEM_read 248or 249.Fn PEM_read_bio . 250If the call is successful, 1 is returned and the cipher and IV are 251stored at the address pointed to by 252.Fa cinfo . 253When the header is malformed or not supported or when the cipher is 254unknown or some internal error happens, 0 is returned. 255.Pp 256.Fn PEM_do_header 257can then be used to decrypt the data if the header indicates encryption. 258The 259.Fa cinfo 260argument is a pointer to the structure initialized by a preceding call 261to 262.Fn PEM_get_EVP_CIPHER_INFO . 263If that structure indicates the absence of encryption, 264.Fn PEM_do_header 265returns successfully without taking any action. 266The 267.Fa data 268and 269.Fa len 270arguments are used both to pass in the encrypted data that was 271returned in the same arguments from the preceding call to 272.Fn PEM_read 273or 274.Fn PEM_read_bio 275and to pass out the decrypted data. 276.Pp 277The callback function 278.Fa cb 279is used to obtain the encryption 280.Fa password ; 281if 282.Fa cb 283is 284.Dv NULL , 285.Fn PEM_def_callback 286is used instead. 287The 288.Fa password 289buffer needs to be at least 290.Fa size 291bytes long. 292Unless 293.Fa userdata 294is 295.Dv NULL , 296.Fn PEM_def_callback 297ignores the 298.Fa verify 299argument and copies the NUL-terminated byte string 300.Fa userdata 301to 302.Fa password 303without a terminating NUL byte, silently truncating the copy to at most 304.Fa size 305bytes. 306If 307.Fa userdata 308is 309.Dv NULL , 310.Fn PEM_def_callback 311instead prompts the user for the password with echoing turned off 312by calling 313.Xr EVP_read_pw_string_min 3 314internally. 315In this case, the 316.Fa size 317is silently reduced to at most 318.Dv BUFSIZ 319and at most 320.Fa size No \- 1 321bytes are accepted from the user and copied into the byte string buffer 322.Fa password . 323A callback function 324.Fa cb 325supplied by the application may use 326.Fa userdata 327for a different purpose than 328.Fn PEM_def_callback 329does, e.g., as auxiliary data to use while acquiring the password. 330For example, a GUI application might pass a window handle. 331If the 332.Fa verify 333flag is non-zero, the user is prompted twice for the password to 334make typos less likely and it is checked that both inputs agree. 335This flag is not set by 336.Fn PEM_do_header 337nor by other read functions, but it is typically set by write functions. 338.Pp 339If the data is a priori known to not be encrypted, then neither 340.Fn PEM_get_EVP_CIPHER_INFO 341nor 342.Fn PEM_do_header 343need to be called. 344.Sh RETURN VALUES 345.Fn PEM_read 346and 347.Fn PEM_read_bio 348return 1 on success or 0 on failure. 349The latter includes the case when no more PEM objects remain in the 350input file. 351To distinguish end of file from more serious errors, the caller 352must peek at the error stack and check for 353.Dv PEM_R_NO_START_LINE , 354which indicates that no more PEM objects were found. 355See 356.Xr ERR_peek_last_error 3 357and 358.Xr ERR_GET_REASON 3 . 359.Pp 360.Fn PEM_get_EVP_CIPHER_INFO 361and 362.Fn PEM_do_header 363return 1 on success or 0 on failure. 364The 365.Fa data 366is likely meaningless if these functions fail. 367.Pp 368.Fn PEM_def_callback 369returns the number of bytes stored into 370.Fa buf 371or a negative value on failure, and 372.Fa cb 373is expected to behave in the same way. 374If 375.Fa userdata 376is 377.Dv NULL , 378.Fn PEM_def_callback 379fails if 380.Fa num 381is less than 5 382or if an error occurs trying to prompt the user for the password. 383Otherwise, it fails when 384.Fa num 385is negative. 386The details of the circumstances that cause 387.Fa cb 388to fail may differ. 389.Sh SEE ALSO 390.Xr crypto 3 , 391.Xr d2i_PKCS8PrivateKey_bio 3 , 392.Xr PEM_ASN1_read 3 , 393.Xr PEM_bytes_read_bio 3 , 394.Xr PEM_read_bio_PrivateKey 3 , 395.Xr PEM_read_SSL_SESSION 3 , 396.Xr PEM_write_bio_CMS_stream 3 , 397.Xr PEM_write_bio_PKCS7_stream 3 , 398.Xr PEM_X509_INFO_read 3 399.Sh HISTORY 400.Fn PEM_write , 401.Fn PEM_read , 402and 403.Fn PEM_do_header 404appeared in SSLeay 0.4 or earlier. 405.Fn PEM_get_EVP_CIPHER_INFO 406first appeared in SSLeay 0.5.1. 407.Fn PEM_write_bio 408and 409.Fn PEM_read_bio 410first appeared in SSLeay 0.6.0. 411These functions have been available since 412.Ox 2.4 . 413.Pp 414.Fn PEM_def_callback 415first appeared in OpenSSL 0.9.7 and has been available since 416.Ox 3.2 . 417