-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | JSON Object Signing and Encryption Library
--   
--   An implementation of the JOSE suite of IETF standards and the closely
--   related JWT (JSON web token) spec
--   (<a>https://tools.ietf.org/html/rfc7519/</a>).
--   
--   Both signed and encrypted JWTs are supported, as well as simple JWK
--   keys.
@package jose-jwt
@version 0.7.8

module Jose.Jwa

-- | General representation of the <tt>alg</tt> JWT header value.
data Alg
Signed :: JwsAlg -> Alg
Encrypted :: JweAlg -> Alg

-- | A subset of the signature algorithms from the <a>JWA Spec</a>.
data JwsAlg
None :: JwsAlg
HS256 :: JwsAlg
HS384 :: JwsAlg
HS512 :: JwsAlg
RS256 :: JwsAlg
RS384 :: JwsAlg
RS512 :: JwsAlg
ES256 :: JwsAlg
ES384 :: JwsAlg
ES512 :: JwsAlg

-- | A subset of the key management algorithms from the <a>JWA Spec</a>.
data JweAlg
RSA1_5 :: JweAlg
RSA_OAEP :: JweAlg
A128KW :: JweAlg
A192KW :: JweAlg
A256KW :: JweAlg

-- | Content encryption algorithms from the <a>JWA Spec</a>.
data Enc
A128CBC_HS256 :: Enc
A192CBC_HS384 :: Enc
A256CBC_HS512 :: Enc
A128GCM :: Enc
A192GCM :: Enc
A256GCM :: Enc
instance GHC.Show.Show Jose.Jwa.Enc
instance GHC.Classes.Eq Jose.Jwa.Enc
instance GHC.Show.Show Jose.Jwa.Alg
instance GHC.Classes.Eq Jose.Jwa.Alg
instance GHC.Read.Read Jose.Jwa.JweAlg
instance GHC.Show.Show Jose.Jwa.JweAlg
instance GHC.Classes.Eq Jose.Jwa.JweAlg
instance GHC.Read.Read Jose.Jwa.JwsAlg
instance GHC.Show.Show Jose.Jwa.JwsAlg
instance GHC.Classes.Eq Jose.Jwa.JwsAlg
instance Data.Aeson.Types.FromJSON.FromJSON Jose.Jwa.Enc
instance Data.Aeson.Types.ToJSON.ToJSON Jose.Jwa.Enc
instance Data.Aeson.Types.FromJSON.FromJSON Jose.Jwa.Alg
instance Data.Aeson.Types.ToJSON.ToJSON Jose.Jwa.Alg
instance Data.Aeson.Types.FromJSON.FromJSON Jose.Jwa.JwsAlg
instance Data.Aeson.Types.ToJSON.ToJSON Jose.Jwa.JwsAlg
instance Data.Aeson.Types.FromJSON.FromJSON Jose.Jwa.JweAlg
instance Data.Aeson.Types.ToJSON.ToJSON Jose.Jwa.JweAlg


-- | Parses encoded JWTs into data structures which can be handled
module Jose.Internal.Parser


-- | Internal functions for encrypting and signing / decrypting and
--   verifying JWT content.
module Jose.Internal.Crypto

-- | Sign a message with an HMAC key.
hmacSign :: JwsAlg -> ByteString -> ByteString -> Either JwtError ByteString

-- | Verify the HMAC for a given message. Returns false if the MAC is
--   incorrect or the <a>Alg</a> is not an HMAC.
hmacVerify :: JwsAlg -> ByteString -> ByteString -> ByteString -> Bool

-- | Sign a message using an RSA private key.
--   
--   The failure condition should only occur if the algorithm is not an RSA
--   algorithm, or the RSA key is too small, causing the padding of the
--   signature to fail. With real-world RSA keys this shouldn't happen in
--   practice.
rsaSign :: Maybe Blinder -> JwsAlg -> PrivateKey -> ByteString -> Either JwtError ByteString

-- | Verify the signature for a message using an RSA public key.
--   
--   Returns false if the check fails or if the <a>Alg</a> value is not an
--   RSA signature algorithm.
rsaVerify :: JwsAlg -> PublicKey -> ByteString -> ByteString -> Bool

-- | Encrypts a message (typically a symmetric key) using RSA.
rsaEncrypt :: (MonadRandom m, ByteArray msg, ByteArray out) => PublicKey -> JweAlg -> msg -> m (Either JwtError out)

-- | Decrypts an RSA encrypted message.
rsaDecrypt :: ByteArray ct => Maybe Blinder -> PrivateKey -> JweAlg -> ct -> Either JwtError ScrubbedBytes

-- | Verify the signature for a message using an EC public key.
--   
--   Returns false if the check fails or if the <a>Alg</a> value is not an
--   EC signature algorithm.
ecVerify :: JwsAlg -> PublicKey -> ByteString -> ByteString -> Bool

-- | Encrypt a message using AES.
encryptPayload :: forall ba iv. (ByteArray ba, ByteArray iv) => Enc -> ScrubbedBytes -> iv -> ba -> ba -> Maybe (AuthTag, ba)

-- | Decrypt an AES encrypted message.
decryptPayload :: forall ba. (ByteArray ba) => Enc -> ScrubbedBytes -> IV -> ba -> Tag -> ba -> Maybe ba

-- | Generates the symmetric key (content management key) and IV
--   
--   Used to encrypt a message.
generateCmkAndIV :: MonadRandom m => Enc -> m (ScrubbedBytes, ScrubbedBytes)

-- | <a>https://tools.ietf.org/html/rfc3394#section-2.2.1</a>
keyWrap :: ByteArray ba => JweAlg -> ScrubbedBytes -> ScrubbedBytes -> Either JwtError ba

module Jose.Jwk
instance GHC.Generics.Generic Jose.Jwk.JwkData
instance GHC.Show.Show Jose.Jwk.JwkBytes
instance GHC.Generics.Generic Jose.Jwk.JwkSet
instance GHC.Classes.Eq Jose.Jwk.JwkSet
instance GHC.Show.Show Jose.Jwk.JwkSet
instance GHC.Classes.Eq Jose.Jwk.Jwk
instance GHC.Show.Show Jose.Jwk.Jwk
instance GHC.Show.Show Jose.Jwk.KeyUse
instance GHC.Classes.Eq Jose.Jwk.KeyUse
instance GHC.Show.Show Jose.Jwk.EcCurve
instance GHC.Classes.Eq Jose.Jwk.EcCurve
instance GHC.Classes.Eq Jose.Jwk.KeyType
instance Data.Aeson.Types.FromJSON.FromJSON Jose.Jwk.Jwk
instance Data.Aeson.Types.ToJSON.ToJSON Jose.Jwk.Jwk
instance Data.Aeson.Types.FromJSON.FromJSON Jose.Jwk.JwkData
instance Data.Aeson.Types.ToJSON.ToJSON Jose.Jwk.JwkData
instance Data.Aeson.Types.FromJSON.FromJSON Jose.Jwk.JwkBytes
instance Data.Aeson.Types.ToJSON.ToJSON Jose.Jwk.JwkBytes
instance Data.Aeson.Types.ToJSON.ToJSON Jose.Jwk.JwkSet
instance Data.Aeson.Types.FromJSON.FromJSON Jose.Jwk.JwkSet
instance Data.Aeson.Types.FromJSON.FromJSON Jose.Jwk.KeyUse
instance Data.Aeson.Types.ToJSON.ToJSON Jose.Jwk.KeyUse
instance Data.Aeson.Types.FromJSON.FromJSON Jose.Jwk.EcCurve
instance Data.Aeson.Types.ToJSON.ToJSON Jose.Jwk.EcCurve
instance Data.Aeson.Types.FromJSON.FromJSON Jose.Jwk.KeyType
instance Data.Aeson.Types.ToJSON.ToJSON Jose.Jwk.KeyType


-- | JWS HMAC and RSA signed token support.
--   
--   Example usage with HMAC:
--   
--   <pre>
--   &gt;&gt;&gt; import Jose.Jws
--   
--   &gt;&gt;&gt; import Jose.Jwa
--   
--   &gt;&gt;&gt; let Right (Jwt jwt) = hmacEncode HS256 "secretmackey" "public claims"
--   
--   &gt;&gt;&gt; jwt
--   "eyJhbGciOiJIUzI1NiJ9.cHVibGljIGNsYWltcw.GDV7RdBrCYfCtFCZZGPy_sWry4GwfX3ckMywXUyxBsc"
--   
--   &gt;&gt;&gt; hmacDecode "wrongkey" jwt
--   Left BadSignature
--   
--   &gt;&gt;&gt; hmacDecode "secretmackey" jwt
--   Right (JwsHeader {jwsAlg = HS256, jwsTyp = Nothing, jwsCty = Nothing, jwsKid = Nothing},"public claims")
--   </pre>
module Jose.Jws

-- | Create a JWS signed with a JWK. The key and algorithm must be
--   consistent or an error will be returned.
jwkEncode :: MonadRandom m => JwsAlg -> Jwk -> Payload -> m (Either JwtError Jwt)

-- | Create a JWS with an HMAC for validation.
hmacEncode :: JwsAlg -> ByteString -> ByteString -> Either JwtError Jwt

-- | Decodes and validates an HMAC signed JWS.
hmacDecode :: ByteString -> ByteString -> Either JwtError Jws

-- | Creates a JWS with an RSA signature.
rsaEncode :: MonadRandom m => JwsAlg -> PrivateKey -> ByteString -> m (Either JwtError Jwt)

-- | Decode and validate an RSA signed JWS.
rsaDecode :: PublicKey -> ByteString -> Either JwtError Jws

-- | Decode and validate an EC signed JWS
ecDecode :: PublicKey -> ByteString -> Either JwtError Jws


-- | JWE encrypted token support.
--   
--   To create a JWE, you need to select two algorithms. One is an AES
--   algorithm used to encrypt the content of your token (for example,
--   <tt>A128GCM</tt>), for which a single-use key is generated internally.
--   The second is used to encrypt this content-encryption key and can be
--   either an RSA or AES-keywrap algorithm. You need to generate a
--   suitable key to use with this, or load one from storage.
--   
--   AES is much faster and creates shorter tokens, but both the encoder
--   and decoder of the token need to have a copy of the key, which they
--   must keep secret. With RSA anyone can send you a JWE if they have a
--   copy of your public key.
--   
--   In the example below, we show encoding and decoding using a 512 byte
--   RSA key pair (in practice you would use a larger key-size, for example
--   2048 bytes):
--   
--   <pre>
--   &gt;&gt;&gt; import Jose.Jwe
--   
--   &gt;&gt;&gt; import Jose.Jwa
--   
--   &gt;&gt;&gt; import Jose.Jwk (generateRsaKeyPair, generateSymmetricKey, KeyUse(Enc), KeyId)
--   
--   &gt;&gt;&gt; (kPub, kPr) &lt;- generateRsaKeyPair 512 (KeyId "My RSA Key") Enc Nothing
--   
--   &gt;&gt;&gt; Right (Jwt jwt) &lt;- jwkEncode RSA_OAEP A128GCM kPub (Claims "secret claims")
--   
--   &gt;&gt;&gt; Right (Jwe (hdr, claims)) &lt;- jwkDecode kPr jwt
--   
--   &gt;&gt;&gt; claims
--   "secret claims"
--   </pre>
--   
--   Using 128-bit AES keywrap is very similar, the main difference is that
--   we generate a 128-bit symmetric key:
--   
--   <pre>
--   &gt;&gt;&gt; aesKey &lt;- generateSymmetricKey 16 (KeyId "My Keywrap Key") Enc Nothing
--   
--   &gt;&gt;&gt; Right (Jwt jwt) &lt;- jwkEncode A128KW A128GCM aesKey (Claims "more secret claims")
--   
--   &gt;&gt;&gt; Right (Jwe (hdr, claims)) &lt;- jwkDecode aesKey jwt
--   
--   &gt;&gt;&gt; claims
--   "more secret claims"
--   </pre>
module Jose.Jwe

-- | Create a JWE using a JWK. The key and algorithms must be consistent or
--   an error will be returned.
jwkEncode :: MonadRandom m => JweAlg -> Enc -> Jwk -> Payload -> m (Either JwtError Jwt)

-- | Try to decode a JWE using a JWK. If the key type does not match the
--   content encoding algorithm, an error will be returned.
jwkDecode :: MonadRandom m => Jwk -> ByteString -> m (Either JwtError JwtContent)

-- | Creates a JWE with the content key encoded using RSA.
rsaEncode :: MonadRandom m => JweAlg -> Enc -> PublicKey -> ByteString -> m (Either JwtError Jwt)

-- | Decrypts a JWE.
rsaDecode :: MonadRandom m => PrivateKey -> ByteString -> m (Either JwtError Jwe)


-- | 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:
--   
--   <pre>
--   &gt;&gt;&gt; import Jose.Jwe
--   
--   &gt;&gt;&gt; import Jose.Jwa
--   
--   &gt;&gt;&gt; import Jose.Jwk
--   
--   &gt;&gt;&gt; import Data.ByteString
--   
--   &gt;&gt;&gt; import Data.Aeson (decodeStrict)
--   
--   &gt;&gt;&gt; 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
--   
--   &gt;&gt;&gt; let Just jwk = decodeStrict jsonJwk :: Maybe Jwk
--   
--   &gt;&gt;&gt; Right (Jwt jwtEncoded) &lt;- encode [jwk] (JwsEncoding RS256) (Claims "public claims")
--   
--   &gt;&gt;&gt; Right jwtDecoded &lt;- Jose.Jwt.decode [jwk] (Just (JwsEncoding RS256)) jwtEncoded
--   
--   &gt;&gt;&gt; jwtDecoded
--   Jws (JwsHeader {jwsAlg = RS256, jwsTyp = Nothing, jwsCty = Nothing, jwsKid = Just (KeyId "mykey")},"public claims")
--   </pre>
module Jose.Jwt

-- | An encoded JWT.
newtype Jwt
Jwt :: ByteString -> Jwt
[unJwt] :: Jwt -> ByteString

-- | The header and claims of a decoded JWE.
type Jwe = (JweHeader, ByteString)

-- | The header and claims of a decoded JWS.
type Jws = (JwsHeader, ByteString)

-- | Registered claims defined in section 4 of the JWT spec.
data JwtClaims
JwtClaims :: !(Maybe Text) -> !(Maybe Text) -> !(Maybe [Text]) -> !(Maybe IntDate) -> !(Maybe IntDate) -> !(Maybe IntDate) -> !(Maybe Text) -> JwtClaims
[jwtIss] :: JwtClaims -> !(Maybe Text)
[jwtSub] :: JwtClaims -> !(Maybe Text)
[jwtAud] :: JwtClaims -> !(Maybe [Text])
[jwtExp] :: JwtClaims -> !(Maybe IntDate)
[jwtNbf] :: JwtClaims -> !(Maybe IntDate)
[jwtIat] :: JwtClaims -> !(Maybe IntDate)
[jwtJti] :: JwtClaims -> !(Maybe Text)

-- | Header content for a JWS.
data JwsHeader
JwsHeader :: JwsAlg -> Maybe Text -> Maybe Text -> Maybe KeyId -> JwsHeader
[jwsAlg] :: JwsHeader -> JwsAlg
[jwsTyp] :: JwsHeader -> Maybe Text
[jwsCty] :: JwsHeader -> Maybe Text
[jwsKid] :: JwsHeader -> Maybe KeyId

-- | Header content for a JWE.
data JweHeader
JweHeader :: JweAlg -> Enc -> Maybe Text -> Maybe Text -> Maybe Text -> Maybe KeyId -> JweHeader
[jweAlg] :: JweHeader -> JweAlg
[jweEnc] :: JweHeader -> Enc
[jweTyp] :: JweHeader -> Maybe Text
[jweCty] :: JweHeader -> Maybe Text
[jweZip] :: JweHeader -> Maybe Text
[jweKid] :: JweHeader -> Maybe KeyId

-- | A decoded JWT which can be either a JWE or a JWS, or an unsecured JWT.
data JwtContent
Unsecured :: !ByteString -> JwtContent
Jws :: !Jws -> JwtContent
Jwe :: !Jwe -> JwtContent

-- | Defines the encoding information for a JWT.
--   
--   Used for both encoding new JWTs and validating existing ones.
data JwtEncoding
JwsEncoding :: JwsAlg -> JwtEncoding
JweEncoding :: JweAlg -> Enc -> JwtEncoding

-- | Decoding errors.
data JwtError

-- | No suitable key or wrong key type
KeyError :: Text -> JwtError

-- | The supplied algorithm is invalid
BadAlgorithm :: Text -> JwtError

-- | Wrong number of "." characters in the JWT
BadDots :: Int -> JwtError

-- | Header couldn't be decoded or contains bad data
BadHeader :: Text -> JwtError

-- | Claims part couldn't be decoded or contains bad data
BadClaims :: JwtError

-- | Signature is invalid
BadSignature :: JwtError

-- | A cryptographic operation failed
BadCrypto :: JwtError

-- | A base64 decoding error
Base64Error :: String -> JwtError

-- | The payload to be encoded in a JWT.
data Payload
Nested :: Jwt -> Payload
Claims :: ByteString -> Payload

-- | 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.
encode :: MonadRandom m => [Jwk] -> JwtEncoding -> Payload -> m (Either JwtError Jwt)

-- | Uses the supplied keys to decode a JWT. Locates a matching key by
--   header <tt>kid</tt> 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 <tt>JwtEncoding</tt> 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 <tt>Just (JwsEncoding None)</tt> or an error will be
--   returned.
decode :: MonadRandom m => [Jwk] -> Maybe JwtEncoding -> ByteString -> m (Either JwtError JwtContent)

-- | Convenience function to return the claims contained in a JWT. This is
--   required in situations such as client assertion authentication, where
--   the contents of the JWT 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.
decodeClaims :: ByteString -> Either JwtError (JwtHeader, JwtClaims)
