Structure to function

To properly use Mobile Credentials 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 a Mobile Credential

Mobile Credential issuers need 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 a Mobile credential, to prevent collision between claim names, claims are grouped into namespaces.

When we create a presentation from a Mobile Credential and present it to a verifier, it only includes a subset of the raw claims from the Mobile Credential. These are the elements required by the verifier that the holder had consented to disclose. By comparing these elements to the corresponding hashes in the MSO, the verifier can ascertain the claims' integrity.

The following diagram depicts the Mobile Credential and Presentation architecture and the aforementioned elements:

  • IssuerAuth: A COSE_sign1 structure (CBOR standard for presenting digital signatures) comprising several components:

    • Header: Details the algorithm being used.

      • DSC: The certificate is included in the credential and can be used to verify the MSO signature.

    • Issuer Signature: The signature of the Mobile Credential’s issuer.

    • Mobile Security Object (MSO): The element signed by the Document Signer Certificate (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 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 a Mobile Credential to a presentation

The following diagram depicts what elements are carried through when we create a presentation from a Mobile Credential and present it to a verifier:

  • DSC: Required to verify the MSO.

  • MSO: Required to verify the signature.

  • Selected Elements: The subset of raw claims from the Mobile Credential. 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.


The structure described above serves the following capabilities:

Salted hashed claims enable selective disclosure

The MSO is always included in a Mobile Credential 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 signed by the issuer. 

When a verifier is validating a Mobile Credential presentation, they re-compute the hash/digest for each revealed claim and its salt, and try to match it to the referenced one 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.

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 that only if you have both the salt and the hash function are you able to reconstruct the hashed claim:

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 a Mobile Credential, 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. 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. The 3rd party has a different public/private key combination and will not be able to generate the same mutually agreed key. This method is considered to be non-repudiable to the verifier, but it is repudiable when a 3rd party tries to use the same authentication.

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 Mobile Credential 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, Issuer signature) exists within the Mobile Credential itself, enabling offline verification as no internet access is required to retrieve any information.

What’s Next?

You should now have a good understanding of the key concepts and technologies that are used by Mobile Credentials, as well as how they are structured and what communication protocols are used to present them. You can now better understand where Mobile Credentials fit across MATTR platforms.