Debian Codegraph @

upstream/debian-unstable/man7/passphrase-encoding.7ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "PASSPHRASE-ENCODING 7SSL"
58 .TH PASSPHRASE-ENCODING 7SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 passphrase\-encoding
65 \&\- How diverse parts of OpenSSL treat pass phrases character encoding
66 .SH DESCRIPTION
67 .IX Header "DESCRIPTION"
68 In a modern world with all sorts of character encodings, the treatment of pass
69 phrases has become increasingly complex.
70 This manual page attempts to give an overview over how this problem is
71 currently addressed in different parts of the OpenSSL library.
72 .SS "The general case"
73 .IX Subsection "The general case"
74 The OpenSSL library doesn't treat pass phrases in any special way as a general
75 rule, and trusts the application or user to choose a suitable character set
76 and stick to that throughout the lifetime of affected objects.
77 This means that for an object that was encrypted using a pass phrase encoded in
78 ISO\-8859\-1, that object needs to be decrypted using a pass phrase encoded in
79 ISO\-8859\-1.
80 Using the wrong encoding is expected to cause a decryption failure.
81 .SS PKCS#12
82 .IX Subsection "PKCS#12"
83 PKCS#12 is a bit different regarding pass phrase encoding.
84 The standard stipulates that the pass phrase shall be encoded as an ASN.1
85 BMPString, which consists of the code points of the basic multilingual plane,
86 encoded in big endian (UCS\-2 BE).
87 .PP
88 OpenSSL tries to adapt to this requirements in one of the following manners:
89 .IP 1. 4
90 Treats the received pass phrase as UTF\-8 encoded and tries to re-encode it to
91 UTF\-16 (which is the same as UCS\-2 for characters U+0000 to U+D7FF and U+E000
92 to U+FFFF, but becomes an expansion for any other character), or failing that,
93 proceeds with step 2.
94 .IP 2. 4
95 Assumes that the pass phrase is encoded in ASCII or ISO\-8859\-1 and
96 opportunistically prepends each byte with a zero byte to obtain the UCS\-2
97 encoding of the characters, which it stores as a BMPString.
98 .Sp
99 Note that since there is no check of your locale, this may produce UCS\-2 /
100 UTF\-16 characters that do not correspond to the original pass phrase characters
101 for other character sets, such as any ISO\-8859\-X encoding other than
102 ISO\-8859\-1 (or for Windows, CP 1252 with exception for the extra "graphical"
103 characters in the 0x80\-0x9F range).
104 .PP
105 OpenSSL versions older than 1.1.0 do variant 2 only, and that is the reason why
106 OpenSSL still does this, to be able to read files produced with older versions.
107 .PP
108 It should be noted that this approach isn't entirely fault free.
109 .PP
110 A pass phrase encoded in ISO\-8859\-2 could very well have a sequence such as
111 0xC3 0xAF (which is the two characters "LATIN CAPITAL LETTER A WITH BREVE"
112 and "LATIN CAPITAL LETTER Z WITH DOT ABOVE" in ISO\-8859\-2 encoding), but would
113 be misinterpreted as the perfectly valid UTF\-8 encoded code point U+00EF (LATIN
114 SMALL LETTER I WITH DIAERESIS) \fIif the pass phrase doesn't contain anything that
115 would be invalid UTF\-8\fR.
116 A pass phrase that contains this kind of byte sequence will give a different
117 outcome in OpenSSL 1.1.0 and newer than in OpenSSL older than 1.1.0.
118 .PP
119 .Vb 2
120 \& 0x00 0xC3 0x00 0xAF # OpenSSL older than 1.1.0
121 \& 0x00 0xEF # OpenSSL 1.1.0 and newer
122 .Ve
123 .PP
124 On the same accord, anything encoded in UTF\-8 that was given to OpenSSL older
125 than 1.1.0 was misinterpreted as ISO\-8859\-1 sequences.
126 .SS OSSL_STORE
127 .IX Subsection "OSSL_STORE"
128 \&\fBossl_store\fR\|(7) acts as a general interface to access all kinds of objects,
129 potentially protected with a pass phrase, a PIN or something else.
130 This API stipulates that pass phrases should be UTF\-8 encoded, and that any
131 other pass phrase encoding may give undefined results.
132 This API relies on the application to ensure UTF\-8 encoding, and doesn't check
133 that this is the case, so what it gets, it will also pass to the underlying
134 loader.
135 .SH RECOMMENDATIONS
136 .IX Header "RECOMMENDATIONS"
137 This section assumes that you know what pass phrase was used for encryption,
138 but that it may have been encoded in a different character encoding than the
139 one used by your current input method.
140 For example, the pass phrase may have been used at a time when your default
141 encoding was ISO\-8859\-1 (i.e. "naïve" resulting in the byte sequence 0x6E 0x61
142 0xEF 0x76 0x65), and you're now in an environment where your default encoding
143 is UTF\-8 (i.e. "naïve" resulting in the byte sequence 0x6E 0x61 0xC3 0xAF 0x76
144 0x65).
145 Whenever it's mentioned that you should use a certain character encoding, it
146 should be understood that you either change the input method to use the
147 mentioned encoding when you type in your pass phrase, or use some suitable tool
148 to convert your pass phrase from your default encoding to the target encoding.
149 .PP
150 Also note that the sub-sections below discuss human readable pass phrases.
151 This is particularly relevant for PKCS#12 objects, where human readable pass
152 phrases are assumed.
153 For other objects, it's as legitimate to use any byte sequence (such as a
154 sequence of bytes from \fI/dev/urandom\fR that's been saved away), which makes any
155 character encoding discussion irrelevant; in such cases, simply use the same
156 byte sequence as it is.
157 .SS "Creating new objects"
158 .IX Subsection "Creating new objects"
159 For creating new pass phrase protected objects, make sure the pass phrase is
160 encoded using UTF\-8.
161 This is default on most modern Unixes, but may involve an effort on other
162 platforms.
163 Specifically for Windows, setting the environment variable
164 \&\fBOPENSSL_WIN32_UTF8\fR will have anything entered on [Windows] console prompt
165 converted to UTF\-8 (command line and separately prompted pass phrases alike).
166 .SS "Opening existing objects"
167 .IX Subsection "Opening existing objects"
168 For opening pass phrase protected objects where you know what character
169 encoding was used for the encryption pass phrase, make sure to use the same
170 encoding again.
171 .PP
172 For opening pass phrase protected objects where the character encoding that was
173 used is unknown, or where the producing application is unknown, try one of the
174 following:
175 .IP 1. 4
176 Try the pass phrase that you have as it is in the character encoding of your
177 environment.
178 It's possible that its byte sequence is exactly right.
179 .IP 2. 4
180 Convert the pass phrase to UTF\-8 and try with the result.
181 Specifically with PKCS#12, this should open up any object that was created
182 according to the specification.
183 .IP 3. 4
184 Do a naïve (i.e. purely mathematical) ISO\-8859\-1 to UTF\-8 conversion and try
185 with the result.
186 This differs from the previous attempt because ISO\-8859\-1 maps directly to
187 U+0000 to U+00FF, which other non\-UTF\-8 character sets do not.
188 .Sp
189 This also takes care of the case when a UTF\-8 encoded string was used with
190 OpenSSL older than 1.1.0.
191 (for example, \f(CW\*(C`ï\*(C'\fR, which is 0xC3 0xAF when encoded in UTF\-8, would become 0xC3
192 0x83 0xC2 0xAF when re-encoded in the naïve manner.
193 The conversion to BMPString would then yield 0x00 0xC3 0x00 0xA4 0x00 0x00, the
194 erroneous/non\-compliant encoding used by OpenSSL older than 1.1.0)
195 .SH "SEE ALSO"
196 .IX Header "SEE ALSO"
197 \&\fBevp\fR\|(7),
198 \&\fBossl_store\fR\|(7),
199 \&\fBEVP_BytesToKey\fR\|(3), \fBEVP_DecryptInit\fR\|(3),
200 \&\fBPEM_do_header\fR\|(3),
201 \&\fBPKCS12_parse\fR\|(3), \fBPKCS12_newpass\fR\|(3),
202 \&\fBd2i_PKCS8PrivateKey_bio\fR\|(3)
203 .SH COPYRIGHT
204 .IX Header "COPYRIGHT"
205 Copyright 2018\-2021 The OpenSSL Project Authors. All Rights Reserved.
206 .PP
207 Licensed under the Apache License 2.0 (the "License"). You may not use
208 this file except in compliance with the License. You can obtain a copy
209 in the file LICENSE in the source distribution or at
210 <https://www.openssl.org/source/license.html>.