Write X509_dup, PEM_read, etc.

Partially document the ASN1 template stuff, and its use for i2d/d2i
and PEM I/O.

Reviewed-by: Richard Levitte <levitte@openssl.org>

4 files changed, 435 insertions, 11 deletions

diff --git a/doc/crypto/pem_read.pod b/doc/crypto/PEM_read.pod
index 7123dd8934..c0bd010e40 100644
--- a/doc/crypto/pem_read.pod
+++ b/doc/crypto/PEM_read.pod
@@ -2,28 +2,60 @@
 
 =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
@@ -50,7 +82,7 @@ call to PEM_get_EVP_CIPHER_INFO().
 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.
@@ -58,9 +90,6 @@ 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
@@ -82,11 +111,11 @@ It uses an encryption format with an OpenSSL-specific key-derivation function,
 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
diff --git a/doc/crypto/PEM_read_CMS.pod b/doc/crypto/PEM_read_CMS.pod
new file mode 100644
index 0000000000..5a799f9e89
--- /dev/null
+++ b/doc/crypto/PEM_read_CMS.pod
@@ -0,0 +1,94 @@
+=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
diff --git a/doc/crypto/PEM_write_bio_CMS_stream.pod b/doc/crypto/PEM_write_bio_CMS_stream.pod
index cc0520b70c..c73fafd44b 100644
--- a/doc/crypto/PEM_write_bio_CMS_stream.pod
+++ b/doc/crypto/PEM_write_bio_CMS_stream.pod
@@ -30,6 +30,7 @@ PEM_write_bio_CMS_stream() returns 1 for success or 0 for failure.
 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)>
 
diff --git a/doc/crypto/X509_dup.pod b/doc/crypto/X509_dup.pod
new file mode 100644
index 0000000000..e1dd91c338
--- /dev/null
+++ b/doc/crypto/X509_dup.pod
@@ -0,0 +1,300 @@
+=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