updated the document for the JWK routes

README.md

@@ -70,7 +70,36 @@ identified by its thumbprint "kid" (which the issuer knows without revealing
 its ppid of the subject and without the authorized party needing to reveal its
 ppid of the subject.
 
-jwks
+JWKs
 ----
+We want the users to have the option of signing tokens using keys on their own
+devices. This requires having a place to store the public half of those keys
+on a server that can then server the public keys to resource providers for
+signature verification.
+
+### Saving a JWK ###
+  * **URL** `:scheme//:hostname/api/issuer@oauth3.org/jwks/:sub`
+  * **Method** `POST`
+  * **Url Params**
+    * `sub`: The [subject](#subject) using the issuer hostname as the `azp`
+  * **Body Params**: The body should be a JSON object representing a
+    [JWK](https://tools.ietf.org/html/rfc7517#section-4).
+
+### Retrieving a JWK ###
+  * **URL** `:scheme//:hostname/api/issuer@oauth3.org/jwks/:kid.json`
+  * **Method** `GET`
+  * **Url Params**
+    * `kid`: The [JWK thumbprint](https://tools.ietf.org/html/rfc7638) of the key
+
+Currently only `EC` and `RSA` key storage is supported. All provided parameters
+will be stored in the database, but only generic JWK parameters and parameters
+specified as part of the public key for the `kty` by the
+[JWA](https://tools.ietf.org/html/rfc7518#section-6) will be given back by the
+GET request. This is to avoid compromising a key if the private portion or any
+other potentially sensitive fields are given to us.
+
+TODO: we need to somehow associate a key with a particular user without needing
+the issuer's subject. Resources providers will not have that subject but will
+need to be able to retrieve only public keys that actually belong to the user
+that are trying to validate.
 
-The jwk endpoint needs to reveal the jwk by thumbprint as well as some