Commit 0189bf2b authored by Richard Levitte's avatar Richard Levitte
Browse files

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: default avatarRich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/6416)
parent 10bda8f8

doc/man7/ossl_store-file.pod

+6 −9
Original line number Diff line number Diff line
@@ -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)>

doc/man7/ossl_store.pod

+7 −0
Original line number Diff line number Diff line
@@ -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

doc/man7/passphrase-encoding.pod

+5 −7
Original line number Diff line number Diff line
@@ -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