(** Block cipher modes of operation.

    Provides module types for block cipher modes (ECB, CBC, CTR, GCM, CCM) and
    functors to construct them from a {{!Block.Core} core cipher}
    implementation. Includes AES and Triple-DES instantiations. *)

(** {1 Block cipher signatures} *)

(** Core block cipher primitive. *)
module Block : sig
  (** Low-level encrypt/decrypt with explicit block counts. *)
  module type Core = sig
    type ekey
    (** Encryption key schedule. *)

    type dkey
    (** Decryption key schedule. *)

    val of_secret : string -> ekey * dkey
    (** [of_secret s] derives both key schedules from [s]. *)

    val e_of_secret : string -> ekey
    (** [e_of_secret s] derives the encryption key schedule. *)

    val d_of_secret : string -> dkey
    (** [d_of_secret s] derives the decryption key schedule. *)

    val key : int array
    (** Supported key sizes in bytes. *)

    val block : int
    (** Block size in bytes. *)

    val encrypt :
      key:ekey -> blocks:int -> string -> int -> bytes -> int -> unit
    (** [encrypt ~key ~blocks src src_off dst dst_off] encrypts [blocks] blocks
        from [src] into [dst]. *)

    val decrypt :
      key:dkey -> blocks:int -> string -> int -> bytes -> int -> unit
    (** [decrypt ~key ~blocks src src_off dst dst_off] decrypts [blocks] blocks
        from [src] into [dst]. *)
  end

  (** Electronic Codebook mode. *)
  module type ECB = sig
    type key
    (** Cipher key. *)

    val of_secret : string -> key
    (** [of_secret s] constructs a key from [s]. *)

    val key_sizes : int array
    (** Supported key sizes in bytes. *)

    val block_size : int
    (** Block size in bytes. *)

    val encrypt : key:key -> string -> string
    (** [encrypt ~key data] encrypts [data]. *)

    val decrypt : key:key -> string -> string
    (** [decrypt ~key data] decrypts [data]. *)

    val encrypt_into :
      key:key -> string -> src_off:int -> bytes -> dst_off:int -> int -> unit
    (** [encrypt_into ~key src ~src_off dst ~dst_off len] encrypts [len] bytes
        from [src] into [dst]. *)

    val decrypt_into :
      key:key -> string -> src_off:int -> bytes -> dst_off:int -> int -> unit
    (** [decrypt_into ~key src ~src_off dst ~dst_off len] decrypts [len] bytes
        from [src] into [dst]. *)

    val unsafe_encrypt_into :
      key:key -> string -> src_off:int -> bytes -> dst_off:int -> int -> unit
    (** Like {!encrypt_into} without bounds checking. *)

    val unsafe_decrypt_into :
      key:key -> string -> src_off:int -> bytes -> dst_off:int -> int -> unit
    (** Like {!decrypt_into} without bounds checking. *)
  end

  (** Cipher Block Chaining mode. *)
  module type CBC = sig
    type key
    (** Cipher key. *)

    val of_secret : string -> key
    (** [of_secret s] constructs a key from [s]. *)

    val key_sizes : int array
    (** Supported key sizes in bytes. *)

    val block_size : int
    (** Block size in bytes. *)

    val encrypt : key:key -> iv:string -> string -> string
    (** [encrypt ~key ~iv data] encrypts [data] with initialisation vector [iv].
    *)

    val decrypt : key:key -> iv:string -> string -> string
    (** [decrypt ~key ~iv data] decrypts [data]. *)

    val next_iv : ?off:int -> string -> iv:string -> string
    (** [next_iv ~off ct ~iv] computes the IV for the next message from the last
        block of ciphertext [ct]. *)

    val encrypt_into :
      key:key ->
      iv:string ->
      string ->
      src_off:int ->
      bytes ->
      dst_off:int ->
      int ->
      unit
    (** [encrypt_into ~key ~iv src ~src_off dst ~dst_off len] encrypts [len]
        bytes from [src] into [dst]. *)

    val decrypt_into :
      key:key ->
      iv:string ->
      string ->
      src_off:int ->
      bytes ->
      dst_off:int ->
      int ->
      unit
    (** [decrypt_into ~key ~iv src ~src_off dst ~dst_off len] decrypts [len]
        bytes from [src] into [dst]. *)

    val unsafe_encrypt_into :
      key:key ->
      iv:string ->
      string ->
      src_off:int ->
      bytes ->
      dst_off:int ->
      int ->
      unit
    (** Like {!encrypt_into} without bounds checking. *)

    val unsafe_decrypt_into :
      key:key ->
      iv:string ->
      string ->
      src_off:int ->
      bytes ->
      dst_off:int ->
      int ->
      unit
    (** Like {!decrypt_into} without bounds checking. *)

    val unsafe_encrypt_into_inplace :
      key:key -> iv:string -> bytes -> dst_off:int -> int -> unit
    (** Like {!unsafe_encrypt_into} but encrypts the buffer in place. *)
  end

  (** Counter mode. *)
  module type CTR = sig
    type key
    (** Cipher key. *)

    val of_secret : string -> key
    (** [of_secret s] constructs a key from [s]. *)

    val key_sizes : int array
    (** Supported key sizes in bytes. *)

    val block_size : int
    (** Block size in bytes. *)

    type ctr
    (** Counter value. *)

    val add_ctr : ctr -> int64 -> ctr
    (** [add_ctr ctr n] increments [ctr] by [n]. *)

    val next_ctr : ?off:int -> string -> ctr:ctr -> ctr
    (** [next_ctr ~off msg ~ctr] advances [ctr] past [msg]. *)

    val ctr_of_octets : string -> ctr
    (** [ctr_of_octets s] decodes a counter from [s]. *)

    val stream : key:key -> ctr:ctr -> int -> string
    (** [stream ~key ~ctr n] generates [n] bytes of key stream. *)

    val encrypt : key:key -> ctr:ctr -> string -> string
    (** [encrypt ~key ~ctr data] encrypts [data]. *)

    val decrypt : key:key -> ctr:ctr -> string -> string
    (** [decrypt ~key ~ctr data] decrypts [data]. *)

    val stream_into : key:key -> ctr:ctr -> bytes -> off:int -> int -> unit
    (** [stream_into ~key ~ctr buf ~off len] writes [len] bytes of key stream
        into [buf]. *)

    val encrypt_into :
      key:key ->
      ctr:ctr ->
      string ->
      src_off:int ->
      bytes ->
      dst_off:int ->
      int ->
      unit
    (** [encrypt_into ~key ~ctr src ~src_off dst ~dst_off len] encrypts [len]
        bytes from [src] into [dst]. *)

    val decrypt_into :
      key:key ->
      ctr:ctr ->
      string ->
      src_off:int ->
      bytes ->
      dst_off:int ->
      int ->
      unit
    (** [decrypt_into ~key ~ctr src ~src_off dst ~dst_off len] decrypts [len]
        bytes from [src] into [dst]. *)

    val unsafe_stream_into :
      key:key -> ctr:ctr -> bytes -> off:int -> int -> unit
    (** Like {!stream_into} without bounds checking. *)

    val unsafe_encrypt_into :
      key:key ->
      ctr:ctr ->
      string ->
      src_off:int ->
      bytes ->
      dst_off:int ->
      int ->
      unit
    (** Like {!encrypt_into} without bounds checking. *)

    val unsafe_decrypt_into :
      key:key ->
      ctr:ctr ->
      string ->
      src_off:int ->
      bytes ->
      dst_off:int ->
      int ->
      unit
    (** Like {!decrypt_into} without bounds checking. *)
  end

  (** Galois/Counter Mode. *)
  module type GCM = sig
    include Aead.AEAD

    val key_sizes : int array
    (** Supported key sizes in bytes. *)

    val block_size : int
    (** Block size in bytes. *)
  end

  (** Counter with CBC-MAC (16-byte tag). *)
  module type CCM16 = sig
    include Aead.AEAD

    val key_sizes : int array
    (** Supported key sizes in bytes. *)

    val block_size : int
    (** Block size in bytes. *)
  end
end

(** {1 Counter representations} *)

(** Counter arithmetic for CTR mode. *)
module Counters : sig
  (** Counter operations. *)
  module type S = sig
    type ctr
    (** Counter value. *)

    val size : int
    (** Counter size in bytes. *)

    val add : ctr -> int64 -> ctr
    (** [add ctr n] increments [ctr] by [n]. *)

    val of_octets : string -> ctr
    (** [of_octets s] decodes a counter from [s]. *)

    val unsafe_count_into : ctr -> bytes -> off:int -> blocks:int -> unit
    (** [unsafe_count_into ctr buf ~off ~blocks] writes [blocks] consecutive
        counter values into [buf]. *)
  end

  module C64be : S with type ctr = int64
  (** Big-endian 64-bit counter. *)

  module C128be : S with type ctr = int64 * int64
  (** Big-endian 128-bit counter. *)

  module C128be32 : S with type ctr = int64 * int64
  (** Big-endian 128-bit counter, incrementing only the lower 32 bits. *)
end

(** {1 Mode functors} *)

(** Constructors for block cipher modes from a core primitive. *)
module Modes : sig
  module ECB_of (Core : Block.Core) : Block.ECB
  module CBC_of (Core : Block.Core) : Block.CBC

  module CTR_of (Core : Block.Core) (Ctr : Counters.S) :
    Block.CTR with type key = Core.ekey and type ctr = Ctr.ctr

  module GCM_of (Core : Block.Core) : Block.GCM
  module CCM16_of (Core : Block.Core) : Block.CCM16
end

(** {1 Cipher instantiations} *)

(** AES (128, 192, and 256-bit keys). *)
module AES : sig
  module Core : Block.Core
  module ECB : Block.ECB
  module CBC : Block.CBC
  module CTR : Block.CTR with type ctr = int64 * int64
  module GCM : Block.GCM
  module CCM16 : Block.CCM16
end

(** Triple DES (168-bit key as 3 x 56-bit). *)
module DES : sig
  module Core : Block.Core
  module ECB : Block.ECB
  module CBC : Block.CBC
  module CTR : Block.CTR with type ctr = int64
end

val accelerated : [ `XOR | `AES | `GHASH ] list
(** [accelerated] is the list of hardware-accelerated operations detected at
    startup. *)