| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Network.Iron
Description
Iron is a cryptographic utility for sealing a JSON object using symmetric key encryption with message integrity verification. Or in other words, it lets you encrypt an object, send it around (in cookies, authentication credentials, etc.), then receive it back and decrypt it. The algorithm ensures that the message was not tampered with, and also provides a simple mechanism for password rotation.
For more information about the sealing/unsealing process, as well as security considerations, see the Iron Website.
Usage
To seal an object:
>>>import Data.ByteString (ByteString)>>>import Data.Aeson>>>import qualified Network.Iron as Iron>>>let opts = Iron.options Iron.AES256CBC Iron.SHA256 256 66666>>>let Just obj = decode "{\"a\":1,\"d\":{\"e\":\"f\"},\"b\":2,\"c\":[3,4,5]}" :: Maybe Object>>>let secret = "some_not_random_password" :: ByteString>>>Just s <- Iron.seal opts (Iron.password secret) obj>>>print s"Fe26.2**3976da2bc627b3551c1ebfe40376bb791efb17f4425facc648038fdaaa2f67b2 *voiPExJrXAxmTWyQr7-Hvw*r_Ok7NOgy9sD2fS61t_u9z8qoszwBRze3NnA6PFmjnd06sLh0 9HRDlLorNYQJeEP**f6e22615db961e5ddc2ed47d956700b2ee63f0ab6f7ae6d3471989e5 4928e653*RsQNtNp4u5L-0fmZHSpPL7nbjBkqyKEyBcbOCbpEcpY"
The resulting "sealed" object is a string which can be sent via cookies, URI query parameter, or a HTTP header attribute.
To unseal the string:
>>>Iron.unseal opts (onePassword secret) s :: IO (Either String Object)Right (Object (fromList [("a",Number 1.0), ("d",Object (fromList [("e",String "f")])), ("b",Number 2.0), ("c",Array [Number 3.0,Number 4.0,Number 5.0])]))
- seal :: ToJSON a => Options -> Password -> a -> IO (Maybe ByteString)
- unseal :: FromJSON a => Options -> LookupPassword -> ByteString -> IO (Either String a)
- options :: IronCipher -> IronHMAC -> Int -> Int -> Options
- password :: ByteArrayAccess a => a -> Password
- passwords :: ByteArrayAccess a => a -> a -> Password
- passwordWithId :: ByteArrayAccess a => PasswordId -> a -> Maybe Password
- passwordsWithId :: ByteArrayAccess a => PasswordId -> a -> a -> Maybe Password
- data Password
- type PasswordId = ByteString
- type LookupPassword = PasswordId -> Maybe Password
- onePassword :: ByteArrayAccess a => a -> LookupPassword
- data Options = Options {}
- data EncryptionOpts = EncryptionOpts {
- ieSalt :: Salt
- ieAlgorithm :: IronCipher
- ieIterations :: Int
- ieIV :: Maybe ByteString
- data IntegrityOpts = IntegrityOpts {
- iiSalt :: Salt
- iiAlgorithm :: IronHMAC
- iiIterations :: Int
- data IronCipher
- data IronHMAC = SHA256
- data Salt
- = Salt ByteString
- | GenSalt Int
Documentation
unseal :: FromJSON a => Options -> LookupPassword -> ByteString -> IO (Either String a) Source #
Arguments
| :: IronCipher | Encryption algorithm. |
| -> IronHMAC | Integrity check algorithm (use |
| -> Int | Number of salt bits for key generation. |
| -> Int | Number of iterations of key derivation function. |
| -> Options |
A set of basic options. You need to choose a cipher and parameters for key generation.
There are also some default options chosen, which are: * Infinite message lifetime * Timestamp skew: 60 seconds either way * Local time offset: 0
passwords :: ByteArrayAccess a => a -> a -> Password Source #
Constructs a Password, with different encryption and integrity
verification passwords.
passwordWithId :: ByteArrayAccess a => PasswordId -> a -> Maybe Password Source #
Constructs a Password. The given identifier will be included as
the second component of the the sealed Fe26 string. The
identifier must only include alphanumeric characters and the
underscore, otherwise nothing will be returned.
passwordsWithId :: ByteArrayAccess a => PasswordId -> a -> a -> Maybe Password Source #
Constructs a Password, with different encryption and integrity
verification passwords. The given identifier will be included as
the second component of the the sealed Fe26 string. The
identifier must only include alphanumeric characters and the
underscore, otherwise nothing will be returned.
Represents the password(s) used to seal and unseal Iron
messages. To construct a Password, use one of password,
passwords, passwordWithId, passwordsWithId.
type PasswordId = ByteString Source #
Identifies the password to use when unsealing the message.
type LookupPassword = PasswordId -> Maybe Password Source #
User-supplied function to get the password corresponding to the identifier from the sealed message.
onePassword :: ByteArrayAccess a => a -> LookupPassword Source #
The simple case of LookupPassword, where there is the same password for encryption and verification of all messages.
Iron options used by sealWith and unsealWith.
Constructors
| Options | |
Fields
| |
data EncryptionOpts Source #
Options controlling encryption of Iron messages.
Constructors
| EncryptionOpts | |
Fields
| |
Instances
data IntegrityOpts Source #
Options controlling cryptographic verification of Iron messages.
Constructors
| IntegrityOpts | |
Fields
| |
Instances
Constructors
| SHA256 |