Common Lisp system for decoding public JSON Web Keys (JWK)

cl-jwk

* cl-jwk

=cl-jwk= is a Common Lisp system for parsing public JSON Web Keys
(JWK).

The following JWK keys are supported by the system.

- =RSA=
- =EC P-256=
- =EC P-384=
- =EC P-521=
- =EC secp256k1=
- =oct= (symmetric key)

* Requirements

- [[https://www.quicklisp.org/beta/][Quicklisp]]

* Installation

Clone the repo in your [[https://www.quicklisp.org/beta/faq.html][Quicklisp local-projects]] directory.

#+begin_src lisp
(ql:register-local-projects)
#+end_src

Then load the system.

#+begin_src lisp
(ql:quickload :cl-jwk)
#+end_src

NOTE: =cl-jwk= uses features from latest =ironclad=, so make sure that
you are using the latest =ironclad= release from Github, until it gets
published on Quicklisp.

* Usage

In order to decode a public JWK key from a JSON object, simply call
the =CL-JWK:DECODE= generic function.

For instance, in order to decode one of the test keys used by the
=cl-jwk.test= system, you can call =CL-JWK:DECODE= like this.

#+begin_src lisp
  CL-USER> (defparameter *json-data*
             (uiop:read-file-string
              (asdf:system-relative-pathname :cl-jwk.test "tests/test-keys/rsa-3072-pub.json")))
  *JSON-DATA*
  CL-USER> (cl-jwk:decode :json *json-data*)
  #<CL-JWK.CORE:JWK {100510EB73}>
#+end_src

Upon successful decoding of the JSON data the =CL-JWK:DECODE= method
will return a =CL-JWK:JWK= class instance. Use the available readers
to get more details about the decoded public key. The following reader
methods are available for a =CL-JWK:JWK= instance.

- =CL-JWK:JWK-KTY=
- =CL-JWK:JWK-USE=
- =CL-JWK:JWK-KID=
- =CL-JWK:JWK-ALG=
- =CL-JWK:JWK-KEY-OPS=
- =CL-JWK:JWK-KEY=

The =CL-JWK:JWK-KEY= method returns an instance of an =ironclad=
public key.

You can also fetch public JWKs from an OpenID Provider. For example:

#+begin_src lisp
  CL-USER> (defparameter *client*
             (cl-jwk:make-client :hostname "accounts.google.com"))
  *CLIENT*
  CL-USER> (cl-jwk:public-keys *client*)
  (#<CL-JWK.CORE:JWK {10021B5FD3}> #<CL-JWK.CORE:JWK {10021B6053}>
   #<CL-JWK.CORE:JWK {10021B60D3}>)
#+end_src

Token verification can be done using the =CL-JWK:VERIFY-TOKEN= generic
function. =CL-JWK:VERIFY-TOKEN= is implemented for both =CL-JWK:JWK=
and =CL-JWK:CLIENT= classes.

* Tests

The =cl-jwk= tests are provided as part of the
=:cl-jwk.test= system.

In order to run the tests you can evaluate the following expressions.

#+begin_src lisp
CL-USER> (ql:quickload :cl-jwk.test)
CL-USER> (asdf:test-system :cl-jwk.test)
#+end_src

Or you can run the tests using the =scripts/run-tests.sh= shell script
instead, e.g.

#+begin_src shell
env LISP=sbcl ./scripts/run-tests.sh
#+end_src

* Contributing

=cl-jwk= is hosted on [[https://github.com/dnaeon/cl-jwk][Github]]. Please contribute by reporting
issues, suggesting features or by sending patches using pull requests.

* Authors

- Marin Atanasov Nikolov <[[mailto:dnaeon@gmail.com][dnaeon@gmail.com]]>

* License

This project is Open Source and licensed under the [[http://opensource.org/licenses/BSD-2-Clause][BSD License]].


cl-jwk

Upstream URL

Author

Maintainer

License

cl-jwk

Version:

License:

Authors:

Maintainers:

Dependencies:

cl-jwk.test

Version:

License:

Authors:

Maintainers:

Dependencies:

Dependencies (8)

Dependents (0)