module Cipher:sig
..end
Cipher
module implements the AES, DES, Triple-DES, ARCfour
and Blowfish symmetric ciphers. Symmetric ciphers are presented
as transforms parameterized by a secret key and a ``direction''
indicating whether encryption or decryption is to be performed.
The same secret key is used for encryption and for decryption.type
direction =
| |
Encrypt |
|||
| |
Decrypt |
(* |
Indicate whether the cipher should perform encryption
(transforming plaintext to ciphertext) or decryption
(transforming ciphertext to plaintext).
| *) |
type
chaining_mode =
| |
ECB |
|||
| |
CBC |
|||
| |
CFB of |
|||
| |
OFB of |
|||
| |
CTR |
|||
| |
CTR_N of |
(* |
Block ciphers such as AES or DES map a fixed-sized block of
input data to a block of output data of the same size.
A chaining mode indicates how to extend them to multiple blocks
of data. The five chaining modes supported in this library are:
CBC is a recommended default. For CFB n and OFB n ,
note that the blocksize is reduced to n , but encryption
speed drops by a factor of blocksize / n , where blocksize
is the block size of the underlying cipher; moreover, n
must be between 1 and blocksize included. For CTR_N n ,
n must be between 1 and blocksize included.
CTR is equivalent to CTR_N blocksize . | *) |
val aes : ?mode:chaining_mode ->
?pad:Cryptokit.Padding.scheme ->
?iv:string -> string -> direction -> Cryptokit.transform
The optional mode
argument specifies a
chaining mode, as described above; CBC
is used by default.
The optional pad
argument specifies a padding scheme to
pad cleartext to an integral number of blocks. If no pad
argument is given, no padding is performed and the length
of the cleartext must be an integral number of blocks.
The optional iv
argument is the initialization vector used
by the chaining mode. It is ignored in ECB mode. If
provided, it must be a string of the same size as the block
size (16 bytes). If omitted, the null initialization vector
(16 zero bytes) is used.
The aes
function returns a transform that performs encryption
or decryption, depending on the direction argument.
val chacha20 : ?iv:string ->
?ctr:int64 -> string -> direction -> Cryptokit.transform
The Chacha20 cipher is a stream cipher, not a block cipher. Hence, its natural block size is 1, and no padding is required. Chaining modes do not apply. A feature of stream ciphers is that the xor of two ciphertexts obtained with the same key is the xor of the corresponding plaintexts, which allows various attacks. Hence, the same key must never be reused.
The string argument is the key; its length must be either 16 or (better) 32.
The optional iv
argument is the initialization vector (also
called nonce) that can be used to diversify the key. If present,
it must be 8 characters long. If absent, it is taken to be
eight zero bytes.
The optional ctr
argument is the initial value of the internal
counter. If absent, it defaults to 0.
The direction argument is present for consistency with the
other ciphers only, and is actually ignored: for all stream
ciphers, decryption is the same function as encryption.
val des : ?mode:chaining_mode ->
?pad:Cryptokit.Padding.scheme ->
?iv:string -> string -> direction -> Cryptokit.transform
des
function have the same meaning as
for the Cryptokit.Cipher.aes
function. The key argument is
a string of length 8 (64 bits); the least significant bit of
each key byte is ignored.val triple_des : ?mode:chaining_mode ->
?pad:Cryptokit.Padding.scheme ->
?iv:string -> string -> direction -> Cryptokit.transform
k1
,
decrypted with another 56-bit key k2
, then re-encrypted with
either k1
or a third 56-bit key k3
.
This results in a 112-bit or 168-bit key length that resists
brute-force attacks. However, the three encryptions required
on each block make this cipher quite slow (4 times slower than
AES). Moreover, the small block size (64 bits) opens the way
to collision-based attacks. Triple DES should therefore be
considered as relatively weak encryption.
The arguments to the triple_des
function have the
same meaning as for the Cryptokit.Cipher.aes
function. The
key argument is a string of length 16 or 24, representing the
concatenation of the key parts k1
, k2
, and optionally
k3
. The least significant bit of each key byte is
ignored.val arcfour : string -> direction -> Cryptokit.transform
ARCfour is popular for its speed: approximately 2 times faster than AES. It accepts any key length up to 2048 bits. However, the security of ARCfour is being questioned owing to several statistical biases in its output. It should not be used for new applications.
The ARCfour cipher is a stream cipher, not a block cipher. Hence, its natural block size is 1, and no padding is required. Chaining modes do not apply. A feature of stream ciphers is that the xor of two ciphertexts obtained with the same key is the xor of the corresponding plaintexts, which allows various attacks. Hence, the same key must never be reused.
The string argument is the key; its length must be between
1 and 256 inclusive. The direction argument is present for
consistency with the other ciphers only, and is actually
ignored: for all stream ciphers, decryption is the same
function as encryption.
val blowfish : ?mode:chaining_mode ->
?pad:Cryptokit.Padding.scheme ->
?iv:string -> string -> direction -> Cryptokit.transform
The small block size (64 bits) of Blowfish opens the way to some collision-based attacks. Depending on the application, ciphers with larger block size should be preferred.
The string argument is the key; its length must be between 4 and 56.
The direction argument specifies whether encryption or decryption is to be performed.
The optional mode
argument specifies a
chaining mode, as described above; CBC
is used by default.
The optional pad
argument specifies a padding scheme to
pad cleartext to an integral number of blocks. If no pad
argument is given, no padding is performed and the length
of the cleartext must be an integral number of blocks.
The optional iv
argument is the initialization vector used
by the chaining mode. It is ignored in ECB mode.
If provided, it must be a string of the same size as the block size
(8 bytes). If omitted, the null initialization vector
(8 zero bytes) is used.
The blowfish
function returns a transform that performs encryption
or decryption, depending on the direction argument.