diff options
author | Viktor Dukhovni <openssl-users@dukhovni.org> | 2016-04-24 19:48:50 -0400 |
---|---|---|
committer | Viktor Dukhovni <openssl-users@dukhovni.org> | 2016-05-19 00:05:30 -0400 |
commit | 67787844f11fd7614bb26452fda1a1de3ed005ef (patch) | |
tree | 2f959f1071b93f6f5097c7e806bf85bcce0a7708 /doc | |
parent | 276fa9bda99d12666441277afa39f81ae374437d (diff) | |
download | openssl-67787844f11fd7614bb26452fda1a1de3ed005ef.tar.gz |
Improve and document low-level PEM read routines
PEM_read(), PEM_read_bio(), PEM_get_EVP_CIPHER_INFO() and
PEM_do_header().
Reviewed-by: Dr. Stephen Henson <steve@openssl.org>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/crypto/pem_read.pod | 90 |
1 files changed, 90 insertions, 0 deletions
diff --git a/doc/crypto/pem_read.pod b/doc/crypto/pem_read.pod new file mode 100644 index 0000000000..b0ec0d8eca --- /dev/null +++ b/doc/crypto/pem_read.pod @@ -0,0 +1,90 @@ +=pod + +=head1 NAME + +PEM_read, PEM_read_bio, PEM_do_header - low-level PEM routines + +=head1 SYNOPSIS + + #include <openssl/pem.h> + + 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); + +=head1 DESCRIPTION + +These functions read and decode PEM-encoded objects, returning the +PEM type B<name>, any encapsulation B<header> and the decoded +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>. +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 +are returned in B<header> and the base64-decoded content and its length are +returned via B<data> and B<len> respectively. +The B<name>, B<header> and B<data> pointers are allocated via OPENSSL_malloc() +and should be freed by the caller via OPENSSL_free() when no longer needed. + +PEM_get_EVP_CIPHER_INFO() can be used to determine the B<data> returned by +PEM_read() or PEM_read_bio() is encrypted and to retrieve the associated cipher +and IV. +The caller passes a pointer to structure of type B<EVP_CIPHER_INFO> via the +B<cinfo> argument and the B<header> returned via PEM_read() or PEM_read_bio(). +If the call is succesful 1 is retured and the cipher and IV are stored at the +address pointed to by B<cinfo>. +When the header is malformed, or not supported or when the cipher is unknown +or some internal error happens 0 is returned. +This function is deprecated, see B<NOTES> below. + +PEM_do_header() can then be used to decrypt the data if the header +indicates encryption. +The B<cinfo> argument is a pointer to the structure initialized by the previous +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)>. +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 +includes the case when no more PEM objects remain in the input file. +To distinguish end of file from more serious errors the caller must peek at the +error stack and check for B<PEM_R_NO_START_LINE>, which indicates that no more +PEM objects were found. See L<ERR_peek_last_error(3)>, L<ERR_GET_REASON(3)>. + +PEM_get_EVP_CIPHER_INFO() and PEM_do_header() return 1 on success, and 0 on +failure. +The B<data> is likely meaningless if these functions fail. + +=head1 NOTES + +The PEM_get_EVP_CIPHER_INFO() and PEM_do_header() functions are deprecated. +This is because the underlying PEM encryption format is obsolete, and should +be avoided. +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)>. + +=head1 SEE ALSO + +L<pem(3)>, L<ERR_peek_last_error(3)>, L<ERR_GET_LIB(3)>, L<pkcs8(1)>, +L<d2i_PKCS8PrivateKey_bio(3)>. |