Botan.Low.BlockCipher

This is a ‘raw’ interface to ECB mode block ciphers. Most applications want the higher level cipher API which provides authenticated encryption. This API exists as an escape hatch for applications which need to implement custom primitives using a PRP.

Block ciphers

A `block cipher` is a deterministic, cryptographic primitive suitable for encrypting or decrypting a single, fixed-size block of data at a time. Block ciphers are used as building blocks for more complex cryptographic operations. If you are looking to encrypt user data, you are probably looking for Cipher instead.

Usage

Unless you need a specific block cipher, it is strongly recommended that you use the AES256 algorithm.

import Botan.Low.BlockCipher
blockCipher <- blockCipherInit AES256

To use a block cipher, we first need to generate (if we haven't already) a secret key.

import Botan.Low.RNG
rng <- rngInit "user"
-- We will use the maximum key size; AES256 keys are always 16 bytes
(_,keySize,_) <- blockCipherGetKeyspec blockCipher
-- Block cipher keys are randomly generated
key <- rngGet rng keySize

After the key is generated, we must set it as the block cipher key:

blockCipherSetKey blockCipher key

To encrypt a message, it must be a multiple of the block size.

blockSize <- blockCipherBlockSize blockCipher
-- AES256 block size is always 16 bytes
message = "0000DEADBEEF0000" :: ByteString
ciphertext <- blockCipherEncryptBlocks blockCipher message

To decrypt a message, simply reverse the process:

plaintext <- blockCipherDecryptBlocks blockCipher ciphertext
message == plaintext -- True

newtype BlockCipher

A mutable block cipher object

Constructors

MkBlockCipher

Fields

• getBlockCipherForeignPtr :: ForeignPtr BotanBlockCipherStruct

type BlockCipherName = ByteString

Block cipher name type

type BlockCipher128Name = BlockCipherName

128-bit block cipher name type

type BlockCipherKey = ByteString

A block cipher secret key

type BlockCipherCiphertext = ByteString

A block cipher ciphertext

withBlockCipher :: BlockCipher -> (BotanBlockCipher -> IO a) -> IO a

blockCipherInit

Arguments

:: BlockCipherName

cipher_name

-> IO BlockCipher

bc

Initialize a block cipher object

blockCipherDestroy :: BlockCipher -> IO ()

Destroy a block cipher object immediately

blockCipherName

Arguments

:: BlockCipher

bc

-> IO BlockCipherName

name

Get the name of a block cipher.

This function is not guaranteed to return the same exact value as used to initialize the context.

blockCipherBlockSize

Arguments

:: BlockCipher

bc: The cipher object

-> IO Int

Return the block size of a block cipher.

blockCipherGetKeyspec

Arguments

:: BlockCipher

bc

-> IO (Int, Int, Int)

(min,max,mod)

Get the key specification of a block cipher

Returns the minimum, maximum, and modulo of valid keys.

blockCipherSetKey

Arguments

:: BlockCipher

bc: The cipher object

-> BlockCipherKey

key[]: A cipher key

-> IO ()

Set the key for a block cipher

Throws an error if the key is not valid.

blockCipherEncryptBlocks

Arguments

:: BlockCipher

bc: The cipher object

-> ByteString

in[]: The plaintext

-> IO BlockCipherCiphertext

out[]: The ciphertext

Warning: The plaintext length should be a multiple of the block size.

Encrypt one or more blocks with a block cipher

The plaintext length should be a multiple of the block size.

blockCipherDecryptBlocks

Arguments

:: BlockCipher

bc: The cipher object

-> BlockCipherCiphertext

in[]: The ciphertext

-> IO ByteString

out[]: The plaintext

Warning: The ciphertext length should be a multiple of the block size.

Decrypt one or more blocks with a block cipher.

The ciphertext length should be a multiple of the block size.

If an incorrect key was set, the content of the decrypted plaintext is unspecified.

blockCipherClear

Arguments

:: BlockCipher

bc: The cipher object

-> IO ()

Reinitializes a block cipher

You must call blockCipherSetKey in order to use the block cipher again.

64-bit block ciphers

pattern Blowfish :: BlockCipherName

pattern CAST128 :: BlockCipherName

pattern DES :: BlockCipherName

pattern TripleDES :: BlockCipherName

pattern GOST_28147_89 :: BlockCipherName

pattern IDEA :: BlockCipherName

128-bit block ciphers

pattern AES128 :: BlockCipher128Name

pattern AES192 :: BlockCipher128Name

pattern AES256 :: BlockCipher128Name

pattern ARIA128 :: BlockCipher128Name

pattern ARIA192 :: BlockCipher128Name

pattern ARIA256 :: BlockCipher128Name

pattern Camellia128 :: BlockCipher128Name

pattern Camellia192 :: BlockCipher128Name

pattern Camellia256 :: BlockCipher128Name

pattern Noekeon :: BlockCipher128Name

pattern SEED :: BlockCipher128Name

pattern SM4 :: BlockCipher128Name

pattern Serpent :: BlockCipher128Name

pattern Twofish :: BlockCipher128Name

256-bit block ciphers

pattern SHACAL2 :: BlockCipherName

512-bit block ciphers

pattern Threefish512 :: BlockCipherName

Convenience

blockCiphers :: [BlockCipherName]

blockCipher128s :: [BlockCipher128Name]

allBlockCiphers :: [BlockCipherName]