Botan 3.8.0
Crypto and TLS for C&
stream_cipher.h
Go to the documentation of this file.
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
19namespace Botan {
20
21/**
22* Base class for all stream ciphers
23*/
25 public:
26 ~StreamCipher() override = default;
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); }
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); }
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()); }
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) {
99 T out(bytes);
100 write_keystream(out);
101 return out;
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); }
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()); }
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()); }
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); }
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()); }
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); }
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"; }
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
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:19
~StreamCipher() override=default
virtual size_t buffer_size() const =0
void cipher1(uint8_t buf[], size_t len)
T keystream_bytes(size_t bytes)
void set_iv(const uint8_t iv[], size_t iv_len)
static std::unique_ptr< StreamCipher > create_or_throw(std::string_view algo_spec, std::string_view provider="")
virtual void set_iv_bytes(const uint8_t iv[], size_t iv_len)=0
static std::unique_ptr< StreamCipher > create(std::string_view algo_spec, std::string_view provider="")
void decrypt(std::span< uint8_t > inout)
void encipher(std::span< uint8_t > inout)
StreamCipher * clone() const
void set_iv(std::span< const uint8_t > iv)
void write_keystream(std::span< uint8_t > out)
virtual std::unique_ptr< StreamCipher > new_object() const =0
void write_keystream(uint8_t out[], size_t len)
void encrypt(std::span< uint8_t > inout)
virtual void seek(uint64_t offset)=0
virtual void generate_keystream(uint8_t out[], size_t len)
void cipher1(std::span< uint8_t > buf)
virtual bool valid_iv_length(size_t iv_len) const
virtual void cipher_bytes(const uint8_t in[], uint8_t out[], size_t len)=0
static std::vector< std::string > providers(std::string_view algo_spec)
void cipher(const uint8_t in[], uint8_t out[], size_t len)
virtual std::string provider() const