mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-03-31 20:10:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

Document UTF-8 expectation for pass phrases passed to OSSL_STORE

Browse Source 
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)
This commit is contained in:
Richard Levitte 2018-06-05 15:58:43 +02:00
parent 10bda8f8dd
commit 0189bf2bbe
3 changed files with 18 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
doc/man7/ossl_store-file.pod
View File

@ -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)>

7
doc/man7/ossl_store.pod
View File

@ -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

12
doc/man7/passphrase-encoding.pod
View File

@ -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