Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft: Verifiable Credentials docs #2894

Merged
merged 25 commits into from
Jun 5, 2024
Merged
Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ import useBaseUrl from "@docusaurus/useBaseUrl";

## Overview

Verifiable credentials (VCs) on ICP rely on Internet Identity (II), which provides different and unlinkable identities for each dapp. A dapp utilizing verifiable credentials can’t ask for a user's credentials from the [issuer of the verifiable credential directly. When a relying party wants to obtain a credential from an issuer, it must request it through an identity provider such as Internet Identity.
Verifiable credentials (VCs) on ICP rely on Internet Identity (II), which provides different and unlinkable identities for each dapp. A dapp utilizing verifiable credentials can’t ask for a user's credentials from the [issuer](/docs/current/developer-docs/identity/verifiable-credentials/overview#terminology) of the verifiable credential directly. When a [relying party](/docs/current/developer-docs/identity/verifiable-credentials/overview#terminology) wants to obtain a credential from an issuer, it must request it through an [identity provider](/docs/current/developer-docs/identity/verifiable-credentials/overview#terminology) such as Internet Identity.
jessiemongeon1 marked this conversation as resolved.
Show resolved Hide resolved

Internet Identity acts as a communication link between the relying party and issuer API, connecting with the issuer API and asking for the credentials for the user. After receiving the credentials, they are forwarded to the relying party.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -28,13 +28,13 @@ Verifiable credentials are designed to be tamper-evident, privacy-preserving, an

When learning about and using VCs, there are two primary terms to familiarize yourself with:

- **Issuer**: A service or app that issues verifiable credentials to a user.
- **User**: Users earn credentials, a piece of data that certifies information about the user, from an issuer.

- **Relying party**: A service or app that requests users provide verifiable credentials.
- **Issuer**: An issuer is an entity (a dapp, organization, government, etc.) that verifies information about the user.

- **User**: Earns a credential, a piece of data that certifies information about them.
- **Relying party**: A different dapp (organization, government, etc.) which requests certified credentials for that user from the issuer.

- **Identity provider**: In this case, Internet Identity, creates a temporary identifier for the user when the issuer passes the credential to the relying party, so that the relying party and the issuer never learn the user's identifiers on the other entity's service.
- **Identity provider**: Entity that (in this case, Internet Identity) creates a temporary identifier for the user when the issuer passes the credential to the relying party, so that the relying party and the issuer never learn the user's identifiers on the other entity's service.

## How to use verifiable credentials

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -172,7 +172,14 @@ In this response, `verifiablePresentation` is a JWT based verifiable presentatio

The specification ensures unlinkability between the relying party and the issuer. That's why two credentials are needed. The first credential proves the link between the relying party's principal and `id_alias` created in the identity provider. The second credential is the actual credential to the `id_alias`.

![Verifiable presentations](/static/img/docs/vcs-4.png)

<div class="text--center">
<img
src={useBaseUrl("/img/docs/vcs-4.png")}
alt="Relying Party workflow"
width="800"
/>
</div>

Note how the issuer's principal never appears in the credentials. Instead, the relying party and the issuer know about the `id_alias`. Therefore, this `id_alias` needs the credential to verify the link between the user's principal and the `id_alias`.

Expand Down Expand Up @@ -299,7 +306,7 @@ When the actual credential decoded, the following info is returned:

To verify the two JWT signatures, verify the signature of the `id_alias` signed by the identity provider, and the signature of the actual credential signed by the issuer. Both are found when you decode the received JWT.

These signatures are [canister signatures](https://internetcomputer.org/docs/current/concepts/glossary/#canister-signature) and there is an example on [how to verify those in the Internet Identity repository](​​https://github.com/dfinity/internet-identity/blob/2ae06956f9cabc048b8536b29b9f861092958515/src/vc_util/src/lib.rs#L193).
These signatures are [canister signatures](https://internetcomputer.org/docs/current/concepts/glossary/#canister-signature) and there is an example on [how to verify those in the Internet Identity repository](https://github.com/dfinity/internet-identity/blob/2ae06956f9cabc048b8536b29b9f861092958515/src/vc_util/src/lib.rs#L193).

### Semantic verification

Expand Down
8 changes: 4 additions & 4 deletions sidebars.js
Original file line number Diff line number Diff line change
Expand Up @@ -560,10 +560,10 @@ const sidebars = {
type: "category",
label: "Verifiable credentials",
items: [
"developer-docs/web-apps/verifiable-credentials/overview",
"developer-docs/web-apps/verifiable-credentials/how-it-works",
"developer-docs/web-apps/verifiable-credentials/issuer",
"developer-docs/web-apps/verifiable-credentials/relying-party",
"developer-docs/identity/verifiable-credentials/overview",
"developer-docs/identity/verifiable-credentials/how-it-works",
"developer-docs/identity/verifiable-credentials/issuer",
"developer-docs/identity/verifiable-credentials/relying-party",
],
},
],
Expand Down
Loading