diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man7/passphrase-encoding.7')
| -rw-r--r-- | secure/lib/libcrypto/man/man7/passphrase-encoding.7 | 178 |
1 files changed, 51 insertions, 127 deletions
diff --git a/secure/lib/libcrypto/man/man7/passphrase-encoding.7 b/secure/lib/libcrypto/man/man7/passphrase-encoding.7 index 2e0394073cee..ef8ac85fdba5 100644 --- a/secure/lib/libcrypto/man/man7/passphrase-encoding.7 +++ b/secure/lib/libcrypto/man/man7/passphrase-encoding.7 @@ -1,4 +1,5 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== @@ -15,29 +16,12 @@ .ft R .fi .. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. \*(C+ will -.\" give a nicer C++. Capital omega is used to do unbreakable dashes and -.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, -.\" nothing in troff, for use with C<>. -.tr \(*W- -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' . ds C` . ds C' 'br\} @@ -68,78 +52,18 @@ . \} .\} .rr rF -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "PASSPHRASE-ENCODING 7ossl" -.TH PASSPHRASE-ENCODING 7ossl "2023-09-19" "3.0.11" "OpenSSL" +.TH PASSPHRASE-ENCODING 7ossl 2025-07-01 3.5.1 OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh -.SH "NAME" +.SH NAME passphrase\-encoding \&\- How diverse parts of OpenSSL treat pass phrases character encoding -.SH "DESCRIPTION" +.SH DESCRIPTION .IX Header "DESCRIPTION" In a modern world with all sorts of character encodings, the treatment of pass phrases has become increasingly complex. @@ -151,31 +75,31 @@ The OpenSSL library doesn't treat pass phrases in any special way as a general rule, and trusts the application or user to choose a suitable character set and stick to that throughout the lifetime of affected objects. This means that for an object that was encrypted using a pass phrase encoded in -\&\s-1ISO\-8859\-1,\s0 that object needs to be decrypted using a pass phrase encoded in -\&\s-1ISO\-8859\-1.\s0 +ISO\-8859\-1, that object needs to be decrypted using a pass phrase encoded in +ISO\-8859\-1. Using the wrong encoding is expected to cause a decryption failure. -.SS "PKCS#12" +.SS PKCS#12 .IX Subsection "PKCS#12" PKCS#12 is a bit different regarding pass phrase encoding. -The standard stipulates that the pass phrase shall be encoded as an \s-1ASN.1\s0 +The standard stipulates that the pass phrase shall be encoded as an ASN.1 BMPString, which consists of the code points of the basic multilingual plane, -encoded in big endian (\s-1UCS\-2 BE\s0). +encoded in big endian (UCS\-2 BE). .PP OpenSSL tries to adapt to this requirements in one of the following manners: -.IP "1." 4 -Treats the received pass phrase as \s-1UTF\-8\s0 encoded and tries to re-encode it to -\&\s-1UTF\-16\s0 (which is the same as \s-1UCS\-2\s0 for characters U+0000 to U+D7FF and U+E000 +.IP 1. 4 +Treats the received pass phrase as UTF\-8 encoded and tries to re-encode it to +UTF\-16 (which is the same as UCS\-2 for characters U+0000 to U+D7FF and U+E000 to U+FFFF, but becomes an expansion for any other character), or failing that, proceeds with step 2. -.IP "2." 4 -Assumes that the pass phrase is encoded in \s-1ASCII\s0 or \s-1ISO\-8859\-1\s0 and -opportunistically prepends each byte with a zero byte to obtain the \s-1UCS\-2\s0 +.IP 2. 4 +Assumes that the pass phrase is encoded in ASCII or ISO\-8859\-1 and +opportunistically prepends each byte with a zero byte to obtain the UCS\-2 encoding of the characters, which it stores as a BMPString. .Sp -Note that since there is no check of your locale, this may produce \s-1UCS\-2 / -UTF\-16\s0 characters that do not correspond to the original pass phrase characters -for other character sets, such as any \s-1ISO\-8859\-X\s0 encoding other than -\&\s-1ISO\-8859\-1\s0 (or for Windows, \s-1CP 1252\s0 with exception for the extra \*(L"graphical\*(R" +Note that since there is no check of your locale, this may produce UCS\-2 / +UTF\-16 characters that do not correspond to the original pass phrase characters +for other character sets, such as any ISO\-8859\-X encoding other than +ISO\-8859\-1 (or for Windows, CP 1252 with exception for the extra "graphical" characters in the 0x80\-0x9F range). .PP OpenSSL versions older than 1.1.0 do variant 2 only, and that is the reason why @@ -183,12 +107,12 @@ OpenSSL still does this, to be able to read files produced with older versions. .PP It should be noted that this approach isn't entirely fault free. .PP -A pass phrase encoded in \s-1ISO\-8859\-2\s0 could very well have a sequence such as -0xC3 0xAF (which is the two characters \*(L"\s-1LATIN CAPITAL LETTER A WITH BREVE\*(R"\s0 -and \*(L"\s-1LATIN CAPITAL LETTER Z WITH DOT ABOVE\*(R"\s0 in \s-1ISO\-8859\-2\s0 encoding), but would -be misinterpreted as the perfectly valid \s-1UTF\-8\s0 encoded code point U+00EF (\s-1LATIN -SMALL LETTER I WITH DIAERESIS\s0) \fIif the pass phrase doesn't contain anything that -would be invalid \s-1UTF\-8\s0\fR. +A pass phrase encoded in ISO\-8859\-2 could very well have a sequence such as +0xC3 0xAF (which is the two characters "LATIN CAPITAL LETTER A WITH BREVE" +and "LATIN CAPITAL LETTER Z WITH DOT ABOVE" in ISO\-8859\-2 encoding), but would +be misinterpreted as the perfectly valid UTF\-8 encoded code point U+00EF (LATIN +SMALL LETTER I WITH DIAERESIS) \fIif the pass phrase doesn't contain anything that +would be invalid UTF\-8\fR. A pass phrase that contains this kind of byte sequence will give a different outcome in OpenSSL 1.1.0 and newer than in OpenSSL older than 1.1.0. .PP @@ -197,26 +121,26 @@ outcome in OpenSSL 1.1.0 and newer than in OpenSSL older than 1.1.0. \& 0x00 0xEF # OpenSSL 1.1.0 and newer .Ve .PP -On the same accord, anything encoded in \s-1UTF\-8\s0 that was given to OpenSSL older -than 1.1.0 was misinterpreted as \s-1ISO\-8859\-1\s0 sequences. -.SS "\s-1OSSL_STORE\s0" +On the same accord, anything encoded in UTF\-8 that was given to OpenSSL older +than 1.1.0 was misinterpreted as ISO\-8859\-1 sequences. +.SS OSSL_STORE .IX Subsection "OSSL_STORE" \&\fBossl_store\fR\|(7) acts as a general interface to access all kinds of objects, -potentially protected with a pass phrase, a \s-1PIN\s0 or something else. -This \s-1API\s0 stipulates that pass phrases should be \s-1UTF\-8\s0 encoded, and that any +potentially protected with a pass phrase, a PIN or something else. +This API stipulates that pass phrases should be UTF\-8 encoded, and that any other pass phrase encoding may give undefined results. -This \s-1API\s0 relies on the application to ensure \s-1UTF\-8\s0 encoding, and doesn't check +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. -.SH "RECOMMENDATIONS" +.SH RECOMMENDATIONS .IX Header "RECOMMENDATIONS" This section assumes that you know what pass phrase was used for encryption, but that it may have been encoded in a different character encoding than the one used by your current input method. For example, the pass phrase may have been used at a time when your default -encoding was \s-1ISO\-8859\-1\s0 (i.e. \*(L"nai\*:ve\*(R" resulting in the byte sequence 0x6E 0x61 +encoding was ISO\-8859\-1 (i.e. "naïve" resulting in the byte sequence 0x6E 0x61 0xEF 0x76 0x65), and you're now in an environment where your default encoding -is \s-1UTF\-8\s0 (i.e. \*(L"nai\*:ve\*(R" resulting in the byte sequence 0x6E 0x61 0xC3 0xAF 0x76 +is UTF\-8 (i.e. "naïve" resulting in the byte sequence 0x6E 0x61 0xC3 0xAF 0x76 0x65). Whenever it's mentioned that you should use a certain character encoding, it should be understood that you either change the input method to use the @@ -233,12 +157,12 @@ byte sequence as it is. .SS "Creating new objects" .IX Subsection "Creating new objects" For creating new pass phrase protected objects, make sure the pass phrase is -encoded using \s-1UTF\-8.\s0 +encoded using UTF\-8. This is default on most modern Unixes, but may involve an effort on other platforms. Specifically for Windows, setting the environment variable -\&\fB\s-1OPENSSL_WIN32_UTF8\s0\fR will have anything entered on [Windows] console prompt -converted to \s-1UTF\-8\s0 (command line and separately prompted pass phrases alike). +\&\fBOPENSSL_WIN32_UTF8\fR will have anything entered on [Windows] console prompt +converted to UTF\-8 (command line and separately prompted pass phrases alike). .SS "Opening existing objects" .IX Subsection "Opening existing objects" For opening pass phrase protected objects where you know what character @@ -248,24 +172,24 @@ encoding again. For opening pass phrase protected objects where the character encoding that was used is unknown, or where the producing application is unknown, try one of the following: -.IP "1." 4 +.IP 1. 4 Try the pass phrase that you have as it is in the character encoding of your environment. It's possible that its byte sequence is exactly right. -.IP "2." 4 -Convert the pass phrase to \s-1UTF\-8\s0 and try with the result. +.IP 2. 4 +Convert the pass phrase to UTF\-8 and try with the result. Specifically with PKCS#12, this should open up any object that was created according to the specification. -.IP "3." 4 -Do a nai\*:ve (i.e. purely mathematical) \s-1ISO\-8859\-1\s0 to \s-1UTF\-8\s0 conversion and try +.IP 3. 4 +Do a naïve (i.e. purely mathematical) ISO\-8859\-1 to UTF\-8 conversion and try with the result. -This differs from the previous attempt because \s-1ISO\-8859\-1\s0 maps directly to +This differs from the previous attempt because ISO\-8859\-1 maps directly to U+0000 to U+00FF, which other non\-UTF\-8 character sets do not. .Sp -This also takes care of the case when a \s-1UTF\-8\s0 encoded string was used with +This also takes care of the case when a UTF\-8 encoded string was used with OpenSSL older than 1.1.0. -(for example, \f(CW\*(C`i\*:\*(C'\fR, which is 0xC3 0xAF when encoded in \s-1UTF\-8,\s0 would become 0xC3 -0x83 0xC2 0xAF when re-encoded in the nai\*:ve manner. +(for example, \f(CW\*(C`ï\*(C'\fR, which is 0xC3 0xAF when encoded in UTF\-8, would become 0xC3 +0x83 0xC2 0xAF when re-encoded in the naïve manner. The conversion to BMPString would then yield 0x00 0xC3 0x00 0xA4 0x00 0x00, the erroneous/non\-compliant encoding used by OpenSSL older than 1.1.0) .SH "SEE ALSO" @@ -276,11 +200,11 @@ erroneous/non\-compliant encoding used by OpenSSL older than 1.1.0) \&\fBPEM_do_header\fR\|(3), \&\fBPKCS12_parse\fR\|(3), \fBPKCS12_newpass\fR\|(3), \&\fBd2i_PKCS8PrivateKey_bio\fR\|(3) -.SH "COPYRIGHT" +.SH COPYRIGHT .IX Header "COPYRIGHT" Copyright 2018\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use +Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy -in the file \s-1LICENSE\s0 in the source distribution or at +in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>. |