pem.h

All headers

PEM.

This library contains functions for reading and writing data encoded in PEM format. This format originated in Privacy-Enhanced Mail (RFC 1421). PEM consists of a series of PEM blocks, which are line-wrapped, base64-encoded data, wrapped in BEGIN and END lines, for example:

-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAGb9ECWmEzf6FQbrBZ9w7lshQhqowtrbLDFw4rXAxZuE=
-----END PUBLIC KEY-----

The BEGIN and END markers specify the type of data encoded. Multiple PEM blocks can be concatenated together. For example, it is common to represent a certificate chain as a series of PEM blocks of type CERTIFICATE. Owing to its email roots, PEM blocks can also be embedded in non-PEM data. The parsers in this library will generally skip over any non-PEM data, as well as any PEM blocks that are not of the expected type.

PEM blocks can be encrypted with a password, specified in RFC 1423. PEM encryption is vulnerable to padding oracle attacks and should not be used as a load-bearing security measure. It is implemented for interoperability with legacy systems only.

Callers should only use PEM for compatibility with legacy systems. PEM use should be limited to the components that directly interoperate with those systems, converting to and from more modern formats. PEM adds overhead to fit in email's 7-bit ASCII limitations, a constraint that is not relevant to most applications.

  1. API conventions
  2. PEM_def_callback
  3. PEM_read_bio_SAMPLE
  4. PEM_write_bio_SAMPLE
  5. Reading and writing X.509 structures as PEM
  6. PEM_read_bio_X509
  7. PEM_write_bio_X509
  8. PEM_read_bio_X509_AUX
  9. PEM_write_bio_X509_AUX
  10. PEM_read_bio_X509_CRL
  11. PEM_write_bio_X509_CRL
  12. PEM_read_bio_X509_REQ
  13. PEM_write_bio_X509_REQ
  14. PEM_write_bio_X509_REQ_NEW
  15. PEM_read_bio_PKCS7
  16. PEM_write_bio_PKCS7
  17. PEM_X509_INFO_read_bio
  18. Reading and writing keys as PEM
  19. PEM_read_bio_PrivateKey
  20. PEM_write_bio_PrivateKey
  21. PEM_read_bio_PUBKEY
  22. PEM_write_bio_PUBKEY
  23. PEM_write_bio_PKCS8PrivateKey_nid
  24. PEM_write_bio_PKCS8PrivateKey
  25. PEM_write_PKCS8PrivateKey_nid
  26. PEM_write_PKCS8PrivateKey
  27. PEM_read_bio_PKCS8
  28. PEM_write_bio_PKCS8
  29. PEM_read_bio_PKCS8_PRIV_KEY_INFO
  30. PEM_write_bio_PKCS8_PRIV_KEY_INFO
  31. PEM_read_bio_RSAPrivateKey
  32. PEM_write_bio_RSAPrivateKey
  33. PEM_read_bio_RSAPublicKey
  34. PEM_write_bio_RSAPublicKey
  35. PEM_read_bio_RSA_PUBKEY
  36. PEM_write_bio_RSA_PUBKEY
  37. PEM_read_bio_DSAPrivateKey
  38. PEM_write_bio_DSAPrivateKey
  39. PEM_read_bio_DSA_PUBKEY
  40. PEM_write_bio_DSA_PUBKEY
  41. PEM_read_bio_DSAparams
  42. PEM_write_bio_DSAparams
  43. PEM_read_bio_ECPrivateKey
  44. PEM_write_bio_ECPrivateKey
  45. PEM_read_bio_EC_PUBKEY
  46. PEM_write_bio_EC_PUBKEY
  47. PEM_read_bio_DHparams
  48. PEM_write_bio_DHparams
  49. File-based functions
  50. PEM_read_X509
  51. PEM_read_X509_CRL
  52. PEM_read_X509_AUX
  53. PEM_X509_INFO_read
  54. PEM_read_X509_REQ
  55. PEM_read_PKCS7
  56. PEM_read_PKCS8
  57. PEM_read_PKCS8_PRIV_KEY_INFO
  58. PEM_read_RSAPrivateKey
  59. PEM_read_RSAPublicKey
  60. PEM_read_RSA_PUBKEY
  61. PEM_read_DSAPrivateKey
  62. PEM_read_DSA_PUBKEY
  63. PEM_read_DSAparams
  64. PEM_read_ECPrivateKey
  65. PEM_read_EC_PUBKEY
  66. PEM_read_DHparams
  67. PEM_read_PrivateKey
  68. PEM_read_PUBKEY
  69. PEM_write_X509
  70. PEM_write_X509_CRL
  71. PEM_write_X509_AUX
  72. PEM_write_X509_REQ
  73. PEM_write_X509_REQ_NEW
  74. PEM_write_PKCS7
  75. PEM_write_PKCS8
  76. PEM_write_PKCS8_PRIV_KEY_INFO
  77. PEM_write_RSAPrivateKey
  78. PEM_write_RSAPublicKey
  79. PEM_write_RSA_PUBKEY
  80. PEM_write_DSAPrivateKey
  81. PEM_write_DSA_PUBKEY
  82. PEM_write_DSAparams
  83. PEM_write_ECPrivateKey
  84. PEM_write_EC_PUBKEY
  85. PEM_write_DHparams
  86. PEM_write_PrivateKey
  87. PEM_write_PUBKEY
  88. Reading and writing raw PEM blocks
  89. PEM_BUFSIZE
  90. PEM_STRING_X509_OLD
  91. PEM_STRING_X509
  92. PEM_STRING_X509_PAIR
  93. PEM_STRING_X509_TRUSTED
  94. PEM_STRING_X509_REQ_OLD
  95. PEM_STRING_X509_REQ
  96. PEM_STRING_X509_CRL
  97. PEM_STRING_PUBLIC
  98. PEM_STRING_RSA
  99. PEM_STRING_RSA_PUBLIC
  100. PEM_STRING_DSA
  101. PEM_STRING_DSA_PUBLIC
  102. PEM_STRING_EC
  103. PEM_STRING_PKCS7
  104. PEM_STRING_PKCS7_SIGNED
  105. PEM_STRING_PKCS8
  106. PEM_STRING_PKCS8INF
  107. PEM_STRING_DHPARAMS
  108. PEM_STRING_SSL_SESSION
  109. PEM_STRING_DSAPARAMS
  110. PEM_STRING_ECDSA_PUBLIC
  111. PEM_STRING_ECPRIVATEKEY
  112. PEM_STRING_CMS
  113. PEM_STRING_EVP_PKEY
  114. PEM_read_bio
  115. PEM_read
  116. PEM_write_bio
  117. PEM_write
  118. PEM_bytes_read_bio
  119. Reading and writing DER-encoded private keys
  120. d2i_PKCS8PrivateKey_bio
  121. i2d_PKCS8PrivateKey_bio
  122. i2d_PKCS8PrivateKey_nid_bio
  123. i2d_PKCS8PrivateKey_fp
  124. i2d_PKCS8PrivateKey_nid_fp
  125. d2i_PKCS8PrivateKey_fp
  126. Internal functions
  127. PEM_ASN1_read_bio
  128. PEM_ASN1_read
  129. PEM_ASN1_write_bio
  130. PEM_ASN1_write

API conventions.

pem_password_cb is an application-supplied callback to supply a PEM password. On success, the callback should write the password into out, which has room for at most max_out bytes. On error, including if max_out is too small, it should return -1. enc is one if the password will be used for encrypting and zero if it is used for decrypting. userdata is the application-supplied parameter of the same name to the PEM function.

typedef int pem_password_cb(char *out, int max_out, int enc, void *userdata);

PEM_def_callback is the default implementation of pem_password_cb. It interprets userdata as a NUL-terminated C string and outputs it according to pem_password_cb. If userdata is NULL, it returns -1.

This differs from OpenSSL, which interactively prompts for a password by default.

OPENSSL_EXPORT int PEM_def_callback(char *buf, int size, int enc,
                                    void *userdata);

The following sample functions document the calling conventions used by this library.

#if 0  // Sample functions

PEM_read_bio_SAMPLE reads a PEM block from bio, skipping non-PEM data and unexpected block types. It then decodes the resulting PEM block and returns a newly-allocated SAMPLE object containing the parsed structure. If out is non-NULL, it additionally frees the previous value at *out and updates *out to the result.

On decode or allocation error, or if EOF is reached before a matching PEM block is found, it returns NULL. In the error case, it will add PEM_R_NO_START_LINE to the error queue. Callers can check the error queue to distinguish these cases.

If the PEM block is encrypted, cb will be called to look up the password. See pem_password_cb for details. If cb is NULL, PEM_def_callback is used and userdata should be a NUL-terminated C string containing the password. Set both cb and userdata to NULL to only handle plaintext blocks.

SAMPLE *PEM_read_bio_SAMPLE(BIO *bio, SAMPLE **out, pem_password_cb *cb,
                            void *userdata);

PEM_write_bio_SAMPLE encodes in as a PEM block and writes it to bio. It returns one on success and zero on error.

If enc is non-NULL, the PEM block is encrypted with the specified cipher and a password. If pass is non-NULL, pass_len bytes from pass is used as the password. Otherwise, cb is called. If cb is NULL, PEM_def_callback is used. PEM encryption is vulnerable to padding oracle attacks and should not be used.

Some functions of this convention do not support encryption. In this case, the encryption-related parameters will be omitted.

On error, the state of bio is undefined. It is possible a prefix of a PEM block was left in the bio.

int PEM_write_bio_SAMPLE(BIO *bio, const SAMPLE *in, const EVP_CIPHER *enc,
                         const uint8_t *pass, int pass_len, pem_password_cb *cb,
                         void *userdata);
#endif  // Sample functions

Reading and writing X.509 structures as PEM.

PEM_read_bio_X509 reads a PEM block of type "CERTIFICATE" (RFC 7468) or "X509 CERTIFICATE", as described in PEM_read_bio_SAMPLE.

OPENSSL_EXPORT X509 *PEM_read_bio_X509(BIO *bio, X509 **out,
                                       pem_password_cb *cb, void *userdata);

PEM_write_bio_X509 writes a PEM block of type "CERTIFICATE" (RFC 7468), as described in PEM_write_bio_SAMPLE.

OPENSSL_EXPORT int PEM_write_bio_X509(BIO *bio, const X509 *in);

PEM_read_bio_X509_AUX reads a PEM block of type "CERTIFICATE" (RFC 7468), "X509 CERTIFICATE", or "TRUSTED CERTIFICATE", as described in PEM_read_bio_SAMPLE.

WARNING: This function parses auxiliary properties as in d2i_X509_AUX. Passing untrusted input to this function allows an attacker to influence those properties. See d2i_X509_AUX for details.

OPENSSL_EXPORT X509 *PEM_read_bio_X509_AUX(BIO *bio, X509 **out,
                                           pem_password_cb *cb, void *userdata);

PEM_write_bio_X509_AUX writes a PEM block of type "TRUSTED CERTIFICATE", as described in PEM_write_bio_SAMPLE.

WARNING: This function writes a custom OpenSSL-specific format that includes auxiliary properties. See i2d_X509_AUX.

OPENSSL_EXPORT int PEM_write_bio_X509_AUX(BIO *bio, const X509 *in);

PEM_read_bio_X509_CRL reads a PEM block of type "X509 CRL" (RFC 7468), as described in PEM_read_bio_SAMPLE.

OPENSSL_EXPORT X509_CRL *PEM_read_bio_X509_CRL(BIO *bio, X509_CRL **out,
                                               pem_password_cb *cb,
                                               void *userdata);

PEM_write_bio_X509_CRL writes a PEM block of type "X509 CRL" (RFC 7468), as described in PEM_write_bio_SAMPLE.

OPENSSL_EXPORT int PEM_write_bio_X509_CRL(BIO *bio, const X509_CRL *in);

PEM_read_bio_X509_REQ reads a PEM block of type "CERTIFICATE REQUEST" (RFC 7468) or "NEW CERTIFICATE REQUEST", as described in PEM_read_bio_SAMPLE.

OPENSSL_EXPORT X509_REQ *PEM_read_bio_X509_REQ(BIO *bio, X509_REQ **out,
                                               pem_password_cb *cb,
                                               void *userdata);

PEM_write_bio_X509_REQ writes a PEM block of type "CERTIFICATE REQUEST" (RFC 7468), as described in PEM_write_bio_SAMPLE.

OPENSSL_EXPORT int PEM_write_bio_X509_REQ(BIO *bio, const X509_REQ *in);

PEM_write_bio_X509_REQ_NEW writes a PEM block of type "NEW CERTIFICATE REQUEST", as described in PEM_write_bio_SAMPLE. Prefer to use PEM_write_bio_X509_REQ. "NEW CERTIFICATE REQUEST" is the older type.

OPENSSL_EXPORT int PEM_write_bio_X509_REQ_NEW(BIO *bio, const X509_REQ *in);

PEM_read_bio_PKCS7 reads a PEM block of type "PKCS7" (RFC 7468) or "PKCS #7 SIGNED DATA", as described in PEM_read_bio_SAMPLE.

This function also accepts type "CERTIFICATE" but decodes the contents as a PKCS #7 structure rather than a certificate. This is a historical workaround for an old CA bug.

OPENSSL_EXPORT PKCS7 *PEM_read_bio_PKCS7(BIO *bio, PKCS7 **out,
                                         pem_password_cb *cb, void *userdata);

PEM_write_bio_PKCS7 writes a PEM block of type "PKCS7" (RFC 7468), as described in PEM_write_bio_SAMPLE.

OPENSSL_EXPORT int PEM_write_bio_PKCS7(BIO *bio, const PKCS7 *in);

PEM_X509_INFO_read_bio reads PEM blocks from bio and decodes any certificates, CRLs, and private keys found. It returns a STACK_OF(X509_INFO) structure containing the results, or NULL on error.

If sk is NULL, the result on success will be a newly-allocated STACK_OF(X509_INFO) structure which should be released with sk_X509_INFO_pop_free and X509_INFO_free when done.

If sk is non-NULL, it appends the results to sk instead and returns sk on success. In this case, the caller retains ownership of sk in both success and failure.

This function will decrypt any encrypted certificates in bio, using cb, but it will not decrypt encrypted private keys. Encrypted private keys are instead represented as placeholder X509_INFO objects with an empty x_pkey field. This allows this function to be used with inputs with unencrypted certificates, but encrypted passwords, without knowing the password. However, it also means that this function cannot be used to decrypt the private key when the password is known.

WARNING: If the input contains "TRUSTED CERTIFICATE" PEM blocks, this function parses auxiliary properties as in d2i_X509_AUX. Passing untrusted input to this function allows an attacker to influence those properties. See d2i_X509_AUX for details.

OPENSSL_EXPORT STACK_OF(X509_INFO) *PEM_X509_INFO_read_bio(
    BIO *bio, STACK_OF(X509_INFO) *sk, pem_password_cb *cb, void *userdata);

Reading and writing keys as PEM.

There are multiple PEM formats for public and private keys:

Public keys are generally encoded with type "PUBLIC KEY" (RFC 7468), which encodes a SubjectPublicKeyInfo structure (RFC 5280).

Private keys may be encoded with type "PRIVATE KEY" or "ENCRYPTED PRIVATE KEY" (RFC 7468), which encode a PrivateKeyInfo or EncryptedPrivateKeyInfo (RFC 5208) structure. EncryptedPrivateKeyInfo is, itself, a mechanism for encrypting private keys with a password, so private keys may be encrypted with PEM encryption, PKCS #8 encryption, or both.

There are also older algorithm-specific PEM types for public and private keys, including "RSA PUBLIC KEY", "RSA PRIVATE KEY", "EC PRIVATE KEY", and "DSA PRIVATE KEY". Some functions in this library will read or write them.

If unsure, use the "PUBLIC KEY" and "PRIVATE KEY" formats.

PEM_read_bio_PrivateKey reads a PEM block containing a private key, as described in PEM_read_bio_SAMPLE. It handles generic PKCS #8 blocks of type "PRIVATE KEY" and "ENCRYPTED PRIVATE KEY", as well as key-specific formats like "RSA PRIVATE KEY", "EC PRIVATE KEY", and "DSA PRIVATE KEY".

cb and userdata are used to look up the password for both PEM-level encryption as well as PKCS #8 encryption, in the case of "ENCRYPTED PRIVATE KEY" blocks.

OPENSSL_EXPORT EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bio, EVP_PKEY **out,
                                                 pem_password_cb *cb,
                                                 void *userdata);

PEM_write_bio_PrivateKey writes in to bio in PKCS#8 format, as described in PEM_write_bio_SAMPLE. However, it interprets encryption parameters differently:

  • If not encrypting (enc is NULL), it writes the key as a PEM block of type "PRIVATE KEY".
  • If encrypted (enc is not NULL), it encrypts the key in an EncryptedPrivateKeyInfo using PBES2 (see PKCS8_encrypt) and writes the result as a PEM block of type "ENCRYPTED PRIVATE KEY".
OPENSSL_EXPORT int PEM_write_bio_PrivateKey(BIO *bio, const EVP_PKEY *in,
                                            const EVP_CIPHER *enc,
                                            const uint8_t *pass, int pass_len,
                                            pem_password_cb *cb,
                                            void *userdata);

PEM_read_bio_PUBKEY reads a PEM block of type "PUBLIC KEY", as described in PEM_read_bio_SAMPLE.

OPENSSL_EXPORT EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bio, EVP_PKEY **out,
                                             pem_password_cb *cb,
                                             void *userdata);

PEM_write_bio_PUBKEY writes in as a PEM block of type "PUBLIC KEY", as described in PEM_write_bio_SAMPLE.

OPENSSL_EXPORT int PEM_write_bio_PUBKEY(BIO *bio, const EVP_PKEY *in);

PEM_write_bio_PKCS8PrivateKey_nid behaves like PEM_write_bio_PrivateKey but uses the PBES1 algorithm specified by nid for encryption. See also PKCS8_encrypt. If nid is -1, it writes the private key unencrypted.

OPENSSL_EXPORT int PEM_write_bio_PKCS8PrivateKey_nid(
    BIO *bio, const EVP_PKEY *in, int nid, const char *pass, int pass_len,
    pem_password_cb *cb, void *userdata);

PEM_write_bio_PKCS8PrivateKey is an alias for PEM_write_bio_PrivateKey.

OPENSSL_EXPORT int PEM_write_bio_PKCS8PrivateKey(BIO *bio, const EVP_PKEY *in,
                                                 const EVP_CIPHER *enc,
                                                 const char *pass, int pass_len,
                                                 pem_password_cb *cb,
                                                 void *userdata);

PEM_write_PKCS8PrivateKey_nid behaves like PEM_write_bio_PKCS8PrivateKey_nid but writes to fp.

OPENSSL_EXPORT int PEM_write_PKCS8PrivateKey_nid(FILE *fp, const EVP_PKEY *in,
                                                 int nid, const char *pass,
                                                 int pass_len,
                                                 pem_password_cb *cb,
                                                 void *userdata);

PEM_write_PKCS8PrivateKey behaves like PEM_write_bio_PKCS8PrivateKey but writes to fp.

OPENSSL_EXPORT int PEM_write_PKCS8PrivateKey(FILE *fp, const EVP_PKEY *in,
                                             const EVP_CIPHER *enc,
                                             const char *pass, int pass_len,
                                             pem_password_cb *cb,
                                             void *userdata);

PEM_read_bio_PKCS8 reads a PEM block of type "ENCRYPTED PRIVATE KEY", as described in PEM_read_bio_SAMPLE.

Although this function accepts cb and userdata to decrypt the PEM-level encryption, it does not decrypt the EncryptedPrivateKeyInfo structure. It returns the encrypted key as an X509_SIG object which, despite its name, is an algorithm and octet string pair.

OPENSSL_EXPORT X509_SIG *PEM_read_bio_PKCS8(BIO *bio, X509_SIG **out,
                                            pem_password_cb *cb,
                                            void *userdata);

PEM_write_bio_PKCS8 writes a PEM block of type "ENCRYPTED PRIVATE KEY", as described in PEM_write_bio_SAMPLE. in is used to represent an already-encrypted EncryptedPrivateKeyInfo structure.

OPENSSL_EXPORT int PEM_write_bio_PKCS8(BIO *bio, const X509_SIG *in);

PEM_read_bio_PKCS8_PRIV_KEY_INFO reads a PEM block of type "PRIVATE KEY", as described in PEM_read_bio_SAMPLE.

OPENSSL_EXPORT PKCS8_PRIV_KEY_INFO *PEM_read_bio_PKCS8_PRIV_KEY_INFO(
    BIO *bio, PKCS8_PRIV_KEY_INFO **out, pem_password_cb *cb, void *userdata);

PEM_write_bio_PKCS8_PRIV_KEY_INFO writes a PEM block of type "PRIVATE KEY", as described in PEM_write_bio_SAMPLE.

OPENSSL_EXPORT int PEM_write_bio_PKCS8_PRIV_KEY_INFO(
    BIO *bio, const PKCS8_PRIV_KEY_INFO *in);

PEM_read_bio_RSAPrivateKey behaves like PEM_read_bio_PrivateKey but only returns RSA keys, represented as an RSA object. Keys of other types result in an error.

OPENSSL_EXPORT RSA *PEM_read_bio_RSAPrivateKey(BIO *bio, RSA **out,
                                               pem_password_cb *cb,
                                               void *userdata);

PEM_write_bio_RSAPrivateKey writes in as a PEM block of type "RSA PRIVATE KEY", as described in PEM_write_bio_SAMPLE.

OPENSSL_EXPORT int PEM_write_bio_RSAPrivateKey(
    BIO *bio, const RSA *in, const EVP_CIPHER *enc, const uint8_t *pass,
    int pass_len, pem_password_cb *cb, void *userdata);

PEM_read_bio_RSAPublicKey reads a PEM block of type "RSA PUBLIC KEY", as described in PEM_read_bio_SAMPLE.

OPENSSL_EXPORT RSA *PEM_read_bio_RSAPublicKey(BIO *bio, RSA **out,
                                              pem_password_cb *cb,
                                              void *userdata);

PEM_write_bio_RSAPublicKey writes a PEM block of type "RSA PUBLIC KEY", as described in PEM_write_bio_SAMPLE.

OPENSSL_EXPORT int PEM_write_bio_RSAPublicKey(BIO *bio, const RSA *in);

PEM_read_bio_RSA_PUBKEY behaves like PEM_read_bio_PUBKEY but only returns RSA keys, represented as an RSA object. Keys of other types result in an error.

OPENSSL_EXPORT RSA *PEM_read_bio_RSA_PUBKEY(BIO *bio, RSA **out,
                                            pem_password_cb *cb,
                                            void *userdata);

PEM_write_bio_RSA_PUBKEY writes in as a PEM block of type "PUBLIC KEY", as described in PEM_write_bio_SAMPLE.

OPENSSL_EXPORT int PEM_write_bio_RSA_PUBKEY(BIO *bio, const RSA *in);

PEM_read_bio_DSAPrivateKey behaves like PEM_read_bio_PrivateKey but only returns DSA keys, represented as a DSA object. Keys of other types result in an error.

OPENSSL_EXPORT DSA *PEM_read_bio_DSAPrivateKey(BIO *bio, DSA **out,
                                               pem_password_cb *cb,
                                               void *userdata);

PEM_write_bio_DSAPrivateKey writes in as a PEM block of type "DSA PRIVATE KEY", as described in PEM_write_bio_SAMPLE.

OPENSSL_EXPORT int PEM_write_bio_DSAPrivateKey(
    BIO *bio, const DSA *in, const EVP_CIPHER *enc, const uint8_t *pass,
    int pass_len, pem_password_cb *cb, void *userdata);

PEM_read_bio_DSA_PUBKEY behaves like PEM_read_bio_PUBKEY but only returns DSA keys, represented as a DSA object. Keys of other types result in an error.

OPENSSL_EXPORT DSA *PEM_read_bio_DSA_PUBKEY(BIO *bio, DSA **out,
                                            pem_password_cb *cb,
                                            void *userdata);

PEM_write_bio_DSA_PUBKEY writes in in SubjectPublicKeyInfo format as a PEM block of type "PUBLIC KEY", as described in PEM_write_bio_SAMPLE.

OPENSSL_EXPORT int PEM_write_bio_DSA_PUBKEY(BIO *bio, const DSA *in);

PEM_read_bio_DSAparams reads a PEM block of type "DSA PARAMETERS", as described in PEM_read_bio_SAMPLE.

OPENSSL_EXPORT DSA *PEM_read_bio_DSAparams(BIO *bio, DSA **out,
                                           pem_password_cb *cb, void *userdata);

PEM_write_bio_DSAparams writes a PEM block of type "DSA PARAMETERS", as described in PEM_write_bio_SAMPLE.

OPENSSL_EXPORT int PEM_write_bio_DSAparams(BIO *bio, const DSA *in);

PEM_read_bio_ECPrivateKey behaves like PEM_read_bio_PrivateKey but only returns EC keys, represented as an EC_KEY object. Keys of other types result in an error.

OPENSSL_EXPORT EC_KEY *PEM_read_bio_ECPrivateKey(BIO *bio, EC_KEY **out,
                                                 pem_password_cb *cb,
                                                 void *userdata);

PEM_write_bio_ECPrivateKey writes in as a PEM block of type "EC PRIVATE KEY", as described in PEM_write_bio_SAMPLE.

OPENSSL_EXPORT int PEM_write_bio_ECPrivateKey(BIO *bio, const EC_KEY *in,
                                              const EVP_CIPHER *enc,
                                              const uint8_t *pass, int pass_len,
                                              pem_password_cb *cb,
                                              void *userdata);

PEM_read_bio_EC_PUBKEY behaves like PEM_read_bio_PUBKEY but only returns EC keys, represented as an EC_KEY object. Keys of other types result in an error.

OPENSSL_EXPORT EC_KEY *PEM_read_bio_EC_PUBKEY(BIO *bio, EC_KEY **out,
                                              pem_password_cb *cb,
                                              void *userdata);

PEM_write_bio_EC_PUBKEY writes in in SubjectPublicKeyInfo format as a PEM block of type "PUBLIC KEY", as described in PEM_write_bio_SAMPLE.

OPENSSL_EXPORT int PEM_write_bio_EC_PUBKEY(BIO *bio, const EC_KEY *in);

PEM_read_bio_DHparams reads a PEM block of type "DH PARAMETERS", as described in PEM_read_bio_SAMPLE.

OPENSSL_EXPORT DH *PEM_read_bio_DHparams(BIO *bio, DH **out,
                                         pem_password_cb *cb, void *userdata);

PEM_write_bio_DHparams writes a PEM block of type "DH PARAMETERS", as described in PEM_write_bio_SAMPLE.

OPENSSL_EXPORT int PEM_write_bio_DHparams(BIO *bio, const DH *in);

File-based functions.

The following functions behave like the corresponding PEM_read_bio_* functions, but read from fp.

OPENSSL_EXPORT X509 *PEM_read_X509(FILE *fp, X509 **out, pem_password_cb *cb,
                                   void *userdata);
OPENSSL_EXPORT X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **out,
                                           pem_password_cb *cb, void *userdata);
OPENSSL_EXPORT X509 *PEM_read_X509_AUX(FILE *fp, X509 **out,
                                       pem_password_cb *cb, void *userdata);
OPENSSL_EXPORT STACK_OF(X509_INFO) *PEM_X509_INFO_read(FILE *fp,
                                                       STACK_OF(X509_INFO) *sk,
                                                       pem_password_cb *cb,
                                                       void *userdata);
OPENSSL_EXPORT X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **out,
                                           pem_password_cb *cb, void *userdata);
OPENSSL_EXPORT PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **out, pem_password_cb *cb,
                                     void *userdata);
OPENSSL_EXPORT X509_SIG *PEM_read_PKCS8(FILE *fp, X509_SIG **out,
                                        pem_password_cb *cb, void *userdata);
OPENSSL_EXPORT PKCS8_PRIV_KEY_INFO *PEM_read_PKCS8_PRIV_KEY_INFO(
    FILE *fp, PKCS8_PRIV_KEY_INFO **out, pem_password_cb *cb, void *userdata);
OPENSSL_EXPORT RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **out,
                                           pem_password_cb *cb, void *userdata);
OPENSSL_EXPORT RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **out,
                                          pem_password_cb *cb, void *userdata);
OPENSSL_EXPORT RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **out,
                                        pem_password_cb *cb, void *userdata);
OPENSSL_EXPORT DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **out,
                                           pem_password_cb *cb, void *userdata);
OPENSSL_EXPORT DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **out,
                                        pem_password_cb *cb, void *userdata);
OPENSSL_EXPORT DSA *PEM_read_DSAparams(FILE *fp, DSA **out, pem_password_cb *cb,
                                       void *userdata);
OPENSSL_EXPORT EC_KEY *PEM_read_ECPrivateKey(FILE *fp, EC_KEY **out,
                                             pem_password_cb *cb,
                                             void *userdata);
OPENSSL_EXPORT EC_KEY *PEM_read_EC_PUBKEY(FILE *fp, EC_KEY **out,
                                          pem_password_cb *cb, void *userdata);
OPENSSL_EXPORT DH *PEM_read_DHparams(FILE *fp, DH **out, pem_password_cb *cb,
                                     void *userdata);
OPENSSL_EXPORT EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **out,
                                             pem_password_cb *cb,
                                             void *userdata);
OPENSSL_EXPORT EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **out,
                                         pem_password_cb *cb, void *userdata);

The following functions behave like the corresponding PEM_write_bio_* functions, but write to fp.

OPENSSL_EXPORT int PEM_write_X509(FILE *fp, const X509 *x);
OPENSSL_EXPORT int PEM_write_X509_CRL(FILE *fp, const X509_CRL *in);
OPENSSL_EXPORT int PEM_write_X509_AUX(FILE *fp, const X509 *in);
OPENSSL_EXPORT int PEM_write_X509_REQ(FILE *fp, const X509_REQ *in);
OPENSSL_EXPORT int PEM_write_X509_REQ_NEW(FILE *fp, const X509_REQ *in);
OPENSSL_EXPORT int PEM_write_PKCS7(FILE *fp, const PKCS7 *in);
OPENSSL_EXPORT int PEM_write_PKCS8(FILE *fp, const X509_SIG *in);
OPENSSL_EXPORT int PEM_write_PKCS8_PRIV_KEY_INFO(FILE *fp,
                                                 const PKCS8_PRIV_KEY_INFO *in);
OPENSSL_EXPORT int PEM_write_RSAPrivateKey(FILE *fp, const RSA *in,
                                           const EVP_CIPHER *enc,
                                           const uint8_t *pass, int pass_len,
                                           pem_password_cb *cb, void *userdata);
OPENSSL_EXPORT int PEM_write_RSAPublicKey(FILE *fp, const RSA *in);
OPENSSL_EXPORT int PEM_write_RSA_PUBKEY(FILE *fp, const RSA *in);
OPENSSL_EXPORT int PEM_write_DSAPrivateKey(FILE *fp, const DSA *in,
                                           const EVP_CIPHER *enc,
                                           const uint8_t *pass, int pass_len,
                                           pem_password_cb *cb, void *userdata);
OPENSSL_EXPORT int PEM_write_DSA_PUBKEY(FILE *fp, const DSA *in);
OPENSSL_EXPORT int PEM_write_DSAparams(FILE *fp, const DSA *in);
OPENSSL_EXPORT int PEM_write_ECPrivateKey(FILE *fp, const EC_KEY *in,
                                          const EVP_CIPHER *enc,
                                          const uint8_t *pass, int pass_len,
                                          pem_password_cb *cb, void *userdata);
OPENSSL_EXPORT int PEM_write_EC_PUBKEY(FILE *fp, const EC_KEY *in);
OPENSSL_EXPORT int PEM_write_DHparams(FILE *fp, const DH *in);
OPENSSL_EXPORT int PEM_write_PrivateKey(FILE *fp, const EVP_PKEY *in,
                                        const EVP_CIPHER *enc,
                                        const uint8_t *pass, int pass_len,
                                        pem_password_cb *cb, void *userdata);
OPENSSL_EXPORT int PEM_write_PUBKEY(FILE *fp, const EVP_PKEY *in);

Reading and writing raw PEM blocks.

The functions in this section read and write PEM blocks without decoding their contents.

PEM_BUFSIZE is an arbitrary buffer size used within the library. Some external callers depend on it being defined.

#define PEM_BUFSIZE 1024

The following constants are a collection of known PEM types.

#define PEM_STRING_X509_OLD "X509 CERTIFICATE"
#define PEM_STRING_X509 "CERTIFICATE"
#define PEM_STRING_X509_PAIR "CERTIFICATE PAIR"
#define PEM_STRING_X509_TRUSTED "TRUSTED CERTIFICATE"
#define PEM_STRING_X509_REQ_OLD "NEW CERTIFICATE REQUEST"
#define PEM_STRING_X509_REQ "CERTIFICATE REQUEST"
#define PEM_STRING_X509_CRL "X509 CRL"
#define PEM_STRING_PUBLIC "PUBLIC KEY"
#define PEM_STRING_RSA "RSA PRIVATE KEY"
#define PEM_STRING_RSA_PUBLIC "RSA PUBLIC KEY"
#define PEM_STRING_DSA "DSA PRIVATE KEY"
#define PEM_STRING_DSA_PUBLIC "DSA PUBLIC KEY"
#define PEM_STRING_EC "EC PRIVATE KEY"
#define PEM_STRING_PKCS7 "PKCS7"
#define PEM_STRING_PKCS7_SIGNED "PKCS #7 SIGNED DATA"
#define PEM_STRING_PKCS8 "ENCRYPTED PRIVATE KEY"
#define PEM_STRING_PKCS8INF "PRIVATE KEY"
#define PEM_STRING_DHPARAMS "DH PARAMETERS"
#define PEM_STRING_SSL_SESSION "SSL SESSION PARAMETERS"
#define PEM_STRING_DSAPARAMS "DSA PARAMETERS"
#define PEM_STRING_ECDSA_PUBLIC "ECDSA PUBLIC KEY"
#define PEM_STRING_ECPRIVATEKEY "EC PRIVATE KEY"
#define PEM_STRING_CMS "CMS"

PEM_STRING_EVP_PKEY is not a PEM type, but is an implementation detail of PEM_read_bio_PrivateKey.

#define PEM_STRING_EVP_PKEY "ANY PRIVATE KEY"

PEM_read_bio reads from bio until the next PEM block. If one is found, it returns one and sets *out_name, *out_header, and *out_data to newly-allocated buffers containing the PEM type, the header block, and the decoded data, respectively. *out_name and *out_header are NUL-terminated C strings, while *out_data has *out_len bytes. The caller must release each of *out_name, *out_header, and *out_data with OPENSSL_free when done.

If no PEM block is found, this function returns zero and pushes PEM_R_NO_START_LINE to the error queue. If one is found, but there is an error decoding it, it returns zero and pushes some other error to the error queue.

This function does not decrypt encrypted PEM blocks and instead returns the header and (possibly encrypted) data unprocessed. See PEM_bytes_read_bio to decrypt blocks.

OPENSSL_EXPORT int PEM_read_bio(BIO *bio, char **out_name, char **out_header,
                                uint8_t **out_data, long *out_len);

PEM_read behaves like PEM_read_bio but reads from fp.

OPENSSL_EXPORT int PEM_read(FILE *fp, char **out_name, char **out_header,
                            uint8_t **out_data, long *out_len);

PEM_write_bio writes a PEM block to bio, containing len bytes from data as data. name and hdr are NUL-terminated C strings containing the PEM type and header block, respectively. This function returns zero on error and the number of bytes written on success.

OPENSSL_EXPORT int PEM_write_bio(BIO *bio, const char *name, const char *hdr,
                                 const uint8_t *data, long len);

PEM_write behaves like PEM_write_bio but reads from fp.

OPENSSL_EXPORT int PEM_write(FILE *fp, const char *name, const char *hdr,
                             const uint8_t *data, long len);

PEM_bytes_read_bio reads from bio until it finds a PEM block whose name matches expected_name. If one is found, it sets *out_name and *out_data to newly-allocated buffers containing the PEM type and (possibly decrypted) PEM data. *out_name is a NUL-terminated C string, while *out_data has *out_len bytes. The caller must release *out_name and *out_data with OPENSSL_free when done.

If the PEM block is encrypted, cb will be called to look up the password. See pem_password_cb for details. If cb is NULL, PEM_def_callback is used and userdata should be a NUL-terminated C string containing the password. Set both cb and userdata to NULL to only handle plaintext blocks.

expected_name and *out_name may not necessarily be the same value, so callers must check *out_name before decoding *out_data. In addition to an exact match, the following values are also accepted:

  • If expected_name is "CERTIFICATE", the older "X509 CERTIFICATE" type is also accepted.
  • If expected_name is "CERTIFICATE REQUEST", the older "NEW CERTIFICATE REQUEST" type is also accepted.
  • If expected_name is "TRUSTED CERTIFICATE", "CERTIFICATE" and the older "X509 CERTIFICATE" are also accepted.
  • If expected_name is "PKCS7", "PKCS #7 SIGNED DATA" is also accepted.
  • If expected_name is "PKCS7", "CERTIFICATE" is also accepted. This is an exposed implementation detail of PKCS7_get_PEM_certificates, which works around a 2000-era mistake by some CAs.
  • If expected_name is "ANY PRIVATE KEY", the type "ANY PRIVATE KEY" is not accepted and, instead, the function accepts "PRIVATE KEY", "ENCRYPTED PRIVATE KEY", "RSA PRIVATE KEY", "EC PRIVATE KEY", and "DSA PRIVATE KEY". This is an exposed implementation detail of PEM_read_bio_PrivateKey.

TODO(davidben): Can some of the older aliases and workarounds be removed now?

If no PEM block is found, this function returns zero and pushes PEM_R_NO_START_LINE to the error queue. If one is found, but there is an error decoding it, it returns zero and pushes some other error to the error queue.

OPENSSL_EXPORT int PEM_bytes_read_bio(uint8_t **out_data, long *out_len,
                                      char **out_name,
                                      const char *expected_name, BIO *bio,
                                      pem_password_cb *cb, void *userdata);

Reading and writing DER-encoded private keys.

d2i_PKCS8PrivateKey_bio reads a DER-encoded EncryptedPrivateKey structure (RFC 5208) from bio, decrypts it with PKCS8_decrypt, and returns the result as a newly-allocated EVP_PKEY, or NULL on error. On success, if out is non-NULL, it additionally frees the previous value at *out and updates *out to the result. The password is determined by calling cb, or PEM_def_callback if NULL.

OPENSSL_EXPORT EVP_PKEY *d2i_PKCS8PrivateKey_bio(BIO *bio, EVP_PKEY **out,
                                                 pem_password_cb *cb,
                                                 void *userdata);

i2d_PKCS8PrivateKey_bio encodes in as a DER-encoded structure and writes it to bio. It returns one on success and zero on error. The structure used depends on enc:

  • If enc is NULL, it writes a PrivateKeyInfo structure (RFC 5208).
  • If enc is non-NULL, it writes an EncryptedPrivateKeyInfo structure (RFC 5280). The key is encrypted with PBES2, as in PKCS8_encrypt. The password is specified by pass, cb, and userdata, as in PEM_write_bio_SAMPLE.

WARNING: PrivateKeyInfo and EncryptedPrivateKeyInfo are different formats, and DER does not include a type header. The encrypted and unencrypted modes of this function should not be mixed in the same context.

OPENSSL_EXPORT int i2d_PKCS8PrivateKey_bio(BIO *bio, const EVP_PKEY *in,
                                           const EVP_CIPHER *enc,
                                           const char *pass, int pass_len,
                                           pem_password_cb *cb, void *userdata);

i2d_PKCS8PrivateKey_nid_bio encodes in as a DER-encoded structure and writes it to bio. It returns one on success and zero on error. The structure used depends on nid:

  • If nid is -1, it writes a PrivateKeyInfo structure (RFC 5208).
  • Otherwise, it writes an EncryptedPrivateKeyInfo structure (RFC 5280). The key is encrypted with PBES1, as in PKCS8_encrypt. The password is specified by pass, cb, and userdata, as in PEM_write_bio_SAMPLE.

WARNING: PrivateKeyInfo and EncryptedPrivateKeyInfo are different formats, and DER does not include a type header. The encrypted and unencrypted modes of this function should not be mixed in the same context.

OPENSSL_EXPORT int i2d_PKCS8PrivateKey_nid_bio(BIO *bio, const EVP_PKEY *in,
                                               int nid, const char *pass,
                                               int pass_len,
                                               pem_password_cb *cb,
                                               void *userdata);

i2d_PKCS8PrivateKey_fp behaves like i2d_PKCS8PrivateKey_bio but writes to fp.

OPENSSL_EXPORT int i2d_PKCS8PrivateKey_fp(FILE *fp, const EVP_PKEY *in,
                                          const EVP_CIPHER *enc,
                                          const char *pass, int pass_len,
                                          pem_password_cb *cb, void *userdata);

i2d_PKCS8PrivateKey_nid_fp behaves like i2d_PKCS8PrivateKey_nid_bio but writes to fp.

OPENSSL_EXPORT int i2d_PKCS8PrivateKey_nid_fp(FILE *fp, const EVP_PKEY *in,
                                              int nid, const char *pass,
                                              int pass_len, pem_password_cb *cb,
                                              void *userdata);

d2i_PKCS8PrivateKey_fp behaves like d2i_PKCS8PrivateKey_bio but reads from fp.

OPENSSL_EXPORT EVP_PKEY *d2i_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY **out,
                                                pem_password_cb *cb,
                                                void *userdata);

Internal functions.

The following functions are used to implement PEM_read_bio_* and PEM_write_bio_*. They should not be used outside the library.

PEM_ASN1_read_bio calls PEM_bytes_read_bio and then decodes the resulting data with d2i, which should behave as in d2i_SAMPLE.

OPENSSL_EXPORT void *PEM_ASN1_read_bio(d2i_of_void *d2i, const char *name,
                                       BIO *bio, void **out,
                                       pem_password_cb *cb, void *userdata);

PEM_ASN1_read behaves like PEM_ASN1_read_bio but reads from fp.

OPENSSL_EXPORT void *PEM_ASN1_read(d2i_of_void *d2i, const char *name, FILE *fp,
                                   void **out, pem_password_cb *cb,
                                   void *userdata);

PEM_ASN1_write_bio encodes in with i2d, which should behave as in i2d_SAMPLE. It then writes the result to bio as in PEM_write_bio_SAMPLE.

OPENSSL_EXPORT int PEM_ASN1_write_bio(i2d_of_void *i2d, const char *name,
                                      BIO *bio, const void *in,
                                      const EVP_CIPHER *enc,
                                      const uint8_t *pass, int pass_len,
                                      pem_password_cb *cb, void *userdata);

PEM_ASN1_write behaves like PEM_ASN1_write_bio but reads from fp.

OPENSSL_EXPORT int PEM_ASN1_write(i2d_of_void *i2d, const char *name, FILE *fp,
                                  const void *in, const EVP_CIPHER *enc,
                                  const uint8_t *pass, int pass_len,
                                  pem_password_cb *callback, void *userdata);