Structure to Function

To properly use mDocs in a digital trust ecosystem, one must gain a good understanding of their structure, and how it relates to their function.

Data structure

From claims to an mDoc

mDocs issuers ascertain verifiable information about holders they issue credentials to. This information is referred to as claims and is stored in systems which are referred to as claims sources. When these claims are issued in an mDoc they are grouped into namespaces to prevent collision between claim names.

When creating a presentation from an mDoc and sharing it with a verifier, it only includes a subset of the raw claims from the mDoc. These are the elements required by the verifier that the holder had consented to disclose. By comparing these elements to the corresponding salted hashes in the Mobile Security Object (MSO), the verifier can ascertain the claims’ integrity.

The following diagram depicts the mDoc and Presentation architecture which includes the aforementioned elements:

• MSO: A COSE_sign1 structure (CBOR standard for presenting digital signatures) comprising several components:
  • Header : Details the algorithm being used.
    • DSC : The Document Signer Certificate (DSC) is included in the MSO and can be used alongside the IACA certificate to verify the MSO signature.
  • Issuer Signature : The signature of the mDoc’s issuer.
  • Payload: The element signed by the DSC. It includes the following components:
    • Device public key.
    • Credential validity period.
    • Metadata (key type, authorisations, etc.).
    • Element Digest/Hash: An array that includes all the salted hashes of issuer signed claims.
• All Elements : Includes the raw claims grouped by namespaces. Each element within a namespace includes the claim name, claim value and salt value.

From an mDoc to a presentation

The following diagram depicts what elements are carried through when we creating a presentation from an mDoc and sharing it with a verifier:

• DSC : Required to verify the MSO signature.
• Selected Elements : The subset of raw claims from the mDoc. These are the elements required by the verifier and agreed to be shared by the holder. Comparing these elements to the corresponding hashes in the MSO, the verifier can ascertain their integrity.
• Device Auth : A signature produced using the private key associated with the device public key in the MSO over the unique session data.

Function

The structure described above serves the following capabilities:

Salted hashed claims enable selective disclosure

The MSO is always included in an mDoc presentation to enable validating the issuer signature. Selective disclosure would not be possible if all claims in the MSO were signed then revealed to every verifier. The salted hashing of claims into the MSO ensures that it provides no data and only proves that what is disclosed and presented by the holder was indeed signed by the issuer.

When a verifier is validating an mDoc presentation, they re-compute the hash/digest for each revealed claim and its salt, and try to match it to the one referenced in the MSO. If the match is successful then the integrity of the claim back to the issuer is proven. If they don’t match, the value is rejected and the presentation is invalid. This structure enables the holder to selectively disclose a subset of their credential claims, and the verifier to verify this subset of claims.

Salt values support unwanted disclosures protection

Since hash functions are repeatable, brute forcing might enable verifiers to guess unrevealed claims when their enumeration is very limited (for example nationality can only be a two letter country code defined in ISO 3166-1).

To solve this, the issuer adds a unique random massive number (commonly referred to as nonce or salt) to each claim value for every hash that is created. This means you can only reconstruct the hashed claim if you have both the salt and the claim value:

Device Auth provides anti-cloning and replay protection

The Device Auth element authenticates that the device presenting the credential is the same one that the credential was issued to.

When an issuer issues an mDoc, the device generates a private key that is locked to its hardware. That same private key must be used whenever the credential is presented to a verifier, both in-person and remotely (online). Assuming the private key is exclusively bound to a device, it prevents anti-cloning, and the relying party can trust that the credential is both valid and is presented by the intended device.

Device authentication can be implemented in one of two methods, both supported by the ISO/IEC 18013-5:2021 specification:

• Signature authentication: The holder uses the device key to produce a digital signature that is included in the device’s response, authenticating the holder’s possession of the device key to the verifier. This is considered a non-repudiable method.
• ECDH-agreed Mac based authentication: The holder and the verifier use their own private key and the other parties public key to generate a mutually agreed key using ECDH (Elliptic Curve Diffie Helman). This prevents scenarios where a verifier may attempt to share the response with a 3rd party without the holder’s consent. Since both parties (the holder and the verifier) could generate the same MAC, the verifier cannot prove to a 3rd party that it was the holder who generated the MAC. This method is considered to be non-repudiable to the verifier, but it is repudiable to a 3rd party as it can’t tell whether the MAC was produced by the holder or the verifier.

Replay protection is achieved using the same mechanism by signing over the session transcript, acting as a fingerprint of the current session between the verifier and the holder.

Issuer Auth enables offline verification

The mDoc is constructed in a way that the verifier only needs the IACA’s certificate of the issuer to verify a presented credential. Everything else (DSC, MSO) exists within the mDoc itself, enabling offline verification as no internet access is required to retrieve any information.