Subject: [OAUTH-WG] draft-ietf-oauth-json-web-token-19 - Examples

From: Hannes Tschofenig <[email-masked]>
Date: Fri, 25 Apr 2014 12:37:40 +0200

Hi all,

As a document shepherd I have to verify the entire document and this
includes the examples as well.

Section 3.1:

You write:

"
   The following octet sequence is the UTF-8 representation of the JWT
   Header/JWS Header above:

   [123, 34, 116, 121, 112, 34, 58, 34, 74, 87, 84, 34, 44, 13, 10, 32,
   34, 97, 108, 103, 34, 58, 34, 72, 83, 50, 53, 54, 34, 125]
"

The values IMHO are represented in Decimal code point rather than Octal
UTF-8 bytes, as stated above.
See the following online tool to see the difference:
http://www.ltg.ed.ac.uk/~richard/utf-8.cgi?input=%22&mode=char

Note that you could also show a hex encoding instead (e.g., via
http://ostermiller.org/calc/encode.html). Hixie's decoder would then
produce the correct decoding. Here is the link to his software:
http://software.hixie.ch/utilities/cgi/unicode-decoder/utf8-decoder
(Note that this program seems to have flaws for most other options.)

When do a Base64URL encoding of

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

then I get

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9

but your spec says:

eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9

Same with {"iss":"joe","exp":1300819380,"http://example.com/is_root":true}.

My result:
eyJpc3MiOiJqb2UiLCJleHAiOjEzMDA4MTkzODAsImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ

Your result:
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ

Note: I am using this online tool for Base64URL encoding:
http://kjur.github.io/jsjws/tool_b64uenc.html.
Interestingly, when I dump the data into http://jwt.io/ then I get a
correct decoding. It might well be that the kjur.github.io has a flaw.

Just wanted to check what tool you have used to create these encodings.

Section 6.1:

The example in Section 6.1 is the same as in 3.1. Maybe it would be
useful to show something different here.

The example in Appendix A.1 is more sophisticated since it demonstrates
encryption. To verify it I would need to have a library that supports
JWE and RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256. Which library
have you been using?

I was wondering whether it would make sense to add two other examples,
namely for integrity protection. One example showing an HMAC-based keyed
message digest and another one using a digital signature.

Here is a simple example to add that almost all JWT libraries seem to be
able to create and verify:

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

I use the HS256 algorithm with a shared secret '12345'.

Body:

{"iss":"https://as.example.com","sub":"mailto:[email-masked]","nbf":1398420753,"exp":1398424353,"iat":1398420753}

jwt.encode({"iss":"https://as.example.com","sub":"mailto:[email-masked]","nbf":1398420753,"exp":1398424353,"iat":1398420753},"12345",
"HS256")

I used http://www.onlineconversion.com/unix_time.htm to create the
date/time values:
"nbf":1398420753 --> Fri, 25 Apr 2014 10:12:33 GMT
"exp":1398424353 --> Fri, 25 Apr 2014 11:12:33 GMT
"iat":1398420753 --> Fri, 25 Apr 2014 10:12:33 GMT

Here is the output created with https://github.com/progrium/pyjwt/ and
verified with http://jwt.io/:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FzLmV4YW1wbGUuY29tIiwiaWF0IjoxMzk4NDIwNzUzLCJzdWIiOiJtYWlsdG86am9obkBleGFtcGxlLmNvbSIsImV4cCI6MTM5ODQyNDM1MywibmJmIjoxMzk4NDIwNzUzfQ.0gfRUIley70bMP7hN6sMWkHwHezdrv2E1LAVcNdTsq4

Ciao
Hannes

---

From: Sergey Beryozkin <[email-masked]>
Date: Fri, 25 Apr 2014 12:06:14 +0100

As far as I recall the spec example uses line separators and it can 
affect the output

Thanks, Sergey

On 25/04/14 11:37, Hannes Tschofenig wrote:
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth
>

---

From: Antonio Sanso <[email-masked]>
Date: Fri, 25 Apr 2014 11:48:36 +0000

hi Hannes.

>   The following octet sequence is the UTF-8 representation of the JWT

see http://www.ietf.org/mail-archive/web/oauth/current/msg11599.html

regards

antonio

---

From: Hannes Tschofenig <[email-masked]>
Date: Fri, 25 Apr 2014 14:42:01 +0200

Hi Antonio

good to see that others have run into the same issue before.

I wonder why the carriage return and the line feed had been inserted.

We either need some text to explain this in the example or to use an
example that does not use carriage returns or line feeds.

Ciao
Hannes

---

From: Brian Campbell <[email-masked]>
Date: Fri, 25 Apr 2014 07:03:40 -0600

So JWT 3.1 is based entirely on, and is just a subset of, JWS Appendix A.1.
And I've got a test which validates that example in my JOSE
library<https://bitbucket.org/b_c/jose4j>:
https://bitbucket.org/b_c/jose4j/src/master/src/test/java/org/jose4j/jws/JwsUsingHmacSha256ExampleTest.java

And here's a verification of the Example Encrypted JWT from Appendix A.1:
https://bitbucket.org/b_c/jose4j/src/master/src/test/java/org/jose4j/jwe/EncryptedJwtTest.java

The example in Section 6.1 is different than 3.1 - it's a "Plaintext JWT"
using the "none" JWS alg. I've got verification of that one as well at the
top of
https://bitbucket.org/b_c/jose4j/src/master/src/test/java/org/jose4j/jws/JwsPlaintextTest.java

On Fri, Apr 25, 2014 at 4:37 AM, Hannes Tschofenig <
[email-masked]> wrote:

> {"iss":"https://as.example.com","sub":"mailto:[email-masked]
> ","nbf":1398420753,"exp":1398424353,"iat":1398420753}
>
> jwt.encode({"iss":"https://as.example.com","sub":"mailto:[email-masked]
> ","nbf":1398420753,"exp":1398424353,"iat":1398420753},"12345",
> "HS256")
>

---

From: Brian Campbell <[email-masked]>
Date: Fri, 25 Apr 2014 08:22:00 -0600

Note that the draft is showing an *octet sequence* with each individual
octet being shown as decimal value. It doesn't state anything about using
octal, the base-8 number system. Those octets also show unambiguously what
is being base64url encoded (including the line endings via "13, 10") - no
matter how the unencoded headers or bodies are shown in the draft, there's
going to be potential confusion about what white space and line breaks is
or is not to be included in the encoding and serialization so giving the
octet sequence alleviates that. It's maybe also worth noting that the JOSE
suite of specs all use the same notation and text in their examples.

If we were to add another example as was suggested, it should probably use
a shared secret with a little more entropy as '12345' isn't strictly
compliant with the normative requirements in JWA for HS256.
http://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-25#section-3.2states
that a 'key of the same size as the hash output (for instance, 256
bits for "HS256") or larger MUST be used.'

---

From: Mike Jones <[email-masked]>
Date: Fri, 25 Apr 2014 16:37:52 +0000

I’m not sure how octal came up, as the examples all use JSON notation, which is decimal.  (The word octet is a standard word for a value containing 8 bits, and has nothing to do with octal.)

Hannes, we use JSON notation in the examples, rather than hexadecimal intentionally, as the specs are based on JSON.

Some of the examples intentionally include whitespace, including CRLFs, to demonstrate that the JSON need not be canonicalized in any way before use in a JWT.  The actual bytes of the JSON representation are included so there’s no ambiguity about the actual values used in the examples.  We do already have explicit text talking about this in the spec.  Bullet 1 of http://tools.ietf.org/html/draft-ietf-oauth-json-web-token-19#section-7 says:
   1.  Create a JWT Claims Set containing the desired claims.  Note that
       white space is explicitly allowed in the representation and no
       canonicalization need be performed before encoding.

While we could add other examples, doing so is beyond the scope of the immediate mission to validate the existing examples, Hannes.  There’s lots of examples in the underlying JOSE specs, so it’s not clear that we really need to add additional ones at this time.  (If this suggestion comes up again during IESG review, we could do that, but I don’t think it’s necessary at this point to move the spec to IESG review.)

                                                            -- Mike

From: OAuth [mailto:[email-masked]] On Behalf Of Brian Campbell
Sent: Friday, April 25, 2014 7:22 AM
To: Hannes Tschofenig
Cc: [email-masked]
Subject: Re: [OAUTH-WG] draft-ietf-oauth-json-web-token-19 - Examples

Note that the draft is showing an *octet sequence* with each individual octet being shown as decimal value. It doesn't state anything about using octal, the base-8 number system. Those octets also show unambiguously what is being base64url encoded (including the line endings via "13, 10") - no matter how the unencoded headers or bodies are shown in the draft, there's going to be potential confusion about what white space and line breaks is or is not to be included in the encoding and serialization so giving the octet sequence alleviates that. It's maybe also worth noting that the JOSE suite of specs all use the same notation and text in their examples.
If we were to add another example as was suggested, it should probably use a shared secret with a little more entropy as '12345' isn't strictly compliant with the normative requirements in JWA for HS256. http://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-25#section-3.2 states that a 'key of the same size as the hash output (for instance, 256 bits for "HS256") or larger MUST be used.'

On Fri, Apr 25, 2014 at 6:42 AM, Hannes Tschofenig <[email-masked]<mailto:[email-masked]>> wrote:
Hi Antonio

Ciao
Hannes

On 04/25/2014 01:48 PM, Antonio Sanso wrote:
> hi Hannes.
>
>
> On Apr 25, 2014, at 12:37 PM, Hannes Tschofenig <[email-masked]<mailto:[email-masked]>> wrote:
>
>> Hi all,
>>
>> correct decoding. It might well be that the kjur.github.io<http://kjur.github.io> has a flaw.
>>
>> {"iss":"https://as.example.com","sub":"mailto:[email-masked]<mailto:[email-masked]>","nbf":1398420753,"exp":1398424353,"iat":1398420753}
>>
>> jwt.encode({"iss":"https://as.example.com","sub":"mailto:[email-masked]<mailto:[email-masked]>","nbf":1398420753,"exp":1398424353,"iat":1398420753},"12345",
>> "HS256")
>>
>> [email-masked]<mailto:[email-masked]>

_______________________________________________
OAuth mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/oauth

---

From: Hannes Tschofenig <[email-masked]>
Date: Mon, 28 Apr 2014 10:23:44 +0200

Hi Brian,

you are entirely correct. I believe I read the paragraph not carefully
enough. For some reason I read octal rather than octet and that makes,
of course, a huge difference.

Sorry. My fault.

Ciao
Hannes

On 04/25/2014 04:22 PM, Brian Campbell wrote:
> octet being shown as decimal value. It doesn't state anything about
> using octal, the base-8 number system. Those octets also show
> unambiguously what is being base64url encoded (including the line
> endings via "13, 10") - no matter how the unencoded headers or bodies
> are shown in the draft, there's going to be potential confusion about
> what white space and line breaks is or is not to be included in the
> encoding and serialization so giving the octet sequence alleviates that.
> It's maybe also worth noting that the JOSE suite of specs all use the
> same notation and text in their examples.

---

From: Hannes Tschofenig <[email-masked]>
Date: Mon, 28 Apr 2014 10:34:03 +0200

Hi Brian,

thanks for the pointers.

It is easy to see from your code where the issue is. In your code the
\r\n sequence is added at the end of each line but due to the nature of
the ASCII draft formatting a reader only sees the \n (new line) but not
the \r carriage return.

While the draft provides the UTF-8 representation of each individual
character but, as I mentioned in my email below, none of the tools I
found produce a convenient way to use this as input for the base64url
encoding procedure.

I believe it would be good to mention that each line in the examples is
followed by the \r\n character sequence to make it easier for those who
want to re-create the examples.

What do you think?

Ciao
Hannes

On 04/25/2014 03:03 PM, Brian Campbell wrote:
> So JWT 3.1 is based entirely on, and is just a subset of, JWS Appendix
> A.1. And I've got a test which validates that example in my JOSE library
> <https://bitbucket.org/b_c/jose4j>:
> The example in Section 6.1 is different than 3.1 - it's a "Plaintext
> JWT" using the "none" JWS alg. I've got verification of that one as well
> at the top of
> On Fri, Apr 25, 2014 at 4:37 AM, Hannes Tschofenig
> <[email-masked] <mailto:[email-masked]>> wrote:
> 
>     Hi all,
> 
>     Same with
>     {"iss":"joe","exp":1300819380,"http://example.com/is_root":true}.
> 
>     My result:
>     <mailto:[email-masked]>","nbf":1398420753,"exp":1398424353,"iat":1398420753}
> 
>     <mailto:[email-masked]>","nbf":1398420753,"exp":1398424353,"iat":1398420753},"12345",
>     "HS256")
> 
>     [email-masked] <mailto:[email-masked]>

---

From: Hannes Tschofenig <[email-masked]>
Date: Mon, 28 Apr 2014 10:38:41 +0200

Hi Mike,

On 04/25/2014 06:37 PM, Mike Jones wrote:
> While we could add other examples, doing so is beyond the scope of the
> immediate mission to validate the existing examples, Hannes.  There’s
> lots of examples in the underlying JOSE specs, so it’s not clear that we
> really need to add additional ones at this time.  (If this suggestion
> comes up again during IESG review, we could do that, but I don’t think
> it’s necessary at this point to move the spec to IESG review.)
> 
It is certainly true that examples are not mandatory and that the JOSE
specs contain a number of examples.

Read through the document it came to my mind that the most common uses
of JWTs are actually not covered as part of the examples. Many readers
look at the examples to quickly get the idea and neither a JWT protected
using a MAC is there nor a JWT protected with a digital signature.

I will, however, get over it.

Ciao
Hannes

---

From: Brian Campbell <[email-masked]>
Date: Mon, 28 Apr 2014 06:50:38 -0600

To be honest, I'm kind of indifferent to it. Yes, the input into the
example encodings do include CR+LF (the editor is a Microsoft guy after
all) but they also have space characters that are removed from the
beginning of each line, which isn't exactly obvious. Describing that in a
way that everyone will find easy to understand and use seems like a
difficult endeavor. The octet sequence is there to unambiguously show what
the input into the encoding was. And one can also always decode the
base64url content too, to see exactly what the input was.

So, yeah, I don't know. I'm not against mentioning the \r\n but I don't
personally think it helps much.

On Mon, Apr 28, 2014 at 2:34 AM, Hannes Tschofenig <
[email-masked]> wrote:

> >     <mailto:[email-masked]
> >     <mailto:[email-masked]
> >     Here is the output created with https://github.com/progrium/pyjwt/and

---

From: Hannes Tschofenig <[email-masked]>
Date: Mon, 28 Apr 2014 16:30:52 +0200

It would be nice to be able to verify the examples in the document(s). I
understand that the ASCII draft format provides a number of limitations.

I wonder what others think. Have you tried to verify the examples? Have
you encounter problems yourself as well?

Ciao
Hannes

On 04/28/2014 02:50 PM, Brian Campbell wrote:
> beginning of each line, which isn't exactly obvious. Describing that in
> a way that everyone will find easy to understand and use seems like a
> difficult endeavor. The octet sequence is there to unambiguously show
> what the input into the encoding was. And one can also always decode the
> On Mon, Apr 28, 2014 at 2:34 AM, Hannes Tschofenig
>     > <[email-masked] <mailto:[email-masked]>
>     <mailto:[email-masked]
>     <mailto:[email-masked]>>> wrote:
>     >
>     >     Hi all,
>     >
>     >     correct decoding. It might well be that the kjur.github.io
>     <http://kjur.github.io>
>     >     <http://kjur.github.io> has a flaw.
>     >
>     <mailto:[email-masked]>
>     >     <mailto:[email-masked]
>     <mailto:[email-masked]>>","nbf":1398420753,"exp":1398424353,"iat":1398420753}
>     >
>     >    
>     <mailto:[email-masked]>
>     >     <mailto:[email-masked]
>     <mailto:[email-masked]>>","nbf":1398420753,"exp":1398424353,"iat":1398420753},"12345",
>     >     "HS256")
>     >
>     >     [email-masked] <mailto:[email-masked]> <mailto:[email-masked]
>     <mailto:[email-masked]>>

---

From: Mike Jones <[email-masked]>
Date: Mon, 28 Apr 2014 15:48:14 +0000

I'm not opposed to saying more about the fact that in order to verify the examples, people need to use the octet sequence representation, rather than the ASCII representation, since aspects of the ASCII rendering will vary, including whether lines are terminated by CRLF or LF sequences and in the number of spaces at the beginning and ends of lines.

I already have to produce an updated draft to swap whether two references are normative or informative, so I can add this caveat this at the same time.

				-- Mike

-----Original Message-----
From: OAuth [mailto:[email-masked]] On Behalf Of Hannes Tschofenig
Sent: Monday, April 28, 2014 7:31 AM
To: Brian Campbell
Cc: [email-masked]
Subject: Re: [OAUTH-WG] draft-ietf-oauth-json-web-token-19 - Examples

It would be nice to be able to verify the examples in the document(s). I understand that the ASCII draft format provides a number of limitations.

I wonder what others think. Have you tried to verify the examples? Have you encounter problems yourself as well?

Ciao
Hannes

On 04/28/2014 02:50 PM, Brian Campbell wrote:
> beginning of each line, which isn't exactly obvious. Describing that 
> in a way that everyone will find easy to understand and use seems like 
> a difficult endeavor. The octet sequence is there to unambiguously 
> show what the input into the encoding was. And one can also always 
> decode the base64url content too, to see exactly what the input was.
> 
> So, yeah, I don't know. I'm not against mentioning the \r\n but I 
> don't personally think it helps much.
> 
> 
> 
>

---

From: Mike Jones <[email-masked]>
Date: Mon, 28 Apr 2014 16:21:47 +0000

I'm confused by your statement below, Hannes, about the examples not showing JWTs protected by MACs or digital signatures, since the example JWT in http://tools.ietf.org/html/draft-ietf-oauth-json-web-token-19#section-3.1 is protected by a MAC and the nested JWT example in http://tools.ietf.org/html/draft-ietf-oauth-json-web-token-19#appendix-A.2 is protected by a digital signature (and then encrypted).

-----Original Message-----
From: Hannes Tschofenig [mailto:[email-masked]] 
Sent: Monday, April 28, 2014 1:39 AM
To: Mike Jones; Brian Campbell
Cc: [email-masked]
Subject: Re: [OAUTH-WG] draft-ietf-oauth-json-web-token-19 - Examples

Hi Mike,

On 04/25/2014 06:37 PM, Mike Jones wrote:
> lots of examples in the underlying JOSE specs, so it’s not clear that 
> we really need to add additional ones at this time.  (If this 
> suggestion comes up again during IESG review, we could do that, but I 
> don’t think it’s necessary at this point to move the spec to IESG 
> review.)
> 
It is certainly true that examples are not mandatory and that the JOSE specs contain a number of examples.

Read through the document it came to my mind that the most common uses of JWTs are actually not covered as part of the examples. Many readers look at the examples to quickly get the idea and neither a JWT protected using a MAC is there nor a JWT protected with a digital signature.

Ciao
Hannes