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::CCM_Encryption Class Referencefinal

`#include <ccm.h>`

Inheritance diagram for Botan::CCM_Encryption:

## Public Member Functions
bool | authenticated () const override
| CCM_Encryption (BlockCipher *cipher, size_t tag_size=16, size_t L=3)
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 sz) override
virtual std::string | provider () const
void | reset () override
template<typename Alloc >
void | set_ad (const std::vector< uint8_t, Alloc > &ad)
void | set_associated_data (const uint8_t ad[], size_t ad_len) override
template<typename Alloc >
void | set_associated_data_vec (const std::vector< uint8_t, Alloc > &ad)
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 ()
size_t | tag_size () const override
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) const override

## Protected Member Functions
const secure_vector< uint8_t > & | ad_buf () const
const BlockCipher & | cipher () const
void | encode_length (size_t len, uint8_t out[])
secure_vector< uint8_t > | format_b0 (size_t msg_size)
secure_vector< uint8_t > | format_c0 ()
void | inc (secure_vector< uint8_t > &C)
size_t | L () const
secure_vector< uint8_t > & | msg_buf ()

## Detailed Description

CCM Encryption

Definition at line 78 of file ccm.h.

## Constructor & Destructor Documentation

Botan::CCM_Encryption::CCM_Encryption | ( | BlockCipher * | cipher,
|  | size_t | tag_size = `16`,
|  | size_t | L = `3`
| ) |  |
| inline

Parameters

  cipher | a 128-bit block cipher
  tag_size | is how big the auth tag will be (even values between 4 and 16 are accepted)
  L | length of L parameter. The total message length must be less than 2**L bytes, and the nonce is 15-L bytes.

Definition at line 88 of file ccm.h.

88 :
89 CCM_Mode(cipher, tag_size, L) {}
Botan::CCM_Mode::L
size_t L() const
Definition: ccm.h:49
Botan::CCM_Mode::cipher
const BlockCipher & cipher() const
Definition: ccm.h:51
Botan::CCM_Mode::CCM_Mode
CCM_Mode(BlockCipher *cipher, size_t tag_size, size_t L)
Definition: ccm.cpp:20
Botan::CCM_Mode::tag_size
size_t tag_size() const override
Definition: ccm.h:44

## Member Function Documentation

const secure_vector<uint8_t>& Botan::CCM_Mode::ad_buf | ( |  | ) | const
| inline protected inherited

Definition at line 57 of file ccm.h.

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

57 { return m_ad_buf; }

bool Botan::AEAD_Mode::authenticated | ( |  | ) | const
| inline override virtual inherited

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

Reimplemented from Botan::Cipher_Mode.

Definition at line 25 of file aead.h.

25 { return true; }

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

Definition at line 51 of file ccm.h.

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

51 { return *m_cipher; }

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

Zeroise all state See also reset_msg()

Implements Botan::Cipher_Mode.

Definition at line 35 of file ccm.cpp.

References Botan::CCM_Mode::reset().

36 {
37 m_cipher->clear();
38 reset();
39 }
Botan::CCM_Mode::reset
void reset() override
Definition: ccm.cpp:41

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

Returns
  default AEAD nonce size (a commonly supported value among AEAD modes, and large enough that random collisions are unlikely)

Reimplemented from Botan::AEAD_Mode.

Definition at line 58 of file ccm.cpp.

References Botan::CCM_Mode::L().

59 {
60 return (15-L());
61 }
Botan::CCM_Mode::L
size_t L() const
Definition: ccm.h:49

void Botan::CCM_Mode::encode_length | ( | size_t | len,
|  | uint8_t | out[]
| ) |  |
| protected inherited

Definition at line 116 of file ccm.cpp.

References BOTAN_ASSERT, Botan::get_byte(), and Botan::CCM_Mode::L().

Referenced by Botan::CCM_Mode::format_b0().

117 {
118 const size_t len_bytes = L();
119
120 BOTAN_ASSERT(len_bytes < sizeof(size_t), "Length field fits");
121
122 for(size_t i = 0; i != len_bytes; ++i)
123 out[len_bytes-1-i] = get_byte(sizeof(size_t)-1-i, len);
124
125 BOTAN_ASSERT((len >> (len_bytes*8)) == 0, "Message length fits in field");
126 }
Botan::CCM_Mode::L
size_t L() const
Definition: ccm.h:49
BOTAN_ASSERT
#define BOTAN_ASSERT(expr, assertion_made)
Definition: assert.h:27
Botan::get_byte
uint8_t get_byte(size_t byte_num, T input)
Definition: loadstor.h:47

void Botan::CCM_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 160 of file ccm.cpp.

References Botan::CCM_Mode::ad_buf(), BOTAN_ASSERT, Botan::CCM_Mode::cipher(), Botan::CCM_Mode::format_b0(), Botan::CCM_Mode::format_c0(), Botan::CCM_Mode::inc(), Botan::CCM_Mode::msg_buf(), Botan::CCM_Mode::tag_size(), and Botan::xor_buf().

161 {
162 BOTAN_ASSERT(buffer.size() >= offset, "Offset is sane");
163
164 buffer.insert(buffer.begin() + offset, msg_buf().begin(), msg_buf().end());
165
166 const size_t sz = buffer.size() - offset;
167 uint8_t* buf = buffer.data() + offset;
168
169 const secure_vector<uint8_t>& ad = ad_buf();
170 BOTAN_ASSERT(ad.size() % CCM_BS == 0, "AD is block size multiple");
171
172 const BlockCipher& E = cipher();
173
174 secure_vector<uint8_t> T(CCM_BS);
175 E.encrypt(format_b0(sz), T);
176
177 for(size_t i = 0; i != ad.size(); i += CCM_BS)
178 {
179 xor_buf(T.data(), &ad[i], CCM_BS);
180 E.encrypt(T);
181 }
182
183 secure_vector<uint8_t> C = format_c0();
184 secure_vector<uint8_t> S0(CCM_BS);
185 E.encrypt(C, S0);
186 inc(C);
187
188 secure_vector<uint8_t> X(CCM_BS);
189
190 const uint8_t* buf_end = &buf[sz];
191
192 while(buf != buf_end)
193 {
194 const size_t to_proc = std::min<size_t>(CCM_BS, buf_end - buf);
195
196 xor_buf(T.data(), buf, to_proc);
197 E.encrypt(T);
198
199 E.encrypt(C, X);
200 xor_buf(buf, X.data(), to_proc);
201 inc(C);
202
203 buf += to_proc;
204 }
205
206 T ^= S0;
207
208 buffer += std::make_pair(T.data(), tag_size());
209 }
Botan::xor_buf
void xor_buf(T out[], const T in[], size_t length)
Definition: mem_ops.h:115
Botan::CCM_Mode::format_c0
secure_vector< uint8_t > format_c0()
Definition: ccm.cpp:148
BOTAN_ASSERT
#define BOTAN_ASSERT(expr, assertion_made)
Definition: assert.h:27
Botan::CCM_Mode::cipher
const BlockCipher & cipher() const
Definition: ccm.h:51
Botan::CCM_Mode::inc
void inc(secure_vector< uint8_t > &C)
Definition: ccm.cpp:128
Botan::CCM_Mode::ad_buf
const secure_vector< uint8_t > & ad_buf() const
Definition: ccm.h:57
Botan::CCM_Mode::format_b0
secure_vector< uint8_t > format_b0(size_t msg_size)
Definition: ccm.cpp:135
Botan::CCM_Mode::msg_buf
secure_vector< uint8_t > & msg_buf()
Definition: ccm.h:59
Botan::CCM_Mode::tag_size
size_t tag_size() const override
Definition: ccm.h:44

secure_vector< uint8_t > Botan::CCM_Mode::format_b0 | ( | size_t | msg_size | ) |
| protected inherited

Definition at line 135 of file ccm.cpp.

References Botan::copy_mem(), Botan::CCM_Mode::encode_length(), Botan::CCM_Mode::L(), and Botan::CCM_Mode::tag_size().

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

136 {
137 secure_vector<uint8_t> B0(CCM_BS);
138
139 const uint8_t b_flags = (m_ad_buf.size() ? 64 : 0) + (((tag_size()/2)-1) << 3) + (L()-1);
140
141 B0[0] = b_flags;
142 copy_mem(&B0[1], m_nonce.data(), m_nonce.size());
143 encode_length(sz, &B0[m_nonce.size()+1]);
144
145 return B0;
146 }
Botan::CCM_Mode::L
size_t L() const
Definition: ccm.h:49
Botan::CCM_Mode::encode_length
void encode_length(size_t len, uint8_t out[])
Definition: ccm.cpp:116
Botan::copy_mem
void copy_mem(T *out, const T *in, size_t n)
Definition: mem_ops.h:68
Botan::CCM_Mode::tag_size
size_t tag_size() const override
Definition: ccm.h:44

secure_vector< uint8_t > Botan::CCM_Mode::format_c0 | ( |  | ) |
| protected inherited

Definition at line 148 of file ccm.cpp.

References Botan::copy_mem(), and Botan::CCM_Mode::L().

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

149 {
150 secure_vector<uint8_t> C(CCM_BS);
151
152 const uint8_t a_flags = L()-1;
153
154 C[0] = a_flags;
155 copy_mem(&C[1], m_nonce.data(), m_nonce.size());
156
157 return C;
158 }
Botan::CCM_Mode::L
size_t L() const
Definition: ccm.h:49
Botan::copy_mem
void copy_mem(T *out, const T *in, size_t n)
Definition: mem_ops.h:68

void Botan::CCM_Mode::inc | ( | secure_vector< uint8_t > & | C | ) |
| protected inherited

Definition at line 128 of file ccm.cpp.

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

129 {
130 for(size_t i = 0; i != C.size(); ++i)
131 if(++C[C.size()-i-1])
132 break;
133 }

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

Returns
  object describing limits on key size

Implements Botan::Cipher_Mode.

Definition at line 74 of file ccm.cpp.

75 {
76 return m_cipher->key_spec();
77 }

size_t Botan::CCM_Mode::L | ( |  | ) | const
| inline protected inherited

Definition at line 49 of file ccm.h.

Referenced by Botan::CCM_Mode::default_nonce_length(), Botan::CCM_Mode::encode_length(), Botan::CCM_Mode::format_b0(), Botan::CCM_Mode::format_c0(), Botan::CCM_Mode::name(), and Botan::CCM_Mode::valid_nonce_length().

49 { return m_L; }

size_t Botan::CCM_Encryption::minimum_final_size | ( |  | ) | const
| inline override virtual

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

Implements Botan::Cipher_Mode.

Definition at line 96 of file ccm.h.

96 { return 0; }

secure_vector<uint8_t>& Botan::CCM_Mode::msg_buf | ( |  | ) |
| inline protected inherited

Definition at line 59 of file ccm.h.

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

59 { return m_msg_buf; }

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

Implements Botan::Cipher_Mode.

Definition at line 48 of file ccm.cpp.

References Botan::CCM_Mode::L(), Botan::CCM_Mode::tag_size(), and Botan::ASN1::to_string().

49 {
50 return (m_cipher->name() + "/CCM(" + std::to_string(tag_size()) + "," + std::to_string(L())) + ")";
51 }
Botan::CCM_Mode::L
size_t L() const
Definition: ccm.h:49
Botan::ASN1::to_string
std::string to_string(const BER_Object &obj)
Definition: asn1_obj.cpp:47
Botan::CCM_Mode::tag_size
size_t tag_size() const override
Definition: ccm.h:44

size_t Botan::CCM_Encryption::output_length | ( | size_t | input_length | ) | const
| inline 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 93 of file ccm.h.

94 { return input_length + tag_size(); }
Botan::CCM_Mode::tag_size
size_t tag_size() const override
Definition: ccm.h:44

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

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 110 of file ccm.cpp.

111 {
112 m_msg_buf.insert(m_msg_buf.end(), buf, buf + sz);
113 return 0; // no output until finished
114 }

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::CCM_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 41 of file ccm.cpp.

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

42 {
43 m_nonce.clear();
44 m_msg_buf.clear();
45 m_ad_buf.clear();
46 }
template<typename Alloc >

void Botan::AEAD_Mode::set_ad | ( | const std::vector< uint8_t, Alloc > & | ad | ) |
| inline inherited

Set associated data that is not included in the ciphertext but that should be authenticated. Must be called after set_key and before start.

See set_associated_data().

Parameters

  ad | the associated data

Definition at line 66 of file aead.h.

Referenced by Botan::TLS::write_record().

67 {
68 set_associated_data(ad.data(), ad.size());
69 }
Botan::AEAD_Mode::set_associated_data
virtual void set_associated_data(const uint8_t ad[], size_t ad_len)=0

void Botan::CCM_Mode::set_associated_data | ( | const uint8_t | ad[],
|  | size_t | ad_len
| ) |  |
| override virtual inherited

Set associated data that is not included in the ciphertext but that should be authenticated. Must be called after set_key and before start.

Unless reset by another call, the associated data is kept between messages. Thus, if the AD does not change, calling once (after set_key) is the optimum.

Parameters

  ad | the associated data
  ad_len | length of add in bytes

Implements Botan::AEAD_Mode.

Definition at line 84 of file ccm.cpp.

References BOTAN_ASSERT, and Botan::get_byte().

85 {
86 m_ad_buf.clear();
87
88 if(length)
89 {
90 // FIXME: support larger AD using length encoding rules
91 BOTAN_ASSERT(length < (0xFFFF - 0xFF), "Supported CCM AD length");
92
93 m_ad_buf.push_back(get_byte(0, static_cast<uint16_t>(length)));
94 m_ad_buf.push_back(get_byte(1, static_cast<uint16_t>(length)));
95 m_ad_buf += std::make_pair(ad, length);
96 while(m_ad_buf.size() % CCM_BS)
97 m_ad_buf.push_back(0); // pad with zeros to full block size
98 }
99 }
BOTAN_ASSERT
#define BOTAN_ASSERT(expr, assertion_made)
Definition: assert.h:27
Botan::get_byte
uint8_t get_byte(size_t byte_num, T input)
Definition: loadstor.h:47
template<typename Alloc >

void Botan::AEAD_Mode::set_associated_data_vec | ( | const std::vector< uint8_t, Alloc > & | ad | ) |
| inline inherited

Set associated data that is not included in the ciphertext but that should be authenticated. Must be called after set_key and before start.

See set_associated_data().

Parameters

  ad | the associated data

Definition at line 51 of file aead.h.

52 {
53 set_associated_data(ad.data(), ad.size());
54 }
Botan::AEAD_Mode::set_associated_data
virtual void set_associated_data(const uint8_t ad[], size_t ad_len)=0
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

size_t Botan::CCM_Mode::tag_size | ( |  | ) | const
| inline override virtual inherited

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

Reimplemented from Botan::Cipher_Mode.

Definition at line 44 of file ccm.h.

Referenced by finish(), Botan::CCM_Decryption::finish(), Botan::CCM_Mode::format_b0(), and Botan::CCM_Mode::name().

44 { return m_tag_size; }

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(), Botan::XTS_Encryption::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::CCM_Mode::update_granularity | ( |  | ) | const
| override virtual inherited

Returns
  size of required blocks to update

Implements Botan::Cipher_Mode.

Definition at line 63 of file ccm.cpp.

64 {
65 /*
66 This value does not particularly matter as regardless CCM_Mode::update
67 buffers all input, so in theory this could be 1. However as for instance
68 Transform_Filter creates update_granularity() uint8_t buffers, use a
69 somewhat large size to avoid bouncing on a tiny buffer.
70 */
71 return m_cipher->parallel_bytes();
72 }

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::CCM_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 53 of file ccm.cpp.

References Botan::CCM_Mode::L().

54 {
55 return (n == (15-L()));
56 }
Botan::CCM_Mode::L
size_t L() const
Definition: ccm.h:49

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

- src/lib/modes/aead/ccm/ccm.h
- src/lib/modes/aead/ccm/ccm.cpp