Module Cryptokit
The Cryptokit library provides a variety of cryptographic primitives that can be used to implement cryptographic protocols in security-sensitive applications. The primitives provided include:
- Symmetric-key ciphers: AES, DES, Triple-DES, ARCfour, in ECB, CBC, CFB and OFB modes.
- Public-key cryptography: RSA encryption, Diffie-Hellman key agreement.
- Hash functions and MACs: SHA-1, SHA-256, SHA-512. SHA-3, RIPEMD-160, MD5, and MACs based on AES and DES.
- Random number generation.
- Encodings and compression: base 64, hexadecimal, Zlib compression.
General-purpose abstract interfaces
class type transform = object ... end
A <I>transform</I> is an arbitrary mapping from sequences of characters to sequences of characters. Examples of transforms include ciphering, deciphering, compression, decompression, and encoding of binary data as text. Input data to a transform is provided by successive calls to the methods
put_substring
,put_string
,put_char
orput_byte
. The result of transforming the input data is buffered internally, and can be obtained via theget_string
,get_substring
,get_char
andget_byte
methods.
val transform_string : transform -> string -> string
transform_string t s
runs the strings
through the transformt
and returns the transformed string. The transformt
is wiped before returning, hence can no longer be used for further transformations.
val transform_channel : transform -> ?len:int -> Stdlib.in_channel -> Stdlib.out_channel -> unit
transform_channel t ic oc
reads characters from input channelic
, runs them through the transformt
, and writes the transformed data to the output channeloc
. If the optionallen
argument is provided, exactlylen
characters are read fromic
and transformed;End_of_file
is raised ific
does not contain at leastlen
characters. Iflen
is not provided,ic
is read all the way to end of file. The transformt
is wiped before returning, hence can no longer be used for further transformations.
val compose : transform -> transform -> transform
Compose two transforms, feeding the output of the first transform to the input of the second transform.
class type hash = object ... end
A <I>hash</I> is a function that maps arbitrarily-long character sequences to small, fixed-size strings.
val hash_string : hash -> string -> string
hash_string h s
runs the strings
through the hash functionh
and returns the hash value ofs
. The hashh
is wiped before returning, hence can no longer be used for further hash computations.
val hash_channel : hash -> ?len:int -> Stdlib.in_channel -> string
hash_channel h ic
reads characters from the input channelic
, computes their hash value and returns it. If the optionallen
argument is provided, exactlylen
characters are read fromic
and hashed;End_of_file
is raised ific
does not contain at leastlen
characters. Iflen
is not provided,ic
is read all the way to end of file. The hashh
is wiped before returning, hence can no longer be used for further hash computations.
Utilities: random numbers and padding schemes
module Random : sig ... end
The
Random
module provides random and pseudo-random number generators suitable for generating cryptographic keys, nonces, or challenges.
module Padding : sig ... end
The
Padding
module defines a generic interface for padding input data to an integral number of blocks, as well as two popular padding schemes.
Cryptographic primitives (simplified interface)
module Cipher : sig ... end
The
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.
module Hash : sig ... end
The
Hash
module implements unkeyed cryptographic hashes (SHA-1, SHA-256, SHA-512, SHA-3, RIPEMD-160 and MD5), also known as message digest functions. Hash functions used in cryptography are characterized as being <I>one-way</I> (given a hash value, it is computationally infeasible to find a text that hashes to this value) and <I>collision-resistant</I> (it is computationally infeasible to find two different texts that hash to the same value). Thus, the hash of a text can be used as a compact replacement for this text for the purposes of ensuring integrity of the text.
module MAC : sig ... end
The
MAC
module implements message authentication codes, also known as keyed hash functions. These are hash functions parameterized by a secret key. In addition to being one-way and collision-resistant, a MAC has the property that without knowing the secret key, it is computationally infeasible to find the hash for a known text, even if many pairs of (text, MAC) are known to the attacker. Thus, MAC can be used to authenticate the sender of a text: the receiver of a (text, MAC) pair can recompute the MAC from the text, and if it matches the transmitted MAC, be reasonably certain that the text was authentified by someone who possesses the secret key.
module RSA : sig ... end
The
RSA
module implements RSA public-key cryptography. Public-key cryptography is asymmetric: two distinct keys are used for encrypting a message, then decrypting it. Moreover, while one of the keys must remain secret, the other can be made public, since it is computationally very hard to reconstruct the private key from the public key. This feature supports both public-key encryption (anyone can encode with the public key, but only the owner of the private key can decrypt) and digital signature (only the owner of the private key can sign, but anyone can check the signature with the public key).
module DH : sig ... end
The
DH
module implements Diffie-Hellman key agreement. Key agreement is a protocol by which two parties can establish a shared secret (typically a key for a symmetric cipher or MAC) by exchanging messages, with the guarantee that even if an attacker eavesdrop on the messages, he cannot recover the shared secret. Diffie-Hellman is one such key agreement protocol, relying on the difficulty of computing discrete logarithms. Notice that the Diffie-Hellman protocol is vulnerable to active attacks (man-in-the-middle attacks).
Advanced, compositional interface to block ciphers and stream ciphers
module Block : sig ... end
The
Block
module provides classes that implements popular block ciphers, chaining modes, and wrapping of a block cipher as a general transform or as a hash function. The classes can be composed in a Lego-like fashion, facilitating the integration of new block ciphers, modes, etc.
module Stream : sig ... end
The
Stream
module provides classes that implement the ARCfour stream cipher, and the wrapping of a stream cipher as a general transform. The classes can be composed in a Lego-like fashion, facilitating the integration of new stream ciphers.
Encoding and compression of data
module Base64 : sig ... end
The
Base64
module supports the encoding and decoding of binary data in base 64 format, using only alphanumeric characters that can safely be transmitted over e-mail or in URLs.
module Hexa : sig ... end
The
Hexa
module supports the encoding and decoding of binary data as hexadecimal strings. This is a popular format for transmitting keys in textual form.
module Zlib : sig ... end
The
Zlib
module supports the compression and decompression of data, using thezlib
library. The algorithm used is Lempel-Ziv compression as in thegzip
andzip
compressors. While compression itself is not encryption, it is often used prior to encryption to hide regularities in the plaintext, and reduce the size of the ciphertext.
Error reporting
type error
=
|
Wrong_key_size
The key is too long or too short for the given cipher.
|
Wrong_IV_size
The initialization vector does not have the same size as the block size.
|
Wrong_data_length
The total length of the input data for a transform is not an integral multiple of the input block size.
|
Bad_padding
Incorrect padding bytes were found after decryption.
|
Output_buffer_overflow
The output buffer for a transform exceeds the maximal length of a Caml string.
|
Incompatible_block_size
A combination of two block ciphers was attempted whereby the ciphers have different block sizes, while they must have the same.
|
Number_too_long
Denotes an internal error in RSA key generation or encryption.
|
Seed_too_short
The seed given to a pseudo random number generator is too short.
|
Message_too_long
The message passed to RSA encryption or decryption is greater than the modulus of the RSA key
|
Bad_encoding
Illegal characters were found in an encoding of binary data such as base 64 or hexadecimal.
|
Compression_error of string * string
Error during compression or decompression.
|
No_entropy_source
No entropy source (OS,
/dev/random
or EGD) was found forCryptokit.Random.secure_rng
.|
Entropy_source_closed
End of file on a device or EGD entropy source.
|
Compression_not_supported
The data compression functions are not available.
Error codes for this library.
exception
Error of error
Exception raised by functions in this library to report error conditions.
Miscellaneous utilities
val wipe_bytes : bytes -> unit
wipe_bytes b
overwritesb
with zeroes. Can be used to reduce the memory lifetime of sensitive data.
val wipe_string : string -> unit
wipe_string s
overwritess
with zeroes. Can be used to reduce the memory lifetime of sensitive data. Note that strings are normally immutable and this operation violates this immutability property. Therefore, this is an unsafe operation, and it should be used only by code that is the only owner of the strings
. SeeBytes
.unsafe_of_string for more details on the ownership policy.
val string_equal : string -> string -> bool
Constant-time comparison between strings.
string_equal s1 s2
returnstrue
if the stringss1
ands2
have the same length and contain the same characters. The execution time of this function is determined by the lengths ofs1
ands2
, but is independent of their contents.
val bytes_equal : bytes -> bytes -> bool
Constant-time comparison between byte sequences. Like
Cryptokit.string_equal
, but for byte sequences.
val xor_bytes : bytes -> int -> bytes -> int -> int -> unit
xor_bytes src spos dst dpos len
performs the xor (exclusive or) of charactersspos, ..., spos + len - 1
ofsrc
with charactersdpos, ..., dpos + len - 1
ofdst
, storing the result indst
starting at positiondpos
.
val xor_string : string -> int -> bytes -> int -> int -> unit
Same as
xor_bytes
, but the source is a string instead of a byte array.