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

2.3 KiB
Raw Blame History

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 trees 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 keys 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 keys 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[]