Claim

Table of Contents

Introduction

The Claim module, in conjunction with the Attestation Protocol, enables the possibility to create verifiable claims. These claims are backed by trusted authorities and can be used to authenticate an entity to a third party.

To do so, a trusted authority signs and stores a fingerprint (hash) of an entity related data set on the blockchain. A verifier can later use this fingerprint to verify the integrity and authenticity of a self-created authentication claim received.

A key benefit of only storing the fingerprint instead of the full data set is privacy protection. This approach lets an entity share pieces of attested user data in a way that a verify can validate these pieces without knowing the full data set.

A claim based authentication system could be built on top of these two modules.

Claim Elements

A claim object, representing a claim, contains the following elements:

// TypeScript notation
interface ClaimObject {
    userData: [
        {
            name: string;
            value: string;
            nonce: string;
        }
    ] | [], // empty array allowed
    hashes: {
        leafHashes: string[];
        rootHash: string;
    }
}

UserData

The userData array contains the user data bundled in an object with the following properties:

user data object properties

The name property contains the name of a user data. It can be a string of any kind. The value property contains the actual user data, and the nonce is needed for unique leaf hash generation.

Hashes

As described above, an entity/user should be able to create a claim with a subset of one's user data. To achieve this, a hash tree based on the user data is created and added to the claim.

To prevent an attacker from recreating the root hash based on collected data, every user data bundle includes a unique nonce. This nonce produces different root hashes even if two user data contain the same name and value.

A flat tree structure with an order of n and a depth of 2 should be used:

hash tree based on user data with order n and depth 2

Whenever an entity wants to authenticate itself, it shares the requested user data subset along with the necessary hashes to recreate the hash tree. A verifier then recreates the hash tree and compares the root hashes to verify the integrity of the shared data.

The hashes object bundles the necessary hashes to recreate the hash tree.

hashes object properties

The leafHash property holds the leaf hashes needed to recreate the root hash. A leaf hash is only included if the corresponding user data is not part of the user data array.

To gain consistency, each property of a user data object is first sorted alphanumerically by property key. The values of these properties are then concatenated to a utf8 string and finally hashed with the sha256 hash function.

/* User data object */
{
    name: "user-data-name",
    value: "user-data-value",
    nonce: "EnYg7EpDzOSPJM3QVfi0DtKmgwiYX4slAv5zNPmenSXiM5PSPAz03PfNI5C1XEDV"
}


/* 1. Sort keys alphanumerically */
{
    name: "user-data-name",
    nonce: "EnYg7EpDzOSPJM3QVfi0DtKmgwiYX4slAv5zNPmenSXiM5PSPAz03PfNI5C1XEDV",
    value: "user-data-value"
}


/* 2. Concatenate values */
"user-data-nameEnYg7EpDzOSPJM3QVfi0DtKmgwiYX4slAv5zNPmenSXiM5PSPAz03PfNI5C1XEDVuser-data-value"


/* 3. Convert string to utf8 and create leaf hash */
"4add21b3a1ed01e56594a1f32034de55be10d1b5f88dd3e6217a1ae51f344623"

The root hash property holds the claim representing root hash. It is the result of a hash generation (sha256) based on all leaf hashes. To gain consistency, all leaf hashes are alphanumerically sorted and concatenated beforehand, too. The resulting utf8 string is then used for the root hash generation.

/* Leaf hash array */
[
    "4add21b3a1ed01e56594a1f32034de55be10d1b5f88dd3e6217a1ae51f344623",
    "2062f74d687e4d8498116de9ea9a63f89b2b98b5442989c474088d27da618300",
    "783fd6868618d40f86aec0d3468fb15a1aa6464d0bd34eea9478b8d3637becd8",
    "e665592df0614a0c6d837145b94887ed80d450a365a46e93cfed00fca91ac54d"
]


/* 1. Sort leaf hashes alphanumerically */
[
    "e665592df0614a0c6d837145b94887ed80d450a365a46e93cfed00fca91ac54d",
    "2062f74d687e4d8498116de9ea9a63f89b2b98b5442989c474088d27da618300",
    "4add21b3a1ed01e56594a1f32034de55be10d1b5f88dd3e6217a1ae51f344623",
    "783fd6868618d40f86aec0d3468fb15a1aa6464d0bd34eea9478b8d3637becd8"
]


/* 2. Concatenate leaf hashes */
"e665592df0614a0c6d837145b94887ed80d450a365a46e93cfed00fca91ac54d2062f74d687e4d8498116de9ea9a63f89b2b98b5442989c474088d27da6183004add21b3a1ed01e56594a1f32034de55be10d1b5f88dd3e6217a1ae51f344623783fd6868618d40f86aec0d3468fb15a1aa6464d0bd34eea9478b8d3637becd8"


/* 3. Convert string to utf8 and create root hash */
"f35c8ac4a881987e38c84a336d91ff3039eeeac42d8bb5baa9dab6448c64fa46"

Authentication Workflows

There are three major steps for a claim based authentication mechanism: claim registration, claim creation, and claim verification.

claim authentication workflows

The claim registration process registers a claim to an account. To do so, an attestor attests an account with the claim's root hash as payload. This ensures that a claim is verified by a trusted entity (the attestor).

An attested account holder can then create verifiable claims self sovereignly. One selects the necessary claim user data, creates the claim, and signs it in the way described in the Attestation Protocol. The resulting data set (containing the claim as payload) is a verifiable claim and ready to be shared with a verifier.

To verify a verifiable claim, one needs to follow the Attestation Protocol verification process with two additionally verification steps.

The first step is to verify the integrity of a claim. At the point of signed data checking, one needs to extract the previously created claim embedded into the singed data payload, recreate the root hash (based on the claim user data and leaf hashes), and compare it with the claim rootHash value.

The second step needs to be embedded into the entity check process. One checks if the claim creator account contains the self-created root hash as payload, which proves that an attestor account attested the claim. If the Attestation Protocol verification process finally succeeds, the verifier can be sure that the claim creator account indeed signed the claim, the claim data are valid and attested by an entity which is itself attested by a trustworthy entity.