.PEM File Format – Encoding and labels

Encoding rules

-----BEGIN CERTIFICATE-----
MII…  (base64 of the DER certificate, 64 characters per line)
…
-----END CERTIFICATE-----

From RFC 7468 sections 2 and 3:

• The first line is five hyphens, BEGIN, one space, the label and five hyphens; the last line the same with END. Writers must use the same label in both; readers may disregard a mismatch.
• Labels are formally case-sensitive and upper case, may contain spaces and hyphens, but not two in a row, and do not start or end with either.
• Between the lines is base64 (RFC 4648, section 4) of the data. Writers break it into lines of exactly 64 characters, the last line shorter, and add no other whitespace. Readers should ignore whitespace, must handle any line ending (LF, CR LF or CR) and may handle other line lengths.
• The data is BER; for most labels DER is preferred or strongly preferred (sections 5 to 13).
• Data before the BEGIN line is allowed, and parsers must not fail on it; section 5.2 describes explanatory text around certificates. A file may hold several blocks, as when it holds several certificates.
• RFC 7468 does not allow header lines inside the block; see legacy headers for the older form that has them.

Standard labels

The labels of RFC 7468 (summary table in section 4, details in sections 5 to 13):

RFC 7468 also names labels in other use that conforming writers must not produce:

Other labels in use

Software uses labels that RFC 7468 does not define. OpenSSL lists the labels it knows as PEM_STRING_* constants in include/openssl/pem.h; besides the RFC 7468 ones, the old X509 CERTIFICATE and NEW CERTIFICATE REQUEST, and two reading patterns described after the table, they are:

Two more constants are not labels found in files but patterns for reading: ANY PRIVATE KEY (PEM_STRING_EVP_PKEY) matches PRIVATE KEY, ENCRYPTED PRIVATE KEY and any type PRIVATE KEY label of a known key type, and PARAMETERS matches any type PARAMETERS label of a known type (check_pem in crypto/pem/pem_lib.c). The same function lets readers accept X509 CERTIFICATE as CERTIFICATE and NEW CERTIFICATE REQUEST as CERTIFICATE REQUEST; OpenSSL’s X509_REQ_NEW write functions still write NEW CERTIFICATE REQUEST “as required by some CAs” (PEM_read_bio_PrivateKey(3)).

OpenSSH writes its own private keys as OPENSSH PRIVATE KEY (MARK_BEGIN in OpenSSH’s sshkey.c), around a format that is not ASN.1 and is described in OpenSSH’s PROTOCOL.key (see OpenSSH keys).

Legacy headers

OpenSSL’s old “traditional” private key routines encrypt with a password by keeping RFC 1421’s header lines after the BEGIN line, followed by a blank line (PEM_read_bio_PrivateKey(3), “PEM ENCRYPTION FORMAT”):

-----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info: AES-256-CBC,3F1C5A0E9B7D2C4486A1E0F37B9C2D51

(base64 of the encrypted PKCS #1 key)
-----END RSA PRIVATE KEY-----

In RFC 1421, Proc-Type (section 4.6.1.1) must be the first header; its first subfield, 4, is the version of the PEM rules, and its second, ENCRYPTED, says the text is encrypted. DEK-Info (section 4.6.1.3) is required for encrypted messages and names the encryption algorithm and mode, followed by its parameters. In OpenSSL’s use, DEK-Info holds the cipher name as known to EVP_get_cipherbyname() and the initialisation vector in hex.

The key is derived from the password with OpenSSL’s EVP_BytesToKey, using MD5 and an iteration count of 1, with the IV passed as the salt, of which PKCS5_SALT_LEN (8) bytes are used (PEM_read_bio_PrivateKey(3); EVP_md5() in crypto/pem/pem_lib.c; PKCS5_SALT_LEN in include/openssl/evp.h). EVP_BytesToKey(3) defines the derivation: D_i = HASH^count(D_i−1 ‖ password ‖ salt), concatenated until there are enough bytes, key first. The same manual page says new applications should write PKCS #8 keys instead (ENCRYPTED PRIVATE KEY), which use PKCS #5 v2.0 encryption and an iteration count of 2048 rather than 1.