diff options
Diffstat (limited to 'doc/crypto/PEM_read.pod')
| -rw-r--r-- | doc/crypto/PEM_read.pod | 127 |
1 files changed, 0 insertions, 127 deletions
diff --git a/doc/crypto/PEM_read.pod b/doc/crypto/PEM_read.pod deleted file mode 100644 index 66cbc7d243..0000000000 --- a/doc/crypto/PEM_read.pod +++ /dev/null @@ -1,127 +0,0 @@ -=pod - -=head1 NAME - -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); - -=head1 DESCRIPTION - -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 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 successfully 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 successful 1 is returned 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_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. - -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. - -=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<PEM_write_PrivateKey(3)> and L<d2i_PKCS8PrivateKey_bio(3)>. - -=head1 SEE ALSO - -L<ERR_peek_last_error(3)>, L<ERR_GET_LIB(3)>, -L<d2i_PKCS8PrivateKey_bio(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 |