JSON Web Signature (JWS)
draft-ietf-jose-json-web-signature-41

[Ballot comment]
I've got some suggestions for improvements below, but overall I cannot support this document, so I'm entering an ABSTAIN. I don't think this WG has actually fulfilled its charter with regard to this document set. The WG was supposed to produce a "JSON syntax that can be used by applications to describe secure data objects". I don't believe it did that. Instead, it produced a compact serialization for a particular purpose and then backed into a JSON syntax. The compact serialization drove the effort and produced IMO a substandard JSON serialization. I don't believe that (reliable) interoperable implementations of the JSON serialization will be possible using this document set. However, there is at least rough consensus that these documents are usable as-is, and I don't think there's anything to be gained by holding them up any further.

I hope the WG will adopt some of the remaining comments, but my intention is not to discuss this any further. If you wish to address any of the comments and need clarification, I'm glad to help with that.

------

I really wish you would have factored out what's common between JWS and JWE so you didn't have so much repeated text.

Throughout: I thought you were changing all "recipient"s to "consumer"s. I haven't changed them below, but you might want to do a proper search for them.

1: Lose the last paragraph. It's not a core goal. Certainly not in the charter.

2. A "JSON Web Signature Signature" is an unfortunate terminology choice. If
there is a whole *thing* that is the combination of the header, the signature,
and the payload, perhaps that should have been a "JOSE Web Object", or better
yet a "JOSE Object". Then you could simply have "JOSE Signature", "JOSE
Payload", and "JOSE Header". I'm also unclear why the word "Web" appears in
each of these things -- except "JOSE Header", which I find equally strange.
They should not just be for use on the Web. This whole "JW*" terminology thing
is goofy.

3. "JWS object" is undefined.

Please reverse the order of section 3.1 and 3.2.

3.1: Failure to have an unprotected header in the compact serialization means that these things are not round-trippable. That's very unfortunate and I think a failure of the protocol.

3.2:

OLD
  In the JWS JSON Serialization, a JWS object is represented as the
  combination of these four values,
      BASE64URL(UTF8(JWS Protected Header)),
      JWS Unprotected Header,
      BASE64URL(JWS Payload), and
      BASE64URL(JWS Signature)

NEW
  In the JSON Serialization, the JWS object is represented as a JSON
  object with 3 members:

      header, whose value is JWS Shared Unprotected Header
      protected, whose value is BASE64URL(UTF8(JWS Protected Header))
      payload, whose value is BASE64URL(JWS Payload)
      signature, whose value is BASE64URL(JWS Signature)

(This doesn't account for multiple signatures, and I'd wish you'd clarify what the structure actually looks like, but this is at least better.)

Also, there is no need for the Payload to be (a) part of the
serialization and (b) base64ed.

3.3:

OLD
  The following example JWS Protected Header declares that the encoded
  object is a JSON Web Token (JWT) [JWT] and the JWS Protected Header
  and the JWS Payload are secured using the HMAC SHA-256 [RFC2104, SHS]
  algorithm:

There's a couple of typos in there. I think you meant:

NEW (1)
  The following example JWS Protected Header declares that the encoded
  object is a JSON Web Token (JWT) [JWT] and the JWS Payload is secured
  using the HMAC SHA-256 [RFC2104, SHS] algorithm:

However, I'm not clear why that's an example of a *Protected* Header. Looks
like it could be any old header. So I think better is:

NEW (1)
  The following example JOSE Header declares that the encoded object is
  a JSON Web Token (JWT) [JWT] and the JWS Payload is secured using the
  HMAC SHA-256 [RFC2104, SHS] algorithm:

Then you would fix:

OLD
  Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected
  Header)) gives this value:
NEW
  If this were a JWS Protected Header, the encoding of
  BASE64URL(UTF8(JWS Protected Header)) gives this value:

Also:

  Concatenating these values...

This section is not about the compact serialization. If you want to give both
example serializations in this section, fine, but if you are giving a general
"Example JWS" as the title of the section states, don't just give the compact.

4.1.1/4.2: I see no need to mention that the alg could be a
"Collision-Resistant Name" (what a term!). The alg should be registered.
If it's not, you're in private agreement space anyway, so it needn't be
specified in the spec. Same thing for Public Header Parameter Names: If
you're going to do this interoperably, you're going to have to know what
the thing means; otherwise, it's out of band anyway. I say get rid of
the whole concept of using non-registered names.

4.1.6:

This is a section where you did not clean up the "reject" language. Here are my suggested changes:

OLD
  The recipient MUST validate
  the certificate chain according to RFC 5280 [RFC5280] and reject the
  signature if any validation failure occurs.
NEW
  The recipient MUST validate
  the certificate chain according to RFC 5280 [RFC5280] and consider
  the signature invalid if any validation failure occurs.

4.1.11:

This is a section where you did not clean up the "reject" language. Here are my suggested changes:

OLD
  If any of the listed extension Header
  Parameters are not understood and supported by the recipient, it MUST
  reject the JWS.
NEW
  If any of the listed extension Header
  Parameters are not understood and supported by the recipient, it MUST
  consider the JWS signature invalid.

5.1: s/MUST perform/performs

  2. BASE64URLing the payload shouldn't be required.

  3. Replace everything after the colon with "the JWS Protected Header
  and/or the JWS Unprotected Header, as appropriate."

  4. Strike the parenthetical "(which can only happen...)". Sounds like you are
  discouraging use of the JSON Serialization and the Unprotected Header.

  5. I don't see a need for the second sentence. Delete.

  8. Replace with "Create the desired serialized output, as described in
  Section 7." Stop privileging Compact.

5.2: s/MUST be taken/are performed.

I made an attempt to untangle the serialization from the actual algorithm. I failed. I think this is likely to be hard to implement strictly from the spec.

10.12:

This is a section where you did not clean up the "reject" language. Here are my suggested changes:

OLD
  In particular, any JSON inputs not
  conforming to the JSON-text syntax defined in RFC 7159 input MUST be
  rejected in their entirety.
NEW
  In particular, any JSON inputs not
  conforming to the JSON-text syntax defined in RFC 7159 input MUST be
  treated as invalid in their entirety by JWS consumers.
OR
  In particular, any JSON inputs not
  conforming to the JSON-text syntax defined in RFC 7159 input MUST be
  rejected in their entirety by JSON parsers.

OLD
  Such input MUST be rejected in its
  entirety.
NEW
  JWS consumers MUST treat the signatures of such input as invalid.

Appendix E:

s/reject/considered invalid/g

[Ballot discuss]
Overall, this document is in much more solid shape than when it began.  Thanks to the WG for a lot of hard work.  I only have one remaining concern, which should hopefully be easy to address.

Section 6.
"""
These Header Parameters MUST be integrity protected if the information that they convey is to be utilized in a trust decision.
"""
This smells really fishy to me.  What's your attack scenario?  I'm pretty certain that there's no way any of these fields can be altered in such a way that (1) the signature will validate, and (2) the recipient will accept a key it shouldn't.  By way of contrast, CMS doesn't sign the certificate fields, and the Certificate payload in TLS is only signed as a side effect of the protocol's verification that the remote end has been the same through the whole handshake (which doesn't apply here).

[Ballot comment]
The following sample text is encoded assuming a CR+LF line terminator:

{"typ":"JWT",
  "alg":"HS256"}

I think it would be better to just encode it as a single line, as was done in the JWE spec, so as to avoid confusing people who use operating systems that use the single-character line ending ("newline").  I suspect this applies to other examples as well.  If you have to go multiline, you could also address this by just saying "line separators in examples are CR+LF ([13, 10])".

This looks like an attack surface:

  The Header Parameter names within the JOSE
  Header MUST be unique; recipients MUST either reject JWSs with
  duplicate Header Parameter names or use a JSON parser that returns
  only the lexically last duplicate member name, as specified in
  Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript].

Is this really safe?

I believe you mean "base64 padding characters" here:

  2.  The encoded representation of the JWS Protected Header MUST be
        successfully base64url decoded following the restriction that no
        padding characters have been used.

I mention this because I don't think you require that no whitespace characters be present in the encoded JWS protected header, and someone might read this text that way.  This concern exists in several other paragraphs in this document, and also in the JWE document.  I don't know if it's worth dealing with, but it seems like it might make peoples' lives easier if you stated explicitly that you are talking about /base64/ padding.

Why not just make this a requirement of JWE:

  o  Require that the "alg" Header Parameter be carried in the
      protected header.  (This is always the case when using the JWS
      Compact Serialization and is the approach taken by CMS [RFC6211].)

Relying on the application to get this right seems chancy.

This document has a really great security considerations section.  Thanks for being so thorough and clear.

[Ballot comment]
[Updated to add a bit about section 3.2.]

2. A "JSON Web Signature Signature" is an unfortunate terminology choice. If there is a whole *thing* that is the combination of the header, the signature, and the payload, perhaps that should have been a "JOSE Web Object", or better yet a "JOSE Object". Then you could simply have "JOSE Signature", "JOSE Payload", and "JOSE Header". I'm also unclear why the word "Web" appears in each of these things -- except "JOSE Header", which I find equally strange. They should not just be for use on the Web. This whole "JW*" terminology thing is goofy.

3. "JWS object" is undefined. Do you just mean a JWS?

Please reverse the order of section 3.1 and 3.2.

3.2:

  In the JWS JSON Serialization, a JWS object is represented as the
  combination of these four values,
      BASE64URL(UTF8(JWS Protected Header)),
      JWS Unprotected Header,
      BASE64URL(JWS Payload), and
      BASE64URL(JWS Signature)

First of all, the above seems not true, and potentially confusing. In the JSON Serialization, the JWS object is represented as a JSON object with 4 members:

  protected, whose value is BASE64URL(UTF8(JWS Protected Header)),
  unprotected, whose value is JWS Shared Unprotected Header...
 
etc. This should be clarified.

Also, why is the Payload (a) part of the serialization and (b) base64ed? Are you saying that the only way I can use JWS is to include the payload as part of the JOSE object? Why can't it be a separate thing? Also, why does it have to be base64ed? It could be a UTF-8 string, or it could be a large binary object that I'm using in a non-JSON context, neither of which I want to bloat by base64ing it. This seems bogus.

3.3:

OLD
  The following example JWS Protected Header declares that the encoded
  object is a JSON Web Token (JWT) [JWT] and the JWS Protected Header
  and the JWS Payload are secured using the HMAC SHA-256 [RFC2104, SHS]
  algorithm:

There's a could of typos in there. I think you meant:

NEW (1)
  The following example JWS Protected Header declares that the encoded
  object is a JSON Web Token (JWT) [JWT] and the JWS Payload is secured
  using the HMAC SHA-256 [RFC2104, SHS] algorithm:

However, I'm not clear why that's an example of a *Protected* Header. Looks like it could be any old header. So I think better is:

NEW (1)
  The following example JOSE Header declares that the encoded object is
  a JSON Web Token (JWT) [JWT] and the JWS Payload is secured using the
  HMAC SHA-256 [RFC2104, SHS] algorithm:

Then you would fix:

OLD
  Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected
  Header)) gives this value:
NEW
  If this were a JWS Protected Header, the encoding of
  BASE64URL(UTF8(JWS Protected Header)) gives this value:

This one:

  Encoding this JWS Payload as BASE64URL(JWS Payload) gives this value

I'll get back to in Section 5. Finally:

  Concatenating these values...
 
This section is not about the compact serialization. If you want to give both example serializations in this section, fine, but if you are giving a general "Example JWS" as the title of the section states, don't just give the compact.

4.1.1/4.2: Why even bother mentioning that the alg could be a "Collision-Resistant Name" (what a term!)? The alg should be registered. If it's not, you're in private agreement space anyway, so it needn't be specified in the spec. Same thing for Public Header Parameter Names: If you're going to do this interoperably, you're going to have to know what the thing means; otherwise, it's out of band anyway. I say get rid of the whole concept of using non-registered names.

4.1.9 (and elsewhere): "Sender" is the wrong term here. (Same with "recipient".) "Generators" and "interpreters" seems much better.

5.1: s/MUST perform/performs

  2. Why is BASE64URLing the payload required? If I want to use a binary payload, or something that I know is a string, why not just use it as-is? The encoding of the payload should be application dependent.

  3. There might not be a Protected Header. Better to say "the JWS Protected Header and/or the JWS Unprotected Header, as appropriate."
 
  4. Strike the parenthetical "(which can only happen...)". Sounds like you are discouraging use of the JSON Serialization and the Unprotected Header.
 
  5. Again, why BASE64URL the payload? Also, I don't understand the need for the second sentence. Please explain.
 
  7 is not a step that you MUST perform.
 
  9. Replace with "Create the desired serialized output, as described in Section 7." Stop privileging Compact.

5.2: s/MUST be taken/are performed.

5.3: I don't understand why this section is necessary.

[Ballot comment]

no-obj

I think Pete is wrong about section 8 and would DISCUSS its
removal;-) Its needed for jku handling.

4.1.2: TLS server auth is good here, but only makes sense if
the jku parameter itself was signed and there wasn't any odd
HTTP 3xx re-direction and/or if the authority in the jku
value is reflected in the subject or SAN of the TLS server
cert. Why is it ok to not include such detail? Is all of that
correct and appropriate in 6125 (which I see you reference
from section 9)

4.1.4: why isn't this case-sensitive still as in JWKs?  (Is
that a result of lots of copied text over >1 draft?)

4.1.5-4.1.8: If all of that text is replicated elsewhere it
should only be included in one and cross-referenced.

[Ballot discuss]
Overall, this document is in much more solid shape than when it began.  Thanks to the WG for a lot of hard work.  I only have two remaining concerns, which should hopefully be easy to address.

Section 7.2.
I've had several implementors trying to use JWS in the JSON serialization ask why it was necessary to include a "signatures" array in cases where there's only one signer.  It seems like this is going to be a major barrier to deployment and re-use, so I would propose including the following text:

"""
In cases where the JWS has been signed by only a single signer, the "signatures" array will contain a single object.  In such cases, the elements of the single "signatures" object MAY be included at the top level of the JWS object.  A JSON-formatted JWS that contains a "signatures" field MUST NOT contain a "protected", "header", or "signature" field, and vice versa.
"""

This may also require some other changes where "signatures" is relied on, e.g., in Section 9 of the JWE spec.


Section 6.
"""
These Header Parameters MUST be integrity protected if the information that they convey is to be utilized in a trust decision.
"""
This smells really fishy to me.  What's your attack scenario?  I'm pretty certain that there's no way any of these fields can be altered in such a way that (1) the signature will validate, and (2) the recipient will accept a key it shouldn't.  By way of contrast, CMS doesn't sign the certificate fields, and the Certificate payload in TLS is only signed as a side effect of the protocol's verification that the remote end has been the same through the whole handshake (which doesn't apply here).

[Ballot comment]
Section 2.
In the definition of "Unsecured JWS", it would be good to note that this requires "alg" == "none".

Section 3.3.
Why doesn't this section have a JSON-encoded form as well?

Appendix A.5.
I would prefer if this example could be removed.  JWT is the only use case for Unsecured JWS right now, and there's already an example in that document.

Thanks for Appendix C.  FWIW, it has been implemented:
http://dxr.mozilla.org/mozilla-central/source/dom/crypto/CryptoBuffer.cpp#85

[Ballot discuss]
3.1: Why can't I use an unprotected header when I'm using the Compact Serialization? This seems like a real problem, since I can't convert (in a round-trippable way) between a JWS with an unprotected header in the JSON Serialization to a Compact Serialization. Why the limitation?

5.2:

Strike the last sentence of the second paragraph. There's no requirement here. If none of them validate, I can do what I want with the JWS. I needn't "reject" it. I might just mark it as "invalid".

[Get rid of all talk of "rejecting" throughout this document. Again, I will note that the signatures are not valid, but rejecting is a local implementation detail.]

This section would be greatly simplified if step 1 was: "If the Compact Serialization is being used, convert it to the JSON Serialization."

Some of these steps are not steps. I could not follow this to figure out what to do. This section could use a serious rewrite. I'm glad to work with you on that, but did not have time to provide a rewrite during my review.

8: This section needs to be removed. There is no need for TLS in a whole host of applications that could implement this protocol.

[Ballot comment]
2. A "JSON Web Signature Signature" is an unfortunate terminology choice. If there is a whole *thing* that is the combination of the header, the signature, and the payload, perhaps that should have been a "JOSE Web Object", or better yet a "JOSE Object". Then you could simply have "JOSE Signature", "JOSE Payload", and "JOSE Header". I'm also unclear why the word "Web" appears in each of these things -- except "JOSE Header", which I find equally strange. They should not just be for use on the Web. This whole "JW*" terminology thing is goofy.

3. "JWS object" is undefined. Do you just mean a JWS?

Please reverse the order of section 3.1 and 3.2.

3.2:

  In the JWS JSON Serialization, a JWS object is represented as the
  combination of these four values,
      BASE64URL(UTF8(JWS Protected Header)),
      JWS Unprotected Header,
      BASE64URL(JWS Payload), and
      BASE64URL(JWS Signature)

Why is the Payload (a) part of the serialization and (b) base64ed? Are you saying that the only way I can use JWS is to include the payload as part of the JOSE object? Why can't it be a separate thing? Also, why does it have to be base64ed? It could be a UTF-8 string, or it could be a large binary object that I'm using in a non-JSON context, neither of which I want to bloat by base64ing it. This seems bogus.

3.3:

OLD
  The following example JWS Protected Header declares that the encoded
  object is a JSON Web Token (JWT) [JWT] and the JWS Protected Header
  and the JWS Payload are secured using the HMAC SHA-256 [RFC2104, SHS]
  algorithm:

There's a could of typos in there. I think you meant:

NEW (1)
  The following example JWS Protected Header declares that the encoded
  object is a JSON Web Token (JWT) [JWT] and the JWS Payload is secured
  using the HMAC SHA-256 [RFC2104, SHS] algorithm:

However, I'm not clear why that's an example of a *Protected* Header. Looks like it could be any old header. So I think better is:

NEW (1)
  The following example JOSE Header declares that the encoded object is
  a JSON Web Token (JWT) [JWT] and the JWS Payload is secured using the
  HMAC SHA-256 [RFC2104, SHS] algorithm:

Then you would fix:

OLD
  Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected
  Header)) gives this value:
NEW
  If this were a JWS Protected Header, the encoding of
  BASE64URL(UTF8(JWS Protected Header)) gives this value:

This one:

  Encoding this JWS Payload as BASE64URL(JWS Payload) gives this value

I'll get back to in Section 5. Finally:

  Concatenating these values...
 
This section is not about the compact serialization. If you want to give both example serializations in this section, fine, but if you are giving a general "Example JWS" as the title of the section states, don't just give the compact.

4.1.1/4.2: Why even bother mentioning that the alg could be a "Collision-Resistant Name" (what a term!)? The alg should be registered. If it's not, you're in private agreement space anyway, so it needn't be specified in the spec. Same thing for Public Header Parameter Names: If you're going to do this interoperably, you're going to have to know what the thing means; otherwise, it's out of band anyway. I say get rid of the whole concept of using non-registered names.

4.1.9 (and elsewhere): "Sender" is the wrong term here. (Same with "recipient".) "Generators" and "interpreters" seems much better.

5.1: s/MUST perform/performs

  2. Why is BASE64URLing the payload required? If I want to use a binary payload, or something that I know is a string, why not just use it as-is? The encoding of the payload should be application dependent.

  3. There might not be a Protected Header. Better to say "the JWS Protected Header and/or the JWS Unprotected Header, as appropriate."
 
  4. Strike the parenthetical "(which can only happen...)". Sounds like you are discouraging use of the JSON Serialization and the Unprotected Header.
 
  5. Again, why BASE64URL the payload? Also, I don't understand the need for the second sentence. Please explain.
 
  7 is not a step that you MUST perform.
 
  9. Replace with "Create the desired serialized output, as described in Section 7." Stop privileging Compact.

5.2: s/MUST be taken/are performed.

5.3: I don't understand why this section is necessary.

[Ballot comment]
== Section 2 ==
"These terms defined by the JSON Web Encryption (JWE) [JWE]
  specification are incorporated into this specification: "JSON Web
  Encryption (JWE)" and "JWE Compact Serialization"."

Seems like "JWE JSON Serialization" should be included in this list as well.

== Section 4.2 ==
"As indicated by the common registry, JWSs and JWEs share a common
  Header Parameter space; when a parameter is used by both
  specifications, its usage must be compatible between the
  specifications."

Since both the JWS and JWE specifications are on their way to becoming RFCs, would it make more sense to say "its usage is compatible between the specifications"? Or is this for the future when new parameters may get defined?

== Section 9 ==

Do we use iesg@iesg.org? I usually use iesg@ietf.org.

IESG/Authors/WG Chairs:

IANA has reviewed draft-ietf-jose-json-web-signature-31.  Please report any inaccuracies and respond to any questions as soon as possible.

IANA's reviewer has the following comments/questions:

IANA understands that, upon approval of this document, there are two actions which IANA must complete.

First, in a location to be determined, a new registry will be created called the JSON Web Signature and Encryption Header Parameters Registry.  The registration rules for the new registry are noted below. The registry records the Header Parameter name and a reference to the specification that defines it. 

Values are registered on a Specification Required [RFC5226] basis after a two-week review period on the [TBD]@ietf.org mailing list, on the advice of one or more Designated Experts.  However, to allow for the allocation of values prior to publication, the Designated Expert(s) may approve registration once they are satisfied that such a specification will be published.

Registration requests must be sent to the [TBD]@ietf.org mailing list for review and comment, with an appropriate subject (e.g., "Request for access token type: example").

There are initial registrations in this new registry as follows:

+----------------------+---------------------+
| Header              |                    |
| Parameter Name      | Reference          |
+----------------------+---------------------+
| alg                  | [ REC-to-be ]      |
| jku                  | [ REC-to-be ]      |
| jwk                  | [ REC-to-be ]      |
| kid                  | [ REC-to-be ]      |
| x5u                  | [ REC-to-be ]      |
| x5c                  | [ REC-to-be ]      |
| x5t                  | [ REC-to-be ]      |
| x5t#S256            | [ REC-to-be ]      |
| typ                  | [ REC-to-be ]      |
| cty                  | [ REC-to-be ]      |
| crit                | [ REC-to-be ]      |
+----------------------+---------------------+

Second, in the application media types registry located at:

http://www.iana.org/assignments/media-types/

two new media types are to be registered as follows:

Name: application/jose
Reference: [ RFC-to-be ]

Name: application/jose+json
Reference: [ RFC-to-be ]


IANA understands that these two actions are the only ones required to be completed upon approval of this document.

Note:  The actions requested in this document will not be completed until the document has been approved for publication as an RFC. This message is only to confirm what actions will be performed.

The following Last Call announcement was sent out:

From: The IESG
To: IETF-Announce
CC:
Reply-To: ietf@ietf.org
Sender:
Subject: Last Call:  (JSON Web Signature (JWS)) to Proposed Standard


The IESG has received a request from the Javascript Object Signing and
Encryption WG (jose) to consider the following document:
- 'JSON Web Signature (JWS)'
  as Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits
final comments on this action. Please send substantive comments to the
ietf@ietf.org mailing lists by 2014-09-03. Exceptionally, comments may be
sent to iesg@ietf.org instead. In either case, please retain the
beginning of the Subject line to allow automated sorting.

Abstract


  JSON Web Signature (JWS) represents content secured with digital
  signatures or Message Authentication Codes (MACs) using JavaScript
  Object Notation (JSON) based data structures.  Cryptographic
  algorithms and identifiers for use with this specification are
  described in the separate JSON Web Algorithms (JWA) specification and
  an IANA registry defined by that specification.  Related encryption
  capabilities are described in the separate JSON Web Encryption (JWE)
  specification.




The file can be obtained via
http://datatracker.ietf.org/doc/draft-ietf-jose-json-web-signature/

IESG discussion can be tracked via
http://datatracker.ietf.org/doc/draft-ietf-jose-json-web-signature/ballot/


The following IPR Declarations may be related to this I-D:

  http://datatracker.ietf.org/ipr/1969/
  http://datatracker.ietf.org/ipr/1963/

(1) What type of RFC is being requested (BCP, Proposed Standard, Internet
Standard, Informational, Experimental, or Historic)? Why is this the proper type of
RFC? Is this type of RFC indicated in the title page header?

This document is being requested for publication as a Proposed Standard. The
document was produced with the expectation that it would be widely used in
conjunction with the JSON Web Algorithms (JWA), JSON Web Encryption (JWE), and
JSON Web Key (JWK) documents as part of a suite of documents providing security 
services for JSON. As such, it is reasonable for these documents to progress on the
standards track. The intended status is shown on the title page. 

(2) The IESG approval announcement includes a Document Announcement Write-
Up. Please provide such a Document Announcement Write-Up. Recent examples can
be found in the "Action" announcements for approved documents. The approval
announcement contains the following sections:

Technical Summary:

This document, JSON Web Signature (JWS), represents content secured with digital
signatures or Message Authentication Codes (MACs) using JavaScript Object
Notation (JSON) based data structures.  Two serializations for JWS objects are
defined, a compact, URL-safe representation and a JSON serialization.

Working Group Summary:

The document has clear working group consensus for publication, and has been
reviewed by several WG participants since its initial adoption as a working group
item.

Document Quality:

This document has been reviewed and revised many times. There are multiple
implementations of this document. Some of these are listed at:
https://openid.net/developers/libraries/ (see the JWT/JWS/JWE/JWK/JWA
Implementations section). There were no specific external expert reviews
conducted; however, the WGLC notification was sent to the W3C WebCrypto
working group.

Personnel:

Karen O'Donoghue is acting as the Document Shepherd.  Kathleen Moriarty is the
Responsible Area Director.

(3) Briefly describe the review of this document that was performed by the
Document Shepherd. If this version of the document is not ready for publication,
please explain why the document is being forwarded to the IESG.

The document shepherd has followed the working group process and reviewed the
final document and feels this document is ready for IESG review. Note, the
document shepherd did not validate the examples in the appendices.

(4) Does the document Shepherd have any concerns about the depth or breadth of
the reviews that have been performed?

The document shepherd does not have any concerns about the reviews that were
performed.

(5) Do portions of the document need review from a particular or from broader
perspective, e.g., security, operational complexity, AAA, DNS, DHCP, XML, or
internationalization? If so, describe the review that took place.

This document registers two new Media Types in the MIME Media Types registry.  A
request for review has been sent to the media type review mailing list.

(6) Describe any specific concerns or issues that the Document Shepherd has with
this document that the Responsible Area Director and/or the IESG should be aware
of? For example, perhaps he or she is uncomfortable with certain parts of the
document, or has concerns whether there really is a need for it. In any event, if the
WG has discussed those issues and has indicated that it still wishes to advance the
document, detail those concerns here.

The Document Shepherd is comfortable with this document as a stable specification
of two serializations for JWS objects. This specification has been implemented and
adopted in some communities (most especially OpenID).

(7) Has each author confirmed that any and all appropriate IPR disclosures required
for full conformance with the provisions of BCP 78 and BCP 79 have already been
filed. If not, explain why?

All authors have confirmed that they have no relevant IPR disclosures.

(8) Has an IPR disclosure been filed that references this document? If so, summarize
any WG discussion and conclusion regarding the IPR disclosures.

Certicom Corporation has filed an IPR discloser dealing with elliptical curve
technologies.  These patents are the normal IPR disclosure from Certicom and
received only a brief discussion. The group was notified of an additional possible
patent from IBM, but no discloser was ever filed and no discussion was ever held on
the patent. (The patent appears to be a mechanical transformation of XML digital
signatures and mapping it onto JSON.)

(9) How solid is the WG consensus behind this document? Does it represent the
strong concurrence of a few individuals, with others being silent, or does the WG as
a whole understand and agree with it?

The document represents a solid WG consensus, however there are some issues for
which consensus was difficult with strong proponents on both sides of the issues.

(10) Has anyone threatened an appeal or otherwise indicated extreme discontent? If
so, please summarize the areas of conflict in separate email messages to the
Responsible Area Director.

There have been no threats of anyone appealing the documents.

(11) Identify any ID nits the Document Shepherd has found in this document. (See
http://www.ietf.org/tools/idnits/ and the Internet-Drafts Checklist). Boilerplate
checks are not enough; this check needs to be thorough.

The following nit errors were identified. These nits are all related to downrefs to
algorithm documents and are discussed further in (15).

** Downref: Normative reference to an Historic RFC: RFC 1421
** Downref: Normative reference to an Informational RFC: RFC 2818

(12) Describe how the document meets any required formal review criteria, such as
the MIB Doctor, media type, and URI type reviews.

This document defines two new media types for the MIME Media Types registry:
      application/jose
      application/jose+json
     
A request for review has been sent to the media type review mailing list.

(13) Have all references within this document been identified as either normative or
informative?

All references are tagged as normative or informative.

(14) Are there normative references to documents that are not ready for
advancement or are otherwise in an unclear state? If such normative references
exist, what is the plan for their completion?

All normative references are on track for completion or are completed.

(15) Are there downward normative references (see RFC 3967)? If so, list these
downward references to support the Area Director in the Last Call procedure.

There are a number of down-references to information documents.  These are all
algorithm documents so this is normal procedure.  There is one down-reference to
an Historic document.
 
JSON-Web-Signature:
      RFC 1421 - Privacy Enhancement for Internet Electronic Mail: Part I: Message
Encryption and Authentication Procedures
      RFC 2818 - HTTP Over TLS

(16) Will publication of this document change the status of any existing RFCs? Are
those RFCs listed on the title page header, listed in the abstract, and discussed in the
introduction? If the RFCs are not listed in the Abstract and Introduction, explain
why, and point to the part of the document where the relationship of this document
to the other RFCs is discussed. If this information is not in the document, explain
why the WG considers it unnecessary.

These documents are all first time documents.  They will not change the status of
any existing documents.

(17) Describe the Document Shepherd's review of the IANA considerations section,
especially with regard to its consistency with the body of the document. Confirm
that all protocol extensions that the document makes are associated with the
appropriate reservations in IANA registries. Confirm that any referenced IANA
registries have been clearly identified. Confirm that newly created IANA registries
include a detailed specification of the initial contents for the registry, that
allocations procedures for future registrations are defined, and a reasonable name
for the new registry has been suggested (see RFC 5226).

(18) List any new IANA registries that require Expert Review for future allocations.
Provide any public guidance that the IESG would find useful in selecting the IANA
Experts for these new registries.

This document defines the following IANA registry including a name, initial entries,
and future allocation procedures:

      JSON Web Signature and Encryption Header Parameters Registry

(19) Describe reviews and automated checks performed by the Document Shepherd
to validate sections of the document written in a formal language, such as XML code,
BNF rules, MIB definitions, etc.

There are no formal language sections in these documents.

(1) What type of RFC is being requested (BCP, Proposed Standard, Internet
Standard, Informational, Experimental, or Historic)? Why is this the proper type of
RFC? Is this type of RFC indicated in the title page header?

This document is being requested for publication as a Proposed Standard. The
document was produced with the expectation that it would be widely used in
conjunction with the JSON Web Algorithms (JWA), JSON Web Encryption (JWE), and
JSON Web Key (JWK) documents as part of a suite of documents providing security 
services for JSON. As such, it is reasonable for these documents to progress on the
standards track. The intended status is shown on the title page. 

(2) The IESG approval announcement includes a Document Announcement Write-
Up. Please provide such a Document Announcement Write-Up. Recent examples can
be found in the "Action" announcements for approved documents. The approval
announcement contains the following sections:

Technical Summary:

This document, JSON Web Signature (JWS), represents content secured with digital
signatures or Message Authentication Codes (MACs) using JavaScript Object
Notation (JSON) based data structures.  Two serializations for JWS objects are
defined, a compact, URL-safe representation and a JSON serialization.

Working Group Summary:

The document has clear working group consensus for publication, and has been
reviewed by several WG participants since its initial adoption as a working group
item.

Document Quality:

This document has been reviewed and revised many times. There are multiple
implementations of this document. Some of these are listed at:
https://openid.net/developers/libraries/ (see the JWT/JWS/JWE/JWK/JWA
Implementations section). There were no specific external expert reviews
conducted; however, the WGLC notification was sent to the W3C WebCrypto
working group.

Personnel:

Karen O'Donoghue is acting as the Document Shepherd.  Kathleen Moriarty is the
Responsible Area Director.

(3) Briefly describe the review of this document that was performed by the
Document Shepherd. If this version of the document is not ready for publication,
please explain why the document is being forwarded to the IESG.

The document shepherd has followed the working group process and reviewed the
final document and feels this document is ready for IESG review.

(4) Does the document Shepherd have any concerns about the depth or breadth of
the reviews that have been performed?

The document shepherd does not have any concerns about the reviews that were
performed.

(5) Do portions of the document need review from a particular or from broader
perspective, e.g., security, operational complexity, AAA, DNS, DHCP, XML, or
internationalization? If so, describe the review that took place.

This document registers two new Media Types in the MIME Media Types registry.  A
request for review has been sent to the media type review mailing list.

(6) Describe any specific concerns or issues that the Document Shepherd has with
this document that the Responsible Area Director and/or the IESG should be aware
of? For example, perhaps he or she is uncomfortable with certain parts of the
document, or has concerns whether there really is a need for it. In any event, if the
WG has discussed those issues and has indicated that it still wishes to advance the
document, detail those concerns here.

The Document Shepherd is comfortable with this document as a stable specification
of two serializations for JWS objects. This specification has been implemented and
adopted in some communities (most especially OpenID).

(7) Has each author confirmed that any and all appropriate IPR disclosures required
for full conformance with the provisions of BCP 78 and BCP 79 have already been
filed. If not, explain why?

All authors have confirmed that they have no relevant IPR disclosures.

(8) Has an IPR disclosure been filed that references this document? If so, summarize
any WG discussion and conclusion regarding the IPR disclosures.

Certicom Corporation has filed an IPR discloser dealing with elliptical curve
technologies.  These patents are the normal IPR disclosure from Certicom and
received only a brief discussion. The group was notified of an additional possible
patent from IBM, but no discloser was ever filed and no discussion was ever held on
the patent. (The patent appears to be a mechanical transformation of XML digital
signatures and mapping it onto JSON.)

(9) How solid is the WG consensus behind this document? Does it represent the
strong concurrence of a few individuals, with others being silent, or does the WG as
a whole understand and agree with it?

The document represents a solid WG consensus, however there are some issues for
which consensus was difficult with strong proponents on both sides of the issues.

(10) Has anyone threatened an appeal or otherwise indicated extreme discontent? If
so, please summarize the areas of conflict in separate email messages to the
Responsible Area Director.

There have been no threats of anyone appealing the documents.

(11) Identify any ID nits the Document Shepherd has found in this document. (See
http://www.ietf.org/tools/idnits/ and the Internet-Drafts Checklist). Boilerplate
checks are not enough; this check needs to be thorough.

The following nit errors were identified. These nits are all related to downrefs to
algorithm documents and are discussed further in (15).

** Downref: Normative reference to an Historic RFC: RFC 1421
** Downref: Normative reference to an Informational RFC: RFC 2818

(12) Describe how the document meets any required formal review criteria, such as
the MIB Doctor, media type, and URI type reviews.

This document defines two new media types for the MIME Media Types registry:
      application/jose
      application/jose+json
     
A request for review has been sent to the media type review mailing list.

(13) Have all references within this document been identified as either normative or
informative?

All references are tagged as normative or informative.

(14) Are there normative references to documents that are not ready for
advancement or are otherwise in an unclear state? If such normative references
exist, what is the plan for their completion?

All normative references are on track for completion or are completed.

(15) Are there downward normative references (see RFC 3967)? If so, list these
downward references to support the Area Director in the Last Call procedure.

There are a number of down-references to information documents.  These are all
algorithm documents so this is normal procedure.  There is one down-reference to
an Historic document.
 
JSON-Web-Signature:
      RFC 1421 - Privacy Enhancement for Internet Electronic Mail: Part I: Message
Encryption and Authentication Procedures
      RFC 2818 - HTTP Over TLS

(16) Will publication of this document change the status of any existing RFCs? Are
those RFCs listed on the title page header, listed in the abstract, and discussed in the
introduction? If the RFCs are not listed in the Abstract and Introduction, explain
why, and point to the part of the document where the relationship of this document
to the other RFCs is discussed. If this information is not in the document, explain
why the WG considers it unnecessary.

These documents are all first time documents.  They will not change the status of
any existing documents.

(17) Describe the Document Shepherd's review of the IANA considerations section,
especially with regard to its consistency with the body of the document. Confirm
that all protocol extensions that the document makes are associated with the
appropriate reservations in IANA registries. Confirm that any referenced IANA
registries have been clearly identified. Confirm that newly created IANA registries
include a detailed specification of the initial contents for the registry, that
allocations procedures for future registrations are defined, and a reasonable name
for the new registry has been suggested (see RFC 5226).

(18) List any new IANA registries that require Expert Review for future allocations.
Provide any public guidance that the IESG would find useful in selecting the IANA
Experts for these new registries.

This document defines the following IANA registry including a name, initial entries,
and future allocation procedures:

      JSON Web Signature and Encryption Header Parameters Registry

(19) Describe reviews and automated checks performed by the Document Shepherd
to validate sections of the document written in a formal language, such as XML code,
BNF rules, MIB definitions, etc.

There are no formal language sections in these documents.

This represents a combined writeup for four documents

JWA - draft-ietf-jose-json-web-algorithms
JWE - draft-ietf-jose-json-web-encryption
JWK - draft-ietf-jose-json-web-key
JWS - draft-ietf-jose-json-web-signature

********************************

(1) These documents are being requested for progress at at Proposed Standard.  The documents were produced in the expectation that they will be widely used to provide security services for JSON documents, as such it is reasonable for these documents to progress on the standards track.

(2) The IESG approval announcement includes a Document Announcement Write-Up. Please provide such a Document Announcement Write-Up. Recent examples can be found in the "Action" announcements for approved documents. The approval announcement contains the following sections:

Technical Summary:

(JWA) This document, the JSON Web Algorithms (JWA) specification, registers cryptographic algorithms and identifiers to be used with the JSON Web Signature (JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK) specifications.  It defines several IANA registries for these identifiers.

(JWE) This document, JSON Web Encryption (JWE), represents encrypted content using JavaScript Object Notation (JSON) based data structures.

(JWK) This document, JSON Web Key (JWK), is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key.  This specification also defines a JSON Web Key Set (JWK Set) JSON data structure for representing a set of JWKs.

(JWS) This document, JSON Web Signature (JWS), represents content secured with digital signatures or Message Authentication Codes (MACs) using JavaScript Object Notation (JSON) based data structures. 

Working Group Summary:

The document has clear working group consensus for publication, and has been reviewed by several WG participants since its initial adoption as a working group item.

(JWA) The question of what cryptographic algorithms should be included was somewhat difficult as it is for any process trying to determine which algorithms should be included. The considerations included what is implemented, available, broadly used, and adequate from a security perspective. The issue of algorithms that are potentially less desirable but more broadly implemented was considered.

Document Quality:

There are multiple implementations of all four documents. There were no specific external expert reviews conducted. The WGLC notification was sent to the W3C WebCrypto working group.

Personnel:

Karen O'Donoghue is acting as the Document Shepard.  Kathleen Morirty  is the Responsible Area Director

(3) The document shepherd has followed the working group process and reviewed the final documents and feels these documents are ready for IESG review. Further discussion and changes may result from IESG and IETF review, but the documents as they stand are ready for publication.

(4) The document shepherd does not have any concerns about the reviews that were performed.

(5) JSON-Web-Signture and JSON-Web-Key register new Media Types.  A request for review has been sent to the media type review mailing list.

(6) The Document Shepherd is comfortable with these documents as a stable set of specifications that have been implemented and adopted in some communities (most especially OpenID). There has also been some attempt to coordinate with the W3C WebCrypto working group. The documents are not perfect, but they do represent the consensus of the working group. There is a minority contingent of recognized experts that believe there are a number of issues in the documents. However, these specifications have been widely implemented and deployed in the OpenID community.

(7) All authors have confirmed that they have dealt with all appropriate IPR disclosures.

(8) Certicom Corporation has filed an IPR discloser on draft-ietf-jose-json-web-algorithms and draft-ietf-jose-json-web-signature dealing with elliptical curve technologies.  These patents are the normal IPR disclosure from Certicom and received only a brief discussion. The group was notified of an additional possible patent from IBM, but no discloser was ever filed and no discussion was ever held on the patent. (The patent appears to be a mechanical transformation of XML digital signatures and mapping it onto JSON.)

(9) The majority of the documents represent a solid WG consensus, however there are some issues for which consensus was reached more by fatigue, with strong proponents on both sides of the issues.

(10) There have been no threats of anyone appealing the documents.

(11) The following nit errors were identified. These nits are all related to downrefs to algorithm documents and are discussed further in (15).

JWA
** Downref: Normative reference to an Informational RFC: RFC 2104
** Downref: Normative reference to an Informational RFC: RFC 2898
** Downref: Normative reference to an Informational RFC: RFC 3394
** Downref: Normative reference to an Informational RFC: RFC 6090

JWE
** Downref: Normative reference to an Informational RFC: RFC 1951

JWK
** Downref: Normative reference to an Historic RFC: RFC 1421
** Downref: Normative reference to an Informational RFC: RFC 2818

JWS
** Downref: Normative reference to an Historic RFC: RFC 1421
** Downref: Normative reference to an Informational RFC: RFC 2818


(12) JSON-Web-Signture and JSON-Web-Key register new Media Types.  A request for review has been sent to the media type review mailing list.

(13) All references are tagged as normative or informative.

(14) All normative references are on track for completion or are completed.

(15) There are a number of down-references to information documents.  These are all algorithm documents so this is normal procedure.  There is one down-reference to an Historic document.

JSON-Web-Algorithms:
        RFC 2104 - HMAC: Keyed-Hashing for Message Authentication
        RFC 2898 - PKCS #5: Password-Based Cryptography Specification Version 2.0
        RFC 3394 - Advanced Encryption Standard (AES) Key Wrap Algorithm
        RFC 6090 - Fundamental Elliptic Curve Cryptography Algorithms

JSON-Web-Encryption:
        RFC 1951 - DEFLATE Compressed Data Format Specification version 1.3

JSON-Web-Key:
        RFC 1421 - Privacy Enhancement for Internet Electronic Mail: Part I: Message Encryption and Authentication Procedures  (Historic)
        RFC 2818 - HTTP Over TLS

JSON-Web-Signature:
        RFC 1421 - Privacy Enhancement for Internet Electronic Mail: Part I: Message Encryption and Authentication Procedures
        RFC 2818 - HTTP Over TLS

(16) These documents are all first time documents.  They will not change the status of any existing documents.

(17) The chairs have walked through all of the documents to verify that all of the items that need to be registered have been called out in the IANA considerations section and that they are consistant between what is in the text and what is in the registration templates.  The WG was careful to try and call out the necessary information needed to do adaquate review on new items for the registry.

(18) All of the registries created by these documents are designated as requiring Expert Review.  The registries to be created are:

JSON-Web-Algorithms:
* JSON Web Signature Encryption Algorithm Registery
* JSON Web Encryption Compression Algorithm Registry
* JSON Web Key Types Registry
* JSON Web Key Elliptic Curve Registry

JSON-Web-Key:
* JSON Web Key Parameters Registry
* JSON Web Key Use Registry
* JSON Web Key Operations Registry
* JSON Web Key Set Parameters Registry

JSON-Web-Signature:
* JSON Web Signature and Encryption Header Parameters Registry

At this time it is known that there will be new allocations from the W3C WebCrypto group and the OAuth WG.  The major concern is going to be the fact that if the authors of the current drafts are selected as the reviewers, it is not going to lead to independent reviewers.  However it is not clear where the pool of reviewers should be drawn from if the current authors are excluded.

(19) There are no formal language sections in these documents.