hostkeys

README

hostkeys

A host key manager for your golang ssh daemons

hostkeys will manage private keys for an ssh.ServerConfig. It creates missing private keys if the application is run for the first time and makes sure to reuse them if they already exist.

Its goal is predictability and does things exactly like one would expect a typical OpenSSH installation to do.

By default, it manages three keys, rsa 3072 bits, ecdsa P256, and an ed25519 key, similar to running ssh-keygen -A.

Basic usage:

// An SSH server is represented by a ServerConfig, which holds
// certificate details and handles authentication of ServerConns.
config := &ssh.ServerConfig{
    PasswordCallback: func(...) {
        // ... omitted ...
    },

    PublicKeyCallback: func(...) (...) {
        // ... omitted ...
    },
}

manager := &hostkeys.Manager{
    Directory: "/etc/app",
}

err := m.Manage(config)
if err != nil {
    t.Fatalf("hostkeys: %s", err)
}

Using existing openssh host keys:

manager := &hostkeys.Manager{
    Directory:    "/etc/ssh",
    NamingScheme: "ssh_host_%s_key",
}

Using stronger keys:

manager := &hostkeys.Manager{
    Directory: "/etc/app",
    Keys: []hostkeys.Generator{
		&generator.RSA{BitSize: 4096},
		&generator.ECDSA{Curve: elliptic.P521()},
	},
}

hostkeys will not update or delete existing keys. Changing key parameters requires the user to manually remove the old keys to have new generated.

Documentation

Index

• type Generator
• type Manager
  • func (m *Manager) Manage(c *ssh.ServerConfig) error

Types

type Generator

type Generator interface {
	// Generate should do actual key generation
	Generate() error

	// Encode should write out the private key in openssh-key-v1 format
	Encode(io.Writer) error

	// EncodePublic should write out the public key, in openssh's authorized_key format
	EncodePublic(io.Writer) error

	// Name should provide the type of key
	Name() string
}

Generator is able to generate a specific type of key and export both private and public parts

type Manager

type Manager struct {
	// Directory where keys are stored
	//
	// default: current work directory
	Directory string

	// NamingScheme specifies naming scheme for keys.
	// Must include a %s for inserting keytype.
	//
	// To use existing openssh keys: "ssh_host_%s_key"
	//
	// default: determines executable name at runtime
	// and sets the value to "<executable>_host_%s_key"
	NamingScheme string

	// Keys defines which types of keys to manage.
	//
	// default: a set of keys similar to openssh,
	// rsa 3072 bits, ecdsa P256, and an ed25519 key.
	Keys []Generator
}

Manager configures hostkeys

func (*Manager) Manage

func (m *Manager) Manage(c *ssh.ServerConfig) error

Manage sets up a *ssh.ServerConfig with keys by generating or reuseing existing keys.