Write X509_dup, PEM_read, etc.
authorRich Salz <rsalz@openssl.org>
Thu, 9 Jun 2016 12:34:17 +0000 (08:34 -0400)
committerRich Salz <rsalz@openssl.org>
Thu, 9 Jun 2016 20:22:16 +0000 (16:22 -0400)
Partially document the ASN1 template stuff, and its use for i2d/d2i
and PEM I/O.

Reviewed-by: Richard Levitte <levitte@openssl.org>
doc/crypto/PEM_read.pod [moved from doc/crypto/pem_read.pod with 70% similarity]
doc/crypto/PEM_read_CMS.pod [new file with mode: 0644]
doc/crypto/X509_dup.pod [new file with mode: 0644]

similarity index 70%
rename from doc/crypto/pem_read.pod
rename to doc/crypto/PEM_read.pod
index 7123dd8..c0bd010 100644 (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 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);
-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:
+ 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>.
 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)>,
diff --git a/doc/crypto/PEM_read_CMS.pod b/doc/crypto/PEM_read_CMS.pod
new file mode 100644 (file)
index 0000000..5a799f9
--- /dev/null
@@ -0,0 +1,94 @@
+=head1 NAME
+- 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);
+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
+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>.
+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
+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
index cc0520b..c73fafd 100644 (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)>
diff --git a/doc/crypto/X509_dup.pod b/doc/crypto/X509_dup.pod
new file mode 100644 (file)
index 0000000..e1dd91c
--- /dev/null
@@ -0,0 +1,300 @@
+=head1 NAME
+- 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);
+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
+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.
+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.
+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