Raaz.Cipher.Internal

This module exposes the low-level internal details of ciphers. Do not import this module unless you want to implement a new cipher or give a new implementation of an existing cipher.

Internals of a cipher.

Ciphers provide symmetric encryption in the raaz library and are captured by the type class Cipher. Instances of Cipher are full encryption/decryption algorithms. For a block cipher this means that one also needs to specify the CipherMode to make it an instance of the class Cipher. They are instances of the class Symmetric and the associated type Key captures the encryption key for the cipher.

Implementations of ciphers are captured by two types.

CipherI:

Values of this type that captures implementations of a cipher. This type is parameterised over the memory element that is used internally by the implementation.

SomeCipherI:

The existentially quantified version of CipherI over its memory element. By wrapping the memory element inside the existential quantifier, values of this type exposes only the interface and not the internals of the implementation. The Implementation associated type of a cipher is the type SomeCipherI

To support a new cipher, a developer needs to:

1. Define a new type which captures the cipher. This type should be an instance of the class Cipher.
2. Define an implementation, i.e. a value of the type SomeCipherI.
3. Define a recommended implementation, i.e. an instance of the type class Recommendation

class (Symmetric cipher, Implementation cipher ~ SomeCipherI cipher) => Cipher cipher

Instances

Cipher (AES 128 CBC)

Cipher (AES 192 CBC)

Cipher (AES 256 CBC)

data CipherMode

Block cipher modes.

Constructors

CBC

Cipher-block chaining

CTR

Counter

Instances

Eq CipherMode

Methods

(==) :: CipherMode -> CipherMode -> Bool

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

Show CipherMode

Methods

showsPrec :: Int -> CipherMode -> ShowS

show :: CipherMode -> String

showList :: [CipherMode] -> ShowS

Cipher implementation

data CipherI cipher encMem decMem

The implementation of a block cipher.

Constructors

CipherI

Fields

• cipherIName :: String
• cipherIDescription :: String
• encryptBlocks :: Pointer -> BLOCKS cipher -> MT encMem ()

  The underlying block encryption function.

• decryptBlocks :: Pointer -> BLOCKS cipher -> MT decMem ()

  The underlying block decryption function.

Instances

Describable (CipherI cipher encMem decMem)

Methods

name :: CipherI cipher encMem decMem -> String

description :: CipherI cipher encMem decMem -> String

data SomeCipherI cipher

Some implementation of a block cipher. This type existentially quantifies over the memory used in the implementation.

Constructors

CipherM cipher encMem decMem => SomeCipherI (CipherI cipher encMem decMem)

Instances

Describable (SomeCipherI cipher)

Methods

name :: SomeCipherI cipher -> String

description :: SomeCipherI cipher -> String

Unsafe encryption and decryption.

We expose some unsafe functions to encrypt and decrypt bytestrings. These function works correctly only if the input byte string has a length which is a multiple of the block size of the cipher and hence are unsafe to use as general methods of encryption and decryption of data. Use these functions for testing and benchmarking and nothing else.

There are multiple ways to handle arbitrary sized strings like padding, cipher block stealing etc. They are not exposed here though.

unsafeEncrypt

Arguments

:: (Cipher c, Recommendation c)

=> c

The cipher

-> Key c

The key to use

-> ByteString

The string to encrypt

-> ByteString

Encrypt using the recommended implementation. This function is unsafe because it only works correctly when the input ByteString is of length which is a multiple of the block length of the cipher.

unsafeDecrypt

Arguments

:: (Cipher c, Recommendation c)

=> c

The cipher

-> Key c

The key to use

-> ByteString

The string to encrypt

-> ByteString

Decrypt using the recommended implementation. This function is unsafe because it only works correctly when the input ByteString is of length which is a multiple of the block length of the cipher.

unsafeEncrypt'

Arguments

:: Cipher c

=> c

The cipher to use

-> Implementation c

The implementation to use

-> Key c

The key to use

-> ByteString

The string to encrypt.

-> ByteString

Encrypt the given ByteString. This function is unsafe because it only works correctly when the input ByteString is of length which is a multiple of the block length of the cipher.

unsafeDecrypt'

Arguments

:: Cipher c

=> c

The cipher to use

-> Implementation c

The implementation to use

-> Key c

The key to use

-> ByteString

The string to encrypt.

-> ByteString

Decrypts the given ByteString. This function is unsafe because it only works correctly when the input ByteString is of length which is a multiple of the block length of the cipher.