71 lines
2.6 KiB
Markdown
71 lines
2.6 KiB
Markdown
# Nim JWT
|
|
|
|
This is a standards-compliant implementation of the JWT, JWK, JWS, and JWE
|
|
standards in Nim, using the [BearSSL](https://www.bearssl.org/) library to
|
|
provide the underlying cryptographic primatives.
|
|
|
|
## JWK ownership and threads
|
|
|
|
`JWK` and `JwkSet` have value semantics. Parsed keys own their key material and
|
|
metadata; changing the input `JsonNode` after `initJwk` or `initJwkSet` does not
|
|
change the keys. Assigning a key, key set, or `Table[string, JwkSet]` produces an
|
|
independent value suitable for handing to a worker thread. Synchronize access
|
|
to any source value that another thread may be modifying.
|
|
|
|
The typed accessors (`kid`, `alg`, `rsaPrv`, etc.) return values. The JSON member
|
|
accessor, `key["member"]`, keeps its `Option[JsonNode]` return type, but each call
|
|
returns a fresh node. Mutating that node does not update the key; construct a
|
|
new key with `initJwk` to change it. Missing members return `none`, while an
|
|
explicit JSON null returns `some` containing a `JNull` node.
|
|
Use `%key` to serialize a complete key, including extension members, to an
|
|
independent JSON object.
|
|
|
|
Internally, arbitrary JSON members are stored as encoded strings in a value
|
|
table. Only JSON member lookups decode them. Signing and verification use the
|
|
parsed key fields directly. This ownership guarantee applies to `JWK` and
|
|
`JwkSet`; JWT claims and JOSE headers retain their existing ownership behavior.
|
|
|
|
Run `nimble unittest` to run the suite, including worker-thread tests, under
|
|
both ARC and ORC.
|
|
|
|
## Supported Algorithms (JWA)
|
|
|
|
[RFC7518 (JWA)][rfc7518] registers
|
|
cryptographic algorithms and identifiers to be used with the JSON Web Signature
|
|
(JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK) specifications.
|
|
|
|
This library supports all REQUIRED algorithms. Specifically, the following
|
|
algorithms are supported:
|
|
|
|
### Digital Signature and MACs (JWS)
|
|
|
|
From [RFC7518 section 3][rfc7518-s3] the following algorithms are supported:
|
|
|
|
* *TBD*
|
|
|
|
### Key Management
|
|
|
|
From [RFC7518 section 4][rfc7518-s4] the following algorithms are supported:
|
|
|
|
* *TBD*
|
|
|
|
### Content Encryption
|
|
|
|
From [RFC7518 section 5][rfc7518-s5] the following algorithms are supported:
|
|
|
|
* *TBD*
|
|
|
|
### Keys
|
|
|
|
From [RFC7518 section 6][rfc7518-s6] the following key types are supported:
|
|
|
|
* EC
|
|
* RSA
|
|
* otc
|
|
|
|
[rfc7518]: https://datatracker.ietf.org/doc/html/rfc7518
|
|
[rfc7518-s3]: https://datatracker.ietf.org/doc/html/rfc7518#section-3
|
|
[rfc7518-s4]: https://datatracker.ietf.org/doc/html/rfc7518#section-4
|
|
[rfc7518-s5]: https://datatracker.ietf.org/doc/html/rfc7518#section-5
|
|
[rfc7518-s6]: https://datatracker.ietf.org/doc/html/rfc7518#section-6
|