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>
This commit is contained in:
Rich Salz 2016-06-09 08:34:17 -04:00
parent dc567f6244
commit 12ce9ea25d
4 changed files with 435 additions and 11 deletions

View file

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

View file

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

View file

@ -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)>

300
doc/crypto/X509_dup.pod Normal file
View file

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