Network.Iron

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 Just obj = decode "{\"a\":1,\"d\":{\"e\":\"f\"},\"b\":2,\"c\":[3,4,5]}" :: Maybe Object
>>> let secret = "some_not_random_password" :: ByteString
>>> s <- Iron.seal (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 (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])]))

Documentation

seal :: ToJSON a => Password -> a -> IO ByteString

Encodes and encrypts a Value using the given password.

sealWith :: ToJSON a => Options -> Password -> a -> IO (Maybe ByteString)

Encodes and encrypts a Value using the given password and Options. Encryption may fail if the supplied options are wrong.

unseal :: FromJSON a => LookupPassword -> ByteString -> IO (Either String a)

Decrypts an Iron-encoded message Value with the given password.

unsealWith :: FromJSON a => Options -> LookupPassword -> ByteString -> IO (Either String a)

Decrypts an Iron-encoded message Value with the given password and Options.

password :: ToSecureMem a => a -> Password

Constructs a Password.

passwords :: ToSecureMem a => a -> a -> Password

Constructs a Password, with different encryption and integrity verification passwords.

passwordWithId :: ToSecureMem a => PasswordId -> a -> Maybe Password

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 :: ToSecureMem a => PasswordId -> a -> a -> Maybe Password

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.

data Password

Represents the password(s) used to seal and unseal Iron messages. To construct a Password, use one of password, passwords, passwordWithId, passwordsWithId.

Instances

Eq Password

Methods

(==) :: Password -> Password -> Bool

(/=) :: Password -> Password -> Bool

Show Password

Methods

showsPrec :: Int -> Password -> ShowS

show :: Password -> String

showList :: [Password] -> ShowS

type PasswordId = ByteString

Identifies the password to use when unsealing the message.

type LookupPassword = PasswordId -> Maybe Password

User-supplied function to get the password corresponding to the identifier from the sealed message.

onePassword :: ToSecureMem a => a -> LookupPassword

The simple case of LookupPassword, where there is the same password for encryption and verification of all messages.

data Options

Iron options used by sealWith and unsealWith. The default options are:

• Encryption: AES256 using CBC mode
• Integrity HMAC: SHA256
• Infinite message lifetime
• Timestamp skew: 60 seconds either way
• Local time offset: 0

Constructors

Options

Fields

• ironEncryption :: EncryptionOpts

  Encryption options

• ironIntegrity :: IntegrityOpts

  Message integrity verification options

• ironTTL :: NominalDiffTime

  Message lifetime in seconds

• ironTimestampSkew :: NominalDiffTime

  Clock difference allowance in seconds

• ironLocaltimeOffset :: NominalDiffTime

  Clock offset in seconds

Instances

Show Options

Methods

showsPrec :: Int -> Options -> ShowS

show :: Options -> String

showList :: [Options] -> ShowS

Default Options

Methods

def :: Options

data EncryptionOpts

Options controlling encryption of Iron messages.

Constructors

EncryptionOpts

Fields

• ieSalt :: IronSalt

  Salt for password-based key generation

• ieAlgorithm :: IronCipher

  Encryption algorithm

• ieIterations :: Int

  Number of iterations for password-based key generation

• ieIV :: Maybe ByteString

  Pre-generated initial value block

Instances

Show EncryptionOpts

Methods

showsPrec :: Int -> EncryptionOpts -> ShowS

show :: EncryptionOpts -> String

showList :: [EncryptionOpts] -> ShowS

Default EncryptionOpts

Methods

def :: EncryptionOpts

data IntegrityOpts

Options controlling cryptographic verification of Iron messages.

Constructors

IntegrityOpts

Fields

• iiSalt :: IronSalt

  Salt for MAC key generation

• iiAlgorithm :: IronMAC

  Hash-based MAC algorithm

• iiIterations :: Int

  Number of iterations for MAC key generation

Instances

Show IntegrityOpts

Methods

showsPrec :: Int -> IntegrityOpts -> ShowS

show :: IntegrityOpts -> String

showList :: [IntegrityOpts] -> ShowS

Default IntegrityOpts

Methods

def :: IntegrityOpts

data IronCipher

Encryption algorithms supported by Iron.

Constructors

AES128CTR

AES256CBC

Instances

Show IronCipher

Methods

showsPrec :: Int -> IronCipher -> ShowS

show :: IronCipher -> String

showList :: [IronCipher] -> ShowS

data IronMAC

Integrity checking algorithm supported by Iron. At present, there is only one. Use IronMAC SHA256.

Constructors

(IsIronMAC alg, Show alg) => IronMAC alg

Instances

Show IronMAC

Methods

showsPrec :: Int -> IronMAC -> ShowS

show :: IronMAC -> String

showList :: [IronMAC] -> ShowS

data SHA256 :: *

SHA256 cryptographic hash algorithm

Constructors

SHA256

Instances

Show SHA256

Methods

showsPrec :: Int -> SHA256 -> ShowS

show :: SHA256 -> String

showList :: [SHA256] -> ShowS

HashAlgorithm SHA256

Methods

hashBlockSize :: SHA256 -> Int

hashDigestSize :: SHA256 -> Int

hashInternalContextSize :: SHA256 -> Int

hashInternalInit :: Ptr (Context SHA256) -> IO ()

hashInternalUpdate :: Ptr (Context SHA256) -> Ptr Word8 -> Word32 -> IO ()

hashInternalFinalize :: Ptr (Context SHA256) -> Ptr (Digest SHA256) -> IO ()

HawkAlgoCls SHA256

Methods

hawkHash :: SHA256 -> ByteString -> ByteString

hawkMac :: SHA256 -> Key -> ByteString -> ByteString

data IronSalt

Specifies the salt for password-based key generation.

Constructors

IronSalt ByteString

Supply pre-generated salt

IronGenSalt Int

Generate salt of given size, in bits

Instances

Show IronSalt

Methods

showsPrec :: Int -> IronSalt -> ShowS

show :: IronSalt -> String

showList :: [IronSalt] -> ShowS

urlSafeBase64 :: ByteString -> ByteString

Fixes up a Base64 encoded string so that it's more convenient to include in URLs. The padding = signs are removed, and the characters + and / are replaced with - and _.