Merge pull request #447 from cds-hooks/issue/187-standardize-jwt-alg

Add JWT alg standardization (fixes #187)

Author: kpshek

docs/specification/1.0.md

@@ -648,6 +648,22 @@ The EHR MUST make its public key, expressed as a JSON Web Key (JWK) in a JWK Set
 
 The EHR MAY make its JWK Set available via a URL identified by the `jku` header field, as defined by [rfc7515 4.1.2](https://tools.ietf.org/html/rfc7515#section-4.1.2). If the `jku` header field is ommitted, the EHR and CDS Service SHALL communicate the JWK Set out-of-band.
 
+#### JWT Signing Algorithm
+
+The cryptographic signing algorithm of JWT is indicated in the `alg` header field. [JSON Web Algorithms (rfc7518)](https://tools.ietf.org/html/rfc7518) defines several cryptographic algorithms for use in signing JWTs and should be referenced by CDS Hooks implementers.
+
+JWTs SHALL NOT be signed used the `none` algorithm, referred to in rfc7518 as unsecured JSON Web Signatures, as the lack of a cryptographic signature does not provide any integrity protection. Such JWTs could not be used by a CDS Service to identity the CDS Client preventing an establishment of trust.
+
+JWTs SHALL NOT be signed using any symmetric algorithm as these algorithms require the CDS Client and CDS Service to share a private key in order to verify the signature. For example, all HMAC based algorithms rely upon a shared private key and thus SHALL NOT be used to sign a JWT.
+
+When choosing an algorithm to sign their JWTs, CDS Clients SHOULD consider not only the algorithms (and key sizes) that are recommended within the security industry, but also how well those algorithms are supported in the various programming languages and libraries that may be used by CDS Services.
+
+At publication time of this specification, both ES384 and RS384 are RECOMMENDED for their regard within the larger security industry, strength, and support across popular programming languages and libraries. However, stronger and better algorithms are continually being introduced due to new threats, weaknesses, and increases in computing power. CDS Clients SHOULD continually re-evaluate their choice of an algorithm based upon these ever changing conditions.
+
+CDS Services SHOULD consider the algorithms they understand and trust based upon their tolerance for risk.
+
+#### Example
+
 An example JSON web token header, payload, and JWK set:
 
 ```json