101 lines
4.1 KiB
Text
101 lines
4.1 KiB
Text
=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)>.
|
|
|
|
=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
|