From 8481434439e421d513350a81a01ba2e2a8e61b6e Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Sun, 13 May 2018 11:35:14 +0200 Subject: [PATCH] Link in passphrase-encoding(7) in relevant documentation Reviewed-by: Andy Polyakov (Merged from https://github.com/openssl/openssl/pull/6179) --- doc/man1/openssl.pod | 3 +++ doc/man3/OSSL_STORE_open.pod | 11 ++++++++++- doc/man3/PEM_bytes_read_bio.pod | 7 ++++++- doc/man3/PEM_read.pod | 7 ++++++- doc/man3/PEM_read_CMS.pod | 9 ++++++++- doc/man3/PEM_read_bio_PrivateKey.pod | 7 ++++++- doc/man3/PKCS12_create.pod | 7 ++++++- doc/man3/PKCS12_newpass.pod | 3 ++- doc/man3/PKCS12_parse.pod | 3 ++- doc/man3/PKCS5_PBKDF2_HMAC.pod | 6 +++++- doc/man3/d2i_PKCS8PrivateKey_bio.pod | 7 ++++++- 11 files changed, 60 insertions(+), 10 deletions(-) diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod index 03c07c053a..a713269129 100644 --- a/doc/man1/openssl.pod +++ b/doc/man1/openssl.pod @@ -439,6 +439,9 @@ password argument is given and a password is required then the user is prompted to enter one: this will typically be read from the current terminal with echoing turned off. +Note that character encoding may be relevant, please see +L. + =over 4 =item B diff --git a/doc/man3/OSSL_STORE_open.pod b/doc/man3/OSSL_STORE_open.pod index 13f3722c4f..b1467f4100 100644 --- a/doc/man3/OSSL_STORE_open.pod +++ b/doc/man3/OSSL_STORE_open.pod @@ -112,6 +112,14 @@ URI, or if it's a different error (such as memory allocation failures); if the URI was parsable but the scheme unregistered, the top error will have the reason C. +These functions make no direct assumption regarding the pass phrase received +from the password callback. +The loaders may make assumptions, however. +For example, the B scheme loader inherits the assumptions made by +OpenSSL functionality that handles the different file types; this is mostly +relevant for PKCS#12 objects. +See L for further information. + =head1 RETURN VALUES OSSL_STORE_open() returns a pointer to a B on success, or @@ -132,7 +140,8 @@ OSSL_STORE_ctrl() and OSSL_STORE_close() returns 1 on success, or 0 on failure. =head1 SEE ALSO -L, L, L +L, L, L, +L =head1 HISTORY diff --git a/doc/man3/PEM_bytes_read_bio.pod b/doc/man3/PEM_bytes_read_bio.pod index d16ccd8c13..cd05582a80 100644 --- a/doc/man3/PEM_bytes_read_bio.pod +++ b/doc/man3/PEM_bytes_read_bio.pod @@ -55,6 +55,10 @@ use of BIO_s_file() indicates the use of the operating system stdio functionality, which includes buffering as a feature; BIO_s_fd() is likely to be more appropriate in such cases. +These functions make no assumption regarding the pass phrase received from the +password callback. +It will simply be treated as a byte sequence. + =head1 RETURN VALUES PEM_bytes_read_bio() and PEM_bytes_read_bio_secmem() return 1 for success or @@ -63,7 +67,8 @@ PEM_bytes_read_bio() and PEM_bytes_read_bio_secmem() return 1 for success or =head1 SEE ALSO L, -L +L, +L =head1 HISTORY diff --git a/doc/man3/PEM_read.pod b/doc/man3/PEM_read.pod index 66cbc7d243..2a017c67b3 100644 --- a/doc/man3/PEM_read.pod +++ b/doc/man3/PEM_read.pod @@ -110,10 +110,15 @@ Instead, private keys should be stored in PKCS#8 form, with a strong PKCS#5 v2.0 PBE. See L and L. +PEM_do_header() makes no assumption regarding the pass phrase received from the +password callback. +It will simply be treated as a byte sequence. + =head1 SEE ALSO L, L, -L. +L, +L =head1 COPYRIGHT diff --git a/doc/man3/PEM_read_CMS.pod b/doc/man3/PEM_read_CMS.pod index 65a114d677..0c22618b0b 100644 --- a/doc/man3/PEM_read_CMS.pod +++ b/doc/man3/PEM_read_CMS.pod @@ -73,6 +73,12 @@ PEM_write_TYPE() writes the PEM encoding of the object B to the file B. PEM_write_bio_TYPE() similarly writes to the BIO B. +=head1 NOTES + +These functions make no assumption regarding the pass phrase received from the +password callback. +It will simply be treated as a byte sequence. + =head1 RETURN VALUES PEM_read_TYPE() and PEM_read_bio_TYPE() return a pointer to an allocated @@ -83,7 +89,8 @@ or zero on error. =head1 SEE ALSO -L +L, +L =head1 COPYRIGHT diff --git a/doc/man3/PEM_read_bio_PrivateKey.pod b/doc/man3/PEM_read_bio_PrivateKey.pod index 4ff5b2d311..9f62140ce6 100644 --- a/doc/man3/PEM_read_bio_PrivateKey.pod +++ b/doc/man3/PEM_read_bio_PrivateKey.pod @@ -386,6 +386,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. @@ -465,7 +469,8 @@ as they will be formally deprecated in a future releases. =head1 SEE ALSO -L, L +L, L, +L =head1 COPYRIGHT diff --git a/doc/man3/PKCS12_create.pod b/doc/man3/PKCS12_create.pod index 37b53be83b..0dcd2ab2a2 100644 --- a/doc/man3/PKCS12_create.pod +++ b/doc/man3/PKCS12_create.pod @@ -60,13 +60,18 @@ should be used. B can be set to -1 and the MAC will then be omitted entirely. +PKCS12_create() makes assumptions regarding the encoding of the given pass +phrase. +See L for more information. + =head1 RETURN VALUES PKCS12_create() returns a valid B structure or NULL if an error occurred. =head1 SEE ALSO -L +L, +L =head1 COPYRIGHT diff --git a/doc/man3/PKCS12_newpass.pod b/doc/man3/PKCS12_newpass.pod index 58207f5ea5..c27c65281e 100644 --- a/doc/man3/PKCS12_newpass.pod +++ b/doc/man3/PKCS12_newpass.pod @@ -102,7 +102,8 @@ this function. =head1 SEE ALSO -L, L +L, L, +L =head1 COPYRIGHT diff --git a/doc/man3/PKCS12_parse.pod b/doc/man3/PKCS12_parse.pod index c03c371a6e..d61b17268a 100644 --- a/doc/man3/PKCS12_parse.pod +++ b/doc/man3/PKCS12_parse.pod @@ -57,7 +57,8 @@ Attributes currently cannot be stored in the private key B structure. =head1 SEE ALSO -L +L, +L =head1 COPYRIGHT diff --git a/doc/man3/PKCS5_PBKDF2_HMAC.pod b/doc/man3/PKCS5_PBKDF2_HMAC.pod index e5d1689e30..174831dabe 100644 --- a/doc/man3/PKCS5_PBKDF2_HMAC.pod +++ b/doc/man3/PKCS5_PBKDF2_HMAC.pod @@ -52,6 +52,9 @@ Increasing the B parameter slows down the algorithm which makes it harder for an attacker to perform a brute force attack using a large number of candidate passwords. +These functions make no assumption regarding the given password. +It will simply be treated as a byte sequence. + =head1 RETURN VALUES PKCS5_PBKDF2_HMAC() and PBKCS5_PBKDF2_HMAC_SHA1() return 1 on success or 0 on error. @@ -59,7 +62,8 @@ PKCS5_PBKDF2_HMAC() and PBKCS5_PBKDF2_HMAC_SHA1() return 1 on success or 0 on er =head1 SEE ALSO L, L, -L +L, +L =head1 COPYRIGHT diff --git a/doc/man3/d2i_PKCS8PrivateKey_bio.pod b/doc/man3/d2i_PKCS8PrivateKey_bio.pod index cc588dfca8..43a218a26a 100644 --- a/doc/man3/d2i_PKCS8PrivateKey_bio.pod +++ b/doc/man3/d2i_PKCS8PrivateKey_bio.pod @@ -45,6 +45,10 @@ Currently all the functions use BIOs or FILE pointers, there are no functions wh work directly on memory: this can be readily worked around by converting the buffers to memory BIOs, see L for details. +These functions make no assumption regarding the pass phrase received from the +password callback. +It will simply be treated as a byte sequence. + =head1 RETURN VALUES d2i_PKCS8PrivateKey_bio() and d2i_PKCS8PrivateKey_fp() return a valid B @@ -55,7 +59,8 @@ and i2d_PKCS8PrivateKey_nid_fp() return 1 on success or 0 on error. =head1 SEE ALSO -L +L, +L =head1 COPYRIGHT -- 2.25.1