ca_bootstrap

package
v0.8.0 Latest Latest
Warning

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

Go to latest
Published: Sep 23, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package ca_bootstrap mints and publishes the assisted-claiming CA and holds the operator certificate configuration it mints from. It is the logic behind the admin CA bootstrap API (see docs/en/specs/assisted-claiming.md §3.9).

The CA certificate cannot be produced at synth time: it has to be signed by the KMS key, which only exists after the base stack is deployed. Mint-once is enforced by the write itself (SSM no-overwrite), so a repeated mint cannot replace an existing CA; an explicit force (rotation) is the only overwrite.

Index

Constants

View Source
const (
	ParamKeyArn  = "/rmng/base/claiming-ca-key-arn"
	ParamCertPem = "/rmng/base/claiming-ca-cert-pem"
	ParamConfig  = "/rmng/base/claiming-config"
)

SSM parameter paths for the claiming CA material and certificate config. Defined here as constants — the way the GVA and Alexa admin config APIs name their parameters — rather than threaded through Lambda env vars. Keep these in sync with src/base_res_constants.py, which the CDK uses to create ParamKeyArn and to grant ssm access on these exact names.

View Source
const DefaultCAValidity = certissuer.DeviceCertValidity + 20*365*24*time.Hour

DefaultCAValidity exceeds the leaf lifetime rather than matching it.

The issuer clamps every leaf to the CA's expiry, so a CA with exactly the leaf lifetime would hand out steadily shorter certificates as it aged. The headroom means leaves get their full term for the first two decades of the CA's life, and the clamp remains the backstop that guarantees a leaf can never outlive its issuer. Used when Config.ValidityYears is unset.

Variables

This section is empty.

Functions

func StoreClaimingConfig

func StoreClaimingConfig(ctx context.Context, param string, cfg ClaimingConfig) error

StoreClaimingConfig writes the claiming configuration to SSM as a plain-string JSON document. It holds no secret — the private key is a non-exportable KMS key and never appears here — so it is a String, not a SecureString.

Types

type ClaimingConfig

type ClaimingConfig struct {
	// Mode is the claiming variant (e.g. "user_authenticated"). Empty means
	// claiming is configured off: the handlers fail closed until it is set.
	// Its value is validated against the implemented variants at the admin API
	// (in the claim package, which owns the Variant type) rather than here, to
	// avoid an import cycle.
	Mode string `json:"mode"`
	// MaxNodesPerClaimant is the per-caller reservation quota for the
	// user_authenticated variant; 0 means the built-in default applies.
	MaxNodesPerClaimant int                `json:"max_nodes_per_claimant"`
	Subject             certissuer.Subject `json:"subject"`
	CACommonName        string             `json:"ca_common_name"`
	CAValidityYears     int                `json:"ca_validity_years"`
	LeafValidityYears   int                `json:"leaf_validity_years"`
}

ClaimingConfig is the operator-set claiming configuration, held as a single JSON document in SSM (ParamConfig) and read by every part of the feature at runtime: CA minting, leaf issuance, the initiate/verify handlers, and the admin config API. Every field is optional; an empty one falls back to the built-in default. The subject is applied to both the CA and every leaf; the leaf Common Name is always the node ID and never comes from here.

This is the single source of truth for claiming — it deliberately replaces the deploy-time rmng-inputs.json block, so the claim stack group carries no dependency on that file. Deploying the group stands up the infrastructure; this document (plus a minted CA) is what turns claiming on.

func LoadClaimingConfig

func LoadClaimingConfig(ctx context.Context, param string, cached bool) (ClaimingConfig, error)

LoadClaimingConfig reads the claiming configuration from SSM. A configuration that has never been set (parameter absent) is not an error: it returns the zero ClaimingConfig so every consumer falls back to defaults (and claiming reads as off). cached enables the process-lifetime cache for hot read paths like leaf issuance and per-request variant/quota lookups.

func (ClaimingConfig) Validate

func (c ClaimingConfig) Validate() error

Validate rejects operator input that would produce an unusable certificate or an out-of-range quota, so a bad configuration fails at the config API rather than silently at issuance. The leaf<=CA check reasons about effective values (0 means the default) — the issuer also clamps a leaf to the CA's expiry, so this only surfaces the mistake earlier and more clearly. Mode is validated by the caller via claim.ValidateConfiguredMode (see the type doc).

type Config

type Config struct {
	KeyArnParam  string
	CertPemParam string
	// CommonName overrides the derived CA subject. Empty means derive.
	CommonName string
	// Subject adds operator-configured organizational attributes to the CA
	// subject (country, organization, etc.). Optional.
	Subject certissuer.Subject
	// ValidityYears sets the CA lifetime; 0 means DefaultCAValidity.
	ValidityYears int
	// Force overwrites an existing CA (rotation). When false, minting is
	// mint-once: an existing CA is left untouched. Rotation invalidates the
	// chain of every certificate the previous CA signed, so it is deliberately
	// opt-in and never the default.
	Force bool
}

Config is the resolved input for a bootstrap run.

type Result

type Result struct {
	AlreadyPresent bool
	CertPEM        string
	KeyARN         string
	CommonName     string
}

Result reports what a run did, so the caller can tell "minted" from "already present" without inspecting SSM again.

func BootstrapCA

func BootstrapCA(ctx context.Context, cfg Config) (Result, error)

BootstrapCA mints and publishes the claiming CA, or reports that one is already present. It is safe to run repeatedly.

Jump to

Keyboard shortcuts

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