1.\" $OpenBSD: PEM_read_bio_PrivateKey.3,v 1.23 2024/09/02 08:04:32 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: September 2 2024 $ 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. 899.Pp 900The 901.Sy X509_REQ 902and 903.Sy X509_REQ_NEW 904functions process a PKCS#10 certificate request using an 905.Vt X509_REQ 906structure. 907The 908.Sy X509_REQ 909write functions use CERTIFICATE REQUEST in the header whereas the 910.Sy X509_REQ_NEW 911functions use NEW CERTIFICATE REQUEST (as required by some CAs). 912The 913.Sy X509_REQ 914read functions will handle either form so there are no 915.Sy X509_REQ_NEW 916read functions. 917.Pp 918The 919.Sy X509_CRL 920functions process an X509 CRL using an 921.Vt X509_CRL 922structure. 923.Pp 924The 925.Sy PKCS7 926functions process a PKCS#7 927.Vt ContentInfo 928using a 929.Vt PKCS7 930structure. 931.Pp 932The 933.Sy CMS 934functions process a 935.Vt CMS_ContentInfo 936structure. 937.Pp 938The old 939.Sy PrivateKey 940write routines are retained for compatibility. 941New applications should write private keys using the 942.Fn PEM_write_bio_PKCS8PrivateKey 943or 944.Fn PEM_write_PKCS8PrivateKey 945routines because they are more secure (they use an iteration count of 9462048 whereas the traditional routines use a count of 1) unless 947compatibility with older versions of OpenSSL is important. 948.Pp 949The 950.Sy PrivateKey 951read routines can be used in all applications because they handle all 952formats transparently. 953.Ss PEM function arguments 954The PEM functions have many common arguments. 955.Pp 956The 957.Fa bp 958parameter specifies the 959.Vt BIO 960to read from or write to. 961.Pp 962The 963.Fa fp 964parameter specifies the 965.Vt FILE 966pointer to read from or write to. 967.Pp 968The PEM read functions all take a pointer to pointer argument 969.Fa x 970and return a pointer of the same type. 971If 972.Fa x 973is 974.Dv NULL , 975then the parameter is ignored. 976If 977.Fa x 978is not 979.Dv NULL 980but 981.Pf * Fa x 982is 983.Dv NULL , 984then the structure returned will be written to 985.Pf * Fa x . 986If neither 987.Fa x 988nor 989.Pf * Fa x 990are 991.Dv NULL , 992then an attempt is made to reuse the structure at 993.Pf * Fa x , 994but see the 995.Sx BUGS 996and 997.Sx EXAMPLES 998sections. 999Irrespective of the value of 1000.Fa x , 1001a pointer to the structure is always returned, or 1002.Dv NULL 1003if an error occurred. 1004.Pp 1005The PEM functions which write private keys take an 1006.Fa enc 1007parameter, which specifies the encryption algorithm to use. 1008Encryption is done at the PEM level. 1009If this parameter is set to 1010.Dv NULL , 1011then the private key is written in unencrypted form. 1012.Pp 1013The optional arguments 1014.Fa u 1015and 1016.Fa cb 1017are a passphrase used for encrypting a PEM structure 1018or a callback to obtain the passphrase; see 1019.Xr pem_password_cb 3 1020for details. 1021.Pp 1022For the PEM write routines, if the 1023.Fa kstr 1024parameter is not 1025.Dv NULL , 1026then 1027.Fa klen 1028bytes at 1029.Fa kstr 1030are used as the passphrase and 1031.Fa cb 1032is ignored. 1033.Ss PEM encryption format 1034These old 1035.Sy PrivateKey 1036routines use a non-standard technique for encryption. 1037.Pp 1038The private key (or other data) takes the following form: 1039.Bd -literal -offset indent 1040-----BEGIN RSA PRIVATE KEY----- 1041Proc-Type: 4,ENCRYPTED 1042DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89 1043 1044\&...base64 encoded data... 1045-----END RSA PRIVATE KEY----- 1046.Ed 1047.Pp 1048The line beginning with 1049.Dq DEK-Info 1050contains two comma separated pieces of information: 1051the encryption algorithm name as used by 1052.Xr EVP_get_cipherbyname 3 1053and an 8-byte salt encoded as a set of hexadecimal digits. 1054.Pp 1055After this is the base64-encoded encrypted data. 1056.Pp 1057The encryption key is determined using 1058.Xr EVP_BytesToKey 3 , 1059using the salt and an iteration count of 1. 1060The IV used is the value of the salt and *not* the IV returned by 1061.Xr EVP_BytesToKey 3 . 1062.Sh RETURN VALUES 1063The read routines return either a pointer to the structure read or 1064.Dv NULL 1065if an error occurred. 1066.Pp 1067The write routines return 1 for success or 0 for failure. 1068.Sh EXAMPLES 1069Although the PEM routines take several arguments, in almost all 1070applications most of them are set to 0 or 1071.Dv NULL . 1072.Pp 1073Read a certificate in PEM format from a 1074.Vt BIO : 1075.Bd -literal -offset indent 1076X509 *x; 1077x = PEM_read_bio_X509(bp, NULL, 0, NULL); 1078if (x == NULL) { 1079 /* Error */ 1080} 1081.Ed 1082.Pp 1083Alternative method: 1084.Bd -literal -offset indent 1085X509 *x = NULL; 1086if (!PEM_read_bio_X509(bp, &x, 0, NULL)) { 1087 /* Error */ 1088} 1089.Ed 1090.Pp 1091Write a certificate to a 1092.Vt BIO : 1093.Bd -literal -offset indent 1094if (!PEM_write_bio_X509(bp, x)) { 1095 /* Error */ 1096} 1097.Ed 1098.Pp 1099Write an unencrypted private key to a 1100.Vt FILE : 1101.Bd -literal -offset indent 1102if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL)) { 1103 /* Error */ 1104} 1105.Ed 1106.Pp 1107Write a private key (using traditional format) to a 1108.Vt BIO 1109using triple DES encryption; the pass phrase is prompted for: 1110.Bd -literal -offset indent 1111if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), 1112 NULL, 0, 0, NULL)) { 1113 /* Error */ 1114} 1115.Ed 1116.Pp 1117Write a private key (using PKCS#8 format) to a 1118.Vt BIO 1119using triple DES encryption, using the pass phrase "hello": 1120.Bd -literal -offset indent 1121if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), 1122 NULL, 0, 0, "hello")) { 1123 /* Error */ 1124} 1125.Ed 1126.Pp 1127Read a private key from a 1128.Vt BIO 1129using the pass phrase "hello": 1130.Bd -literal -offset indent 1131key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello"); 1132if (key == NULL) { 1133 /* Error */ 1134} 1135.Ed 1136.Pp 1137Read a private key from a 1138.Vt BIO 1139using a pass phrase callback: 1140.Bd -literal -offset indent 1141key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key"); 1142if (key == NULL) { 1143 /* Error */ 1144} 1145.Ed 1146.Pp 1147Skeleton pass phrase callback: 1148.Bd -literal -offset indent 1149int 1150pass_cb(char *buf, int size, int rwflag, void *u) 1151{ 1152 char *tmp; 1153 size_t len; 1154 1155 /* We'd probably do something else if 'rwflag' is 1 */ 1156 printf("Enter pass phrase for \e"%s\e"\en", u); 1157 1158 /* 1159 * Instead of the following line, get the passphrase 1160 * from the user in some way. 1161 */ 1162 tmp = "hello"; 1163 if (tmp == NULL) /* An error occurred. */ 1164 return -1; 1165 1166 len = strlen(tmp); 1167 if (len == 0) /* Treat an empty passphrase as an error, too. */ 1168 return -1; 1169 1170 /* if too long, truncate */ 1171 if (len > size) 1172 len = size; 1173 memcpy(buf, tmp, len); 1174 return len; 1175} 1176.Ed 1177.Sh SEE ALSO 1178.Xr BIO_new 3 , 1179.Xr DSA_new 3 , 1180.Xr PEM_ASN1_read 3 , 1181.Xr PEM_bytes_read_bio 3 , 1182.Xr PEM_read 3 , 1183.Xr PEM_read_SSL_SESSION 3 , 1184.Xr PEM_write_bio_CMS_stream 3 , 1185.Xr PEM_write_bio_PKCS7_stream 3 , 1186.Xr PEM_X509_INFO_read 3 , 1187.Xr RSA_new 3 , 1188.Xr X509_CRL_new 3 , 1189.Xr X509_REQ_new 3 , 1190.Xr X509_SIG_new 3 1191.Sh HISTORY 1192.Fn PEM_read_X509 1193and 1194.Fn PEM_write_X509 1195appeared in SSLeay 0.4 or earlier. 1196.Fn PEM_read_X509_REQ , 1197.Fn PEM_write_X509_REQ , 1198.Fn PEM_read_X509_CRL , 1199and 1200.Fn PEM_write_X509_CRL 1201first appeared in SSLeay 0.4.4. 1202.Fn PEM_read_RSAPrivateKey , 1203.Fn PEM_write_RSAPrivateKey , 1204.Fn PEM_read_DHparams , 1205.Fn PEM_write_DHparams , 1206.Fn PEM_read_PKCS7 , 1207and 1208.Fn PEM_write_PKCS7 1209first appeared in SSLeay 0.5.1. 1210.Fn PEM_read_bio_PrivateKey , 1211.Fn PEM_read_PrivateKey , 1212.Fn PEM_read_bio_RSAPrivateKey , 1213.Fn PEM_write_bio_RSAPrivateKey , 1214.Fn PEM_read_bio_DSAPrivateKey , 1215.Fn PEM_read_DSAPrivateKey , 1216.Fn PEM_write_bio_DSAPrivateKey , 1217.Fn PEM_write_DSAPrivateKey , 1218.Fn PEM_read_bio_DHparams , 1219.Fn PEM_write_bio_DHparams , 1220.Fn PEM_read_bio_X509 , 1221.Fn PEM_write_bio_X509 , 1222.Fn PEM_read_bio_X509_REQ , 1223.Fn PEM_write_bio_X509_REQ , 1224.Fn PEM_read_bio_X509_CRL , 1225.Fn PEM_write_bio_X509_CRL , 1226.Fn PEM_read_bio_PKCS7 , 1227and 1228.Fn PEM_write_bio_PKCS7 1229first appeared in SSLeay 0.6.0. 1230.Fn PEM_write_bio_PrivateKey , 1231.Fn PEM_write_PrivateKey , 1232.Fn PEM_read_bio_DSAparams , 1233.Fn PEM_read_DSAparams , 1234.Fn PEM_write_bio_DSAparams , 1235and 1236.Fn PEM_write_DSAparams 1237first appeared in SSLeay 0.8.0. 1238.Fn PEM_read_bio_RSAPublicKey , 1239.Fn PEM_read_RSAPublicKey , 1240.Fn PEM_write_bio_RSAPublicKey , 1241and 1242.Fn PEM_write_RSAPublicKey 1243first appeared in SSLeay 0.8.1. 1244All these functions have been available since 1245.Ox 2.4 . 1246.Pp 1247.Fn PEM_write_bio_PKCS8PrivateKey , 1248.Fn PEM_write_PKCS8PrivateKey , 1249.Fn PEM_read_bio_PKCS8 , 1250.Fn PEM_read_PKCS8 , 1251.Fn PEM_write_bio_PKCS8 , 1252.Fn PEM_write_PKCS8 , 1253.Fn PEM_read_bio_PKCS8_PRIV_KEY_INFO , 1254.Fn PEM_read_PKCS8_PRIV_KEY_INFO , 1255.Fn PEM_write_bio_PKCS8_PRIV_KEY_INFO , 1256.Fn PEM_write_PKCS8_PRIV_KEY_INFO , 1257.Pp 1258.Fn PEM_write_bio_PKCS8PrivateKey_nid , 1259.Fn PEM_write_PKCS8PrivateKey_nid , 1260.Fn PEM_read_bio_PUBKEY , 1261.Fn PEM_read_PUBKEY , 1262.Fn PEM_write_bio_PUBKEY , 1263.Fn PEM_write_PUBKEY , 1264.Fn PEM_read_bio_RSA_PUBKEY , 1265.Fn PEM_read_RSA_PUBKEY , 1266.Fn PEM_write_bio_RSA_PUBKEY , 1267.Fn PEM_write_RSA_PUBKEY , 1268.Fn PEM_read_bio_DSA_PUBKEY , 1269.Fn PEM_read_DSA_PUBKEY , 1270.Fn PEM_write_bio_DSA_PUBKEY , 1271.Fn PEM_write_DSA_PUBKEY , 1272.Fn PEM_write_bio_X509_REQ_NEW , 1273.Fn PEM_write_X509_REQ_NEW , 1274.Fn PEM_read_bio_X509_AUX , 1275.Fn PEM_read_X509_AUX , 1276.Fn PEM_write_bio_X509_AUX , 1277and 1278.Fn PEM_write_X509_AUX 1279first appeared in OpenSSL 0.9.5 and have been available since 1280.Ox 2.7 . 1281.Pp 1282.Fn PEM_read_bio_ECPKParameters , 1283.Fn PEM_read_ECPKParameters , 1284.Fn PEM_write_bio_ECPKParameters , 1285.Fn PEM_write_ECPKParameters , 1286.Fn PEM_read_bio_ECPrivateKey , 1287.Fn PEM_read_ECPrivateKey , 1288.Fn PEM_write_bio_ECPrivateKey , 1289.Fn PEM_write_ECPrivateKey , 1290.Fn PEM_read_bio_EC_PUBKEY , 1291.Fn PEM_read_EC_PUBKEY , 1292.Fn PEM_write_bio_EC_PUBKEY , 1293and 1294.Fn PEM_write_EC_PUBKEY 1295first appeared in OpenSSL 0.9.8 and have been available since 1296.Ox 4.5 . 1297.Pp 1298.Fn PEM_read_CMS , 1299.Fn PEM_read_bio_CMS , 1300.Fn PEM_write_CMS , 1301and 1302.Fn PEM_write_bio_CMS 1303first appeared in OpenSSL 0.9.8h and have been available since 1304.Ox 6.7 . 1305.Sh CAVEATS 1306A frequent cause of problems is attempting to use the PEM routines like 1307this: 1308.Bd -literal -offset indent 1309X509 *x; 1310PEM_read_bio_X509(bp, &x, 0, NULL); 1311.Ed 1312.Pp 1313This is a bug because an attempt will be made to reuse the data at 1314.Fa x , 1315which is an uninitialised pointer. 1316.Pp 1317These functions make no assumption regarding the pass phrase received 1318from the password callback. 1319It will simply be treated as a byte sequence. 1320.Sh BUGS 1321The PEM read routines in some versions of OpenSSL will not correctly 1322reuse an existing structure. 1323Therefore 1324.Pp 1325.Dl PEM_read_bio_X509(bp, &x, 0, NULL); 1326.Pp 1327where 1328.Fa x 1329already contains a valid certificate may not work, whereas 1330.Bd -literal -offset indent 1331X509_free(x); 1332x = PEM_read_bio_X509(bp, NULL, 0, NULL); 1333.Ed 1334.Pp 1335is guaranteed to work. 1336