OpenSSH Key Structure Guide

The guide was created because the official OpenSSH protocol documentation provides only a brief description of key formats. It offers a detailed, type-specific breakdown of how keys are laid out on disk, which helps engineers avoid mis-parsing. By mapping each field to its binary representation, the guide clarifies the exact bytes to expect when reading or writing keys.

In older OpenSSH releases, private keys were stored as unmodified PEM blocks, making them interchangeable with other TLS libraries without conversion. Public keys were written as a space-separated line containing the key type, a Base64-encoded key blob, and an optional comment. The guide notes that the decoded Base64 component is what the structural descriptions refer to.

Recent OpenSSH releases switched to a proprietary “v1” private-key format. This format no longer uses plain PEM; instead it packs metadata such as the chosen key-derivation function, encryption cipher, a checksum to verify successful decryption, the public key itself, and any comment directly into the file. The guide points to the OpenSSH source’s PROTOCOL.key for a high-level view, while providing concrete field layouts for each key type.

For developers, the change means that any code that reads or writes private keys must be updated to handle the new binary layout and optional encryption parameters. Tools that only understand PEM will still process legacy keys but will reject or misinterpret v1 keys unless they are extended. Conversely, software that generates v1 keys can still produce legacy public-key files, preserving compatibility on the public side.

The document also advises preferring newer key algorithms such as ED25519 when possible, while noting that RSA remains widely supported but benefits from larger key sizes. This recommendation helps engineers choose key types that align with both security best practices and the capabilities of the updated format.