From 3b6ae86b6efc0ee2ab926e359cd12864907b98f2 Mon Sep 17 00:00:00 2001 From: vmidyllic <74898029+vmidyllic@users.noreply.github.com> Date: Tue, 19 Sep 2023 13:04:58 +0300 Subject: [PATCH 1/2] add page for non-merklized.md --- mkdocs/docs/protocol/claim-schema.md | 16 ++-- mkdocs/docs/protocol/non-merklized.md | 126 ++++++++++++++++++++++++++ mkdocs/mkdocs.yml | 1 + 3 files changed, 134 insertions(+), 9 deletions(-) create mode 100644 mkdocs/docs/protocol/non-merklized.md diff --git a/mkdocs/docs/protocol/claim-schema.md b/mkdocs/docs/protocol/claim-schema.md index 3f8bee8..5889ce6 100644 --- a/mkdocs/docs/protocol/claim-schema.md +++ b/mkdocs/docs/protocol/claim-schema.md @@ -6,7 +6,7 @@ Schemas are described via JSON-LD documents. A claim issuer could reuse existing ## Example: KYCAgeCredential Schema -- [Github Document](https://github.com/iden3/claim-schema-vocab/blob/main/schemas/json-ld/kyc-v3.json-ld) +- [Github Document](https://github.com/iden3/claim-schema-vocab/blob/main/schemas/json-ld/kyc-v4.jsonld) ```json { @@ -17,7 +17,7 @@ Schemas are described via JSON-LD documents. A claim issuer could reuse existing "id": "@id", "type": "@type", "KYCAgeCredential": { - "@id": "https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v3.json-ld#KYCAgeCredential", + "@id": "https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v4.jsonld#KYCAgeCredential", "@context": { "@version": 1.1, "@protected": true, @@ -34,7 +34,7 @@ Schemas are described via JSON-LD documents. A claim issuer could reuse existing "@type": "xsd:integer" } } - }, + } } ] } @@ -47,16 +47,14 @@ The last part of the document contains a reference to the value types `birthday` ## Schema Hash -The Schema Hash is a unique identifier for a Claim Schema. It is derived by hashing the string that represents unique identifier `@id` of the Claim Schema type. In the previous example, the hash pre-image is the string `https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v3.json-ld#KYCAgeCredential`. - +The Schema Hash is a unique identifier for a Claim Schema. It is derived by hashing the string that represents unique identifier `@id` of the Claim Schema type. In the previous example, the hash pre-image is the string `https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v4.jsonld#KYCAgeCredential`. +` For example, in the case of the Auth Claim the schema hash would be ```golang var sHash core.SchemaHash -h := Keccak256([]byte("https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v3.json-ld#KYCAgeCredential")) +h := Keccak256([]byte("https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v4.jsonld#KYCAgeCredential")) copy(sHash[:], h[len(h)-16:]) sHashHex, _ := sHash.MarshalText() - fmt.Println(string(sHashHex)) -// f21e8faf5c95292b6bfbc53f8143a9d4 -``` \ No newline at end of file +``` diff --git a/mkdocs/docs/protocol/non-merklized.md b/mkdocs/docs/protocol/non-merklized.md new file mode 100644 index 0000000..48145be --- /dev/null +++ b/mkdocs/docs/protocol/non-merklized.md @@ -0,0 +1,126 @@ +# Non-merklized credentials + +## Motivation + +While Iden3 protocol allows to have a root of merklized JSON-LD document for proving the inclusion of the credential entries in the tree, that increases level of privacy and flexibility for the credential data there is also a need to issue a core claim with a data itself. This is useful as for onchain issuers that can’t work with ld schemas in smart contracts and also for use case when the actual data must be saved, e.g. Auth BJJ credential public key representation. + +**Core Concept** + +Non merklized credentials now can be created relying on JSON-LD schemas. + +Example of such context: `https://schema.iden3.io/core/jsonld/auth.jsonld` + +```json +{ + "@context": [{ + "@version": 1.1, + "@protected": true, + "id": "@id", + "type": "@type", + "AuthBJJCredential": { + "@id": "https://schema.iden3.io/core/jsonld/auth.jsonld#AuthBJJCredential", + "@context": { + "@version": 1.1, + "@protected": true, + "id": "@id", + "type": "@type", + "iden3_serialization": "iden3:v1:slotIndexA=x&slotIndexB=y", + "xsd": "http://www.w3.org/2001/XMLSchema#", + "auth-vocab": "https://schema.iden3.io/core/vocab/auth.md#", + "x": { + "@id": "auth-vocab:x", + "@type": "xsd:positiveInteger" + }, + "y": { + "@id": "auth-vocab:y", + "@type": "xsd:positiveInteger" + } + } + } + }] +} +``` + +Schema is defined as a schema for non-merklized credentials by utilizing `iden3_serialization` attribute. + +It contains a map string represented mapping, where: + +`iden3:v1` - version of protocol serialization, constant. + +`slotIndexA=x` slotIndexA is index data slot A with index 2 for path to field `x` in credential + +`slotIndexB=y` slotIndexB is index data slot B with index 3 for path to field `y` in credential + +other possible values: + +`slotValueA` slotIndexB is value data slot with index 6 + +`slotValueB` slotValueB is value data slot with index 7 + +See more information regarding data slot indexes [here](https://www.notion.so/Identity-Core-77fe2f04c8ad4e0296e2b90400d7ae3a?pvs=21). When user creates schema he should choose the slot to put the field. + +Nested structures are supported and path are created using concatenation with `.` e.g for birthday field in the Index Data Slot A mapping entry looks like that: `"...slotIndexA=passportInfo.birthday"` + +```json +{ + ... + ... + "passportInfo": { + "@id": "vocab:passportInfo", + "@context": { + "@version": 1.1, + "@protected": true, + "kyc-vocab": "https://github.com/iden3/claim-schema-vocab/blob/main/credentials/kyc.md#", + "xsd": "http://www.w3.org/2001/XMLSchema#", + "id": "@id", + "type": "@type", + "birthday": { + "@type": "xsd:integer", + "@id": "vocab:birthday" + } + } + } + ... + ... +} +``` + +**Important**: + +1. Fields in index slots make influence on the uniqueness of the claim in the clams tree of issuer, data in the value slots - don’t. +2. Data Slots number is 4, so there is a restriction to have only 4 fields for non-merklized credentials. + +Meanwhile `@type` filed for each field must contain one of the supported primitive types, so value can be written according to the data type. + +List of supported data types: + +```jsx +XSD namespace { + Boolean = 'http://www.w3.org/2001/XMLSchema#boolean', + Integer = 'http://www.w3.org/2001/XMLSchema#integer', + NonNegativeInteger = 'http://www.w3.org/2001/XMLSchema#nonNegativeInteger', + NonPositiveInteger = 'http://www.w3.org/2001/XMLSchema#nonPositiveInteger', + NegativeInteger = 'http://www.w3.org/2001/XMLSchema#negativeInteger', + PositiveInteger = 'http://www.w3.org/2001/XMLSchema#positiveInteger', + DateTime = 'http://www.w3.org/2001/XMLSchema#dateTime', + Double = 'http://www.w3.org/2001/XMLSchema#double' +} +``` + +Libraries that support non-merklized credentials: +https://github.com/iden3/go-schema-processor/releases/tag/v2.0.1 +https://github.com/0xPolygonID/js-sdk/releases/tag/v1.1.0 + +To create non-merklized credential in go-schema-processor / JS-sdk merklized Root Position must be set to None (default value) and ld context must contain `iden3_serialization` attribute. + +```go +processor.CoreClaimOptions{ + .., + MerklizedRootPosition: verifiable.CredentialMerklizedRootPositionNone, + ... + } +``` + +If context contains serialization attribute but MerklizedRootPosition is set to Index / Value error will be thrown. + +In case context doesn’t contain serialization attribute and MerklizedRootPosition is set to Index / Value. Merkle root will be written to corresponding position. If the MerklizedRootPosition is set to None Merkle root will be written to Index. diff --git a/mkdocs/mkdocs.yml b/mkdocs/mkdocs.yml index 81b4d57..759c27d 100644 --- a/mkdocs/mkdocs.yml +++ b/mkdocs/mkdocs.yml @@ -84,6 +84,7 @@ nav: # - Libraries: "services/libraries.md" - Login protocol: "protocol/zklogin.md" - Proof Query language: "protocol/querylanguage.md" + - NON merklized credentials: "protocol/non-merklized.md" - JSON-LD merklization: "w3c/merklization.md" - Reverse hash service: "services/rhs.md" - On-chain credential status: "protocol/onchain-credential-status.md" From ab68ef6d3263f0e40e25029c10c21ac2072f1405 Mon Sep 17 00:00:00 2001 From: vmidyllic <74898029+vmidyllic@users.noreply.github.com> Date: Tue, 26 Sep 2023 17:21:52 +0300 Subject: [PATCH 2/2] fix comments --- mkdocs/docs/protocol/non-merklized.md | 39 +++++++++++++++++++-------- mkdocs/mkdocs.yml | 2 +- 2 files changed, 29 insertions(+), 12 deletions(-) diff --git a/mkdocs/docs/protocol/non-merklized.md b/mkdocs/docs/protocol/non-merklized.md index 48145be..a5f81ef 100644 --- a/mkdocs/docs/protocol/non-merklized.md +++ b/mkdocs/docs/protocol/non-merklized.md @@ -2,11 +2,11 @@ ## Motivation -While Iden3 protocol allows to have a root of merklized JSON-LD document for proving the inclusion of the credential entries in the tree, that increases level of privacy and flexibility for the credential data there is also a need to issue a core claim with a data itself. This is useful as for onchain issuers that can’t work with ld schemas in smart contracts and also for use case when the actual data must be saved, e.g. Auth BJJ credential public key representation. +While Iden3 protocol allows to "merklize" the whole JSON-LD document (transform the document into key-value pairs and put them into a sparse merkle tree for later proving of credential field value in the tree), which removes limits on amount and structure of the credential data, there's still a need to issue a core claim with the data itself. This is particularly useful for onchain issuers, which can’t work with json-ld schemas in smart contracts (for many reasons), and also for use cases when the actual data must be saved for cheaper access inside circuits (e.g. Auth BJJ credential public key representation). **Core Concept** -Non merklized credentials now can be created relying on JSON-LD schemas. +Non-merklized credentials now can be created relying on JSON-LD schemas. Example of such context: `https://schema.iden3.io/core/jsonld/auth.jsonld` @@ -59,14 +59,29 @@ other possible values: See more information regarding data slot indexes [here](https://www.notion.so/Identity-Core-77fe2f04c8ad4e0296e2b90400d7ae3a?pvs=21). When user creates schema he should choose the slot to put the field. -Nested structures are supported and path are created using concatenation with `.` e.g for birthday field in the Index Data Slot A mapping entry looks like that: `"...slotIndexA=passportInfo.birthday"` +Nested structures are supported and path is created using concatenation with `.` e.g for birthday field in the Index Data Slot A mapping entry looks like that: + +`"iden3:v1:slotIndexA=passportInfo.birthday"` ```json { - ... - ... + "@context": [ + { + "@version": 1.1, + "@protected": true, + "id": "@id", + "type": "@type", + "Passport": { + "@id": "uuid:urn:229a9afc-4aad-48e4-b113-bf2ca6f3a98f", + "@context": { + "@version": 1.1, + "@protected": true, + "id": "@id", + "type": "@type", + "kyc-vocab": "https://github.com/iden3/claim-schema-vocab/blob/main/credentials/kyc.md#", + "xsd": "http://www.w3.org/2001/XMLSchema#", "passportInfo": { - "@id": "vocab:passportInfo", + "@id": "kyc-vocab:passportInfo", "@context": { "@version": 1.1, "@protected": true, @@ -76,12 +91,14 @@ Nested structures are supported and path are created using concatenation with `. "type": "@type", "birthday": { "@type": "xsd:integer", - "@id": "vocab:birthday" + "@id": "kyc-vocab:birthday" } } } - ... - ... + } + } + } + ] } ``` @@ -94,7 +111,7 @@ Meanwhile `@type` filed for each field must contain one of the supported primiti List of supported data types: -```jsx +```json XSD namespace { Boolean = 'http://www.w3.org/2001/XMLSchema#boolean', Integer = 'http://www.w3.org/2001/XMLSchema#integer', @@ -113,7 +130,7 @@ https://github.com/0xPolygonID/js-sdk/releases/tag/v1.1.0 To create non-merklized credential in go-schema-processor / JS-sdk merklized Root Position must be set to None (default value) and ld context must contain `iden3_serialization` attribute. -```go +```golang processor.CoreClaimOptions{ .., MerklizedRootPosition: verifiable.CredentialMerklizedRootPositionNone, diff --git a/mkdocs/mkdocs.yml b/mkdocs/mkdocs.yml index 759c27d..ac5f3b6 100644 --- a/mkdocs/mkdocs.yml +++ b/mkdocs/mkdocs.yml @@ -84,7 +84,7 @@ nav: # - Libraries: "services/libraries.md" - Login protocol: "protocol/zklogin.md" - Proof Query language: "protocol/querylanguage.md" - - NON merklized credentials: "protocol/non-merklized.md" + - Non-merklized credentials: "protocol/non-merklized.md" - JSON-LD merklization: "w3c/merklization.md" - Reverse hash service: "services/rhs.md" - On-chain credential status: "protocol/onchain-credential-status.md"