Advanced customer enablement
This optional upper-tier path is only for customers who require AWS Nitro or GCP Confidential Space to gate release of the qURL sidecar private key. The standard tunnel install remains the simple default; use this guide after that requirement is confirmed.
Stores private_key.sealed.json instead of durable plaintext key material.
KMS releases only to the approved Nitro or Confidential Space workload.
OpenNHP plaintext config exists only in the process-lifetime runtime dir.
Outcomes
Standard qURL tunnel onboarding does not require this tier. When a customer opts into attested custody, the sidecar still uses the normal first bootstrap or recovery key, but steady state should run from persisted sealed state without keeping QURL_API_KEY or QURL_API_KEY_FILE mounted.
private_key.sealed.json, not durable plaintext private_key.Architecture model
For this advanced mode, the qURL client fails closed and checks local config, but confidentiality comes from the AWS KMS key policy for Nitro or the GCP Workload Identity Federation and Cloud KMS IAM binding for Confidential Space.
file stores durable plaintext key material in the sidecar state directory. Use for development or low-sensitivity local deployments.
aws-kms and gcp-kms store sealed state, but do not add an attested release condition.
aws-nitro and gcp-confidential-space tie unseal to cloud attestation and approved workload identity. Use this only when a customer requires attested key release.
Inputs
Do not start this optional migration until the platform owner and security owner agree on provider, rollout gates, and rollback ownership.
Collect the one-time qURL API key, a stable LAYERV_AGENT_ID, and the persistent state path before first start.
Use a tmpfs-backed path such as /dev/shm, or set LAYERV_NHP_RUNTIME_DIR. Disk fallback requires explicit LAYERV_ALLOW_DISK_NHP_RUNTIME_DIR opt-in.
Name the KMS key, steady-state principal, attestation claims, negative-test owner, and audit-log evidence location.
For migration, preserve a pre-migration state backup if the customer policy requires rollback to the file provider.
Provider choice
Switching an existing file provider volume to a sealed provider is a one-way migration unless the customer restores a pre-migration backup.
AWS Nitro onboarding
aws-nitro uses normal KMS encrypt for first seal, then requires AWS KMS Recipient decrypt on unseal. The client expects CiphertextForRecipient and fails closed if AWS returns host plaintext.
kms:Encrypt.LAYERV_KEY_PROVIDER=aws-nitro
LAYERV_AWS_KMS_KEY_ID=arn:aws:kms:us-east-1:111122223333:key/...
LAYERV_AWS_KMS_REGION=us-east-1
LAYERV_AWS_NITRO_ATTESTATION_DOCUMENT_FILE=/run/qurl/attestation.cose
LAYERV_AWS_NITRO_ATTESTATION_DOCUMENT_ENCODING=raw
LAYERV_AWS_NITRO_RECIPIENT_UNWRAP_COMMAND=/opt/qurl/bin/unwrap-recipient
QURL_API_KEY_FILE=/run/secrets/qurl-api-key
LAYERV_AGENT_ID=customer-prod-agent-01{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowQurlAgentFirstSeal",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/qurl-agent-provisioner"
},
"Action": "kms:Encrypt",
"Resource": "*"
},
{
"Sid": "AllowQurlAgentNitroDecrypt",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/qurl-agent-parent"
},
"Action": "kms:Decrypt",
"Resource": "*",
"Condition": {
"StringEqualsIgnoreCase": {
"kms:RecipientAttestation:ImageSha384": "PCR0_OR_IMAGE_SHA384_HEX"
}
}
}
]
}"Resource": "*" refers to the current key.arn:aws:iam::111122223333:role/qurl-agent-parent, because IAM ARNs are regionless.kms:RecipientAttestation:PCR<PCR_ID> conditions when the customer wants PCR1, PCR2, or custom PCR binding.GCP Confidential Space onboarding
gcp-confidential-space checks local Confidential Space claims before KMS calls, but the local parse is not a JWT verifier. WIF/IAM plus Cloud KMS are the real cryptographic release boundary.
If the customer does not enforce the same image digest and service account in WIF/IAM, local token claims can pass startup while Cloud KMS still releases the key. Treat the negative IAM test as a production gate.
LAYERV_KEY_PROVIDER=gcp-confidential-space
LAYERV_GCP_KMS_KEY_NAME=projects/acme-prod/locations/us/keyRings/qurl/cryptoKeys/agent-identity
LAYERV_GCP_CONFIDENTIAL_SPACE_TOKEN_FILE=/run/container_launcher/attestation_verifier_claims_token
LAYERV_GCP_CONFIDENTIAL_SPACE_IMAGE_DIGEST=sha256:...
LAYERV_GCP_CONFIDENTIAL_SPACE_SERVICE_ACCOUNT=qurl-agent@acme-prod.iam.gserviceaccount.com
QURL_API_KEY_FILE=/run/secrets/qurl-api-key
LAYERV_AGENT_ID=customer-prod-agent-01APPROVED_IMAGE_DIGEST="sha256:..."
gcloud iam workload-identity-pools providers create-oidc attestation-verifier \
--location=global \
--workload-identity-pool=QURL_AGENT_POOL \
--issuer-uri="https://confidentialcomputing.googleapis.com" \
--allowed-audiences="https://sts.googleapis.com" \
--attribute-mapping='google.subject="gcpcs::"+assertion.submods.container.image_digest+"::"+assertion.submods.gce.project_number+"::"+assertion.submods.gce.instance_id,attribute.image_digest=assertion.submods.container.image_digest' \
--attribute-condition="assertion.swname == 'CONFIDENTIAL_SPACE' && 'STABLE' in assertion.submods.confidential_space.support_attributes && assertion.submods.container.image_digest == '${APPROVED_IMAGE_DIGEST}'"
gcloud kms keys add-iam-policy-binding \
projects/acme-prod/locations/us/keyRings/qurl/cryptoKeys/agent-identity \
--member="principalSet://iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/QURL_AGENT_POOL/attribute.image_digest/${APPROVED_IMAGE_DIGEST}" \
--role=roles/cloudkms.cryptoKeyEncrypterDecrypterThe ${APPROVED_IMAGE_DIGEST} placeholders are shell variables set at the top of the snippet; keep them literal when copying the block.
/run/container_launcher/attestation_verifier_claims_token.swname=CONFIDENTIAL_SPACE, dbgstat=disabled-since-boot, and STABLE support attributes.Bootstrap and migration
The sidecar writes sealed state only after it proves the selected provider can unseal it. If verification fails, the client exits rather than writing an unusable sealed blob.
QURL_API_KEY_FILE.LAYERV_AGENT_ID.LAYERV_KEY_PROVIDER to the sealed provider.LAYERV_ALLOW_KEY_MIGRATION=true for one restart only.private_key.sealed.json exists.Validation plan
The customer change ticket should include startup state, tunnel restart behavior, negative cloud policy tests, and cloud audit evidence.
These examples use the default state directory. If the deployment sets LAYERV_AGENT_STATE_DIR, replace /var/lib/layerv/agent with that path.
# Confirm sealed state
ls -la /var/lib/layerv/agent
test -f /var/lib/layerv/agent/private_key.sealed.json
test ! -f /var/lib/layerv/agent/private_key
# Confirm the provider recorded in the sealed blob
grep -m1 -E '"provider"[[:space:]]*:[[:space:]]*"(aws-nitro|gcp-confidential-space)"' \
/var/lib/layerv/agent/private_key.sealed.json
# Confirm steady-state restart does not need the API key
# Remove QURL_API_KEY / QURL_API_KEY_FILE from compose or service env first.
docker compose up -d --force-recreate qurl-agentOperations handoff
After onboarding, the customer operations owner should know when an API key is needed, what state to preserve, how attestation failures surface, and which audit logs matter.
Keep the qURL API key available only for first bootstrap or state recovery.
Do not delete or share the state volume; it contains the stable agent identity and sealed key blob.
Coordinate KMS key policy changes with qURL restarts.
Review CloudTrail or Cloud Audit Logs for unexpected decrypt attempts.
Troubleshooting
Most failures are missing provider env vars, stale attestation inputs, cloud policy mismatch, or state volume drift.
Set the provider-specific env vars in this guide. For GCP, image digest and service account are required before the token file is read.
Verify the helper runs in the attested runtime and writes exactly 32 raw private-key bytes to stdout with no trailing newline.
Fix the key policy or attestation document. aws-nitro intentionally rejects host plaintext and requires CiphertextForRecipient.
Compare local pins to WIF attribute mapping and Cloud KMS IAM binding. The federated principal must match the approved workload.
Restore the correct state directory or intentionally re-bootstrap. The API key is only for first bootstrap or state recovery.
Related docs
Start with the standard tunnel install guide, then use this optional advanced companion only when the customer needs attested key custody.