package cryptokit

  1. Overview
  2. Docs

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.

The module MAC provides six MAC functions based on the hashes BLAKE2b, SHA-1, SHA256, SHA512, RIPEMD160 and MD5; five MAC functions based on the block ciphers AES, DES, and Triple-DES; and the SipHash algorithm.

val hmac_sha1 : string -> hash

hmac_sha1 key returns a MAC based on the HMAC construction (RFC2104) applied to SHA-1. The returned hash values are 160 bits (20 bytes) long. The key argument is the MAC key; it can have any length, but a minimal length of 20 bytes is recommended.

val hmac_sha256 : string -> hash

hmac_sha256 key returns a MAC based on the HMAC construction (RFC2104) applied to SHA-256. The returned hash values are 256 bits (32 bytes) long. The key argument is the MAC key; it can have any length, but a minimal length of 32 bytes is recommended.

val hmac_sha384 : string -> hash

hmac_sha384 key returns a MAC based on the HMAC construction (RFC2104) applied to SHA-384. The returned hash values are 384 bits (48 bytes) long. The key argument is the MAC key; it can have any length, but a minimal length of 64 bytes is recommended.

val hmac_sha512 : string -> hash

hmac_sha512 key returns a MAC based on the HMAC construction (RFC2104) applied to SHA-512. The returned hash values are 512 bits (64 bytes) long. The key argument is the MAC key; it can have any length, but a minimal length of 64 bytes is recommended.

val hmac_ripemd160 : string -> hash

hmac_ripemd160 key returns a MAC based on the HMAC construction (RFC2104) applied to RIPEMD-160. The returned hash values are 160 bits (20 bytes) long. The key argument is the MAC key; it can have any length, but a minimal length of 20 bytes is recommended.

val hmac_md5 : string -> hash

hmac_md5 key returns a MAC based on the HMAC construction (RFC2104) applied to MD5. The returned hash values are 128 bits (16 bytes) long. The key argument is the MAC key; it can have any length, but a minimal length of 16 bytes is recommended.

val blake2b : int -> string -> hash

blake2b sz key is the BLAKE2b keyed hash function. The returned hash values have length 1 to 64 bytes. The sz is the desired size of the hash, in bits. It must be between 8 and 512, and a multiple of 8. The key argument is the MAC key. It must have length 64 at most. A length of 64 bytes is recommended.

val blake2b512 : string -> hash

blake2b512 key is the BLAKE2b keyed hash function specialized to 512 bit hashes (64 bytes). The key argument is the MAC key. It must have length 64 at most. A length of 64 bytes is recommended.

val blake2s : int -> string -> hash

blake2s sz key is the BLAKE2s keyed hash function. The returned hash values have length 1 to 32 bytes. The sz is the desired size of the hash, in bits. It must be between 8 and 256, and a multiple of 8. The key argument is the MAC key. It must have length 32 at most. A length of 32 bytes is recommended.

val blake2s256 : string -> hash

blake2s256 key is the BLAKE2s keyed hash function specialized to 256 bit hashes (32 bytes). The key argument is the MAC key. It must have length 32 at most. A length of 32 bytes is recommended.

val blake3 : int -> string -> hash

blake3 sz key is the BLAKE3 keyed hash function. key is the MAC key. It must have length 32. sz is the desired size of the hash, in bits. The recommended length is 256 bits (32 bytes). Shorter hashes are less secure, but longer hashes are not more secure.

val blake3_256 : string -> hash

blake3_256 key is the BLAKE3 keyed hash function specialized to 256 bit hashes (32 bytes). key is the MAC key. It must have length 32.

val aes_cmac : ?iv:string -> string -> hash

aes_cmac key returns a MAC based on AES encryption in CMAC mode, also known as OMAC1 mode. The input data is encrypted using AES in CBC mode, with a special treatment of the final block that makes this MAC suitable for input data of variable length. The final value of the initialization vector is the MAC value. Thus, the returned hash values are 128 bit (16 bytes) long. The key argument is the MAC key; it must have length 16, 24, or 32. The optional iv argument is the first value of the initialization vector, and defaults to 0.

val aes : ?iv:string -> ?pad:Padding.scheme -> string -> hash

aes key returns a MAC based on AES encryption in CBC mode. Unlike aes_cmac, there is no special treatment for the final block, except padding it as per the optional pad argument. This makes this MAC weak when used with input data of variable length. (It is fine for data of fixed length, though.) The returned hash values are 128 bit (16 bytes) long. The key argument is the MAC key; it must have length 16, 24, or 32. The optional iv argument is the first value of the initialization vector, and defaults to 0. The optional pad argument specifies a padding scheme to pad input to an integral number of 16-byte blocks.

val des : ?iv:string -> ?pad:Padding.scheme -> string -> hash

des key returns a MAC based on DES encryption in CBC mode. The construction is identical to that used for the aes MAC. The key size is 64 bits (8 bytes), of which only 56 are used. The returned hash value has length 8 bytes. Due to the small hash size and key size, this MAC is weak.

  • alert crypto DES MAC is weak
val triple_des : ?iv:string -> ?pad:Padding.scheme -> string -> hash

triple_des key returns a MAC based on triple DES encryption in CBC mode. The construction is identical to that used for the aes MAC. The key size is 16 or 24 bytes. The returned hash value has length 8 bytes. The key size is sufficient to protect against brute-force attacks, but the small hash size means that this MAC is not collision-resistant.

  • alert crypto Triple-DES MAC is weak
val des_final_triple_des : ?iv:string -> ?pad:Padding.scheme -> string -> hash

des_final_triple_des key returns a MAC that uses DES CBC with the first 8 bytes of key as key. The final initialization vector is then DES-decrypted with bytes 8 to 15 of key, and DES-encrypted again with either the last 8 bytes of key (if a triple-length key is provided) or the first 8 bytes of key (if a double-length key is provided). Thus, the key is 16 or 24 bytes long, of which 112 or 168 bits are used. The overall construction has the same key size as a triple DES MAC, but runs faster because triple encryption is not performed on all data blocks, but only on the final MAC.

  • alert crypto Triple-DES MAC is weak
val siphash : string -> hash

siphash key is the SipHash-2-4 function. The returned hash values have length 8 bytes. The key argument is the MAC key. It must be 16 bytes (128 bits) long. This MAC is very fast, especially for short inputs. However, it has not been cryptanalyzed as intensively as the other MACs above.

val siphash128 : string -> hash

siphash128 key is a variant of siphash that returns hash values of length 16 bytes instead of 8 bytes.

OCaml

Innovation. Community. Security.