{ "content": [ { "type": "text", "text": "# PASSPHRASE-ENCODING(7SSL) (man)\n\n**Summary:** passphrase-encoding - How diverse parts of OpenSSL treat pass phrases character encoding\n\n## See Also\n\n- evp(7)\n- osslstore(7)\n- EVPBytesToKey(3)\n- EVPDecryptInit(3)\n- PEMdoheader(3)\n- PKCS12parse(3)\n- PKCS12newpass(3)\n- d2iPKCS8PrivateKeybio(3)\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **DESCRIPTION** (4 lines) — 2 subsections\n - The general case (7 lines)\n - PKCS#12 (45 lines)\n- **RECOMMENDATIONS** (16 lines) — 2 subsections\n - Creating new objects (6 lines)\n - Opening existing objects (22 lines)\n- **SEE ALSO** (3 lines)\n- **COPYRIGHT** (9 lines)\n\n## Full Content\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 of pass phrases has\nbecome increasingly complex. This manual page attempts to give an overview over how this\nproblem is currently addressed in different parts of the OpenSSL library.\n\n#### The general case\n\nThe OpenSSL library doesn't treat pass phrases in any special way as a general rule, and\ntrusts the application or user to choose a suitable character set and stick to that\nthroughout the lifetime of affected objects. This means that for an object that was\nencrypted using a pass phrase encoded in ISO-8859-1, that object needs to be decrypted using\na pass phrase encoded in ISO-8859-1. Using the wrong encoding is expected to cause a\ndecryption failure.\n\n#### PKCS#12\n\nPKCS#12 is a bit different regarding pass phrase encoding. The standard stipulates that the\npass phrase shall be encoded as an ASN.1 BMPString, which consists of the code points of the\nbasic multilingual plane, encoded in big endian (UCS-2 BE).\n\nOpenSSL tries to adapt to this requirements in one of the following manners:\n\n1. Treats the received pass phrase as UTF-8 encoded and tries to re-encode it to UTF-16\n(which is the same as UCS-2 for characters U+0000 to U+D7FF and U+E000 to U+FFFF, but\nbecomes an expansion for any 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 opportunistically\nprepends each byte with a zero byte to obtain the UCS-2 encoding of the characters, which\nit stores as a BMPString.\n\nNote that since there is no check of your locale, this may produce UCS-2 / UTF-16\ncharacters that do not correspond to the original pass phrase characters for other\ncharacter sets, such as any ISO-8859-X encoding other than ISO-8859-1 (or for Windows, CP\n1252 with exception for the extra \"graphical\" characters in the 0x80-0x9F range).\n\nOpenSSL versions older than 1.1.0 do variant 2 only, and that is the reason why OpenSSL still\ndoes this, to be able to read files produced with 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 such as 0xC3 0xAF (which\nis the two characters \"LATIN CAPITAL LETTER A WITH BREVE\" and \"LATIN CAPITAL LETTER Z WITH\nDOT ABOVE\" in ISO-8859-2 encoding), but would be misinterpreted as the perfectly valid UTF-8\nencoded code point U+00EF (LATIN SMALL LETTER I WITH DIAERESIS) if the pass phrase doesn't\ncontain anything that would be invalid UTF-8. A pass phrase that contains this kind of byte\nsequence will give a different 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 older than 1.1.0 was\nmisinterpreted as ISO-8859-1 sequences.\n\nOSSLSTORE\nosslstore(7) acts as a general interface to access all kinds of objects, potentially\nprotected with a pass phrase, a PIN or something else. This API stipulates that pass phrases\nshould be UTF-8 encoded, and that any other pass phrase encoding may give undefined results.\nThis API relies on the application to ensure UTF-8 encoding, and doesn't check that this is\nthe case, so what it gets, it will also pass to the underlying loader.\n\n### RECOMMENDATIONS\n\nThis section assumes that you know what pass phrase was used for encryption, but that it may\nhave been encoded in a different character encoding than the one used by your current input\nmethod. For example, the 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 0xEF 0x76 0x65), and\nyou're now in an environment where your default encoding is UTF-8 (i.e. \"naieve\" resulting in\nthe byte sequence 0x6E 0x61 0xC3 0xAF 0x76 0x65). Whenever it's mentioned that you should\nuse a certain character encoding, it should be understood that you either change the input\nmethod to use the mentioned encoding when you type in your pass phrase, or use some suitable\ntool to convert your pass phrase from your default encoding to the target encoding.\n\nAlso note that the sub-sections below discuss human readable pass phrases. This is\nparticularly relevant for PKCS#12 objects, where human readable pass phrases are assumed.\nFor other objects, it's as legitimate to use any byte sequence (such as a sequence of bytes\nfrom /dev/urandom that's been saved away), which makes any character encoding discussion\nirrelevant; in such cases, simply use the same byte sequence as it is.\n\n#### Creating new objects\n\nFor creating new pass phrase protected objects, make sure the pass phrase is encoded using\nUTF-8. This is default on most modern Unixes, but may involve an effort on other platforms.\nSpecifically for Windows, setting the environment variable OPENSSLWIN32UTF8 will have\nanything entered on [Windows] console prompt converted to UTF-8 (command line and separately\nprompted pass phrases alike).\n\n#### Opening existing objects\n\nFor opening pass phrase protected objects where you know what character encoding was used for\nthe encryption pass phrase, make sure to use the same encoding again.\n\nFor opening pass phrase protected objects where the character encoding that was used is\nunknown, or where the producing application is unknown, try one of the following:\n\n1. Try the pass phrase that you have as it is in the character encoding of your environment.\nIt's possible that its byte sequence is exactly right.\n\n2. Convert the pass phrase to UTF-8 and try with the result. Specifically with PKCS#12,\nthis should open up any object that was created according to the specification.\n\n3. Do a naieve (i.e. purely mathematical) ISO-8859-1 to UTF-8 conversion and try with the\nresult. This differs from the previous attempt because ISO-8859-1 maps directly to\nU+0000 to U+00FF, which other non-UTF-8 character sets do not.\n\nThis also takes care of the case when a UTF-8 encoded string was used with OpenSSL older\nthan 1.1.0. (for example, \"ie\", which is 0xC3 0xAF when encoded in UTF-8, would become\n0xC3 0x83 0xC2 0xAF when re-encoded in the naieve manner. The conversion to BMPString\nwould then yield 0x00 0xC3 0x00 0xA4 0x00 0x00, the erroneous/non-compliant encoding used\nby OpenSSL older than 1.1.0)\n\n### SEE ALSO\n\nevp(7), osslstore(7), EVPBytesToKey(3), EVPDecryptInit(3), PEMdoheader(3),\nPKCS12parse(3), PKCS12newpass(3), d2iPKCS8PrivateKeybio(3)\n\n### COPYRIGHT\n\nCopyright 2018-2021 The OpenSSL Project Authors. All Rights Reserved.\n\nLicensed under the Apache License 2.0 (the \"License\"). You may not use this file except in\ncompliance with the License. You can obtain a copy in the file LICENSE in the source\ndistribution or at .\n\n\n\n3.0.2 2026-04-07 PASSPHRASE-ENCODING(7SSL)\n\n" } ], "structuredContent": { "command": "PASSPHRASE-ENCODING", "section": "7SSL", "mode": "man", "summary": "passphrase-encoding - How diverse parts of OpenSSL treat pass phrases character encoding", "synopsis": 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": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 4, "subsections": [ { "name": "The general case", "lines": 7 }, { "name": "PKCS#12", "lines": 45 } ] }, { "name": "RECOMMENDATIONS", "lines": 16, "subsections": [ { "name": "Creating new objects", "lines": 6 }, { "name": "Opening existing objects", "lines": 22 } ] }, { "name": "SEE ALSO", "lines": 3, "subsections": [] }, { "name": "COPYRIGHT", "lines": 9, "subsections": [] } ] } }