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

Source (jump to first uncovered line)
/*
* 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/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:
      virtual ~StreamCipher() = 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
      * @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) {
         BOTAN_ARG_CHECK(in.size() <= out.size(),
                         "Output buffer of stream cipher must be at least as long as input buffer");
         cipher_bytes(in.data(), out.data(), in.size());
      }

      /**
      * 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
      *
      * @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
      * @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
      */
      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 0, then this cipher does not support nonces
      *
      * 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
      * @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) {
         clear_mem(out, len);
         cipher1(out, 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: 2023-06-07 07:00

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