# Module Nettls_gnutls.Symmetric_crypto

    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 scipher

Describes a cipher

    val ciphers : scipher list

List 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 -> scipher

`find (name,mode)`: Looks up a cipher by name and mode, or raises Not_found

    val name : scipher -> string

Returns 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 -> string

Returns 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) list

Supported key lengths as pairs `min,max`. If there is a recommended key length, this should be the first.

    val iv_lengths : scipher -> (int * int) list

Supported iv lengths as pairs `min,max`. If there is a recommended iv length, this should be the first.

    val block_constraint : scipher -> int

The 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 -> bool

Whether this cipher integrates authentication

    type scipher_ctx

A cipher context stores processing data while encrypting or decrypting data

    val create : scipher ->
           string -> scipher_ctx

`create 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 -> unit

`set_iv cctx iv`: Sets the initialization vector. This is only allowed before encrypting or decrypting data

    val set_header : scipher_ctx -> string -> unit

`set_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 -> unit

`encrypt 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 -> bool

`decrypt 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 -> string

Returns the MAC for AEAD ciphers. This is updated after `encrypt`/`decrypt`. This function fails for non-AEAD ciphers.