module Symmetric_crypto:Netsys_crypto_types.SYMMETRIC_CRYPTO
Symmetric cryptography as provided by GnuTLS and its helper library Nettle
Symmetric cryptographic ciphers.
Users should not call functions of the provider directly, but use
Netsys_ciphers, or another higher-level layer.
type
Describes a cipher
val ciphers : scipher listList of supported ciphers. OCamlnet implements a number of modes anyway, and it is normally only required to implement "ECB" here. If there is special hardware acceleration, though, it is an option to provide accelerated modes too (e.g. some CPUs support AES-GCM specially).
val find : string * string -> scipherfind (name,mode): Looks up a cipher by name and mode, or
raises Not_found
val name : scipher -> stringReturns the name. This should follow the convention
<uppercasestring>-<size>, e.g.
"AES-128" or "TWOFISH-128". The size is normally the key size.
val mode : scipher -> stringReturns the mode. Modes are "ECB", "CBC", "OFB", "CTR", "STREAM", "GCM".
Note that the mode needs not to deal with padding (this is done on a higher level).
val key_lengths : scipher -> (int * int) listSupported key lengths as pairs min,max. If there is a recommended
key length, this should be the first.
val iv_lengths : scipher -> (int * int) listSupported iv lengths as pairs min,max. If there is a recommended
iv length, this should be the first.
val block_constraint : scipher -> intThe buffers used with encrypt/decrypt must have a length that is a multiple of this number. (In ECB mode, this is the block size.)
val supports_aead : scipher -> boolWhether this cipher integrates authentication
type
A cipher context stores processing data while encrypting or decrypting data
val create : scipher ->
string -> scipher_ctxcreate c key: create a new cipher context for key. If not set,
the initialization vector is zero, and the header the empty string.
val set_iv : scipher_ctx -> string -> unitset_iv cctx iv: Sets the initialization vector. This is only allowed
before encrypting or decrypting data
val set_header : scipher_ctx -> string -> unitset_header cctx data: Sets the additional header that is authenticated
for AEAD schemes. The header must have been set before starting the
encryption or decryption (otherwise it is assumed to be the empty
string).
For non-AEAD schemes, the header is ignored for encryption, and must be empty for decryption.
val encrypt : scipher_ctx ->
Netsys_types.memory -> Netsys_types.memory -> unitencrypt cctx inbuf outbuf: Encrypts the data in inbuf and writes
the result into outbuf. Both buffers must have the same size.
It is not allowed to pass the same buffer as inbuf and outbuf.
In order to encrypt long texts, it is allowed to call encrypt several
times in sequence.
val decrypt : scipher_ctx ->
Netsys_types.memory -> Netsys_types.memory -> booldecrypt cctx inbuf outbuf: Decrypts the data in inbuf and writes
the result into outbuf. Both buffers must have the same size.
It is not allowed to pass the same buffer as inbuf and outbuf.
The function returns true on success, and false if a problem
is detected.
In order to decrypt long texts, it is allowed to call decrypt several
times in sequence.
val mac : scipher_ctx -> stringReturns the MAC for AEAD ciphers. This is updated after
encrypt/decrypt. This function fails for non-AEAD ciphers.
