1.\" $OpenBSD: PEM_read_bio_PrivateKey.3,v 1.21 2023/04/25 18:57:57 tb Exp $ 2.\" full merge up to: 3.\" OpenSSL man3/PEM_read_bio_PrivateKey.pod 18bad535 Apr 9 15:13:55 2019 +0100 4.\" OpenSSL man3/PEM_read_CMS.pod 83cf7abf May 29 13:07:08 2018 +0100 5.\" 6.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 7.\" Copyright (c) 2001-2004, 2009, 2013-2016 The OpenSSL Project. 8.\" All rights reserved. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 14.\" 1. Redistributions of source code must retain the above copyright 15.\" notice, this list of conditions and the following disclaimer. 16.\" 17.\" 2. Redistributions in binary form must reproduce the above copyright 18.\" notice, this list of conditions and the following disclaimer in 19.\" the documentation and/or other materials provided with the 20.\" distribution. 21.\" 22.\" 3. All advertising materials mentioning features or use of this 23.\" software must display the following acknowledgment: 24.\" "This product includes software developed by the OpenSSL Project 25.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 26.\" 27.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 28.\" endorse or promote products derived from this software without 29.\" prior written permission. For written permission, please contact 30.\" openssl-core@openssl.org. 31.\" 32.\" 5. Products derived from this software may not be called "OpenSSL" 33.\" nor may "OpenSSL" appear in their names without prior written 34.\" permission of the OpenSSL Project. 35.\" 36.\" 6. Redistributions of any form whatsoever must retain the following 37.\" acknowledgment: 38.\" "This product includes software developed by the OpenSSL Project 39.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 40.\" 41.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 42.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 43.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 44.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 45.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 46.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 47.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 48.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 49.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 50.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 51.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 52.\" OF THE POSSIBILITY OF SUCH DAMAGE. 53.\" 54.Dd $Mdocdate: April 25 2023 $ 55.Dt PEM_READ_BIO_PRIVATEKEY 3 56.Os 57.Sh NAME 58.Nm PEM_read_bio_PrivateKey , 59.Nm PEM_read_PrivateKey , 60.Nm PEM_write_bio_PrivateKey , 61.Nm PEM_write_PrivateKey , 62.Nm PEM_write_bio_PKCS8PrivateKey , 63.Nm PEM_write_PKCS8PrivateKey , 64.Nm PEM_write_bio_PKCS8PrivateKey_nid , 65.Nm PEM_write_PKCS8PrivateKey_nid , 66.Nm PEM_read_bio_PKCS8 , 67.Nm PEM_read_PKCS8 , 68.Nm PEM_write_bio_PKCS8 , 69.Nm PEM_write_PKCS8 , 70.Nm PEM_read_bio_PKCS8_PRIV_KEY_INFO , 71.Nm PEM_read_PKCS8_PRIV_KEY_INFO , 72.Nm PEM_write_bio_PKCS8_PRIV_KEY_INFO , 73.Nm PEM_write_PKCS8_PRIV_KEY_INFO , 74.Nm PEM_read_bio_PUBKEY , 75.Nm PEM_read_PUBKEY , 76.Nm PEM_write_bio_PUBKEY , 77.Nm PEM_write_PUBKEY , 78.Nm PEM_read_bio_RSAPrivateKey , 79.Nm PEM_read_RSAPrivateKey , 80.Nm PEM_write_bio_RSAPrivateKey , 81.Nm PEM_write_RSAPrivateKey , 82.Nm PEM_read_bio_RSAPublicKey , 83.Nm PEM_read_RSAPublicKey , 84.Nm PEM_write_bio_RSAPublicKey , 85.Nm PEM_write_RSAPublicKey , 86.Nm PEM_read_bio_RSA_PUBKEY , 87.Nm PEM_read_RSA_PUBKEY , 88.Nm PEM_write_bio_RSA_PUBKEY , 89.Nm PEM_write_RSA_PUBKEY , 90.Nm PEM_read_bio_DSAPrivateKey , 91.Nm PEM_read_DSAPrivateKey , 92.Nm PEM_write_bio_DSAPrivateKey , 93.Nm PEM_write_DSAPrivateKey , 94.Nm PEM_read_bio_DSA_PUBKEY , 95.Nm PEM_read_DSA_PUBKEY , 96.Nm PEM_write_bio_DSA_PUBKEY , 97.Nm PEM_write_DSA_PUBKEY , 98.Nm PEM_read_bio_DSAparams , 99.Nm PEM_read_DSAparams , 100.Nm PEM_write_bio_DSAparams , 101.Nm PEM_write_DSAparams , 102.Nm PEM_read_bio_DHparams , 103.Nm PEM_read_DHparams , 104.Nm PEM_write_bio_DHparams , 105.Nm PEM_write_DHparams , 106.Nm PEM_read_bio_ECPKParameters , 107.Nm PEM_read_ECPKParameters , 108.Nm PEM_write_bio_ECPKParameters , 109.Nm PEM_write_ECPKParameters , 110.Nm PEM_read_bio_ECPrivateKey , 111.Nm PEM_read_ECPrivateKey , 112.Nm PEM_write_bio_ECPrivateKey , 113.Nm PEM_write_ECPrivateKey , 114.Nm PEM_read_bio_EC_PUBKEY , 115.Nm PEM_read_EC_PUBKEY , 116.Nm PEM_write_bio_EC_PUBKEY , 117.Nm PEM_write_EC_PUBKEY , 118.Nm PEM_read_bio_X509 , 119.Nm PEM_read_X509 , 120.Nm PEM_write_bio_X509 , 121.Nm PEM_write_X509 , 122.Nm PEM_read_bio_X509_AUX , 123.Nm PEM_read_X509_AUX , 124.Nm PEM_write_bio_X509_AUX , 125.Nm PEM_write_X509_AUX , 126.Nm PEM_read_bio_X509_REQ , 127.Nm PEM_read_X509_REQ , 128.Nm PEM_write_bio_X509_REQ , 129.Nm PEM_write_X509_REQ , 130.Nm PEM_write_bio_X509_REQ_NEW , 131.Nm PEM_write_X509_REQ_NEW , 132.Nm PEM_read_bio_X509_CRL , 133.Nm PEM_read_X509_CRL , 134.Nm PEM_write_bio_X509_CRL , 135.Nm PEM_write_X509_CRL , 136.Nm PEM_read_bio_PKCS7 , 137.Nm PEM_read_PKCS7 , 138.Nm PEM_write_bio_PKCS7 , 139.Nm PEM_write_PKCS7 , 140.Nm PEM_read_CMS , 141.Nm PEM_read_bio_CMS , 142.Nm PEM_write_CMS , 143.Nm PEM_write_bio_CMS 144.Nd PEM routines 145.Sh SYNOPSIS 146.In openssl/pem.h 147.Ft EVP_PKEY * 148.Fo PEM_read_bio_PrivateKey 149.Fa "BIO *bp" 150.Fa "EVP_PKEY **x" 151.Fa "pem_password_cb *cb" 152.Fa "void *u" 153.Fc 154.Ft EVP_PKEY * 155.Fo PEM_read_PrivateKey 156.Fa "FILE *fp" 157.Fa "EVP_PKEY **x" 158.Fa "pem_password_cb *cb" 159.Fa "void *u" 160.Fc 161.Ft int 162.Fo PEM_write_bio_PrivateKey 163.Fa "BIO *bp" 164.Fa "EVP_PKEY *x" 165.Fa "const EVP_CIPHER *enc" 166.Fa "unsigned char *kstr" 167.Fa "int klen" 168.Fa "pem_password_cb *cb" 169.Fa "void *u" 170.Fc 171.Ft int 172.Fo PEM_write_PrivateKey 173.Fa "FILE *fp" 174.Fa "EVP_PKEY *x" 175.Fa "const EVP_CIPHER *enc" 176.Fa "unsigned char *kstr" 177.Fa "int klen" 178.Fa "pem_password_cb *cb" 179.Fa "void *u" 180.Fc 181.Ft int 182.Fo PEM_write_bio_PKCS8PrivateKey 183.Fa "BIO *bp" 184.Fa "EVP_PKEY *x" 185.Fa "const EVP_CIPHER *enc" 186.Fa "char *kstr" 187.Fa "int klen" 188.Fa "pem_password_cb *cb" 189.Fa "void *u" 190.Fc 191.Ft int 192.Fo PEM_write_PKCS8PrivateKey 193.Fa "FILE *fp" 194.Fa "EVP_PKEY *x" 195.Fa "const EVP_CIPHER *enc" 196.Fa "char *kstr" 197.Fa "int klen" 198.Fa "pem_password_cb *cb" 199.Fa "void *u" 200.Fc 201.Ft int 202.Fo PEM_write_bio_PKCS8PrivateKey_nid 203.Fa "BIO *bp" 204.Fa "EVP_PKEY *x" 205.Fa "int nid" 206.Fa "char *kstr" 207.Fa "int klen" 208.Fa "pem_password_cb *cb" 209.Fa "void *u" 210.Fc 211.Ft int 212.Fo PEM_write_PKCS8PrivateKey_nid 213.Fa "FILE *fp" 214.Fa "EVP_PKEY *x" 215.Fa "int nid" 216.Fa "char *kstr" 217.Fa "int klen" 218.Fa "pem_password_cb *cb" 219.Fa "void *u" 220.Fc 221.Ft X509_SIG * 222.Fo PEM_read_bio_PKCS8 223.Fa "BIO *bp" 224.Fa "X509_SIG **x" 225.Fa "pem_password_cb *cb" 226.Fa "void *u" 227.Fc 228.Ft X509_SIG * 229.Fo PEM_read_PKCS8 230.Fa "FILE *fp" 231.Fa "X509_SIG **x" 232.Fa "pem_password_cb *cb" 233.Fa "void *u" 234.Fc 235.Ft int 236.Fo PEM_write_bio_PKCS8 237.Fa "BIO *bp" 238.Fa "X509_SIG *x" 239.Fc 240.Ft int 241.Fo PEM_write_PKCS8 242.Fa "FILE *fp" 243.Fa "X509_SIG *x" 244.Fc 245.Ft PKCS8_PRIV_KEY_INFO * 246.Fo PEM_read_bio_PKCS8_PRIV_KEY_INFO 247.Fa "BIO *bp" 248.Fa "PKCS8_PRIV_KEY_INFO **x" 249.Fa "pem_password_cb *cb" 250.Fa "void *u" 251.Fc 252.Ft PKCS8_PRIV_KEY_INFO * 253.Fo PEM_read_PKCS8_PRIV_KEY_INFO 254.Fa "FILE *fp" 255.Fa "PKCS8_PRIV_KEY_INFO **x" 256.Fa "pem_password_cb *cb" 257.Fa "void *u" 258.Fc 259.Ft int 260.Fo PEM_write_bio_PKCS8_PRIV_KEY_INFO 261.Fa "BIO *bp" 262.Fa "PKCS8_PRIV_KEY_INFO *x" 263.Fc 264.Ft int 265.Fo PEM_write_PKCS8_PRIV_KEY_INFO 266.Fa "FILE *fp" 267.Fa "PKCS8_PRIV_KEY_INFO *x" 268.Fc 269.Ft EVP_PKEY * 270.Fo PEM_read_bio_PUBKEY 271.Fa "BIO *bp" 272.Fa "EVP_PKEY **x" 273.Fa "pem_password_cb *cb" 274.Fa "void *u" 275.Fc 276.Ft EVP_PKEY * 277.Fo PEM_read_PUBKEY 278.Fa "FILE *fp" 279.Fa "EVP_PKEY **x" 280.Fa "pem_password_cb *cb" 281.Fa "void *u" 282.Fc 283.Ft int 284.Fo PEM_write_bio_PUBKEY 285.Fa "BIO *bp" 286.Fa "EVP_PKEY *x" 287.Fc 288.Ft int 289.Fo PEM_write_PUBKEY 290.Fa "FILE *fp" 291.Fa "EVP_PKEY *x" 292.Fc 293.Ft RSA * 294.Fo PEM_read_bio_RSAPrivateKey 295.Fa "BIO *bp" 296.Fa "RSA **x" 297.Fa "pem_password_cb *cb" 298.Fa "void *u" 299.Fc 300.Ft RSA * 301.Fo PEM_read_RSAPrivateKey 302.Fa "FILE *fp" 303.Fa "RSA **x" 304.Fa "pem_password_cb *cb" 305.Fa "void *u" 306.Fc 307.Ft int 308.Fo PEM_write_bio_RSAPrivateKey 309.Fa "BIO *bp" 310.Fa "RSA *x" 311.Fa "const EVP_CIPHER *enc" 312.Fa "unsigned char *kstr" 313.Fa "int klen" 314.Fa "pem_password_cb *cb" 315.Fa "void *u" 316.Fc 317.Ft int 318.Fo PEM_write_RSAPrivateKey 319.Fa "FILE *fp" 320.Fa "RSA *x" 321.Fa "const EVP_CIPHER *enc" 322.Fa "unsigned char *kstr" 323.Fa "int klen" 324.Fa "pem_password_cb *cb" 325.Fa "void *u" 326.Fc 327.Ft RSA * 328.Fo PEM_read_bio_RSAPublicKey 329.Fa "BIO *bp" 330.Fa "RSA **x" 331.Fa "pem_password_cb *cb" 332.Fa "void *u" 333.Fc 334.Ft RSA * 335.Fo PEM_read_RSAPublicKey 336.Fa "FILE *fp" 337.Fa "RSA **x" 338.Fa "pem_password_cb *cb" 339.Fa "void *u" 340.Fc 341.Ft int 342.Fo PEM_write_bio_RSAPublicKey 343.Fa "BIO *bp" 344.Fa "RSA *x" 345.Fc 346.Ft int 347.Fo PEM_write_RSAPublicKey 348.Fa "FILE *fp" 349.Fa "RSA *x" 350.Fc 351.Ft RSA * 352.Fo PEM_read_bio_RSA_PUBKEY 353.Fa "BIO *bp" 354.Fa "RSA **x" 355.Fa "pem_password_cb *cb" 356.Fa "void *u" 357.Fc 358.Ft RSA * 359.Fo PEM_read_RSA_PUBKEY 360.Fa "FILE *fp" 361.Fa "RSA **x" 362.Fa "pem_password_cb *cb" 363.Fa "void *u" 364.Fc 365.Ft int 366.Fo PEM_write_bio_RSA_PUBKEY 367.Fa "BIO *bp" 368.Fa "RSA *x" 369.Fc 370.Ft int 371.Fo PEM_write_RSA_PUBKEY 372.Fa "FILE *fp" 373.Fa "RSA *x" 374.Fc 375.Ft DSA * 376.Fo PEM_read_bio_DSAPrivateKey 377.Fa "BIO *bp" 378.Fa "DSA **x" 379.Fa "pem_password_cb *cb" 380.Fa "void *u" 381.Fc 382.Ft DSA * 383.Fo PEM_read_DSAPrivateKey 384.Fa "FILE *fp" 385.Fa "DSA **x" 386.Fa "pem_password_cb *cb" 387.Fa "void *u" 388.Fc 389.Ft int 390.Fo PEM_write_bio_DSAPrivateKey 391.Fa "BIO *bp" 392.Fa "DSA *x" 393.Fa "const EVP_CIPHER *enc" 394.Fa "unsigned char *kstr" 395.Fa "int klen" 396.Fa "pem_password_cb *cb" 397.Fa "void *u" 398.Fc 399.Ft int 400.Fo PEM_write_DSAPrivateKey 401.Fa "FILE *fp" 402.Fa "DSA *x" 403.Fa "const EVP_CIPHER *enc" 404.Fa "unsigned char *kstr" 405.Fa "int klen" 406.Fa "pem_password_cb *cb" 407.Fa "void *u" 408.Fc 409.Ft DSA * 410.Fo PEM_read_bio_DSA_PUBKEY 411.Fa "BIO *bp" 412.Fa "DSA **x" 413.Fa "pem_password_cb *cb" 414.Fa "void *u" 415.Fc 416.Ft DSA * 417.Fo PEM_read_DSA_PUBKEY 418.Fa "FILE *fp" 419.Fa "DSA **x" 420.Fa "pem_password_cb *cb" 421.Fa "void *u" 422.Fc 423.Ft int 424.Fo PEM_write_bio_DSA_PUBKEY 425.Fa "BIO *bp" 426.Fa "DSA *x" 427.Fc 428.Ft int 429.Fo PEM_write_DSA_PUBKEY 430.Fa "FILE *fp" 431.Fa "DSA *x" 432.Fc 433.Ft DSA * 434.Fo PEM_read_bio_DSAparams 435.Fa "BIO *bp" 436.Fa "DSA **x" 437.Fa "pem_password_cb *cb" 438.Fa "void *u" 439.Fc 440.Ft DSA * 441.Fo PEM_read_DSAparams 442.Fa "FILE *fp" 443.Fa "DSA **x" 444.Fa "pem_password_cb *cb" 445.Fa "void *u" 446.Fc 447.Ft int 448.Fo PEM_write_bio_DSAparams 449.Fa "BIO *bp" 450.Fa "DSA *x" 451.Fc 452.Ft int 453.Fo PEM_write_DSAparams 454.Fa "FILE *fp" 455.Fa "DSA *x" 456.Fc 457.Ft DH * 458.Fo PEM_read_bio_DHparams 459.Fa "BIO *bp" 460.Fa "DH **x" 461.Fa "pem_password_cb *cb" 462.Fa "void *u" 463.Fc 464.Ft DH * 465.Fo PEM_read_DHparams 466.Fa "FILE *fp" 467.Fa "DH **x" 468.Fa "pem_password_cb *cb" 469.Fa "void *u" 470.Fc 471.Ft int 472.Fo PEM_write_bio_DHparams 473.Fa "BIO *bp" 474.Fa "DH *x" 475.Fc 476.Ft int 477.Fo PEM_write_DHparams 478.Fa "FILE *fp" 479.Fa "DH *x" 480.Fc 481.Ft EC_GROUP * 482.Fo PEM_read_bio_ECPKParameters 483.Fa "BIO *bp" 484.Fa "EC_GROUP **x" 485.Fa "pem_password_cb *cb" 486.Fa "void *u" 487.Fc 488.Ft EC_GROUP * 489.Fo PEM_read_ECPKParameters 490.Fa "FILE *fp" 491.Fa "EC_GROUP **x" 492.Fa "pem_password_cb *cb" 493.Fa "void *u" 494.Fc 495.Ft int 496.Fo PEM_write_bio_ECPKParameters 497.Fa "BIO *bp" 498.Fa "const EC_GROUP *x" 499.Fc 500.Ft int 501.Fo PEM_write_ECPKParameters 502.Fa "FILE *fp" 503.Fa "const EC_GROUP *x" 504.Fc 505.Ft EC_KEY * 506.Fo PEM_read_bio_ECPrivateKey 507.Fa "BIO *bp" 508.Fa "EC_KEY **key" 509.Fa "pem_password_cb *cb" 510.Fa "void *u" 511.Fc 512.Ft EC_KEY * 513.Fo PEM_read_ECPrivateKey 514.Fa "FILE *fp" 515.Fa "EC_KEY **eckey" 516.Fa "pem_password_cb *cb" 517.Fa "void *u" 518.Fc 519.Ft int 520.Fo PEM_write_bio_ECPrivateKey 521.Fa "BIO *bp" 522.Fa "EC_KEY *x" 523.Fa "const EVP_CIPHER *enc" 524.Fa "unsigned char *kstr" 525.Fa "int klen" 526.Fa "pem_password_cb *cb" 527.Fa "void *u" 528.Fc 529.Ft int 530.Fo PEM_write_ECPrivateKey 531.Fa "FILE *fp" 532.Fa "EC_KEY *x" 533.Fa "const EVP_CIPHER *enc" 534.Fa "unsigned char *kstr" 535.Fa "int klen" 536.Fa "pem_password_cb *cb" 537.Fa "void *u" 538.Fc 539.Ft EC_KEY * 540.Fo PEM_read_bio_EC_PUBKEY 541.Fa "BIO *bp" 542.Fa "EC_KEY **x" 543.Fa "pem_password_cb *cb" 544.Fa "void *u" 545.Fc 546.Ft EC_KEY * 547.Fo PEM_read_EC_PUBKEY 548.Fa "FILE *fp" 549.Fa "EC_KEY **x" 550.Fa "pem_password_cb *cb" 551.Fa "void *u" 552.Fc 553.Ft int 554.Fo PEM_write_bio_EC_PUBKEY 555.Fa "BIO *bp" 556.Fa "EC_KEY *x" 557.Fc 558.Ft int 559.Fo PEM_write_EC_PUBKEY 560.Fa "FILE *fp" 561.Fa "EC_KEY *x" 562.Fc 563.Ft X509 * 564.Fo PEM_read_bio_X509 565.Fa "BIO *bp" 566.Fa "X509 **x" 567.Fa "pem_password_cb *cb" 568.Fa "void *u" 569.Fc 570.Ft X509 * 571.Fo PEM_read_X509 572.Fa "FILE *fp" 573.Fa "X509 **x" 574.Fa "pem_password_cb *cb" 575.Fa "void *u" 576.Fc 577.Ft int 578.Fo PEM_write_bio_X509 579.Fa "BIO *bp" 580.Fa "X509 *x" 581.Fc 582.Ft int 583.Fo PEM_write_X509 584.Fa "FILE *fp" 585.Fa "X509 *x" 586.Fc 587.Ft X509 * 588.Fo PEM_read_bio_X509_AUX 589.Fa "BIO *bp" 590.Fa "X509 **x" 591.Fa "pem_password_cb *cb" 592.Fa "void *u" 593.Fc 594.Ft X509 * 595.Fo PEM_read_X509_AUX 596.Fa "FILE *fp" 597.Fa "X509 **x" 598.Fa "pem_password_cb *cb" 599.Fa "void *u" 600.Fc 601.Ft int 602.Fo PEM_write_bio_X509_AUX 603.Fa "BIO *bp" 604.Fa "X509 *x" 605.Fc 606.Ft int 607.Fo PEM_write_X509_AUX 608.Fa "FILE *fp" 609.Fa "X509 *x" 610.Fc 611.Ft X509_REQ * 612.Fo PEM_read_bio_X509_REQ 613.Fa "BIO *bp" 614.Fa "X509_REQ **x" 615.Fa "pem_password_cb *cb" 616.Fa "void *u" 617.Fc 618.Ft X509_REQ * 619.Fo PEM_read_X509_REQ 620.Fa "FILE *fp" 621.Fa "X509_REQ **x" 622.Fa "pem_password_cb *cb" 623.Fa "void *u" 624.Fc 625.Ft int 626.Fo PEM_write_bio_X509_REQ 627.Fa "BIO *bp" 628.Fa "X509_REQ *x" 629.Fc 630.Ft int 631.Fo PEM_write_X509_REQ 632.Fa "FILE *fp" 633.Fa "X509_REQ *x" 634.Fc 635.Ft int 636.Fo PEM_write_bio_X509_REQ_NEW 637.Fa "BIO *bp" 638.Fa "X509_REQ *x" 639.Fc 640.Ft int 641.Fo PEM_write_X509_REQ_NEW 642.Fa "FILE *fp" 643.Fa "X509_REQ *x" 644.Fc 645.Ft X509_CRL * 646.Fo PEM_read_bio_X509_CRL 647.Fa "BIO *bp" 648.Fa "X509_CRL **x" 649.Fa "pem_password_cb *cb" 650.Fa "void *u" 651.Fc 652.Ft X509_CRL * 653.Fo PEM_read_X509_CRL 654.Fa "FILE *fp" 655.Fa "X509_CRL **x" 656.Fa "pem_password_cb *cb" 657.Fa "void *u" 658.Fc 659.Ft int 660.Fo PEM_write_bio_X509_CRL 661.Fa "BIO *bp" 662.Fa "X509_CRL *x" 663.Fc 664.Ft int 665.Fo PEM_write_X509_CRL 666.Fa "FILE *fp" 667.Fa "X509_CRL *x" 668.Fc 669.Ft PKCS7 * 670.Fo PEM_read_bio_PKCS7 671.Fa "BIO *bp" 672.Fa "PKCS7 **x" 673.Fa "pem_password_cb *cb" 674.Fa "void *u" 675.Fc 676.Ft PKCS7 * 677.Fo PEM_read_PKCS7 678.Fa "FILE *fp" 679.Fa "PKCS7 **x" 680.Fa "pem_password_cb *cb" 681.Fa "void *u" 682.Fc 683.Ft int 684.Fo PEM_write_bio_PKCS7 685.Fa "BIO *bp" 686.Fa "PKCS7 *x" 687.Fc 688.Ft int 689.Fo PEM_write_PKCS7 690.Fa "FILE *fp" 691.Fa "PKCS7 *x" 692.Fc 693.In openssl/cms.h 694.Ft CMS_ContentInfo * 695.Fo PEM_read_CMS 696.Fa "FILE *fp" 697.Fa "CMS_ContentInfo **x" 698.Fa "pem_password_cb *cb" 699.Fa "void *u" 700.Fc 701.Ft CMS_ContentInfo * 702.Fo PEM_read_bio_CMS 703.Fa "BIO *bp" 704.Fa "CMS_ContentInfo **x" 705.Fa "pem_password_cb *cb" 706.Fa "void *u" 707.Fc 708.Ft int 709.Fo PEM_write_CMS 710.Fa "FILE *fp" 711.Fa "const CMS_ContentInfo *x" 712.Fc 713.Ft int 714.Fo PEM_write_bio_CMS 715.Fa "BIO *bp" 716.Fa "const CMS_ContentInfo *x" 717.Fc 718.Sh DESCRIPTION 719The PEM functions read or write structures in PEM format. 720In this sense PEM format is simply base64-encoded data surrounded by 721header lines; see 722.Xr PEM_read 3 723for more details. 724.Pp 725For more details about the meaning of arguments see the 726.Sx PEM function arguments 727section. 728.Pp 729Each operation has four functions associated with it. 730For brevity the term 731.Dq Ar TYPE No functions 732will be used to collectively refer to the 733.Fn PEM_read_bio_TYPE , 734.Fn PEM_read_TYPE , 735.Fn PEM_write_bio_TYPE , 736and 737.Fn PEM_write_TYPE 738functions. 739If no set of specific functions exists for a given type, 740.Xr PEM_ASN1_read 3 741can be used instead. 742.Pp 743The 744.Sy PrivateKey 745functions read or write a private key in PEM format using an 746.Vt EVP_PKEY 747structure. 748The write routines use "traditional" private key format and can handle 749both RSA and DSA private keys. 750The read functions can additionally transparently handle PKCS#8 format 751encrypted and unencrypted keys too. 752.Pp 753.Fn PEM_write_bio_PKCS8PrivateKey 754and 755.Fn PEM_write_PKCS8PrivateKey 756write a private key in an 757.Vt EVP_PKEY 758structure in PKCS#8 759.Vt EncryptedPrivateKeyInfo 760format using PKCS#5 v2.0 password based encryption algorithms. 761The 762.Fa enc 763argument specifies the encryption algorithm to use: unlike all other PEM 764routines, the encryption is applied at the PKCS#8 level and not in the 765PEM headers. 766If 767.Fa enc 768is 769.Dv NULL , 770then no encryption is used and a PKCS#8 771.Vt PrivateKeyInfo 772structure is used instead. 773.Pp 774.Fn PEM_write_bio_PKCS8PrivateKey_nid 775and 776.Fn PEM_write_PKCS8PrivateKey_nid 777also write out a private key as a PKCS#8 778.Vt EncryptedPrivateKeyInfo . 779However they use PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. 780The algorithm to use is specified in the 781.Fa nid 782parameter and should be the NID of the corresponding OBJECT IDENTIFIER. 783.Pp 784The 785.Sy PKCS8 786functions process an encrypted private key using an 787.Vt X509_SIG 788structure and the 789.Xr d2i_X509_SIG 3 790function. 791.Pp 792The 793.Sy PKCS8_PRIV_KEY_INFO 794functions process a private key using a 795.Vt PKCS8_PRIV_KEY_INFO 796structure. 797.Pp 798The 799.Sy PUBKEY 800functions process a public key using an 801.Vt EVP_PKEY 802structure. 803The public key is encoded as an ASN.1 804.Vt SubjectPublicKeyInfo 805structure. 806.Pp 807The 808.Sy RSAPrivateKey 809functions process an RSA private key using an 810.Vt RSA 811structure. 812They handle the same formats as the 813.Sy PrivateKey 814functions, but an error occurs if the private key is not RSA. 815.Pp 816The 817.Sy RSAPublicKey 818functions process an RSA public key using an 819.Vt RSA 820structure. 821The public key is encoded using a PKCS#1 822.Vt RSAPublicKey 823structure. 824.Pp 825The 826.Sy RSA_PUBKEY 827functions also process an RSA public key using an 828.Vt RSA 829structure. 830However the public key is encoded using an ASN.1 831.Vt SubjectPublicKeyInfo 832structure and an error occurs if the public key is not RSA. 833.Pp 834The 835.Sy DSAPrivateKey 836functions process a DSA private key using a 837.Vt DSA 838structure. 839They handle the same formats as the 840.Sy PrivateKey 841functions but an error occurs if the private key is not DSA. 842.Pp 843The 844.Sy DSA_PUBKEY 845functions process a DSA public key using a 846.Vt DSA 847structure. 848The public key is encoded using an ASN.1 849.Vt SubjectPublicKeyInfo 850structure and an error occurs if the public key is not DSA. 851.Pp 852The 853.Sy DSAparams 854functions process DSA parameters using a 855.Vt DSA 856structure. 857The parameters are encoded using a Dss-Parms structure as defined in RFC 2459. 858.Pp 859The 860.Sy DHparams 861functions process DH parameters using a 862.Vt DH 863structure. 864The parameters are encoded using a PKCS#3 DHparameter structure. 865.Pp 866The 867.Sy ECPKParameters 868functions process EC parameters using an 869.Vt EC_GROUP 870structure and the 871.Xr d2i_ECPKParameters 3 872function. 873.Pp 874The 875.Sy ECPrivateKey 876functions process an EC private key using an 877.Vt EC_KEY 878structure. 879.Pp 880The 881.Sy EC_PUBKEY 882functions process an EC public key using an 883.Vt EC_KEY 884structure. 885.Pp 886The 887.Sy X509 888functions process an X509 certificate using an 889.Vt X509 890structure. 891They will also process a trusted X509 certificate but any trust settings 892are discarded. 893.Pp 894The 895.Sy X509_AUX 896functions process a trusted X509 certificate using an 897.Vt X509 898structure. 899The 900.Xr X509_check_trust 3 901manual explains how the auxiliary trust information is used. 902.Pp 903The 904.Sy X509_REQ 905and 906.Sy X509_REQ_NEW 907functions process a PKCS#10 certificate request using an 908.Vt X509_REQ 909structure. 910The 911.Sy X509_REQ 912write functions use CERTIFICATE REQUEST in the header whereas the 913.Sy X509_REQ_NEW 914functions use NEW CERTIFICATE REQUEST (as required by some CAs). 915The 916.Sy X509_REQ 917read functions will handle either form so there are no 918.Sy X509_REQ_NEW 919read functions. 920.Pp 921The 922.Sy X509_CRL 923functions process an X509 CRL using an 924.Vt X509_CRL 925structure. 926.Pp 927The 928.Sy PKCS7 929functions process a PKCS#7 930.Vt ContentInfo 931using a 932.Vt PKCS7 933structure. 934.Pp 935The 936.Sy CMS 937functions process a 938.Vt CMS_ContentInfo 939structure. 940.Pp 941The old 942.Sy PrivateKey 943write routines are retained for compatibility. 944New applications should write private keys using the 945.Fn PEM_write_bio_PKCS8PrivateKey 946or 947.Fn PEM_write_PKCS8PrivateKey 948routines because they are more secure (they use an iteration count of 9492048 whereas the traditional routines use a count of 1) unless 950compatibility with older versions of OpenSSL is important. 951.Pp 952The 953.Sy PrivateKey 954read routines can be used in all applications because they handle all 955formats transparently. 956.Ss PEM function arguments 957The PEM functions have many common arguments. 958.Pp 959The 960.Fa bp 961parameter specifies the 962.Vt BIO 963to read from or write to. 964.Pp 965The 966.Fa fp 967parameter specifies the 968.Vt FILE 969pointer to read from or write to. 970.Pp 971The PEM read functions all take a pointer to pointer argument 972.Fa x 973and return a pointer of the same type. 974If 975.Fa x 976is 977.Dv NULL , 978then the parameter is ignored. 979If 980.Fa x 981is not 982.Dv NULL 983but 984.Pf * Fa x 985is 986.Dv NULL , 987then the structure returned will be written to 988.Pf * Fa x . 989If neither 990.Fa x 991nor 992.Pf * Fa x 993are 994.Dv NULL , 995then an attempt is made to reuse the structure at 996.Pf * Fa x , 997but see the 998.Sx BUGS 999and 1000.Sx EXAMPLES 1001sections. 1002Irrespective of the value of 1003.Fa x , 1004a pointer to the structure is always returned, or 1005.Dv NULL 1006if an error occurred. 1007.Pp 1008The PEM functions which write private keys take an 1009.Fa enc 1010parameter, which specifies the encryption algorithm to use. 1011Encryption is done at the PEM level. 1012If this parameter is set to 1013.Dv NULL , 1014then the private key is written in unencrypted form. 1015.Pp 1016The optional arguments 1017.Fa u 1018and 1019.Fa cb 1020are a passphrase used for encrypting a PEM structure 1021or a callback to obtain the passphrase; see 1022.Xr pem_password_cb 3 1023for details. 1024.Pp 1025For the PEM write routines, if the 1026.Fa kstr 1027parameter is not 1028.Dv NULL , 1029then 1030.Fa klen 1031bytes at 1032.Fa kstr 1033are used as the passphrase and 1034.Fa cb 1035is ignored. 1036.Ss PEM encryption format 1037This old 1038.Sy PrivateKey 1039routines use a non-standard technique for encryption. 1040.Pp 1041The private key (or other data) takes the following form: 1042.Bd -literal -offset indent 1043-----BEGIN RSA PRIVATE KEY----- 1044Proc-Type: 4,ENCRYPTED 1045DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89 1046 1047\&...base64 encoded data... 1048-----END RSA PRIVATE KEY----- 1049.Ed 1050.Pp 1051The line beginning with 1052.Dq DEK-Info 1053contains two comma separated pieces of information: 1054the encryption algorithm name as used by 1055.Xr EVP_get_cipherbyname 3 1056and an 8-byte salt encoded as a set of hexadecimal digits. 1057.Pp 1058After this is the base64-encoded encrypted data. 1059.Pp 1060The encryption key is determined using 1061.Xr EVP_BytesToKey 3 , 1062using the salt and an iteration count of 1. 1063The IV used is the value of the salt and *not* the IV returned by 1064.Xr EVP_BytesToKey 3 . 1065.Sh RETURN VALUES 1066The read routines return either a pointer to the structure read or 1067.Dv NULL 1068if an error occurred. 1069.Pp 1070The write routines return 1 for success or 0 for failure. 1071.Sh EXAMPLES 1072Although the PEM routines take several arguments, in almost all 1073applications most of them are set to 0 or 1074.Dv NULL . 1075.Pp 1076Read a certificate in PEM format from a 1077.Vt BIO : 1078.Bd -literal -offset indent 1079X509 *x; 1080x = PEM_read_bio_X509(bp, NULL, 0, NULL); 1081if (x == NULL) { 1082 /* Error */ 1083} 1084.Ed 1085.Pp 1086Alternative method: 1087.Bd -literal -offset indent 1088X509 *x = NULL; 1089if (!PEM_read_bio_X509(bp, &x, 0, NULL)) { 1090 /* Error */ 1091} 1092.Ed 1093.Pp 1094Write a certificate to a 1095.Vt BIO : 1096.Bd -literal -offset indent 1097if (!PEM_write_bio_X509(bp, x)) { 1098 /* Error */ 1099} 1100.Ed 1101.Pp 1102Write an unencrypted private key to a 1103.Vt FILE : 1104.Bd -literal -offset indent 1105if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL)) { 1106 /* Error */ 1107} 1108.Ed 1109.Pp 1110Write a private key (using traditional format) to a 1111.Vt BIO 1112using triple DES encryption; the pass phrase is prompted for: 1113.Bd -literal -offset indent 1114if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), 1115 NULL, 0, 0, NULL)) { 1116 /* Error */ 1117} 1118.Ed 1119.Pp 1120Write a private key (using PKCS#8 format) to a 1121.Vt BIO 1122using triple DES encryption, using the pass phrase "hello": 1123.Bd -literal -offset indent 1124if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), 1125 NULL, 0, 0, "hello")) { 1126 /* Error */ 1127} 1128.Ed 1129.Pp 1130Read a private key from a 1131.Vt BIO 1132using the pass phrase "hello": 1133.Bd -literal -offset indent 1134key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello"); 1135if (key == NULL) { 1136 /* Error */ 1137} 1138.Ed 1139.Pp 1140Read a private key from a 1141.Vt BIO 1142using a pass phrase callback: 1143.Bd -literal -offset indent 1144key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key"); 1145if (key == NULL) { 1146 /* Error */ 1147} 1148.Ed 1149.Pp 1150Skeleton pass phrase callback: 1151.Bd -literal -offset indent 1152int 1153pass_cb(char *buf, int size, int rwflag, void *u) 1154{ 1155 char *tmp; 1156 size_t len; 1157 1158 /* We'd probably do something else if 'rwflag' is 1 */ 1159 printf("Enter pass phrase for \e"%s\e"\en", u); 1160 1161 /* 1162 * Instead of the following line, get the passphrase 1163 * from the user in some way. 1164 */ 1165 tmp = "hello"; 1166 if (tmp == NULL) /* An error occurred. */ 1167 return -1; 1168 1169 len = strlen(tmp); 1170 if (len == 0) /* Treat an empty passphrase as an error, too. */ 1171 return -1; 1172 1173 /* if too long, truncate */ 1174 if (len > size) 1175 len = size; 1176 memcpy(buf, tmp, len); 1177 return len; 1178} 1179.Ed 1180.Sh SEE ALSO 1181.Xr BIO_new 3 , 1182.Xr DSA_new 3 , 1183.Xr PEM_ASN1_read 3 , 1184.Xr PEM_bytes_read_bio 3 , 1185.Xr PEM_read 3 , 1186.Xr PEM_read_SSL_SESSION 3 , 1187.Xr PEM_write_bio_CMS_stream 3 , 1188.Xr PEM_write_bio_PKCS7_stream 3 , 1189.Xr PEM_X509_INFO_read 3 , 1190.Xr RSA_new 3 , 1191.Xr X509_CRL_new 3 , 1192.Xr X509_REQ_new 3 , 1193.Xr X509_SIG_new 3 1194.Sh HISTORY 1195.Fn PEM_read_X509 1196and 1197.Fn PEM_write_X509 1198appeared in SSLeay 0.4 or earlier. 1199.Fn PEM_read_X509_REQ , 1200.Fn PEM_write_X509_REQ , 1201.Fn PEM_read_X509_CRL , 1202and 1203.Fn PEM_write_X509_CRL 1204first appeared in SSLeay 0.4.4. 1205.Fn PEM_read_RSAPrivateKey , 1206.Fn PEM_write_RSAPrivateKey , 1207.Fn PEM_read_DHparams , 1208.Fn PEM_write_DHparams , 1209.Fn PEM_read_PKCS7 , 1210and 1211.Fn PEM_write_PKCS7 1212first appeared in SSLeay 0.5.1. 1213.Fn PEM_read_bio_PrivateKey , 1214.Fn PEM_read_PrivateKey , 1215.Fn PEM_read_bio_RSAPrivateKey , 1216.Fn PEM_write_bio_RSAPrivateKey , 1217.Fn PEM_read_bio_DSAPrivateKey , 1218.Fn PEM_read_DSAPrivateKey , 1219.Fn PEM_write_bio_DSAPrivateKey , 1220.Fn PEM_write_DSAPrivateKey , 1221.Fn PEM_read_bio_DHparams , 1222.Fn PEM_write_bio_DHparams , 1223.Fn PEM_read_bio_X509 , 1224.Fn PEM_write_bio_X509 , 1225.Fn PEM_read_bio_X509_REQ , 1226.Fn PEM_write_bio_X509_REQ , 1227.Fn PEM_read_bio_X509_CRL , 1228.Fn PEM_write_bio_X509_CRL , 1229.Fn PEM_read_bio_PKCS7 , 1230and 1231.Fn PEM_write_bio_PKCS7 1232first appeared in SSLeay 0.6.0. 1233.Fn PEM_write_bio_PrivateKey , 1234.Fn PEM_write_PrivateKey , 1235.Fn PEM_read_bio_DSAparams , 1236.Fn PEM_read_DSAparams , 1237.Fn PEM_write_bio_DSAparams , 1238and 1239.Fn PEM_write_DSAparams 1240first appeared in SSLeay 0.8.0. 1241.Fn PEM_read_bio_RSAPublicKey , 1242.Fn PEM_read_RSAPublicKey , 1243.Fn PEM_write_bio_RSAPublicKey , 1244and 1245.Fn PEM_write_RSAPublicKey 1246first appeared in SSLeay 0.8.1. 1247All these functions have been available since 1248.Ox 2.4 . 1249.Pp 1250.Fn PEM_write_bio_PKCS8PrivateKey , 1251.Fn PEM_write_PKCS8PrivateKey , 1252.Fn PEM_read_bio_PKCS8 , 1253.Fn PEM_read_PKCS8 , 1254.Fn PEM_write_bio_PKCS8 , 1255.Fn PEM_write_PKCS8 , 1256.Fn PEM_read_bio_PKCS8_PRIV_KEY_INFO , 1257.Fn PEM_read_PKCS8_PRIV_KEY_INFO , 1258.Fn PEM_write_bio_PKCS8_PRIV_KEY_INFO , 1259.Fn PEM_write_PKCS8_PRIV_KEY_INFO , 1260.Pp 1261.Fn PEM_write_bio_PKCS8PrivateKey_nid , 1262.Fn PEM_write_PKCS8PrivateKey_nid , 1263.Fn PEM_read_bio_PUBKEY , 1264.Fn PEM_read_PUBKEY , 1265.Fn PEM_write_bio_PUBKEY , 1266.Fn PEM_write_PUBKEY , 1267.Fn PEM_read_bio_RSA_PUBKEY , 1268.Fn PEM_read_RSA_PUBKEY , 1269.Fn PEM_write_bio_RSA_PUBKEY , 1270.Fn PEM_write_RSA_PUBKEY , 1271.Fn PEM_read_bio_DSA_PUBKEY , 1272.Fn PEM_read_DSA_PUBKEY , 1273.Fn PEM_write_bio_DSA_PUBKEY , 1274.Fn PEM_write_DSA_PUBKEY , 1275.Fn PEM_write_bio_X509_REQ_NEW , 1276.Fn PEM_write_X509_REQ_NEW , 1277.Fn PEM_read_bio_X509_AUX , 1278.Fn PEM_read_X509_AUX , 1279.Fn PEM_write_bio_X509_AUX , 1280and 1281.Fn PEM_write_X509_AUX 1282first appeared in OpenSSL 0.9.5 and have been available since 1283.Ox 2.7 . 1284.Pp 1285.Fn PEM_read_bio_ECPKParameters , 1286.Fn PEM_read_ECPKParameters , 1287.Fn PEM_write_bio_ECPKParameters , 1288.Fn PEM_write_ECPKParameters , 1289.Fn PEM_read_bio_ECPrivateKey , 1290.Fn PEM_read_ECPrivateKey , 1291.Fn PEM_write_bio_ECPrivateKey , 1292.Fn PEM_write_ECPrivateKey , 1293.Fn PEM_read_bio_EC_PUBKEY , 1294.Fn PEM_read_EC_PUBKEY , 1295.Fn PEM_write_bio_EC_PUBKEY , 1296and 1297.Fn PEM_write_EC_PUBKEY 1298first appeared in OpenSSL 0.9.8 and have been available since 1299.Ox 4.5 . 1300.Pp 1301.Fn PEM_read_CMS , 1302.Fn PEM_read_bio_CMS , 1303.Fn PEM_write_CMS , 1304and 1305.Fn PEM_write_bio_CMS 1306first appeared in OpenSSL 0.9.8h and have been available since 1307.Ox 6.7 . 1308.Sh CAVEATS 1309A frequent cause of problems is attempting to use the PEM routines like 1310this: 1311.Bd -literal -offset indent 1312X509 *x; 1313PEM_read_bio_X509(bp, &x, 0, NULL); 1314.Ed 1315.Pp 1316This is a bug because an attempt will be made to reuse the data at 1317.Fa x , 1318which is an uninitialised pointer. 1319.Pp 1320These functions make no assumption regarding the pass phrase received 1321from the password callback. 1322It will simply be treated as a byte sequence. 1323.Sh BUGS 1324The PEM read routines in some versions of OpenSSL will not correctly 1325reuse an existing structure. 1326Therefore 1327.Pp 1328.Dl PEM_read_bio_X509(bp, &x, 0, NULL); 1329.Pp 1330where 1331.Fa x 1332already contains a valid certificate may not work, whereas 1333.Bd -literal -offset indent 1334X509_free(x); 1335x = PEM_read_bio_X509(bp, NULL, 0, NULL); 1336.Ed 1337.Pp 1338is guaranteed to work. 1339