X-Git-Url: https://git.openssl.org/gitweb/?a=blobdiff_plain;f=doc%2Fman3%2FPEM_read_bio_PrivateKey.pod;h=69ff679b2d1ccc54f7ab55d189ce448fc8bb96c9;hb=8c47e55ee69500e31e80458682c6e022294cd0be;hp=5fb14e9cef5839d2be5ad3844781dbaea43d0252;hpb=e9b77246879071308130cda42336338ddb63cbb4;p=openssl.git diff --git a/doc/man3/PEM_read_bio_PrivateKey.pod b/doc/man3/PEM_read_bio_PrivateKey.pod index 5fb14e9cef..69ff679b2d 100644 --- a/doc/man3/PEM_read_bio_PrivateKey.pod +++ b/doc/man3/PEM_read_bio_PrivateKey.pod @@ -30,13 +30,13 @@ PEM_write_bio_PKCS7, PEM_write_PKCS7 - PEM routines #include - 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); EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x, pem_password_cb *cb, void *u); - int PEM_write_bio_PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, + int PEM_write_bio_PrivateKey(BIO *bp, const EVP_PKEY *x, const EVP_CIPHER *enc, unsigned char *kstr, int klen, pem_password_cb *cb, void *u); int PEM_write_bio_PrivateKey_traditional(BIO *bp, EVP_PKEY *x, @@ -46,17 +46,16 @@ PEM_write_bio_PKCS7, PEM_write_PKCS7 - PEM routines int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, unsigned char *kstr, int klen, pem_password_cb *cb, void *u); - int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, char *kstr, int klen, pem_password_cb *cb, void *u); int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, char *kstr, int klen, pem_password_cb *cb, void *u); - int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid, + int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, const EVP_PKEY *x, int nid, char *kstr, int klen, pem_password_cb *cb, void *u); - int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid, + int PEM_write_PKCS8PrivateKey_nid(FILE *fp, const EVP_PKEY *x, int nid, char *kstr, int klen, pem_password_cb *cb, void *u); @@ -161,17 +160,18 @@ For more details about the meaning of arguments see the B section. Each operation has four functions associated with it. For -clarity the term "B 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 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 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 @@ -294,75 +294,9 @@ for it twice) if B is 1. The B parameter has the same value as the B 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 return the number of characters in the passphrase or 0 if +B 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 write routines are retained for compatibility. @@ -385,6 +319,10 @@ this: this is a bug because an attempt will be made to reuse the data at B 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 routines use a non standard technique for encryption. @@ -449,28 +387,94 @@ where B already contains a valid certificate, may not work, whereas: 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 HISTORY +=head1 EXAMPLES -The old Netscape certificate sequences were no longer documented -in OpenSSL 1.1; applications should use the PKCS7 standard instead -as they will be formally deprecated in a future releases. +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 SEE ALSO -L, L +L, L, +L + +=head1 HISTORY + +The old Netscape certificate sequences were no longer documented +in OpenSSL 1.1.0; applications should use the PKCS7 standard instead +as they will be formally deprecated in a future releases. =head1 COPYRIGHT -Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2001-2019 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.