Link in passphrase-encoding(7) in relevant documentation

Reviewed-by: Andy Polyakov <appro@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/6179)

diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod
index 03c07c053a57a0e2201cc04276ff30e2e695ea6d..a713269129d56f3c23667716cf7306f2d66235b4 100644 (file)
--- 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<passphrase-encoding(7)>.
+
 =over 4
 
 =item B<pass:password>

diff --git a/doc/man3/OSSL_STORE_open.pod b/doc/man3/OSSL_STORE_open.pod
index 13f3722c4fc2407ccbf26ba2723e953be934048b..b1467f4100a71afdebcdbb49a6aaa3db772032d6 100644 (file)
--- 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<OSSL_STORE_R_UNREGISTERED_SCHEME>.
 
+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<file:> 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<passphrase-encoding(7)> for further information.
+
 =head1 RETURN VALUES
 
 OSSL_STORE_open() returns a pointer to a B<OSSL_STORE_CTX> 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<ossl_store(7)>, L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_register_loader(3)>
+L<ossl_store(7)>, L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_register_loader(3)>,
+L<passphrase-encoding(7)>
 
 =head1 HISTORY
 

diff --git a/doc/man3/PEM_bytes_read_bio.pod b/doc/man3/PEM_bytes_read_bio.pod
index d16ccd8c1330c4ddba57084686ec22f6c08c0c4d..cd05582a8095d0c698375db2b154ab07e92bb6ad 100644 (file)
--- 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<PEM(3)>,
-L<PEM_read_bio_ex(3)>
+L<PEM_read_bio_ex(3)>,
+L<passphrase-encoding(7)>
 
 =head1 HISTORY
 

diff --git a/doc/man3/PEM_read.pod b/doc/man3/PEM_read.pod
index 66cbc7d2433cc1eefb241fa3aea0345734aabcdb..2a017c67b333bd62af9e564f87b31d90e148236b 100644 (file)
--- 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<PEM_write_PrivateKey(3)> and L<d2i_PKCS8PrivateKey_bio(3)>.
 
+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<ERR_peek_last_error(3)>, L<ERR_GET_LIB(3)>,
-L<d2i_PKCS8PrivateKey_bio(3)>.
+L<d2i_PKCS8PrivateKey_bio(3)>,
+L<passphrase-encoding(7)>
 
 =head1 COPYRIGHT
 

diff --git a/doc/man3/PEM_read_CMS.pod b/doc/man3/PEM_read_CMS.pod
index 65a114d6777fbab3033430bdaee58412475a608b..0c22618b0b38a86e88f57a511d919e6ca5901a4f 100644 (file)
--- 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<a> to the file B<fp>.
 
 PEM_write_bio_TYPE() similarly writes to the BIO B<bp>.
 
+=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<PEM_read(3)>
+L<PEM_read(3)>,
+L<passphrase-encoding(7)>
 
 =head1 COPYRIGHT
 

diff --git a/doc/man3/PEM_read_bio_PrivateKey.pod b/doc/man3/PEM_read_bio_PrivateKey.pod
index 4ff5b2d311406ff479515b647bee89daa5576eab..9f62140ce63fcf3f4b85fc9550e86d71015b7c7a 100644 (file)
--- 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<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.
@@ -465,7 +469,8 @@ 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
 

diff --git a/doc/man3/PKCS12_create.pod b/doc/man3/PKCS12_create.pod
index 37b53be83b1e124b45a22197b6efd13cbcab97ea..0dcd2ab2a266ca18d69be65e77a242ac7b266e28 100644 (file)
--- a/doc/man3/PKCS12_create.pod
+++ b/doc/man3/PKCS12_create.pod
@@ -60,13 +60,18 @@ should be used.
 
 B<mac_iter> 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<passphrase-encoding(7)> for more information.
+
 =head1 RETURN VALUES
 
 PKCS12_create() returns a valid B<PKCS12> structure or NULL if an error occurred.
 
 =head1 SEE ALSO
 
-L<d2i_PKCS12(3)>
+L<d2i_PKCS12(3)>,
+L<passphrase-encoding(7)>
 
 =head1 COPYRIGHT
 

diff --git a/doc/man3/PKCS12_newpass.pod b/doc/man3/PKCS12_newpass.pod
index 58207f5ea5210a55419228c4c2e1a05108aae571..c27c65281ef635242044ce2b683d74b2672ff980 100644 (file)
--- a/doc/man3/PKCS12_newpass.pod
+++ b/doc/man3/PKCS12_newpass.pod
@@ -102,7 +102,8 @@ this function.
 
 =head1 SEE ALSO
 
-L<PKCS12_create(3)>, L<ERR_get_error(3)>
+L<PKCS12_create(3)>, L<ERR_get_error(3)>,
+L<passphrase-encoding(7)>
 
 =head1 COPYRIGHT
 

diff --git a/doc/man3/PKCS12_parse.pod b/doc/man3/PKCS12_parse.pod
index c03c371a6e88092254be727bca34056fddb921f5..d61b17268a0f01ff5040edd21acee2f64934f1dc 100644 (file)
--- 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<EVP_PKEY> structure.
 
 =head1 SEE ALSO
 
-L<d2i_PKCS12(3)>
+L<d2i_PKCS12(3)>,
+L<passphrase-encoding(7)>
 
 =head1 COPYRIGHT
 

diff --git a/doc/man3/PKCS5_PBKDF2_HMAC.pod b/doc/man3/PKCS5_PBKDF2_HMAC.pod
index e5d1689e302909eb037cf4e59ed1e9a9fcc1ef56..174831dabecedb0b4a568195a42885c83232c181 100644 (file)
--- a/doc/man3/PKCS5_PBKDF2_HMAC.pod
+++ b/doc/man3/PKCS5_PBKDF2_HMAC.pod
@@ -52,6 +52,9 @@ Increasing the B<iter> 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<evp(7)>, L<RAND_bytes(3)>,
-L<EVP_BytesToKey(3)>
+L<EVP_BytesToKey(3)>,
+L<passphrase-encoding(7)>
 
 =head1 COPYRIGHT
 

diff --git a/doc/man3/d2i_PKCS8PrivateKey_bio.pod b/doc/man3/d2i_PKCS8PrivateKey_bio.pod
index cc588dfca8d21a9533b9ae84006cf81d4b1325a4..43a218a26a1187aeec074def8860b61eb3d39ad0 100644 (file)
--- 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<BIO_s_mem(3)> 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<EVP_PKEY>
@@ -55,7 +59,8 @@ and i2d_PKCS8PrivateKey_nid_fp() return 1 on success or 0 on error.
 
 =head1 SEE ALSO
 
-L<PEM_read_PrivateKey(3)>
+L<PEM_read_PrivateKey(3)>,
+L<passphrase-encoding(7)>
 
 =head1 COPYRIGHT