Compare the options
For production operators, use a YubiKey or a Turnkey-hosted operator. A local key file is a plaintext seed, so keep it to development, or to CI pipelines where the seed is injected from a secrets manager through
TVC_OPERATOR_SEED and never written to disk.
A manifest set can include both self-hosted and Turnkey-hosted operators. A share set must be all self-hosted or all Turnkey-hosted.
The list_tvc_operators query lists the operators registered in your organization.
Self-hosted keys
Self-hosted operators keep their private keys with you. Turnkey learns only the public keys, when the operator is included in an operator set’snewOperators at app creation, and every signature and decryption happens on your hardware.
YubiKey
A YubiKey operator keeps the operator’s two private keys, the signing key and the encryption key, in the token’s PIV application, generated on the device so they can never be exported. Signing and decryption happen on the YubiKey and require the PIV PIN and a physical touch every time.tvc only uses operations the PIV PIN unlocks: signing and key agreement with existing keys. It never holds the PIV management key, so it cannot generate, import, or delete keys or certificates on the device. Those changes are made with YubiKey Manager (ykman) commands you run yourself, so you can audit exactly what touches the device.
Prerequisites. YubiKey firmware 5.3 or later (check with ykman info), the ykman CLI, and a current tvc installation. The examples assume one YubiKey is connected; with several, unplug the others or pass --serial <SERIAL>.
1
Harden PIV access
Optional for an already-hardened device, but recommended before generating operator keys. Each command prompts for the current and replacement credential.
--protect stores the generated management key on the YubiKey behind the PIN, so later ykman administrative operations can authorize with a PIN prompt. tvc never reads or uses this key.2
Generate the operator keys
Generate both private keys on the device with the policies TVC requires:The printed public keys can be discarded; the next step reads them back from device metadata. Algorithm, origin, and policies can’t be corrected after the fact. If
tvc later rejects a slot, regenerate it with the exact options above, but never regenerate a slot whose key is already in use as an operator.3
Create and import the certificates
QuorumOS expects each slot to carry a self-signed certificate with subject
CN=QuorumOS. Create them with tvc, which prompts for the PIN and one touch per slot, then import them with ykman:create-certs writes the two PEM files to the current directory and doesn’t modify the device. --verify proves each certificate matches the private key in its slot. The PEM files hold public certificates only, so they’re safe to keep for auditing.4
Register the YubiKey with tvc
Cache the device’s operator public keys in the local The command prints the canonical hexadecimal serial that later
tvc configuration. This needs neither the PIN nor a touch:tvc commands expect.5
Add the operator to an organization
With the target organization active, create an operator record that points at the registered serial. This step is local: it uses the cached public keys and doesn’t contact Turnkey or modify the device. As with a local key file, Turnkey learns the public keys when the operator is included in an operator set’s
--default makes YubiKey the organization’s default operator kind, so commands pick it without --serial when it’s the only one:newOperators at app creation. You can also pick YubiKey instead of Local key file when tvc login sets up a new organization.9c key. The CLI prompts for the PIN and waits for a touch:
9d key decrypts the share during re-encryption:
tvc yubikey unregister --serial <SERIAL>. This only edits the local configuration. The keys stay on the device, and the operator remains valid for any organization that still trusts its public keys. Remove it from a Turnkey operator set by creating a new set.
Local key file
tvc login generates a 32-byte master seed on your machine. Both the signing key and the encryption key are derived from that seed following the QOS key set specification. The seed is written as JSON to:
newOperators field when you run tvc app init, or which you paste into the dashboard when creating an app there.
The seed is stored unencrypted. The CLI writes the file with owner-only permissions, so its protection is the operating system’s access control and whatever disk encryption the machine has. Anyone who can read the file can act as that operator.
tvc login offers to back the key up during onboarding, and you can do it any time:
operator.json, so it holds the same plaintext seed as the original.
Approve manifests. With the organization active, the CLI reads the key from the file automatically:
tvc login, pass the seed explicitly with --operator-seed-path <FILE> (a file containing the raw hex seed) or --operator-seed <HEX>. The two flags are mutually exclusive.
Add --skip-post to sign without contacting the API, for example on an air-gapped machine. The CLI writes the approval JSON to stdout or to --approval-out <PATH>. There is no CLI command to submit a saved approval; post it with the create_tvc_manifest_approvals activity using the manifest ID, operator ID, and hex-encoded signature.
Hold Quorum Key shares. Local operators can be share set members too, but the share lifecycle runs on your machine rather than through Turnkey:
tvc keys generate-local-quorum-keygenerates a Quorum Key, splits it with Shamir’s Secret Sharing, and encrypts each share to an operator’s encryption key.- When an enclave boots,
tvc keys re-encrypt-local-shareverifies the enclave’s attestation and manifest approvals, then re-encrypts your share to the enclave’s Ephemeral Key. tvc deploy post-sharesubmits the re-encrypted share.
--operator-seed and --operator-seed-path flags as deploy approve. Run tvc keys init-local-quorum-key to generate a template configuration for step 1.
Turnkey-hosted keys
A Turnkey-hosted operator keeps its keys in two P-256 wallet accounts in your Turnkey organization.tvc operator create calls the create_tvc_operator activity, which creates a wallet named tvc-wallet (or reuses one you pass with --wallet-id) and derives two accounts under a base path. The default base path is m/5527107'/0'/0', where 5527107 is the ASCII bytes of TVC. Turnkey appends /0 for the encryption account and /1 for the signing account.
--account-path.
Who controls the key. The private keys never leave Turnkey’s enclaves, and they are never returned to the CLI. Every use of a hosted operator is a Turnkey activity submitted with your API key, so it is subject to the same controls as any other activity in your organization: the submitting user’s permissions, policies, consensus requirements, and the activity log. The relevant activity types are ACTIVITY_TYPE_SIGN_RAW_PAYLOAD for approvals and ACTIVITY_TYPE_RE_ENCRYPT_TVC_QUORUM_KEY_SHARE for share provisioning.
Approve manifests. The same command as a local operator. The CLI recognizes the operator ID as a hosted operator and signs the approval through the sign_raw_payload activity instead of a local key:
--skip-post is not available for hosted operators, since signing requires the API.
Hold Quorum Key shares. Hosted operators have a shorter share lifecycle because Turnkey holds the encrypted shares:
tvc keys create-quorum-key --threshold <N> --operator-ids <IDS>creates the Quorum Key inside Turnkey’s enclaves with one share encrypted to each hosted operator.tvc deploy provision --deploy-id <ID> --operator-id <ID>verifies the enclave’s attestation and approvals, then calls there_encrypt_tvc_quorum_key_shareactivity to re-encrypt that operator’s share to the enclave’s Ephemeral Key.
See also
- Manifest sets and share sets for how operators are grouped and what their thresholds protect
- Quickstart for the local-key flow end to end
create_tvc_operatorandlist_tvc_operatorsAPI references