Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add revoked and expires properties to JsonWebKey context. #184

Merged
merged 5 commits into from
Sep 2, 2023
+56 −13
Merged

Add revoked and expires properties to JsonWebKey context. #184

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
e3fef8e
Add revoked and expires properties to JsonWebKey context.
msporny Aug 26, 2023
aded2d6
Add `expires` property to verification method properties list.
msporny Aug 26, 2023
2d1726e
Re-anchor definition for expires (on proof and verification method).
msporny Aug 26, 2023
b298c49
Simplify grammar for `expires` property.
msporny Sep 2, 2023
c4aede2
Clarify VM revocation/expiration vs. VC revocation.
msporny Sep 2, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions contexts/jwk/v1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,14 @@
"@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"
Expand Down
53 changes: 43 additions & 10 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -614,10 +614,10 @@ <h3>Proofs</h3>
specified as an [[XMLSCHEMA11-2]] `dateTimeStamp` string.
</dd>

<dt><dfn class="lint-ignore">expires</dfn></dt>
<dt id="defn-proof-expires">expires</dt>
<dd>
An OPTIONAL property that conveys the date and time that a proof expires and that, if present, MUST be
specified as an [[XMLSCHEMA11-2]] `dateTimeStamp` string.
The `expires` property is OPTIONAL. If present, it MUST be an [[XMLSCHEMA11-2]]
`dateTimeStamp` string specifying when the proof expires.
</dd>

<dt id="defn-domain">domain</dt>
Expand Down Expand Up @@ -995,14 +995,29 @@ <h2>Verification Methods</h2>
<dd>
The value of the `controller` property MUST be a <a
data-cite="INFRA#string">string</a> that conforms to the [[URL]] syntax.
</dd>
<dt id="defn-vm-expires">expires</dt>
<dd>
The `expires` property is OPTIONAL. It is set, in advance, by the
<a>controller</a> of a <a>verification method</a> to signal when that method
can no longer be used for verification purposes. If provided, it MUST be an
[[XMLSCHEMA11-2]] `dateTimeStamp` string specifying when the
<a>verification method</a> SHOULD cease to be used. Once the value is set, it is
not expected to be updated, and systems depending on the value are expected to
not verify any proofs associated with the <a>verification method</a> at or after
the time of expiration.
</dd>
<dt><dfn class="lint-ignore">revoked</dfn></dt>
<dd>
The `revoked` property is OPTIONAL. If provided, it MUST be an [[XMLSCHEMA11-2]]
The `revoked` property is OPTIONAL. It is set by the <a>controller</a> of a
<a>verification method</a> to signal when that method is to no longer to be used
for verification purposes, such as after a security compromise of the
<a>verification method</a>. If provided, it MUST be an [[XMLSCHEMA11-2]]
`dateTimeStamp` string specifying when the <a>verification method</a>
SHOULD cease to be used. Once the value is set, it is not expected to be updated, and
systems depending on the value are expected to not verify any proofs associated
with the <a>verification method</a> at or after the time of revocation.
SHOULD cease to be used. Once the value is set, it is not expected to be
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@msporny this seems like a great places to remove confusion over "verification method revocation" and "credential revocation"... we get this question a LOT... and it would nice to be able to share a note to a comment regarding this. something like:

verification method revocation time information can reveal information about a controller. credential status do not include timing information, because it can degrade the privacy characteristics of some status lists... there is not formal relationship between these concepts, etc....

Copy link
Member Author

@msporny msporny Aug 28, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, I'll add that text to that effect in a future update to this PR.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added in c4aede2.

updated, and systems depending on the value are expected to not verify any
proofs associated with the <a>verification method</a> at or after the time of
revocation.
</dd>
</dl>
</dd>
Expand Down Expand Up @@ -1910,8 +1925,8 @@ <h2>Relationship to Verifiable Credentials</h2>
Document authors and implementers are advised to understand the difference
between the validity period of a <a href="#proofs">proof</a>, which is expressed
using the <a href="#dfn-created">`created`</a> and <a
href="#dfn-expires">`expires`</a> properties, and the validity period of a
<a data-cite="?VC-DATA-MODEL-2.0#dfn-credential">credential</a>,
href="#defn-proof-expires">`expires`</a> properties, and the validity period of
a <a data-cite="?VC-DATA-MODEL-2.0#dfn-credential">credential</a>,
which is expressed using the
<a data-cite="?VC-DATA-MODEL-2.0#defn-validFrom">`validFrom`</a> and
<a data-cite="?VC-DATA-MODEL-2.0#defn-validUntil">`validUntil`</a> properties.
Expand All @@ -1920,7 +1935,8 @@ <h2>Relationship to Verifiable Credentials</h2>
<a href="#proofs">proof</a>, it is important to ensure that the time of interest
(which might be the current time or any other time) is within the
validity period for the proof (that is, between
<a href="#dfn-created">`created`</a> and <a href="#dfn-expires">`expires`</a> ).
<a href="#dfn-created">`created`</a> and
<a href="#defn-proof-expires">`expires`</a> ).
When <a data-cite="?VC-DATA-MODEL-2.0#validation">validating</a> a
<a>verifiable credential</a>, it is important to ensure that the time of
interest is within the validity period for the
Expand All @@ -1933,6 +1949,23 @@ <h2>Relationship to Verifiable Credentials</h2>
<a data-cite="?VC-DATA-MODEL-2.0#dfn-credential">credential</a>, might result
in accepting data that ought to have been rejected.
</p>

<p>
Finally, implementers are also urged to understand that there is a difference
between the <a href="#dfn-revoked">revocation time</a> and
<a href="#defn-vm-expires">expiration time</a> for a <a>verification method</a>,
and the revocation information associated with a <a>verifiable credential</a>.
The <a href="#dfn-revoked">revocation time</a> and
<a href="#defn-vm-expires">expiration time</a> for a <a>verification method</a>
are expressed using the `revocation` and `expires` properties, respectively, and
are related to events such as a private key being compromised or expiring and
can provide timing information which might reveal details about a controller
such as their security practices or when they might have been compromised. The
revocation information for a <a>verifiable credential</a> is expressed using
the `credentialStatus` property and is related to events such as an individual
losing the privilege that is granted by the <a>verifiable credential</a> and
does not provide timing information, which enhances privacy.
</p>
</section>

<section>
Expand Down
8 changes: 5 additions & 3 deletions vocab/security/vocabulary.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -207,9 +207,11 @@ property:
range: xsd:dateTime

- id: expires
label: Proof expiration time
defined_by: https://www.w3.org/TR/vc-data-integrity/#dfn-expires
domain: sec:Proof
label: Expiration time for a proof or verification method
defined_by: https://www.w3.org/TR/vc-data-integrity/#defn-proof-expires
domain:
- sec:Proof
- sec:VerificationMethod
Comment on lines +212 to +214
Copy link
Member

@TallTed TallTed Sep 1, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

According to @iherman in w3c/vc-data-model#1262 (comment)

the domain expired is set to both (i.e., the union) of Proof and VerificationMethod.

Note that expires rdfs:domain Proof, VerificationMethod does not set rdfs:domain to the union of Proof and VerificationMethod, but rather to their intersection; that is, any entity with the property expires must be both a Proof and a VerificationMethod.

For the apparently intended union, where an entity with the property expires could be either a Proof or a VerificationMethod, rdfs:domain must be changed to schema:domainIncludes.

Suggested change
domain:
- sec:Proof
- sec:VerificationMethod
domainIncludes:
- sec:Proof
- sec:VerificationMethod

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@iherman would have to add this to the yml2vocab tool, as I don't think it has a domainIncludes property? Thoughts, @iherman?

range: xsd:dateTime

- id: nonce
Expand Down