/src/botan/build/include/public/botan/stream_cipher.h

Source
/*
* Stream Cipher
* (C) 1999-2007 Jack Lloyd
*
* Botan is released under the Simplified BSD License (see license.txt)
*/

#ifndef BOTAN_STREAM_CIPHER_H_
#define BOTAN_STREAM_CIPHER_H_

#include <botan/concepts.h>
#include <botan/secmem.h>
#include <botan/sym_algo.h>
#include <memory>
#include <string>
#include <string_view>
#include <vector>

namespace Botan {

/**
* Base class for all stream ciphers
*/
class BOTAN_PUBLIC_API(2, 0) StreamCipher : public SymmetricAlgorithm {
   public:
      /**
      * Create an instance based on a name
      * If provider is empty then best available is chosen.
      * @param algo_spec algorithm name
      * @param provider provider implementation to use
      * @return a null pointer if the algo/provider combination cannot be found
      */
      static std::unique_ptr<StreamCipher> create(std::string_view algo_spec, std::string_view provider = "");

      /**
      * Create an instance based on a name
      * If provider is empty then best available is chosen.
      * @param algo_spec algorithm name
      * @param provider provider implementation to use
      * Throws a Lookup_Error if the algo/provider combination cannot be found
      */
      static std::unique_ptr<StreamCipher> create_or_throw(std::string_view algo_spec, std::string_view provider = "");

      /**
      * @return list of available providers for this algorithm, empty if not available
      */
      static std::vector<std::string> providers(std::string_view algo_spec);

      /**
      * Encrypt or decrypt a message
      *
      * Processes all bytes plain/ciphertext from @p in and writes the result to
      * @p out.
      *
      * @param in the plaintext
      * @param out the byte array to hold the output, i.e. the ciphertext
      * @param len the length of both in and out in bytes
      */
      void cipher(const uint8_t in[], uint8_t out[], size_t len) { cipher_bytes(in, out, len); }

      /**
      * Encrypt or decrypt a message
      * @param in the plaintext
      * @param out the byte array to hold the output, i.e. the ciphertext
      *            with at least the same size as @p in
      */
      void cipher(std::span<const uint8_t> in, std::span<uint8_t> out);

      /**
      * Write keystream bytes to a buffer
      *
      * The contents of @p out are ignored/overwritten
      *
      * @param out the byte array to hold the keystream
      * @param len the length of out in bytes
      */
      void write_keystream(uint8_t out[], size_t len) { generate_keystream(out, len); }

      /**
      * Fill a given buffer with keystream bytes
      *
      * The contents of @p out are ignored/overwritten
      *
      * @param out the byte array to hold the keystream
      */
      void write_keystream(std::span<uint8_t> out) { generate_keystream(out.data(), out.size()); }

      /**
      * Get @p bytes from the keystream
      *
      * The bytes are written into a continuous byte buffer of your choosing.
      *
      * @param bytes The number of bytes to be produced
      */
      template <concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
      T keystream_bytes(size_t bytes) {
         T out(bytes);
         write_keystream(out);
         return out;
      }

      /**
      * Encrypt or decrypt a message
      * The message is encrypted/decrypted in place.
      * @param buf the plaintext / ciphertext
      * @param len the length of buf in bytes
      */
      void cipher1(uint8_t buf[], size_t len) { cipher(buf, buf, len); }

      /**
      * Encrypt or decrypt a message
      * The message is encrypted/decrypted in place.
      * @param buf the plaintext / ciphertext
      */
      void cipher1(std::span<uint8_t> buf) { cipher(buf, buf); }

      /**
      * Encrypt a message
      * The message is encrypted/decrypted in place.
      * @param inout the plaintext / ciphertext
      */
      void encipher(std::span<uint8_t> inout) { cipher(inout.data(), inout.data(), inout.size()); }

      /**
      * Encrypt a message
      * The message is encrypted in place.
      * @param inout the plaintext / ciphertext
      */
      void encrypt(std::span<uint8_t> inout) { cipher(inout.data(), inout.data(), inout.size()); }

      /**
      * Decrypt a message in place
      * The message is decrypted in place.
      * @param inout the plaintext / ciphertext
      */
      void decrypt(std::span<uint8_t> inout) { cipher(inout.data(), inout.data(), inout.size()); }

      /**
      * Return the optimium buffer size to use with this cipher
      *
      * Most stream ciphers internally produce blocks of bytes.  This function
      * returns that block size. Aligning buffer sizes to a multiple of this
      * size may improve performance by reducing internal buffering overhead.
      *
      * Note the return value of this function may change for any particular
      * algorithm due to changes in the implementation from release to release,
      * or changes in the runtime environment (such as CPUID indicating
      * availability of an optimized implementation). It is not intrinsic to
      * the algorithm; it is just a suggestion for gaining best performance.
      */
      virtual size_t buffer_size() const = 0;

      /**
      * Resync the cipher using the IV
      *
      * Load @p IV into the stream cipher state. This should happen after the
      * key is set (set_key()) and before any operation (encrypt(), decrypt() or
      * seek()) is called.
      *
      * If the cipher does not support IVs, then a call with an empty IV will be
      * accepted and any other length will cause an Invalid_IV_Length exception.
      *
      * @param iv the initialization vector
      * @param iv_len the length of the IV in bytes
      */
      void set_iv(const uint8_t iv[], size_t iv_len) { set_iv_bytes(iv, iv_len); }

      /**
      * Resync the cipher using the IV
      * @param iv the initialization vector
      * @throws Invalid_IV_Length if an incompatible IV was passed.
      */
      void set_iv(std::span<const uint8_t> iv) { set_iv_bytes(iv.data(), iv.size()); }

      /**
      * Return the default (preferred) nonce length
      *
      * If this function returns zero, then this cipher does not support nonces;
      * in this case any call to set_iv with a (non-empty) value will fail.
      *
      * Default implementation returns 0
      */
      virtual size_t default_iv_length() const;

      /**
      * @param iv_len the length of the IV in bytes
      * @return if the length is valid for this algorithm
      */
      virtual bool valid_iv_length(size_t iv_len) const { return (iv_len == 0); }

      /**
      * @return a new object representing the same algorithm as *this
      */
      StreamCipher* clone() const { return this->new_object().release(); }

      /**
      * @return new object representing the same algorithm as *this
      */
      virtual std::unique_ptr<StreamCipher> new_object() const = 0;

      /**
      * Set the offset and the state used later to generate the keystream
      *
      * Sets the state of the stream cipher and keystream according to the
      * passed @p offset, exactly as if @p offset bytes had first been
      * encrypted. The key and (if required) the IV have to be set before this
      * can be called.
      *
      * @note Not all ciphers support seeking; such objects will throw
      *       Not_Implemented in this case.
      *
      * @param offset the offset where we begin to generate the keystream
      */
      virtual void seek(uint64_t offset) = 0;

      /**
      * @return provider information about this implementation. Default is "base",
      * might also return "sse2", "avx2" or some other arbitrary string.
      */
      virtual std::string provider() const { return "base"; }

   protected:
      /**
      * Encrypt or decrypt a message
      */
      virtual void cipher_bytes(const uint8_t in[], uint8_t out[], size_t len) = 0;

      /**
      * Write keystream bytes to a buffer
      */
      virtual void generate_keystream(uint8_t out[], size_t len);

      /**
      * Resync the cipher using the IV
      */
      virtual void set_iv_bytes(const uint8_t iv[], size_t iv_len) = 0;
};

}  // namespace Botan

#endif

Coverage Report

Created: 2025-12-31 06:08

Line	Count	Source
1		/*
2		* Stream Cipher
3		* (C) 1999-2007 Jack Lloyd
4		*
5		* Botan is released under the Simplified BSD License (see license.txt)
6		*/
7
8		#ifndef BOTAN_STREAM_CIPHER_H_
9		#define BOTAN_STREAM_CIPHER_H_
10
11		#include <botan/concepts.h>
12		#include <botan/secmem.h>
13		#include <botan/sym_algo.h>
14		#include <memory>
15		#include <string>
16		#include <string_view>
17		#include <vector>
18
19		namespace Botan {
20
21		/**
22		* Base class for all stream ciphers
23		*/
24		class BOTAN_PUBLIC_API(2, 0) StreamCipher : public SymmetricAlgorithm {
25		public:
26		/**
27		* Create an instance based on a name
28		* If provider is empty then best available is chosen.
29		* @param algo_spec algorithm name
30		* @param provider provider implementation to use
31		* @return a null pointer if the algo/provider combination cannot be found
32		*/
33		static std::unique_ptr<StreamCipher> create(std::string_view algo_spec, std::string_view provider = "");
34
35		/**
36		* Create an instance based on a name
37		* If provider is empty then best available is chosen.
38		* @param algo_spec algorithm name
39		* @param provider provider implementation to use
40		* Throws a Lookup_Error if the algo/provider combination cannot be found
41		*/
42		static std::unique_ptr<StreamCipher> create_or_throw(std::string_view algo_spec, std::string_view provider = "");
43
44		/**
45		* @return list of available providers for this algorithm, empty if not available
46		*/
47		static std::vector<std::string> providers(std::string_view algo_spec);
48
49		/**
50		* Encrypt or decrypt a message
51		*
52		* Processes all bytes plain/ciphertext from @p in and writes the result to
53		* @p out.
54		*
55		* @param in the plaintext
56		* @param out the byte array to hold the output, i.e. the ciphertext
57		* @param len the length of both in and out in bytes
58		*/
59	0	void cipher(const uint8_t in[], uint8_t out[], size_t len) { cipher_bytes(in, out, len); }
60
61		/**
62		* Encrypt or decrypt a message
63		* @param in the plaintext
64		* @param out the byte array to hold the output, i.e. the ciphertext
65		* with at least the same size as @p in
66		*/
67		void cipher(std::span<const uint8_t> in, std::span<uint8_t> out);
68
69		/**
70		* Write keystream bytes to a buffer
71		*
72		* The contents of @p out are ignored/overwritten
73		*
74		* @param out the byte array to hold the keystream
75		* @param len the length of out in bytes
76		*/
77	0	void write_keystream(uint8_t out[], size_t len) { generate_keystream(out, len); }
78
79		/**
80		* Fill a given buffer with keystream bytes
81		*
82		* The contents of @p out are ignored/overwritten
83		*
84		* @param out the byte array to hold the keystream
85		*/
86	0	void write_keystream(std::span<uint8_t> out) { generate_keystream(out.data(), out.size()); }
87
88		/**
89		* Get @p bytes from the keystream
90		*
91		* The bytes are written into a continuous byte buffer of your choosing.
92		*
93		* @param bytes The number of bytes to be produced
94		*/
95		template <concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
96		T keystream_bytes(size_t bytes) {
97		T out(bytes);
98		write_keystream(out);
99		return out;
100		}
101
102		/**
103		* Encrypt or decrypt a message
104		* The message is encrypted/decrypted in place.
105		* @param buf the plaintext / ciphertext
106		* @param len the length of buf in bytes
107		*/
108	0	void cipher1(uint8_t buf[], size_t len) { cipher(buf, buf, len); }
109
110		/**
111		* Encrypt or decrypt a message
112		* The message is encrypted/decrypted in place.
113		* @param buf the plaintext / ciphertext
114		*/
115	0	void cipher1(std::span<uint8_t> buf) { cipher(buf, buf); }
116
117		/**
118		* Encrypt a message
119		* The message is encrypted/decrypted in place.
120		* @param inout the plaintext / ciphertext
121		*/
122	0	void encipher(std::span<uint8_t> inout) { cipher(inout.data(), inout.data(), inout.size()); }
123
124		/**
125		* Encrypt a message
126		* The message is encrypted in place.
127		* @param inout the plaintext / ciphertext
128		*/
129	0	void encrypt(std::span<uint8_t> inout) { cipher(inout.data(), inout.data(), inout.size()); }
130
131		/**
132		* Decrypt a message in place
133		* The message is decrypted in place.
134		* @param inout the plaintext / ciphertext
135		*/
136	0	void decrypt(std::span<uint8_t> inout) { cipher(inout.data(), inout.data(), inout.size()); }
137
138		/**
139		* Return the optimium buffer size to use with this cipher
140		*
141		* Most stream ciphers internally produce blocks of bytes. This function
142		* returns that block size. Aligning buffer sizes to a multiple of this
143		* size may improve performance by reducing internal buffering overhead.
144		*
145		* Note the return value of this function may change for any particular
146		* algorithm due to changes in the implementation from release to release,
147		* or changes in the runtime environment (such as CPUID indicating
148		* availability of an optimized implementation). It is not intrinsic to
149		* the algorithm; it is just a suggestion for gaining best performance.
150		*/
151		virtual size_t buffer_size() const = 0;
152
153		/**
154		* Resync the cipher using the IV
155		*
156		* Load @p IV into the stream cipher state. This should happen after the
157		* key is set (set_key()) and before any operation (encrypt(), decrypt() or
158		* seek()) is called.
159		*
160		* If the cipher does not support IVs, then a call with an empty IV will be
161		* accepted and any other length will cause an Invalid_IV_Length exception.
162		*
163		* @param iv the initialization vector
164		* @param iv_len the length of the IV in bytes
165		*/
166	0	void set_iv(const uint8_t iv[], size_t iv_len) { set_iv_bytes(iv, iv_len); }
167
168		/**
169		* Resync the cipher using the IV
170		* @param iv the initialization vector
171		* @throws Invalid_IV_Length if an incompatible IV was passed.
172		*/
173	0	void set_iv(std::span<const uint8_t> iv) { set_iv_bytes(iv.data(), iv.size()); }
174
175		/**
176		* Return the default (preferred) nonce length
177		*
178		* If this function returns zero, then this cipher does not support nonces;
179		* in this case any call to set_iv with a (non-empty) value will fail.
180		*
181		* Default implementation returns 0
182		*/
183		virtual size_t default_iv_length() const;
184
185		/**
186		* @param iv_len the length of the IV in bytes
187		* @return if the length is valid for this algorithm
188		*/
189	0	virtual bool valid_iv_length(size_t iv_len) const { return (iv_len == 0); }
190
191		/**
192		* @return a new object representing the same algorithm as *this
193		*/
194	0	StreamCipher* clone() const { return this->new_object().release(); }
195
196		/**
197		* @return new object representing the same algorithm as *this
198		*/
199		virtual std::unique_ptr<StreamCipher> new_object() const = 0;
200
201		/**
202		* Set the offset and the state used later to generate the keystream
203		*
204		* Sets the state of the stream cipher and keystream according to the
205		* passed @p offset, exactly as if @p offset bytes had first been
206		* encrypted. The key and (if required) the IV have to be set before this
207		* can be called.
208		*
209		* @note Not all ciphers support seeking; such objects will throw
210		* Not_Implemented in this case.
211		*
212		* @param offset the offset where we begin to generate the keystream
213		*/
214		virtual void seek(uint64_t offset) = 0;
215
216		/**
217		* @return provider information about this implementation. Default is "base",
218		* might also return "sse2", "avx2" or some other arbitrary string.
219		*/
220	0	virtual std::string provider() const { return "base"; }
221
222		protected:
223		/**
224		* Encrypt or decrypt a message
225		*/
226		virtual void cipher_bytes(const uint8_t in[], uint8_t out[], size_t len) = 0;
227
228		/**
229		* Write keystream bytes to a buffer
230		*/
231		virtual void generate_keystream(uint8_t out[], size_t len);
232
233		/**
234		* Resync the cipher using the IV
235		*/
236		virtual void set_iv_bytes(const uint8_t iv[], size_t iv_len) = 0;
237		};
238
239		} // namespace Botan
240
241		#endif