.. index:: single: cbc
.. _cbc/0:

.. rst-class:: right

**object**

``cbc``
=======

Generic Cipher Block Chaining mode encryption and decryption.

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

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

| **Compilation flags:**
|    ``static, context_switching_calls``


| **Imports:**
|    ``public`` :ref:`block_cipher_modes_common <block_cipher_modes_common/0>`
| **Uses:**
|    :ref:`list <list/0>`

| **Remarks:**
|    (none)

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

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

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

.. index:: encrypt/5
.. _cbc/0::encrypt/5:

``encrypt/5``
^^^^^^^^^^^^^

Encrypts block-aligned plaintext without padding using an explicit initialization vector.

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

| **Template:**
|    ``encrypt(Cipher,Key,IV,Plaintext,Ciphertext)``
| **Mode and number of proofs:**
|    ``encrypt(+object_identifier,+list(byte),+list(byte),+list(byte),--list(byte))`` - ``one_or_error``

| **Exceptions:**
|    ``Cipher`` is a variable:
|        ``instantiation_error``
|    ``Cipher`` is neither a variable nor a prepared-key block cipher object:
|        ``domain_error(block_cipher,Cipher)``
|    ``IV`` is not a byte list of exactly one block:
|        ``type_error(list(byte,BlockSize),IV)``
|    ``Plaintext`` is a variable or a partial list:
|        ``instantiation_error``
|    ``Plaintext`` is neither a partial list nor a list:
|        ``type_error(list,Plaintext)``
|    An element ``Byte`` of the ``Plaintext`` list is neither a variable nor an integer:
|        ``type_error(integer,Byte)``
|    An element ``Byte`` of the ``Plaintext`` list is an integer but not a valid byte:
|        ``domain_error(byte,Byte)``
|    ``Plaintext`` length is not block aligned:
|        ``domain_error(block_aligned_byte_length(BlockSize),Plaintext)``


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

.. index:: decrypt/5
.. _cbc/0::decrypt/5:

``decrypt/5``
^^^^^^^^^^^^^

Decrypts block-aligned ciphertext without removing padding using an explicit initialization vector.

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

| **Template:**
|    ``decrypt(Cipher,Key,IV,Ciphertext,Plaintext)``
| **Mode and number of proofs:**
|    ``decrypt(+object_identifier,+list(byte),+list(byte),+list(byte),--list(byte))`` - ``one_or_error``

| **Exceptions:**
|    ``Cipher`` is a variable:
|        ``instantiation_error``
|    ``Cipher`` is neither a variable nor a prepared-key block cipher object:
|        ``domain_error(block_cipher,Cipher)``
|    ``IV`` is not a byte list of exactly one block:
|        ``type_error(list(byte,BlockSize),IV)``
|    ``Ciphertext`` is a variable or a partial list:
|        ``instantiation_error``
|    ``Ciphertext`` is neither a partial list nor a list:
|        ``type_error(list,Ciphertext)``
|    An element ``Byte`` of the ``Ciphertext`` list is neither a variable nor an integer:
|        ``type_error(integer,Byte)``
|    An element ``Byte`` of the ``Ciphertext`` list is an integer but not a valid byte:
|        ``domain_error(byte,Byte)``
|    ``Ciphertext`` length is not block aligned:
|        ``domain_error(block_aligned_byte_length(BlockSize),Ciphertext)``


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

.. index:: encrypt_padded/5
.. _cbc/0::encrypt_padded/5:

``encrypt_padded/5``
^^^^^^^^^^^^^^^^^^^^

Pads plaintext using PKCS#7 and encrypts it using an explicit initialization vector.

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

| **Template:**
|    ``encrypt_padded(Cipher,Key,IV,Plaintext,Ciphertext)``
| **Mode and number of proofs:**
|    ``encrypt_padded(+object_identifier,+list(byte),+list(byte),+list(byte),--list(byte))`` - ``one_or_error``

| **Exceptions:**
|    ``Cipher`` is a variable:
|        ``instantiation_error``
|    ``Cipher`` is neither a variable nor a prepared-key block cipher object:
|        ``domain_error(block_cipher,Cipher)``
|    ``Cipher`` block size exceeds the PKCS#7 limit:
|        ``domain_error(pkcs7_block_size,BlockSize)``
|    ``IV`` is not a byte list of exactly one block:
|        ``type_error(list(byte,BlockSize),IV)``
|    ``Plaintext`` is a variable or a partial list:
|        ``instantiation_error``
|    ``Plaintext`` is neither a partial list nor a list:
|        ``type_error(list,Plaintext)``
|    An element ``Byte`` of the ``Plaintext`` list is neither a variable nor an integer:
|        ``type_error(integer,Byte)``
|    An element ``Byte`` of the ``Plaintext`` list is an integer but not a valid byte:
|        ``domain_error(byte,Byte)``


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

.. index:: decrypt_padded/5
.. _cbc/0::decrypt_padded/5:

``decrypt_padded/5``
^^^^^^^^^^^^^^^^^^^^

Decrypts ciphertext and validates and removes PKCS#7 padding using an explicit initialization vector.

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

| **Template:**
|    ``decrypt_padded(Cipher,Key,IV,Ciphertext,Plaintext)``
| **Mode and number of proofs:**
|    ``decrypt_padded(+object_identifier,+list(byte),+list(byte),+list(byte),--list(byte))`` - ``one_or_error``

| **Exceptions:**
|    ``Cipher`` is a variable:
|        ``instantiation_error``
|    ``Cipher`` is neither a variable nor a prepared-key block cipher object:
|        ``domain_error(block_cipher,Cipher)``
|    ``IV`` is not a byte list of exactly one block:
|        ``type_error(list(byte,BlockSize),IV)``
|    ``Ciphertext`` is a variable or a partial list:
|        ``instantiation_error``
|    ``Ciphertext`` is neither a partial list nor a list:
|        ``type_error(list,Ciphertext)``
|    An element ``Byte`` of the ``Ciphertext`` list is neither a variable nor an integer:
|        ``type_error(integer,Byte)``
|    An element ``Byte`` of the ``Ciphertext`` list is an integer but not a valid byte:
|        ``domain_error(byte,Byte)``
|    ``Ciphertext`` is empty:
|        ``domain_error(non_empty_ciphertext,Ciphertext)``
|    ``Ciphertext`` length is not block aligned:
|        ``domain_error(block_aligned_byte_length(BlockSize),Ciphertext)``
|    ``Ciphertext`` does not contain valid PKCS#7 padding:
|        ``domain_error(pkcs7_padding,Ciphertext)``


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

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

(no local declarations; see entity ancestors if any)

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

(no local declarations; see entity ancestors if any)

Operators
---------

(none)