Botan  2.4.0
Crypto and TLS for C++11
tls_cbc.cpp
Go to the documentation of this file.
1 /*
2 * TLS CBC Record Handling
3 * (C) 2012,2013,2014,2015,2016 Jack Lloyd
4 * (C) 2016 Juraj Somorovsky
5 * (C) 2016 Matthias Gierlings
6 * (C) 2016 Daniel Neus, Rohde & Schwarz Cybersecurity
7 *
8 * Botan is released under the Simplified BSD License (see license.txt)
9 */
10 
11 #include <botan/internal/tls_cbc.h>
12 #include <botan/cbc.h>
13 
14 #include <botan/internal/rounding.h>
15 #include <botan/internal/ct_utils.h>
16 #include <botan/tls_alert.h>
17 #include <botan/tls_exceptn.h>
18 
19 namespace Botan {
20 
21 namespace TLS {
22 
23 /*
24 * TLS_CBC_HMAC_AEAD_Mode Constructor
25 */
27  const std::string& cipher_name,
28  size_t cipher_keylen,
29  const std::string& mac_name,
30  size_t mac_keylen,
31  bool use_explicit_iv,
32  bool use_encrypt_then_mac) :
33  m_cipher_name(cipher_name),
34  m_mac_name(mac_name),
35  m_cipher_keylen(cipher_keylen),
36  m_mac_keylen(mac_keylen),
37  m_use_encrypt_then_mac(use_encrypt_then_mac)
38  {
39  m_mac = MessageAuthenticationCode::create_or_throw("HMAC(" + m_mac_name + ")");
40  std::unique_ptr<BlockCipher> cipher = BlockCipher::create_or_throw(m_cipher_name);
41 
42  m_tag_size = m_mac->output_length();
43  m_block_size = cipher->block_size();
44 
45  m_iv_size = use_explicit_iv ? m_block_size : 0;
46 
47  if(dir == ENCRYPTION)
48  m_cbc.reset(new CBC_Encryption(cipher.release(), new Null_Padding));
49  else
50  m_cbc.reset(new CBC_Decryption(cipher.release(), new Null_Padding));
51  }
52 
54  {
55  cbc().clear();
56  mac().clear();
57  reset();
58  }
59 
61  {
62  cbc_state().clear();
63  m_ad.clear();
64  m_msg.clear();
65  }
66 
67 std::string TLS_CBC_HMAC_AEAD_Mode::name() const
68  {
69  return "TLS_CBC(" + m_cipher_name + "," + m_mac_name + ")";
70  }
71 
73  {
74  return 1; // just buffers anyway
75  }
76 
78  {
79  if(m_cbc_state.empty())
80  return nl == block_size();
81  return nl == iv_size();
82  }
83 
85  {
86  return Key_Length_Specification(m_cipher_keylen + m_mac_keylen);
87  }
88 
89 void TLS_CBC_HMAC_AEAD_Mode::key_schedule(const uint8_t key[], size_t keylen)
90  {
91  // Both keys are of fixed length specified by the ciphersuite
92 
93  if(keylen != m_cipher_keylen + m_mac_keylen)
94  throw Invalid_Key_Length(name(), keylen);
95 
96  cbc().set_key(&key[0], m_cipher_keylen);
97  mac().set_key(&key[m_cipher_keylen], m_mac_keylen);
98  }
99 
100 void TLS_CBC_HMAC_AEAD_Mode::start_msg(const uint8_t nonce[], size_t nonce_len)
101  {
102  if(!valid_nonce_length(nonce_len))
103  {
104  throw Invalid_IV_Length(name(), nonce_len);
105  }
106 
107  m_msg.clear();
108 
109  if(nonce_len > 0)
110  {
111  m_cbc_state.assign(nonce, nonce + nonce_len);
112  }
113  }
114 
115 size_t TLS_CBC_HMAC_AEAD_Mode::process(uint8_t buf[], size_t sz)
116  {
117  m_msg.insert(m_msg.end(), buf, buf + sz);
118  return 0;
119  }
120 
121 std::vector<uint8_t> TLS_CBC_HMAC_AEAD_Mode::assoc_data_with_len(uint16_t len)
122  {
123  std::vector<uint8_t> ad = m_ad;
124  BOTAN_ASSERT(ad.size() == 13, "Expected AAD size");
125  ad[11] = get_byte(0, len);
126  ad[12] = get_byte(1, len);
127  return ad;
128  }
129 
130 void TLS_CBC_HMAC_AEAD_Mode::set_associated_data(const uint8_t ad[], size_t ad_len)
131  {
132  if(ad_len != 13)
133  throw Exception("Invalid TLS AEAD associated data length");
134  m_ad.assign(ad, ad + ad_len);
135  }
136 
137 void TLS_CBC_HMAC_AEAD_Encryption::set_associated_data(const uint8_t ad[], size_t ad_len)
138  {
140 
142  {
143  // AAD hack for EtM
144  const uint16_t pt_size = make_uint16(assoc_data()[11], assoc_data()[12]);
145  const uint16_t enc_size = round_up(iv_size() + pt_size + 1, block_size());
146  assoc_data()[11] = get_byte<uint16_t>(0, enc_size);
147  assoc_data()[12] = get_byte<uint16_t>(1, enc_size);
148  }
149  }
150 
151 void TLS_CBC_HMAC_AEAD_Encryption::cbc_encrypt_record(uint8_t buf[], size_t buf_size)
152  {
153  cbc().start(cbc_state());
154  cbc().process(buf, buf_size);
155 
156  cbc_state().assign(buf + buf_size - block_size(), buf + buf_size);
157  }
158 
159 size_t TLS_CBC_HMAC_AEAD_Encryption::output_length(size_t input_length) const
160  {
161  return round_up(input_length + 1 + (use_encrypt_then_mac() ? 0 : tag_size()), block_size()) +
162  (use_encrypt_then_mac() ? tag_size() : 0);
163  }
164 
166  {
167  update(buffer, offset);
168  buffer.resize(offset); // truncate, leaving just header
169  const size_t header_size = offset;
170 
171  buffer.insert(buffer.end(), msg().begin(), msg().end());
172 
173  const size_t input_size = msg().size() + 1 + (use_encrypt_then_mac() ? 0 : tag_size());
174  const size_t enc_size = round_up(input_size, block_size());
175  const size_t pad_val = enc_size - input_size;
176  const size_t buf_size = enc_size + (use_encrypt_then_mac() ? tag_size() : 0);
177 
178  BOTAN_ASSERT(enc_size % block_size() == 0,
179  "Buffer is an even multiple of block size");
180 
181  mac().update(assoc_data());
182 
184  {
185  if(iv_size() > 0)
186  {
187  mac().update(cbc_state());
188  }
189 
190  for(size_t i = 0; i != pad_val + 1; ++i)
191  buffer.push_back(static_cast<uint8_t>(pad_val));
192  cbc_encrypt_record(&buffer[header_size], enc_size);
193  }
194 
195  // EtM also uses ciphertext size instead of plaintext size for AEAD input
196  const uint8_t* mac_input = (use_encrypt_then_mac() ? &buffer[header_size] : msg().data());
197  const size_t mac_input_len = (use_encrypt_then_mac() ? enc_size : msg().size());
198 
199  mac().update(mac_input, mac_input_len);
200 
201  buffer.resize(buffer.size() + tag_size());
202  mac().final(&buffer[buffer.size() - tag_size()]);
203 
204  if(use_encrypt_then_mac() == false)
205  {
206  for(size_t i = 0; i != pad_val + 1; ++i)
207  buffer.push_back(static_cast<uint8_t>(pad_val));
208  cbc_encrypt_record(&buffer[header_size], buf_size);
209  }
210  }
211 
212 /*
213 * Checks the TLS padding. Returns 0 if the padding is invalid (we
214 * count the padding_length field as part of the padding size so a
215 * valid padding will always be at least one byte long), or the length
216 * of the padding otherwise. This is actually padding_length + 1
217 * because both the padding and padding_length fields are padding from
218 * our perspective.
219 *
220 * Returning 0 in the error case should ensure the MAC check will fail.
221 * This approach is suggested in section 6.2.3.2 of RFC 5246.
222 */
223 uint16_t check_tls_cbc_padding(const uint8_t record[], size_t record_len)
224  {
225  if(record_len == 0 || record_len > 0xFFFF)
226  return 0;
227 
228  const uint16_t rec16 = static_cast<uint16_t>(record_len);
229 
230  /*
231  * TLS v1.0 and up require all the padding bytes be the same value
232  * and allows up to 255 bytes.
233  */
234 
235  const uint16_t to_check = std::min<uint16_t>(256, record_len);
236  const uint8_t pad_byte = record[record_len-1];
237  const uint16_t pad_bytes = 1 + pad_byte;
238 
239  uint16_t pad_invalid = CT::is_less<uint16_t>(rec16, pad_bytes);
240 
241  for(uint16_t i = rec16 - to_check; i != rec16; ++i)
242  {
243  const uint16_t offset = rec16 - i;
244  const uint16_t in_pad_range = CT::is_lte<uint16_t>(offset, pad_bytes);
245  pad_invalid |= (in_pad_range & (record[i] ^ pad_byte));
246  }
247 
248  const uint16_t pad_invalid_mask = CT::expand_mask<uint16_t>(pad_invalid);
249  return CT::select<uint16_t>(pad_invalid_mask, 0, pad_byte + 1);
250  }
251 
252 void TLS_CBC_HMAC_AEAD_Decryption::cbc_decrypt_record(uint8_t record_contents[], size_t record_len)
253  {
254  if(record_len == 0 || record_len % block_size() != 0)
255  throw Decoding_Error("Received TLS CBC ciphertext with invalid length");
256 
257  cbc().start(cbc_state());
258  cbc_state().assign(record_contents + record_len - block_size(),
259  record_contents + record_len);
260 
261  cbc().process(record_contents, record_len);
262  }
263 
265  {
266  /*
267  * We don't know this because the padding is arbitrary
268  */
269  return 0;
270  }
271 
272 /*
273 * This function performs additional compression calls in order
274 * to protect from the Lucky 13 attack. It adds new compression
275 * function calls over dummy data, by computing additional HMAC updates.
276 *
277 * The countermeasure was described (in a similar way) in the Lucky 13 paper.
278 *
279 * Background:
280 * - One SHA-1/SHA-256 compression is performed with 64 bytes of data.
281 * - HMAC adds 8 byte length field and padding (at least 1 byte) so that we have:
282 * - 0 - 55 bytes: 1 compression
283 * - 56 - 55+64 bytes: 2 compressions
284 * - 56+64 - 55+2*64 bytes: 3 compressions ...
285 * - For SHA-384, this works similarly, but we have 128 byte blocks and 16 byte
286 * long length field. This results in:
287 * - 0 - 111 bytes: 1 compression
288 * - 112 - 111+128 bytes: 2 compressions ...
289 *
290 * The implemented countermeasure works as follows:
291 * 1) It computes max_compressions: number of maximum compressions performed on
292 * the decrypted data
293 * 2) It computes current_compressions: number of compressions performed on the
294 * decrypted data, after padding has been removed
295 * 3) If current_compressions != max_compressions: It invokes an HMAC update
296 * over dummy data so that (max_compressions - current_compressions)
297 * compressions are performed. Otherwise, it invokes an HMAC update so that
298 * no compressions are performed.
299 *
300 * Note that the padding validation in Botan is always performed over
301 * min(plen,256) bytes, see the function check_tls_cbc_padding. This differs
302 * from the countermeasure described in the paper.
303 *
304 * Note that the padding length padlen does also count the last byte
305 * of the decrypted plaintext. This is different from the Lucky 13 paper.
306 *
307 * This countermeasure leaves a difference of about 100 clock cycles (in
308 * comparison to >1000 clock cycles observed without it).
309 *
310 * plen represents the length of the decrypted plaintext message P
311 * padlen represents the padding length
312 *
313 */
314 void TLS_CBC_HMAC_AEAD_Decryption::perform_additional_compressions(size_t plen, size_t padlen)
315  {
316  uint16_t block_size;
317  uint16_t max_bytes_in_first_block;
318  if(mac().name() == "HMAC(SHA-384)")
319  {
320  block_size = 128;
321  max_bytes_in_first_block = 111;
322  }
323  else
324  {
325  block_size = 64;
326  max_bytes_in_first_block = 55;
327  }
328  // number of maximum MACed bytes
329  const uint16_t L1 = static_cast<uint16_t>(13 + plen - tag_size());
330  // number of current MACed bytes (L1 - padlen)
331  // Here the Lucky 13 paper is different because the padlen length in the paper
332  // does not count the last message byte.
333  const uint16_t L2 = static_cast<uint16_t>(13 + plen - padlen - tag_size());
334  // From the paper, for SHA-256/SHA-1 compute: ceil((L1-55)/64) and ceil((L2-55)/64)
335  // ceil((L1-55)/64) = floor((L1+64-1-55)/64)
336  // Here we compute number of compressions for SHA-* in general
337  const uint16_t max_compresssions = ( (L1 + block_size - 1 - max_bytes_in_first_block) / block_size);
338  const uint16_t current_compressions = ((L2 + block_size - 1 - max_bytes_in_first_block) / block_size);
339  // number of additional compressions we have to perform
340  const uint16_t add_compressions = max_compresssions - current_compressions;
341  const uint8_t equal = CT::is_equal(max_compresssions, current_compressions) & 0x01;
342  // We compute the data length we need to achieve the number of compressions.
343  // If there are no compressions, we just add 55/111 dummy bytes so that no
344  // compression is performed.
345  const uint16_t data_len = block_size * add_compressions + equal * max_bytes_in_first_block;
346  secure_vector<uint8_t> data(data_len);
347  mac().update(unlock(data));
348  // we do not need to clear the MAC since the connection is broken anyway
349  }
350 
352  {
353  update(buffer, offset);
354  buffer.resize(offset);
355 
356  const size_t record_len = msg().size();
357  uint8_t* record_contents = msg().data();
358 
359  // This early exit does not leak info because all the values compared are public
360  if(record_len < tag_size() ||
361  (record_len - (use_encrypt_then_mac() ? tag_size() : 0)) % block_size() != 0)
362  {
363  throw TLS_Exception(Alert::BAD_RECORD_MAC, "Message authentication failure");
364  }
365 
367  {
368  const size_t enc_size = record_len - tag_size();
369 
370  mac().update(assoc_data_with_len(iv_size() + enc_size));
371  if(iv_size() > 0)
372  {
373  mac().update(cbc_state());
374  }
375  mac().update(record_contents, enc_size);
376 
377  std::vector<uint8_t> mac_buf(tag_size());
378  mac().final(mac_buf.data());
379 
380  const size_t mac_offset = enc_size;
381 
382  const bool mac_ok = constant_time_compare(&record_contents[mac_offset], mac_buf.data(), tag_size());
383 
384  if(!mac_ok)
385  {
386  throw TLS_Exception(Alert::BAD_RECORD_MAC, "Message authentication failure");
387  }
388 
389  cbc_decrypt_record(record_contents, enc_size);
390 
391  // 0 if padding was invalid, otherwise 1 + padding_bytes
392  uint16_t pad_size = check_tls_cbc_padding(record_contents, enc_size);
393 
394  // No oracle here, whoever sent us this had the key since MAC check passed
395  if(pad_size == 0)
396  {
397  throw TLS_Exception(Alert::BAD_RECORD_MAC, "Message authentication failure");
398  }
399 
400  const uint8_t* plaintext_block = &record_contents[0];
401  const size_t plaintext_length = enc_size - pad_size;
402 
403  buffer.insert(buffer.end(), plaintext_block, plaintext_block + plaintext_length);
404  }
405  else
406  {
407  cbc_decrypt_record(record_contents, record_len);
408 
409  CT::poison(record_contents, record_len);
410 
411  // 0 if padding was invalid, otherwise 1 + padding_bytes
412  uint16_t pad_size = check_tls_cbc_padding(record_contents, record_len);
413 
414  /*
415  This mask is zero if there is not enough room in the packet to get a valid MAC.
416 
417  We have to accept empty packets, since otherwise we are not compatible
418  with how OpenSSL's countermeasure for fixing BEAST in TLS 1.0 CBC works
419  (sending empty records, instead of 1/(n-1) splitting)
420  */
421 
422  const uint16_t size_ok_mask = CT::is_lte<uint16_t>(static_cast<uint16_t>(tag_size() + pad_size), static_cast<uint16_t>(record_len + 1));
423  pad_size &= size_ok_mask;
424 
425  CT::unpoison(record_contents, record_len);
426 
427  /*
428  This is unpoisoned sooner than it should. The pad_size leaks to plaintext_length and
429  then to the timing channel in the MAC computation described in the Lucky 13 paper.
430  */
431  CT::unpoison(pad_size);
432 
433  const uint8_t* plaintext_block = &record_contents[0];
434  const uint16_t plaintext_length = static_cast<uint16_t>(record_len - tag_size() - pad_size);
435 
436  mac().update(assoc_data_with_len(plaintext_length));
437  mac().update(plaintext_block, plaintext_length);
438 
439  std::vector<uint8_t> mac_buf(tag_size());
440  mac().final(mac_buf.data());
441 
442  const size_t mac_offset = record_len - (tag_size() + pad_size);
443 
444  const bool mac_ok = constant_time_compare(&record_contents[mac_offset], mac_buf.data(), tag_size());
445 
446  const uint16_t ok_mask = size_ok_mask & CT::expand_mask<uint16_t>(mac_ok) & CT::expand_mask<uint16_t>(pad_size);
447 
448  CT::unpoison(ok_mask);
449 
450  if(ok_mask)
451  {
452  buffer.insert(buffer.end(), plaintext_block, plaintext_block + plaintext_length);
453  }
454  else
455  {
456  perform_additional_compressions(record_len, pad_size);
457  throw TLS_Exception(Alert::BAD_RECORD_MAC, "Message authentication failure");
458  }
459  }
460  }
461 
462 }
463 
464 }
size_t process(uint8_t buf[], size_t sz) override final
Definition: tls_cbc.cpp:115
std::string m_cipher_name
virtual void clear()=0
void finish(secure_vector< uint8_t > &final_block, size_t offset=0) override
Definition: tls_cbc.cpp:165
void update(secure_vector< uint8_t > &buffer, size_t offset=0)
Definition: cipher_mode.h:87
Cipher_Mode & cbc() const
Definition: tls_cbc.h:63
bool constant_time_compare(const uint8_t x[], const uint8_t y[], size_t len)
Definition: mem_ops.cpp:44
void poison(const T *p, size_t n)
Definition: ct_utils.h:46
void finish(secure_vector< uint8_t > &final_block, size_t offset=0) override
Definition: tls_cbc.cpp:351
MessageAuthenticationCode & mac() const
Definition: tls_cbc.h:65
T is_equal(T x, T y)
Definition: ct_utils.h:124
void start(const std::vector< uint8_t, Alloc > &nonce)
Definition: cipher_mode.h:44
Key_Length_Specification key_spec() const override final
Definition: tls_cbc.cpp:84
void set_associated_data(const uint8_t ad[], size_t ad_len) override
Definition: tls_cbc.cpp:130
#define BOTAN_ASSERT(expr, assertion_made)
Definition: assert.h:29
secure_vector< uint8_t > & cbc_state()
Definition: tls_cbc.h:71
void final(uint8_t out[])
Definition: buf_comp.h:89
void set_key(const SymmetricKey &key)
Definition: sym_algo.h:66
bool valid_nonce_length(size_t nl) const override final
Definition: tls_cbc.cpp:77
void clear() override final
Definition: tls_cbc.cpp:53
std::string name() const override final
Definition: tls_cbc.cpp:67
virtual void clear()=0
size_t tag_size() const override final
Definition: tls_cbc.h:39
std::vector< uint8_t > & assoc_data()
Definition: tls_cbc.h:72
Definition: alg_id.cpp:13
static std::unique_ptr< BlockCipher > create_or_throw(const std::string &algo_spec, const std::string &provider="")
size_t update_granularity() const override final
Definition: tls_cbc.cpp:72
std::vector< T > unlock(const secure_vector< T > &in)
Definition: secmem.h:95
virtual size_t process(uint8_t msg[], size_t msg_len)=0
void set_key(const std::vector< uint8_t, Alloc > &key)
Definition: cipher_mode.h:178
std::vector< uint8_t > assoc_data_with_len(uint16_t len)
Definition: tls_cbc.cpp:121
void update(const uint8_t in[], size_t length)
Definition: buf_comp.h:34
uint16_t make_uint16(uint8_t i0, uint8_t i1)
Definition: loadstor.h:52
uint16_t check_tls_cbc_padding(const uint8_t record[], size_t record_len)
Definition: tls_cbc.cpp:223
void reset() override final
Definition: tls_cbc.cpp:60
static std::unique_ptr< MessageAuthenticationCode > create_or_throw(const std::string &algo_spec, const std::string &provider="")
Definition: mac.cpp:140
size_t output_length(size_t input_length) const override
Definition: tls_cbc.cpp:159
uint8_t get_byte(size_t byte_num, T input)
Definition: loadstor.h:39
void unpoison(const T *p, size_t n)
Definition: ct_utils.h:57
secure_vector< uint8_t > & msg()
Definition: tls_cbc.h:73
std::vector< T, secure_allocator< T > > secure_vector
Definition: secmem.h:88
size_t round_up(size_t n, size_t align_to)
Definition: rounding.h:21
size_t output_length(size_t input_length) const override
Definition: tls_cbc.cpp:264
void set_associated_data(const uint8_t ad[], size_t ad_len) override
Definition: tls_cbc.cpp:137
TLS_CBC_HMAC_AEAD_Mode(Cipher_Dir direction, const std::string &cipher_name, size_t cipher_keylen, const std::string &mac_name, size_t mac_keylen, bool use_explicit_iv, bool use_encrypt_then_mac)
Definition: tls_cbc.cpp:26