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

Request media type for 1.1 vc-jwt claim set #40

Merged
merged 4 commits into from
Jan 25, 2023
Merged

Request media type for 1.1 vc-jwt claim set #40

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
25b67a5
Request media type for 1.1 vc-jwt claim set
OR13 Jan 16, 2023
e4784a0
Update index.html
OR13 Jan 17, 2023
e280be2
Update index.html
OR13 Jan 20, 2023
80e807f
Apply resolution from WG call
OR13 Jan 25, 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
47 changes: 47 additions & 0 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -525,5 +525,52 @@ <h2>Privacy Considerations</h2>
<section>
<h2>Security Considerations</h2>
</section>

<section class="appendix informative">
<h2>IANA Considerations</h2>
<section id="media-type">
<h2>The <code>application/credential-1.1+json</code> Media Type</h2>
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
<h2>The <code>application/credential-1.1+json</code> Media Type</h2>
<h2>The <code>application/credential-1.1+jose+json</code> Media Type</h2>

If this PR is about JWT claim sets, the media type identifier should contain that information in there somewhere.

Otherwise, people might misunderstand this media type to be THE media type for v1.1 VCs.

IOW, this media type could be seen as squatting on the main spec's media type.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

its a payload type, not a "jose" type... jose currently refers to the entire token....

Copy link
Contributor

Choose a reason for hiding this comment

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

Hmm, I'm confused by this. This media type is to identify a specific JWT claims set that has the vc claim in it, right? For example:

{
  "vc": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "id": "http://example.edu/credentials/3732",
    "type": [
      "VerifiableCredential",
      "UniversityDegreeCredential"
    ],
    "issuer": "https://example.edu/issuers/565049",
    "issuanceDate": "2010-01-01T00:00:00Z",
    "credentialSubject": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "degree": {
        "type": "BachelorDegree",
        "name": "Bachelor of Science and Arts"
      }
    }
  },
  "iss": "https://example.edu/issuers/565049",
  "nbf": 1262304000,
  "jti": "http://example.edu/credentials/3732",
  "sub": "did:example:ebfeb1f712ebc6f1c276e12ec21"
}

Is that right? If so, it seems like we should have jwt in the media type somewhere. Perhaps application/credential-1.1+jwt? This would be similar to application/at+jwt -- where the JWT must have access token claims.

This is to be used in the typ claim, right? The cty claim is "NOT RECOMMENDED" per RFC 7519 except for nested signing / encryption (a JWT within a JWT) cases, which I don't think we're talking about here.

Copy link
Contributor

@Sakurann Sakurann Jan 17, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

JWS can sign anything - does not have to be a JWT. application/credential-1.1+json would allow signing using JWS a conformant structure which is not necessarily a JWT?

wrt nested JWT, it is a confusing term... it is defined as

A JWT in which nested signing and/or encryption are employed. In
Nested JWTs, a JWT is used as the payload or plaintext value of an
enclosing JWS or JWE structure, respectively.

so JWS(JWT claims) and JWE(JWT claims) are technically nested JWTs (though it is usually used for JWE(JWS(JWT claims)) ) is also a nested JWT so it is kind of in scope...

Copy link
Contributor

Choose a reason for hiding this comment

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

application/credential-1.1+json would allow signing using JWS a conformant structure which is not necessarily a JWT?

But this PR says that when application/credential-1.1+json is used then it means the payload is a JWT Claims set ... right?

If not, when one sees application/credential-1.1+json in the cty field, what is the expected payload? What does the JSON look like if it isn't a JWT Claims set? It seems we need to enumerate the possibilities in this PR / change the text if it can be something other than that.

Copy link
Contributor

Choose a reason for hiding this comment

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

In my research preparing this PR, I have not seen any example where claimset was present in other use of cty.

Yes, but I think that's because using cty when the payload is a claim set is recommended against. This is what I've been saying. If the payload is a claim set, you don't use cty -- at least this is what people who follow the RFC have been doing. Using cty in that case would be redundancy, IMO. The payload is assumed to be a claim set unless otherwise specified via cty, like when the content type is jwk+json or a nested JWT.

@selfissued noted that would be redundant on the last call and I agree.

I don't understand how it's redundant (clearly this is a different redundancy from what I said above). Perhaps there's an assumption about where the media type "may appear" -- but media types don't work that way. So, the media type name should properly reflect what it identifies regardless of where it appears.

Furthermore, using cty is a signal that the payload is not a claim set, but, rather, is whatever the media type says it is. This, to me, is an even stronger indication that we need to be clear -- we're using cty where it is advised against by the RFC, we haven't been able to find cases where other people do it (thus far, unless they are using non-claim sets), and the thing we're identifying is not a credential... but there actually is a thing that is a credential that it could be erroneously confused with.

Copy link
Member

Choose a reason for hiding this comment

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

Can you therefore withdraw the suggestion, @msporny ? Thanks.

The suggestion was to use SOMETHING to denote that the object isn't a VC as defined by the v1.1 data model, but a claim set that wraps a VC. So, we don't have to use +jose literally, but we do have to differentiate this thing vs. the v1.1 data model because the data structures are observably different.

One of the data structures is a claims set that wraps a VC, the other is a VC. Those are two different things.

Copy link
Collaborator

Choose a reason for hiding this comment

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

@dlongley wrote:

Furthermore, using cty is a signal that the payload is not a claim set, but, rather, is whatever the media type says it is. This, to me, is an even stronger indication that we need to be clear -- we're using cty where it is advised against by the RFC

The definition in the PR explicitly says that it is a media type "identifying a JWT Claims Set conforming to the Verifiable Credentials 1.1 JWT format". So there's no doubt that it's a JWT Claims Set.

As for the JWT spec saying "In the normal case in which nested signing or encryption operations are not employed, the use of this Header Parameter is NOT RECOMMENDED." about cty, as the author of that sentence and an author of the JWT BCP, I can definitively say that explicit typing of objects is now favored by the IETF - which wasn't something we thought of a decade ago as we were developing the JWT spec. Yes, a JWT payload is always a JWT Claims Set, but there are numerous different kinds of JWT Claims Sets - one of which is the one identified by the proposed Media Type. Using cty enables us to use explicit typing to tell the difference between them.

@msporny wrote:

The suggestion was to use SOMETHING to denote that the object isn't a VC as defined by the v1.1 data model, but a claim set that wraps a VC.

The something that indicates that the object isn't a VC is that it's called a credential in the Media Type name. If we were to define Media Types for Verified Credentials, they would have vc (or verifiable-credential) in the name - not just credential - which indicates a yet-to-be-secured credential. The credential becomes verifiable once it's secured.

Copy link
Contributor

Choose a reason for hiding this comment

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

@selfissued,

The definition in the PR explicitly says that it is a media type "identifying a JWT Claims Set conforming to the Verifiable Credentials 1.1 JWT format". So there's no doubt that it's a JWT Claims Set.

Many people will not read the full description, instead only looking at the media type name.

I don't understand your "redundant" argument since it seems that any name at all would be redundant if we're relying on people always reading the description. But, if you are really ok with the name being anything that isn't "redundant", because you think the description is clear, then let's change the name to address my concern and yours. As I said, I don't know what wouldn't be "redundant" to you, so if you could suggest something new to address both of our concerns, please do.

I'm happy for us to use another name that doesn't include "claim set" in it, so long as it won't be confused with a credential or some other thing this group defines / has defined. I don't think it's ideal for the name to not reflect what it is, but I'm more concerned about basic confusion. My preferences are for avoiding confusion first and then second for good naming hygiene (clearly name things after what they are / refer to).

Copy link
Collaborator

Choose a reason for hiding this comment

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

@dlongley wrote:

Many people will not read the full description, instead only looking at the media type name.

I'm not sympathetic to arguments based on the premise that people won't read the specification. If one follows that to its logical conclusion, we shouldn't bother writing anything down at all.

As already discussed, using the name credential aligns with the way we describe the data structures this working group has invented - and is distinct from "Verifiable Credential". I think we're good to go as-is.

OR13 marked this conversation as resolved.
Show resolved Hide resolved
<p>
This specification registers the <code>application/credential-1.1+json</code> MIME Media Type specifically for
identifying a <a href="https://www.rfc-editor.org/rfc/rfc7519#section-4">JWT Claims Set</a> conforming to the Verifiable Credentials 1.1 format.
OR13 marked this conversation as resolved.
Show resolved Hide resolved
</p>
<table>
<tr>
<td>Type name: </td>
<td>application</td>
</tr>
<tr>
<td>Subtype name: </td>
<td>credential-1.1+json</td>
Copy link
Contributor

Choose a reason for hiding this comment

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

This needed to be updated too, if an editor wants to quickly fix it.

</tr>
<tr>
<td>Required parameters: </td>
<td>None</td>
</tr>
<tr>
<td>Encoding considerations: </td>
<td>
Resources that use the "<code>application/credential-1.1+json</code>"
Media Type are required to conform to all of the requirements
for the "<code>application/json</code>" Media Type and are
therefore subject to the same encoding considerations specified
in Section 11 of [[!RFC7159]].
</td>
</tr>
<tr>
<td>Security considerations: </td>
<td>As defined in this specification.</td>
</tr>
<tr>
<td>Contact: </td>
<td>
W3C Verifiable Claims Working Group <a href="mailto:[email protected]">[email protected]</a>
OR13 marked this conversation as resolved.
Show resolved Hide resolved
OR13 marked this conversation as resolved.
Show resolved Hide resolved
</td>
</tr>
</table>
</section>


</section>
</body>
</html>