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
- Variables
- func AuthorizedKey(pub ssh.PublicKey, comment string) string
- func CheckKeyAlgorithm(p Profile, alg Algorithm) error
- func EncodeKRL(k KRL) ([]byte, error)
- func Fingerprint(pub ssh.PublicKey) string
- func GenerateKey(alg Algorithm) (crypto.Signer, error)
- func MarshalCAKey(key crypto.Signer) ([]byte, error)
- func MarshalUserPrivateKey(key crypto.Signer, comment string) (string, error)
- func NewSerial() (uint64, error)
- func ParseSourceAddresses(in []string) ([]netip.Prefix, error)
- func PublicKeyOf(key crypto.Signer) (ssh.PublicKey, error)
- func Sign(ca ssh.Signer, pub ssh.PublicKey, t Template) (*ssh.Certificate, error)
- func ValidPrincipal(s string) bool
- func ValidateProfile(p Profile) error
- type Algorithm
- func AlgorithmOf(pub ssh.PublicKey) (Algorithm, error)
- func Algorithms() []Algorithm
- func ParseAlgorithm(s string) (Algorithm, error)
- func ParseImportedKey(pemBytes []byte) (crypto.Signer, Algorithm, error)
- func ParsePublicKey(line string) (ssh.PublicKey, Algorithm, error)
- func SignerFromCAKey(der []byte) (ssh.Signer, Algorithm, error)
- type Extension
- type KRL
- type KRLSection
- type Profile
- type PublicKey
- type Request
- type Resolved
- type Template
Constants ¶
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.
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 ¶
var ErrConstraint = errors.New("sshca: constraint violated")
ErrConstraint is a request or profile outside the declared bounds.
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.
var ErrKRLTooLarge = errors.New("sshca: key revocation list exceeds its bound")
ErrKRLTooLarge reports a KRL over MaxKRLSerials.
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 ¶
AuthorizedKey renders a public key as one authorized_keys line (no trailing newline) with an optional comment.
func CheckKeyAlgorithm ¶
CheckKeyAlgorithm refuses a user key whose algorithm the profile does not allow.
func EncodeKRL ¶
EncodeKRL serializes a KRL. Serials are de-duplicated and sorted; zero serials (unrevocable by the format) and empty sections are dropped.
func Fingerprint ¶
Fingerprint is the OpenSSH SHA256 fingerprint (`SHA256:...`).
func GenerateKey ¶
GenerateKey creates a fresh private key of the given algorithm.
func MarshalCAKey ¶
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 ¶
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 ¶
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 ¶
ParseSourceAddresses parses and canonicalizes a CIDR list. A bare address is read as a single-host prefix.
func PublicKeyOf ¶
PublicKeyOf returns the SSH public key of a private key.
func Sign ¶
Sign builds and signs a user certificate for pub. The caller has already resolved the request against the profile.
func ValidPrincipal ¶
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 ¶
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).
func AlgorithmOf ¶
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 ¶
ParseAlgorithm rejects an unknown algorithm name rather than defaulting one.
func ParseImportedKey ¶
ParseImportedKey parses an operator-supplied CA private key (OpenSSH or PKCS#8/PKCS#1/SEC1 PEM). Passphrase-protected keys are refused.
func ParsePublicKey ¶
ParsePublicKey parses one authorized_keys-format line (options and comment tolerated, ignored) and classifies it. Exactly one key is accepted.
type Extension ¶
type Extension string
Extension is the closed set of standard OpenSSH certificate extensions a profile may permit.
func Extensions ¶
func Extensions() []Extension
Extensions returns the closed set in canonical order.
func ParseExtension ¶
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 ¶
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 ¶
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.