diff --git a/docs/issuer/display-method.md b/docs/issuer/display-method.md index 78744221..48bc7222 100644 --- a/docs/issuer/display-method.md +++ b/docs/issuer/display-method.md @@ -1,84 +1,134 @@ --- id: display-method -title: Display method -sidebar_label: Display method -description: Display method +title: "Creating Custom Display Methods: Enhance Credential Presentation and Branding" +sidebar_label: "Custom Display Methods" +description: "Learn how to create and manage custom display methods in the Privado Issuer Node to enhance the visual presentation of verifiable credentials, maintain consistent branding, and build user trust." keywords: - docs - - polygon id + - privado id - issuer node - - claim - verifiable credentials - credential customization + - display methods + - digital credentials + - branding + - ipfs + - layout + - metadata + - credential design + - digital identity --- -import useBaseUrl from '@docusaurus/useBaseUrl'; - -## Description - -To improve credential usage, a client needs to be able to customize the presentation of credentials in user wallets. A standard must be established that will guide the wallet in displaying credential cards. This will improve the user experience and allow issuers to present their own special presentation for credentials. - -This tutorial will show you how to create a custom credential representation in a mobile wallet. - -## Credential representation configuration - -Restrictions: - -1. `backgroundImageUrl` and `logo` only support .png and .jpeg formats. -2. Maximum length for `title` is 60 characters. -3. Maximum length for `description` is 120 characters. - -To configure the credential representation on the PolygonID wallet, follow the steps below: - -1. Upload a background and logo for the credential card to IPFS or an HTTP(s) host. -1. Create a file named metadata.json with the following content: - ```json - { - "title": "KYC Country of Residence", - "description": "Know Your Customer Verification", - "issuerName": "PolygonID Issuer", - "titleTextColor": "#f2743a", - "descriptionTextColor": "#f2743a", - "issuerTextColor": "#f2743a", - "backgroundImageUrl": "ipfs://QmecKDMotkM8a6vxw35CB7iHfToBJnzJrPcmA3gHit9jt9", - "logo": { - "uri": "ipfs://QmWkSgmHbKRfhndWqHwVgfVpZSrWNiWZMTHb6k5KxY8ySc", - "alt": "Logo PolygonID Issuer" - } - } - ``` -
- -
-1. Upload the metadata.json file to IPFS or an HTTPS(s) host. -1. Use the API to issue a verifiable credential with information about the display method. You can do this using the issuer-node API: - ```bash - POST https:///v1//claims - ``` - Body: - ```json - { - "credentialSchema": "https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json/KYCAgeCredential-v3.json", - "type": "KYCAgeCredential", - "credentialSubject": { - "id": "", - "birthday": 19960424, - "documentType": 2 - }, - "expiration": 1735689600, - "displayMethod": { - "id": "", - "type": "Iden3BasicDisplayMethodV1" - } - } - ``` -1. Fetch the credential using the PolygonID mobile wallet: -
- -
- -Please note that you should replace placeholders like ``, ``, ``, `` with actual values as needed for your configuration. + +# Custom Display Methods + +**What are Custom Display Methods?** +They define how a credential is presented to its holder. For instance, a university may issue digital diplomas in a specific layout (with the university’s logo, official colors, etc.) that is visually appealing. A Custom Display Method ensures consistency and brand adherence across all issued credentials. + +--- + +## Example Use Case + +**Scenario**: A company wants to issue secure digital certificates as Verifiable Credentials for its employees' achievements or training. Instead of generic text-based credentials, they want a branded, visually appealing credential that includes: + +- Company logo +- Employee photo +- Distinct color scheme +- Signature of the HR manager + +By creating a Custom Display Method and referencing it during credential issuance, they ensure each certificate is displayed exactly as intended, maintaining brand identity and professionalism. + +--- + +## Building a Display Method + +### Step 1: Fill Out Metadata +1. Open the [Display Method Builder](https://display-method-dev.privado.id/). +2. Enter all required metadata fields (name, description, type, etc.) as guided by the [Display Method Documentation](https://docs.privado.id/docs/issuer/display-method/). +3. Make sure to follow any restrictions or formatting requirements. + +![Display Method Builder](../../static/img/display_methods/1.png) + +### Step 2: Publish to IPFS +1. After filling out the metadata, click on “**Publish to IPFS**”. +2. The Builder will bundle and publish your Display Method JSON to IPFS. + +### Step 3: Obtain the IPFS Link +1. Wait for the publishing response. +2. Copy the IPFS link provided (e.g., `ipfs://...` or `https://ipfs.io/ipfs/...`). +3. This link uniquely references your Display Method and will be used in the Issuer Node. + +![Obtain the IPFS Link](../../static/img/display_methods/2.png) +--- + +## Usage of a Display Method in Issuer Node + +### Adding the Display Method to the Issuer Node +1. In your Issuer Node, navigate to the **Display Method** section (go to `/display-methods/create` or click **Create a Display Method**). +2. Fill out the form: + - Provide a **unique name** for the Display Method (e.g., `KYC Age Display Method` or `Employee Achievement Method`). + + - Paste the **IPFS URL** from the previous step into the `URL` field. + + ![Adding the Display Method to the Issuer Node](../../static/img/display_methods/3.png) + +3. Save your changes. The Display Method is now registered with your Issuer Node. + +### Using a Display Method When Issuing Credentials +1. In the **Issue Credential** flow, enable the **Display Method** checkbox. +2. Select your newly created method from the dropdown list. +3. Once you issue the credential, it will reference your custom Display Method. + +![Using a Display Method When Issuing Credentials](../../static/img/display_methods/4.png) + +### Setting a Default Display Method for a Schema +1. On the **Schema Details** page in the Issuer Node, find the **Display Method** selector. +2. Choose a default method for that schema. +3. Any credential issued under this schema will automatically use the default Display Method (unless manually overridden). + +![Setting a Default Display Method for a Schema](../../static/img/display_methods/5.png) + +--- + +## Editing or Deleting a Display Method +To edit or delete a Display Method, go to: +- The detail page of the Display Method, or +- The list of all Display Methods. + +Locate the **edit** or **delete** icons to make changes accordingly. + +![Editing or Deleting a Display Method](../../static/img/display_methods/6.png) + +--- + +## API References + +Below is a summary of the relevant API endpoints to manage Display Methods and schemas: + +### New APIs Added in the Issuer Node +- [**Create Custom Display Method**](https://issuer-node-core-api-testing.privado.id/#post-/v2/identities/-identifier-/display-method) +- [**Delete Display Method**](https://issuer-node-core-api-testing.privado.id/#delete-/v2/identities/-identifier-/display-method/-id-) +- [**Get All Display Methods**](https://issuer-node-core-api-testing.privado.id/#get-/v2/identities/-identifier-/display-method) +- [**Get Display Method**](https://issuer-node-core-api-testing.privado.id/#get-/v2/identities/-identifier-/display-method/-id-) +- [**Update Display Method**](https://issuer-node-core-api-testing.privado.id/#patch-/v2/identities/-identifier-/display-method/-id-) +- [**Update Schema**](https://issuer-node-core-api-testing.privado.id/#patch-/v2/identities/-identifier-/schemas/-id-) + +### Updated APIs in the Issuer Node +- [**Get Schemas**](https://issuer-node-core-api-testing.privado.id/#get-/v2/identities/-identifier-/schemas) + - Now returns a `displayMethodID` in the schema response. +- [**Get Schema**](https://issuer-node-core-api-testing.privado.id/#get-/v2/identities/-identifier-/schemas/-id-) + - Now returns a `displayMethodID` in the schema response. + +--- ## Links -1. [Display method](https://iden3-communication.io/w3c/display-method/overview) +1. [Display Method Info](https://iden3-communication.io/w3c/display-method/overview) +2. [Display Method Builder](https://display-method-dev.privado.id/) + + + +## Conclusion + +With these steps, you can create, manage, and apply custom Display Methods to credentials in the Privado Issuer Node. By leveraging custom layouts, organizations, and institutions can ensure consistent branding and meaningful designs for their verifiable credentials. This not only adds professionalism but also improves the user’s trust and recognition of your issued credentials. + diff --git a/docs/issuer/issuer-configuration.md b/docs/issuer/issuer-configuration.md index 799873e0..e78a3462 100644 --- a/docs/issuer/issuer-configuration.md +++ b/docs/issuer/issuer-configuration.md @@ -95,7 +95,88 @@ then: * OnChain - `Iden3commRevocationStatusV1.0` and `Iden3OnchainSparseMerkleTreeProof2023` credential status type * All - All the statuses. +## KMS Configuration +Credentials issued by the issuer node are signed using a private key tied to the identity responsible for issuing them. Each identity can have one or more BabyJubJub (BJJ) type private keys. Additionally, the issuer node supports creating Ethereum-controlled identities, where both a BJJ key and an Ethereum (ETH) key are associated with the identity. + +#### Identity Types and State Transitions +- BJJ-Based Identity: + - A BJJ type key is generated for the identity to sign credentials and generate zk-proofs for state transitions. + - A shared ETH type key (imported during setup) is used to publish zk-proofs on-chain. + +- ETH-Based Identity: + - Both a BJJ type key and an ETH type key are generated for the identity. + - The BJJ type key is used to signs the credentials. + - Only the ETH type key is involved in state transition. + +The issuer node integrates with various key management solutions to create, sign, and store these keys securely. Depending on your setup, here’s an overview of the available options: + +| **KMS Service** | **Supported Key Types** | **Purpose** | **Recommended For** | +|------------------------|-------------------------|------------------------------------------|--------------------------| +| HashiCorp Vault | BJJ, ETH | Secure key creation and storage | Production | +| AWS Secrets Manager | BJJ, ETH | Secure key storage | Production | +| AWS KMS | ETH (only) | Secure ETH key creation and signing | Production (ETH only) | +| Localstorage | BJJ, ETH | Local storage for testing | Testing Only | + + +### HashiCorp Vault +The issuer node integrates with HashiCorp Vault, delegating the creation, signing, and secure storage of both BJJ and ETH keys via a Vault plugin. To configure the issuer node to use Vault as a Key Management Service (KMS), update the .env-issuer file as follows: + +```bash +ISSUER_KMS_BJJ_PROVIDER=vault +ISSUER_KMS_ETH_PROVIDER=vault + +ISSUER_VAULT_USERPASS_AUTH_ENABLED=true +ISSUER_VAULT_USERPASS_AUTH_PASSWORD= +ISSUER_KEY_STORE_ADDRESS= +``` +For detailed steps to configure the Vault plugin, refer to the Docker-based setup in the following repository: [HashiCorp Vault Setup](https://github.com/0xPolygonID/issuer-node/blob/main/infrastructure/local/.vault/scripts/init.sh). + +### AWS Secrets Manager +In this configuration, the issuer node handles the creation of private keys, which are securely stored in AWS Secrets Manager. + +Update the .env-issuer file as follows: + +```bash +ISSUER_KMS_BJJ_PROVIDER=aws-sm +ISSUER_KMS_ETH_PROVIDER=aws-sm + +ISSUER_KMS_AWS_ACCESS_KEY= +ISSUER_KMS_AWS_SECRET_KEY= +ISSUER_KMS_AWS_REGION= +``` +:::note + Ensure the credentials you use have the necessary permissions to access AWS Secrets Manager. +::: +Learn more about AWS Secrets Manager here: [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/.) + +### AWS KMS Service (Only for ETH Keys) +Alternatively, AWS KMS can be used exclusively for managing and signing ETH keys, delegating their creation and secure storage to the AWS KMS service. + +To configure this setup, update the .env-issuer file as follows: + +```bash +ISSUER_KMS_BJJ_PROVIDER= +ISSUER_KMS_ETH_PROVIDER=aws-kms + +ISSUER_KMS_AWS_ACCESS_KEY= +ISSUER_KMS_AWS_SECRET_KEY= +ISSUER_KMS_AWS_REGION= +``` +:::note +Ensure your credentials have the necessary permissions for AWS KMS. +::: +Learn more about AWS KMS service: [AWS KMS](https://aws.amazon.com/kms/?nc1=h_ls) + +### Localstorage (For Testing Only) +For testing purposes, both BJJ and ETH keys can be stored locally as flat files. This option is not recommended for production environments due to its lack of security. + +To enable this setup, update the .env-issuer file as follows: + +```bash +ISSUER_KMS_BJJ_PROVIDER=localstorage +ISSUER_KMS_ETH_PROVIDER=localstorage +``` diff --git a/docs/issuer/key-rotation.md b/docs/issuer/key-rotation.md new file mode 100644 index 00000000..1f5c7718 --- /dev/null +++ b/docs/issuer/key-rotation.md @@ -0,0 +1,114 @@ +--- +id: key-rotation +title: Key Rotation +sidebar_label: Key Rotation +description: Learn how you can rotate keys in the issuer node +keywords: + - docs + - privado id + - issuer node + - key rotation + - key + - auth core claim + +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +When an identity is created on the issuer node, a credential (also referred to as [authCoreClaim](https://docs.iden3.io/getting-started/claim/auth-claim/)) is generated to sign issued credentials. This authCoreClaim is tied to a babyjubjub-type private key, which is securely stored based on the issuer node's configuration. Supported storage options include local storage, vault, or AWS Secret Manager – [see Key Management Configuration](./issuer-configuration.md/#kms-configuration). + +## Features + +### Security +- The issuer node supports key rotation, allowing you to replace an old key (authCoreClaim) with a new one without disrupting operations. +- Key rotation minimizes the risk of compromised keys being misused, ensuring that the system remains secure over time. + +### Credential Invalidation +- Revoking an authCoreClaim (via its revocation nonce) automatically invalidates all credentials associated with it +- This eliminates the need to revoke each credential individually, saving time and effort while ensuring quick and effective security enforcement. + +:::note +The first `authCoreClaim` assosiated with an identity has a revocation nonce set to `0`. If this nonce is revoked, all previously issued credentials will become invalid for verification through ZKProofs. Additionally, new credentials cannot be issued with the identity linked to the revoked authCoreClaim. +::: + +In the sections below, we’ll walk through the process of creating new credentials (authCoreClaims) for an identity on the issuer node. + +## Creating a New Key + +The first step in creating a new authCoreClaim is to generate a babyjubjub-type private key. The issuer node provides an endpoint for this purpose: + +`/v2/identities/{identifier}/keys` [API Reference](https://issuer-node-core-api-demo.privado.id/#post-/v2/identities/-identifier-/keys) + +In the request body, specify that you want to create a babyjubjub-type key and provide a unique name for the key: + +```json +{ + "keyType": "babyjubJub", + "name": "my-new-key" +} +``` +The response will include a JSON payload similar to this: + +```json +{ + "id": "ZGlkOmlkZW4zOnBv..." +} +``` +The returned `id` represents the newly created babyjubjub key, which you’ll need to reference when creating the new `authCoreClaim`. + +## Creating the Auth Core Claim + +To create a new authCoreClaim, call the following endpoint: + +`/v2/identities/-identifier-/create-auth-credential` [API Reference](https://issuer-node-core-api-demo.privado.id/#post-/v2/identities/-identifier-/create-auth-credential) + +Include a request body like the example below: + +```json +{ + "KeyID" : "{{id of the previously generated key}}", + "expiration": 1829174400, // Expiration date (optional) + "version": 1, // Version (optional) + "revNonce": 100, // Revocation nonce (optional) + "credentialStatusType": "Iden3commRevocationStatusV1.0" // Must be supported by the issuer node (optional, default: Iden3commRevocationStatusV1.0) +} +``` +The response will return the ID of the newly created credential. This `id` can be used to retrieve and inspect the credential using the endpoint: + +`/v2/identities/-identifier-/credentials/-id-` [API Reference](https://issuer-node-core-api-demo.privado.id/#post-/v2/identities/-identifier-/credentials/-id-) + +The returned credential JSON will include a `vc` field containing a `credentialStatus` object as shown below: + +```json +[...] +"credentialStatus": { + "id": "", + "revocationNonce": 100, + "type": "Iden3commRevocationStatusV1.0" +}, +[...] +``` +:::note +The revocation nonce must be a unique value (not 0 or any value already assigned to other authCoreClaims). Revoking a nonce will invalidate all credentials associated with it. If no revocation nonce is provided, the issuer node will automatically assign one for you. +::: + +## Activating the New Auth Core Claim + +Once the new babyjubjub key and authCoreClaim are created, the issuer node’s state must be published on-chain for the authCoreClaim to become active. Use the following endpoint to publish the state: + +`/v2/identities/-identifier-/state/publish` [API Reference](https://issuer-node-core-api-demo.privado.id/#post-/v2/identities/-identifier-/state/publish) + +After the transaction is confirmed, the new authCoreClaim will be ready for use in issuing credentials. + +## How Does the Issuer Node Choose Which Auth Core Claim to Use? + +When issuing a new credential, the issuer node sequentially selects an `authCoreClaim` based on the order in which they were created. A claim is considered valid if it has been published on-chain and is not revoked. + +If you want to prevent the issuer node from using a specific authCoreClaim: + +1. Revoke the nonce associated with that authCoreClaim. +2. Publish the updated state on-chain to ensure the changes take effect. + +This process ensures that only the desired authCoreClaims are available for signing new credentials while maintaining security and flexibility in credential issuance. \ No newline at end of file diff --git a/docs/issuer/setup-issuer-core.md b/docs/issuer/setup-issuer-core.md index 62546c57..20aef0d0 100644 --- a/docs/issuer/setup-issuer-core.md +++ b/docs/issuer/setup-issuer-core.md @@ -68,44 +68,14 @@ cp .env-issuer.sample .env-issuer 3. Key Management System (KMS) Setup - Please Look at the [KMS configuration](https://github.com/0xPolygonID/issuer-node/blob/main/.env-issuer.sample#L21) in the sample file and file your .env-issuer config file accordingly. - - The Issuer Node allows you to choose between two key management systems for managing private keys: local storage (default) or [Vault](https://www.vaultproject.io/). It is recommended to use Vault for production environments for enhanced security. - - - Local Storage: - - If you opt for local storage, set the following in your .env-issuer file: - - ```bash - ISSUER_KMS_BJJ_PROVIDER=localstorage - ISSUER_KMS_ETH_PROVIDER=localstorage - ``` - - - Specify the path for local storage: - - ```bash - ISSUER_KMS_PROVIDER_LOCAL_STORAGE_FILE_PATH=./localstoragekeys - ``` - - - Vault: - - For Vault configuration, ensure that you set the Vault address, plugin, and authentication method properly: - - ```bash - ISSUER_KMS_BJJ_PROVIDER=vault - ISSUER_KMS_ETH_PROVIDER=vault - ISSUER_KEY_STORE_ADDRESS=http://vault:8200 - ISSUER_KEY_STORE_PLUGIN_IDEN3_MOUNT_PATH=iden3 - ``` - - - Optionally, configure authentication and TLS if necessary: - - ```bash - ISSUER_VAULT_USERPASS_AUTH_ENABLED=true - ISSUER_VAULT_USERPASS_AUTH_PASSWORD= - ISSUER_VAULT_TLS_ENABLED=false # Set to true if TLS is needed - ISSUER_VAULT_TLS_CERT_PATH= - ``` + The Issuer Node supports multiple Key Management System (KMS) options for securely creating, signing, and managing private keys. Depending on your setup, you can choose one or more of the following options: + - HashiCorp Vault + - AWS Secrets Manager + - AWS KMS (for ETH keys only) + - Local Storage (for testing only) + To configure your KMS, refer to the [sample .env-issuer file](https://github.com/0xPolygonID/issuer-node/blob/main/.env-issuer.sample#L21) and update your .env-issuer config file accordingly to your selected KMS. Detailed instructions and guidance on how to choose the right option for your use case can be found on the [KMS Configuration section](./issuer-configuration.md/#kms-configuration). 3. Import Ethereum Private Key diff --git a/docs/js-sdk/js-sdk-browser-wallet-demo.md b/docs/js-sdk/js-sdk-browser-wallet-demo.md deleted file mode 100644 index aecc3745..00000000 --- a/docs/js-sdk/js-sdk-browser-wallet-demo.md +++ /dev/null @@ -1,295 +0,0 @@ ---- -id: js-sdk-browser-wallet-demo -title: JS SDK Browser Wallet Demo -sidebar_label: Browser Wallet Demo -description: Check out a sample of a JS SDK browser application implementation. -keywords: - - docs - - polygon id - - holder - - issuer - - verifier - - wallet - - js sdk - - credential - - proof - - browser ---- - -import useBaseUrl from '@docusaurus/useBaseUrl'; - -## Demo for Polygon ID JS SDK Browser Wallet Extension - -Polygon ID has created a [sample browser wallet extension](https://github.com/0xPolygonID/extension-demo) based on our JS SDK that lets its user fetch credentials from an Issuer and generate proof for these credentials to be presented to a Verifier. - -You need to [manually install the browser wallet extension](https://github.com/0xPolygonID/extension-demo#how-deploy-project-as-chrome-extension) on your machine. This wallet works like a common crypto wallet such as the MetaMask Wallet but differs in functionality. - -:::note - -Some of the content on this page is still to be updated. Please note that the "Polygon Verify" service mentioned in the screenshots has been eliminated. The screenshots illustrate the general process of how the JS SDK wallet extension works. - -::: - -## Demo for JS SDK Browser Extension Wallet - -1. Install the Polygon ID JS SDK browser wallet extension on your machine and open it. - -2. When you open the extension for the first time, it prompts you to create a new wallet or import an existing wallet. Click **Create a New Wallet**. - -
- -
-
- -3. This shows the **_Create Password_** screen. Enter your password and confirm it. Click **Create**. - -
- -
-
- -4. This displays the Polygon Account window on your browser wallet. - -
- -
-
- -5. Open the Polygon Verify website (this is like an Issuer site that issues credentials to its users). Click **Sign Up**. - -
- -
-
- -6. A QR Code is displayed. Click on the **_Polygon ID_** icon to open your browser wallet. - -
- -
-
- -7. Your wallet shows the **_Authorization_** window. Click **Approve**. - -
- -
-
- - This shows auth info and claims list on the Polygon Verify site. - -
- -
- -## Steps to Create and Fetch Credentials - -1. On the website, click **Create Claim**. - -
- -
-
- -2. This displays the screen to create claims. - -
- -
-
- -3. Select **Schema** which you need to create credentials. Enter **Schema URL**, type of credential required, date of expiration of the credential, and other information related to the credential. For example, for a KYCAgeCredential, we can enter **birthdate** and **DocumentType**. Click **Submit**. - -
- -
-
- -4. After some moment, the credential is created successfully. - -
- -
-
- -5. As the credential is now created, the user needs to fetch it to his/her browser wallet. The website displays the QR code. Click the **_Polygon ID_** icon to open your browser wallet. On the wallet, click **Receive**. - -
- -
-
- - The credential is now saved on your browser wallet. -
- -
- -
- -## Steps to Create KYCAgeCredential Signature Proof - -1. On the Polygon Verify website, select the **_KYCAgeCredential(less than 2000/01/01)- sig_** type of credential. - -
- -
-
- -2. Click **Sign In**. This shows the QR code for the credential type you selected in the step above. Click the **_Polygon ID_** icon to open your browser wallet. - -
- -
-
- -3. The browser wallet shows the **_Proof Request_** window. Here, you can see the type of credential and proof requested. As you have selected the credential based on signature proof, the **_Proof Type_** shown here is type **_credentialAtomicQuerySigV2_**. Click **Continue**. - -
- -
-
- -4. The website verifies your membership successfully. - -
- -
-
- -5. On the wallet, click **KYCAgeCredential** to view its details including **_birthday_**, **_documentType_**, **_Issuer_** (DID of Issuer), **_Issued On_** (Date of Issuance), **_Expiration Date_**, and **_Proof types_** (in this case, it is BJJSignature2021). - -
- -
-
- -6. On the Polygon Verify website, click **Auth Info** to view details of the **_Auth Request_** (authorization requested by the user). - -
- -
-
- - Scroll down the page to view **_Auth Response_**. Here, you can see the proof and the public signals (used to generate the proof), and the JWZ token. Copy the JWZ token and paste it on the [Polygon ID JWZ Validator](https://jwz.polygonid.me) site. Click **Validate**. - -
- -
- -
-
- - Upon validation, the JWZ token is broken down into three parts: **_Header_**, **_Payload_**, and **_Auth Proof_**. - - Header and Payload: -
- -
-
- - Auth Proof: -
- -
-
- - You can see proof along with other data including **_from_** and **_to_** fields. The **_from_** field shows the DID that sent the proof request. It must match your wallet's DID. The **_to_** represents the Verifier DID to whom the proof request has been sent. - -7. Wait for the proof to get published on-chain. After that, on the website, you can view the credential details that show **_state_** information such as **_txId_** (ID of the transaction done from a wallet to complete publishing of the state on-chain), **_blockTimestamp_** (time at which block was created), **_blockNumber_**, **_rootofRoots_** (Roots tree), **_claimsTreeRoot_** (Claims tree), **_revocationTreeRoot_**(Revocation tree): - -
- -
- - Credential details: -
- -
- -8. Below the QR code, click the **_Polygon ID_** icon to open your browser wallet. On your wallet, click **Receive** to fetch and save the credential to your wallet. - -
- -
-
- - Click on your **_KYCAgeCredential_** to view its details. You can now see that you have two types of proofs in your wallet: **_BJJSignature2021_** and **_iden3SparseMerkleTreeProof_** - -
- -
-
- -## Steps to Create KYCAgeCredential Merkle Tree Proof - -1. On the Polygon Verify website, select the **_KYCAgeCredential(less than 2000/01/01)- mtp_** credential type. -
- -
-
- -2. Click **Sign In**. This shows the QR code for the credential type you selected in the step above. Click the **_Polygon ID_** icon to open your browser wallet. - -
- -
-
- -3. The browser wallet shows the **_Proof Request_** window. Here, you can see the type of credential and proof requested. As you have selected the credential based on MTP proof, the **_Proof Type_** shown here is **_credentialAtomicQueryMTPV2_**. Click **Continue**. - -
- -
-
- -4. The website verifies your membership successfully. -
- -
- -
-
- -5. On the Polygon Verify website, click **Auth Info** to view details of the **_Auth Request_** (authorization requested by the user). - - Scroll down the page to view **_Auth Response_**. Here, you can see the proof, the public signals (used to generate the proof), and the JWZ token. Copy the JWZ token and paste it on the [Polygon ID JWZ Validator](https://jwz.polygonid.me) site. Click **Validate**. - - Upon validation, the JWZ token is broken down into three parts: **_Header_**, **_Payload_**, and **_Auth Proof_**. - -
- -
- -
- - Header and Payload: -
- -
- -
- - Auth Proof: -
- -
-
- - You can see proof (**_CredentialAtomicQueryMTPV2_**) along with the other data including **_from_** and **_to_** fields. The **_from_** field shows the DID that sent the proof request. It must match your wallet's DID. The **_to_** represents the Verifier DID to whom the proof request has been sent. - -6. Wait for the proof to get published on-chain. After that, on the website, you can view the credential details that show **_state_** information such as **_txId_** (ID of the transaction done from a wallet to complete publishing of the state on-chain), **_blockTimestamp_** (time at which block was created), **_blockNumber_**, **_rootofRoots_** (Roots tree), **_claimsTreeRoot_** (Claims tree), **_revocationTreeRoot_**(Revocation tree): - -
- -
- - Credential details: -
- -
- -7. Below the QR code, click the **_Polygon ID_** icon to open your browser wallet. On your wallet, click **Receive** to fetch and save the credential to your wallet. - -
- -
diff --git a/docs/verifier/circuits.md b/docs/verifier/circuits.md new file mode 100644 index 00000000..9955c158 --- /dev/null +++ b/docs/verifier/circuits.md @@ -0,0 +1,151 @@ +--- +id: circuits +title: "Circuits" +sidebar_label: "Circuits" +description: "Explore the essential Circom circuits used in Iden3’s decentralized identity protocol. Learn how state transitions, authentication, and advanced credential verification techniques work together for robust digital identity management." +keywords: + - iden3 + - circuits + - decentralized identity + - identity verification + - circom + - zkSNARKs + - state transition + - authentication + - credential verification + - merkle tree + - on-chain + - off-chain + - digital identity + - cryptography +--- + + + +The following is the overview of the most important `circom` circuits used in Privado ID protocol and ecosystem. These circuits play a crucial role in enabling secure identity ownership, trustworthy credential verification, and efficient on-chain or off-chain checks. +## 1. stateTransition + +**Circuit Purpose:** +Validates an identity state transition from an old user state to the new one, ensuring the identity owner is the one making the update. + +**Usage Notes:** + +- Used whenever an identity’s Claims Tree, Revocation Tree, or Roots Tree is updated (e.g., adding or revoking a claim). +- Relies on the Prover’s signature to confirm ownership of the old state before finalizing the new state. +- Typically verified on-chain via a `transitState` function, which updates the global identity mapping and GIST upon successful proof verification. + +## 2. authV2 + +**Circuit Purpose:** +Confirms that the Prover (identity holder) owns a specific identity by controlling a BabyJubJub private key and including its state in the GIST (global identity state tree) or being at genesis state. + +**Usage Notes:** + +- `authV2` is the standard circuit for proving an identity’s ownership with on-chain or off-chain identity state consistency checks. +- It is a main circuit to be used in authentication and authorization flows in JWZ (JSON WEB Zero-Knowledge tokens). + +## 3. credentialAtomicQueryMTPV2 + +**Circuit Purpose:** +Proves that the Prover holds a valid credential (issued by an issuer) that satisfies a Verifier’s query. The credential's representation is stored in the issuer’s Claims Tree, and the circuit relies on: + +- Checking that the core claim representation hash is included in this tree via a Merkle Tree Proof (MTP) approach. +- Verifying the non-revocation of the credentials in the issuer’s Revocation Tree. +- Checking the validity of the issuer's state and its existence in the state contract. +- Ensuring that the Prover uses an identity that controls the credential subject identifier. +- Supporting queries on any credential field, thanks to the unique JSON-LD merklization algorithm. + +**Usage Notes:** + +- Designed for off-chain verifications with atomic queries. + +## 4. credentialAtomicQueryMTPV2Onchain + +**Circuit Purpose:** +Same as `credentialAtomicQueryMTPV2`, but with support for output optimizations, making it more efficient for on-chain use. **Note:** It does not support selective disclosure. + +**Usage Notes:** + +- Designed for on-chain verifiers. + +## 5. credentialAtomicQuerySigV2 + +**Circuit Purpose:** +Similar to `credentialAtomicQueryMTPV2` but for credentials that are signed by the issuer's BabyJubJub key rather than being included in the issuer’s Merkle Tree. It: + +- Verifies the issuer’s signature over the core claim representation of a W3C credential (including the Merkle root of the JSON-LD document). +- Checks that the BabyJubJub key is included in the issuer state (which is either at genesis or published on-chain) and that key is not revoked in the latest issuer state. + +**Usage Notes:** + +- Suitable when the issuer issues credentials in a purely signature-based manner, rather than including them in state and performing state transitions. + +## 6. credentialAtomicQuerySigV2Onchain + +**Circuit Purpose:** +Builds on `credentialAtomicQuerySigV2` by adding on-chain verifier support. It: + +- Checks that a credential signed by the issuer meets the verifier’s query. +- Verifies that the Prover controls the identity to which the credential belongs. +- Ensures that the credential is not expired or revoked. +- Computes a hash of query-related inputs (such as schema, operator, value, etc.) for cheaper on-chain verification of the proof. + +**Usage Notes:** + +- Ideal for smart contract verifiers that need to confirm a user’s credentials without relying on the issuer’s Merkle tree (i.e., signature-based issuance). +- The circuit’s proof can be submitted to a contract function (often verifying via an on-chain zkSNARK), reducing gas costs by exposing fewer public inputs. + +## 7. credentialAtomicQueryV3-beta.1 + +**Circuit Purpose:** +An enhanced version of `credentialAtomicQueryV2` that supports: + +- Optional revocation checks. +- Credential expiration checks. +- Selective disclosure of specific credential fields. +- Computation of nullifiers for one-time or limited-use proofs. + +This circuit combines the verification of BabyJubJub signatures and Iden3SparseMerkleTreeProof in a single circuit, ideal for advanced credential scenarios where flexible issuance (signature- or Merkle-based) and partial data disclosure are required. + +- **Supports Nullifiers:** The proof can only be used once for the same verifier, credential, user identity, and nullifier session id. +- Supports linkage between proofs. + +**Usage Notes:** + +- Supports more comparison operators. +- Can be integrated with on-chain or off-chain verifiers; if on-chain, the V3OnChain variant is typically used to reduce public inputs. + +## 8. credentialAtomicQueryV3Onchain-beta.1 + +**Circuit Purpose:** +Designed for smart contract verifiers, this circuit builds on `credentialAtomicQueryV3` by adding two major enhancements: + +1. It can check that the Prover controls the identity, similar to how `authV2` works (if authentication is enabled). +2. It computes a hash of all query-related inputs (e.g., `claimSchema`, `slotIndex`, `operator`, `claimPathKey`, `claimPathNotExists`, and any field values) so they don’t need to be exposed individually as public inputs on-chain. + +**Usage Notes:** + +- Ideal for on-chain verification where minimizing public inputs is crucial to reduce gas costs. +- Retains all capabilities of `credentialAtomicQueryV3`, such as selective disclosure, expiration checks, and optional revocation checks. +- If authentication is enabled, the Prover must demonstrate identity ownership in the same way as `authV2` before the proof is accepted. +- The reduced set of public inputs lowers the overhead for smart contract verification, making it more efficient for complex or frequent credential proofs on Ethereum. + +## 9. linkedMultiQuery10-beta.1 + +**Circuit Purpose:** +Generates a single proof capable of verifying up to **10 parameters** in a single query. This allows multiple credential attributes or conditions (e.g., age, location, graduation) to be checked together, simplifying and streamlining multi-parameter verifications. + +**Usage Notes:** + +- Batching multiple parameter checks into one proof reduces overhead and improves efficiency compared to issuing separate queries. +- Ideal for composite credential checks (e.g., age, residence, and education) in a single proof step. +- Should be used by verifiers **only in conjunction with** the `credentialAtomicV3` circuit to ensure all checks (including signatures) are properly performed. +- Supports integration with both on-chain and off-chain verifiers, providing flexibility for a range of identity and credential scenarios. + +## Source Code: + +[Circuits Github link](https://github.com/iden3/circuits) + +## Public Verification Keys + +All public verification keys for the Iden3 circuits, generated following the [trusted setup](https://github.com/0xPolygonID/phase2ceremony), are available at [this link](https://github.com/0xPolygonID/verifier-backend/tree/develop/keys). This resource ensures transparency and makes it easier to verify proofs. \ No newline at end of file diff --git a/docs/verifier/verification-library/verifier-set-up.md b/docs/verifier/verification-library/verifier-set-up.md index 4f6f4669..877dc8cb 100644 --- a/docs/verifier/verification-library/verifier-set-up.md +++ b/docs/verifier/verification-library/verifier-set-up.md @@ -170,9 +170,6 @@ uri := fmt.Sprintf("%s%s?sessionId=%s", rURL, CallbackURL, strconv.Itoa(sessionI // Generate request for basic authentication var request protocol.AuthorizationRequestMessage = auth.CreateAuthorizationRequest("test flow", Audience, uri) -request.ID = "7f38a193-0918-4a48-9fac-36adfdb8b542" -request.ThreadID = "7f38a193-0918-4a48-9fac-36adfdb8b542" - // Add request for a specific proof var mtpProofRequest protocol.ZeroKnowledgeProofRequest mtpProofRequest.ID = 1 @@ -220,9 +217,6 @@ async function GetAuthRequest(req, res) { // Generate request for basic authentication const request = auth.createAuthorizationRequest("test flow", audience, uri); - request.id = "7f38a193-0918-4a48-9fac-36adfdb8b542"; - request.thid = "7f38a193-0918-4a48-9fac-36adfdb8b542"; - // Add request for a specific proof const proofRequest = { id: 1, diff --git a/docs/verifier/verification-library/zk-query-language.md b/docs/verifier/verification-library/zk-query-language.md index 97e9fabe..c01e165c 100644 --- a/docs/verifier/verification-library/zk-query-language.md +++ b/docs/verifier/verification-library/zk-query-language.md @@ -980,8 +980,65 @@ In the example below, the verifier requests two different proof queries in the s } ``` +## Multi query from a single Credential + +To efficiently query multiple attributes from a single credential, use the [LinkedMultiQuery Circuit](./../circuits#9-linkedmultiquery10circom). It supports up to 10 queries in a single proof response, reducing redundancy while ensuring security. + +The LinkedMultiQuery Circuit verifies multiple field-based predicate requests, while the V3 Atomic Query Circuit validates credential integrity (signature, Merkle proof, non-revocation, etc.). Both proofs must be from the same credential and share the same groupId to ensure validity. Verification is only valid when both proofs pass. + +** Example Query** + +This request includes a LinkedMultiQuery (for multiple fields) and a V3 Atomic Query (for credential validation). + + +```json +{ + "id": "f8aee09d-f592-4fcc-8d2a-8938aa26676c", + "typ": "application/iden3comm-plain-json", + "type": "https://iden3-communication.io/authorization/1.0/request", + "thid": "f8aee09d-f592-4fcc-8d2a-8938aa26676c", + "from": "did:iden3:polygon:amoy:2qFroxB5kwgCxgVrNGUM6EW3khJgCdHHnKTr3VnTcp", + "body": { + "callbackUrl": "https://test.com/callback", + "reason": "Employee verification", + "message": "test message", + "scope": [ + { + "id": "1", + "circuitId": "linkedMultiQuery10-beta.1", + "query": { + "groupId": 1, + "proofType": "BJJSignature", + "allowedIssuers": ["*"], + "type": "KYCEmployee", + "context": "https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v101.json-ld", + "credentialSubject": { + "documentType": { "$eq": 1 }, + "position": { "$eq": "boss", "$ne": "employee" } + } + } + }, + { + "id": "2", + "circuitId": "credentialAtomicQueryV3-beta.1", + "query": { + "groupId": 1, + "proofType": "BJJSignature", + "allowedIssuers": ["*"], + "type": "KYCEmployee", + "context": "https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v101.json-ld", + "credentialSubject": { + "hireDate": { "$eq": "2023-12-11" } + } + }, + } + ] + } +} +``` + :::warning "Allowed Issuers" When we use `*` in the "allowed issuers" segment (`allowedIssuers: ['*']`), we mean that we accept any entity that might have provided the credential. Even though this seems to be convenient for testing purposes, it may also be considered risky. Applying due diligence by **actually choosing trusted specific issuers** should be the best approach. Only in rare cases, a verifier would accept any issuer, so we advise not to use `*`. -::: +::: \ No newline at end of file diff --git a/docs/verifier/verifier-backend.md b/docs/verifier/verifier-backend.md index d9024c63..7b7c5ce1 100644 --- a/docs/verifier/verifier-backend.md +++ b/docs/verifier/verifier-backend.md @@ -16,7 +16,7 @@ The [Verifier Backend](https://github.com/0xPolygonID/verifier-backend) project It is built using libraries developed by the iden3 protocol team. Below, we'll explain how to install it using Docker and how it can be used to perform zero knowledge proofs. -You can try our [Verifier Backend API](https://verifier-backend.polygonid.me/) running. +You can try our [Verifier Backend API](https://verifier-backend.privado.id/) running. ## Local Installation diff --git a/sidebars.js b/sidebars.js index ab5f8317..49b2638f 100644 --- a/sidebars.js +++ b/sidebars.js @@ -57,6 +57,7 @@ module.exports = { "issuer-node/issuer-node-guide", ] }, + "issuer/key-rotation", { type: "category", label: "On-chain Issuer", @@ -153,8 +154,10 @@ module.exports = { }, "verifier/query-builder", "verifier/verification-library/zk-query-language", + "verifier/circuits", "verifier/v3-circuit", + ], }, { @@ -377,7 +380,6 @@ module.exports = { ], }, "js-sdk/js-sdk-example", - "js-sdk/js-sdk-browser-wallet-demo", "js-sdk/js-sdk-dynamic-did" ], }, diff --git a/src/data/content-data.js b/src/data/content-data.js index 05a079ba..5af5e6e2 100644 --- a/src/data/content-data.js +++ b/src/data/content-data.js @@ -104,19 +104,19 @@ export const contentData = { }, { title: "Build an app with Android SDK", - link: "/docs/wallet/wallet-sdk/android-sdk/install-android-sdk", + link: "/docs/wallet/wallet-sdk/android-sdk/example-app", }, { title: "Wallet APIs", link: "/docs/category/wallet-apis", }, { - title: "Polygon ID Wallet app: SDK reference implementation", - link: "/docs/wallet/wallet-sdk/polygonid-app", + title: "Privado ID Wallet app: Wallet SDK reference implementation", + link: "/docs/category/privado-id-wallet-app", }, { - title: "Web wallet via JS SDK", - link: "/docs/js-sdk/js-sdk-browser-wallet-demo", + title: "Privado ID Web wallet: JS SDK reference implementation", + link: "/docs/wallet/web-wallet", }, ], }, diff --git a/static/img/display_methods/1.png b/static/img/display_methods/1.png new file mode 100644 index 00000000..834f7077 Binary files /dev/null and b/static/img/display_methods/1.png differ diff --git a/static/img/display_methods/2.png b/static/img/display_methods/2.png new file mode 100644 index 00000000..272560bf Binary files /dev/null and b/static/img/display_methods/2.png differ diff --git a/static/img/display_methods/3.png b/static/img/display_methods/3.png new file mode 100644 index 00000000..752c6d4d Binary files /dev/null and b/static/img/display_methods/3.png differ diff --git a/static/img/display_methods/4.png b/static/img/display_methods/4.png new file mode 100644 index 00000000..9a4aed38 Binary files /dev/null and b/static/img/display_methods/4.png differ diff --git a/static/img/display_methods/5.png b/static/img/display_methods/5.png new file mode 100644 index 00000000..133b76ab Binary files /dev/null and b/static/img/display_methods/5.png differ diff --git a/static/img/display_methods/6.png b/static/img/display_methods/6.png new file mode 100644 index 00000000..c465be27 Binary files /dev/null and b/static/img/display_methods/6.png differ