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 context integrity approach for VC-JWTs #90

Closed
wants to merge 4 commits into from
Closed

Add context integrity approach for VC-JWTs #90

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
cbfe1c7
chore: add context integrity approach for VC-JWTs
mprorock May 30, 2023
3ea77a6
fix: correct date in example
mprorock May 30, 2023
2421133
chore: apply feedback from code review and clarify a few items
mprorock May 30, 2023
2b724aa
Apply suggestions from code review
mprorock Jun 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
130 changes: 100 additions & 30 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -363,36 +363,106 @@ <h2>Security Considerations</h2>
It is important to carefully consider these factors to ensure the security
and integrity of Verifiable Credentials when implemented using JWTs.
</p>
<p>
When implementing VC-JWTs, it is essential to address all security issues relevant
to broad cryptographic applications. This especially includes protecting the user's
asymmetric private and symmetric secret keys, as well as employing countermeasures
against various attacks. Failure to adequately address these issues could compromise
the security and integrity of Verifiable Credentials, potentially leading to unauthorized
access, modification, or disclosure of sensitive information.
</p>
<p>
Implementers are advised to follow best practices and established cryptographic standards to ensure
the secure handling of keys and other sensitive data.
Additionally, conduct regular security assessments and audits to identify and
address any vulnerabilities or threats.
</p>
<p>
Follow all security considerations outlined in [[rfc7515]] and [[rfc7519]].
</p>
<p>
When utilizing JSON-LD, take special care around remote retrieval of contexts and follow the
additional security considerations noted in [[json-ld11]].
</p>
<p>
As noted in [[rfc7515]] when utilizing JSON [[rfc7159]], strict validation is a security
requirement. If malformed JSON is received, it may be impossible to reliably interpret the
producer's intent, potentially leading to ambiguous or exploitable situations.
To prevent these risks, it is essential to use a JSON parser that strictly validates the syntax
of all input data. It is essential that any JSON inputs that do not conform to the JSON-text syntax defined in [[rfc7159]]
be rejected in their entirety by JSON parsers. Failure to reject invalid input could compromise
the security and integrity of Verifiable Credentials.
</p>
<section>
<h2>General Considerations</h2>
<p>
When implementing VC-JWTs, it is essential to address all security issues relevant
to broad cryptographic applications. This especially includes protecting the user's
asymmetric private and symmetric secret keys, as well as employing countermeasures
against various attacks. Failure to adequately address these issues could compromise
the security and integrity of Verifiable Credentials, potentially leading to unauthorized
access, modification, or disclosure of sensitive information.
</p>
<p>
Implementers are advised to follow best practices and established cryptographic standards to ensure
the secure handling of keys and other sensitive data.
Additionally, conduct regular security assessments and audits to identify and
address any vulnerabilities or threats.
</p>
<p>
Follow all security considerations outlined in [[rfc7515]] and [[rfc7519]].
</p>
<p>
When utilizing JSON-LD, take special care around remote retrieval of contexts and follow the
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
When utilizing JSON-LD, take special care around remote retrieval of contexts and follow the
When using JSON-LD, take special care around remote retrieval of contexts and follow the

additional security considerations noted in [[json-ld11]].
</p>
<p>
As noted in [[rfc7515]] when utilizing JSON [[rfc7159]], strict validation is a security
requirement. If malformed JSON is received, it may be impossible to reliably interpret the
Comment on lines +390 to +391
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
As noted in [[rfc7515]] when utilizing JSON [[rfc7159]], strict validation is a security
requirement. If malformed JSON is received, it may be impossible to reliably interpret the
As noted in [[rfc7515]], strict validation is a security requirement when using
JSON [[rfc7159]]. If malformed JSON is received, it may be impossible to reliably interpret the

producer's intent, potentially leading to ambiguous or exploitable situations.
To prevent these risks, it is essential to use a JSON parser that strictly validates the syntax
of all input data. It is essential that any JSON inputs that do not conform to the JSON-text syntax defined in [[rfc7159]]
be rejected in their entirety by JSON parsers. Failure to reject invalid input could compromise
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
be rejected in their entirety by JSON parsers. Failure to reject invalid input could compromise
be rejected in their entirety by JSON parsers. Failure to reject such invalid input could compromise

the security and integrity of Verifiable Credentials.
</p>
</section>
<section>
<h2>Context Integrity</h2>
<p>
In some cases it is desirable to know that the contents of the
context(s) utilized in the verifiable credential are the same as
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
context(s) utilized in the verifiable credential are the same as
context(s) used in the verifiable credential are the same as

used by both the issuer and verifier.
</p>
<p>
To validate that a context included in a Verifiable Credential is
the same at verification time as at issuing time an implementer
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
the same at verification time as at issuing time an implementer
the same at verification time as at issuing time, an implementer

MAY include a property named <code>contextIntegrity</code> that
stores an array of objects that describe additional integrity
metadata about each context used by the VC. If
<code>contextIntegrity</code>
is present there MUST be an object in the array for each remote
context.
</p>
<p>
Each object in the
<code>contextIntegrity</code> array MUST contain the following:
the URL to the context named <code>context</code>, a
mprorock marked this conversation as resolved.
Show resolved Hide resolved
<code>timestamp</code>
that indicates the time at which the hash was computed, the
<code>hash</code>
of the context, and the <code>method</code> which indicates what
Comment on lines +419 to +423
Copy link
Member

Choose a reason for hiding this comment

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

It might be better to use an <ul> for these. If making that switch, there should be no punctuation at the end of any list item (i.e., delete the semicolons here as well as the . after Registry).

Suggested change
the URL to the context named <code>context</code>, a
<code>timestamp</code>
that indicates the time at which the hash was computed, the
<code>hash</code>
of the context, and the <code>method</code> which indicates what
the URL to the context named <code>context</code>; a
<code>timestamp</code>
that indicates the time at which the hash was computed; the
<code>hash</code>
of the context; and the <code>method</code> which indicates what

hashing algorithm was used as listed as the 'Hash Name String'
property from the <a
href="https://www.iana.org/assignments/named-information/named-information.xhtml">IANA
Named Information Hash Algorithm Registry</a>.
mprorock marked this conversation as resolved.
Show resolved Hide resolved
The <code>timestamp</code> property MUST be a string value of an
[[XMLSCHEMA11-2]] combined date-time string. An implementer may
include other fields in each object.
</p>
<p>
Implementers should consult appropriate sources, such as the <a
href="https://www.iana.org/assignments/named-information/named-information.xhtml">IANA
Named Information Hash Algorithm Registry</a> to ensure that they
are chosing a current and reliable hash algorithm. At the time of
this writing `sha-256` should be considered the minimum strength
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
this writing `sha-256` should be considered the minimum strength
this writing, `sha-256` is considered the minimum strength

hash algorithm for use by implemnters.
</p>
<p class="note">
If at a later date subresource integrity as defined in [[SRI]] is
adopted into the [[JSON-LD]] specification as noted in that
specifications <a
href="https://www.w3.org/TR/json-ld11/#security">current security
considerations</a> of that specification, this hash in the VC can
serve as an additional check towards ensuring that a cached
context used when issuing the VC matches the remote resource.
Comment on lines +441 to +447
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
If at a later date subresource integrity as defined in [[SRI]] is
adopted into the [[JSON-LD]] specification as noted in that
specifications <a
href="https://www.w3.org/TR/json-ld11/#security">current security
considerations</a> of that specification, this hash in the VC can
serve as an additional check towards ensuring that a cached
context used when issuing the VC matches the remote resource.
If subresource integrity as defined in [[SRI]] is adopted into
the [[JSON-LD]] specification at a later date, as noted in the
<a href="https://www.w3.org/TR/json-ld11/#security">current security
considerations</a> of that specification, this hash in the VC can
serve as an additional check towards ensuring that a cached
context used when issuing the VC matches the remote resource.

</p>
<p>
<aside
class="example"
title="context integrity"
>
<p>An example of a context integrity object</p>
mprorock marked this conversation as resolved.
Show resolved Hide resolved
<pre>
"contextIntegrity": [{
"context":"https://example.org/v1/context",
"timestamp": "2020-01-01T19:23:24Z",
"hash": "0c63a75b845e4f7d01107d852e4c2485c51a50aaaa94fc61995e71bbee983a2ac3713831264adb47fb6bd1e058d5f004",
"method": "sha3-384"
}]
</pre>
</aside>
</p>
</section>
</section>

<section class="appendix informative">
Expand Down