// Copyright 1995-2016 The OpenSSL Project Authors. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#ifndef OPENSSL_HEADER_PEM_H
#define OPENSSL_HEADER_PEM_H

#include <openssl/base64.h>
#include <openssl/bio.h>
#include <openssl/cipher.h>
#include <openssl/digest.h>
#include <openssl/evp.h>
#include <openssl/pkcs7.h>
#include <openssl/stack.h>
#include <openssl/x509.h>

// For compatibility with open-iscsi, which assumes that it can get
// `OPENSSL_malloc` from pem.h or err.h
#include <openssl/crypto.h>

#if defined(__cplusplus)
extern "C" {
#endif


// 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.


// 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);


#if defined(__cplusplus)
}  // extern C
#endif

#define PEM_R_BAD_BASE64_DECODE 100
#define PEM_R_BAD_DECRYPT 101
#define PEM_R_BAD_END_LINE 102
#define PEM_R_BAD_IV_CHARS 103
#define PEM_R_BAD_PASSWORD_READ 104
#define PEM_R_CIPHER_IS_NULL 105
#define PEM_R_ERROR_CONVERTING_PRIVATE_KEY 106
#define PEM_R_NOT_DEK_INFO 107
#define PEM_R_NOT_ENCRYPTED 108
#define PEM_R_NOT_PROC_TYPE 109
#define PEM_R_NO_START_LINE 110
#define PEM_R_READ_KEY 111
#define PEM_R_SHORT_HEADER 112
#define PEM_R_UNSUPPORTED_CIPHER 113
#define PEM_R_UNSUPPORTED_ENCRYPTION 114
#define PEM_R_UNSUPPORTED_PROC_TYPE_VERSION 115
#define PEM_R_NO_DATA 116

#endif  // OPENSSL_HEADER_PEM_H