From 12ce9ea25d3437f8097520567a493669ebde44e9 Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Thu, 9 Jun 2016 08:34:17 -0400 Subject: [PATCH] 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 --- doc/crypto/{pem_read.pod => PEM_read.pod} | 51 +++- doc/crypto/PEM_read_CMS.pod | 94 +++++++ doc/crypto/PEM_write_bio_CMS_stream.pod | 1 + doc/crypto/X509_dup.pod | 300 ++++++++++++++++++++++ 4 files changed, 435 insertions(+), 11 deletions(-) rename doc/crypto/{pem_read.pod => PEM_read.pod} (70%) create mode 100644 doc/crypto/PEM_read_CMS.pod create mode 100644 doc/crypto/X509_dup.pod diff --git a/doc/crypto/pem_read.pod b/doc/crypto/PEM_read.pod similarity index 70% rename from doc/crypto/pem_read.pod rename to 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 + 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, any encapsulation B
and the decoded +These functions read and write PEM-encoded objects, using the PEM +type B, any additional B
information, and the raw B of length B. -PEM_read() reads from the stdio file handle B, while PEM_read_bio() reads -from the BIO B. +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, while PEM_write_bio() writes to +the BIO B. The B is the name to use in the marker, the +B
is the header value or NULL, and B and B specify +the data and its length. + +The final B buffer is typically an ASN.1 object which can be decoded with +the B function appropriate to the type B; see L +for examples. + +PEM_read() reads from the file B, while PEM_read_bio() reads +from the BIO B. 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 -----" is returned via the B argument, any encapsulation headers @@ -50,7 +82,7 @@ call to PEM_get_EVP_CIPHER_INFO(). The B and B arguments are those returned by the previous call to PEM_read() or PEM_read_bio(). The B and B arguments make it possible to override the default password -prompt function as described in L. +prompt function as described in L. On successful completion the B is decrypted in place, and B is updated to indicate the plaintext length. This function is deprecated, see B below. @@ -58,9 +90,6 @@ This function is deprecated, see B 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 buffer is typically an ASN.1 object which can be decoded with -the B function appropriate to the type B. - =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 and L and L. +See L and L. =head1 SEE ALSO -L, L, L, L, +L, L, L. =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 + + #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 is used +as a placeholder for any of the OpenSSL datatypes, such as I. + +These routines convert between local instances of ASN1 datatypes and +the PEM encoding. For more information on the templates, see +L. For more information on the lower-level routines used +by the functions here, see L. + +PEM_read_TYPE() reads a PEM-encoded object of I from the file B +and returns it. The B and B parameters are as described in +L. + +PEM_read_bio_TYPE() is similar to PEM_read_TYPE() but reads from the BIO B. + +PEM_write_TYPE() writes the PEM encoding of the object B to the file B. + +PEM_write_bio_TYPE() similarly writes to the BIO B. + +=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 + +=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. + +=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, L, L, L L, +L, L, L 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 + + #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 is used +as a placeholder for any of the OpenSSL datatypes, such as I. + +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 on the specified BIO B. +Each line will be prefixed with B spaces. +The B 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 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. + +=cut -- 2.34.1