Documentation
¶
Overview ¶
Package ssh provides Ed25519 SSH key loading and signing/verification helpers for go-service.
This package supports:
- generating Ed25519 SSH key pairs,
- loading Ed25519 keys from SSH key formats, and
- constructing Signer/Verifier helpers around that key material.
Supported key encodings are:
- public key: SSH authorized_keys format (parsed via ssh.ParseAuthorizedKey)
- private key: SSH private key format (parsed via ssh.ParseRawPrivateKey)
Configuration values are typically loaded using the go-service "source string" pattern (for example "env:NAME", "file:/path", or a literal key value) via os.FS.ReadSource.
The package treats a nil *Config as disabled in constructor-style helpers such as NewSigner and NewVerifier, allowing SSH signing/verification to be wired as an optional capability.
If the provided key material is valid SSH key data but not an Ed25519 key, key parsing helpers return github.com/alexfalkowski/go-service/v2/crypto/errors.ErrInvalidKeyType instead of panicking. Callers can use errors.Is with github.com/alexfalkowski/go-service/v2/crypto/errors.ErrInvalidKeyType to detect that case while still receiving wrapped context about the actual decoded type.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Module = di.Module( di.Constructor(NewGenerator), di.Constructor(NewSigner), di.Constructor(NewVerifier), )
Module wires the SSH crypto subsystem into go.uber.org/fx/go.uber.org/dig.
It provides constructors for:
- *Generator (via NewGenerator), which generates Ed25519 SSH key pairs,
- *Signer (via NewSigner), which signs messages when SSH config is enabled, and
- *Verifier (via NewVerifier), which verifies signatures when SSH config is enabled.
Disabled behavior: if SSH configuration is disabled (nil *Config), NewSigner and NewVerifier return (nil, nil) so downstream consumers can treat SSH signing/verification as optional.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Public is a "source string" for the SSH public key in authorized_keys format.
//
// The value is resolved via os.FS.ReadSource and parsed via x/crypto/ssh.ParseAuthorizedKey.
Public string `yaml:"public,omitempty" json:"public,omitempty" toml:"public,omitempty"`
// Private is a "source string" for the SSH private key.
//
// The value is resolved via os.FS.ReadSource and parsed via x/crypto/ssh.ParseRawPrivateKey.
Private string `yaml:"private,omitempty" json:"private,omitempty" toml:"private,omitempty"`
}
Config configures SSH key loading for Ed25519 keys used by this package.
Public and Private are "source strings" resolved via os.FS.ReadSource (for example "env:NAME", "file:/path", or a literal key value).
Expected key formats:
- Public: SSH authorized_keys format (parsed via golang.org/x/crypto/ssh.ParseAuthorizedKey). Comments are allowed, but authorized_keys options and trailing entries are rejected.
- Private: SSH private key format (parsed via golang.org/x/crypto/ssh.ParseRawPrivateKey).
If the provided key material is a valid SSH key but not an Ed25519 key, PublicKey and PrivateKey return github.com/alexfalkowski/go-service/v2/crypto/errors.ErrInvalidKeyType.
func (*Config) IsEnabled ¶ added in v2.115.0
IsEnabled reports whether SSH configuration is enabled.
By convention, a nil *Config is treated as "SSH disabled" by wiring that depends on this configuration.
func (*Config) PrivateKey ¶
PrivateKey resolves and parses the configured Ed25519 private key.
It reads the private key data via os.FS.ReadSource and parses it as an SSH private key.
If the parsed SSH private key is not an Ed25519 key, PrivateKey returns github.com/alexfalkowski/go-service/v2/crypto/errors.ErrInvalidKeyType. This can happen if the input is a valid SSH private key but contains a different key type.
The returned error wraps github.com/alexfalkowski/go-service/v2/crypto/errors.ErrInvalidKeyType, so callers can use errors.Is to distinguish this case from read or SSH parsing errors.
func (*Config) PublicKey ¶
PublicKey resolves and parses the configured Ed25519 public key.
It reads the public key data via os.FS.ReadSource and parses it as an SSH authorized key.
If the parsed SSH public key is not an Ed25519 key, PublicKey returns github.com/alexfalkowski/go-service/v2/crypto/errors.ErrInvalidKeyType. This can happen if the input is a valid authorized_keys entry but contains a different key type (for example RSA).
The returned error wraps github.com/alexfalkowski/go-service/v2/crypto/errors.ErrInvalidKeyType, so callers can use errors.Is to distinguish this case from read or SSH parsing errors.
type Generator ¶
type Generator struct {
// contains filtered or unexported fields
}
Generator generates Ed25519 SSH key pairs.
func NewGenerator ¶
NewGenerator constructs a Generator that produces Ed25519 SSH key pairs.
The provided generator is used as the cryptographically-secure randomness source for key generation.
func (*Generator) Generate ¶
Generate returns an Ed25519 public/private key pair encoded in SSH formats.
The returned values are compatible with the expectations of Config:
- public: SSH authorized_keys format (via golang.org/x/crypto/ssh.MarshalAuthorizedKey)
- private: PEM-encoded SSH private key (via golang.org/x/crypto/ssh.MarshalPrivateKey and pem.EncodeToMemory)
If key generation, marshaling, or encoding fails, the returned error is prefixed with "ssh".
type Signer ¶
type Signer struct {
// PrivateKey is the Ed25519 private key used by Sign.
PrivateKey ed25519.PrivateKey
}
Signer holds an Ed25519 private key used for signing messages.
func NewSigner ¶
NewSigner constructs an SSH Signer when configuration is enabled.
Disabled behavior: if cfg is nil (disabled), NewSigner returns (nil, nil).
Enabled behavior: NewSigner resolves and parses the Ed25519 private key via cfg.PrivateKey(fs) and returns a Signer that can produce Ed25519 signatures.
Any error encountered while resolving/reading or parsing the key material is returned.
type Verifier ¶
type Verifier struct {
// PublicKey is the Ed25519 public key used by Verify.
PublicKey ed25519.PublicKey
}
Verifier holds an Ed25519 public key used for signature verification.
func NewVerifier ¶
NewVerifier constructs an SSH Verifier when configuration is enabled.
Disabled behavior: if cfg is nil (disabled), NewVerifier returns (nil, nil).
Enabled behavior: NewVerifier resolves and parses the Ed25519 public key via cfg.PublicKey(fs) and returns a Verifier that can validate Ed25519 signatures.
Any error encountered while resolving/reading or parsing the key material is returned.
func (*Verifier) Verify ¶
Verify verifies that sig is a valid Ed25519 signature for msg.
It returns crypto.ErrInvalidMatch when verification fails.
Note: Ed25519 verification is a boolean check and does not return an error on failure. This method returns a sentinel error to provide a uniform verification API across crypto implementations.
Source Files