From cb5b9226de932bfc4346017799ef5974028a68a3 Mon Sep 17 00:00:00 2001 From: Ivan Herman Date: Mon, 16 Sep 2024 16:50:19 +0200 Subject: [PATCH] Revise and clarify Context and Vocabulary section. Co-authored-by: Michael Jones Co-authored-by: Dave Longley Co-authored-by: Manu Sporny --- context/v1.jsonld | 103 ++++++++++++++++ index.html | 291 +++++++++++++++++++++------------------------- 2 files changed, 237 insertions(+), 157 deletions(-) create mode 100644 context/v1.jsonld diff --git a/context/v1.jsonld b/context/v1.jsonld new file mode 100644 index 0000000..9160835 --- /dev/null +++ b/context/v1.jsonld @@ -0,0 +1,103 @@ +{ + "@context": { + "@protected": true, + "id": "@id", + "type": "@type", + + "alsoKnownAs": { + "@id": "https://w3id.org/security#alsoKnownAs", + "@type": "@id", + "@container": "@set" + }, + "assertionMethod": { + "@id": "https://w3id.org/security#assertionMethod", + "@type": "@id", + "@container": "@set" + }, + "authentication": { + "@id": "https://w3id.org/security#authenticationMethod", + "@type": "@id", + "@container": "@set" + }, + "capabilityDelegation": { + "@id": "https://w3id.org/security#capabilityDelegationMethod", + "@type": "@id", + "@container": "@set" + }, + "capabilityInvocation": { + "@id": "https://w3id.org/security#capabilityInvocationMethod", + "@type": "@id", + "@container": "@set" + }, + "controller": { + "@id": "https://w3id.org/security#controller", + "@type": "@id" + }, + "keyAgreement": { + "@id": "https://w3id.org/security#keyAgreementMethod", + "@type": "@id", + "@container": "@set" + }, + "verificationMethod": { + "@id": "https://w3id.org/security#verificationMethod", + "@type": "@id", + "@container": "@set" + }, + "Multikey": { + "@id": "https://w3id.org/security#Multikey", + "@context": { + "@protected": true, + "id": "@id", + "type": "@type", + "controller": { + "@id": "https://w3id.org/security#controller", + "@type": "@id" + }, + "revoked": { + "@id": "https://w3id.org/security#revoked", + "@type": "http://www.w3.org/2001/XMLSchema#dateTime" + }, + "expires": { + "@id": "https://w3id.org/security#expiration", + "@type": "http://www.w3.org/2001/XMLSchema#dateTime" + }, + "publicKeyMultibase": { + "@id": "https://w3id.org/security#publicKeyMultibase", + "@type": "https://w3id.org/security#multibase" + }, + "secretKeyMultibase": { + "@id": "https://w3id.org/security#secretKeyMultibase", + "@type": "https://w3id.org/security#multibase" + } + } + }, + "JsonWebKey": { + "@id": "https://w3id.org/security#JsonWebKey", + "@context": { + "@protected": true, + "id": "@id", + "type": "@type", + "controller": { + "@id": "https://w3id.org/security#controller", + "@type": "@id" + }, + "revoked": { + "@id": "https://w3id.org/security#revoked", + "@type": "http://www.w3.org/2001/XMLSchema#dateTime" + }, + "expires": { + "@id": "https://w3id.org/security#expiration", + "@type": "http://www.w3.org/2001/XMLSchema#dateTime" + }, + "publicKeyJwk": { + "@id": "https://w3id.org/security#publicKeyJwk", + "@type": "@json" + }, + "secretKeyJwk": { + "@id": "https://w3id.org/security#secretKeyJwk", + "@type": "@json" + } + } + } + } +} diff --git a/index.html b/index.html index 59f1741..135d2dd 100644 --- a/index.html +++ b/index.html @@ -970,7 +970,7 @@

Verification Material

-
+

Multikey

The Multikey data model is a specific type of [=verification method=] that @@ -1142,7 +1142,7 @@

Multikey

-
+

JsonWebKey

The JSON Web Key (JWK) data model is a specific type of [=verification method=] @@ -2301,176 +2301,153 @@

Processing Errors

Contexts and Vocabularies

-

-This section lists cryptographic hash values that might change during the -Candidate Recommendation phase based on implementer feedback that requires -the referenced files to be modified. -

-

-Implementations that perform JSON-LD processing MUST treat the following -JSON-LD context URLs as already resolved, where the resolved document matches -the corresponding hash values below: -

- - - - - - - - - - - - - - - - - - -
URL, Media Type, and Content Digest
-URL: -https://w3id.org/security/data-integrity/v2 (application/ld+json)
-SHA2-256 Digest: - -
-URL: -https://w3id.org/security/multikey/v1 (application/ld+json)
-SHA2-256 Digest: - -
-URL: -https://w3id.org/security/jwk/v1 (application/ld+json)
-SHA2-256 Digest: - -
- -

-The security vocabulary terms that the JSON-LD contexts listed above resolve -to are in the https://w3id.org/security# -namespace. That is, all security terms in this vocabulary are of the form -`https://w3id.org/security#TERM`, where `TERM` is the name of a term. -

- -

-Implementations that perform RDF processing MUST treat the following -JSON-LD vocabulary URL as already resolved, where the resolved document matches -the corresponding hash values below. -

- -

-When dereferencing the -https://w3id.org/security# URL, -the data returned depends on HTTP content negotiation. These are as follows: +

+ This section lists cryptographic hash values that might change during the + Candidate Recommendation phase based on implementer feedback that requires + the referenced files to be modified.

- - - - - - - - - - - - - - - - - -
URL, Media Type, and Content Digest
-URL: -https://w3id.org/security (application/ld+json)
-SHA2-256 Digest: -
-URL: -https://w3id.org/security (text/turtle)
-SHA2-256 Digest: -
-URL: -https://w3id.org/security (text/html)
-SHA2-256 Digest: - -
- -

-It is possible to confirm the digests listed above by running the following -command from a modern Unix command interface line: -`curl -sL -H "Accept: <MEDIA_TYPE>" <DOCUMENT_URL> | openssl dgst -sha256`. -

+
+

Vocabulary

+

+ The terms defined in this specification are also part of the + RDF vocabulary namespace [[RDF-CONCEPTS]] + https://w3id.org/security#. + For any `TERM`, the relevant URL is of the form + `https://w3id.org/security#TERM` or `https://w3id.org/security#TERMmethod`. + Implementations that use RDF processing and rely on this specification MUST use these URLs. +

-

-Authors of application-specific vocabularies and specifications SHOULD ensure -that their JSON-LD context and vocabulary files are permanently cacheable -using the approaches to caching described above or a functionally equivalent -mechanism. -

+

+ When dereferencing the + https://w3id.org/security# URL, + the media type of the data that is returned depends on HTTP content negotiation. These are as follows: +

-

-Implementations MAY load application-specific JSON-LD context files from the -network during development, but SHOULD permanently cache JSON-LD context files -used in [=conforming documents=] in production settings to increase their -security and privacy characteristics. Caching goals MAY be achieved through -approaches such as those described above or functionally equivalent mechanisms. -

-

-Some applications, such as digital wallets, that are capable of holding arbitrary -verifiable credentials or other data-integrity-protected documents, from -any issuer and using any contexts, might need to be able to load externally -linked resources, such as JSON-LD context files, in production settings. This is -expected to increase user choice, scalability, and decentralized upgrades in the -ecosystem over time. Authors of such applications are advised to read the -security and privacy sections of this document for further considerations. -

+ + + + + + + + + + + + + + + + + + + + + +
Media TypeDescription and Hash
+ application/ld+json + + The vocabulary in JSON-LD format [[?JSON-LD11]].
+ + SHA2-256 Digest: +
+ text/turtle + + The vocabulary in Turtle format [[?TURTLE]].
+ + SHA2-256 Digest: +
+ text/html + + The vocabulary in HTML+RDFa Format [[?HTML-RDFA]].
+ + + SHA2-256 Digest: +
-

-For further information regarding processing of JSON-LD contexts and -vocabularies, see Verifiable -Credentials v2.0: Base Context and -Verifiable Credentials v2.0: Vocabularies. -

+

+ It is possible to confirm the cryptographic digests above by running + a command like the following (replacing `<MEDIA_TYPE>` and `<DOCUMENT_URL>` + with the appropriate values) through a modern UNIX-like OS command line interface: + `curl -sL -H "Accept: <MEDIA_TYPE>" <DOCUMENT_URL> | openssl dgst -sha256` +

+
-

Context Injection

- +

JSON-LD context

-The `@context` property is used by implementations that employ JSON-LD to ensure that implementations are using the -same semantics when terms in this specification are processed. For example, this -can be important when properties like `type` are processed and its values, such -as `DataIntegrityProof`, are used. + Implementations that perform JSON-LD processing MUST treat the following + JSON-LD context URL as already resolved, where the resolved document matches + the corresponding hash value below:

+ + + + + + + + + +
Context URL and Hash
+ URL: https://www.w3.org/ns/controller/v1
+ SHA2-256 Digest:
+
+

-If an `@context` property is not provided in a document that is being secured or -verified, or any Data Integrity terms used in the document are not mapped by -existing values in the `@context` property, implementations using JSON-LD MUST inject or add -an `@context` property with a value of -`https://www.w3.org/ns/controller/v1`. + It is possible to confirm the cryptographic digests listed above by running a + command like the following through a modern UNIX-like OS command line interface: `curl -sL -H + "Accept: application/ld+json" https://www.w3.org/ns/controller/v1 | openssl dgst -sha256`

-Context injection is expected to be unnecessary sometimes, such as when the Verifiable -Credential Data Model v2.0 context (`https://www.w3.org/ns/credentials/v2`) -exists as a value in the `@context` property, as that context maps all of the -necessary Data Integrity terms that were previously mapped by -`https://w3id.org/security/data-integrity/v2`. + The security vocabulary terms that the JSON-LD contexts listed above resolve + to are in the https://w3id.org/security# + namespace. See also for further details. +

+ +

+ Applications or specifications may define mappings to the + vocabulary URLs using their own JSON-LD contexts. For example, these mappings are part + of the `https://w3id.org/security/data-integrity/v2` context, + defined by the [[[?VC-DATA-INTEGRITY]]] specification, or the `https://www.w3.org/ns/did/v1` context, + defined by the [[[?DID-CORE]]] specification.

+ +
+

Context injection

+

+ The `@context` property is used to ensure that implementations are using the + same semantics when terms in this specification are processed. For example, this + can be important when properties like `authentication` are processed and its + value, such as `Multikey` or `JsonWebKey`, are used. +

+ +

+ When an application is processing a [=controller document=], if an `@context` + property is not provided in the document or the terms used in the document are + not mapped by existing values in the `@context` property, implementations MUST inject + or append an `@context` property with a value of + `https://www.w3.org/ns/controller/v1` or one or more contexts with at least the + same declarations, such as the Decentralized Identifier v1.1 context + (`https://www.w3.org/ns/did/v1`). +

+ +

+ Implementations that do not intend to use JSON-LD MAY choose to not include an + `@context` declaration at the top-level of the document. +

+