2.3 KiB
OpenSSH Key Structure Guide
1. Purpose
This document attempts to present a much more detailed, thorough, and easily-understood form of the key formats used by OpenSSH. The extent of those formats' canonical documentation is the OpenSSH source tree’s PROTOCOL.key, which is a little lacking.
2. Basic Introduction
2.1. Legacy
2.1.1. Private Keys
In OpenSSH pre-7.8, private keys are stored in their respective PEM encoding[1] with no modification. These legacy private keys should be entirely usable by OpenSSL/LibreSSL/GnuTLS etc. natively with no conversion necessary.
2.1.2. Public Keys
Each public key file (*.pub) is written out in the following format:
A B C
Where:
- A
-
The key type (e.g.
ssh-rsa,ssh-ed25519, etc.) - B
-
The public key itself, Base64[2]-encoded
- C
-
The key’s comment
The structures specified in the breakdowns later in this document describe the decoded version of B only. They are specific to each keytype and format version starting with item 2.0.
2.2. New "v1" Format
2.2.1. Private Keys
Private key structures have been retooled in the "v1" format. In recent OpenSSH versions, all new keys use the v1 format. They no longer are in straight PEM-compatible format.
Refer to PROTOCOL.key for a (very) general description, or each key’s specific breakdown for more detailed information.
The v1 format offers several benefits over the legacy format, including:
-
customizable key derivation and encryption ciphers for encrypted private keys
-
embedded comments
-
embedded public key (no need to derive from the private key)
-
"checksumming" to confirm proper decryption for encrypted keys
2.2.2. Public Keys
All public keys in v1 continue to use the same packed binary format as the legacy format.
3. Keytype-Specific Breakdowns
Unresolved directive in <stdin> - include::rsa/main.adoc[]
Unresolved directive in <stdin> - include::ed25519/main.adoc[]