secure/lib/libcrypto/man/man7/passphrase-encoding.7

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.40)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "PASSPHRASE-ENCODING 7"
 136 .TH PASSPHRASE-ENCODING 7 "2020-03-17" "1.1.1e" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 passphrase\-encoding \&\- How diverse parts of OpenSSL treat pass phrases character encoding
 143 .SH "DESCRIPTION"
 144 .IX Header "DESCRIPTION"
 145 In a modern world with all sorts of character encodings, the treatment of pass
 146 phrases has become increasingly complex.
 147 This manual page attempts to give an overview over how this problem is
 148 currently addressed in different parts of the OpenSSL library.
 149 .SS "The general case"
 150 .IX Subsection "The general case"
 151 The OpenSSL library doesn't treat pass phrases in any special way as a general
 152 rule, and trusts the application or user to choose a suitable character set
 153 and stick to that throughout the lifetime of affected objects.
 154 This means that for an object that was encrypted using a pass phrase encoded in
 155 \&\s-1ISO\-8859\-1,\s0 that object needs to be decrypted using a pass phrase encoded in
 156 \&\s-1ISO\-8859\-1.\s0
 157 Using the wrong encoding is expected to cause a decryption failure.
 158 .SS "PKCS#12"
 159 .IX Subsection "PKCS#12"
 160 PKCS#12 is a bit different regarding pass phrase encoding.
 161 The standard stipulates that the pass phrase shall be encoded as an \s-1ASN.1\s0
 162 BMPString, which consists of the code points of the basic multilingual plane,
 163 encoded in big endian (\s-1UCS\-2 BE\s0).
 164 .PP
 165 OpenSSL tries to adapt to this requirements in one of the following manners:
 166 .IP "1." 4
 167 Treats the received pass phrase as \s-1UTF\-8\s0 encoded and tries to re-encode it to
 168 \&\s-1UTF\-16\s0 (which is the same as \s-1UCS\-2\s0 for characters U+0000 to U+D7FF and U+E000
 169 to U+FFFF, but becomes an expansion for any other character), or failing that,
 170 proceeds with step 2.
 171 .IP "2." 4
 172 Assumes that the pass phrase is encoded in \s-1ASCII\s0 or \s-1ISO\-8859\-1\s0 and
 173 opportunistically prepends each byte with a zero byte to obtain the \s-1UCS\-2\s0
 174 encoding of the characters, which it stores as a BMPString.
 175 .Sp
 176 Note that since there is no check of your locale, this may produce \s-1UCS\-2 /
 177 UTF\-16\s0 characters that do not correspond to the original pass phrase characters
 178 for other character sets, such as any \s-1ISO\-8859\-X\s0 encoding other than
 179 \&\s-1ISO\-8859\-1\s0 (or for Windows, \s-1CP 1252\s0 with exception for the extra \*(L"graphical\*(R"
 180 characters in the 0x80\-0x9F range).
 181 .PP
 182 OpenSSL versions older than 1.1.0 do variant 2 only, and that is the reason why
 183 OpenSSL still does this, to be able to read files produced with older versions.
 184 .PP
 185 It should be noted that this approach isn't entirely fault free.
 186 .PP
 187 A pass phrase encoded in \s-1ISO\-8859\-2\s0 could very well have a sequence such as
 188 0xC3 0xAF (which is the two characters \*(L"\s-1LATIN CAPITAL LETTER A WITH BREVE\*(R"\s0
 189 and \*(L"\s-1LATIN CAPITAL LETTER Z WITH DOT ABOVE\*(R"\s0 in \s-1ISO\-8859\-2\s0 encoding), but would
 190 be misinterpreted as the perfectly valid \s-1UTF\-8\s0 encoded code point U+00EF (\s-1LATIN
 191 SMALL LETTER I WITH DIAERESIS\s0) \fIif the pass phrase doesn't contain anything that
 192 would be invalid \s-1UTF\-8\s0\fR.
 193 A pass phrase that contains this kind of byte sequence will give a different
 194 outcome in OpenSSL 1.1.0 and newer than in OpenSSL older than 1.1.0.
 195 .PP
 196 .Vb 2
 197 \& 0x00 0xC3 0x00 0xAF                    # OpenSSL older than 1.1.0
 198 \& 0x00 0xEF                              # OpenSSL 1.1.0 and newer
 199 .Ve
 200 .PP
 201 On the same accord, anything encoded in \s-1UTF\-8\s0 that was given to OpenSSL older
 202 than 1.1.0 was misinterpreted as \s-1ISO\-8859\-1\s0 sequences.
 203 .SS "\s-1OSSL_STORE\s0"
 204 .IX Subsection "OSSL_STORE"
 205 \&\fBossl_store\fR\|(7) acts as a general interface to access all kinds of objects,
 206 potentially protected with a pass phrase, a \s-1PIN\s0 or something else.
 207 This \s-1API\s0 stipulates that pass phrases should be \s-1UTF\-8\s0 encoded, and that any
 208 other pass phrase encoding may give undefined results.
 209 This \s-1API\s0 relies on the application to ensure \s-1UTF\-8\s0 encoding, and doesn't check
 210 that this is the case, so what it gets, it will also pass to the underlying
 211 loader.
 212 .SH "RECOMMENDATIONS"
 213 .IX Header "RECOMMENDATIONS"
 214 This section assumes that you know what pass phrase was used for encryption,
 215 but that it may have been encoded in a different character encoding than the
 216 one used by your current input method.
 217 For example, the pass phrase may have been used at a time when your default
 218 encoding was \s-1ISO\-8859\-1\s0 (i.e. \*(L"nai\*:ve\*(R" resulting in the byte sequence 0x6E 0x61
 219 0xEF 0x76 0x65), and you're now in an environment where your default encoding
 220 is \s-1UTF\-8\s0 (i.e. \*(L"nai\*:ve\*(R" resulting in the byte sequence 0x6E 0x61 0xC3 0xAF 0x76
 221 0x65).
 222 Whenever it's mentioned that you should use a certain character encoding, it
 223 should be understood that you either change the input method to use the
 224 mentioned encoding when you type in your pass phrase, or use some suitable tool
 225 to convert your pass phrase from your default encoding to the target encoding.
 226 .PP
 227 Also note that the sub-sections below discuss human readable pass phrases.
 228 This is particularly relevant for PKCS#12 objects, where human readable pass
 229 phrases are assumed.
 230 For other objects, it's as legitimate to use any byte sequence (such as a
 231 sequence of bytes from `/dev/urandom` that's been saved away), which makes any
 232 character encoding discussion irrelevant; in such cases, simply use the same
 233 byte sequence as it is.
 234 .SS "Creating new objects"
 235 .IX Subsection "Creating new objects"
 236 For creating new pass phrase protected objects, make sure the pass phrase is
 237 encoded using \s-1UTF\-8.\s0
 238 This is default on most modern Unixes, but may involve an effort on other
 239 platforms.
 240 Specifically for Windows, setting the environment variable
 241 \&\f(CW\*(C`OPENSSL_WIN32_UTF8\*(C'\fR will have anything entered on [Windows] console prompt
 242 converted to \s-1UTF\-8\s0 (command line and separately prompted pass phrases alike).
 243 .SS "Opening existing objects"
 244 .IX Subsection "Opening existing objects"
 245 For opening pass phrase protected objects where you know what character
 246 encoding was used for the encryption pass phrase, make sure to use the same
 247 encoding again.
 248 .PP
 249 For opening pass phrase protected objects where the character encoding that was
 250 used is unknown, or where the producing application is unknown, try one of the
 251 following:
 252 .IP "1." 4
 253 Try the pass phrase that you have as it is in the character encoding of your
 254 environment.
 255 It's possible that its byte sequence is exactly right.
 256 .IP "2." 4
 257 Convert the pass phrase to \s-1UTF\-8\s0 and try with the result.
 258 Specifically with PKCS#12, this should open up any object that was created
 259 according to the specification.
 260 .IP "3." 4
 261 Do a nai\*:ve (i.e. purely mathematical) \s-1ISO\-8859\-1\s0 to \s-1UTF\-8\s0 conversion and try
 262 with the result.
 263 This differs from the previous attempt because \s-1ISO\-8859\-1\s0 maps directly to
 264 U+0000 to U+00FF, which other non\-UTF\-8 character sets do not.
 265 .Sp
 266 This also takes care of the case when a \s-1UTF\-8\s0 encoded string was used with
 267 OpenSSL older than 1.1.0.
 268 (for example, \f(CW\*(C`i\*:\*(C'\fR, which is 0xC3 0xAF when encoded in \s-1UTF\-8,\s0 would become 0xC3
 269 0x83 0xC2 0xAF when re-encoded in the nai\*:ve manner.
 270 The conversion to BMPString would then yield 0x00 0xC3 0x00 0xA4 0x00 0x00, the
 271 erroneous/non\-compliant encoding used by OpenSSL older than 1.1.0)
 272 .SH "SEE ALSO"
 273 .IX Header "SEE ALSO"
 274 \&\fBevp\fR\|(7),
 275 \&\fBossl_store\fR\|(7),
 276 \&\fBEVP_BytesToKey\fR\|(3), \fBEVP_DecryptInit\fR\|(3),
 277 \&\fBPEM_do_header\fR\|(3),
 278 \&\fBPKCS12_parse\fR\|(3), \fBPKCS12_newpass\fR\|(3),
 279 \&\fBd2i_PKCS8PrivateKey_bio\fR\|(3)
 280 .SH "COPYRIGHT"
 281 .IX Header "COPYRIGHT"
 282 Copyright 2018\-2020 The OpenSSL Project Authors. All Rights Reserved.
 283 .PP
 284 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 285 this file except in compliance with the License.  You can obtain a copy
 286 in the file \s-1LICENSE\s0 in the source distribution or at
 287 <https://www.openssl.org/source/license.html>.