提交 0189bf2b 编写于 作者: R Richard Levitte

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.htmlReviewed-by: NRich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/6416)
上级 10bda8f8
......@@ -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)>
......
......@@ -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
......
......@@ -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
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册