1.\" $OpenBSD: PEM_read.3,v 1.12 2020/07/23 17:34:53 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: July 23 2020 $ 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 "ocnst 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 *u" 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 *u" 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 *u" 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 sucessfully 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. 292.Fn PEM_def_callback 293silently truncates the NUL-terminated byte string 294.Fa u 295to at most 296.Fa num 297bytes and copies it into 298.Fa password 299without a terminating NUL byte. 300If 301.Fa u 302is 303.Dv NULL , 304.Fn PEM_def_callback 305instead prompts the user for the password with echoing turned off 306by calling 307.Xr EVP_read_pw_string_min 3 308internally. 309In this case, the 310.Fa size 311is silently reduced to at most 312.Dv BUFSIZ 313and at most 314.Fa size No \- 1 315bytes are accepted from the user and copied into the byte string buffer 316.Fa password . 317A callback function 318.Fa cb 319supplied by the application may use 320.Fa u 321for a different purpose than 322.Fn PEM_def_callback 323does, e.g., as auxiliary data to use while acquiring the password. 324For example, a GUI application might pass a window handle. 325If the 326.Fa verify 327flag is non-zero, the user is prompted twice for the password to 328make typos less likely and it is checked that both inputs agree. 329This flag is not set by 330.Fn PEM_do_header 331nor by other read functions. 332.Pp 333If the data is a priori known to not be encrypted, then neither 334.Fn PEM_get_EVP_CIPHER_INFO 335nor 336.Fn PEM_do_header 337need to be called. 338.Sh RETURN VALUES 339.Fn PEM_read 340and 341.Fn PEM_read_bio 342return 1 on success or 0 on failure. 343The latter includes the case when no more PEM objects remain in the 344input file. 345To distinguish end of file from more serious errors, the caller 346must peek at the error stack and check for 347.Dv PEM_R_NO_START_LINE , 348which indicates that no more PEM objects were found. 349See 350.Xr ERR_peek_last_error 3 351and 352.Xr ERR_GET_REASON 3 . 353.Pp 354.Fn PEM_get_EVP_CIPHER_INFO 355and 356.Fn PEM_do_header 357return 1 on success or 0 on failure. 358The 359.Fa data 360is likely meaningless if these functions fail. 361.Pp 362.Fn PEM_def_callback 363returns the number of bytes stored into 364.Fa buf 365or a negative value on failure, and 366.Fa cb 367is expected to behave in the same way. 368If 369.Fa u 370is 371.Dv NULL , 372.Fn PEM_def_callback 373fails if 374.Fa num 375is less than 5 376or if an error occurs trying to prompt the user for the password. 377Otherwise, it fails when 378.Fa num 379is negative. 380The details of the circumstances that cause 381.Fa cb 382to fail may differ. 383.Sh SEE ALSO 384.Xr crypto 3 , 385.Xr d2i_PKCS8PrivateKey_bio 3 , 386.Xr PEM_ASN1_read 3 , 387.Xr PEM_bytes_read_bio 3 , 388.Xr PEM_read_bio_PrivateKey 3 , 389.Xr PEM_read_SSL_SESSION 3 , 390.Xr PEM_write_bio_CMS_stream 3 , 391.Xr PEM_write_bio_PKCS7_stream 3 , 392.Xr PEM_X509_INFO_read 3 393.Sh HISTORY 394.Fn PEM_write , 395.Fn PEM_read , 396and 397.Fn PEM_do_header 398appeared in SSLeay 0.4 or earlier. 399.Fn PEM_get_EVP_CIPHER_INFO 400first appeared in SSLeay 0.5.1. 401.Fn PEM_write_bio 402and 403.Fn PEM_read_bio 404first appeared in SSLeay 0.6.0. 405These functions have been available since 406.Ox 2.4 . 407.Pp 408.Fn PEM_def_callback 409first appeared in OpenSSL 0.9.7 and has been available since 410.Ox 3.2 . 411