jose-jwt: JSON Object Signing and Encryption Library
This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.
Warnings:
- Packages relying on Cabal 1.12 or later should specify a specific version of the Cabal spec of the form 'cabal-version: x.y'. Use 'cabal-version: 1.16'.
An implementation of the JOSE suite of IETF standards and the closely related JWT (JSON web token) spec (https://tools.ietf.org/html/rfc7519/).
Both signed and encrypted JWTs are supported, as well as simple JWK keys.
[Skip to Readme]
Properties
| Versions | 0.1, 0.2, 0.3, 0.3.1, 0.4, 0.4.1, 0.4.1.1, 0.4.2, 0.5, 0.6, 0.6.1, 0.6.2, 0.7, 0.7.1, 0.7.2, 0.7.3, 0.7.4, 0.7.5, 0.7.6, 0.7.7, 0.7.8, 0.8.0, 0.9.0, 0.9.0, 0.9.1, 0.9.2, 0.9.3, 0.9.4, 0.9.5, 0.9.6, 0.10.0 |
|---|---|
| Change log | CHANGELOG.md |
| Dependencies | aeson (>=0.8.0.2), attoparsec (>=0.12.0.0), base (>=4.9 && <5), bytestring (>=0.9), cereal (>=0.4), containers (>=0.4), cryptonite (>=0.19), memory (>=0.10), mtl (>=2.1.3.1), text (>=0.11), time (>=1.4), transformers (>=0.3), transformers-compat (>=0.4), unordered-containers (>=0.2), vector (>=0.10) [details] |
| License | BSD-3-Clause |
| Author | Luke Taylor <tekul.hs@gmail.com> |
| Maintainer | Luke Taylor <tekul.hs@gmail.com> |
| Category | JSON, Cryptography |
| Home page | http://github.com/tekul/jose-jwt |
| Bug tracker | http://github.com/tekul/jose-jwt/issues |
| Source repo | head: git clone https://github.com/tekul/jose-jwt.git |
| Uploaded | by LukeTaylor at 2021-01-26T22:49:12Z |
Modules
[Index] [Quick Jump]
- Jose
- Internal
- Jose.Internal.Base64
- Jose.Internal.Crypto
- Jose.Internal.Parser
- Jose.Jwa
- Jose.Jwe
- Jose.Jwk
- Jose.Jws
- Jose.Jwt
- Internal
Flags
Manual Flags
| Name | Description | Default |
|---|---|---|
| doctest | Disabled |
Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info
Downloads
- jose-jwt-0.9.0.tar.gz [browse] (Cabal source package)
- Package description (as included in the package)
Maintainer's Corner
Package maintainers
For package maintainers and hackage trustees
Readme for jose-jwt-0.9.0
[back to package description]jose-jwt
A Haskell implementation of the JSON Object Signing and Encryption (JOSE) specifications and the related JWT specification, as used, for example, in OpenID Connect.
Background
The JWT specification was split into JWS and JWE during its development and thus does not contain much. Basically, a JWT is either a JWS or a JWE depending on whether it is signed or encrypted. It is encoded as a sequence of base64 strings separated by '.' characters [1].
Technically, the content of a JWT should be JSON (unless it's a nested JWT), but the library doesn't care - it only requires a bytestring. The calling application should verify that the content is valid. Exactly what that means will depend on what you are using JWTs for.
Examples
You can either use the high-level encode and decode functions in the Jwt module or specific functions in the Jws and Jwe modules.
The following examples can be entered directly into ghci. Use
> :set -XOverloadedStrings
to begin with.
JWS signing example with a symmetric HMAC algorithm
HMAC is a good choice when both signer and verifier have a copy of the key.
> import Jose.Jws (hmacEncode, hmacDecode)
> import Jose.Jwa (JwsAlg(HS256))
>
> hmacEncode HS256 "aRANDOMlygeneratedkey" "my JSON message"
Right (Jwt {unJwt = "eyJhbGciOiJIUzI1NiJ9.bXkgSlNPTiBtZXNzYWdl.lTJx7ECLwYF3P7WbrrUpcp_2SdLiFXaDwK-PXcipt5Q"})
> hmacDecode "aRANDOMlygeneratedkey" "eyJhbGciOiJIUzI1NiJ9.bXkgSlNPTiBtZXNzYWdl.lTJx7ECLwYF3P7WbrrUpcp_2SdLiFXaDwK-PXcipt5Q"
Right (JwsHeader {jwsAlg = HS256, jwsTyp = Nothing, jwsCty = Nothing, jwsKid = Nothing},"my JSON message")
Trying to decode with a different key would return a Left BadSignature [2].
JWS signing using Ed25519 private key
Some situations require the use of public key cryptography for signing. For example, only a trusted party is allowed to create a signed token, but it must be verified by others.
Elliptic-curve EdDSA signing and verification are supported as defined in RFC 8037, as well as the older RSA JWS algorithms.
> import Jose.Jwt
> import Jose.Jwk
> import Jose.Jwa (JwsAlg(EdDSA))
> import Data.ByteString (ByteString)
> import Data.Aeson (decodeStrict)
>
> jsonJwk = "{\"kty\":\"OKP\", \"crv\":\"Ed25519\", \"d\":\"nWGxne_9WmC6hEr0kuwsxERJxWl7MmkZcDusAxyuf2A\", \"x\":\"11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo\"}" :: ByteString
> Just jwk = decodeStrict jsonJwk :: Maybe Jwk
> Jose.Jwt.encode [jwk] (JwsEncoding EdDSA) (Claims "public claims")
Right (Jwt {unJwt = "eyJhbGciOiJFZERTQSJ9.cHVibGljIGNsYWltcw.xYekeeGSQVpnQbl16lOCqFcmYsUj3goSTrZ4UBQqogjHLrvFUaVJ_StBqly-Tb-0xvayjUMM4INYBTwFMt_xAQ"})
To verify the JWT you would use the Jose.Jwt.decode function with the corresponding public key.
More examples can be found in the package documentation.
Build Status
[1] This is now referred to as "compact serialization". The additional "JSON serialization" is not supported in this library.
[2] Note that a real key for HMAC256 should be a much longer, random string of bytes. See, for example, this stackexchange answer.