hw-attest-verify

Verification library for RFC Hardware-Attestation and Hardware-Trust-Proof email headers.

Receiving mail servers use this library to verify that an email was sent from a hardware-attested identity, as defined in draft-drake-email-hardware-attestation-03.

Installation

pip install hw-attest-verify

# With DNS key discovery support (recommended):
pip install hw-attest-verify[dns]

Usage

Mode 1: Hardware-Attestation (Direct Hardware Attestation)

from hw_attest_verify import verify_hardware_attestation

result = verify_hardware_attestation(
    header_value=msg["Hardware-Attestation"],
    email_headers={
        "from": msg["From"],
        "to": msg["To"],
        "subject": msg["Subject"],
        "date": msg["Date"],
        "message-id": msg["Message-ID"],
    },
    body=msg.get_payload(decode=True),
    allow_self_signed=True,  # or provide trusted_root_certificates
)

if result.is_valid:
    print(f"Verified: trust_tier={result.trust_tier}, alg={result.alg}")
    print(f"Certificate: {result.leaf_certificate_subject}")
else:
    print(f"Verification failed: {result.failure_reason}")

Mode 2: Hardware-Trust-Proof (SD-JWT Trust Proof)

from hw_attest_verify import verify_hardware_trust_proof

result = verify_hardware_trust_proof(
    header_value=msg["Hardware-Trust-Proof"],
    email_headers={
        "from": msg["From"],
        "to": msg["To"],
        "subject": msg["Subject"],
        "date": msg["Date"],
        "message-id": msg["Message-ID"],
    },
    body=msg.get_payload(decode=True),
)

if result.is_valid:
    print(f"Verified: trust_tier={result.trust_tier}")
    print(f"Issuer: {result.issuer}")
    print(f"Disclosed claims: {result.disclosed_claims}")
else:
    print(f"Verification failed: {result.failure_reason}")

Parsing without verification

from hw_attest_verify import parse_hardware_attestation_header

parsed = parse_hardware_attestation_header(header_value)
print(f"typ={parsed.typ}, alg={parsed.alg}, trust_tier={parsed.trust_tier}")
print(f"Signed headers: {parsed.signed_header_names}")
print(f"Timestamp: {parsed.ts}")

CLI: Verify a raw email

# From stdin
python -m hw_attest_verify < email.eml

# From file
hw-attest-verify email.eml

Output is JSON with is_valid, trust_tier, failure_reasons, etc.

Issuer Key Discovery (Mode 2)

The library discovers the issuer's public key using two mechanisms:

1. DNS TXT record (preferred): _hwattest.{domain} with format v=hwattest1; alg=ES256; p=<base64 SPKI DER>
2. HTTPS JWKS fallback: https://{issuer}/.well-known/jwks.json

Install dnspython for DNS discovery: pip install hw-attest-verify[dns]

Trust Tiers

RFC Reference

draft-drake-email-hardware-attestation-03 -- Hardware Attestation for Email Sender Verification

License

MIT

Spec -> code traceability (G6.3)

This is C3, the offline verifier for draft-drake-email-hardware-attestation-03. Paths relative to this package.

Verified end-to-end by gates G4.2 (tamper suite), G4.3 (live 5-tier round trips), and G4.6 (the draft's own appendix examples re-verify through this CLI). Not implemented: manufacturer-root-only chains (Profile M) -- the Issuer-certified chain format is what ships.