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