Write X509_dup, PEM_read, etc.

=head1 NAME

PEM_read, PEM_read_bio, PEM_do_header - low-level PEM routines

PEM_write, PEM_write_bio,

PEM_read, PEM_read_bio, PEM_do_header, PEM_get_EVP_CIPHER_INFO,

pem_password_cb

- PEM encoding routines

=head1 SYNOPSIS

 #include <openssl/pem.h>

 int PEM_write(FILE *fp, const char *name, const char *header,

               const unsigned char *data, long len)

 int PEM_write_bio(BIO *bp, const char *name, const char *header,

                   const unsigned char *data, long len)

 int PEM_read(FILE *fp, char **name, char **header,

              unsigned char **data, long *len);

 int PEM_read_bio(BIO *bp, char **name, char **header,

                  unsigned char **data, long *len);

 int PEM_get_EVP_CIPHER_INFO(char *header, EVP_CIPHER_INFO *cinfo);

 int PEM_do_header(EVP_CIPHER_INFO *cinfo, unsigned char *data, long *len,

                   pem_password_cb *cb, void *u);

 typedef int pem_password_cb (char *buf, int size, int rwflag, void *u);

=head1 DESCRIPTION

These functions read and decode PEM-encoded objects, returning the

PEM type B<name>, any encapsulation B<header> and the decoded

These functions read and write PEM-encoded objects, using the PEM

type B<name>, any additional B<header> information, and the raw

B<data> of length B<len>.

PEM_read() reads from the stdio file handle B<fp>, while PEM_read_bio() reads

from the BIO B<bio>.

PEM is the term used for binary content encoding first defined in IETF

RFC 1421.  The content is a series of base64-encoded lines, surrounded

by begin/end markers each on their own line.  For example:

 -----BEGIN PRIVATE KEY-----

 MIICdg....

 ... bhTQ==

 -----END PRIVATE KEY-----

Optional header line(s) may appear after the begin line, and their

existence depends on the type of object being written or read.

PEM_write() writes to the file B<fp>, while PEM_write_bio() writes to

the BIO B<bp>.  The B<name> is the name to use in the marker, the

B<header> is the header value or NULL, and B<data> and B<len> specify

the data and its length.

The final B<data> buffer is typically an ASN.1 object which can be decoded with

the B<d2i> function appropriate to the type B<name>; see L<d2i_X509(3)>

for examples.

PEM_read() reads from the file B<fp>, while PEM_read_bio() reads

from the BIO B<bp>.

Both skip any non-PEM data that precedes the start of the next PEM object.

When an object is successfuly retrieved, the type name from the "----BEGIN

<type>-----" is returned via the B<name> argument, any encapsulation headers

The B<data> and B<len> arguments are those returned by the previous call to

PEM_read() or PEM_read_bio().

The B<cb> and B<u> arguments make it possible to override the default password

prompt function as described in L<pem(3)>.

prompt function as described in L<PEM_read_PrivateKey(3)>.

On successful completion the B<data> is decrypted in place, and B<len> is

updated to indicate the plaintext length.

This function is deprecated, see B<NOTES> below.

If the data is a priori known to not be encrypted, then neither PEM_do_header()

nor PEM_get_EVP_CIPHER_INFO() need be called.

The final B<data> buffer is typically an ASN.1 object which can be decoded with

the B<d2i> function appropriate to the type B<name>.

=head1 RETURN VALUES

PEM_read() and PEM_read_bio() return 1 on success and 0 on failure, the latter

which employs MD5 with an iteration count of 1!

Instead, private keys should be stored in PKCS#8 form, with a strong PKCS#5

v2.0 PBE.

See L<pkcs8(1)> and L<pem(3)> and L<d2i_PKCS8PrivateKey_bio(3)>.

See L<PEM_write_PrivateKey(3)> and L<d2i_PKCS8PrivateKey_bio(3)>.

=head1 SEE ALSO

L<pem(3)>, L<ERR_peek_last_error(3)>, L<ERR_GET_LIB(3)>, L<pkcs8(1)>,

L<ERR_peek_last_error(3)>, L<ERR_GET_LIB(3)>,

L<d2i_PKCS8PrivateKey_bio(3)>.

=head1 COPYRIGHT

=pod

=head1 NAME

PEM_read_CMS,

PEM_read_bio_CMS,

PEM_write_CMS,

PEM_write_bio_CMS,

PEM_write_DHxparams,

PEM_write_bio_DHxparams,

PEM_read_ECPKParameters,

PEM_read_bio_ECPKParameters,

PEM_write_ECPKParameters,

PEM_write_bio_ECPKParameters,

PEM_read_ECPrivateKey,

PEM_write_ECPrivateKey,

PEM_write_bio_ECPrivateKey,

PEM_read_EC_PUBKEY,

PEM_read_bio_EC_PUBKEY,

PEM_write_EC_PUBKEY,

PEM_write_bio_EC_PUBKEY,

PEM_read_NETSCAPE_CERT_SEQUENCE,

PEM_read_bio_NETSCAPE_CERT_SEQUENCE,

PEM_write_NETSCAPE_CERT_SEQUENCE,

PEM_write_bio_NETSCAPE_CERT_SEQUENCE,

PEM_read_PKCS8,

PEM_read_bio_PKCS8,

PEM_write_PKCS8,

PEM_write_bio_PKCS8,

PEM_write_PKCS8_PRIV_KEY_INFO,

PEM_read_bio_PKCS8_PRIV_KEY_INFO,

PEM_read_PKCS8_PRIV_KEY_INFO,

PEM_write_bio_PKCS8_PRIV_KEY_INFO,

PEM_read_SSL_SESSION,

PEM_read_bio_SSL_SESSION,

PEM_write_SSL_SESSION,

PEM_write_bio_SSL_SESSION

- PEM object encoding routines

=for comment generic

=head1 SYNOPSIS

 #include <openssl/pem.h>

 #define DECLARE_PEM_rw(name, TYPE) ...

 TYPE *PEM_read_TYPE(FILE *fp, TYPE **a, pem_password_cb *cb, void *u);

 TYPE *PEM_read_bio_TYPE(BIO *bp, TYPE **a, pem_password_cb *cb, void *u);

 int PEM_write_TYPE(FILE *fp, const TYPE *a);

 int PEM_write_bio_TYPE(BIO *bp, const TYPE *a);

=head1 DESCRIPTION

In the description below, I<TYPE> is used

as a placeholder for any of the OpenSSL datatypes, such as I<X509>.

These routines convert between local instances of ASN1 datatypes and

the PEM encoding.  For more information on the templates, see

L<ASN1_ITEM(3)>.  For more information on the lower-level routines used

by the functions here, see L<PEM_read(3)>.

PEM_read_TYPE() reads a PEM-encoded object of I<TYPE> from the file B<fp>

and returns it.  The B<cb> and B<u> parameters are as described in

L<pem_password_cb(3)>.

PEM_read_bio_TYPE() is similar to PEM_read_TYPE() but reads from the BIO B<bp>.

PEM_write_TYPE() writes the PEM encoding of the object B<a> to the file B<fp>.

PEM_write_bio_TYPE() similarly writes to the BIO B<bp>.

=head1 RETURN VALUES

PEM_read_TYPE() and PEM_read_bio_TYPE() return a pointer to an allocated

object, which should be released by calling TYPE_free(), or NULL on error.

PEM_write_TYPE() and PEM_write_bio_TYPE() return the number of bytes written

or zero on error.

=head1 SEE ALSO

L<PEM_read(3)>

=head1 COPYRIGHT

Copyright 1998-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (the "License").  You may not use

this file except in compliance with the License.  You can obtain a copy

in the file LICENSE in the source distribution or at

L<https://www.openssl.org/source/license.html>.

=cut

L<ERR_get_error(3)>, L<CMS_sign(3)>,

L<CMS_verify(3)>, L<CMS_encrypt(3)>

L<CMS_decrypt(3)>,

L<PEM_write(3)>,

L<SMIME_write_CMS(3)>,

L<i2d_CMS_bio_stream(3)>

=pod

=head1 NAME

DECLARE_ASN1_FUNCTIONS,

IMPLEMENT_ASN1_FUNCTIONS,

ASN1_ITEM,

ACCESS_DESCRIPTION_free,

ACCESS_DESCRIPTION_new,

ASIdOrRange_free,

ASIdOrRange_new,

ASIdentifierChoice_free,

ASIdentifierChoice_new,

ASIdentifiers_free,

ASIdentifiers_new,

ASRange_free,

ASRange_new,

AUTHORITY_INFO_ACCESS_free,

AUTHORITY_INFO_ACCESS_new,

AUTHORITY_KEYID_free,

AUTHORITY_KEYID_new,

BASIC_CONSTRAINTS_free,

BASIC_CONSTRAINTS_new,

CERTIFICATEPOLICIES_free,

CERTIFICATEPOLICIES_new,

CMS_ContentInfo_free,

CMS_ContentInfo_new,

CMS_ContentInfo_print_ctx,

CMS_ReceiptRequest_free,

CMS_ReceiptRequest_new,

CRL_DIST_POINTS_free,

CRL_DIST_POINTS_new,

DIRECTORYSTRING_free,

DIRECTORYSTRING_new,

DISPLAYTEXT_free,

DISPLAYTEXT_new,

DIST_POINT_NAME_free,

DIST_POINT_NAME_new,

DIST_POINT_free,

DIST_POINT_new,

DSAparams_dup,

EDIPARTYNAME_free,

EDIPARTYNAME_new,

ESS_CERT_ID_dup,

ESS_CERT_ID_free,

ESS_CERT_ID_new,

ESS_ISSUER_SERIAL_dup,

ESS_ISSUER_SERIAL_free,

ESS_ISSUER_SERIAL_new,

ESS_SIGNING_CERT_dup,

ESS_SIGNING_CERT_free,

ESS_SIGNING_CERT_new,

EXTENDED_KEY_USAGE_free,

EXTENDED_KEY_USAGE_new,

GENERAL_NAMES_free,

GENERAL_NAMES_new,

GENERAL_NAME_dup,

GENERAL_NAME_free,

GENERAL_NAME_new,

GENERAL_SUBTREE_free,

GENERAL_SUBTREE_new,

IPAddressChoice_free,

IPAddressChoice_new,

IPAddressFamily_free,

IPAddressFamily_new,

IPAddressOrRange_free,

IPAddressOrRange_new,

IPAddressRange_free,

IPAddressRange_new,

ISSUING_DIST_POINT_free,

ISSUING_DIST_POINT_new,

NAME_CONSTRAINTS_free,

NAME_CONSTRAINTS_new,

NETSCAPE_CERT_SEQUENCE_free,

NETSCAPE_CERT_SEQUENCE_new,

NETSCAPE_SPKAC_free,

NETSCAPE_SPKAC_new,

NETSCAPE_SPKI_free,

NETSCAPE_SPKI_new,

NOTICEREF_free,

NOTICEREF_new,

OCSP_BASICRESP_free,

OCSP_BASICRESP_new,

OCSP_CERTID_dup,

OCSP_CERTID_new,

OCSP_CERTSTATUS_free,

OCSP_CERTSTATUS_new,

OCSP_CRLID_free,

OCSP_CRLID_new,

OCSP_ONEREQ_free,

OCSP_ONEREQ_new,

OCSP_REQINFO_free,

OCSP_REQINFO_new,

OCSP_RESPBYTES_free,

OCSP_RESPBYTES_new,

OCSP_RESPDATA_free,

OCSP_RESPDATA_new,

OCSP_RESPID_free,

OCSP_RESPID_new,

OCSP_RESPONSE_new,

OCSP_REVOKEDINFO_free,

OCSP_REVOKEDINFO_new,

OCSP_SERVICELOC_free,

OCSP_SERVICELOC_new,

OCSP_SIGNATURE_free,

OCSP_SIGNATURE_new,

OCSP_SINGLERESP_free,

OCSP_SINGLERESP_new,

OTHERNAME_free,

OTHERNAME_new,

PBE2PARAM_free,

PBE2PARAM_new,

PBEPARAM_free,

PBEPARAM_new,

PBKDF2PARAM_free,

PBKDF2PARAM_new,

PKCS12_BAGS_free,

PKCS12_BAGS_new,

PKCS12_MAC_DATA_free,

PKCS12_MAC_DATA_new,

PKCS12_SAFEBAG_free,

PKCS12_SAFEBAG_new,

PKCS12_free,

PKCS12_new,

PKCS7_DIGEST_free,

PKCS7_DIGEST_new,

PKCS7_ENCRYPT_free,

PKCS7_ENCRYPT_new,

PKCS7_ENC_CONTENT_free,

PKCS7_ENC_CONTENT_new,

PKCS7_ENVELOPE_free,

PKCS7_ENVELOPE_new,

PKCS7_ISSUER_AND_SERIAL_free,

PKCS7_ISSUER_AND_SERIAL_new,

PKCS7_RECIP_INFO_free,

PKCS7_RECIP_INFO_new,

PKCS7_SIGNED_free,

PKCS7_SIGNED_new,

PKCS7_SIGNER_INFO_free,

PKCS7_SIGNER_INFO_new,

PKCS7_SIGN_ENVELOPE_free,

PKCS7_SIGN_ENVELOPE_new,

PKCS7_dup,

PKCS7_free,

PKCS7_new,

PKCS7_print_ctx,

PKCS8_PRIV_KEY_INFO_free,

PKCS8_PRIV_KEY_INFO_new,

PKEY_USAGE_PERIOD_free,

PKEY_USAGE_PERIOD_new,

POLICYINFO_free,

POLICYINFO_new,

POLICYQUALINFO_free,

POLICYQUALINFO_new,

POLICY_CONSTRAINTS_free,

POLICY_CONSTRAINTS_new,

POLICY_MAPPING_free,

POLICY_MAPPING_new,

PROXY_CERT_INFO_EXTENSION_free,

PROXY_CERT_INFO_EXTENSION_new,

PROXY_POLICY_free,

PROXY_POLICY_new,

RSAPrivateKey_dup,

RSAPublicKey_dup,

RSA_OAEP_PARAMS_free,

RSA_OAEP_PARAMS_new,

RSA_PSS_PARAMS_free,

RSA_PSS_PARAMS_new,

SCT_LIST_free,

SXNETID_free,

SXNETID_new,

SXNET_free,

SXNET_new,

TLS_FEATURE_free,

TLS_FEATURE_new,

TS_ACCURACY_dup,

TS_ACCURACY_free,

TS_ACCURACY_new,

TS_MSG_IMPRINT_dup,

TS_MSG_IMPRINT_free,

TS_MSG_IMPRINT_new,

TS_REQ_dup,

TS_REQ_free,

TS_REQ_new,

TS_RESP_dup,

TS_RESP_free,

TS_RESP_new,

TS_STATUS_INFO_dup,

TS_STATUS_INFO_free,

TS_STATUS_INFO_new,

TS_TST_INFO_dup,

TS_TST_INFO_free,

TS_TST_INFO_new,

USERNOTICE_free,

USERNOTICE_new,

X509_ALGOR_free,

X509_ALGOR_new,

X509_ATTRIBUTE_dup,

X509_ATTRIBUTE_free,

X509_ATTRIBUTE_new,

X509_CERT_AUX_free,

X509_CERT_AUX_new,

X509_CINF_free,

X509_CINF_new,

X509_CRL_INFO_free,

X509_CRL_INFO_new,

X509_CRL_METHOD_free,

X509_CRL_METHOD_new,

X509_CRL_dup,

X509_CRL_free,

X509_CRL_new,

X509_EXTENSION_dup,

X509_EXTENSION_free,

X509_EXTENSION_new,

X509_NAME_ENTRY_dup,

X509_NAME_ENTRY_free,

X509_NAME_ENTRY_new,

X509_NAME_dup,

X509_NAME_free,

X509_NAME_new,

X509_REQ_INFO_free,

X509_REQ_INFO_new,

X509_REQ_dup,

X509_REQ_free,

X509_REQ_new,

X509_REVOKED_dup,

X509_REVOKED_free,

X509_REVOKED_new,

X509_SIG_free,

X509_SIG_new,

X509_VAL_free,

X509_VAL_new,

X509_dup,

- ASN1 object utilities

=head1 SYNOPSIS

 #include <openssl/asn1t.h>

 #define DECLARE_ASN1_FUNCTIONS(type) ...

 #define IMPLEMENT_ASN1_FUNCTIONS(stname) ...

 typedef struct ASN1_ITEM_st ASN1_ITEM;

 extern const ASN1_ITEM TYPE_it;

 TYPE *TYPE_new(void);

 TYPE *TYPE_dup(TYPE *a);

 void TYPE_free(TYPE *a);

 int TYPE_print_ctx(BIO *out, TYPE *a, int indent, const ASN1_PCTX *pctx);

=head1 DESCRIPTION

In the description below, I<TYPE> is used

as a placeholder for any of the OpenSSL datatypes, such as I<X509>.

The OpenSSL ASN1 parsing library templates are like a data-driven bytecode

interpreter.

Every ASN1 object as a global variable, TYPE_it, that describes the item

such as its fields.  (On systems which cannot export variables from shared

libraries, the global is instead a function which returns a pointer to a

static variable.

The macro DECLARE_ASN1_FUNCTIONS() is typically used in header files

to generate the function declarations.

The macro IMPLEMENT_ASN1_FUNCTIONS() is used once in a source file

to generate the function bodies.

TYPE_new() allocates an empty object of the indicated type.

The object returned must be released by calling TYPE_free().

TYPE_dup() copies an existing object.

TYPE_free() releases the object and all pointers and sub-objects

within it.

TYPE_print_ctx() prints the object B<a> on the specified BIO B<out>.

Each line will be prefixed with B<indent> spaces.

The B<pctx> specifies the printing context and is for internal

use; use NULL to get the default behavior.  If a print function is

user-defined, then pass in any B<pctx> down to any nested calls.

=head1 RETURN VALUES

TYPE_new() and TYPE_dup() return a pointer to the object or NULL on failure.

TYPE_print_ctx() returns 1 on success or zero on failure.

=head1 COPYRIGHT

Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (the "License").  You may not use

this file except in compliance with the License.  You can obtain a copy

in the file LICENSE in the source distribution or at

L<https://www.openssl.org/source/license.html>.

=cut