HomeISO mDOCMSO & Security

Mobile Security Object (MSO)

The MSO is the heart of mDOC security. It contains hashes of all data elements, validity information, and the device public key, all signed by the issuer.

What is the MSO?

The Mobile Security Object (MSO) is a CBOR structure that binds together all the security properties of an mDOC. It's signed by the issuer using a COSE_Sign1 structure and contains:

Value Digests

SHA-256 hashes of each IssuerSignedItem, enabling selective disclosure verification.

Validity Info

Timestamps defining when the credential is valid and when to refresh.

Device Key

Public key bound to the holder's device for authentication during presentation.

Issuer Signature

COSE signature with X.509 certificate chain for trust verification.

MSO Structure

The MSO is embedded in the issuerAuth field as the payload of a COSE_Sign1 structure.

MSO CBOR Structure
MobileSecurityObject = {
  "version": "1.0",
  "digestAlgorithm": "SHA-256",
  "valueDigests": {
    "org.iso.18013.5.1": {
      0: h'...hash of IssuerSignedItem 0...',
      1: h'...hash of IssuerSignedItem 1...',
      2: h'...hash of IssuerSignedItem 2...',
      // digestID → SHA-256 hash
    },
    "org.iso.18013.5.1.aamva": {
      0: h'...hash...',
      1: h'...hash...'
    }
  },
  "docType": "org.iso.18013.5.1.mDL",
  "validityInfo": {
    "signed": tag(0) "2024-01-15T10:00:00Z",
    "validFrom": tag(0) "2024-01-15T10:00:00Z",
    "validUntil": tag(0) "2029-01-15T10:00:00Z",
    "expectedUpdate": tag(0) "2025-01-15T10:00:00Z"  // optional
  },
  "deviceKeyInfo": {
    "deviceKey": {
      1: 2,       // kty: EC
      -1: 1,      // crv: P-256
      -2: h'...', // x coordinate
      -3: h'...'  // y coordinate
    },
    "keyAuthorizations": {...},  // optional
    "keyInfo": {...}             // optional
  }
}

Value Digests

The valueDigests map contains SHA-256 hashes of each IssuerSignedItem, organized by namespace. This is the key to selective disclosure.

How It Works

  1. 1
    Issuance: Issuer creates IssuerSignedItem for each claim with random salt
  2. 2
    Hashing: Issuer computes SHA-256(CBOR(IssuerSignedItem)) for each item
  3. 3
    MSO: Hashes are stored in valueDigests with digestID as key
  4. 4
    Signing: Issuer signs the MSO using COSE_Sign1
  5. 5
    Presentation: Holder sends only selected IssuerSignedItems + full MSO
  6. 6
    Verification: Verifier hashes received items, matches against MSO digests
Privacy Through Salted Hashes
Because each IssuerSignedItem contains a random salt, the verifier cannot guess or brute-force undisclosed values from the hashes in the MSO.

Validity Information

The validityInfo structure defines the temporal validity of the credential.

FieldDescription
signedTimestamp when the MSO was signed by the issuer
validFromEarliest time the mDOC should be accepted
validUntilLatest time the mDOC should be accepted
expectedUpdateHint for when holder should refresh the credential (optional)

Date Format

All dates use CBOR tag 0 (ISO 8601 date-time string) or tag 1004 (full-date). Example: tag(0) "2024-01-15T10:00:00Z"

Device Key Binding

The deviceKeyInfo contains the public key that the holder must prove possession of during presentation. This binds the credential to a specific device.

Device Key (COSE_Key)
"deviceKeyInfo": {
  "deviceKey": {
    1: 2,       // kty: EC (Elliptic Curve)
    -1: 1,      // crv: P-256 (secp256r1)
    -2: h'...x-coordinate...',  // 32 bytes
    -3: h'...y-coordinate...'   // 32 bytes
  }
}

Secure Element Storage

The private key should be stored in secure hardware (SE, TEE) and never exported.

Per-Credential Key

Each mDOC typically has its own device key pair to prevent correlation across credentials.

Anti-Theft Protection
During presentation, the holder must sign a session transcript with this device key. Without the private key, a stolen credential is useless.

Trust Chain (X.509)

mDOC uses traditional X.509 PKI for trust. The issuer's signing certificate chains up to an Issuing Authority Certificate Authority (IACA).

IACA (Root)

Issuing Authority Certificate Authority - the trust anchor. Typically operated by a government body. Verifiers must have IACA certificates pre-installed.

Document Signer (DS)

Certificate used to sign individual mDOCs. Issued by IACA. The DS certificate is included in the issuerAuth's x5chain parameter.

Verification Steps

  1. 1. Extract x5chain from issuerAuth unprotected header
  2. 2. Verify certificate chain from DS certificate to trusted IACA
  3. 3. Check certificates are not revoked (CRL/OCSP)
  4. 4. Verify MSO signature using DS certificate's public key
  5. 5. Check MSO docType matches expected document type
  6. 6. Verify current time is within validFrom and validUntil

Security Considerations

Proper trust management is critical for mDOC verification security.

IACA Trust Store Management

Certificate Chain Validation

Offline Verification
When verifying offline, ensure the trust store and revocation information are recent. Consider implementing periodic updates and grace periods for revocation checks.
Document Structure Device Authentication