From 5faa5c2eba61d79e85b41cdef923d6fdb9376308 Mon Sep 17 00:00:00 2001 From: Wes Biggs Date: Thu, 29 Aug 2024 10:23:45 -0400 Subject: [PATCH] Include support for VC 2.0 credentials. Other updates, fixes, and clarifications. --- book.toml | 2 +- .../ActivityContent/Associated/Attachments.md | 120 +++--------------- pages/DSNP/AttributeSets.md | 45 +++---- pages/DSNP/Types/DSNPContentAttributeSet.md | 6 +- .../DSNP/Types/ExternalContentAttributeSet.md | 10 +- pages/DSNP/Types/UserAttributeSet.md | 6 +- pages/VerifiableCredentials/Overview.md | 20 +-- pages/VerifiableCredentials/Types/DID.md | 13 +- .../Types/VerifiableCredential.md | 34 ++--- .../Types/VerifiableCredentialSchema.md | 14 +- 10 files changed, 90 insertions(+), 180 deletions(-) diff --git a/book.toml b/book.toml index 02905339..f9684958 100644 --- a/book.toml +++ b/book.toml @@ -17,7 +17,7 @@ preferred-dark-theme = "coal" [output.linkcheck] follow-web-links = true traverse-parent-directories = false -exclude = ['en\.bitcoin\.it', 'github\.com/LibertyDSNP/spec'] +exclude = ['en\.bitcoin\.it', 'github\.com/LibertyDSNP/spec', 'w3\.org'] [output.html.fold] enable = true diff --git a/pages/ActivityContent/Associated/Attachments.md b/pages/ActivityContent/Associated/Attachments.md index b3dd7cf8..eccf1c54 100644 --- a/pages/ActivityContent/Associated/Attachments.md +++ b/pages/ActivityContent/Associated/Attachments.md @@ -209,13 +209,21 @@ } ``` -## Attestations and Interactions +## Attestations -Attestation and Interaction attachments are DSNP extensions to the Activity Content model that allow Verifiable Credentials to be attached to content with clear semantics. +Attestation attachments are DSNP extensions to the Activity Content model that allow users to attach Verifiable Credentials corresponding to an Attribute Set Type with their DSNP profile or a social media post. + +The Verifiable Credential found at the indicated URL must include the user's [DSNP User URI](../../DSNP/Identifiers.md#dsnp-user-uri) in its `credentialSubject.id` field. + +| Property | Base Spec | Required | Description | Restrictions | +| --- | --- | --- | --- | --- | +| `type` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-type) | YES | Identifies the type of the object | MUST be set to `Attestation` | +| `url` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-url) | YES | An array of links for the given credential | MUST be a [Verifiable Credential Link](#verifiable-credential-link) | +| `name` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-name) | no | The display name for the attestation | | ### Verifiable Credential Link -Both Attestation and Interaction attachments must contain a link to Verifiable Credential document. +Attestation attachments must contain a link to a Verifiable Credential document. The link must contain a relationship identifier in the form of a DSNP Attribute Set Type (the `rel` field), to allow applications to determine the type of credential expected. | Property | Base Spec | Required | Description | Restrictions | @@ -223,21 +231,8 @@ The link must contain a relationship identifier in the form of a DSNP Attribute | `type` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-type) | YES | Identifies the type of the object | MUST be set to `Link` | | `rel` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-id) | YES | The attestation's attribute set type | MUST be a DSNP [Attribute Set Type](../../DSNP/AttributeSets.md#attribute-set-type) corresponding to the referenced credential document | | `href` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-href) | YES | The URL for the associated Verifiable Credential | MUST be a [Supported URL Schema](../Overview.md#supported-url-schema) | -| `mediaType` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-mediatype) | YES | MIME type of `href` content | MUST be set to [`application/vc+ld+json`](https://w3c.github.io/vc-data-model/#vc-ld-media-type) | -| `hash` | [DSNP 1.0](Hash.md) | YES | Array of hashes for linked content validation | MUST include at least one [supported hash](Hash.md#supported-algorithms) | - -### Attestation - -Attestations about a DSNP User may be included as attachments in an Activity object. -This format allows users to include relevant data corresponding to an Attribute Set Type with their DSNP profile or a social media content item. - -The Verifiable Credential found at the indicated URL must include the [DSNP DID](../../VerifiableCredentials/Types/DID.md) of the user in its `credentialSubject.id` field. - -| Property | Base Spec | Required | Description | Restrictions | -| --- | --- | --- | --- | --- | -| `type` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-type) | YES | Identifies the type of the object | MUST be set to `Attestation` | -| `url` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-url) | YES | An array of links for the given credential | MUST be a [Verifiable Credential Link](#verifiable-credential-link) | -| `name` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-name) | no | The display name for the attestation | | +| `mediaType` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-mediatype) | YES | MIME type of `href` content | MUST be set to [`application/vc`](https://www.w3.org/TR/vc-data-model-2.0/#vc-ld-media-type) | +| `hash` | [DSNP extension](Hash.md) | YES | Array of hashes for linked content validation | MUST include at least one [supported hash](Hash.md#supported-algorithms) | #### Example @@ -254,84 +249,11 @@ The Verifiable Credential found at the indicated URL must include the [DSNP DID] "url": [ { "type": "Link", - "rel": "did:dsnp:123456$AcmeMedicalAssociation", + "rel": "did:dsnp:123456$AcmeMedicalAssociationPhysician", "href": "https://acmemedicalassn.org/credentials/degree-123.json", - "mediaType": "application/vc+ld+json", - "hash": [ - "QmQrGdv6Ky5sJhaVdw27y4aod5pdfihDkBTxiBkRaSGJJ7" - ] - } - ] - } - ], - "published": "1970-01-01T00:00:00+00:00" -} -``` - -### Interaction - -The `Interaction` attachment type enables simple discovery of pseudonymously issued credentials that may be relevant for a user to relate to a specific content item. - -In contrast to `Attestation` attachments, Interactions reference a Verifiable Credential that does not address a specific DSNP User as its subject, but instead relies on a user-provided interaction identifier that can later be provably associated with a DSNP identity. -This allows for the issuance of Interaction credentials outside of an authenticated DSNP application context, and in scenarios where users wish to remain anonymous to the issuer. - -An Interaction attachment resembles an Attestation, with the addition of an interaction nonce as described below (the `nonce` field), a Verifiable Credential Link in the `url` field, and an identifier of the object of the interaction in the `href` field. -The linked Verifiable Credential must have a credential subject that minimally includes an `interactionId` and repeats the `href` field, but may contain other data as defined by a [Verifiable Credential Schema](../../VerifiableCredentials/Types/VerifiableCredentialSchema.md)). - -Proof that the credential was issued to the user responsible for posting the content is produced and verified using a cryptographic hash. -To acquire an anonymous Interaction credential, a DSNP User generates and records a random nonce of any length (192 bits or more is recommended). -The user then concatenates their DSNP User Id (in little-endian 64-bit format) with the nonce and generates a message digest using a [supported hashing algorithm](Hash.md#supported-algorithms). -The multibase-encoded hash output is then sent to the credential issuer to be included as an `interactionId` key in the `credentialSubject` field of the generated document. -It is intentionally opaque to the issuer. -The issuer may include any other fields relevant to the document schema in the `credentialSubject`, and then generate a signature proof. -The URL of the signed credential is then included in the interaction attachment (see example). - -When posting content including the Interaction attachment, the user must include the nonce (as the `nonce` key) in order for consuming applications to verify that the originator of the content is responsible for generating the interaction. -A verifier MUST inspect the DSNP User Id of the sender of the content (via the relevant announcement) and the nonce, and repeat the hashing process to verify that it matches the value from `interactionId`. - -Issuers of interaction credentials are encouraged to use the `display` extension described in the DSNP [Verifiable Credential Schema](../../VerifiableCredentials/Types/VerifiableCredentialSchema.md#display-extension) documentation to provide applications with hints as to how a verified interaction may be displayed, for example as a badge on a profile or content post. - -| Property | Base Spec | Required | Description | Restrictions | -| --- | --- | --- | --- | --- | -| `type` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-type) | YES | Identifies the tag as type `Interaction` | MUST be `Interaction` | -| `url` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-url) | YES | An array of links for the given credential | MUST be a [Verifiable Credential Link](#verifiable-credential-link) | -| `name` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-name) | no | The display name for the interaction | | -| `reference` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-id) | YES | URI of object of the interaction | MUST be the same as the corresponding field within the linked document's `credentialSubject` | -| `nonce` | DSNP extension | YES | Multibase-encoded random byte string (a minimum deserialized size of 24 bytes is recommended) | | - -#### Provenance of Interaction Credentials (Non-Normative) - -Part of the provenance of a credential relies upon having a DSNP User Id and nonce that are hashed by the requester of the credential. -Ideally, the requester could prove that they were the user indicated by the DSNP User Id. -Similar assertions are often done by providing signatures: the user could sign a message including their User Id with the private key associated with a public key they manage as user data, in much the same way that the issuer of a Verifiable Credential creates a signature proof. - -However, because DSNP does not prevent multiple users from associating the same public key with their accounts, it would be possible, for example, for Alice to obtain a credential in Bob's name and give it to Bob to post, as long as Bob represents that the corresponding public key is his own by listing it as one of his DSNP public keys. -Therefore, the provenance guarantee offered by the hashing approach on an otherwise anonymous credential is ultimately equivalent. -Because of this, applications should _not_ infer that the credential requester and sender are necessarily the same entity, only that, if different, they have collaborated to obtain a credential associated with the sender. - -If it is important to be able to prove definitively that the credential requester is the same user as represented in the hash (for example, in a proof of personhood claim), the credential issuer should ask the user to authenticate by signing a challenge with their control key, and include the user's unhashed DSNP DID as the `credentialSubject`. - -#### Example - -```json -{ - "@context": "https://www.w3.org/ns/activitystreams", - "type": "Note", - "content": "This rug really ties the room together.", - "mediaType": "text/plain", - "attachments": [ - { - "type": "Interaction", - "reference": "https://thebiglebowski.fandom.com/wiki/The_Rug", - "nonce": "zYAjKoNbau5KiqmHPmSxYCvn66dA1vLmwbt", - "url": [ - { - "type": "Link", - "rel": "did:dsnp:898998$ProofOfPurchase", - "href": "https://therugstore.com/proof/txn-2929123.json", - "mediaType": "application/vc+ld+json", + "mediaType": "application/vc", "hash": [ - "QmQrGdv6Ky5sJhaVdw27y4aod5pdfihDkBTxiBkRaSGJJ7" + "bciqdnu347gcfmxzbkhgoubiobphm6readngitfywktdtbdocgogop2q" ] } ] @@ -340,13 +262,3 @@ If it is important to be able to prove definitively that the credential requeste "published": "1970-01-01T00:00:00+00:00" } ``` - -The referenced credential document would include within its `credentialSubject` a matching `reference` value, as well as an `interactionId` generated by hashing the sender's 64-bit little-endian DSNP User Id and the (deserialized) `nonce`: - -``` - "credentialSubject": { - "interactionId": "...", - "reference": "https://thebiglebowski.fandom.com/wiki/The_Rug", - "transactionId": "ABC123" - } -``` diff --git a/pages/DSNP/AttributeSets.md b/pages/DSNP/AttributeSets.md index d42257ed..f02a3cb6 100644 --- a/pages/DSNP/AttributeSets.md +++ b/pages/DSNP/AttributeSets.md @@ -67,7 +67,7 @@ Attribute Set announcements are expressed using three announcement types, depend | [DSNP Content Attribute Set](./Types/DSNPContentAttributeSet.md) | 9 | [DSNP Content URI](./Identifiers.md#dsnp-content-uri) | | [External Content Attribute Set](./Types/ExternalContentAttributeSet.md) | 10 | URL and hash | -### Attestation and Interaction Attachments +### Attestation Attachments Attribute Sets associated with and controlled by a DSNP User can be referenced as [Attestation Attachments](../ActivityContent/Associated/Attachments.md#attestation) to a user's [Profile](./Types/Profile.md) document, or to an Activity Content Note object that is referenced from a Broadcast or Reply announcement. @@ -78,19 +78,13 @@ Applications enabling users to update their Profile document should take care to Attestation attachments link to credentials that identify a DSNP User as their subject. That is, the `credentialSubject.id` field should match the user's DSNP DID. -[Interaction Attachments](../ActivityContent/Associated/Attachments.md#interaction) instead identify a subject other than the DSNP User, represented by a URI. -A user can request a credential as proof of interaction with the specified subject by generating a pseudonymous Interaction Id generated by hashing their DSNP User Id with a random nonce value. -This allows users to request credentials without revealing their DSNP User Id to the issuer. -When the credential is attached, the user can prove ownership by supplying the nonce. -For example, a social media post might include provenance data attested to by a trusted third party, or a proof of purchase issued to the buyer of a product reviewed in a post. - ### On-Demand Presentation Holders of Verifiable Credentials may wish to present these only on demand rather than have a public record of the credential. Several emerging specifications are developing for this usage pattern and are outside the scope of this specification. Developers are encouraged to consider the [Verifiable Presentation Request](https://w3c-ccg.github.io/vp-request-spec/) specification. -## Public Key references +## Public Key References Both Verifiable Credential Schema documents and Verifiable Credential documents may include proof sections. @@ -101,27 +95,27 @@ A verifier must ensure that the DSNP User Id referenced this way (that is, the s Following the principle of least privilege, the key pair used to issue credentials SHOULD be different from any control keys used to authenticate transactions. -## Trust and verification +## Trust and Verification Trust in an attribute set may be assigned based on a combination of its Attribute Set Type and issuer. It is left to each application that acts as a DSNP consumer to determine which attribute sets it will trust. Trust MUST be accompanied by verification of the documents linked to an Attribute Set reference. -### Summary of verification responsibilities +### Summary of Verification Responsibilities When verifying a credential document, a consumer MUST: * Retrieve the Verifiable Credential document from the announcement or attachment link's `url` field (or, for on-demand credentials, receive the credential document by some other mechanism). -* Calculate and verify that the content hash of the Credential Document matches the value specified in the referring item (an Attribute Set Announcement's `contentHash` field, for example). +* Calculate and verify that the content hash of the credential document matches the value specified in the referring item (an Attribute Set Announcement's `contentHash` field, for example). * Verify that the credential document is well formed (it should comply with the generic JSON schema for verifiable credential documents, and include a valid combination of fields). -* Verify that the credential's `expirationDate`, if present, has not passed. +* Verify that the credential's expiration date (the `expirationDate` or `validUntil` field), if present, has not passed. * If the subject of the credential document is not a URL beginning with "`dsnp://`", verify the `subjectContentHash` by retrieving the subject URL and applying the indicated hash function. URLs beginning with "`dsnp://`" do not need a hash check as they already include a self-reflective content hash. They should, however, be checked for existence. -* Retrieve the Verifiable Credential Schema document from the URL specified in the `credentialSchema.id` field. -* Validate the Verifiable Credential Schema document against the generic JSON schema for Verifiable Credential Schema. -* Validate that the claim content in the `credentialSubject` field conforms to the JSON schema within the Verifiable Credential Schema document. -* Construct the `attributeSetType` for the document by following the rules for schemaless, unsigned, and signed schemas, and ensure it matches the declared type in the announcement or link object. Note that this MAY require verification of the issuer proof of the Verifiable Credential Schema, and potentially a chain of trust (see below). -* Verify the issuer proof, if present. +* Retrieve the schema document from the URL specified in the `credentialSchema.id` field. +* For schema of type `JsonSchemaCredential`, validate the schema document against the generic JSON schema for Verifiable Credential Schema, and validate the credential document against the JSON schema found in the Verifiable Credential Schema document's `credentialSubject.jsonSchema` property. +* For schema of type `JsonSchema`, validate that the schema document is a well formed JSON schema, then validate the credential document against the schema document. +* Construct the `attributeSetType` for the credential document by following the rules for schemaless, unsigned, or signed schemas, and ensure it matches the declared type in the announcement or link object. Note that this MAY require verification of the issuer proof of the Verifiable Credential Schema, and potentially a chain of trust (see below). +* Verify the issuer proof on the credential document, if present. Verifiers should take care that transient errors (for example, a URL being unreachable due to temporary network issues) do not lead to long-term caching of false negatives. @@ -129,20 +123,20 @@ Verifiers should take care that transient errors (for example, a URL being unrea Applications are free to make their own trust decisions, and display or incorporate Verifiable Credentials based on their `issuer`. However, in many real world scenarios, the originator of a particular type of credential may authorize agents to issue the credential, based on any number of approval or certification processes external to DSNP. -The controller of a DSNP Attribute Set Type can encode its requirements for trusted agents within a DSNP extension field of the Verifiable Credential Schema document. +When utilizing Verifiable Credential Schema documents, the originator of a DSNP Attribute Set Type can encode its requirements for trusted agents within a DSNP extension field. -To capture this requirement, DSNP uses an optional, protocol-specific `trust` key within the `dsnp` key under the `credentialSubject` section of the schema credential. -The `trust` key can contain one or both subkeys `oneOf` or `allOf`, which in turn contain a list of Attribute Set Types. +To do so, DSNP uses an optional, protocol-specific `trust` key within the `dsnp` key under the `credentialSubject` section of the schema credential. +The `trust` key can contain one or both subkeys `oneOf` or `allOf`, which in turn contain a list of Attribute Set Types, or further embedded `oneOf` or `allOf` groupings. These indicate to the consumer that the author of the credential schema requires that a credential of the defined type be trusted only if its issuer can be shown to possess Verifiable Credentials of the indicated type. In the case of `oneOf`, the verifier should check that the issuer is the subject of a Verifiable Credential conforming to at least one of the given Attribute Set Types. In the case of `allOf`, the verifier should check that the issuer is the subject of Verifiable Credentials for every given Attribute Set Type. -For example, the Worldwide Whale Foundation, identified by DSNP User Id 123456, may authorize its agents to issue credentials of type `did:dsnp:123456$CertifiedWhaleBiologist` to individuals that meet the certification standard that the Foundation defines. -The Worldwide Whale Foundation defines a second attribute set type, `did:dsnp:123456$AuthorizedWhaleBiologistCertifier` by publishing a Verifiable Schema Credential for that type, and then issues a Verifiable Credential of that type (an accreditation) to Acme Ocean Certification Lab. -Acme Ocean Certification Lab should update its DSNP Profile document to reference the accreditation document via an attachment of type `Attestation`. -Worldwide Whale Foundation then includes the `did:dsnp:123456$AuthorizedWhaleBiologistCertifier` Attribute Set Type in the `credentialSubject.trust.allOf` value of the `CertifiedWhaleBiologist` Verifiable Credential Scheme (in this example, using `oneOf` would be equivalent), generates the signature proof, and publishes the schema document. -Acme Ocean Certification Lab can now issue `did:dsnp:123456$CertifiedWhaleBiologist` credentials to users that can be verified through the trust chain. +For example, the Worldwide Whale Foundation, identified by DSNP User Id 123456, may authorize its agents, including Acme Ocean Certification Lab, to issue credentials of type `did:dsnp:123456$CertifiedWhaleBiologist` to individuals that meet the certification standard that the Foundation defines. +The Worldwide Whale Foundation defines a second attribute set type, `did:dsnp:123456$AuthorizedWhaleBiologistCertifier` by publishing a Verifiable Schema Credential for that type, and then issues a Verifiable Credential of that type (an accreditation) to Acme Ocean Certification Lab, which is then published online. +Worldwide Whale Foundation then includes the `did:dsnp:123456$AuthorizedWhaleBiologistCertifier` Attribute Set Type in the `credentialSubject.dsnp.trust.allOf` array of the `CertifiedWhaleBiologist` Verifiable Credential Schema (in this example, using `oneOf` would be equivalent), generates and attaches the signature proof, and publishes the schema document. +When Acme Ocean Certification Lab wants to issue `did:dsnp:123456$CertifiedWhaleBiologist` credentials to users, it should include the URL, attribute set type, and content hash of its accreditation credential in the `issuer.authority` array of each credential issued. +A consumer of the credential can retrieve and verify that Acme Ocean Certification Lab is an accredited issuer. ### Displaying credentials @@ -151,7 +145,6 @@ This allows the authors of attribute set types to recommend how a credential sho To allow for localizable text, a map of content language codes (following `BCP-47`, so using the same form as the HTTP `Content-Language` header) to display text can be used under the subkey `label`. - Example: ``` ... diff --git a/pages/DSNP/Types/DSNPContentAttributeSet.md b/pages/DSNP/Types/DSNPContentAttributeSet.md index e9828668..36437365 100644 --- a/pages/DSNP/Types/DSNPContentAttributeSet.md +++ b/pages/DSNP/Types/DSNPContentAttributeSet.md @@ -10,7 +10,7 @@ A DSNP Content Attribute Set Announcement is a way to create an authenticated (a | fromId | id of the user creating the Announcement | 64 bit unsigned integer | [decimal](../Serializations.md#decimal) | `UINT_64` | YES | | subject | DSNP Content URI of the attribute set subject | [DSNP Content URI](../Identifiers.md#dsnp-content-uri) | `UTF-8` | `UTF8` | YES | | url | URL for the Verifiable Credential Document | `UTF-8` | `UTF-8` | `UTF8` | no | -| contentHash | multihash-encoded hash of content stored at URL | variable length byte array | [hexadecimal](../Serializations.md#hexadecimal) | `BYTE_ARRAY` | YES | +| contentHash | [DSNP Content Hash](../Identifiers.md#dsnp-content-hash) of content | UTF-8 | [base32 multibase](../Serializations.md#base32-multibase) | `UTF8` | YES | | attributeSetType | Canonical name of attribute set type | `UTF-8` | `UTF-8` | `UTF8` | YES | | issuer | URI of issuer | `UTF-8` | `UTF-8` | `UTF8` | YES | @@ -43,11 +43,11 @@ A DSNP Content Attribute Set Announcement is a way to create an authenticated (a ### contentHash -- MUST be a [DSNP Content Hash](../Identifiers.md#dsnp-content-hash) +- MUST be a valid [DSNP Content Hash](../Identifiers.md#dsnp-content-hash) ### attributeSetType -- MUST be a valid [Attribute Set Type canonical name](../Identifiers.md#attribute-set-type-canonical-name) +- MUST be a valid [Attribute Set Type canonical name](../AttributeSets.md#canonical-naming) ### issuer diff --git a/pages/DSNP/Types/ExternalContentAttributeSet.md b/pages/DSNP/Types/ExternalContentAttributeSet.md index ab33b095..a4b0497f 100644 --- a/pages/DSNP/Types/ExternalContentAttributeSet.md +++ b/pages/DSNP/Types/ExternalContentAttributeSet.md @@ -9,9 +9,9 @@ An External Content Attribute Set Announcement is a way to create an authenticat | announcementType | Announcement Type Enum (`10`) | enum | [decimal](../Serializations.md#decimal) | `INT32` | no | | fromId | id of the user creating the Announcement | 64 bit unsigned integer | [decimal](../Serializations.md#decimal) | `UINT_64` | YES | | subject | URL of the external content | URL | `UTF-8` | `UTF8` | no | -| subjectContentHash | multihash-encoded hash of subject document | variable length byte array | [hexadecimal](../Serializations.md#hexadecimal) | `BYTE_ARRAY` | YES | +| subjectContentHash | [DSNP Content Hash](../Identifiers.md#dsnp-content-hash) of content at `subject` | UTF-8 | [base32 multibase](../Serializations.md#base32-multibase) | `UTF8` | YES | | url | URL for the Verifiable Credential document | `UTF-8` | `UTF-8` | `UTF8` | YES | -| contentHash | multihash-encoded hash of content stored at URL | variable length byte array | [hexadecimal](../Serializations.md#hexadecimal) | `BYTE_ARRAY` | YES | +| contentHash | [DSNP Content Hash](../Identifiers.md#dsnp-content-hash) of content at `url` | UTF-8 | [base32 multibase](../Serializations.md#base32-multibase) | `UTF8` | YES | | attributeSetType | Canonical name of attribute set type | `UTF-8` | `UTF-8` | `UTF8` | YES | | issuer | URI of issuer | `UTF-8` | `UTF-8` | `UTF8` | YES | @@ -35,7 +35,7 @@ Optional. If present, ### subjectContentHash -- MUST be a [DSNP Content Hash](../Identifiers.md#dsnp-content-hash) +- MUST be a valid [DSNP Content Hash](../Identifiers.md#dsnp-content-hash) ### url @@ -45,11 +45,11 @@ Optional. If present, ### contentHash -- MUST be a [DSNP Content Hash](../Identifiers.md#dsnp-content-hash) +- MUST be a valid [DSNP Content Hash](../Identifiers.md#dsnp-content-hash) ### attributeSetType -- MUST be a valid [Attribute Set Type canonical name](../Identifiers.md#attribute-set-type-canonical-name) +- MUST be a valid [Attribute Set Type canonical name](../AttributeSets.md#canonical-naming) ### issuer diff --git a/pages/DSNP/Types/UserAttributeSet.md b/pages/DSNP/Types/UserAttributeSet.md index 58bd9117..d605a513 100644 --- a/pages/DSNP/Types/UserAttributeSet.md +++ b/pages/DSNP/Types/UserAttributeSet.md @@ -10,7 +10,7 @@ A User Attribute Set Announcement is a way to create an authenticated (and, opti | fromId | id of the user creating the Announcement | 64 bit unsigned integer | [decimal](../Serializations.md#decimal) | `UINT_64` | YES | | subject | DSNP User Id of the attribute set subject | 64 bit unsigned integer | decimal | `UINT_64` | YES | | url | URL for the Verifiable Credential Document (optional) | `UTF-8` | `UTF-8` | `UTF8` | no | -| contentHash | multihash-encoded hash of content stored at URL | variable length byte array | [hexadecimal](../Serializations.md#hexadecimal) | `BYTE_ARRAY` | YES | +| contentHash | [DSNP Content Hash](../Identifiers.md#dsnp-content-hash) of content | UTF-8 | [base32 multibase](../Serializations.md#base32-multibase) | `UTF8` | YES | | attributeSetType | Canonical name of attribute set type | `UTF-8` | `UTF-8` | `UTF8` | YES | | issuer | URI of issuer | `UTF-8` | `UTF-8` | `UTF8` | YES | @@ -43,11 +43,11 @@ A User Attribute Set Announcement is a way to create an authenticated (and, opti ### contentHash -- MUST be a [DSNP Content Hash](../Identifiers.md#dsnp-content-hash) +- MUST be a valid [DSNP Content Hash](../Identifiers.md#dsnp-content-hash) ### attributeSetType -- MUST be a valid [Attribute Set Type canonical name](../Identifiers.md#attribute-set-type-canonical-name) +- MUST be a valid [Attribute Set Type canonical name](../AttributeSets.md#canonical-naming) ### issuer diff --git a/pages/VerifiableCredentials/Overview.md b/pages/VerifiableCredentials/Overview.md index d35d898a..7c274b64 100644 --- a/pages/VerifiableCredentials/Overview.md +++ b/pages/VerifiableCredentials/Overview.md @@ -1,7 +1,7 @@ # Verifiable Credentials Specification __Version pre-1.3.0__ -[Attribute Sets](../DSNP/AttributeSets.md) and [Interaction](../ActivityContent/Associated/Tag.md#interaction) tags shared via DSNP reference data documents containing Verifiable Credentials and related objects. +[Attribute Sets](../DSNP/AttributeSets.md), [Attestation](../../ActivityContent/Associated/Attachments.md#attestation) attachments, and [Interaction](../ActivityContent/Associated/Attachments.md#interaction) attachents shared via DSNP reference data documents containing Verifiable Credentials and related objects. For DSNP purposes, certain restrictions and extensions are applied to the base World Wide Web Consortium (W3C) specification documents noted below. When there are DSNP extensions, they are guaranteed to use non-colliding terms. @@ -14,8 +14,8 @@ Current usage with DSNP relies on the following specifications: | Specification | Version/Status | Relevant JSON-LD `@context` Values | | --- | --- | --- | - | Verifiable Credentials Data Model | [1.1 (W3C Recommendation)](https://www.w3.org/TR/vc-data-model-1.1) | `https://www.w3.org/2018/credentials/v1` | - | Verifiable Credential Data Integrity | [1.0 (W3C Candidate Recommendation Draft 15 March 2024)](https://www.w3.org/TR/2024/CRD-vc-data-integrity-20240315/) | `https://w3id.org/security/data-integrity/v2` | + | Verifiable Credentials Data Model | [1.1 (W3C Recommendation)](https://www.w3.org/TR/vc-data-model-1.1)
[2.0 (W3C Candidate Recommendation Draft 23 August 2024)](https://www.w3.org/TR/2024/CRD-vc-data-model-2.0-20240823/) | `https://www.w3.org/2018/credentials/v1`
`https://www.w3.org/ns/credentials/v2` | + | Verifiable Credential Data Integrity | [1.0 (W3C Candidate Recommendation Draft 3 August 2024)](https://www.w3.org/TR/2024/CRD-vc-data-integrity-20240803/) | `https://w3id.org/security/data-integrity/v2` | | Verifiable Credentials JSON Schema | [(W3C Candidate Recommendation Draft 18 December 2023)](https://www.w3.org/TR/2023/CRD-vc-json-schema-20231218/) | | | Decentralized Identifiers (DIDs) | [1.0 (W3C Recommendation 19 July 2022)](https://www.w3.org/TR/2022/REC-did-core-20220719/) | `https://www.w3.org/ns/did/v1` | @@ -26,7 +26,7 @@ DSNP compliant applications MUST support the following cryptosuites, which corre | Specification | Version/Status | Multikey codec | | --- | --- | --- | -| Data Integrity EdDSA Cryptosuites | [1.0 (W3C Candidate Recommendation Draft 03 March 2024)](https://www.w3.org/TR/2024/CRD-vc-di-eddsa-20240303/) | `ed25519-pub` | +| Data Integrity EdDSA Cryptosuites | [1.0 (W3C Candidate Recommendation Draft 16 August 2024)](https://www.w3.org/TR/2024/CRD-vc-di-eddsa-20240816/) | `ed25519-pub` | ## DSNP Usage Details @@ -34,11 +34,11 @@ DSNP compliant applications MUST support the following cryptosuites, which corre DSNP incorporates the following W3C JSON-LD types. See the individual pages for details of restrictions to and extensions on each type. -| Name | Description | +| Name | Since DSNP Version | | --- | --- | - | [Verifiable Credential](./Types/VerifiableCredential.md) | [Verifiable Credentials Data Model 1.1 (W3C Recommendation)](https://www.w3.org/TR/vc-data-model-1.1)
[Verifiable Credential Data Integrity 1.0 (W3C Candidate Recommendation Draft 15 March 2024)](https://www.w3.org/TR/2024/CRD-vc-data-integrity-20240315/) | - | [Verifiable Credential Schema](./Types/VerifiableCredentialSchema.md) | [Verifiable Credentials JSON Schema (W3C Candidate Recommendation Draft 18 December 2023)](https://www.w3.org/TR/2023/CRD-vc-json-schema-20231218/) | - | [DID](./Types/DID.md) | [Decentralized Identifiers (DIDs) v1.0 (W3C Recommendation 19 July 2022)](https://www.w3.org/TR/2022/REC-did-core-20220719/) | + | [Verifiable Credential](./Types/VerifiableCredential.md) | 1.3 | + | [Verifiable Credential Schema](./Types/VerifiableCredentialSchema.md) | 1.3 | + | [DID](./Types/DID.md) | 1.3 | ## Libraries @@ -63,12 +63,12 @@ See the individual pages for details of restrictions to and extensions on each t ## Additional Fields -Implementers may choose to support more of the relevant JSON-LD vocabularies from the specifications above as long as it does not conflict with this specification, but should note that other implementations may not recognize those additions. +DSNP application developers may choose to support more of the relevant JSON-LD vocabularies from the specifications above as long as doing so does not conflict with this specification, but should note that other conformant applications may not recognize those additions. Implementers who extend their support for Verifiable Credentials objects beyond the subset defined here do so at their own risk. ## Verifiable Presentations -[Verifiable Presentations](https://www.w3.org/TR/vc-data-model-1.1/#presentations-0) combine one or more Verifiable Credentials in a single document. +[Verifiable Presentations](https://www.w3.org/TR/2024/CRD-vc-data-model-2.0-20240823/#verifiable-presentations) combine one or more Verifiable Credentials in a single document. These might be existing Verifiable Credentials, whether or not previously published, or new Verifiable Credentials derived from non-public source credentials using methods like zero-knowledge proofs. At this time, Verifiable Presentations are not directly tied to DSNP content or announcements. However, application and service providers may be interested in implementing functionality using Verifiable Presentations with DSNP Verifiable Credentials. diff --git a/pages/VerifiableCredentials/Types/DID.md b/pages/VerifiableCredentials/Types/DID.md index d37cb6ca..1351a3c0 100644 --- a/pages/VerifiableCredentials/Types/DID.md +++ b/pages/VerifiableCredentials/Types/DID.md @@ -1,6 +1,6 @@ # DIDs -DSNP Users are referenced in Verifiable Credentials documents in compliance with the [Decentralized Identifiers v1.0](https://www.w3.org/TR/did-core/) specification. +DSNP Users are referenced in Verifiable Credentials documents via DIDs compliant with the [Decentralized Identifiers v1.0](https://www.w3.org/TR/did-core/) specification. Applications that make use of Verifiable Credentials issued by DSNP Users MUST be able to resolve DSNP User DIDs to DID documents in order to verify that signatures were created with keys controlled by that user. A DSNP DID document is effectively a document aggregating DSNP User Data. @@ -13,7 +13,7 @@ A DSNP DID uses `dsnp` (lowercase) as the method name and the DSNP User Id as th `did:dsnp:123456` This DID identifies the DSNP User with User Id 123456. -In this format, the DSNP User Id is represented in decimal form. +In this format, the DSNP User Id is serialized in decimal form with no additional punctuation. References to identifiers within a DID document are formed by appending URL fragments to a DID. For example, a Verifiable Credential might reference the public key to be used to verify a document's signature as `did:dsnp:123456#key1`, assuming the document included a `verificationMethod` with `"id": "key1"`. @@ -26,9 +26,12 @@ A DSNP DID document is a JSON-LD document representing key material associated w | --- | --- | --- | --- | --- | | `@context` | YES | Array of strings | JSON-LD @context | MUST include `"https://www.w3.org/ns/did/v1"` | | `id` | YES | String | The DID described by this document | MUST be of the form `did:dsnp:{userId}` | -| `verificationMethod` | NO | Array of Verification Method objects | Set of public keys that may be referenced from `assertionMethod` and `keyAgreement` arrays | -| `assertionMethod` | NO | Array | Set of public keys used to generate digital signatures | MUST include or reference all relevant keys present in DSNP User Data | -| `keyAgreement` | NO | Array | Set of public keys used to generate shared secrets | MUST include or reference all relevant keys present in DSNP User Data | +| `verificationMethod` | NO | Array of Verification Method objects | Set of public keys that may be referenced from `assertionMethod`, `authentication`, and `keyAgreement` arrays | +| `assertionMethod` | NO | Array | Set of public keys used to generate digital signatures | MUST include or reference all relevant keys present in DSNP User Data `assertionMethodPublicKeys` | +| `authentication` | NO | Array | Set of public keys used as DSNP control keys | MAY include or reference any keys used as control keys | +| `keyAgreement` | NO | Array | Set of public keys used to generate shared secrets | MUST include or reference all relevant keys present in DSNP User Data `keyAgreementPublicKeys` | + +Additional properties defined in the DID specification MAY be present. ### Public Key Representation diff --git a/pages/VerifiableCredentials/Types/VerifiableCredential.md b/pages/VerifiableCredentials/Types/VerifiableCredential.md index cd6a149b..335765ea 100644 --- a/pages/VerifiableCredentials/Types/VerifiableCredential.md +++ b/pages/VerifiableCredentials/Types/VerifiableCredential.md @@ -1,6 +1,6 @@ # Verifiable Credential -Credentials should conform to the [Verifiable Credentials Data Model 1.1](https://www.w3.org/TR/vc-data-model-1.1/), expressed as JSON-LD. +Credentials should conform to the [Verifiable Credentials Data Model 1.1](https://www.w3.org/TR/vc-data-model-1.1/) or [Verifiable Credentials Data Model 2.0](https://www.w3.org/TR/vc-data-model-2.0/), expressed as [JSON-LD](https://json-ld.org/). The fields noted below consist only of those with requirements or semantics that differ from the underlying specification. ## JSON-LD Contexts @@ -9,7 +9,7 @@ The following JSON-LD context values are valid for use with DSNP: | Object | `@context` | | --- | --- | -| Verifiable Credential | `https://www.w3.org/2018/credentials/v1` | +| Verifiable Credential | `https://www.w3.org/2018/credentials/v1`
`https://www.w3.org/ns/credentials/v2` | ## Verifiable Credential Document @@ -17,12 +17,12 @@ A DSNP Verifiable Credential JSON document specializes the following fields: | Property | Required | JSON Type | Description | Restrictions | | --- | --- | --- | --- | --- | -| `@context` | YES | Array of strings | JSON-LD @context | MUST include `"https://www.w3.org/2018/credentials/v1"` | +| `@context` | YES | Array of strings | JSON-LD @context | MUST include `"https://www.w3.org/2018/credentials/v1"` or `"https://www.w3.org/ns/credentials/v2"` | | `type` | YES | Array of strings | Type of credential | MUST contain `"VerifiableCredential"` per specification; if a `credentialSchema` is present, MUST also contain a string matching the referenced JSON Schema's `title`. | -| `issuer` | YES | String or Object | DID or object identifying credential issuer | See below | -|`credentialSubject` | YES | Object | Object identifying subject and claim | See below | -| `credentialSchema` | no | Object | Reference to schema for this credential | See below | -| `proof` | no | Object | Cryptographic proof of authorship by `issuer` | See below | +| `issuer` | YES | String or Object | DID or object identifying credential issuer | See [Issuer](#issuer) | +|`credentialSubject` | YES | Object | Object identifying subject and claim | See [Credential Subject](#credential-subject) | +| `credentialSchema` | no | Object | Reference to schema for this credential | See [Credential Schema](#credential-schema) | +| `proof` | no | Object | Cryptographic proof of authorship by `issuer` | See [Proof](#proof) | ### Issuer @@ -36,15 +36,17 @@ In the object form, the issuer may optionally include references to its own cred | Property | Required | JSON Type | Description | Restrictions | | --- | --- | --- | --- | --- | | `id` | YES | String | DID of issuer | Must be a [DSNP DID](./DID.md) | -| `authority` | no | Array | List of relevant credentials with issuer as subject | See below | +| `authority` | no | Array | List of relevant credentials with issuer as subject | See [Authority](#authority) | -Objects in the `authority` array MUST have the following properties: +#### Authority + +Objects in the `issuer.authority` array MUST have the following properties: | Property | Required | JSON Type | Description | Restrictions | | --- | --- | --- | --- | --- | | `id` | YES | String | URL of Verifiable Credential | MUST be a DSNP Verifiable Credential | | `rel` | YES | String | The linked credential's attribute set type | MUST be a DSNP [Attribute Set Type](../../DSNP/AttributeSets.md#attribute-set-type) corresponding to the referenced credential document | -| `hash` | YES | Array | Array of hashes for linked content validation | MUST include at least one [supported hash](../../ActivityContent/Associated/Hash.md#supported-algorithms) | +| `digestMultibase` | YES | Array | Array of hashes for linked content validation | MUST include at least one [supported hash](../../ActivityContent/Associated/Hash.md#supported-algorithms) | Examples: @@ -59,15 +61,15 @@ Examples: { "id": "https://mydsnpcreds.net/86420-fp", "rel": "did:dsnp:123456$FairTradeProducer", - "hash": [ - "QmQrGdv6Ky5sJhaVdw27y4aod5pdfihDkBTxiBkRaSGJJ7" + "digestMultibase": [ + "bciqdnu347gcfmxzbkhgoubiobphm6readngitfywktdtbdocgogop2q" ] }, { "id": "https://mydsnpcreds.net/86420-ap", "rel": "did:dsnp:123456$AppleProducer", - "hash": [ - "2Drjgb4a8eC4XheBKCBcbAcaVdEWcKjMbCSZ2L2c9CQs4x98jf" + "digestMultibase": [ + "bdyqhwoxp2mc6oyaqpqyd2fvaxralslk32ggazv6nxpp342iec6652tq" ] } ] @@ -86,7 +88,7 @@ The remainder of the contents of the `credentialSubject` value MUST conform to t | Property | Required | JSON Type | Description | Restrictions | | --- | --- | --- | --- | --- | -| `id` | YES | String | URL of schema document | MUST reference a [DSNP Verifiable Credential Schema](./VerifiableCredentialSchema.md) | +| `id` | YES | String | URL of schema document | If `type` is `JsonSchemaCredential`, MUST reference a [DSNP Verifiable Credential Schema](./VerifiableCredentialSchema.md) | ### Proof @@ -116,7 +118,7 @@ The remainder of the contents of the `credentialSubject` value MUST conform to t "id": "https://dsnp.org/schema/examples/vehicle_owner.json" }, "credentialSubject": { - "id": "did:dsnp:999999", + "id": "dsnp://999999", "make": "DeLorean", "model": "DMC-12", "year": 1981 diff --git a/pages/VerifiableCredentials/Types/VerifiableCredentialSchema.md b/pages/VerifiableCredentials/Types/VerifiableCredentialSchema.md index f0b47f74..b57800c4 100644 --- a/pages/VerifiableCredentials/Types/VerifiableCredentialSchema.md +++ b/pages/VerifiableCredentials/Types/VerifiableCredentialSchema.md @@ -14,8 +14,8 @@ A schema credential specializes the meaning of the following fields: | Property | Required | JSON Type | Description | Restrictions | | --- | --- | --- | --- | --- | | `type` | YES | Array of strings | Type of credential | MUST contain the strings `"VerifiableCredential"` and `"JsonSchemaCredential"` | -|`credentialSubject` | YES | Object | Object containing JSON schema and DSNP extensions | See below | -| `credentialSchema` | YES | Object | Metaschema defining JSON Schema types | See below for required contents | +|`credentialSubject` | YES | Object | Object containing JSON schema and DSNP extensions | See [Credential Subject](#credential-subject) | +| `credentialSchema` | YES | Object | Metaschema defining JSON Schema types | See [Credential Schema](#credential-schema) | ### Credential Schema The required `credentialSchema` object MUST follow the specification and contain: @@ -35,8 +35,8 @@ A DSNP Verifiable Credential Schema document's `credentialSubject` object uses t | Property | Required | JSON Type | Description | Restrictions | | --- | --- | --- | --- | --- | | `type` | YES | String | Type of subject matter | MUST be `JsonSchema` | -| `jsonSchema` | YES | Object | Embedded JSON Schema object | See below | -| `dsnp` | NO | Object | DSNP extension object | See below | +| `jsonSchema` | YES | Object | Embedded JSON Schema object | See [JSON Schema](#json-schema) | +| `dsnp` | NO | Object | DSNP extension object | See [DSNP Extensions](#dsnp-extensions) | #### JSON Schema @@ -49,7 +49,7 @@ The JSON Schema object is formed as follows: The remainder of the schema object should be interpreted as per the relevant JSON schema specification. -##### Valid DSNP JSON Schema versions +##### Valid DSNP JSON Schema Versions DSNP applications MUST support the following JSON Schema versions: @@ -164,8 +164,8 @@ The above example might be translated as "A credential conforming to this schema }, "trust": { "oneOf": [ - "did:dsnp:123456$CarDealership", - "did:dsnp:123456$TaxOffice" + "did:dsnp:123456$AuthorizedCarDealership", + "did:dsnp:123456$OfficialTaxOffice" ] } }