{ "content": [ { "type": "text", "text": "# PASSPHRASE-ENCODING (info)\n\n## NAME\n\npassphrase-encoding - How diverse parts of OpenSSL treat pass phrases character encoding\n\n## DESCRIPTION\n\nIn a modern world with all sorts of character encodings, the treatment\nof pass phrases has become increasingly complex. This manual page\nattempts to give an overview over how this problem is currently\naddressed in different parts of the OpenSSL library.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION**\n- **RECOMMENDATIONS**\n- **SEE ALSO**\n- **COPYRIGHT**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "PASSPHRASE-ENCODING", "section": "", "mode": "info", "summary": "passphrase-encoding - How diverse parts of OpenSSL treat pass phrases character encoding", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [ { "name": "evp", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/evp/7/json" }, { "name": "osslstore", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/osslstore/7/json" }, { "name": "EVPBytesToKey", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/EVPBytesToKey/3/json" }, { "name": "EVPDecryptInit", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/EVPDecryptInit/3/json" }, { "name": "PEMdoheader", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/PEMdoheader/3/json" }, { "name": "PKCS12parse", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/PKCS12parse/3/json" }, { "name": "PKCS12newpass", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/PKCS12newpass/3/json" }, { "name": "d2iPKCS8PrivateKeybio", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/d2iPKCS8PrivateKeybio/3/json" } ], "section_outline": [ { "name": "NAME", "lines": 3, "subsections": [] }, { "name": "DESCRIPTION", "lines": 70, "subsections": [] }, { "name": "RECOMMENDATIONS", "lines": 58, "subsections": [] }, { "name": "SEE ALSO", "lines": 4, "subsections": [] }, { "name": "COPYRIGHT", "lines": 8, "subsections": [] } ], "sections": { "NAME": { "content": "passphrase-encoding - How diverse parts of OpenSSL treat pass phrases\ncharacter encoding\n", "subsections": [] }, "DESCRIPTION": { "content": "In a modern world with all sorts of character encodings, the treatment\nof pass phrases has become increasingly complex. This manual page\nattempts to give an overview over how this problem is currently\naddressed in different parts of the OpenSSL library.\n\nThe general case\nThe OpenSSL library doesn't treat pass phrases in any special way as a\ngeneral rule, and trusts the application or user to choose a suitable\ncharacter set and stick to that throughout the lifetime of affected\nobjects. This means that for an object that was encrypted using a pass\nphrase encoded in ISO-8859-1, that object needs to be decrypted using a\npass phrase encoded in ISO-8859-1. Using the wrong encoding is\nexpected to cause a decryption failure.\n\nPKCS#12\nPKCS#12 is a bit different regarding pass phrase encoding. The\nstandard stipulates that the pass phrase shall be encoded as an ASN.1\nBMPString, which consists of the code points of the basic multilingual\nplane, encoded in big endian (UCS-2 BE).\n\nOpenSSL tries to adapt to this requirements in one of the following\nmanners:\n\n1. Treats the received pass phrase as UTF-8 encoded and tries to re-\nencode it to UTF-16 (which is the same as UCS-2 for characters\nU+0000 to U+D7FF and U+E000 to U+FFFF, but becomes an expansion for\nany other character), or failing that, proceeds with step 2.\n\n2. Assumes that the pass phrase is encoded in ASCII or ISO-8859-1 and\nopportunistically prepends each byte with a zero byte to obtain the\nUCS-2 encoding of the characters, which it stores as a BMPString.\n\nNote that since there is no check of your locale, this may produce\nUCS-2 / UTF-16 characters that do not correspond to the original\npass phrase characters for other character sets, such as any\nISO-8859-X encoding other than ISO-8859-1 (or for Windows, CP 1252\nwith exception for the extra \"graphical\" characters in the\n0x80-0x9F range).\n\nOpenSSL versions older than 1.1.0 do variant 2 only, and that is the\nreason why OpenSSL still does this, to be able to read files produced\nwith older versions.\n\nIt should be noted that this approach isn't entirely fault free.\n\nA pass phrase encoded in ISO-8859-2 could very well have a sequence\nsuch as 0xC3 0xAF (which is the two characters \"LATIN CAPITAL LETTER A\nWITH BREVE\" and \"LATIN CAPITAL LETTER Z WITH DOT ABOVE\" in ISO-8859-2\nencoding), but would be misinterpreted as the perfectly valid UTF-8\nencoded code point U+00EF (LATIN SMALL LETTER I WITH DIAERESIS) if the\npass phrase doesn't contain anything that would be invalid UTF-8. A\npass phrase that contains this kind of byte sequence will give a\ndifferent outcome in OpenSSL 1.1.0 and newer than in OpenSSL older than\n1.1.0.\n\n0x00 0xC3 0x00 0xAF # OpenSSL older than 1.1.0\n0x00 0xEF # OpenSSL 1.1.0 and newer\n\nOn the same accord, anything encoded in UTF-8 that was given to OpenSSL\nolder than 1.1.0 was misinterpreted as ISO-8859-1 sequences.\n\nOSSLSTORE\nosslstore(7) acts as a general interface to access all kinds of\nobjects, potentially protected with a pass phrase, a PIN or something\nelse. This API stipulates that pass phrases should be UTF-8 encoded,\nand that any other pass phrase encoding may give undefined results.\nThis API relies on the application to ensure UTF-8 encoding, and\ndoesn't check that this is the case, so what it gets, it will also pass\nto the underlying loader.\n", "subsections": [] }, "RECOMMENDATIONS": { "content": "This section assumes that you know what pass phrase was used for\nencryption, but that it may have been encoded in a different character\nencoding than the one used by your current input method. For example,\nthe pass phrase may have been used at a time when your default encoding\nwas ISO-8859-1 (i.e. \"naieve\" resulting in the byte sequence 0x6E 0x61\n0xEF 0x76 0x65), and you're now in an environment where your default\nencoding is UTF-8 (i.e. \"naieve\" resulting in the byte sequence 0x6E\n0x61 0xC3 0xAF 0x76 0x65). Whenever it's mentioned that you should use\na certain character encoding, it should be understood that you either\nchange the input method to use the mentioned encoding when you type in\nyour pass phrase, or use some suitable tool to convert your pass phrase\nfrom your default encoding to the target encoding.\n\nAlso note that the sub-sections below discuss human readable pass\nphrases. This is particularly relevant for PKCS#12 objects, where\nhuman readable pass phrases are assumed. For other objects, it's as\nlegitimate to use any byte sequence (such as a sequence of bytes from\n/dev/urandom that's been saved away), which makes any character\nencoding discussion irrelevant; in such cases, simply use the same byte\nsequence as it is.\n\nCreating new objects\nFor creating new pass phrase protected objects, make sure the pass\nphrase is encoded using UTF-8. This is default on most modern Unixes,\nbut may involve an effort on other platforms. Specifically for\nWindows, setting the environment variable OPENSSLWIN32UTF8 will have\nanything entered on [Windows] console prompt converted to UTF-8\n(command line and separately prompted pass phrases alike).\n\nOpening existing objects\nFor opening pass phrase protected objects where you know what character\nencoding was used for the encryption pass phrase, make sure to use the\nsame encoding again.\n\nFor opening pass phrase protected objects where the character encoding\nthat was used is unknown, or where the producing application is\nunknown, try one of the following:\n\n1. Try the pass phrase that you have as it is in the character\nencoding of your environment. It's possible that its byte sequence\nis exactly right.\n\n2. Convert the pass phrase to UTF-8 and try with the result.\nSpecifically with PKCS#12, this should open up any object that was\ncreated according to the specification.\n\n3. Do a naieve (i.e. purely mathematical) ISO-8859-1 to UTF-8\nconversion and try with the result. This differs from the previous\nattempt because ISO-8859-1 maps directly to U+0000 to U+00FF, which\nother non-UTF-8 character sets do not.\n\nThis also takes care of the case when a UTF-8 encoded string was\nused with OpenSSL older than 1.1.0. (for example, \"ie\", which is\n0xC3 0xAF when encoded in UTF-8, would become 0xC3 0x83 0xC2 0xAF\nwhen re-encoded in the naieve manner. The conversion to BMPString\nwould then yield 0x00 0xC3 0x00 0xA4 0x00 0x00, the\nerroneous/non-compliant encoding used by OpenSSL older than 1.1.0)\n", "subsections": [] }, "SEE ALSO": { "content": "evp(7), osslstore(7), EVPBytesToKey(3), EVPDecryptInit(3),\nPEMdoheader(3), PKCS12parse(3), PKCS12newpass(3),\nd2iPKCS8PrivateKeybio(3)\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright 2018-2021 The OpenSSL Project Authors. All Rights Reserved.\n\nLicensed under the Apache License 2.0 (the \"License\"). You may not use\nthis file except in compliance with the License. You can obtain a copy\nin the file LICENSE in the source distribution or at\n.\n\n3.0.2 2026-06-02 PASSPHRASE-ENCODING(7SSL)", "subsections": [] } } } }