Subject: [jose] Appendix D. Notes on Validation Key Selection

From: Mike Jones <[email-masked]>
Date: Fri, 17 Jan 2014 02:44:00 +0000

Per my action item on the call, the following is proposed updated text for JWS Appendix D.  It includes a lot of introductory text proposed by Jim.  It also more explicitly describes the likely methods of key ordering and key filtering, as also requested on the call.  Please let me know if there are any additional text changes you'd like to see (and if so, please provide specific proposed text, if possible).  The previous version of this appendix can be read at http://tools.ietf.org/html/draft-ietf-jose-json-web-signature-19#appendix-D.

Appendix D.  Notes on Validation Key Selection

This appendix describes a set of possible algorithms for selecting the key to be used to validate the digital signature or MAC of a JWS object. This guidance identifies a set of algorithms, rather than a single algorithm, because in different contexts, not all the sources of keys will be used, they can be tried in different orders, and sometimes not all the collected keys will be tried.

The algorithms consist of the application of some or all of the steps described below; the order and inclusion of steps described below does not mean that they need to be performed in this order or that they are required in all contexts. These algorithms are described for illustration purposes only; specific applications can and are likely to use different algorithms. Specific applications will frequently have a much simpler method of determining the keys to use, as there may be one or two key selection methods that are profiled for the application's use. This appendix supplements the normative information on key location in Section 6 (Key Identification).

The gist of these algorithms is to collect a set of keys from known applicable sources of keys and then to use them to attempt to validate the digital signature or MAC value of a JWS. Potential sources of keys include:
*         Keys supplied by the application protocol being used.
*         Keys referenced by the jku (JWK Set URL) Header Parameter.
*         The key provided by the jwk (JSON Web Key) Header Parameter.
*         The keys referenced by the kid (Key ID) Header Parameter.
*         Keys referenced by the x5u (X.509 URL) Header Parameter.
*         The key provided by the x5c (X.509 Certificate Chain) Header Parameter.
*         The key referenced by the x5t (X.509 Certificate SHA-1 Thumbprint) Header Parameter.
*         Other applicable keys available to the application.

Once the set of keys has been collected, the following steps may also be applied:
*         Order the set of collected keys in a particular way. For instance, keys referenced by the kid or x5t parameters might be used before other keys. Keys with certain alg values or other member values might be ordered before keys with other alg values or other member values.
*         Filter the set of collected keys in a particular way. For instance, only keys referenced by the kid or x5t parameters might be used by the application. Keys might be filtered to include or exclude keys with certain alg values, use values, or other member values.

Finally, signature or MAC validation will be tried with some or all of the collected and possibly ordered and/or filtered keys. This process will normally terminate following a successful validation.

                                                                -- Mike

---

From: "Jim Schaad" <[email-masked]>
Date: Fri, 17 Jan 2014 12:31:21 -0800

Webster's defines an algorithm as "a step-by-step procedure for solving a
problem or accomplishing some end especially by a computer".  I fail to find
an algorithm in the text below.  I also fail to find any steps in the
description as well.  I therefore object to the concept of calling the
whatever is being presented here as an algorithm.

From: jose [mailto:[email-masked]] On Behalf Of Mike Jones
Sent: Thursday, January 16, 2014 6:44 PM
To: [email-masked]
Subject: [jose] Appendix D. Notes on Validation Key Selection

Per my action item on the call, the following is proposed updated text for
JWS Appendix D.  It includes a lot of introductory text proposed by Jim.  It
also more explicitly describes the likely methods of key ordering and key
filtering, as also requested on the call.  Please let me know if there are
any additional text changes you'd like to see (and if so, please provide
specific proposed text, if possible).  The previous version of this appendix
can be read at
http://tools.ietf.org/html/draft-ietf-jose-json-web-signature-19#appendix-D.

This appendix describes a set of possible algorithms for selecting the key
to be used to validate the digital signature or MAC of a JWS object. This
guidance identifies a set of algorithms, rather than a single algorithm,
because in different contexts, not all the sources of keys will be used,
they can be tried in different orders, and sometimes not all the collected
keys will be tried. 

Does the text offered up here intentionally ignore the problem of locating
keys for encryption? 

The algorithms consist of the application of some or all of the steps
described below; the order and inclusion of steps described below does not
mean that they need to be performed in this order or that they are required
in all contexts. These algorithms are described for illustration purposes
only; specific applications can and are likely to use different algorithms. 

If this is a set of algorithms -and the set is complete - then why would
they use different algorithms?  Text makes no sense without a single
algorithm.

Specific applications will frequently have a much simpler method of
determining the keys to use, as there may be one or two key selection
methods that are profiled for the application's use. This appendix
supplements the normative information on key location in Section 6 (Key
Identification). 

The gist of these algorithms is to collect a set of keys from known
applicable sources of keys and then to use them to attempt to validate the
digital signature or MAC value of a JWS. Potential sources of keys include: 

.         Keys supplied by the application protocol being used. 

.         Keys referenced by the jku (JWK Set URL) Header Parameter. 

.         The key provided by the jwk (JSON Web Key) Header Parameter. 

.         The keys referenced by the kid (Key ID) Header Parameter. 

Given a kid how do I find  key?  This is just a filter.

.         Keys referenced by the x5u (X.509 URL) Header Parameter. 

Singular or multiple?

.         The key provided by the x5c (X.509 Certificate Chain) Header
Parameter. 

.         The key referenced by the x5t (X.509 Certificate SHA-1 Thumbprint)
Header Parameter. 

Given a thumbprint how do I find a key? This is just  filter.

.         Other applicable keys available to the application. 

Once the set of keys has been collected, the following steps may also be
applied:

s/Once the/As the/

.         Order the set of collected keys in a particular way. For instance,
keys referenced by the kid or x5t parameters might be used before other
keys. Keys with certain alg values or other member values might be ordered
before keys with other alg values or other member values. 

s/might be used/might be tried/

I don't understand ordering on alg values - I would need a very concrete
example to know what this meant.  I can understand filtering but that is not
what is here.

.         Filter the set of collected keys in a particular way. For
instance, only keys referenced by the kid or x5t parameters might be used by
the application. Keys might be filtered to include or exclude keys with
certain alg values, use values, or other member values. 

So I am free to ignore the following things when selecting keys - alg, use,
key_ops, ktyp even if they would make no sense in the context.  I.e.
"use":"enc" is purely advisory.

Finally, signature or MAC validation will be tried with some or all of the
collected and possibly ordered and/or filtered keys. This process will
normally terminate following a successful validation. 

I don't know that I understand the fail condition that is proposed here.
Would a fail after trying 5 keys be acceptable?  Or would I need to try all
of the keys that I found?  Is a shotgun approach considered to be a good
method of determining the key to be used?

Nothing is said in this text about doing a trust check on keys or
certificates.  Should it be part of the filtering steps?

                                                                -- Mike