pkcs11

package
v0.6.13 Latest Latest
Warning

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

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source
const (
	RestartExit     = "exit"
	RestartDeadline = "deadline"
)

Restart reasons for aerolvm_pkcs11_helper_restarts_total{reason}.

View Source
const (
	IVAuto   = "auto"
	IVHSM    = "hsm"
	IVCaller = "caller"
)

IV modes (SB_SECRET_PKCS11_GCM_IV).

View Source
const HelperFlag = "--pkcs11-helper"

HelperFlag starts `sandboxd` as the PKCS#11 helper (cmd/sandboxd).

View Source
const OpDeadline = 5 * time.Second

OpDeadline bounds every helper op. A vendor C_Encrypt can block inside the helper; past this deadline sandboxd kills and replaces the helper, which frees any session stuck in a C call (eng D25).

View Source
const StartTimeout = 15 * time.Second

StartTimeout covers C_Initialize, login, the IV probe and the first key lookup in a fresh helper.

Variables

This section is empty.

Functions

func ExecStarter

func ExecStarter(cfg TokenConfig) starter

ExecStarter runs this same binary with HelperFlag and the token settings as flags. The helper exits when its parent does.

func RunHelper

func RunHelper(args []string) error

RunHelper is `sandboxd --pkcs11-helper`: it opens the token and serves the socket until sandboxd exits or signals it. args are what ExecStarter passes.

Types

type Helper

type Helper struct {
	// contains filtered or unexported fields
}

Helper is the sandboxd side of the PKCS#11 helper (eng D5): a secrets.DataKeyWrapper that forwards each call over the helper's socket and keeps the helper running. The vendor library never loads into sandboxd, so a vendor crash costs a helper restart, not the daemon.

func StartHelper

func StartHelper(opts HelperOptions) (*Helper, error)

StartHelper launches the helper and waits until it serves. It always returns a Helper whose supervisor keeps (re)starting the helper; the error is the first start's, so boot can refuse under strict boot or warn and carry on, as for the other providers.

func (*Helper) Close

func (h *Helper) Close() error

Close stops the helper and its supervisor.

func (*Helper) CurrentKeyVersion

func (h *Helper) CurrentKeyVersion(context.Context) (string, error)

CurrentKeyVersion implements secrets.KeyVersioner: the label new wraps use, in the form secrets.WrappedKeyVersion reports, so the rewrap sweep moves rows on older labels to it (§11, eng D23).

func (*Helper) DecryptableKeyVersions

func (h *Helper) DecryptableKeyVersions() []string

DecryptableKeyVersions lists the labels this node still opens, current first, for aerolvm_key_decryptable (eng D23: a rotation waits until every member can open the new label before switching to it).

func (*Helper) Info

func (h *Helper) Info() Info

Info is what the helper reported about its token at its last start; the zero Info until a start succeeds.

func (*Helper) Unwrap

func (h *Helper) Unwrap(ctx context.Context, wrapped []byte, encCtx map[string]string) ([]byte, error)

Unwrap implements secrets.DataKeyWrapper.

func (*Helper) Wrap

func (h *Helper) Wrap(ctx context.Context, dek []byte, encCtx map[string]string) ([]byte, error)

Wrap implements secrets.DataKeyWrapper.

type HelperOptions

type HelperOptions struct {
	// Socket is the helper's Unix socket. Its directory is made 0700, and
	// the helper makes the socket 0600.
	Socket string
	Token  TokenConfig
	// contains filtered or unexported fields
}

HelperOptions configures the sandboxd side of the helper.

type InProcess

type InProcess struct {
	// contains filtered or unexported fields
}

InProcess is the token used directly as a secrets.DataKeyWrapper, for the short-lived `sandboxd key` CLI: a vendor crash there only ends the command, so it needs no helper (§2). sandboxd itself always uses Helper.

func OpenInProcess

func OpenInProcess(cfg TokenConfig) (*InProcess, error)

OpenInProcess opens the token in this process.

func (*InProcess) Close

func (p *InProcess) Close()

Close closes the token.

func (*InProcess) Info

func (p *InProcess) Info() Info

Info is what the token reports.

func (*InProcess) Unwrap

func (p *InProcess) Unwrap(ctx context.Context, wrapped []byte, encCtx map[string]string) ([]byte, error)

Unwrap implements secrets.DataKeyWrapper.

func (*InProcess) Wrap

func (p *InProcess) Wrap(ctx context.Context, dek []byte, encCtx map[string]string) ([]byte, error)

Wrap implements secrets.DataKeyWrapper.

type Info

type Info struct {
	HardwareSlot  bool     `json:"hardware_slot"`
	TokenLabel    string   `json:"token_label"`
	Manufacturer  string   `json:"manufacturer"`
	Model         string   `json:"model"`
	KeyLabel      string   `json:"key_label"`
	DecryptLabels []string `json:"decrypt_labels,omitempty"`
	IVMode        string   `json:"iv_mode"`
}

Info describes the token the helper opened, for the hardware-slot rule and the custody report.

type Token

type Token struct {
	// contains filtered or unexported fields
}

Token is one HSM token opened by the helper: a logged-in session pool and the configured key labels.

func OpenToken

func OpenToken(cfg TokenConfig) (*Token, error)

OpenToken opens the vendor module and the configured token.

func (*Token) Close

func (t *Token) Close()

Close closes every pooled session and finalizes the module.

func (*Token) Info

func (t *Token) Info() Info

Info implements backend.

func (*Token) Ping

func (t *Token) Ping(ctx context.Context) error

Ping implements backend: the current key is on the token right now.

func (*Token) Unwrap

func (t *Token) Unwrap(ctx context.Context, raw, aad []byte) ([]byte, error)

Unwrap implements backend.

func (*Token) Wrap

func (t *Token) Wrap(ctx context.Context, dek, aad []byte) ([]byte, error)

Wrap implements backend: AES-GCM under the current label, 128-bit tag.

type TokenConfig

type TokenConfig struct {
	Module        string
	TokenLabel    string
	PINFile       string
	KeyLabel      string
	DecryptLabels []string
	IVMode        string
	// Sessions is the session pool: the foreground cap plus the background
	// slots (eng D13), so background work never takes a session a create
	// needs.
	Sessions int
}

TokenConfig is the SB_SECRET_PKCS11_* settings, handed to the helper as flags so it never re-reads sandboxd's configuration.

Jump to

Keyboard shortcuts

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