13262741994

Committed 11 Feb 2025 12:19PM UTC coverage: 91.656% (-0.003%) from 91.659%

Build # 13262741994

Build Type

Pull #4647

github

Committed by

web-flow

Commit Message

Merge 0b8e56724 into f372b5a9e

Pull Request Pull Request #4647: Avoid using mem_ops.h or assert.h in public headers

Run Details

94864 of 103500 relevant lines covered (91.66%)

11330304.66 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

94.12

/src/lib/stream/stream_cipher.h

/*
* 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:
      ~StreamCipher() override = default;

      /**
      * 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 continous 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

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

randombit / botan / 13262741994

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous