sshsig

README

pault.ag/go/sshsig - sign data using OpenSSH

OpenSSH supports a new SSHSIG format, which allows for the signing of any data using an OpenSSH key.

This is supported on the CLI via ssh-keygen -Y sign (and associated -Y friends) but, support for SSHSIG is not implemented in x/crypto.

I don't have the time to handle upstreaming this to x/crypto, but I'd very much welcome someone upstreaming this (and deprecating this module), I'm happy to sign whatever is needed to help with that, including relicensing for inclusion into Go's x/crypto. Until then, this can do the work of signing and verification.

Documentation

Index

• Variables
• func Sign(rand io.Reader, priv ssh.Signer, namespace []byte, hashAlgo HashAlgo, ...) ([]byte, error)
• func Verify(pub ssh.PublicKey, namespace []byte, hashAlgo HashAlgo, hash []byte, ...) error
• type HashAlgo
  • func (ha HashAlgo) Check() error
  • func (ha HashAlgo) Hash() (crypto.Hash, error)
• type Signature
  • func ParseSignature(b []byte) (*Signature, error)
  • func (sig Signature) Marshal() []byte

Variables

var (
	// ErrUnknownHashAlgorithm will be returned if the HashAlgo is not
	// understood by this implementation.
	ErrUnknownHashAlgorithm = fmt.Errorf("sshsig: Unknown Hash Algorithm")

	// ErrBadMagic will be returned if the Magic preamble is not correct
	// for an SSHSIG packet.
	ErrBadMagic = fmt.Errorf("sshsig: Bad Magic Preamble")

	// ErrUnknownVersion will be returned if the Version is different than
	// the library supported (currently, only version 1 is supported).
	ErrUnknownVersion = fmt.Errorf("sshsig: Unknown Version")

	// HashAlgoSHA512 is the SHA512 algorithm.
	HashAlgoSHA512 HashAlgo = "sha512"

	// HashAlgoSHA256 is the SHA256 algorithm.
	HashAlgoSHA256 HashAlgo = "sha256"

	// MagicPreamble is the first 6 bytes of any Signature.
	MagicPreamble = [6]byte{'S', 'S', 'H', 'S', 'I', 'G'}
)

Functions

func Sign

func Sign(
	rand io.Reader,
	priv ssh.Signer,
	namespace []byte,
	hashAlgo HashAlgo,
	hash []byte,
) ([]byte, error)

Sign will create an OpenSSH SSHSIG format Signature in the provdied namespace, with the provided Hash Algorith, and data hash. This will create an SSHSIG v1.

func Verify

func Verify(
	pub ssh.PublicKey,
	namespace []byte,
	hashAlgo HashAlgo,
	hash []byte,
	sig *Signature,
) error

Verify will check that the OpenSSH SSHSIG Signature is valid given the data hash, hash algorith, and namespace.

This function expects that the data from the Signature is passed explicitly -- even though the Signature type also includes the Namespace, HashAlgo, and PublicKey, passing them in here ensures that the values of the Signature are confirmed totally during validation.

This will only verify an SSHSIG v1 signature.

Types

type HashAlgo

type HashAlgo string

HashAlgo represents the hash function used to sign the data.

func (HashAlgo) Check

func (ha HashAlgo) Check() error

Check will ensure that the Hash Algorithm is understood by sshsig.

func (HashAlgo) Hash

func (ha HashAlgo) Hash() (crypto.Hash, error)

Hash will return the crypto.Hash object that relates to the specified hashing algorithm.

type Signature

type Signature struct {
	// Version is the major version of the SSHSIG protocol. Currently, only
	// Version 1 is supported; any other version is not understood
	// and will result in an error.
	Version uint32

	// PublicKey is the underlying SSH Public Key used to create the signature.
	// This is user provided, and not to be treated as validated or otherwise
	// trustworthy until otherwise verified.
	PublicKey ssh.PublicKey

	// Namespace is a unique signature domain used to avoid copy-and-pasting
	// signatures between uses. Ensure your key signing scheme has a unique
	// namespace.
	Namespace []byte

	// HashAlgorithm is the algorithm used to sign the data.
	HashAlgorithm HashAlgo

	// Signature is an ssh Signature over the hash of the data.
	Signature *ssh.Signature
}

Signature contains the fields of an OpenSSH SSHSIG Signature, as read from the underlying wire data. All of the fields of this struct are user-provided and not safe to consider trusted without other verification.

func ParseSignature

func ParseSignature(b []byte) (*Signature, error)

ParseSignature will unpack the wire-protocol version of an SSHSIG format Signature into a Signature struct.

func (Signature) Marshal

func (sig Signature) Marshal() []byte

Marshal will encode the Signature into the SSHSIG Wire format.