Sagittarius Users' Reference

(rfc jwk) - Json Web Key

This library provides Json Web Key (JWK) APIs. JWS is defined in RFC 7517.

This library also supports OKP defined in RFC 8037.

This library also supports curve secp256k1 RFC 8812, as well as the P-256K which is defined in the draft 00 of the RFC.

The following examples show how to interact with keys from (sagittarius crypto keys) library.

;; (sagittarius crypto keys) keys to JWK/JWKS
(import (rnrs)
        (sagittarius crypto keys)
        (rfc jwk))

(define keypair (generate-key-pair *key:ed25519*))

(define private-key (key-pair-private keypair))

(define jwk-config (jwk-config-builder (kid "my key id")))

(let ((jwks (make-jwk-set (list (key->jwk private-key jwk-config)))))
  (jwk-set->json-string jwks) ;; -> {"keys":[{"kid":"my key id",...}]}
  (jwk-set:find-key jwks (jwk-matcher:kid "my key id")) ;; -> #<jwk>
  (jwk-set->public-jwk-set jwks)) ;; -> #<jwk-set> contains only public key

;; JWK/JWKS to (sagittarius crypto keys) key
(import (rnrs)
        (sagittarius crypto keys)
        (rfc jwk))

;; JWKS with EC private key
(define jwks-json
  #(("keys"
     #(("kty" . "EC")
       ("crv" . "P-256")
       ("x"   . "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4")
       ("y"   . "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM")
       ("d"   . "870MB6gfuTJ4HtUnUvYMyJpr5eUZNP4Bk43bVdj3eAE")
       ("use" . "enc")
       ("kid" . "1")))))
(define jwks (json->jwk-set jwks-json))
(define kid-matcher (jwk-matcher:kid "1"))

(define jwk (jwk-set:find-key jwks kid-matcher))

(jwk->public-key jwk)   ;; -> ECDSA public key
(jwk->private-key jwk)  ;; -> ECDSA private key

JWK Set

JWK Set (JWKS) is an object represents a set of JWKs.

Function jwk-set? obj

Returns #t if the given obj is a JWKS object otherwise #f.

Function make-jwk-set keys

Construct a newly allocated JWKS object whose keys are keys.

keys must be a list of JWK objects.

Function jwk-set-keys jwk-set

Retrieves a list of JWKs from the given jwk-set.

Function json->jwk-set obj

Function read-jwk-set

Function read-jwk-set port

Function json-string->jwk-set string

Construct JWKS from S-exp JSON representation of obj, from input port port or a string string.

If the first form of read-jwk-set is used, then it reads from current input port.

Function jwk-set->json jwk-set

Function write-jwk-set jwk-set

Function write-jwk-set jwk-set port

Function jwk-set->json-string jwk-set

Serialize the given jwk-set to a S-exp representaion, to port or string.

If first form of write-jwk-set is used, then it writes the serialized JWK set to current output port.

Function jwk-set:find-key jwk-set jwk-matcher

Finds a key which matches to jwk-matcher from given jwk-set.

JWK Matcher

A JWK matcher is a procedure takes one argument, jwk, and returns the given jwk if it matches the condition otherwise returns #f.

The matchers provided by this library complies to the above so that users can compose matchers like this:

(import (rnrs)
        (rfc jwk)
        (sagittarius combinators))

(define kid/alg-matcher
 (compose (jwk-matcher:kid "kid") (jwk-matcher:alg 'EdDSA)))

Function jwk-matcher:kty obj

Function jwk-matcher:use obj

Function jwk-matcher:alg obj

Function jwk-matcher:kid obj

Function jwk-matcher:x5t obj

Function jwk-matcher:x5t-s256 obj

Function jwk-matcher:crv obj

Creates a JWK matcher which checks kty, use, alg, kid, x5t, x5t-s256 or crv field of the target JWK is equal to obj, respectively.

Function jwk-matcher:key-ops obj

Creates a JWK matcher which checks key-ops field of the target JWK contains given obj.

Function jwk-matcher:rsa jwk

Function jwk-matcher:ec jwk

Function jwk-matcher:oct jwk

Function jwk-matcher:okp jwk

Convenient JWK matchers which check kty to be RSA, EC, oct or OKP, respectively.

JWK

JWK is an object which contains key information. The object contains the following fields:

kty: key type, symbol
use: key usage, symbol, must be either sig or enc
key-ops: key operation, a list of symbols
alg: key algorithm, symbol
kid: key ID
x5u: URL of certificate
x5c: Certificate chain, list of x509 certificate
x5t: SHA-1 certificate finger print, bytevector
x5t-s256: SHA-256 certificate finger print, bytevector

Function jwk? obj

Returns #t if the given obj is a JWK object otherwise #f.

Function jwk-kty jwk

Function jwk-use jwk

Function jwk-key-ops jwk

Function jwk-alg jwk

Function jwk-kid jwk

Function jwk-x5u jwk

Function jwk-x5c jwk

Function jwk-x5t jwk

Function jwk-x5t-s256 jwk

Retrieves the field value of jwk.

Function json->jwk obj

Function read-jwk

Function read-jwk :optional port

Function json-string->jwk string

Construct JWK from S-exp JSON representation of obj, from input port port or a string string.

If the first form of read-jwk is used, then it reads from current input port.

Function jwk->json jwk

Function write-jwk jwk

Function write-jwk jwk port

Function jwk->json-string jwk

Serialize the given jwk to a S-exp representaion, to port or string.

If first form of write-jwk is used, then it writes the serialized JWK to current output port.

From JWK Conversion

The below conversion procedures raise an error if the conversion is not possible. For example, key type oct can't be public key.

Function jwk->public-key jwk

Function jwk->private-key jwk

Convert given jwk to (sagittarius crypto keys) public key and private key, respectively.

Function jwk->octet-key jwk

Convert given jwk to octet key bytevector.

Function jwk->public-jwk jwk

Convert given jwk to JWK which only contains public key information.

To JWK Conversion

Function jwk:config? obj

Returns #t if the given obj is a JWK config object otherwise #f.

JWK may contain meta data, such as kid, to provide the information, users can use JWK config object. The object has the below fields:

use: key usage, symbol, must be either sig or enc
kid: key ID
key-ops: key operation, a list of symbols
alg: key algorithm, symbol
x5u: URL of certificate
x5c: Certificate chain, list of x509 certificate
e: RSA public key exponent

e is provided due to the historical reason of not to have public exponent in non CRT RSA private key. By default, the value is 65537.

Macro jwk-config-builder

A builder macro of JWK config. The macro is generated by (record builder). see (record builder)for more details.

Function jwk->jwk-config jwk

Construct JWK config from given jwk.

Function key->jwk key

Function key->jwk key jwk-config

Converts given key to JWK object.

If the second form is used, then the returning JWK contains the configured information.

The key must be one of public key, private key, or secret key of (sagittarius crypto keys).