Next: , Previous: , Up: Top   [Contents][Index]


5 Managing keys

Some functions require a key, or a key pair, to operate. The (webid-oidc jwk) module provides you with everything required to manage keys.

Class: <private-key> () alg

This is the base class for a private key. You need it to issue signatures. Signatures issued with this key will use alg for the signature algorithm, but the public key associated with this private key will verify signatures in any compatible algorithm, not just alg.

alg is a symbol, for instance 'RS256.

Class: <public-key> ()

This is the base class for a public key. You need it to check signatures.

Class: <key-pair> () public-key private-key

A key pair contains a public-key and a matching private-key. You use this form for keys you own.

Class: <rsa-key-pair> () (<key-pair>)

This key pair contains matching RSA keys.

Class: <ec-key-pair> () (<key-pair>) crv

This key pair contains matching elliptic curve keys. crv is a symbol identifiying the curve.

Class: <rsa-private-key> (<private-key>) d p q dp dq qi
Class: <rsa-public-key> (<public-key>) n e
Class: <ec-scalar> (<private-key>) crv z
Class: <ec-point> (<public-key>) crv x y

All fields are strings, base64 encoding the parameters, except crv, which is a symbol.

Class: <jwks> () keys

An identity provider may use different keys that are in validity to sign different access tokens. The JWKS encapsulates many public keys.

Generic method: <public-key> public-key (key <key-pair>)
Generic method: <public-key> public-key (key <public-key>)

Return the public part of key, which may either be a key pair or a public key.

Generic method: <private-key> private-key (key <key-pair>)
Generic method: <private-key> private-key (key <private-key>)

Return the private part of key.

Generic method: <string> rsa-d (key <rsa-key-pair>)
Generic method: <string> rsa-d (key <rsa-private-key>)
Generic method: <string> rsa-p (key <rsa-key-pair>)
Generic method: <string> rsa-p (key <rsa-private-key>)
Generic method: <string> rsa-q (key <rsa-key-pair>)
Generic method: <string> rsa-q (key <rsa-private-key>)
Generic method: <string> rsa-dp (key <rsa-key-pair>)
Generic method: <string> rsa-dp (key <rsa-private-key>)
Generic method: <string> rsa-dq (key <rsa-key-pair>)
Generic method: <string> rsa-dq (key <rsa-private-key>)
Generic method: <string> rsa-qi (key <rsa-key-pair>)
Generic method: <string> rsa-qi (key <rsa-private-key>)
Generic method: <string> rsa-n (key <rsa-key-pair>)
Generic method: <string> rsa-n (key <rsa-public-key>)
Generic method: <string> rsa-e (key <rsa-key-pair>)
Generic method: <string> rsa-e (key <rsa-public-key>)
Generic method: <symbol> ec-crv (key <ec-key-pair>)
Generic method: <symbol> ec-crv (key <ec-point>)
Generic method: <symbol> ec-crv (key <ec-scalar>)
Generic method: <string> ec-x (key <ec-key-pair>)
Generic method: <string> ec-x (key <ec-point>)
Generic method: <string> ec-y (key <ec-key-pair>)
Generic method: <string> ec-y (key <ec-point>)
Generic method: <string> ec-z (key <ec-key-pair>)
Generic method: <string> ec-z (key <ec-scalar>)
Generic method: <symbol> alg (key <key-pair>)
Generic method: <symbol> alg (key <private-key>)

Key parameter getters.

Generic method: <list> keys (jwks <jwks>)

Return all the public keys used by jwks.

Generic method: <undefined> check-key (key <public-key>)
Generic method: <undefined> check-key (key <private-key>)
Generic method: <undefined> check-key (key <key-pair>)

Check that the key parameters are consistent.

When exchanging keys, maybe you will have them in the form of a JWK: an alist from symbols to strings, as a representation for a JSON object.

Generic method: <list> key->jwk (key <public-key>)
Generic method: <list> key->jwk (key <private-key>)
Generic method: <list> key->jwk (key <key-pair>)

Return an alist with known parameter names for JSON.

function: jwk->key jwk

Parse jwk as a key or a key pair.

Generic method: <symbol> kty (key <rsa-key-pair>)
Generic method: <symbol> kty (key <rsa-public-key>)
Generic method: <symbol> kty (key <rsa-private-key>)
Generic method: <symbol> kty (key <ec-key-pair>)
Generic method: <symbol> kty (key <ec-point>)
Generic method: <symbol> kty (key <ec-scalar>)

Return 'RSA for RSA keys, or 'EC for elliptic curve keys.

Generic method: <string> jkt (key <key-pair>)
Generic method: <string> jkt (key <public-key>)

Hash the key parameters in a reproducible order to get the hash of a key.

function: generate-key [#:n-size] [#:e-size] [#:e=\"AQAB\"] [#:crv]

Generate a new key pair.

Generic method: <values> serve (jwks <jwks>) expiration-date

Return a response and response body for serving jwks. Client-side caching is very much necessary for a JWKS, so pass expiration-date as a SRFI-19 date to define a maximum date for caching. It should be in the future, for instance in 1 hour.

function: get-jwks uri [#:http-request]

Download a JWKS on the web at uri. Use http-request, with the same interface as that of (web client), to actually get the JWKS.

Exception type: &not-a-jwk

If the key parameters are incorrect, this exception is raised.

Exception type: &not-a-jwks

If the JWKS cannot be downloaded, or is incorrect, this exception is raised.


Next: , Previous: , Up: Top   [Contents][Index]