X-Git-Url: https://code.wpia.club/?a=blobdiff_plain;f=lib%2Fopenssl%2Fdoc%2Fcrypto%2FPEM_read.pod;fp=lib%2Fopenssl%2Fdoc%2Fcrypto%2FPEM_read.pod;h=66cbc7d2433cc1eefb241fa3aea0345734aabcdb;hb=02ed66432c92de70694700164f986190aad3cbc5;hp=0000000000000000000000000000000000000000;hpb=89016837dcbf2775cd15dc8cbaba00dc6379f86e;p=cassiopeia.git diff --git a/lib/openssl/doc/crypto/PEM_read.pod b/lib/openssl/doc/crypto/PEM_read.pod new file mode 100644 index 0000000..66cbc7d --- /dev/null +++ b/lib/openssl/doc/crypto/PEM_read.pod @@ -0,0 +1,127 @@ +=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 + + 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, any additional B
information, and the raw +B of length B. + +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, while PEM_write_bio() writes to +the BIO B. The B is the name to use in the marker, the +B
is the header value or NULL, and B and B specify +the data and its length. + +The final B buffer is typically an ASN.1 object which can be decoded with +the B function appropriate to the type B; see L +for examples. + +PEM_read() reads from the file B, while PEM_read_bio() reads +from the BIO B. +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 +-----" is returned via the B argument, any encapsulation headers +are returned in B
and the base64-decoded content and its length are +returned via B and B respectively. +The B, B
and B 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 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 via the +B argument and the B
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. +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 below. + +PEM_do_header() can then be used to decrypt the data if the header +indicates encryption. +The B argument is a pointer to the structure initialized by the previous +call to PEM_get_EVP_CIPHER_INFO(). +The B and B arguments are those returned by the previous call to +PEM_read() or PEM_read_bio(). +The B and B arguments make it possible to override the default password +prompt function as described in L. +On successful completion the B is decrypted in place, and B is +updated to indicate the plaintext length. +This function is deprecated, see B 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, which indicates that no more +PEM objects were found. See L, L. + +PEM_get_EVP_CIPHER_INFO() and PEM_do_header() return 1 on success, and 0 on +failure. +The B 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 and L. + +=head1 SEE ALSO + +L, L, +L. + +=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. + +=cut