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 ¶
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.
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 ¶
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.