Documentation
¶
Overview ¶
Package jwssign implements JWS compact serialization signing. It supports PKCS#11 backends (SoftHSM2, YubiHSM2) for production use, and ephemeral in-memory keys for development and CI.
Index ¶
- func ParsePKCS11URI(uri string) (module, token, pin string, err error)
- type Config
- type Signer
- func (s *Signer) Close() error
- func (s *Signer) JWKS() jose.JSONWebKeySet
- func (s *Signer) PublicJWK() jose.JSONWebKey
- func (s *Signer) Sign(payload json.RawMessage) (string, error)
- func (s *Signer) SignAggregate(dir, pattern, outputPath string) error
- func (s *Signer) SignDirectory(dir, pattern string) ([]string, error)
- func (s *Signer) SignFile(jsonPath string) (string, error)
- type TimestampedJWKS
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ParsePKCS11URI ¶
ParsePKCS11URI parses a PKCS#11 URI into module, token, and pin components. Format: pkcs11:module=/path/to/lib.so;token=label;pin=1234
Types ¶
type Config ¶
type Config struct {
// PKCS11Module is the path to the PKCS#11 shared library.
PKCS11Module string
// TokenLabel is the PKCS#11 token label.
TokenLabel string
// PIN is the PKCS#11 token PIN.
PIN string
// KeyLabel is the label of the signing key in the HSM.
KeyLabel string
// KeyID is the hex ID of the key (default "01").
KeyID string
// Issuer is the JWT "iss" claim.
Issuer string
// JKU is the JWS Key URL header value.
JKU string
}
Config holds the configuration for creating a Signer.
type Signer ¶
type Signer struct {
// contains filtered or unexported fields
}
Signer signs JSON payloads as JWS compact serialization.
func NewEphemeralSigner ¶ added in v0.8.0
NewEphemeralSigner creates a signer backed by an in-memory ECDSA P-256 key. This is suitable for development, CI, and deployments without HSM access. The key exists only for the lifetime of the process.
func NewSignerFromConfig ¶
NewSignerFromConfig creates a signer from a parsed PKCS11 URI string.
func (*Signer) JWKS ¶
func (s *Signer) JWKS() jose.JSONWebKeySet
JWKS returns a JSON Web Key Set containing the public key.
func (*Signer) PublicJWK ¶
func (s *Signer) PublicJWK() jose.JSONWebKey
PublicJWK returns the public key as a JSON Web Key.
func (*Signer) Sign ¶
func (s *Signer) Sign(payload json.RawMessage) (string, error)
Sign signs a JSON payload and returns a JWS compact serialization string. The payload is wrapped in a JWT envelope with iss and iat claims.
func (*Signer) SignAggregate ¶
SignAggregate reads all JSON files matching a pattern, combines them into a list payload, signs it, and writes to the output path.
func (*Signer) SignDirectory ¶
SignDirectory signs all files matching a glob pattern in a directory.
type TimestampedJWKS ¶ added in v0.7.0
type TimestampedJWKS struct {
Keys []jose.JSONWebKey `json:"keys"`
KeyAdded map[string]int64 `json:"x-key-added,omitempty"`
}
TimestampedJWKS extends a standard JWKS with per-key timestamps for key rotation tracking. The "x-key-added" field is ignored by standard JWKS consumers but preserved by this tool.
func LoadTimestampedJWKS ¶ added in v0.7.0
func LoadTimestampedJWKS(path string) (TimestampedJWKS, error)
LoadTimestampedJWKS reads a TimestampedJWKS from a JSON file. Returns an empty JWKS if the file does not exist.
func MergeJWKS ¶ added in v0.7.0
func MergeJWKS(current jose.JSONWebKeySet, previous TimestampedJWKS, retention time.Duration) TimestampedJWKS
MergeJWKS merges the current signing key with keys from a previous JWKS, retaining old keys for a configurable duration to support key rotation. Keys whose timestamp in KeyAdded is older than the retention period are removed. The current key is always added with a fresh timestamp. If a previous key has the same KeyID as the current key, it is replaced.
func (*TimestampedJWKS) ToJoseJWKS ¶ added in v0.7.0
func (t *TimestampedJWKS) ToJoseJWKS() jose.JSONWebKeySet
ToJoseJWKS converts to a standard jose.JSONWebKeySet (drops timestamps).
Source Files
Directories