Botan  1.11.15
src/lib/tls/tls_record.cpp
Go to the documentation of this file.
00001 /*
00002 * TLS Record Handling
00003 * (C) 2012,2013,2014 Jack Lloyd
00004 *
00005 * Botan is released under the Simplified BSD License (see license.txt)
00006 */
00007 
00008 #include <botan/internal/tls_record.h>
00009 #include <botan/tls_ciphersuite.h>
00010 #include <botan/tls_exceptn.h>
00011 #include <botan/loadstor.h>
00012 #include <botan/internal/tls_seq_numbers.h>
00013 #include <botan/internal/tls_session_key.h>
00014 #include <botan/internal/rounding.h>
00015 #include <botan/internal/xor_buf.h>
00016 #include <botan/lookup.h>
00017 #include <botan/rng.h>
00018 
00019 namespace Botan {
00020 
00021 namespace TLS {
00022 
00023 Connection_Cipher_State::Connection_Cipher_State(Protocol_Version version,
00024                                                  Connection_Side side,
00025                                                  bool our_side,
00026                                                  const Ciphersuite& suite,
00027                                                  const Session_Keys& keys) :
00028    m_start_time(std::chrono::system_clock::now()),
00029    m_nonce_bytes_from_handshake(suite.nonce_bytes_from_handshake()),
00030    m_nonce_bytes_from_record(suite.nonce_bytes_from_record())
00031    {
00032    SymmetricKey mac_key, cipher_key;
00033    InitializationVector iv;
00034 
00035    if(side == CLIENT)
00036       {
00037       cipher_key = keys.client_cipher_key();
00038       iv = keys.client_iv();
00039       mac_key = keys.client_mac_key();
00040       }
00041    else
00042       {
00043       cipher_key = keys.server_cipher_key();
00044       iv = keys.server_iv();
00045       mac_key = keys.server_mac_key();
00046       }
00047 
00048    const std::string cipher_algo = suite.cipher_algo();
00049    const std::string mac_algo = suite.mac_algo();
00050 
00051    if(AEAD_Mode* aead = get_aead(cipher_algo, our_side ? ENCRYPTION : DECRYPTION))
00052       {
00053       m_aead.reset(aead);
00054       m_aead->set_key(cipher_key + mac_key);
00055 
00056       BOTAN_ASSERT_EQUAL(iv.length(), nonce_bytes_from_handshake(), "Matching nonce sizes");
00057       m_nonce = iv.bits_of();
00058 
00059       BOTAN_ASSERT(nonce_bytes_from_record() == 0 || nonce_bytes_from_record() == 8,
00060                    "Ciphersuite uses implemented IV length");
00061 
00062       m_nonce.resize(m_nonce.size() + 8);
00063       return;
00064       }
00065 
00066    if(BlockCipher* bc = get_block_cipher(cipher_algo))
00067       {
00068       m_block_cipher.reset(bc->clone());
00069       m_block_cipher->set_key(cipher_key);
00070       m_block_cipher_cbc_state = iv.bits_of();
00071       m_block_size = bc->block_size();
00072 
00073       if(version.supports_explicit_cbc_ivs())
00074          m_iv_size = m_block_size;
00075       }
00076    else if(StreamCipher* sc = get_stream_cipher(cipher_algo))
00077       {
00078       m_stream_cipher.reset(sc->clone());
00079       m_stream_cipher->set_key(cipher_key);
00080       }
00081    else
00082       throw Invalid_Argument("Unknown TLS cipher " + cipher_algo);
00083 
00084    m_mac.reset(get_mac("HMAC(" + mac_algo + ")"));
00085 
00086    m_mac->set_key(mac_key);
00087    }
00088 
00089 const secure_vector<byte>& Connection_Cipher_State::aead_nonce(u64bit seq)
00090    {
00091    store_be(seq, &m_nonce[nonce_bytes_from_handshake()]);
00092    return m_nonce;
00093    }
00094 
00095 const secure_vector<byte>&
00096 Connection_Cipher_State::aead_nonce(const byte record[], size_t record_len, u64bit seq)
00097    {
00098    if(nonce_bytes_from_record())
00099       {
00100       if(record_len < nonce_bytes_from_record())
00101          throw Decoding_Error("Invalid AEAD packet too short to be valid");
00102       copy_mem(&m_nonce[nonce_bytes_from_handshake()], record, nonce_bytes_from_record());
00103       }
00104    else
00105       {
00106       /*
00107       nonce_len == 0 is assumed to mean no nonce in the message but
00108       instead the AEAD uses the seq number in network order.
00109       */
00110       store_be(seq, &m_nonce[nonce_bytes_from_handshake()]);
00111       }
00112    return m_nonce;
00113    }
00114 
00115 const secure_vector<byte>&
00116 Connection_Cipher_State::format_ad(u64bit msg_sequence,
00117                                    byte msg_type,
00118                                    Protocol_Version version,
00119                                    u16bit msg_length)
00120    {
00121    m_ad.clear();
00122    for(size_t i = 0; i != 8; ++i)
00123       m_ad.push_back(get_byte(i, msg_sequence));
00124    m_ad.push_back(msg_type);
00125 
00126    m_ad.push_back(version.major_version());
00127    m_ad.push_back(version.minor_version());
00128 
00129    m_ad.push_back(get_byte(0, msg_length));
00130    m_ad.push_back(get_byte(1, msg_length));
00131 
00132    return m_ad;
00133    }
00134 
00135 void write_record(secure_vector<byte>& output,
00136                   byte msg_type, const byte msg[], size_t msg_length,
00137                   Protocol_Version version,
00138                   u64bit seq,
00139                   Connection_Cipher_State* cs,
00140                   RandomNumberGenerator& rng)
00141    {
00142    output.clear();
00143 
00144    output.push_back(msg_type);
00145    output.push_back(version.major_version());
00146    output.push_back(version.minor_version());
00147 
00148    if(version.is_datagram_protocol())
00149       {
00150       for(size_t i = 0; i != 8; ++i)
00151          output.push_back(get_byte(i, seq));
00152       }
00153 
00154    if(!cs) // initial unencrypted handshake records
00155       {
00156       output.push_back(get_byte<u16bit>(0, msg_length));
00157       output.push_back(get_byte<u16bit>(1, msg_length));
00158 
00159       output.insert(output.end(), &msg[0], &msg[msg_length]);
00160 
00161       return;
00162       }
00163 
00164    if(AEAD_Mode* aead = cs->aead())
00165       {
00166       const size_t ctext_size = aead->output_length(msg_length);
00167 
00168       const secure_vector<byte>& nonce = cs->aead_nonce(seq);
00169 
00170       // wrong if start returns something
00171       const size_t rec_size = ctext_size + cs->nonce_bytes_from_record();
00172 
00173       BOTAN_ASSERT(rec_size <= 0xFFFF, "Ciphertext length fits in field");
00174       output.push_back(get_byte<u16bit>(0, rec_size));
00175       output.push_back(get_byte<u16bit>(1, rec_size));
00176 
00177       aead->set_ad(cs->format_ad(seq, msg_type, version, msg_length));
00178 
00179       output += std::make_pair(&nonce[cs->nonce_bytes_from_handshake()], cs->nonce_bytes_from_record());
00180       BOTAN_ASSERT(aead->start(nonce).empty(), "AEAD doesn't return anything from start");
00181 
00182       const size_t offset = output.size();
00183       output += std::make_pair(&msg[0], msg_length);
00184       aead->finish(output, offset);
00185 
00186       BOTAN_ASSERT(output.size() == offset + ctext_size, "Expected size");
00187 
00188       BOTAN_ASSERT(output.size() < MAX_CIPHERTEXT_SIZE,
00189                    "Produced ciphertext larger than protocol allows");
00190       return;
00191       }
00192 
00193    cs->mac()->update(cs->format_ad(seq, msg_type, version, msg_length));
00194 
00195    cs->mac()->update(msg, msg_length);
00196 
00197    const size_t block_size = cs->block_size();
00198    const size_t iv_size = cs->iv_size();
00199    const size_t mac_size = cs->mac_size();
00200 
00201    const size_t buf_size = round_up(
00202       iv_size + msg_length + mac_size + (block_size ? 1 : 0),
00203       block_size);
00204 
00205    if(buf_size > MAX_CIPHERTEXT_SIZE)
00206       throw Internal_Error("Output record is larger than allowed by protocol");
00207 
00208    output.push_back(get_byte<u16bit>(0, buf_size));
00209    output.push_back(get_byte<u16bit>(1, buf_size));
00210 
00211    const size_t header_size = output.size();
00212 
00213    if(iv_size)
00214       {
00215       output.resize(output.size() + iv_size);
00216       rng.randomize(&output[output.size() - iv_size], iv_size);
00217       }
00218 
00219    output.insert(output.end(), &msg[0], &msg[msg_length]);
00220 
00221    output.resize(output.size() + mac_size);
00222    cs->mac()->final(&output[output.size() - mac_size]);
00223 
00224    if(block_size)
00225       {
00226       const size_t pad_val =
00227          buf_size - (iv_size + msg_length + mac_size + 1);
00228 
00229       for(size_t i = 0; i != pad_val + 1; ++i)
00230          output.push_back(pad_val);
00231       }
00232 
00233    if(buf_size > MAX_CIPHERTEXT_SIZE)
00234       throw Internal_Error("Produced ciphertext larger than protocol allows");
00235 
00236    BOTAN_ASSERT_EQUAL(buf_size + header_size, output.size(),
00237                       "Output buffer is sized properly");
00238 
00239    if(StreamCipher* sc = cs->stream_cipher())
00240       {
00241       sc->cipher1(&output[header_size], buf_size);
00242       }
00243    else if(BlockCipher* bc = cs->block_cipher())
00244       {
00245       secure_vector<byte>& cbc_state = cs->cbc_state();
00246 
00247       BOTAN_ASSERT(buf_size % block_size == 0,
00248                    "Buffer is an even multiple of block size");
00249 
00250       byte* buf = &output[header_size];
00251 
00252       const size_t blocks = buf_size / block_size;
00253 
00254       xor_buf(&buf[0], &cbc_state[0], block_size);
00255       bc->encrypt(&buf[0]);
00256 
00257       for(size_t i = 1; i < blocks; ++i)
00258          {
00259          xor_buf(&buf[block_size*i], &buf[block_size*(i-1)], block_size);
00260          bc->encrypt(&buf[block_size*i]);
00261          }
00262 
00263       cbc_state.assign(&buf[block_size*(blocks-1)],
00264                        &buf[block_size*blocks]);
00265       }
00266    else
00267       throw Internal_Error("NULL cipher not supported");
00268    }
00269 
00270 namespace {
00271 
00272 size_t fill_buffer_to(secure_vector<byte>& readbuf,
00273                       const byte*& input,
00274                       size_t& input_size,
00275                       size_t& input_consumed,
00276                       size_t desired)
00277    {
00278    if(readbuf.size() >= desired)
00279       return 0; // already have it
00280 
00281    const size_t taken = std::min(input_size, desired - readbuf.size());
00282 
00283    readbuf.insert(readbuf.end(), &input[0], &input[taken]);
00284    input_consumed += taken;
00285    input_size -= taken;
00286    input += taken;
00287 
00288    return (desired - readbuf.size()); // how many bytes do we still need?
00289    }
00290 
00291 /*
00292 * Checks the TLS padding. Returns 0 if the padding is invalid (we
00293 * count the padding_length field as part of the padding size so a
00294 * valid padding will always be at least one byte long), or the length
00295 * of the padding otherwise. This is actually padding_length + 1
00296 * because both the padding and padding_length fields are padding from
00297 * our perspective.
00298 *
00299 * Returning 0 in the error case should ensure the MAC check will fail.
00300 * This approach is suggested in section 6.2.3.2 of RFC 5246.
00301 *
00302 * Also returns 0 if block_size == 0, so can be safely called with a
00303 * stream cipher in use.
00304 *
00305 * @fixme This should run in constant time
00306 */
00307 size_t tls_padding_check(const byte record[], size_t record_len)
00308    {
00309    const size_t padding_length = record[(record_len-1)];
00310 
00311    if(padding_length >= record_len)
00312       return 0;
00313 
00314    /*
00315    * TLS v1.0 and up require all the padding bytes be the same value
00316    * and allows up to 255 bytes.
00317    */
00318    const size_t pad_start = record_len - padding_length - 1;
00319 
00320    volatile size_t cmp = 0;
00321 
00322    for(size_t i = 0; i != padding_length; ++i)
00323       cmp += record[pad_start + i] ^ padding_length;
00324 
00325    return cmp ? 0 : padding_length + 1;
00326    }
00327 
00328 void cbc_decrypt_record(byte record_contents[], size_t record_len,
00329                         Connection_Cipher_State& cs,
00330                         const BlockCipher& bc)
00331    {
00332    const size_t block_size = cs.block_size();
00333 
00334    BOTAN_ASSERT(record_len % block_size == 0,
00335                 "Buffer is an even multiple of block size");
00336 
00337    const size_t blocks = record_len / block_size;
00338 
00339    BOTAN_ASSERT(blocks >= 1, "At least one ciphertext block");
00340 
00341    byte* buf = record_contents;
00342 
00343    secure_vector<byte> last_ciphertext(block_size);
00344    copy_mem(&last_ciphertext[0], &buf[0], block_size);
00345 
00346    bc.decrypt(&buf[0]);
00347    xor_buf(&buf[0], &cs.cbc_state()[0], block_size);
00348 
00349    secure_vector<byte> last_ciphertext2;
00350 
00351    for(size_t i = 1; i < blocks; ++i)
00352       {
00353       last_ciphertext2.assign(&buf[block_size*i], &buf[block_size*(i+1)]);
00354       bc.decrypt(&buf[block_size*i]);
00355       xor_buf(&buf[block_size*i], &last_ciphertext[0], block_size);
00356       std::swap(last_ciphertext, last_ciphertext2);
00357       }
00358 
00359    cs.cbc_state() = last_ciphertext;
00360    }
00361 
00362 void decrypt_record(secure_vector<byte>& output,
00363                     byte record_contents[], size_t record_len,
00364                     u64bit record_sequence,
00365                     Protocol_Version record_version,
00366                     Record_Type record_type,
00367                     Connection_Cipher_State& cs)
00368    {
00369    if(AEAD_Mode* aead = cs.aead())
00370       {
00371       const secure_vector<byte>& nonce = cs.aead_nonce(record_contents, record_len, record_sequence);
00372       const byte* msg = &record_contents[cs.nonce_bytes_from_record()];
00373       const size_t msg_length = record_len - cs.nonce_bytes_from_record();
00374 
00375       const size_t ptext_size = aead->output_length(msg_length);
00376 
00377       aead->set_associated_data_vec(
00378          cs.format_ad(record_sequence, record_type, record_version, ptext_size)
00379          );
00380 
00381       output += aead->start(nonce);
00382 
00383       const size_t offset = output.size();
00384       output += std::make_pair(&msg[0], msg_length);
00385       aead->finish(output, offset);
00386 
00387       BOTAN_ASSERT(output.size() == ptext_size + offset, "Produced expected size");
00388       }
00389    else
00390       {
00391       // GenericBlockCipher / GenericStreamCipher case
00392 
00393       volatile bool padding_bad = false;
00394       size_t pad_size = 0;
00395 
00396       if(StreamCipher* sc = cs.stream_cipher())
00397          {
00398          sc->cipher1(record_contents, record_len);
00399          // no padding to check or remove
00400          }
00401       else if(BlockCipher* bc = cs.block_cipher())
00402          {
00403          cbc_decrypt_record(record_contents, record_len, cs, *bc);
00404 
00405          pad_size = tls_padding_check(record_contents, record_len);
00406 
00407          padding_bad = (pad_size == 0);
00408          }
00409       else
00410          {
00411          throw Internal_Error("No cipher state set but needed to decrypt");
00412          }
00413 
00414       const size_t mac_size = cs.mac_size();
00415       const size_t iv_size = cs.iv_size();
00416 
00417       const size_t mac_pad_iv_size = mac_size + pad_size + iv_size;
00418 
00419       if(record_len < mac_pad_iv_size)
00420          throw Decoding_Error("Record sent with invalid length");
00421 
00422       const byte* plaintext_block = &record_contents[iv_size];
00423       const u16bit plaintext_length = record_len - mac_pad_iv_size;
00424 
00425       cs.mac()->update(
00426          cs.format_ad(record_sequence, record_type, record_version, plaintext_length)
00427          );
00428 
00429       cs.mac()->update(plaintext_block, plaintext_length);
00430 
00431       std::vector<byte> mac_buf(mac_size);
00432       cs.mac()->final(&mac_buf[0]);
00433 
00434       const size_t mac_offset = record_len - (mac_size + pad_size);
00435 
00436       const bool mac_bad = !same_mem(&record_contents[mac_offset], &mac_buf[0], mac_size);
00437 
00438       if(mac_bad || padding_bad)
00439          throw TLS_Exception(Alert::BAD_RECORD_MAC, "Message authentication failure");
00440 
00441       output.assign(plaintext_block, plaintext_block + plaintext_length);
00442       }
00443    }
00444 
00445 size_t read_tls_record(secure_vector<byte>& readbuf,
00446                        const byte input[],
00447                        size_t input_sz,
00448                        size_t& consumed,
00449                        secure_vector<byte>& record,
00450                        u64bit* record_sequence,
00451                        Protocol_Version* record_version,
00452                        Record_Type* record_type,
00453                        Connection_Sequence_Numbers* sequence_numbers,
00454                        get_cipherstate_fn get_cipherstate)
00455    {
00456    consumed = 0;
00457 
00458    if(readbuf.size() < TLS_HEADER_SIZE) // header incomplete?
00459       {
00460       if(size_t needed = fill_buffer_to(readbuf,
00461                                         input, input_sz, consumed,
00462                                         TLS_HEADER_SIZE))
00463          return needed;
00464 
00465       BOTAN_ASSERT_EQUAL(readbuf.size(), TLS_HEADER_SIZE, "Have an entire header");
00466       }
00467 
00468    *record_version = Protocol_Version(readbuf[1], readbuf[2]);
00469 
00470    BOTAN_ASSERT(!record_version->is_datagram_protocol(), "Expected TLS");
00471 
00472    const size_t record_len = make_u16bit(readbuf[TLS_HEADER_SIZE-2],
00473                                          readbuf[TLS_HEADER_SIZE-1]);
00474 
00475    if(record_len > MAX_CIPHERTEXT_SIZE)
00476       throw TLS_Exception(Alert::RECORD_OVERFLOW,
00477                           "Got message that exceeds maximum size");
00478 
00479    if(size_t needed = fill_buffer_to(readbuf,
00480                                      input, input_sz, consumed,
00481                                      TLS_HEADER_SIZE + record_len))
00482       return needed;
00483 
00484    BOTAN_ASSERT_EQUAL(static_cast<size_t>(TLS_HEADER_SIZE) + record_len,
00485                       readbuf.size(),
00486                       "Have the full record");
00487 
00488    *record_type = static_cast<Record_Type>(readbuf[0]);
00489 
00490    u16bit epoch = 0;
00491 
00492    if(sequence_numbers)
00493       {
00494       *record_sequence = sequence_numbers->next_read_sequence();
00495       epoch = sequence_numbers->current_read_epoch();
00496       }
00497    else
00498       {
00499       // server initial handshake case
00500       *record_sequence = 0;
00501       epoch = 0;
00502       }
00503 
00504    byte* record_contents = &readbuf[TLS_HEADER_SIZE];
00505 
00506    if(epoch == 0) // Unencrypted initial handshake
00507       {
00508       record.assign(&readbuf[TLS_HEADER_SIZE], &readbuf[TLS_HEADER_SIZE + record_len]);
00509       readbuf.clear();
00510       return 0; // got a full record
00511       }
00512 
00513    // Otherwise, decrypt, check MAC, return plaintext
00514    auto cs = get_cipherstate(epoch);
00515 
00516    BOTAN_ASSERT(cs, "Have cipherstate for this epoch");
00517 
00518    decrypt_record(record,
00519                   record_contents,
00520                   record_len,
00521                   *record_sequence,
00522                   *record_version,
00523                   *record_type,
00524                   *cs);
00525 
00526    if(sequence_numbers)
00527       sequence_numbers->read_accept(*record_sequence);
00528 
00529    readbuf.clear();
00530    return 0;
00531    }
00532 
00533 size_t read_dtls_record(secure_vector<byte>& readbuf,
00534                         const byte input[],
00535                         size_t input_sz,
00536                         size_t& consumed,
00537                         secure_vector<byte>& record,
00538                         u64bit* record_sequence,
00539                         Protocol_Version* record_version,
00540                         Record_Type* record_type,
00541                         Connection_Sequence_Numbers* sequence_numbers,
00542                         get_cipherstate_fn get_cipherstate)
00543    {
00544    consumed = 0;
00545 
00546    if(readbuf.size() < DTLS_HEADER_SIZE) // header incomplete?
00547       {
00548       if(fill_buffer_to(readbuf, input, input_sz, consumed, DTLS_HEADER_SIZE))
00549          {
00550          readbuf.clear();
00551          return 0;
00552          }
00553 
00554       BOTAN_ASSERT_EQUAL(readbuf.size(), DTLS_HEADER_SIZE, "Have an entire header");
00555       }
00556 
00557    *record_version = Protocol_Version(readbuf[1], readbuf[2]);
00558 
00559    BOTAN_ASSERT(record_version->is_datagram_protocol(), "Expected DTLS");
00560 
00561    const size_t record_len = make_u16bit(readbuf[DTLS_HEADER_SIZE-2],
00562                                          readbuf[DTLS_HEADER_SIZE-1]);
00563 
00564    if(record_len > MAX_CIPHERTEXT_SIZE)
00565       throw TLS_Exception(Alert::RECORD_OVERFLOW,
00566                           "Got message that exceeds maximum size");
00567 
00568    if(fill_buffer_to(readbuf, input, input_sz, consumed, DTLS_HEADER_SIZE + record_len))
00569       {
00570       // Truncated packet?
00571       readbuf.clear();
00572       return 0;
00573       }
00574 
00575    BOTAN_ASSERT_EQUAL(static_cast<size_t>(DTLS_HEADER_SIZE) + record_len, readbuf.size(),
00576                       "Have the full record");
00577 
00578    *record_type = static_cast<Record_Type>(readbuf[0]);
00579 
00580    u16bit epoch = 0;
00581 
00582    *record_sequence = load_be<u64bit>(&readbuf[3], 0);
00583    epoch = (*record_sequence >> 48);
00584 
00585    if(sequence_numbers && sequence_numbers->already_seen(*record_sequence))
00586       {
00587       readbuf.clear();
00588       return 0;
00589       }
00590 
00591    byte* record_contents = &readbuf[DTLS_HEADER_SIZE];
00592 
00593    if(epoch == 0) // Unencrypted initial handshake
00594       {
00595       record.assign(&readbuf[DTLS_HEADER_SIZE], &readbuf[DTLS_HEADER_SIZE + record_len]);
00596       readbuf.clear();
00597       return 0; // got a full record
00598       }
00599 
00600    try
00601       {
00602       // Otherwise, decrypt, check MAC, return plaintext
00603       auto cs = get_cipherstate(epoch);
00604 
00605       BOTAN_ASSERT(cs, "Have cipherstate for this epoch");
00606 
00607       decrypt_record(record,
00608                      record_contents,
00609                      record_len,
00610                      *record_sequence,
00611                      *record_version,
00612                      *record_type,
00613                      *cs);
00614       }
00615    catch(std::exception)
00616       {
00617       readbuf.clear();
00618       *record_type = NO_RECORD;
00619       return 0;
00620       }
00621 
00622    if(sequence_numbers)
00623       sequence_numbers->read_accept(*record_sequence);
00624 
00625    readbuf.clear();
00626    return 0;
00627    }
00628 
00629 }
00630 
00631 size_t read_record(secure_vector<byte>& readbuf,
00632                    const byte input[],
00633                    size_t input_sz,
00634                    bool is_datagram,
00635                    size_t& consumed,
00636                    secure_vector<byte>& record,
00637                    u64bit* record_sequence,
00638                    Protocol_Version* record_version,
00639                    Record_Type* record_type,
00640                    Connection_Sequence_Numbers* sequence_numbers,
00641                    get_cipherstate_fn get_cipherstate)
00642    {
00643    if(is_datagram)
00644       return read_dtls_record(readbuf, input, input_sz, consumed,
00645                               record, record_sequence, record_version, record_type,
00646                               sequence_numbers, get_cipherstate);
00647    else
00648       return read_tls_record(readbuf, input, input_sz, consumed,
00649                              record, record_sequence, record_version, record_type,
00650                              sequence_numbers, get_cipherstate);
00651    }
00652 
00653 }
00654 
00655 }