The Master Secret — Operator training

One environment variable protects every software-custody CA key you will ever create. GOCA_MASTER_SECRET is the root of software key protection: the KEK that wraps every CA private key is derived from it, and so is the key that signs operator and API tokens. The shipped compose file sets a well-known development value — fine for evaluation, unacceptable for anything real. Treat every key and token created under it as public.

For a real deployment: set a long random value via your secret mechanism, before creating your hierarchy. Changing it later makes every wrapped key unusable — that is the design: a stolen database without the secret is inert. Escrow it with the same care as an HSM's admin card set; losing it means losing every software-custody CA key.

And give it only to the containers that must unwrap a CA key — the all-in-one, the API service and the key service. The RA runs without it, deliberately: the component that authorizes issuance can unwrap nothing. Handing it the secret quietly undoes that.

Metaphor: the blank from which every key in the building is cut.

Where it breaks: replacing a physical master key re-keys the locks. Replacing this one bricks them — every wrapped key becomes permanently unusable, on purpose.

Now I can say what the master secret protects, who may hold it, and why losing it is unrecoverable.