Skip to content

Commit

Permalink
Docs audit for credentials section (#317)
Browse files Browse the repository at this point in the history 
* Draft

Signed-off-by: Chris Chinchilla <chris@kilt.io>

* Update

Signed-off-by: Chris Chinchilla <chris@kilt.io>

* Draft

Signed-off-by: Chris Chinchilla <chris@kilt.io>

* Draft

Signed-off-by: Chris Chinchilla <chris@kilt.io>

* Update docs/concepts/05_credentials/01_overview.md

Co-authored-by: Andrés <105802444+kilted-andres@users.noreply.github.com>

* Update docs/concepts/05_credentials/01_overview.md

Co-authored-by: Andrés <105802444+kilted-andres@users.noreply.github.com>

* Update docs/concepts/05_credentials/02_ctypes.md

Co-authored-by: Andrés <105802444+kilted-andres@users.noreply.github.com>

* Update docs/concepts/05_credentials/03_claiming.md

* Update docs/concepts/05_credentials/02_ctypes.md

Co-authored-by: Andrés <105802444+kilted-andres@users.noreply.github.com>

* Update docs/concepts/05_credentials/01_overview.md

Co-authored-by: Andrés <105802444+kilted-andres@users.noreply.github.com>

* Update docs/concepts/05_credentials/01_overview.md

Co-authored-by: Andrés <105802444+kilted-andres@users.noreply.github.com>

* Update docs/concepts/05_credentials/01_overview.md

Co-authored-by: Andrés <105802444+kilted-andres@users.noreply.github.com>

* Update docs/concepts/05_credentials/01_overview.md

Co-authored-by: Andrés <105802444+kilted-andres@users.noreply.github.com>

* Update docs/concepts/05_credentials/03_claiming.md

Co-authored-by: Andrés <105802444+kilted-andres@users.noreply.github.com>

* Changes

Signed-off-by: Chris Chinchilla <chris@kilt.io>

* Update docs/concepts/05_credentials/05_verification.md

Co-authored-by: Andrés <105802444+kilted-andres@users.noreply.github.com>

* Draft

Signed-off-by: Chris Chinchilla <chris@kilt.io>

* Update docs/concepts/05_credentials/05_verification.md

Co-authored-by: Andrés <105802444+kilted-andres@users.noreply.github.com>

* Changes

Signed-off-by: Chris Chinchilla <chris@kilt.io>

* Change

Signed-off-by: Chris Chinchilla <chris@kilt.io>

* Updates

Signed-off-by: Chris Chinchilla <chris@kilt.io>

* Update docs/concepts/05_credentials/01_overview.md

Co-authored-by: Andrés <105802444+kilted-andres@users.noreply.github.com>

* Update docs/concepts/05_credentials/05_verification.md

---------

Signed-off-by: Chris Chinchilla <chris@kilt.io>
Co-authored-by: Andrés <105802444+kilted-andres@users.noreply.github.com>
  • Loading branch information
@ChrisChinchilla @kilted-andres
ChrisChinchilla and kilted-andres authored Jul 19, 2024
1 parent 2249bf7 commit cdf7e80
Show file tree
Hide file tree
Showing 6 changed files with 224 additions and 153 deletions.
30 changes: 18 additions & 12 deletions docs/concepts/05_credentials/01_overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ title: Overview

import ThemedImage from '@theme/ThemedImage';

**Credentials** consist of a set of claims which belong to a **Claimer**, are attested by an **Attester** and can be verified by **Verifiers**.
**Credentials** consist of a set of claims which belong to a **Claimer**, are attested by an **Attester**, and that a **Verifier** can verify.

<center>
<ThemedImage
Expand All @@ -17,22 +17,28 @@ import ThemedImage from '@theme/ThemedImage';
/>
</center>

To get a credential, a Claimer needs to go through following process:
To get a credential, a Claimer needs to take the following steps:

1. Find a **CType** a claim should be based on. Potential Attesters and Verifiers might advertise this information themselves.
1. Find a **CType** to base a claim on. Potential Attesters and Verifiers might advertise this information themselves.
2. Make a **claim** containing a set of properties about themselves.
3. Potentially request and receive **Terms** and agree on a **Quote** with the potential Attester.
3. Fulfil any requirement from your Attester. For example, accepting their **Terms** and paying a **Quote**.
4. **Request an attestation** from the Attester.
5. Wait for the claims to be **attested** by the Attester.
5. Wait for the Attester to **attest** claims.

Once attested, the claims are considered to be a valid credential.
Once attested, the wrapped claims are considered to be a valid credential.

To verify a credential, a Claimer can generate a presentation of it to a Verifier, with the following process:
To use a Credential, the Claimer can generate a Credential-Presentation for a Verifier.
The verification would follow this process:

1. The Verifier may request a **credential** as the first step, along with with properties to reveal from such Credential.
2. The Claimer selectively **discloses** the requested properties and signs the generated presentation.
3. The Verifier **checks** the presentation structure, content and signature, and decides whether they trust the Attester of the presented credential.
1. The Verifier may request a **Credential** of a CType, along with with properties to reveal.
He would also provide a **challenge** to ensure the presentations are not recycled.
2. The Claimer selectively **discloses** the requested properties and signs them along with the challenge to generate a presentation.
3. The Verifier **verify** the presentation structure, content and signature, and decides whether they trust the Attester of the presented credential.

Each step is described in more detail in the next sections.
The next sections describe each step in more detail.

If you want to learn about how implement the above flow in a dapp that interacts with a browser extension, please refer to the [Credential API specification](https://github.com/KILTprotocol/spec-ext-credential-api).
:::info

To learn about how to implement the flow above in a dapp that interacts with a browser extension, read the [Credential API specification](https://github.com/KILTprotocol/spec-ext-credential-api).

:::
158 changes: 82 additions & 76 deletions docs/concepts/05_credentials/02_ctypes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,124 +2,130 @@
id: ctypes
title: CTypes
---

import CodeBlock from '@theme/CodeBlock';

<!-- Taken from https://github.com/webpack-contrib/raw-loader/issues/91#issuecomment-648830498 -->

import ctypeSchema from '@site/scripts/out/ctype-schema.json.raw!=!raw-loader!@site/scripts/out/ctype-schema.json';
import ctype from '@site/scripts/out/ctype.json.raw!=!raw-loader!@site/scripts/out/ctype.json';

CTypes are data types specific to KILT that define the structure of a claim (i.e., its data model).
CTypes are based on JSON Schema, a standard used to annotate and validate JSON documents.
Claim types (CTypes) are data types specific to KILT that define the structure of a claim (i.e., its data model).
CTypes are based on [JSON Schema](https://json-schema.org/), a standard used to annotate and validate JSON documents.
The schema defines which properties exist and what their type should be, e.g., a string, a number, an object, etc.

## JSON Schema
## CType model JSON schema

KILT uses [JSON Schema](https://json-schema.org/) (currently draft-07) to validate and annotate data in a strict format.
This data format is used to define [CType models](https://github.com/KILTprotocol/sdk-js/blob/master/packages/core/src/ctype/CType.schemas.ts).
The following are all required properties of the schema:
The following are all required properties of the JSON schema for [CType models](https://github.com/KILTprotocol/sdk-js/blob/master/packages/core/src/ctype/CType.schemas.ts):

- **Identifier**: `$id` in the format `kilt:ctype:0x{cTypeHash}`.
- **Reference to CType metaschema (`$schema`)**: Describes what a valid CType must looks like. The latest metaschema is accessible at [ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/](ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/).
- **Title**: Defines a user-friendly name for the CType that makes it easier for users to contextualize.
- **Properties**: Set of fields (e.g., name, birthdate) that the CType can contain, and hence that the Claimer can have attested.
- **Type**: Is always `"object"`, instructing the JSON schema validator to expect an object (where each property is a claim about the Claimer in the credential).
- **Additional properties**: In newer CTypes, *additionalProperties* must be present and must be set to `false`, restricting allowable claims in a credential to those listed in `properties`.
- `$id`: An **identifier**: in the format `kilt:ctype:0x{cTypeHash}`.
- `$schema`: A **reference to CType metaschema**: Describes what a valid CType must looks like. You can find the latest metaschema on IPFS at the following address [ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/](ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/).
- `title`: A user-friendly name for the CType that makes it easier for users to contextualize.
- `properties`: A set of fields (e.g., name, birth date) that the CType can contain, and that the Claimer can have attested. [Read more details about properties below](#properties).
- `type`: An object containing properties for a claim about the Claimer in the credential.
- `additionalProperties`: A boolean added since version 1 of CTypes, that must be set and allows or disallows any properties in addition to those in `properties`. If set to `false`, the CType validation will fail if there are any additional properties.

:::warning
Deprecation Warning: CType metaschema draft-01
### Properties

CTypes based on the `[http://kilt-protocol.org/draft-01/ctype#](http://kilt-protocol.org/draft-01/ctype%23%60)` metaschema are susceptible to faulty or malicious attester integrations that may introduce unexpected properties to a claim.
Due to this vulnerability, this version of the metaschema is deprecated and its use is discouraged in the creation of new CTypes.
For optimal security and functionality, it is recommended to use SDK version `0.33.0` or later for creating CTypes.
This newer version defaults to using the updated metaschema available at [`ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/`](ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/%60).
When creating the accepted properties of a new CType schema, you define each property as a key-value pair.
The **key** is the property name (such as "age") and the **value** is an object that has a "type" property whose property defines which type the credential property should have (e.g., "number") or a `$ref` property whose value is a reference to another CType or one of its properties. Using a `$ref` allows for nested CTypes

This also means you should update existing CTypes.
Each property must have:

While existing CTypes will continue to work in the short term, we advise to upgrade to the latest metaschema at your earliest convenience.
- One of the following fields: `type` or `$ref`
- A type of `string`, `integer`, `number` or `boolean` to define the attribute
- Reference nested JSON schemas from previously created CTypes with a `uri` using `$ref`.
- The format field is optionally:
- _Date_ format e.g., 2012-04-23T18:25:43.511Z
- _Time_ format e.g., T18:25:43.511Z
- _URI_ format e.g., "https://www.example.com"

Old Property Value: `"$schema": "http://kilt-protocol.org/draft-01/ctype#"`
<CodeBlock className="language-json" title="CType schema example">
{ctypeSchema}
</CodeBlock>

New Property Value: `"$schema": "ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/"`
When submitted, the CType schema is hashed to generate its own identifier, and it becomes the full CType object:

**Migration instructions:**
<CodeBlock className="language-json" title="Full CType example">
{ctype}
</CodeBlock>

Attesters are recommended to transition to issuing credentials using upgraded versions of CTypes currently in use.
## CType metadata

Using sdk version `0.33.0` or later, you can produce a copy of an existing CType `oldCType` as follows:
You can link CType Metadata to a given CType to provide title and descriptions in different languages for the whole CType and its properties.

``` js
const newCType = CType.fromProperties(oldCType.title, oldCType.properties, 'V1')
```
<!-- TODO: Add example of CType metadata -->

The new CType will have the same title and properties as the existing one, but will be based on the new metaschema, resulting in a different hash and id.
After [registering the new CType on the Kilt blockchain](../../develop/01_sdk/02_cookbook/04_claiming/01_ctype_creation.md), you can use the new CType as a drop-in replacement in issuing credentials.
Depending verifiers are recommended to accept both the old and new CType during a transition period.
Test thoroughly to ensure the correct behaviour and functionality of the new CTypes in your application.
## Hashing

If you encounter any issues during the migration process or have questions, refer to the documentation or seek support from the relevant community.
:::
Use the hash of the CType to identify and anchor it to the KILT blockchain. Once this is done, it's no longer possible to change or delete the CType schema.

### Properties
### Constructing the `hash` for the `$id`

When creating a new CType schema, the following properties are required:
KILT uses the `blake2b256` hashing algorithm to compute the hash of CTypes, after sorting the CType object by a canonicalization algorithm to ensure that semantically equivalent CTypes with different orders of their properties result in the same final hash.

- One of the following fields: `type` or `$ref`
- A type of `string`, `integer`, `number` or `boolean` to define the attribute
- Nested JSON schemas can be referenced by a `uri` using `$ref` (giving the advantage of being able to reference previously-created CTypes)
- The format field is optionally:
- *Date* format e.g., 2012-04-23T18:25:43.511Z
- *Time* format e.g., T18:25:43.511Z
- *URI* format e.g., "https://www.example.com"
KILT computes the hash from the following fields of the CType schema:

<CodeBlock className="language-json" title="CType schema example">
{ctypeSchema}
</CodeBlock>
- `$schema`
- `properties`
- `key`
- `$ref`
- `type`
- `format`
- `title`
- `type`

The CType schema is afterwards hashed to generate its own identifier, and it becomes the full CType object:
A typical CType ID looks like this: `kilt:ctype:0xda3861a45e0197f3ca145c2c209f9126e5053fas503e459af4255cf8011d5101`.

<CodeBlock className="language-json" title="Full CType example">
{ctype}
</CodeBlock>
## Storing and querying CTypes

## CType Metadata
As of the [KILT runtime 1.9.0][kilt-runtime-1.9.0], you can query CTypes directly from any KILT archive node.

CType Metadata can be linked to a given CType to provide title and descriptions in different languages for the whole CType and its properties.
After creating a CType, its full content is only included in the blockchain block history and its hash and creation block number anchored to the blockchain state.

<!-- TODO: Add example of CType metadata -->
To query the full content of a CType, use its hash to look up the creation block number, and use that to query any KILT archive node for the extrinsic information about the CType.

## Hashing
The returned information includes the whole CType, which is now available for the user to, for example, verify credentials against it.

The hash of the CType is used to identify and anchor it to the KILT blockchain.
:::info CType creation cost

### Constructing the `hash` for the `$id`
Currently, it costs 0.001 KILT to create a CType on the KILT blockchain.

:::

For a detailed developer-oriented guide to KILT CTypes, read the [CType Cookbook section](../../develop/01_sdk/02_cookbook/04_claiming/01_ctype_creation.md).

KILT uses the hashing algorithm `blake2b256` to compute the hash of CTypes.
Before hashing, the CType object is sorted by a canonicalization algorithm to ensure that semantically equivalent CTypes with different order of their properties result in the same final hash.
[kilt-runtime-1.9.0]: https://github.com/KILTprotocol/kilt-node/releases/tag/1.9.0

The hash is computed from the following fields of the CType schema:
:::danger Deprecation Warning: CType metaschema draft-01

- `$schema`
- `properties`
- `key`
- `$ref`
- `type`
- `format`
- `title`
- `type`
CTypes based on the [Draft 01](http://kilt-protocol.org/draft-01/ctype) metaschema are subject to a vulnerability that could fool an **Attester** by introducing data they never checked.

A typical CType ID would look like this: `kilt:ctype:0xda3861a45e0197f3ca145c2c209f9126e5053fas503e459af4255cf8011d5101`.

## Storing and Querying CTypes
Due to this vulnerability, this version of the metaschema is deprecated and its use is discouraged when creating new CTypes.

As of the [KILT runtime 1.9.0][kilt-runtime-1.9.0], CTypes can be queried directly from any KILT archive node!
For optimal security and functionality, use SDK version `0.33.0` or later for creating CTypes.
This newer version defaults to using the updated metaschema available at [`ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/`](ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq).

After creating a CType, its full content is included only in the blockchain block history, while its hash and creation block number is anchored to the blockchain state.
This also means you should update existing CTypes.
While existing CTypes continue to work in the short term, we advise to upgrade to the latest metaschema at your earliest convenience.

Querying the full content of a CType then becomes trivial, since the CType hash can be used to look up its creation block number, and then that information can be used to ask any KILT archive node for the extrinsic information about the CType creation.
The information includes the whole CType, which is now available for the user to, e.g., verify credentials against it.
Old Property Value: `"$schema": "http://kilt-protocol.org/draft-01/ctype"`
New Property Value: `"$schema": "ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/"`

For adding a CType, a constant fee of 0.001 KILT is required.
## Migration instructions

For a detailed developer-oriented guide to KILT CTypes, see our [CType Cookbook section](../../develop/01_sdk/02_cookbook/04_claiming/01_ctype_creation.md).
Attesters should transition to issuing credentials using upgraded versions of CTypes currently in use.

[kilt-runtime-1.9.0]: https://github.com/KILTprotocol/kilt-node/releases/tag/1.9.0
Using sdk version `0.33.0` or later, you can produce a copy of an existing CType `oldCType` as follows:

```js
const newCType = CType.fromProperties(oldCType.title, oldCType.properties, 'V1')
```

The new CType has the same title and properties as the existing one, but be based on the new metaschema, resulting in a different hash and id.
After [registering the new CType on the KILT blockchain](../../develop/01_sdk/02_cookbook/04_claiming/01_ctype_creation.md), you can use the new CType as a drop-in replacement in issuing credentials.

Verifiers depending on these CTypes should accept both the old and new CType during a transition period.
Test thoroughly to ensure the correct behavior and functionality of the new CTypes in your application.
:::
32 changes: 20 additions & 12 deletions docs/concepts/05_credentials/03_claiming.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,29 +4,37 @@ title: Claims
---

import CodeBlock from '@theme/CodeBlock';

<!-- Taken from https://github.com/webpack-contrib/raw-loader/issues/91#issuecomment-648830498 -->
import Claim from '@site/scripts/out/claim.json.raw!=!raw-loader!@site/scripts/out/claim.json';

As KILT is an open system, entities can make claims about any other entities, including themselves.
A claim (as in the real world) can only be trusted if another trusted entity (we call them Attesters) *certifies* this claim.
Therefore, Verifiers might trust different Attesters for distinct scenarios.
An entity can only trust a claim (as in the real world) if another trusted entity (called **Attesters**) *certifies* this claim.
Therefore, **Verifiers** might trust different **Attesters** for distinct scenarios.

:::info Role recap
- **Claimers** want information about themselves certified.
They also issue credentials, but these remain invalid without an attestation.
- **Attester** check the truthfulness of a claim and certify them.
- **Verifiers** accept the credentials, only verifying that your certification are legitimate.
:::

## Creating a Claim
## Creating a claim

In KILT, claims are based on claim types (CTypes).
Hence, given a CType, a Claimer only needs to create a claim with the properties specified in the CType schema.
The resulting claim contains a reference to the CType by its hash and includes the identity of the claim subject (identified by the `owner` property).
Given a CType, a Claimer only needs to create a claim with the properties specified in the CType schema.
The resulting claim contains a reference to the CType by its hash and includes the identity of the claim subject (identified by the `owner` property, which has the value of a KILT DID).

<CodeBlock className="language-json" title="Claim example">
{Claim}
</CodeBlock>

## Requesting a Credential
## Requesting a credential

Once the Claimer has wrapped their claims into a `Credential`, they send it to the chosen Attester using any messaging system for **certification**, i.e. attested.

The to-be-attested `Credential` contains the original claim, data needed for future selective disclosure of the claim contents (read more in the [Verification documentation](./05_verification.md)), and the legitimation and / or delegation ID of the Attester and the credential root hash, used to identify both the credential and its on-chain attestation.

Once the Claimer has created a claim, they need to get it *certified*, i.e., attested, by an Attester.
The resulting `Credential` must then be sent to the chosen Attester using any messaging system.
:::info

The to-be-attested `Credential` contains the original claim, data needed for future selective disclosure (more on that in the [Verification section](./05_verification.md)) of the claim contents, the legitimation and / or delegation ID of the Attester and the credential root hash, which is used to identify both the credential and its on-chain attestation.
For a detailed developer-oriented guide to KILT claims, read the [Claim Cookbook section](../../develop/01_sdk/02_cookbook/04_claiming/02_attestation_request.md).

For a detailed developer-oriented guide to KILT claims, see our [Claim Cookbook section](../../develop/01_sdk/02_cookbook/04_claiming/02_attestation_request.md).
:::
Loading

0 comments on commit cdf7e80

Please sign in to comment.