sshca

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2026 License: MPL-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package sshca is the OpenSSH user-certificate core (#155): the closed key algorithm set, CA key custody encoding, certificate construction under a profile's constraints, and the Key Revocation List encoder. It holds no state and performs no I/O; the service layer owns authorization, sealing, and persistence.

Every cryptographic primitive comes from the standard library or golang.org/x/crypto/ssh. The KRL encoder (krl.go) writes only the OpenSSH container format (big-endian integers and length-prefixed strings); it implements no primitive.

Index

Constants

View Source
const (
	MinTTL             = time.Minute
	MaxTTL             = 30 * 24 * time.Hour
	MaxPrincipals      = 32
	MaxPrincipalLength = 256
	MaxSourceAddresses = 32
	MaxForceCommand    = 1024
	// ClockSkew backdates valid_after so a host whose clock trails Hikyo's
	// by up to a minute still accepts a freshly issued certificate.
	ClockSkew = time.Minute
)

Bounds shared by profiles and requests. They are the contract's limits too.

View Source
const MaxKRLSerials = 65536

MaxKRLSerials bounds one CA's KRL. It is far above any realistic revocation volume inside one max_ttl window; exceeding it is refused loudly by the service rather than truncated, because a truncated KRL silently un-revokes.

Variables

View Source
var ErrConstraint = errors.New("sshca: constraint violated")

ErrConstraint is a request or profile outside the declared bounds.

View Source
var ErrEncryptedKey = errors.New("sshca: passphrase-protected keys are not accepted")

ErrEncryptedKey refuses a passphrase-protected import. The operator decrypts the key locally first; Hikyo never handles a CA passphrase.

View Source
var ErrKRLTooLarge = errors.New("sshca: key revocation list exceeds its bound")

ErrKRLTooLarge reports a KRL over MaxKRLSerials.

View Source
var ErrUnsupportedKey = errors.New("sshca: unsupported key type")

ErrUnsupportedKey refuses a key outside the closed algorithm set: DSA, other curves, short RSA, security-key types, or a certificate offered as a key.

Functions

func AuthorizedKey

func AuthorizedKey(pub ssh.PublicKey, comment string) string

AuthorizedKey renders a public key as one authorized_keys line (no trailing newline) with an optional comment.

func CheckKeyAlgorithm

func CheckKeyAlgorithm(p Profile, alg Algorithm) error

CheckKeyAlgorithm refuses a user key whose algorithm the profile does not allow.

func EncodeKRL

func EncodeKRL(k KRL) ([]byte, error)

EncodeKRL serializes a KRL. Serials are de-duplicated and sorted; zero serials (unrevocable by the format) and empty sections are dropped.

func Fingerprint

func Fingerprint(pub ssh.PublicKey) string

Fingerprint is the OpenSSH SHA256 fingerprint (`SHA256:...`).

func GenerateKey

func GenerateKey(alg Algorithm) (crypto.Signer, error)

GenerateKey creates a fresh private key of the given algorithm.

func MarshalCAKey

func MarshalCAKey(key crypto.Signer) ([]byte, error)

MarshalCAKey encodes a CA private key as PKCS#8 DER, the single canonical sealed form. The caller seals the result and zeroes it.

func MarshalUserPrivateKey

func MarshalUserPrivateKey(key crypto.Signer, comment string) (string, error)

MarshalUserPrivateKey renders a generated user key in the OpenSSH private key format, unencrypted: it is disclosed once to the requester, who owns its protection from then on. Hikyo never stores it.

func NewSerial

func NewSerial() (uint64, error)

NewSerial returns a uniformly random serial in [1, 2^63-1]. It fits a signed 64-bit column and is never 0, which OpenSSH KRLs cannot revoke.

func ParseSourceAddresses

func ParseSourceAddresses(in []string) ([]netip.Prefix, error)

ParseSourceAddresses parses and canonicalizes a CIDR list. A bare address is read as a single-host prefix.

func PublicKeyOf

func PublicKeyOf(key crypto.Signer) (ssh.PublicKey, error)

PublicKeyOf returns the SSH public key of a private key.

func Sign

func Sign(ca ssh.Signer, pub ssh.PublicKey, t Template) (*ssh.Certificate, error)

Sign builds and signs a user certificate for pub. The caller has already resolved the request against the profile.

func ValidPrincipal

func ValidPrincipal(s string) bool

ValidPrincipal reports whether s is an acceptable certificate principal: a non-empty printable string with no whitespace, commas (the OpenSSH list separator in authorized principals files), or control characters.

func ValidateProfile

func ValidateProfile(p Profile) error

ValidateProfile checks a profile's own shape.

Types

type Algorithm

type Algorithm string

Algorithm is the closed key algorithm enum shared by CA keys and user keys. Anything else is refused by every parser and switch (fail-closed).

const (
	AlgorithmEd25519   Algorithm = "ed25519"
	AlgorithmECDSAP256 Algorithm = "ecdsa-p256"
	AlgorithmRSA3072   Algorithm = "rsa-3072"
)

func AlgorithmOf

func AlgorithmOf(pub ssh.PublicKey) (Algorithm, error)

AlgorithmOf classifies an SSH public key into the closed set. Certificates, security-key types, DSA, other curves, and RSA under 3072 bits are refused.

func Algorithms

func Algorithms() []Algorithm

Algorithms returns the closed set in its canonical order.

func ParseAlgorithm

func ParseAlgorithm(s string) (Algorithm, error)

ParseAlgorithm rejects an unknown algorithm name rather than defaulting one.

func ParseImportedKey

func ParseImportedKey(pemBytes []byte) (crypto.Signer, Algorithm, error)

ParseImportedKey parses an operator-supplied CA private key (OpenSSH or PKCS#8/PKCS#1/SEC1 PEM). Passphrase-protected keys are refused.

func ParsePublicKey

func ParsePublicKey(line string) (ssh.PublicKey, Algorithm, error)

ParsePublicKey parses one authorized_keys-format line (options and comment tolerated, ignored) and classifies it. Exactly one key is accepted.

func SignerFromCAKey

func SignerFromCAKey(der []byte) (ssh.Signer, Algorithm, error)

SignerFromCAKey opens a PKCS#8 DER CA key into an SSH signer. RSA CA keys sign with rsa-sha2-512 only (never SHA-1 ssh-rsa).

type Extension

type Extension string

Extension is the closed set of standard OpenSSH certificate extensions a profile may permit.

const (
	ExtX11Forwarding   Extension = "permit-X11-forwarding"
	ExtAgentForwarding Extension = "permit-agent-forwarding"
	ExtPortForwarding  Extension = "permit-port-forwarding"
	ExtPTY             Extension = "permit-pty"
	ExtUserRC          Extension = "permit-user-rc"
)

func Extensions

func Extensions() []Extension

Extensions returns the closed set in canonical order.

func ParseExtension

func ParseExtension(s string) (Extension, error)

ParseExtension accepts only the closed extension set.

type KRL

type KRL struct {
	Version     uint64
	GeneratedAt time.Time
	Comment     string
	Sections    []KRLSection
}

KRL is one revocation list.

type KRLSection

type KRLSection struct {
	CAKey   ssh.PublicKey
	Serials []uint64
}

KRLSection revokes serials issued by one CA key.

type Profile

type Profile struct {
	Principals      []string
	ForceCommand    string
	SourceAddresses []netip.Prefix
	Extensions      []Extension
	KeyAlgorithms   []Algorithm
	DefaultTTL      time.Duration
	MaxTTL          time.Duration
}

Profile is the signing policy a certificate is constrained by. The service loads it from the profile row; every field is already validated there.

type PublicKey

type PublicKey = ssh.PublicKey

PublicKey is the OpenSSH public key type. Callers name it through this package so golang.org/x/crypto/ssh stays confined here (boundary test).

type Request

type Request struct {
	Principals      []string
	SourceAddresses []netip.Prefix
	Extensions      []Extension
	// ExtensionsSet distinguishes "no extensions" from "profile default".
	ExtensionsSet bool
	TTL           time.Duration
}

Request is what the requester asks for. Empty fields take the profile's defaults; every non-empty field may only narrow the profile.

type Resolved

type Resolved struct {
	Principals      []string
	ForceCommand    string
	SourceAddresses []netip.Prefix
	Extensions      []Extension
	TTL             time.Duration
}

Resolved is the exact content of a certificate after applying a request to a profile.

func Resolve

func Resolve(p Profile, req Request) (Resolved, error)

Resolve applies a request to a profile, refusing anything that would widen it. The key algorithm is checked separately (CheckKeyAlgorithm).

type Template

type Template struct {
	Serial      uint64
	KeyID       string
	Resolved    Resolved
	ValidAfter  time.Time
	ValidBefore time.Time
}

Template is everything a certificate states besides the key being certified.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL