#include <openssl/pem.h>
- typedef int (*pem_password_cb)(char *buf, int size, int rwflag, void *u);
+ typedef int pem_password_cb(char *buf, int size, int rwflag, void *u);
EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x,
pem_password_cb *cb, void *u);
B<PEM FUNCTION ARGUMENTS> section.
Each operation has four functions associated with it. For
-clarity the term "B<foobar> functions" will be used to collectively
-refer to the PEM_read_bio_foobar(), PEM_read_foobar(),
-PEM_write_bio_foobar() and PEM_write_foobar() functions.
+brevity the term "B<TYPE> functions" will be used below to collectively
+refer to the PEM_read_bio_TYPE(), PEM_read_TYPE(),
+PEM_write_bio_TYPE(), and PEM_write_TYPE() functions.
The B<PrivateKey> functions read or write a private key in PEM format using an
EVP_PKEY structure. The write routines use PKCS#8 private key format and are
equivalent to PEM_write_bio_PKCS8PrivateKey().The read functions transparently
handle traditional and PKCS#8 format encrypted and unencrypted keys.
-PEM_write_bio_PrivateKey_traditional() writes out a private key in legacy
-"traditional" format.
+PEM_write_bio_PrivateKey_traditional() writes out a private key in the
+"traditional" format with a simple private key marker and should only
+be used for compatibility with legacy programs.
PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() write a private
key in an EVP_PKEY structure in PKCS#8 EncryptedPrivateKeyInfo format using
value as the B<u> parameter passed to the PEM routine. It allows
arbitrary data to be passed to the callback by the application
(for example a window handle in a GUI application). The callback
-B<must> return the number of characters in the passphrase or 0 if
+B<must> return the number of characters in the passphrase or -1 if
an error occurred.
-=head1 EXAMPLES
-
-Although the PEM routines take several arguments in almost all applications
-most of them are set to 0 or NULL.
-
-Read a certificate in PEM format from a BIO:
-
- X509 *x;
- x = PEM_read_bio_X509(bp, NULL, 0, NULL);
- if (x == NULL)
- /* Error */
-
-Alternative method:
-
- X509 *x = NULL;
- if (!PEM_read_bio_X509(bp, &x, 0, NULL))
- /* Error */
-
-Write a certificate to a BIO:
-
- if (!PEM_write_bio_X509(bp, x))
- /* Error */
-
-Write a private key (using traditional format) to a BIO using
-triple DES encryption, the pass phrase is prompted for:
-
- if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL))
- /* Error */
-
-Write a private key (using PKCS#8 format) to a BIO using triple
-DES encryption, using the pass phrase "hello":
-
- if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(),
- NULL, 0, 0, "hello"))
- /* Error */
-
-Read a private key from a BIO using a pass phrase callback:
-
- key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
- if (key == NULL)
- /* Error */
-
-Skeleton pass phrase callback:
-
- int pass_cb(char *buf, int size, int rwflag, void *u)
- {
- int len;
- char *tmp;
-
- /* We'd probably do something else if 'rwflag' is 1 */
- printf("Enter pass phrase for \"%s\"\n", (char *)u);
-
- /* get pass phrase, length 'len' into 'tmp' */
- tmp = "hello";
- len = strlen(tmp);
- if (len <= 0)
- return 0;
-
- if (len > size)
- len = size;
- memcpy(buf, tmp, len);
- return len;
- }
-
=head1 NOTES
The old B<PrivateKey> write routines are retained for compatibility.
this:
X509 *x;
+
PEM_read_bio_X509(bp, &x, 0, NULL);
this is a bug because an attempt will be made to reuse the data at B<x>
which is an uninitialised pointer.
+These functions make no assumption regarding the pass phrase received from the
+password callback.
+It will simply be treated as a byte sequence.
+
=head1 PEM ENCRYPTION FORMAT
These old B<PrivateKey> routines use a non standard technique for encryption.
is guaranteed to work.
-=head1 RETURN CODES
+=head1 RETURN VALUES
The read routines return either a pointer to the structure read or NULL
if an error occurred.
The write routines return 1 for success or 0 for failure.
+=head1 EXAMPLES
+
+Although the PEM routines take several arguments in almost all applications
+most of them are set to 0 or NULL.
+
+Read a certificate in PEM format from a BIO:
+
+ X509 *x;
+
+ x = PEM_read_bio_X509(bp, NULL, 0, NULL);
+ if (x == NULL)
+ /* Error */
+
+Alternative method:
+
+ X509 *x = NULL;
+
+ if (!PEM_read_bio_X509(bp, &x, 0, NULL))
+ /* Error */
+
+Write a certificate to a BIO:
+
+ if (!PEM_write_bio_X509(bp, x))
+ /* Error */
+
+Write a private key (using traditional format) to a BIO using
+triple DES encryption, the pass phrase is prompted for:
+
+ if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL))
+ /* Error */
+
+Write a private key (using PKCS#8 format) to a BIO using triple
+DES encryption, using the pass phrase "hello":
+
+ if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(),
+ NULL, 0, 0, "hello"))
+ /* Error */
+
+Read a private key from a BIO using a pass phrase callback:
+
+ key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
+ if (key == NULL)
+ /* Error */
+
+Skeleton pass phrase callback:
+
+ int pass_cb(char *buf, int size, int rwflag, void *u)
+ {
+
+ /* We'd probably do something else if 'rwflag' is 1 */
+ printf("Enter pass phrase for \"%s\"\n", (char *)u);
+
+ /* get pass phrase, length 'len' into 'tmp' */
+ char *tmp = "hello";
+ if (tmp == NULL) /* An error occurred */
+ return -1;
+
+ size_t len = strlen(tmp);
+
+ if (len > size)
+ len = size;
+ memcpy(buf, tmp, len);
+ return len;
+ }
+
=head1 HISTORY
The old Netscape certificate sequences were no longer documented
-in OpenSSL 1.1; applications should use the PKCS7 standard instead
+in OpenSSL 1.1.0; applications should use the PKCS7 standard instead
as they will be formally deprecated in a future releases.
=head1 SEE ALSO
-L<EVP_EncryptInit(3)>, L<EVP_BytesToKey(3)>
+L<EVP_EncryptInit(3)>, L<EVP_BytesToKey(3)>,
+L<passphrase-encoding(7)>
=head1 COPYRIGHT
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved.
-Licensed under the OpenSSL license (the "License"). You may not use
+Licensed under the Apache License 2.0 (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>.
projects / openssl.git / blobdiff