jose-jwt-0.10.0: JSON Object Signing and Encryption Library
Safe HaskellSafe-Inferred
LanguageHaskell2010

Jose.Jwt

Description

High-level JWT encoding and decoding.

See the Jose.Jws and Jose.Jwe modules for specific JWS and JWE examples.

Example usage with a key stored as a JWK:

>>> import Jose.Jwe
>>> import Jose.Jwa
>>> import Jose.Jwk
>>> import Data.ByteString
>>> import Data.Aeson (decodeStrict)
>>> let jsonJwk = "{\"kty\":\"RSA\", \"kid\":\"mykey\", \"n\":\"ofgWCuLjybRlzo0tZWJjNiuSfb4p4fAkd_wWJcyQoTbji9k0l8W26mPddxHmfHQp-Vaw-4qPCJrcS2mJPMEzP1Pt0Bm4d4QlL-yRT-SFd2lZS-pCgNMsD1W_YpRPEwOWvG6b32690r2jZ47soMZo9wGzjb_7OMg0LOL-bSf63kpaSHSXndS5z5rexMdbBYUsLA9e-KXBdQOS-UTo7WTBEMa2R2CapHg665xsmtdVMTBQY4uDZlxvb3qCo5ZwKh9kG4LT6_I5IhlJH7aGhyxXFvUK-DWNmoudF8NAco9_h9iaGNj8q2ethFkMLs91kzk2PAcDTW9gb54h4FRWyuXpoQ\", \"e\":\"AQAB\", \"d\":\"Eq5xpGnNCivDflJsRQBXHx1hdR1k6Ulwe2JZD50LpXyWPEAeP88vLNO97IjlA7_GQ5sLKMgvfTeXZx9SE-7YwVol2NXOoAJe46sui395IW_GO-pWJ1O0BkTGoVEn2bKVRUCgu-GjBVaYLU6f3l9kJfFNS3E0QbVdxzubSu3Mkqzjkn439X0M_V51gfpRLI9JYanrC4D4qAdGcopV_0ZHHzQlBjudU2QvXt4ehNYTCBr6XCLQUShb1juUO1ZdiYoFaFQT5Tw8bGUl_x_jTj3ccPDVZFD9pIuhLhBOneufuBiB4cS98l2SR_RQyGWSeWjnczT0QU91p1DhOVRuOopznQ\"}" :: ByteString
>>> let Just jwk = decodeStrict jsonJwk :: Maybe Jwk
>>> Right (Jwt jwtEncoded) <- encode [jwk] (JwsEncoding RS256) (Claims "public claims")
>>> Right jwtDecoded <- Jose.Jwt.decode [jwk] (Just (JwsEncoding RS256)) jwtEncoded
>>> jwtDecoded
Jws (JwsHeader {jwsAlg = RS256, jwsTyp = Nothing, jwsCty = Nothing, jwsKid = Just (KeyId "mykey")},"public claims")
Synopsis

Documentation

newtype Jwt Source #

An encoded JWT.

Constructors

Jwt 

Fields

Instances

Instances details
FromJSON Jwt Source # 
Instance details

Defined in Jose.Types

ToJSON Jwt Source # 
Instance details

Defined in Jose.Types

Show Jwt Source # 
Instance details

Defined in Jose.Types

Methods

showsPrec :: Int -> Jwt -> ShowS #

show :: Jwt -> String #

showList :: [Jwt] -> ShowS #

Eq Jwt Source # 
Instance details

Defined in Jose.Types

Methods

(==) :: Jwt -> Jwt -> Bool #

(/=) :: Jwt -> Jwt -> Bool #

type Jwe = (JweHeader, ByteString) Source #

The header and claims of a decoded JWE.

type Jws = (JwsHeader, ByteString) Source #

The header and claims of a decoded JWS.

data JwtClaims Source #

Registered claims defined in section 4 of the JWT spec.

Constructors

JwtClaims 

Fields

Instances

Instances details
FromJSON JwtClaims Source # 
Instance details

Defined in Jose.Types

ToJSON JwtClaims Source # 
Instance details

Defined in Jose.Types

Generic JwtClaims Source # 
Instance details

Defined in Jose.Types

Associated Types

type Rep JwtClaims :: Type -> Type #

Show JwtClaims Source # 
Instance details

Defined in Jose.Types

type Rep JwtClaims Source # 
Instance details

Defined in Jose.Types

data JwsHeader Source #

Header content for a JWS.

Constructors

JwsHeader 

Instances

Instances details
FromJSON JwsHeader Source # 
Instance details

Defined in Jose.Types

ToJSON JwsHeader Source # 
Instance details

Defined in Jose.Types

Generic JwsHeader Source # 
Instance details

Defined in Jose.Types

Associated Types

type Rep JwsHeader :: Type -> Type #

Show JwsHeader Source # 
Instance details

Defined in Jose.Types

Eq JwsHeader Source # 
Instance details

Defined in Jose.Types

type Rep JwsHeader Source # 
Instance details

Defined in Jose.Types

data JweHeader Source #

Header content for a JWE.

Instances

Instances details
FromJSON JweHeader Source # 
Instance details

Defined in Jose.Types

ToJSON JweHeader Source # 
Instance details

Defined in Jose.Types

Generic JweHeader Source # 
Instance details

Defined in Jose.Types

Associated Types

type Rep JweHeader :: Type -> Type #

Show JweHeader Source # 
Instance details

Defined in Jose.Types

Eq JweHeader Source # 
Instance details

Defined in Jose.Types

type Rep JweHeader Source # 
Instance details

Defined in Jose.Types

data JwtContent Source #

A decoded JWT which can be either a JWE or a JWS, or an unsecured JWT.

Constructors

Unsecured !ByteString 
Jws !Jws 
Jwe !Jwe 

Instances

Instances details
Show JwtContent Source # 
Instance details

Defined in Jose.Types

Eq JwtContent Source # 
Instance details

Defined in Jose.Types

data JwtEncoding Source #

Defines the encoding information for a JWT.

Used for both encoding new JWTs and validating existing ones.

Instances

Instances details
Show JwtEncoding Source # 
Instance details

Defined in Jose.Types

Eq JwtEncoding Source # 
Instance details

Defined in Jose.Types

data JwtError Source #

Decoding errors.

Constructors

KeyError Text

No suitable key or wrong key type

BadAlgorithm Text

The supplied algorithm is invalid

BadDots Int

Wrong number of "." characters in the JWT

BadHeader Text

Header couldn't be decoded or contains bad data

BadClaims

Claims part couldn't be decoded or contains bad data

BadSignature

Signature is invalid

BadCrypto

A cryptographic operation failed

Base64Error String

A base64 decoding error

Instances

Instances details
Show JwtError Source # 
Instance details

Defined in Jose.Types

Eq JwtError Source # 
Instance details

Defined in Jose.Types

data Payload Source #

The payload to be encoded in a JWT.

Constructors

Nested Jwt 
Claims ByteString 

Instances

Instances details
Show Payload Source # 
Instance details

Defined in Jose.Types

Eq Payload Source # 
Instance details

Defined in Jose.Types

Methods

(==) :: Payload -> Payload -> Bool #

(/=) :: Payload -> Payload -> Bool #

encode Source #

Arguments

:: MonadRandom m 
=> [Jwk]

The key or keys. At least one must be consistent with the chosen algorithm

-> JwtEncoding

The encoding algorithm(s) used to encode the payload

-> Payload

The payload (claims)

-> m (Either JwtError Jwt)

The encoded JWT, if successful

Use the supplied JWKs to create a JWT. The list of keys will be searched to locate one which is consistent with the chosen encoding algorithms.

decode Source #

Arguments

:: MonadRandom m 
=> [Jwk]

The keys to use for decoding

-> Maybe JwtEncoding

The expected encoding information

-> ByteString

The encoded JWT

-> m (Either JwtError JwtContent)

The decoded JWT payload, if successful

Uses the supplied keys to decode a JWT. Locates a matching key by header kid value where possible or by suitable key type for the encoding algorithm.

The algorithm(s) used can optionally be supplied for validation by setting the JwtEncoding parameter, in which case an error will be returned if they don't match. If you expect the tokens to use a particular algorithm, then you should set this parameter.

For unsecured tokens (with algorithm "none"), the expected algorithm must be set to Just (JwsEncoding None) or an error will be returned.

decodeClaims :: FromJSON a => ByteString -> Either JwtError (JwtHeader, a) Source #

Convenience function to return the claims contained in a JWS. This is needed in situations such as client assertion authentication, https://tools.ietf.org/html/rfc7523, where the contents of the JWT, such as the sub claim, may be required in order to work out which key should be used to verify the token.

Obviously this should not be used by itself to decode a token since no integrity checking is done and the contents may be forged.