Botan 2.1.0 Crypto and TLS for C++11

- Main Page
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Member Functions | Protected Member Functions | List of all members
Botan::XTS_Encryption Class Referencefinal

`#include <xts.h>`

Inheritance diagram for Botan::XTS_Encryption:

## Public Member Functions
virtual bool | authenticated () const
void | clear () override
size_t | default_nonce_length () const override
void | finish (secure_vector< uint8_t > &final_block, size_t offset=0) override
Key_Length_Specification | key_spec () const override
size_t | minimum_final_size () const override
std::string | name () const override
size_t | output_length (size_t input_length) const override
size_t | process (uint8_t buf[], size_t size) override
virtual std::string | provider () const
void | reset () override
template<typename Alloc >
void | set_key (const std::vector< uint8_t, Alloc > &key)
void | set_key (const SymmetricKey &key)
void | set_key (const uint8_t key[], size_t length)
template<typename Alloc >
void | start (const std::vector< uint8_t, Alloc > &nonce)
void | start (const uint8_t nonce[], size_t nonce_len)
void | start ()
virtual size_t | tag_size () const
void | update (secure_vector< uint8_t > &buffer, size_t offset=0)
size_t | update_granularity () const override
bool | valid_keylength (size_t length) const
bool | valid_nonce_length (size_t n) const override
| XTS_Encryption (BlockCipher *cipher)

## Protected Member Functions
const BlockCipher & | cipher () const
const uint8_t * | tweak () const
void | update_tweak (size_t last_used)

## Detailed Description

IEEE P1619 XTS Encryption

Definition at line 59 of file xts.h.

## Constructor & Destructor Documentation

Botan::XTS_Encryption::XTS_Encryption | ( | BlockCipher * | cipher | ) |
| inline explicit

Parameters

  cipher | underlying block cipher

Definition at line 65 of file xts.h.

65 : XTS_Mode(cipher) {}
Botan::XTS_Mode::XTS_Mode
XTS_Mode(BlockCipher *cipher)
Definition: xts.cpp:52
Botan::XTS_Mode::cipher
const BlockCipher & cipher() const
Definition: xts.h:44

## Member Function Documentation

virtual bool Botan::Cipher_Mode::authenticated | ( |  | ) | const
| inline virtual inherited

Returns
  true iff this mode provides authentication as well as confidentiality.

Reimplemented in Botan::AEAD_Mode.

Definition at line 145 of file cipher_mode.h.

145 { return false; }

const BlockCipher& Botan::XTS_Mode::cipher | ( |  | ) | const
| inline protected inherited

Definition at line 44 of file xts.h.

Referenced by Botan::XTS_Mode::default_nonce_length(), finish(), Botan::XTS_Decryption::finish(), Botan::XTS_Mode::key_spec(), Botan::XTS_Mode::minimum_final_size(), Botan::XTS_Mode::name(), process(), Botan::XTS_Decryption::process(), Botan::XTS_Mode::update_granularity(), and Botan::XTS_Mode::valid_nonce_length().

44 { return *m_cipher; }

void Botan::XTS_Mode::clear | ( |  | ) |
| override virtual inherited

Zeroise all state See also reset_msg()

Implements Botan::Cipher_Mode.

Definition at line 61 of file xts.cpp.

References Botan::XTS_Mode::reset().

62 {
63 m_cipher->clear();
64 m_tweak_cipher->clear();
65 reset();
66 }
Botan::XTS_Mode::reset
void reset() override
Definition: xts.cpp:68

size_t Botan::XTS_Mode::default_nonce_length | ( |  | ) | const
| override virtual inherited

Returns
  the default size for a nonce

Implements Botan::Cipher_Mode.

Definition at line 93 of file xts.cpp.

References Botan::BlockCipher::block_size(), and Botan::XTS_Mode::cipher().

94 {
95 return cipher().block_size();
96 }
Botan::XTS_Mode::cipher
const BlockCipher & cipher() const
Definition: xts.h:44
Botan::BlockCipher::block_size
virtual size_t block_size() const =0

void Botan::XTS_Encryption::finish | ( | secure_vector< uint8_t > & | final_block,
|  | size_t | offset = `0`
| ) |  |
| override virtual

Complete processing of a message.

Parameters

  final_block | in/out parameter which must be at least minimum_final_size() bytes, and will be set to any final output
  offset | an offset into final_block to begin processing

Implements Botan::Cipher_Mode.

Definition at line 170 of file xts.cpp.

References Botan::BlockCipher::block_size(), BOTAN_ASSERT, Botan::XTS_Mode::cipher(), Botan::BlockCipher::encrypt(), Botan::XTS_Mode::minimum_final_size(), Botan::XTS_Mode::tweak(), Botan::Cipher_Mode::update(), and Botan::xor_buf().

171 {
172 BOTAN_ASSERT(buffer.size() >= offset, "Offset is sane");
173 const size_t sz = buffer.size() - offset;
174 uint8_t* buf = buffer.data() + offset;
175
176 BOTAN_ASSERT(sz >= minimum_final_size(), "Have sufficient final input");
177
178 const size_t BS = cipher().block_size();
179
180 if(sz % BS == 0)
181 {
182 update(buffer, offset);
183 }
184 else
185 {
186 // steal ciphertext
187 const size_t full_blocks = ((sz / BS) - 1) * BS;
188 const size_t final_bytes = sz - full_blocks;
189 BOTAN_ASSERT(final_bytes > BS && final_bytes < 2*BS, "Left over size in expected range");
190
191 secure_vector<uint8_t> last(buf + full_blocks, buf + full_blocks + final_bytes);
192 buffer.resize(full_blocks + offset);
193 update(buffer, offset);
194
195 xor_buf(last, tweak(), BS);
196 cipher().encrypt(last);
197 xor_buf(last, tweak(), BS);
198
199 for(size_t i = 0; i != final_bytes - BS; ++i)
200 {
201 last[i] ^= last[i + BS];
202 last[i + BS] ^= last[i];
203 last[i] ^= last[i + BS];
204 }
205
206 xor_buf(last, tweak() + BS, BS);
207 cipher().encrypt(last);
208 xor_buf(last, tweak() + BS, BS);
209
210 buffer += last;
211 }
212 }
Botan::xor_buf
void xor_buf(T out[], const T in[], size_t length)
Definition: mem_ops.h:115
Botan::BlockCipher::encrypt
void encrypt(const uint8_t in[], uint8_t out[]) const
Definition: block_cipher.h:80
Botan::Cipher_Mode::update
void update(secure_vector< uint8_t > &buffer, size_t offset=0)
Definition: cipher_mode.h:81
BOTAN_ASSERT
#define BOTAN_ASSERT(expr, assertion_made)
Definition: assert.h:27
Botan::XTS_Mode::cipher
const BlockCipher & cipher() const
Definition: xts.h:44
Botan::XTS_Mode::minimum_final_size
size_t minimum_final_size() const override
Definition: xts.cpp:83
Botan::BlockCipher::block_size
virtual size_t block_size() const =0
Botan::XTS_Mode::tweak
const uint8_t * tweak() const
Definition: xts.h:42

Key_Length_Specification Botan::XTS_Mode::key_spec | ( |  | ) | const
| override virtual inherited

Returns
  object describing limits on key size

Implements Botan::Cipher_Mode.

Definition at line 88 of file xts.cpp.

References Botan::XTS_Mode::cipher(), Botan::SymmetricAlgorithm::key_spec(), and Botan::Key_Length_Specification::multiple().

89 {
90 return cipher().key_spec().multiple(2);
91 }
Botan::Key_Length_Specification::multiple
Key_Length_Specification multiple(size_t n) const
Definition: key_spec.h:87
Botan::XTS_Mode::cipher
const BlockCipher & cipher() const
Definition: xts.h:44
Botan::SymmetricAlgorithm::key_spec
virtual Key_Length_Specification key_spec() const =0

size_t Botan::XTS_Mode::minimum_final_size | ( |  | ) | const
| override virtual inherited

Returns
  required minimium size to finalize() - may be any length larger than this.

Implements Botan::Cipher_Mode.

Definition at line 83 of file xts.cpp.

References Botan::BlockCipher::block_size(), and Botan::XTS_Mode::cipher().

Referenced by finish(), and Botan::XTS_Decryption::finish().

84 {
85 return cipher().block_size() + 1;
86 }
Botan::XTS_Mode::cipher
const BlockCipher & cipher() const
Definition: xts.h:44
Botan::BlockCipher::block_size
virtual size_t block_size() const =0

std::string Botan::XTS_Mode::name | ( |  | ) | const
| override virtual inherited

Implements Botan::Cipher_Mode.

Definition at line 73 of file xts.cpp.

References Botan::XTS_Mode::cipher(), and Botan::SymmetricAlgorithm::name().

74 {
75 return cipher().name() + "/XTS";
76 }
Botan::SymmetricAlgorithm::name
virtual std::string name() const =0
Botan::XTS_Mode::cipher
const BlockCipher & cipher() const
Definition: xts.h:44

size_t Botan::XTS_Encryption::output_length | ( | size_t | input_length | ) | const
| override virtual

Returns the size of the output if this transform is used to process a message with input_length bytes. Will throw if unable to give a precise answer.

Implements Botan::Cipher_Mode.

Definition at line 138 of file xts.cpp.

139 {
140 return input_length;
141 }

size_t Botan::XTS_Encryption::process | ( | uint8_t | msg[],
|  | size_t | msg_len
| ) |  |
| override virtual

Process message blocks

Input must be a multiple of update_granularity

Processes msg in place and returns bytes written. Normally this will be either msg_len (indicating the entire message was processed) or for certain AEAD modes zero (indicating that the mode requires the entire message be processed in one pass).

Parameters

  msg | the message to be processed
  msg_len | length of the message in bytes

Implements Botan::Cipher_Mode.

Definition at line 143 of file xts.cpp.

References Botan::BlockCipher::block_size(), BOTAN_ASSERT, Botan::XTS_Mode::cipher(), Botan::BlockCipher::encrypt_n(), Botan::CT::min(), Botan::XTS_Mode::tweak(), Botan::XTS_Mode::update_granularity(), Botan::XTS_Mode::update_tweak(), and Botan::xor_buf().

144 {
145 const size_t BS = cipher().block_size();
146
147 BOTAN_ASSERT(sz % BS == 0, "Input is full blocks");
148 size_t blocks = sz / BS;
149
150 const size_t blocks_in_tweak = update_granularity() / BS;
151
152 while(blocks)
153 {
154 const size_t to_proc = std::min(blocks, blocks_in_tweak);
155 const size_t to_proc_bytes = to_proc * BS;
156
157 xor_buf(buf, tweak(), to_proc_bytes);
158 cipher().encrypt_n(buf, buf, to_proc);
159 xor_buf(buf, tweak(), to_proc_bytes);
160
161 buf += to_proc * BS;
162 blocks -= to_proc;
163
164 update_tweak(to_proc);
165 }
166
167 return sz;
168 }
Botan::xor_buf
void xor_buf(T out[], const T in[], size_t length)
Definition: mem_ops.h:115
Botan::XTS_Mode::update_tweak
void update_tweak(size_t last_used)
Definition: xts.cpp:125
BOTAN_ASSERT
#define BOTAN_ASSERT(expr, assertion_made)
Definition: assert.h:27
Botan::XTS_Mode::cipher
const BlockCipher & cipher() const
Definition: xts.h:44
Botan::BlockCipher::encrypt_n
virtual void encrypt_n(const uint8_t in[], uint8_t out[], size_t blocks) const =0
Botan::CT::min
T min(T a, T b)
Definition: ct_utils.h:180
Botan::XTS_Mode::update_granularity
size_t update_granularity() const override
Definition: xts.cpp:78
Botan::BlockCipher::block_size
virtual size_t block_size() const =0
Botan::XTS_Mode::tweak
const uint8_t * tweak() const
Definition: xts.h:42

virtual std::string Botan::Cipher_Mode::provider | ( |  | ) | const
| inline virtual inherited

Returns
  provider information about this implementation. Default is "base", might also return "sse2", "avx2", "openssl", or some other arbitrary string.

Reimplemented in Botan::GCM_Mode.

Definition at line 202 of file cipher_mode.h.

202 { return "base"; }

void Botan::XTS_Mode::reset | ( |  | ) |
| override virtual inherited

Resets just the message specific state and allows encrypting again under the existing key

Implements Botan::Cipher_Mode.

Definition at line 68 of file xts.cpp.

References Botan::zeroise().

Referenced by Botan::XTS_Mode::clear().

69 {
70 zeroise(m_tweak);
71 }
Botan::zeroise
void zeroise(std::vector< T, Alloc > &vec)
Definition: secmem.h:211
template<typename Alloc >

void Botan::Cipher_Mode::set_key | ( | const std::vector< uint8_t, Alloc > & | key | ) |
| inline inherited

Set the symmetric key of this transform

Parameters

  key | contains the key material

Definition at line 172 of file cipher_mode.h.

Referenced by botan_cipher_set_key().

173 {
174 set_key(key.data(), key.size());
175 }
Botan::Cipher_Mode::set_key
void set_key(const std::vector< uint8_t, Alloc > &key)
Definition: cipher_mode.h:172

void Botan::Cipher_Mode::set_key | ( | const SymmetricKey & | key | ) |
| inline inherited

Set the symmetric key of this transform

Parameters

  key | contains the key material

Definition at line 181 of file cipher_mode.h.

References Botan::OctetString::begin(), and Botan::OctetString::length().

182 {
183 set_key(key.begin(), key.length());
184 }
Botan::Cipher_Mode::set_key
void set_key(const std::vector< uint8_t, Alloc > &key)
Definition: cipher_mode.h:172

void Botan::Cipher_Mode::set_key | ( | const uint8_t | key[],
|  | size_t | length
| ) |  |
| inline inherited

Set the symmetric key of this transform

Parameters

  key | contains the key material
  length | in bytes of key param

Definition at line 191 of file cipher_mode.h.

192 {
193 if(!valid_keylength(length))
194 throw Invalid_Key_Length(name(), length);
195 key_schedule(key, length);
196 }
Botan::Cipher_Mode::name
virtual std::string name() const =0
Botan::Cipher_Mode::valid_keylength
bool valid_keylength(size_t length) const
Definition: cipher_mode.h:162
template<typename Alloc >

void Botan::Cipher_Mode::start | ( | const std::vector< uint8_t, Alloc > & | nonce | ) |
| inline inherited

Begin processing a message.

Parameters

  nonce | the per message nonce

Definition at line 38 of file cipher_mode.h.

Referenced by botan_cipher_start(), and Botan::TLS::write_record().

39 {
40 start_msg(nonce.data(), nonce.size());
41 }
Botan::Cipher_Mode::start_msg
virtual void start_msg(const uint8_t nonce[], size_t nonce_len)=0

void Botan::Cipher_Mode::start | ( | const uint8_t | nonce[],
|  | size_t | nonce_len
| ) |  |
| inline inherited

Begin processing a message.

Parameters

  nonce | the per message nonce
  nonce_len | length of nonce

Definition at line 48 of file cipher_mode.h.

49 {
50 start_msg(nonce, nonce_len);
51 }
Botan::Cipher_Mode::start_msg
virtual void start_msg(const uint8_t nonce[], size_t nonce_len)=0

void Botan::Cipher_Mode::start | ( |  | ) |
| inline inherited

Begin processing a message.

Definition at line 56 of file cipher_mode.h.

57 {
58 return start_msg(nullptr, 0);
59 }
Botan::Cipher_Mode::start_msg
virtual void start_msg(const uint8_t nonce[], size_t nonce_len)=0

virtual size_t Botan::Cipher_Mode::tag_size | ( |  | ) | const
| inline virtual inherited

Returns
  the size of the authentication tag used (in bytes)

Reimplemented in Botan::SIV_Mode, Botan::CCM_Mode, Botan::OCB_Mode, Botan::TLS::TLS_CBC_HMAC_AEAD_Mode, Botan::ChaCha20Poly1305_Mode, Botan::GCM_Mode, and Botan::EAX_Mode.

Definition at line 150 of file cipher_mode.h.

Referenced by botan_cipher_get_tag_length().

150 { return 0; }

const uint8_t* Botan::XTS_Mode::tweak | ( |  | ) | const
| inline protected inherited

Definition at line 42 of file xts.h.

Referenced by finish(), Botan::XTS_Decryption::finish(), process(), and Botan::XTS_Decryption::process().

42 { return m_tweak.data(); }

void Botan::Cipher_Mode::update | ( | secure_vector< uint8_t > & | buffer,
|  | size_t | offset = `0`
| ) |  |
| inline inherited

Process some data. Input must be in size update_granularity() uint8_t blocks.

Parameters

  buffer | in/out parameter which will possibly be resized
  offset | an offset into blocks to begin processing

Definition at line 81 of file cipher_mode.h.

References BOTAN_ASSERT.

Referenced by botan_cipher_update(), finish(), Botan::ChaCha20Poly1305_Encryption::finish(), Botan::CBC_Encryption::finish(), Botan::CFB_Encryption::finish(), Botan::EAX_Encryption::finish(), Botan::XTS_Decryption::finish(), Botan::CFB_Decryption::finish(), Botan::CTS_Encryption::finish(), Botan::CBC_Decryption::finish(), Botan::TLS::TLS_CBC_HMAC_AEAD_Encryption::finish(), Botan::CTS_Decryption::finish(), and Botan::TLS::TLS_CBC_HMAC_AEAD_Decryption::finish().

82 {
83 BOTAN_ASSERT(buffer.size() >= offset, "Offset ok");
84 uint8_t* buf = buffer.data() + offset;
85 const size_t buf_size = buffer.size() - offset;
86
87 const size_t written = process(buf, buf_size);
88 buffer.resize(offset + written);
89 }
BOTAN_ASSERT
#define BOTAN_ASSERT(expr, assertion_made)
Definition: assert.h:27
Botan::Cipher_Mode::process
virtual size_t process(uint8_t msg[], size_t msg_len)=0

size_t Botan::XTS_Mode::update_granularity | ( |  | ) | const
| override virtual inherited

Returns
  size of required blocks to update

Implements Botan::Cipher_Mode.

Definition at line 78 of file xts.cpp.

References Botan::XTS_Mode::cipher(), and Botan::BlockCipher::parallel_bytes().

Referenced by process(), Botan::XTS_Decryption::process(), Botan::XTS_Mode::update_tweak(), and Botan::XTS_Mode::XTS_Mode().

79 {
80 return cipher().parallel_bytes();
81 }
Botan::BlockCipher::parallel_bytes
size_t parallel_bytes() const
Definition: block_cipher.h:62
Botan::XTS_Mode::cipher
const BlockCipher & cipher() const
Definition: xts.h:44

void Botan::XTS_Mode::update_tweak | ( | size_t | last_used | ) |
| protected inherited

Definition at line 125 of file xts.cpp.

References Botan::XTS_Mode::update_granularity().

Referenced by process(), and Botan::XTS_Decryption::process().

126 {
127 const size_t BS = m_tweak_cipher->block_size();
128
129 if(which > 0)
130 poly_double(m_tweak.data(), &m_tweak[(which-1)*BS], BS);
131
132 const size_t blocks_in_tweak = update_granularity() / BS;
133
134 for(size_t i = 1; i < blocks_in_tweak; ++i)
135 poly_double(&m_tweak[i*BS], &m_tweak[(i-1)*BS], BS);
136 }
Botan::XTS_Mode::update_granularity
size_t update_granularity() const override
Definition: xts.cpp:78

bool Botan::Cipher_Mode::valid_keylength | ( | size_t | length | ) | const
| inline inherited

Check whether a given key length is valid for this algorithm.

Parameters

  length | the key length to be checked.

Returns
  true if the key length is valid.

Definition at line 162 of file cipher_mode.h.

163 {
164 return key_spec().valid_keylength(length);
165 }
Botan::Key_Length_Specification::valid_keylength
bool valid_keylength(size_t length) const
Definition: key_spec.h:51
Botan::Cipher_Mode::key_spec
virtual Key_Length_Specification key_spec() const =0

bool Botan::XTS_Mode::valid_nonce_length | ( | size_t | nonce_len | ) | const
| override virtual inherited

Returns
  true iff nonce_len is a valid length for the nonce

Implements Botan::Cipher_Mode.

Definition at line 98 of file xts.cpp.

References Botan::BlockCipher::block_size(), and Botan::XTS_Mode::cipher().

99 {
100 return cipher().block_size() == n;
101 }
Botan::XTS_Mode::cipher
const BlockCipher & cipher() const
Definition: xts.h:44
Botan::BlockCipher::block_size
virtual size_t block_size() const =0

The documentation for this class was generated from the following files:

- src/lib/modes/xts/xts.h
- src/lib/modes/xts/xts.cpp