Failure Modes¶
What happens when verification fails, and what to do about it.
Expired attestation¶
Cause: The attestation's expires_at timestamp is in the past.
Fix: Renew the attestation:
auths device extend \
--identity-key-alias my-key \
--device-did "$DEVICE_DID" \
--expires-in-days 90
Revoked attestation¶
Cause: The attestation was explicitly revoked with auths device revoke.
Fix: This is intentional. If the revocation was a mistake, link the device again:
auths device link \
--identity-key-alias my-key \
--device-key-alias device-key \
--device-did "$DEVICE_DID" \
--note "Re-linked after accidental revocation"
Invalid signature¶
Cause: The attestation JSON was modified after signing, or the wrong public key was provided for verification.
Possible causes:
- Attestation JSON was edited (even whitespace changes break canonical signatures)
- Wrong issuer public key passed to the verifier
- Data corruption in transit
Fix: Re-export the attestation from Git storage. Ensure you're using the correct issuer public key.
Broken chain¶
Cause: The chain of attestations has a gap. The subject of one attestation doesn't match the issuer of the next.
Fix: Ensure all attestations in the chain are present and ordered correctly.
Key not found¶
Cause: The referenced key alias doesn't exist in the keychain.
Fix:
Wrong passphrase¶
Cause: The passphrase entered doesn't match the one used to encrypt the key.
Fix: Try again with the correct passphrase. If forgotten, the key must be recreated.
Keychain unavailable¶
Cause: The platform keychain is not accessible (locked, missing, or unsupported).
Fix by platform:
| Platform | Action |
|---|---|
| macOS | Open Keychain Access, unlock the login keychain |
| Linux | Start the Secret Service daemon |
| CI/headless | Set AUTHS_KEYCHAIN_BACKEND=file |
Clock skew¶
Attestations may be rejected if the system clock is more than 5 minutes off. The verifier uses a tolerance of MAX_SKEW_SECS = 300.
Fix: Sync your system clock with NTP.