Documentation
¶
Index ¶
- Constants
- Variables
- func DecryptAge(identityPath string, data []byte) ([]byte, error)
- func EncryptAge(recipients []string, data []byte) ([]byte, error)
- func GenerateAgeIdentity() (*age.X25519Identity, error)
- func HashDirectory(dir string, pattern string) (string, error)
- func HashFile(path string) (string, error)
- func LoadPublic(path string) (ed25519.PublicKey, error)
- func RightForSignal(signum int32) (uint64, error)
- func SignCapabilityToken(payload *gapiv1.CapabilityTokenPayload, priv ed25519.PrivateKey) (*gapiv1.CapabilityToken, error)
- func Verify(pub ed25519.PublicKey, data, sig []byte) bool
- func VerifyCapabilityToken(tok *gapiv1.CapabilityToken, resolve KeyResolver, now time.Time, ...) (*gapiv1.CapabilityTokenPayload, error)
- func VerifySignedBinary(binPath string, pub ed25519.PublicKey) error
- func WriteAgeIdentity(path string, id *age.X25519Identity) error
- type KeyPair
- type KeyResolver
- type PEMNS
- func (PEMNS) EncodePrivateKey(key any) ([]byte, error)
- func (PEMNS) EncodePublicKey(key any) ([]byte, error)
- func (PEMNS) FingerprintPublicKey(key any) (string, error)
- func (PEMNS) FormatFingerprint(key any, truncateTo int) (string, error)
- func (PEMNS) ParsePrivateKey(data []byte) (any, error)
- func (PEMNS) ParsePublicKey(data []byte) (any, error)
Constants ¶
const ( // RightSignalTerm authorizes graceful-stop signals (SIGTERM, SIGINT). RightSignalTerm uint64 = 1 << 0 // RightSignalKill authorizes SIGKILL. RightSignalKill uint64 = 1 << 1 // RightSignalUser authorizes SIGUSR1/SIGUSR2. RightSignalUser uint64 = 1 << 2 )
Rights bits carried in a capability token's bitmap. The kernel checks these at delivery; the orchestrator checks them at the FSM before a signal is even committed (defense in depth).
Variables ¶
var ( ErrTokenMalformed = errors.New("capability token: malformed") ErrTokenUnknownKey = errors.New("capability token: unknown signing key") ErrTokenSignature = errors.New("capability token: signature verification failed") ErrTokenExpired = errors.New("capability token: expired") ErrTokenRights = errors.New("capability token: insufficient rights") )
Typed verification failures. Errors are data: callers branch on these, never on message strings.
var PEM = PEMNS{}
Functions ¶
func DecryptAge ¶
DecryptAge decrypts data using an identity file (containing private keys).
func EncryptAge ¶
EncryptAge encrypts data for a list of recipients (public keys).
func GenerateAgeIdentity ¶
func GenerateAgeIdentity() (*age.X25519Identity, error)
GenerateAgeIdentity generates a new x25519 identity.
func HashDirectory ¶
HashDirectory computes a single BLAKE3 hash for all matching files in a directory
func LoadPublic ¶
LoadPublic loads a public key from a hex file
func RightForSignal ¶
RightForSignal maps a signal number to the capability right that authorizes it. Signals with no mapping (SIGSEGV, SIGSTOP, ...) are never grantable and fail closed.
func SignCapabilityToken ¶
func SignCapabilityToken(payload *gapiv1.CapabilityTokenPayload, priv ed25519.PrivateKey) (*gapiv1.CapabilityToken, error)
SignCapabilityToken serializes payload and signs the literal bytes. The signature covers exactly the bytes embedded in the token - protobuf serialization is not canonical, so verifiers must never re-serialize before checking.
func VerifyCapabilityToken ¶
func VerifyCapabilityToken(tok *gapiv1.CapabilityToken, resolve KeyResolver, now time.Time, requiredRights uint64) (*gapiv1.CapabilityTokenPayload, error)
VerifyCapabilityToken is the kernel's single verification codepath (GAPI-DIV-017). It checks structure, signature (over the literal payload bytes), validity window, and rights, in that order, and returns the verified payload. The payload is parsed before the signature check only to learn key_id; no other field is trusted until the signature has passed.
func VerifySignedBinary ¶
VerifySignedBinary checks a binary against its sidecar provenance files: the .b3 BLAKE3 digest must match the binary's current content, and the .sig must be a valid hex-encoded Ed25519 signature over that digest, made by the given public key. This is the same convention `gapictl agent verify` checks; both consume this package so verification has one codepath (ecosystem provenance rule).
The signature covers the CANONICAL digest string - exactly what HashFile returns - and not the raw bytes of the .b3 file. Those two differ: Magefile writes the sidecar as hexSum+"\n", so signing the file bytes would bind the signature to incidental formatting, and a .b3 rewritten without the trailing newline would stop verifying against an unchanged binary. Signing the digest keeps the chain pubkey -> digest -> binary independent of how the sidecar is spelled.
This asymmetry was a live defect (GAPI-DIV-032): the digest comparison trimmed and the signature check did not, so no signature produced by 'gapictl crypto sign' could ever verify, and production mode - which gates agent start on this - could not start any agent.
func WriteAgeIdentity ¶
func WriteAgeIdentity(path string, id *age.X25519Identity) error
WriteAgeIdentity writes an identity to a file in standard format.
The identity is a secret, so the file is replaced rather than written through - see safeio.ReplaceOwnerOnly. os.WriteFile's perm argument would apply only when creating the file, leaving an overwrite at whatever mode the destination already had.
Types ¶
type KeyPair ¶
type KeyPair struct {
Public ed25519.PublicKey
Private ed25519.PrivateKey
}
KeyPair holds the private and public keys
func LoadPrivate ¶
LoadPrivate loads a private key from a PEM file. It accepts the canonical PKCS#8 "PRIVATE KEY" format as well as the legacy raw "ED25519 PRIVATE KEY" format for backward compatibility (legacy keys are upgraded to PKCS#8 the next time SavePrivate runs).
func (*KeyPair) SavePrivate ¶
SavePrivate saves the private key to a PEM file in PKCS#8 form ("PRIVATE KEY" block), the same format PEMNS.EncodePrivateKey produces, so a key written here can be loaded through either code path.
The file is replaced, not written through, so the key is never on disk at a mode the operator did not choose - see safeio.ReplaceOwnerOnly. The mode is not left to the caller: every caller of this function is writing a secret, and a caller that forgets leaks the key silently.
func (*KeyPair) SavePublic ¶
SavePublic saves the public key to a hex file (simple format for now).
A public key is not a secret, but this has always been written owner-only and tightening or loosening that is a separate decision; routing it through the same helper preserves the mode and keeps ReplaceOwnerOnly the only thing in this package that decides a file mode.
type KeyResolver ¶
KeyResolver maps a token's key_id to the issuer public key. Returning false fails the token closed with ErrTokenUnknownKey.
Source Files