diff options
author | Richard Levitte <levitte@openssl.org> | 2018-06-05 15:58:43 +0200 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2018-06-07 13:25:03 +0200 |
commit | 0189bf2bbe30d4fa710fe7440ed7f3d8eab039c6 (patch) | |
tree | 9c26dcb74f6bb0c57cc09d4e570a7bb58a427aa7 /doc/man7 | |
parent | 10bda8f8dd359b3db39a5157be0e72afe9f05eea (diff) |
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@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/6416)
Diffstat (limited to 'doc/man7')
-rw-r--r-- | doc/man7/ossl_store-file.pod | 15 | ||||
-rw-r--r-- | doc/man7/ossl_store.pod | 7 | ||||
-rw-r--r-- | 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 13784276b1..996043b0fb 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 efa47806c7..6e75abd314 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 bc777c90c6..d5c9d1e6f6 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 |