auto

Documentation

Overview

Package auto constructs a Signer from the git signing configuration fields gpg.format and user.signingKey. It supports OpenPGP and SSH signing.

For SSH signing the resolution logic closely mirrors the git CLI: file paths, key:: literals, and .pub paths matched via an SSH agent are all supported. For OpenPGP signing the behaviour differs from git: the git CLI expects a key ID or fingerprint and shells out to gpg(1), whereas this package expects a file path to an armored private-key ring and signs natively in Go.

The underlying signing process takes place via Go native libraries, as opposed to shelling out to binaries.

Passphrase-protected keys are not supported directly. Expose such keys through an SSH agent instead, or use the lower-level gpg and ssh sibling packages when full control over key loading is required.

Index

• Variables
• type Config
• type Format
• type Signer
  • func FromConfig(cfg Config) (Signer, error)

Variables

var (
	// ErrPassphraseUnsupported is returned when the SSH private key on disk
	// is protected by a passphrase.
	ErrPassphraseUnsupported = errors.New("passphrase-protected SSH keys are not supported")
	// ErrEncryptedKeyUnsupported is returned when every private key in an
	// OpenPGP key ring is encrypted and no unencrypted alternative exists.
	ErrEncryptedKeyUnsupported = errors.New("encrypted GPG private keys are not supported")
	// ErrNoPrivateKey is returned when no usable private key can be found:
	// the key ring contains no private-key material, or no SigningKey or
	// agent was provided.
	ErrNoPrivateKey = errors.New("no private key found")
	// ErrNoPrivateKeyInAgent is returned when the SSH agent holds no keys.
	ErrNoPrivateKeyInAgent = errors.New("no private key found in SSH agent")
	// ErrUnsupportedFormat is returned for unrecognized signing formats.
	ErrUnsupportedFormat = errors.New("unsupported signing format")
)

Types

type Config

type Config struct {
	// FS is the filesystem used to read key files. When nil, it defaults
	// to the OS root filesystem.
	FS billy.Basic

	// SSHAgent is an optional SSH agent for SSH signing. It is consulted when
	// SigningKey is a key:: literal, a .pub file path, or empty. For any other
	// path, the private key is read from FS directly and the agent is ignored.
	SSHAgent agent.Agent

	// SigningKey is the value of user.signingKey.
	//
	// For SSH format:
	//   - Path to a private key file (e.g. ~/.ssh/id_ed25519).
	//   - Path to a public key file ending in .pub (e.g. ~/.ssh/id_ed25519.pub)
	//     when SSHAgent is set; the agent is queried for the matching signer.
	//   - A key:: literal (e.g. "key::ssh-ed25519 AAAA...") when SSHAgent is
	//     set; the agent is queried for the matching signer.
	//   - Empty string when SSHAgent is set; the first agent signer is used.
	//
	// For OpenPGP format: path to an armored private-key file.
	//
	// A leading ~/ is expanded to the current user's home directory.
	// ~username/ prefixes are not expanded.
	SigningKey string

	// Format is the value of gpg.format.
	// Supported: FormatSSH, FormatOpenPGP. Defaults to FormatOpenPGP when empty.
	Format Format
}

Config holds the git signing configuration values needed to construct the appropriate signer.

type Format

type Format string

Format represents the signing format as configured by gpg.format.

const (
	// FormatOpenPGP selects OpenPGP (GPG) signing. This is the default
	// when no format is configured.
	FormatOpenPGP Format = "openpgp"
	// FormatSSH selects SSH signing.
	FormatSSH Format = "ssh"
)

type Signer

type Signer interface {
	Sign(message io.Reader) ([]byte, error)
}

Signer signs a message read from an io.Reader and returns the raw signature bytes.

func FromConfig

func FromConfig(cfg Config) (Signer, error)

FromConfig returns a Signer configured according to the provided Config. It reads the signing key from disk and selects the appropriate signer implementation based on the format.