.. index:: single: block_cipher_modes_common
.. _block_cipher_modes_common/0:

.. rst-class:: right

**category**

``block_cipher_modes_common``
=============================

Shared validation, block, XOR, and PKCS#7 predicates for block cipher modes.

| **Availability:** 
|    ``logtalk_load(block_ciphers(loader))``

| **Author:** Paulo Moura
| **Version:** 1:0:0
| **Date:** 2026-08-08

| **Compilation flags:**
|    ``static``


| **Uses:**
|    :ref:`list <list/0>`
|    :ref:`type <type/0>`

| **Remarks:**
|    (none)

| **Inherited public predicates:**
|    (none)

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

(no local declarations; see entity ancestors if any)

Protected predicates
--------------------

.. index:: prepare_cipher/4
.. _block_cipher_modes_common/0::prepare_cipher/4:

``prepare_cipher/4``
^^^^^^^^^^^^^^^^^^^^

Validates a cipher object, queries its block size, and prepares a key.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``prepare_cipher(Cipher,Key,BlockSize,PreparedKey)``
| **Mode and number of proofs:**
|    ``prepare_cipher(+object_identifier,+list(byte),--positive_integer,--compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Cipher`` is a variable:
|        ``instantiation_error``
|    ``Cipher`` is not a variable but does not implement the prepared-key block cipher protocol:
|        ``domain_error(block_cipher,Cipher)``
|    ``Cipher`` implements he prepared-key block cipher protocol but reports an invalid block size:
|        ``domain_error(block_cipher_block_size,BlockSize)``
|    ``Key`` is invalid for ``Cipher``:
|        ``type_error(list(byte,KeySize),Key)``


------------

.. index:: check_bytes/1
.. _block_cipher_modes_common/0::check_bytes/1:

``check_bytes/1``
^^^^^^^^^^^^^^^^^

Checks a list of bytes.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``check_bytes(Bytes)``
| **Mode and number of proofs:**
|    ``check_bytes(+list(byte))`` - ``one_or_error``

| **Exceptions:**
|    ``Bytes`` is a variable or a partial list:
|        ``instantiation_error``
|    ``Bytes`` is neither a partial list nor a list:
|        ``type_error(list,Bytes)``
|    An element ``Byte`` of the ``Bytes`` list is neither a variable nor an integer:
|        ``type_error(integer,Byte)``
|    An element ``Byte`` of the ``Bytes`` list is an integer but not a valid byte:
|        ``domain_error(byte,Byte)``


------------

.. index:: check_block/2
.. _block_cipher_modes_common/0::check_block/2:

``check_block/2``
^^^^^^^^^^^^^^^^^

Checks a byte list whose length is exactly one block.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``check_block(BlockSize,Block)``
| **Mode and number of proofs:**
|    ``check_block(+positive_integer,+list(byte))`` - ``one_or_error``

| **Exceptions:**
|    ``BlockSize`` is a variable:
|        ``instantiation_error``
|    ``BlockSize`` is neither a variable nor an integer:
|        ``type_error(integer,BlockSize)``
|    ``BlockSize`` is an integer but not a positive integer:
|        ``domain_error(positive_integer,BlockSize)``
|    ``Block`` is a variable or a partial list:
|        ``instantiation_error``
|    ``Block`` is not a list of exactly ``BlockSize`` bytes:
|        ``type_error(list(byte,BlockSize),Block)``
|    An element ``Byte`` of the `Block`` list is neither a variable nor an integer:
|        ``type_error(integer,Byte)``
|    An element ``Byte`` of the ``Block`` list is an integer but not a valid byte:
|        ``domain_error(byte,Byte)``


------------

.. index:: check_aligned/2
.. _block_cipher_modes_common/0::check_aligned/2:

``check_aligned/2``
^^^^^^^^^^^^^^^^^^^

Checks that a byte-list length is a multiple of the block size.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``check_aligned(BlockSize,Bytes)``
| **Mode and number of proofs:**
|    ``check_aligned(+positive_integer,+list(byte))`` - ``one_or_error``

| **Exceptions:**
|    ``BlockSize`` is a variable:
|        ``instantiation_error``
|    ``BlockSize`` is neither a variable nor an integer:
|        ``type_error(integer,BlockSize)``
|    ``BlockSize`` is an integer but not a positive integer:
|        ``domain_error(positive_integer,BlockSize)``
|    ``Bytes`` length is not a multiple of ``BlockSize``:
|        ``domain_error(block_aligned_byte_length(BlockSize),Bytes)``


------------

.. index:: blocks/3
.. _block_cipher_modes_common/0::blocks/3:

``blocks/3``
^^^^^^^^^^^^

Splits an aligned byte list into blocks.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``blocks(BlockSize,Bytes,Blocks)``
| **Mode and number of proofs:**
|    ``blocks(+positive_integer,+list(byte),--list(list(byte)))`` - ``one``


------------

.. index:: xor_bytes/3
.. _block_cipher_modes_common/0::xor_bytes/3:

``xor_bytes/3``
^^^^^^^^^^^^^^^

XORs equal-length byte lists.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``xor_bytes(Bytes1,Bytes2,Bytes)``
| **Mode and number of proofs:**
|    ``xor_bytes(+list(byte),+list(byte),--list(byte))`` - ``one``


------------

.. index:: pkcs7_pad/3
.. _block_cipher_modes_common/0::pkcs7_pad/3:

``pkcs7_pad/3``
^^^^^^^^^^^^^^^

Pads bytes using PKCS#7.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``pkcs7_pad(BlockSize,Bytes,PaddedBytes)``
| **Mode and number of proofs:**
|    ``pkcs7_pad(+positive_integer,+list(byte),--list(byte))`` - ``one_or_error``

| **Exceptions:**
|    ``BlockSize`` exceeds the maximum PKCS#7 block size:
|        ``domain_error(pkcs7_block_size,BlockSize)``


------------

.. index:: pkcs7_unpad/4
.. _block_cipher_modes_common/0::pkcs7_unpad/4:

``pkcs7_unpad/4``
^^^^^^^^^^^^^^^^^

Validates and removes PKCS#7 padding, reporting the supplied error value when padding is invalid.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``pkcs7_unpad(BlockSize,PaddedBytes,ErrorValue,Bytes)``
| **Mode and number of proofs:**
|    ``pkcs7_unpad(+positive_integer,+list(byte),+term,--list(byte))`` - ``one_or_error``

| **Exceptions:**
|    ``BlockSize`` exceeds the maximum PKCS#7 block size:
|        ``domain_error(pkcs7_block_size,BlockSize)``
|    ``PaddedBytes`` does not contain valid PKCS#7 padding:
|        ``domain_error(pkcs7_padding,ErrorValue)``


------------

Private predicates
------------------

(no local declarations; see entity ancestors if any)

Operators
---------

(none)