91 lines
3.8 KiB
Plaintext
91 lines
3.8 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
|
|
|
|
////
|
|
This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License.
|
|
To view a copy of this license, visit
|
|
http://creativecommons.org/licenses/by-sa/4.0/.
|
|
////
|
|
|
|
[id="why"]
|
|
== 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.
|
|
|
|
[id="intro"]
|
|
== Basic Introduction
|
|
|
|
[id="intro_legc"]
|
|
=== Legacy
|
|
|
|
[id="intro_legc_priv"]
|
|
==== 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.
|
|
|
|
[id="intro_legc_pub"]
|
|
==== 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`.
|
|
|
|
[id="intro_v1"]
|
|
=== New "v1" Format
|
|
|
|
[id="intro_v1_priv"]
|
|
==== 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://anongit.mindrot.org/openssh.git/tree/PROTOCOL.key[`PROTOCOL.key`^] (https://github.com/openssh/openssh-portable/blob/master/PROTOCOL.key[GitHub mirror^]) for a (very) general description, or each key type's specific breakdown in this document 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
|
|
|
|
[id="intro_v1_pub"]
|
|
==== Public Keys
|
|
All public keys in v1 continue to use the same packed binary format as <<intro_legc_pub, the legacy format>>.
|
|
|
|
[id="bkdn"]
|
|
== Keytype-Specific Breakdowns
|
|
|
|
include::rsa/main.adoc[]
|
|
|
|
include::ed25519/main.adoc[]
|
|
|
|
[id="moar"]
|
|
== Further Information
|
|
|
|
++++
|
|
<a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">
|
|
<img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-sa/4.0/88x31.png" />
|
|
</a><br />
|
|
<span xmlns:dct="http://purl.org/dc/terms/" href="http://purl.org/dc/dcmitype/Text" property="dct:title" rel="dct:type">OpenSSH Key Structure Guide</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="https://r00t2.io/" property="cc:attributionName" rel="cc:attributionURL">Brent Saner</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International License</a>.<br />
|
|
<br />
|
|
++++
|
|
|
|
You are free to use, distribute, modify, redistribute, use for commercial purposes, etc. with very few restrictions; please see http://creativecommons.org/licenses/by-sa/4.0/[the license summary^] and https://creativecommons.org/licenses/by-sa/4.0/legalcode[full license^] for further details.
|