# # Cipher/mode_ctr.py : CTR mode # # =================================================================== # The contents of this file are dedicated to the public domain. To # the extent that dedication to the public domain is not available, # everyone is granted a worldwide, perpetual, royalty-free, # non-exclusive license to exercise all rights associated with the # contents of this file for any purpose whatsoever. # No rights are reserved. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS # BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN # ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE # SOFTWARE. # =================================================================== """ Counter (CTR) mode. """ from __future__ import annotations from typing import Any, Optional, Union, overload __all__ = ["CtrMode"] import struct from Crypto import MessageTooLongError from Crypto.Cipher._state_machine import Method from Crypto.Random import get_random_bytes from Crypto.Util._raw_api import ( SmartPointer, VoidPointer, c_size_t, c_uint8_ptr_len, c_uint8_ptr_out, create_output_buffer, get_raw_buffer, is_writeable_buffer, load_pycryptodome_raw_lib, ) from Crypto.Util._threads import range_boundaries, run_in_threads, threads_param from Crypto.Util.number import long_to_bytes Buffer = Union[bytes, bytearray, memoryview] raw_ctr_lib = load_pycryptodome_raw_lib( "Crypto.Cipher._raw_ctr", """ int CTR_start_operation(void *cipher, uint8_t initialCounterBlock[], size_t initialCounterBlock_len, size_t prefix_len, unsigned counter_len, unsigned littleEndian, void **pResult); int CTR_encrypt(void *ctrState, const uint8_t *in, uint8_t *out, size_t data_len); int CTR_decrypt(void *ctrState, const uint8_t *in, uint8_t *out, size_t data_len); int CTR_encrypt_at(const void *ctrState, const uint8_t *in, uint8_t *out, size_t offset, size_t data_len); int CTR_skip(void *ctrState, size_t data_len); int CTR_check(const void *ctrState, size_t data_len); int CTR_stop_operation(void *ctrState);""", ) # Minimum amount of data (1 MiB) that each thread must process: # with less, starting the thread costs more than what it saves. _MIN_BYTES_PER_THREAD = 1024 * 1024 def _ctr_threaded(state: Any, in_ptr: Any, out_ptr: Any, data_len: int, threads: int) -> int: """Encrypt or decrypt ``data_len`` bytes in CTR mode, by splitting them into ``threads`` contiguous ranges, which are processed in parallel. Fewer threads are used if a range would be shorter than ``_MIN_BYTES_PER_THREAD`` bytes. The calling thread processes the first range. ``state``, ``in_ptr`` and ``out_ptr`` are C pointers, whose types depend on the backend (cffi or ctypes): see :mod:`Crypto.Util._raw_api`. :return: the error code of the C library (0 for success) """ threads = min(threads, data_len // _MIN_BYTES_PER_THREAD) if threads <= 1: return raw_ctr_lib.CTR_encrypt(state, in_ptr, out_ptr, c_size_t(data_len)) # Like CTR_encrypt(), process nothing if the key stream runs out result = raw_ctr_lib.CTR_check(state, c_size_t(data_len)) if result: return result # Ranges may start in the middle of a cipher block: in CTR mode, each byte # of the key stream only depends on its position (see CTR_encrypt_at) bounds = range_boundaries(data_len, threads) def worker(i: int) -> int: # CTR_encrypt_at() does not change the state, and writes only # out_ptr[start:end] (no two threads write the same bytes) start, end = bounds[i], bounds[i + 1] return raw_ctr_lib.CTR_encrypt_at(state, in_ptr, out_ptr, c_size_t(start), c_size_t(end - start)) results: list[int] = [] try: results = run_in_threads(worker, threads) finally: # Move the state forward even after an error in a thread (some ranges may # be processed already), so that the same key stream cannot be used again skip_result = raw_ctr_lib.CTR_skip(state, c_size_t(data_len)) # Report the first error of a thread, if any for result in results: if result: return result return skip_result class CtrMode: """*CounTeR (CTR)* mode. This mode is very similar to ECB, in that encryption of one block is done independently of all other blocks. Unlike ECB, the block *position* contributes to the encryption and no information leaks about symbol frequency. Each message block is associated to a *counter* which must be unique across all messages that get encrypted with the same key (not just within the same message). The counter is as big as the block size. Counters can be generated in several ways. The most straightword one is to choose an *initial counter block* (which can be made public, similarly to the *IV* for the other modes) and increment its lowest **m** bits by one (modulo *2^m*) for each block. In most cases, **m** is chosen to be half the block size. See `NIST SP800-38A`_, Section 6.5 (for the mode) and Appendix B (for how to manage the *initial counter block*). .. _`NIST SP800-38A` : http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf """ def __init__( self, block_cipher: SmartPointer, initial_counter_block: Buffer, prefix_len: int, counter_len: int, little_endian: bool, threads: int = 1, ) -> None: """Create a new block cipher, configured in CTR mode. Args: block_cipher (C pointer): A smart pointer to the low-level block cipher instance. initial_counter_block (bytes/bytearray/memoryview): The initial plaintext to use to generate the key stream. It is as large as the cipher block, and it embeds the initial value of the counter. This value must not be reused. It shall contain a nonce or a random component. Reusing the *initial counter block* for encryptions performed with the same key compromises confidentiality. prefix_len (integer): The amount of bytes at the beginning of the counter block that never change. counter_len (integer): The length in bytes of the counter embedded in the counter block. little_endian (boolean): True if the counter in the counter block is an integer encoded in little endian mode. If False, it is big endian. threads (integer): The maximum number of threads used to process long data (0 for as many as the CPU cores available). """ self._threads = threads_param(threads) if len(initial_counter_block) == prefix_len + counter_len: self.nonce = bytes(initial_counter_block[:prefix_len]) """Nonce; not available if there is a fixed suffix""" state = VoidPointer() initial_counter_block_ptr, initial_counter_block_len = c_uint8_ptr_len(initial_counter_block) result = raw_ctr_lib.CTR_start_operation( block_cipher.get(), initial_counter_block_ptr, c_size_t(initial_counter_block_len), c_size_t(prefix_len), counter_len, little_endian, state.address_of(), ) if result: raise ValueError("Error %X while instantiating the CTR mode" % result) # Ensure that object disposal of this Python object will (eventually) # free the memory allocated by the raw library for the cipher mode self._state = SmartPointer(state.get(), raw_ctr_lib.CTR_stop_operation) # Memory allocated for the underlying block cipher is now owed # by the cipher mode block_cipher.release() self.block_size = len(initial_counter_block) """The block size of the underlying cipher, in bytes.""" self._next = [Method.ENCRYPT, Method.DECRYPT] @overload def encrypt(self, plaintext: Buffer) -> bytes: ... @overload def encrypt(self, plaintext: Buffer, output: Union[bytearray, memoryview]) -> None: ... def encrypt( self, plaintext: Buffer, output: Optional[Union[bytearray, memoryview]] = None ) -> Optional[bytes]: """Encrypt data with the key and the parameters set at initialization. A cipher object is stateful: once you have encrypted a message you cannot encrypt (or decrypt) another message using the same object. The data to encrypt can be broken up in two or more pieces and `encrypt` can be called multiple times. That is, the statement: >>> c.encrypt(a) + c.encrypt(b) is equivalent to: >>> c.encrypt(a+b) This function does not add any padding to the plaintext. Args: plaintext (bytes/bytearray/memoryview): The piece of data to encrypt. It can be of any length. Keyword Args: output (bytearray/memoryview): The location where the ciphertext must be written to. If ``None``, the ciphertext is returned. Returns: If ``output`` is ``None``, the ciphertext is returned as ``bytes``. Otherwise, ``None``. """ if Method.ENCRYPT not in self._next: raise TypeError("encrypt() cannot be called after decrypt()") self._next = [Method.ENCRYPT] return self._process(plaintext, output, "encrypting") @overload def decrypt(self, ciphertext: Buffer) -> bytes: ... @overload def decrypt(self, ciphertext: Buffer, output: Union[bytearray, memoryview]) -> None: ... def decrypt( self, ciphertext: Buffer, output: Optional[Union[bytearray, memoryview]] = None ) -> Optional[bytes]: """Decrypt data with the key and the parameters set at initialization. A cipher object is stateful: once you have decrypted a message you cannot decrypt (or encrypt) another message with the same object. The data to decrypt can be broken up in two or more pieces and `decrypt` can be called multiple times. That is, the statement: >>> c.decrypt(a) + c.decrypt(b) is equivalent to: >>> c.decrypt(a+b) This function does not remove any padding from the plaintext. Args: ciphertext (bytes/bytearray/memoryview): The piece of data to decrypt. It can be of any length. Keyword Args: output (bytearray/memoryview): The location where the plaintext must be written to. If ``None``, the plaintext is returned. Returns: If ``output`` is ``None``, the plaintext is returned as ``bytes``. Otherwise, ``None``. """ if Method.DECRYPT not in self._next: raise TypeError("decrypt() cannot be called after encrypt()") self._next = [Method.DECRYPT] return self._process(ciphertext, output, "decrypting") def _process( self, data: Buffer, output: Optional[Union[bytearray, memoryview]], what: str ) -> Optional[bytes]: """Encrypt or decrypt (which are the same operation in CTR mode)""" if output is None: result_buffer = create_output_buffer(len(data)) else: result_buffer = output if not is_writeable_buffer(output): raise TypeError("output must be a bytearray or a writeable memoryview") if len(data) != len(output): raise ValueError("output must have the same length as the input (%d bytes)" % len(data)) with c_uint8_ptr_out(result_buffer) as result_ptr: data_ptr, data_len = c_uint8_ptr_len(data) # Check the lengths of the buffers that C code gets if len(result_ptr) != data_len: raise ValueError("output must have the same length as the input (%d bytes)" % data_len) result = self._ctr(data_ptr, result_ptr, data_len) self._check(result, what) if output is None: return get_raw_buffer(result_buffer) else: return None def _ctr(self, in_ptr, out_ptr, data_len: int) -> int: if self._threads > 1: return _ctr_threaded(self._state.get(), in_ptr, out_ptr, data_len, self._threads) return raw_ctr_lib.CTR_encrypt(self._state.get(), in_ptr, out_ptr, c_size_t(data_len)) @staticmethod def _check(result: int, what: str) -> None: if result: if result == 0x60002: raise MessageTooLongError("The counter has wrapped around in CTR mode") raise ValueError("Error %X while %s in CTR mode" % (result, what)) def _create_ctr_cipher(factory, **kwargs): """Instantiate a cipher object that performs CTR encryption/decryption. Args: factory (module): The underlying block cipher, a module from ``Crypto.Cipher``. Keyword Args: nonce (bytes/bytearray/memoryview): The fixed part at the beginning of the counter block - the rest is the counter number that gets increased when processing the next block. The nonce must be such that no two messages are encrypted under the same key and the same nonce. The nonce must be shorter than the block size (it can have zero length; the counter is then as long as the block). If this parameter is not present, a random nonce will be created with length equal to half the block size. No random nonce shorter than 64 bits will be created though - you must really think through all security consequences of using such a short block size. initial_value (positive integer or bytes/bytearray/memoryview): The initial value for the counter. If not present, the cipher will start counting from 0. The value is incremented by one for each block. The counter number is encoded in big endian mode. counter (object): Instance of ``Crypto.Util.Counter``, which allows full customization of the counter block. This parameter is incompatible to both ``nonce`` and ``initial_value``. threads (integer): The maximum number of threads used to process long data (default: 1, no extra threads; 0 for all CPU cores). Any other keyword will be passed to the underlying block cipher. See the relevant documentation for details (at least ``key`` will need to be present). """ threads = kwargs.pop("threads", 1) cipher_state = factory._create_base_cipher(kwargs) counter = kwargs.pop("counter", None) nonce = kwargs.pop("nonce", None) initial_value = kwargs.pop("initial_value", None) if kwargs: raise TypeError("Invalid parameters for CTR mode: %s" % str(kwargs)) if counter is not None and (nonce, initial_value) != (None, None): raise TypeError("'counter' and 'nonce'/'initial_value' are mutually exclusive") if counter is None: # Crypto.Util.Counter is not used if nonce is None: if factory.block_size < 16: raise TypeError("Impossible to create a safe nonce for short block sizes") nonce = get_random_bytes(factory.block_size // 2) else: if len(nonce) >= factory.block_size: raise ValueError("Nonce is too long") # What is not nonce is counter counter_len = factory.block_size - len(nonce) if initial_value is None: initial_value = 0 if isinstance(initial_value, int): if (1 << (counter_len * 8)) - 1 < initial_value: raise ValueError("Initial counter value is too large") initial_counter_block = nonce + long_to_bytes(initial_value, counter_len) else: if len(initial_value) != counter_len: raise ValueError( "Incorrect length for counter byte string (%d bytes, expected %d)" % (len(initial_value), counter_len) ) initial_counter_block = nonce + initial_value return CtrMode( cipher_state, initial_counter_block, len(nonce), # prefix counter_len, False, # little_endian threads, ) # Crypto.Util.Counter is used # 'counter' used to be a callable object, but now it is # just a dictionary for backward compatibility. _counter = dict(counter) try: counter_len = _counter.pop("counter_len") prefix = _counter.pop("prefix") suffix = _counter.pop("suffix") initial_value = _counter.pop("initial_value") little_endian = _counter.pop("little_endian") except KeyError: raise TypeError("Incorrect counter object (use Crypto.Util.Counter.new)") # Compute initial counter block words = [] while initial_value > 0: words.append(struct.pack("B", initial_value & 255)) initial_value >>= 8 words += [b"\x00"] * max(0, counter_len - len(words)) if not little_endian: words.reverse() initial_counter_block = prefix + b"".join(words) + suffix if len(initial_counter_block) != factory.block_size: raise ValueError( "Size of the counter block (%d bytes) must match" " block size (%d)" % (len(initial_counter_block), factory.block_size) ) return CtrMode(cipher_state, initial_counter_block, len(prefix), counter_len, little_endian, threads)