[openssl-commits] [openssl] master update

[Richard Levitte]

The branch master has been updated
       via  0189bf2bbe30d4fa710fe7440ed7f3d8eab039c6 (commit)
      from  10bda8f8dd359b3db39a5157be0e72afe9f05eea (commit)


- Log -----------------------------------------------------------------
commit 0189bf2bbe30d4fa710fe7440ed7f3d8eab039c6
Author: Richard Levitte <levitte at openssl.org>
Date:   Tue Jun 5 15:58:43 2018 +0200

    Document UTF-8 expectation for pass phrases passed to OSSL_STORE
    
    After some discussion, it was concluded that the better idea is to
    stipulate that the pass phrases passed to the OSSL_STORE API are
    expected to be UTF-8 encoded, and that all objects made accessible
    through OSSL_STORE URIs should adhere to this expectation (at the
    discretion of the loaders).
    
    Email ref:
    https://mta.openssl.org/pipermail/openssl-project/2018-June/000771.html
    
    Reviewed-by: Rich Salz <rsalz at openssl.org>
    (Merged from https://github.com/openssl/openssl/pull/6416)

-----------------------------------------------------------------------

Summary of changes:
 doc/man7/ossl_store-file.pod     | 15 ++++++---------
 doc/man7/ossl_store.pod          |  7 +++++++
 doc/man7/passphrase-encoding.pod | 12 +++++-------
 3 files changed, 18 insertions(+), 16 deletions(-)

diff --git a/doc/man7/ossl_store-file.pod b/doc/man7/ossl_store-file.pod
index 1378427..996043b 100644
--- a/doc/man7/ossl_store-file.pod
+++ b/doc/man7/ossl_store-file.pod
@@ -47,17 +47,14 @@ only).
 
 When needed, the 'file' scheme loader will require a pass phrase by
 using the C<UI_METHOD> that was passed via OSSL_STORE_open().
-This pass phrase is used as it is, which may present some challenge
-when the file that's loaded contains a PKCS#12 object.
+This pass phrase is expected to be UTF-8 encoded, anything else will
+give an undefined result.
+The files made accessible through this loader are expected to be
+standard compliant with regards to pass phrase encoding.
+Files that aren't should be re-generated with a correctly encoded pass
+phrase.
 See L<passphrase-encoding(7)> for more information.
 
-=begin comment
-
-The treatment of pass phrases is currently being worked on and may
-change.
-
-=end comment
-
 =head1 SEE ALSO
 
 L<ossl_store(7)>, L<passphrase-encoding(7)>
diff --git a/doc/man7/ossl_store.pod b/doc/man7/ossl_store.pod
index efa4780..6e75abd 100644
--- a/doc/man7/ossl_store.pod
+++ b/doc/man7/ossl_store.pod
@@ -33,6 +33,13 @@ dynamically from the calling application or from a loadable engine.
 Support for the 'file' scheme is built into C<libcrypto>.
 See L<ossl_store-file(7)> for more information.
 
+=head2 UI_METHOD and pass phrases
+
+The B<OSS_STORE> API does nothing to enforce any specific format or
+encoding on the pass phrase that the B<UI_METHOD> provides.  However,
+the pass phrase is expected to be UTF-8 encoded.  The result of any
+other encoding is undefined.
+
 =head1 EXAMPLES
 
 =head2 A generic call
diff --git a/doc/man7/passphrase-encoding.pod b/doc/man7/passphrase-encoding.pod
index bc777c9..d5c9d1e 100644
--- a/doc/man7/passphrase-encoding.pod
+++ b/doc/man7/passphrase-encoding.pod
@@ -80,13 +80,11 @@ than 1.1.0 was misinterpreted as ISO-8859-1 sequences.
 
 L<ossl_store(7)> acts as a general interface to access all kinds of objects,
 potentially protected with a pass phrase, a PIN or something else.
-This API currently doesn't stipulate any specific encoding of pass phrases, but
-uses the underlying routines with their behaviours.
-This means that when using the built-in C<file:> scheme loader, the pass phrase
-to unlock a PKCS#12 file will be treated as described for PKCS#12 above, and
-the pass phrase for a PEM files will be treated as the general case described
-above, since that loader uses the same underlying routines.
-I<Note that other loaders will have their own behaviours>.
+This API stipulates that pass phrases should be UTF-8 encoded, and that any
+other pass phrase encoding may give undefined results.
+This API relies on the application to ensure UTF-8 encoding, and doesn't check
+that this is the case, so what it gets, it will also pass to the underlying
+loader.
 
 =head1 RECOMMENDATIONS