go_sshkeys/_ref/KEY_GUIDE.adoc
2022-03-07 02:34:27 -05:00

65 lines
2.3 KiB
Plaintext

= OpenSSH Key Structure Guide
brent saner <bts@square-r00t.net>, https://r00t2.io
Last updated {localdatetime}
:doctype: book
:docinfo: shared
:data-uri:
:imagesdir: images
:sectlinks:
:sectnums:
:sectnumlevels: 7
:toc: preamble
:toc2: left
:idprefix:
:toclevels: 7
:source-highlighter: rouge
:docinfo: shared
== 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 https://github.com/openssh/openssh-portable/blob/master/PROTOCOL.key[the OpenSSH source tree's `PROTOCOL.key`^], which is a little lacking.
== Basic Introduction
=== Legacy
==== Private Keys
In OpenSSH pre-7.8, private keys are stored in their respective PEM encodingfootnote:[https://datatracker.ietf.org/doc/html/rfc7468] with no modification. These legacy private keys should be entirely usable by OpenSSL/LibreSSL/GnuTLS etc. natively with no conversion necessary.
==== 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, Base64footnote:[https://datatracker.ietf.org/doc/html/rfc4648]-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`.
=== New "v1" Format
==== 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 https://github.com/openssh/openssh-portable/blob/master/PROTOCOL.key[`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
==== Public Keys
All public keys in v1 continue to use the same packed binary format as <<public_keys, the legacy format>>.
== Keytype-Specific Breakdowns
include::rsa/main.adoc[]
include::ed25519/main.adoc[]