Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
<todo>
By completing this subsection, you will:
Identify all actors and map out their roles and relationships.
Define the rules and policies of your use case.
Define the legal identities involved.
Understand how to set up DIDs for your entities
Define accreditations issued by the Trusted Accreditation Organisation.
<todo>
Accreditation Policies are included in each "Verifiable Accreditation" or "Verifiable Credential" within the termsOfUse
section of the credential. The Accreditation Policies reference the other members of the Trust Chain, so that a Relying Party can traverse the Trust Chain.
<todo>
<todo>
<todo>
Verifiable Accreditations are credentials that are issued from one organisation to another organisation to "accredit" that organisation to perform a particular action. These types of credentials are stored directly on-ledger as DID-Linked Resources, meaning that they are persistent, sequentially versioned and highly available.
There are two types of Verifiable Accreditation:
For a trusted ecosystem, these attestations are required to trace the legitimacy of a credential issuer to a root-of-trust.
In order to ensure consistency and interoperability within a trusted ecosystem, Trusted Accreditation Organisations (TAOs) should define schemas for the Verifiable Accreditations for their particular ecosystem. They may also reuse existing schemas that have been created for equivalent ecosystems.
Notably, Verifiable Accreditations are credentials that are issued to organisational DIDs on cheqd. In each Verifiable Accreditation, there is also a reservedAttributeId
that corresponds to the resourceId
of the Accreditation as a DID-Linked Resource.
Storing Verifiable Accreditations as DID-Linked Resources enables each accreditation to be individually resolvable using a DID URL. It also enables Accreditations to be "chained" to a DID, allowing the traversal of the Accreditation to the root of trust.
The diagram below shows how DID-Linked Resources can be applied to the trust hierarchy to enable DID resolvable Verifiable Accreditations:
cheqd supports two predominant Root of Trust Models.
For existing trust frameworks such as eIDAS, organisations need to establish a root of trust using X.509 certificates in traditional "Trusted List" infrastructure. These certificates establish that an organisation is authorised to provide a service under a particular jurisdiction.
Article 22 of the eIDAS Regulation obliges Member States to establish, maintain and publish trusted lists. These lists should include information related to the qualified trust service providers for which they are responsible, and information related to the qualified trust services provided by them. The lists are to be published in a secured manner, electronically signed or sealed in a format suitable for automated processing.
Standard information in an X509 certificate includes:
Version — The version of X.509 that applies to the certificate.
Serial number — Serial number assigned by certificate authority to distinguish one certificate from other certificates.
Algorithm information — The hashing algorithm used by the CA to sign the certificate (SHA-2 in almost all cases).
Issuer distinguished name — The name of the entity issuing the certificate (usually a certificate authority)
Validity period of the certificate — The period during which certificate is valid to use.
Subject distinguished name — The name of the identity the certificate is issued to (individual, organization, domain name, etc.)
Subject public key information — The public key of the certificate
As such, one method of establishing a root of trust is associating a DID on cheqd with an existing X.509 certificate. This concept has been written on recently, with there being various approaches to achieving this.
As a first iteration of trust infrastructure on cheqd, we suggest that:
did:cheqd
DIDs can be derived from the same public/private key pair as existing X.509 certificates
did:cheqd
DIDs can reference X.509 certificates using a serviceEndpoint
X.509 certificates can reference did:cheqd
DIDs using the "Subject Alternative Name" field within the X.509 certificate.
This will enable Root TAOs to create a reciprocal root of trust across European Trusted Lists for eIDAS compliance, and equally on cheqd.
For ecosystems that do not require a "traditional" root of trust, we can leverage the cheqd network itself to create reputable, "weighted" roots of trust.
For this model, we suggest that "Root TAOs" set up a cheqd Validator on the cheqd Network and include their DID in the "description" field of their Validator. This will tie the reputation and weight of the Validator with the DID itself.
Then, when traversing the trust chain and resolving to the Root of Trust, the validating application can apply logic to validate the "reputation" of the Root TAO, based on the voting power of the Validator within the active set.
Learn how to set up your account on cheqd Studio.
The user is required to Log In to our cheqd Studio portal, select a billing plan and then access their API key to authenticate with our APIs. The API key guards the API from unauthorized access and is required for both testing production environments.
Head to our cheqd Studio and click Get Started.
New users can cancel their cheqd Studio plan at any time within the free trial period and will not be charged.
Get started with our tutorials for cheqd Studio functionality.
Create did:cheqd
DID for Root TAO
Establish root of trust, by:
Associating Root TAO DID with X.509 certificate;
Publishing Root TAO DID as a Well-Known DID;
Associating Root TAO DID with cheqd Validator.
Create did:cheqd
DIDs for TAOs or TIs within the ecosystem
Create body of Verifiable Accreditation, specifying:
The did:cheqd
DID of the subject organisation that the Accreditation is being issued to
A UUID as a reservedAttributeId which aligns with the resourceId of the DID-Linked Resource
Encode Verifiable Accreditation as a hexidecimal and as a base64 encoded value
Compile payload file for writing Verifiable Accreditation as a DID-Linked Resource
Publish transaction as a DID-Linked Resource, using the same UUID for the resourceId
as the value specified in the reservedAttributeId
API keys are unique data strings used to authenticate a user and enable access to privileged operations on cheqd Studio APIs. All cheqd Studio APIs use API keys as the mechanism to authenticate client requests. Your API key should be kept confidential and secure at all times.
Authentication is required for all API requests; without it, the requests will fail.
All API requests must be made over HTTPS.
Because our API keys allow access to cheqd Studio APIs, you must keep them secure at all times.
Ensure your API key is always stored securely as soon as it is initially generated.
Make sure to copy your API key into a secure place, such as a Password Manager.
Never share it or record it in a publicly accessible medium (client-side code, public repositories, etc.).
Caution: If you lose secure control of your API keys, your entity may not be able to access your created DIDs, DID-Linked Resources or Credential Payments.
Follow the tutorial here to get started with your cheqd Studio account.
Navigate to the "Developers" tab on cheqd Studio and select "Create an API Key". You are able to choose the expiry date of the API key, and it will automatically be set to expire 1 year from the current date.
Navigate to the "APIs" tab and copy/paste your API key into the API key box towards the top of your page. This will enable you to authenticate with the cheqd Studio APIs, allowing users to use cheqd Studio APIs within their existing Billing Plan and usage limits.
Get started with our tutorials for cheqd Studio functionality.
Understanding cheqd's API product offering, cheqd Studio
cheqd Studio is a set of guides, tutorials and APIs to help users establish an end-to-end trusted ecosystem for digital credentials.
Using REST APIs, customers can build cheqd's trust infrastructure into existing applications. All of cheqd’s existing open-source libraries remain available, and cheqd Studio does not necessitate developers to switch their SSI stack in their entirety, but allows them to build into their existing tooling, for example alongside APIs such as the Universal Resolver.
With cheqd Studio, there are multiple ways it can be deployed and hosted to support clients with different requirements.
This mode is the most simple for users, allowing cheqd to custody both Cosmos AND Identity keys in Veramo KMS. This means that manages both ledger-writes and signing identity transactions on behalf of the customer.
To ensure this is highly secure, we have deployed an instance of a Veramo Key Management Store (KMS) which uses a Postgress DB (TypeOrm) to store Cosmos AND identity keys in one encrypted table, so it cannot be read in plaintext. This design allows us to segment different customers' keys securely and efficiently.
Within Custodian mode, we also enable clients to toggle
Client-managed mode gives the cheqd Studio user the ability to utilise their own identity keys for signing identity transactions, while still allowing cheqd Studio to manage the CHEQ account keys for writing to the cheqd network. This mode is intended to be used for more production environments where the user signs each identity transaction independently, affording a greater level of security and control to the client.
Full client-managed mode is still in development and we will update this documentation as and when it becomes available
Below are a list of alternatives for integrating with cheqd. Each offers a different set of protocols and underlying technical capabilities.
Users may exhaust their usage limits in their cheqd Studio billing plan, but may want to continue using the Studio before their usage limits refresh. Therefore, users can manually top up their account with CHEQ tokens to use any APIs that involve a ledger-write, e.g:
Creating, Updating or Deactivating DIDs
Creating unencrypted or encrypted Status Lists
Creating Trust Registries
Creating other DID-Linked Resources
The following API can be used to fetch the new account information:
customer_id
is used as an identifier for the particular customer using cheqd Studio. It is generated as a sub-field of the JWT token used in the authorization header.
cheqd_account
is used to pay for identity transactions on either testnet
or mainnet
. A cheqd account is automatically generated when a new customer_id
is generated.
Users will need to add our token, CHEQ, to their cheqd_account
on mainnet
in order to be able to use the ledger-based identity functionality on cheqd Studio, such as creating DIDs and DID-Linked Resources.
If you need to add CHEQ tokens to your cheqd Studio cheqd_account
, there are a few steps you need to follow:
Once you have successfully created an account and have topped up your CHEQ tokens, you are ready to get started!
Get started with our tutorials for cheqd Studio functionality.
Developer guide for running the cheqd Studio.
This standalone service uses an in-memory database with no persistence, and therefore is recommended only if you're managing key/secret storage separately.
Construct the postgres URL and configure the env variables mentioned above.
POSTGRES_USER
: Username for Postgres database
POSTGRES_PASSWORD
: Password for Postgres database
POSTGRES_MULTIPLE_DATABASES
: Database names for multiple databases in the same cluster, e.g.: "app,logto"
. This sets up multiple databases in the same cluster, which can be used independently for External Veramo KMS or LogTo service.
Then, make the Postgres initialisation scripts executable:
Then, run the LogTo service to configure the LogTo application API resources, applications, sign-in experiences, roles etc using Docker Compose:
Then, start the service using Docker Compose:
When upgrading either the external Veramo KMS or LogTo, you might need to run migrations for the underlying databases.
For example, to run cheqd Studio app migrations on an existing Postgres database (for external Veramo KMS):
Or to run LogTo migrations on an existing Postgres database:
Type | Description |
---|---|
You will be able to get started for free by selecting either plan, which includes a Free Trial. cheqd Studio billing uses as a payments processor and users will need to input their card information to initiate a billing plan.
cheqd Studio uses a to handle user authentication and login. This allows users to create new accounts as well as sign in using their email, Google single sign-on, or Discord login.
Field | Description | Required |
---|
cheqd Studio directly leverages our , making a wide array of features available from launch, including:
We use similar techniques to Password Managers such as and to ensure that even if the database were to be compromised, the keys would remain encrypted and unusable.
We use a self-hosted version of , which supports OpenID Connect. Theoretically, these values could also be replaced with or any other OpenID Connect identity provider.
Default role update using : LogTo supports webhooks to fire of requests to an API when it detects certain actions/changes. If you want to automatically assign a role to users, a webhook is recommended to be setup for firing off whenever there's a new account created, or a new sign-in.
Under the hood, cheqd Studio leverages our for its identity functionality. Check out our to understand how cheqd Studio fits together with our other Open Source packages.
First you need to which is able to hold CHEQ tokens. We recommend using which natively supports all CHEQ transactions in a browser plugin or on mobile. Alternatively, follow the .
You will then need to .
This is super simple. You can add free CHEQ tokens to your cheqd_account by inputting your cheqd account address. Access the .
If you want to run the application without any external databases or dependent services, we provide to spin up a standalone service.
The in the same folder contains all the environment variables necessary to configure the service. (See section Configuration above.)
Spinning up a Docker container from the is as simple as the command below:
Configure the environment variables in the :
Configure the environment variables in the with the settings described in section above.
Configuring LogTo is outside the scope of this guide, and we recommend reading to familiarise yourself.
Configure the environment variables in the with the settings described in section above. Depending on whether you are using external Veramo KMS only, LogTo only, or both you will need to have previously provisioned these services as there are environment variables in this file that originate from Postgres/LogTo.
You can run just the migration scripts using defined in the Compose file.
To build your own image using Docker, use the provided.
Verifiable Accreditation to Accredit
This Credential verifies that an organisation has the permissions needed to accredit other organisations for issuing a particular type of Verifiable Accredittion.
Verifiable Accreditation to Attest
This Credential verifies that an organisation has the permissions needed to issue Verifiable Credentials, defined by a particular schema.
Combination of x509 and DID/VC for inheritance properties of trust in digital identities
Paper written by Carsten Stocker, Paul Bastian and Steffen Schwalm on the different methods for associating DIDs with X.509 certificates
did | DID of the DID Controller publishing the DID-Linked Resource | Yes |
hash | Hash of the Verifiable Accreditation as a Base64 encoded value | Yes |
body | Body of the Verifiable Accreditation as a hexidecimal string | Yes |
type | Type of Resource being created, defaults to | Yes |
issuerType | Type of Issuer that is issuing this Verifiable Accreditation, can be: "RootTAO", "TAO" or "SubTAO" | Yes |
tao | DID of the TAO that accredited the Issuer | Yes |
rootTao | DID of the root of trust that accredited the TAO and the issuer | Yes |
revoked | Boolean value indicating whether the Verifiable Accreditation is revoked or not | Yes |
Encrypted | Boolean value indicating whether the Verifiable Accreditation is encrypted or not | No |
Walt.id Community Stack is an SDK that supports the standards for identity, with full cheqd support.
This endpoint returns the custodian-mode client details for authenticated users.
The request was successful.