This is the cl-jwk Reference Manual, version 0.1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 15:22:13 2024 GMT+0.
The main system appears first, followed by any subsystem dependency.
cl-jwkCommon Lisp system for decoding public JSON Web Keys (JWK)
cl-jwk
Marin Atanasov Nikolov <dnaeon@gmail.com>
Marin Atanasov Nikolov <dnaeon@gmail.com>
BSD 2-Clause
* 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]].
0.1.0
alexandria (system).
binascii (system).
cl-reexport (system).
dexador (system).
ironclad (system).
jonathan (system).
jose (system).
core (module).
client-package (module).
Modules are listed depth-first from the system components tree.
cl-jwk/client-packagecore (module).
cl-jwk (system).
package.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
cl-jwk/core/core.lispcore (module).
*user-agent* (special variable).
client (class).
client-api-prefix (reader method).
(setf client-api-prefix) (writer method).
client-hostname (reader method).
(setf client-hostname) (writer method).
client-port (reader method).
(setf client-port) (writer method).
client-scheme (reader method).
(setf client-scheme) (writer method).
decode (generic function).
invalid-key (condition).
invalid-key-data (reader method).
invalid-key-message (reader method).
jwk (class).
jwk-alg (reader method).
jwk-key (reader method).
jwk-key-ops (reader method).
jwk-kid (reader method).
jwk-kty (reader method).
jwk-use (reader method).
keywordize (function).
make-api-uri (generic function).
make-client (function).
openid-provider-metadata (generic function).
public-keys (generic function).
verify-token (generic function).
%get-hmac (function).
Packages are listed by definition order.
cl-jwk.corejwk.core
common-lisp.
*user-agent* (special variable).
client (class).
client-api-prefix (generic reader).
(setf client-api-prefix) (generic writer).
client-hostname (generic reader).
(setf client-hostname) (generic writer).
client-port (generic reader).
(setf client-port) (generic writer).
client-scheme (generic reader).
(setf client-scheme) (generic writer).
decode (generic function).
invalid-key (condition).
invalid-key-data (generic reader).
invalid-key-message (generic reader).
jwk (class).
jwk-alg (generic reader).
jwk-key (generic reader).
jwk-key-ops (generic reader).
jwk-kid (generic reader).
jwk-kty (generic reader).
jwk-use (generic reader).
keywordize (function).
make-api-uri (generic function).
make-client (function).
openid-provider-metadata (generic function).
public-keys (generic function).
verify-token (generic function).
%get-hmac (function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Returns a keyword from the given NAME
Creates a new client for interfacing with the CSP APIs
Decodes a JWK key of the given kind using the provided data
(eql :oct)) data) ¶Decodes a JWK ‘octet-sequence’ symmetric key from the given plist data. See RFC 7518, Section 6.4 for more details about Symmetric Keys format.
(eql :secp256k1)) data) ¶Decodes Secp256k1 public key from the given plist data.
See RFC 7518, Section 6.2.1 for more details about Elliptic Curve
public keys format.
(eql :secp521r1)) data) ¶Decodes Secp521r1 (NIST P-521) public key from the given plist data. See RFC 7518, Section 6.2.1 for more details about Elliptic Curve public keys format.
(eql :secp384r1)) data) ¶Decodes Secp384r1 (NIST P-384) public key from the given plist data. See RFC 7518, Section 6.2.1 for more details about Elliptic Curve public keys format.
(eql :secp256r1)) data) ¶Decodes Secp256r1 (NIST P-256) public key from the given plist data. See RFC 7518, Section 6.2.1 for more details about Elliptic Curve public keys format.
(eql :rsa)) data) ¶Decodes RSA public key using the provided plist data.
See RFC 7517 about the JWK format and RFC 7518, Section 6.3 about the
RSA key parameters.
(eql :ec)) data) ¶Decodes an Elliptic Curve public key from the given data
(eql :key)) data) ¶Decodes a JWK public key by inferring the key from the given plist data and dispatches further decoding to the respective implementation
(eql :json)) json-string) ¶Decodes JWK public key from the given JSON string
invalid-key)) ¶invalid-key)) ¶Returns an URI to the given API path
Returns the OpenID Provider Metadata
Returns the public keys used to verify the authenticity of tokens
Verifies and decodes the given JWT token
Condition which is signalled when an invalid key is detected
simple-error.
Human-friendly error message
(quote (error "must specify error message"))
:message
This slot is read-only.
The data of the invalid key
(quote (error "must specify key data"))
:data
This slot is read-only.
API client for interfacing with an OpenID Provider endpoint
Scheme to use
"https"
:scheme
Port to connect to
443
:port
Hostname to connect to
(error "must specify hostname")
:hostname
API prefix
""
:api-prefix
JWK represents a public JSON Web Key (JWK) as per RFC 7517
| Jump to: | %
(
C D F G I J K M O P V |
|---|
| Jump to: | %
(
C D F G I J K M O P V |
|---|
| Jump to: | *
A D H K M P S U |
|---|
| Jump to: | *
A D H K M P S U |
|---|
| Jump to: | C F I J M P S |
|---|
| Jump to: | C F I J M P S |
|---|