Botan 2.19.5 Crypto and TLS for C&

Functions
ffi_cipher.cpp File Reference
`#include <botan/ffi.h>`
`#include <botan/internal/ffi_util.h>`
`#include <botan/aead.h>`

Go to the source code of this file.

## Functions
int | botan_cipher_clear (botan_cipher_t cipher)
int | botan_cipher_destroy (botan_cipher_t cipher)
int | botan_cipher_get_default_nonce_length (botan_cipher_t cipher, size_t *nl)
int | botan_cipher_get_keyspec (botan_cipher_t cipher, size_t *out_minimum_keylength, size_t *out_maximum_keylength, size_t *out_keylength_modulo)
int | botan_cipher_get_tag_length (botan_cipher_t cipher, size_t *tl)
int | botan_cipher_get_update_granularity (botan_cipher_t cipher, size_t *ug)
int | botan_cipher_init (botan_cipher_t *cipher, const char *cipher_name, uint32_t flags)
int | botan_cipher_name (botan_cipher_t cipher, char *name, size_t *name_len)
int | botan_cipher_output_length (botan_cipher_t cipher, size_t in_len, size_t *out_len)
int | botan_cipher_query_keylen (botan_cipher_t cipher, size_t *out_minimum_keylength, size_t *out_maximum_keylength)
int | botan_cipher_reset (botan_cipher_t cipher)
int | botan_cipher_set_associated_data (botan_cipher_t cipher, const uint8_t *ad, size_t ad_len)
int | botan_cipher_set_key (botan_cipher_t cipher, const uint8_t *key, size_t key_len)
int | botan_cipher_start (botan_cipher_t cipher_obj, const uint8_t *nonce, size_t nonce_len)
int | botan_cipher_update (botan_cipher_t cipher_obj, uint32_t flags, uint8_t output_ptr[], size_t orig_output_size, size_t *output_written, const uint8_t input_ptr[], size_t orig_input_size, size_t *input_consumed)
int | botan_cipher_valid_nonce_length (botan_cipher_t cipher, size_t nl)

## Function Documentation

## ◆ botan_cipher_clear()

int botan_cipher_clear | ( | botan_cipher_t | hash | ) |

Reset the key, nonce, AD and all other state on this cipher object

Definition at line 39 of file ffi_cipher.cpp.

40 {
41 return BOTAN_FFI_DO(Botan::Cipher_Mode, cipher, c, { c.clear(); });
42 }
Botan::Cipher_Mode
Definition: cipher_mode.h:29
Botan::SymmetricAlgorithm::clear
virtual void clear()=0
BOTAN_FFI_DO
#define BOTAN_FFI_DO(T, obj, param, block)
Definition: ffi_util.h:92

References BOTAN_FFI_DO, and Botan::SymmetricAlgorithm::clear().

## ◆ botan_cipher_destroy()

int botan_cipher_destroy | ( | botan_cipher_t | cipher | ) |

Destroy the cipher object

Returns
  0 if success, error if invalid object handle

Definition at line 34 of file ffi_cipher.cpp.

35 {
36 return BOTAN_FFI_CHECKED_DELETE(cipher);
37 }
BOTAN_FFI_CHECKED_DELETE
#define BOTAN_FFI_CHECKED_DELETE(o)
Definition: ffi_util.h:129

References BOTAN_FFI_CHECKED_DELETE.

## ◆ botan_cipher_get_default_nonce_length()

int botan_cipher_get_default_nonce_length | ( | botan_cipher_t | cipher,
|  | size_t * | nl
| ) |  |

Get the default nonce length of this cipher

Definition at line 212 of file ffi_cipher.cpp.

213 {
214 return BOTAN_FFI_DO(Botan::Cipher_Mode, cipher, c, { *nl = c.default_nonce_length(); });
215 }
Botan::Cipher_Mode::default_nonce_length
virtual size_t default_nonce_length() const =0

References BOTAN_FFI_DO, and Botan::Cipher_Mode::default_nonce_length().

## ◆ botan_cipher_get_keyspec()

int botan_cipher_get_keyspec | ( | botan_cipher_t | cipher,
|  | size_t * | min_keylen,
|  | size_t * | max_keylen,
|  | size_t * | mod_keylen
| ) |  |

Get information about the supported key lengths.

Definition at line 67 of file ffi_cipher.cpp.

71 {
72 return BOTAN_FFI_DO(Botan::Cipher_Mode, cipher, c, {
73 if(out_minimum_keylength)
74 *out_minimum_keylength = c.key_spec().minimum_keylength();
75 if(out_maximum_keylength)
76 *out_maximum_keylength = c.key_spec().maximum_keylength();
77 if(out_keylength_modulo)
78 *out_keylength_modulo = c.key_spec().keylength_multiple();
79 });
80 }
Botan::Key_Length_Specification::minimum_keylength
size_t minimum_keylength() const
Definition: sym_algo.h:62
Botan::SymmetricAlgorithm::key_spec
virtual Key_Length_Specification key_spec() const =0

References BOTAN_FFI_DO, Botan::SymmetricAlgorithm::key_spec(), and Botan::Key_Length_Specification::minimum_keylength().

## ◆ botan_cipher_get_tag_length()

int botan_cipher_get_tag_length | ( | botan_cipher_t | cipher,
|  | size_t * | tag_size
| ) |  |

Get the tag length of the cipher (0 for non-AEAD modes)

Definition at line 222 of file ffi_cipher.cpp.

223 {
224 return BOTAN_FFI_DO(Botan::Cipher_Mode, cipher, c, { *tl = c.tag_size(); });
225 }
Botan::Cipher_Mode::tag_size
virtual size_t tag_size() const
Definition: cipher_mode.h:174

References BOTAN_FFI_DO, and Botan::Cipher_Mode::tag_size().

## ◆ botan_cipher_get_update_granularity()

int botan_cipher_get_update_granularity | ( | botan_cipher_t | cipher,
|  | size_t * | ug
| ) |  |

Return the update granularity of the cipher; botan_cipher_update must be called with blocks of this size, except for the final.

Definition at line 217 of file ffi_cipher.cpp.

218 {
219 return BOTAN_FFI_DO(Botan::Cipher_Mode, cipher, c, { *ug = c.update_granularity(); });
220 }
Botan::Cipher_Mode::update_granularity
virtual size_t update_granularity() const =0

References BOTAN_FFI_DO, and Botan::Cipher_Mode::update_granularity().

## ◆ botan_cipher_init()

int botan_cipher_init | ( | botan_cipher_t * | cipher,
|  | const char * | name,
|  | uint32_t | flags
| ) |  |

Initialize a cipher object

Definition at line 21 of file ffi_cipher.cpp.

22 {
23 return ffi_guard_thunk(__func__, [=]() -> int {
24 const bool encrypt_p = ((flags & BOTAN_CIPHER_INIT_FLAG_MASK_DIRECTION) == BOTAN_CIPHER_INIT_FLAG_ENCRYPT);
25 const Botan::Cipher_Dir dir = encrypt_p ? Botan::ENCRYPTION : Botan::DECRYPTION;
26 std::unique_ptr<Botan::Cipher_Mode> mode(Botan::Cipher_Mode::create(cipher_name, dir));
27 if(!mode)
28 return BOTAN_FFI_ERROR_NOT_IMPLEMENTED;
29 *cipher = new botan_cipher_struct(mode.release());
30 return BOTAN_FFI_SUCCESS;
31 });
32 }
Botan::Cipher_Mode::create
static std::unique_ptr< Cipher_Mode > create(const std::string &algo, Cipher_Dir direction, const std::string &provider="")
Definition: cipher_mode.cpp:50
BOTAN_CIPHER_INIT_FLAG_ENCRYPT
#define BOTAN_CIPHER_INIT_FLAG_ENCRYPT
Definition: ffi.h:440
BOTAN_CIPHER_INIT_FLAG_MASK_DIRECTION
#define BOTAN_CIPHER_INIT_FLAG_MASK_DIRECTION
Definition: ffi.h:439
BOTAN_FFI_ERROR_NOT_IMPLEMENTED
@ BOTAN_FFI_ERROR_NOT_IMPLEMENTED
Definition: ffi.h:83
BOTAN_FFI_SUCCESS
@ BOTAN_FFI_SUCCESS
Definition: ffi.h:63
Botan::PKCS11::flags
Flags flags(Flag flags)
Definition: p11.h:860
Botan_FFI::ffi_guard_thunk
int ffi_guard_thunk(const char *func_name, std::function< int()> thunk)
Definition: ffi.cpp:89
Botan::Cipher_Dir
Cipher_Dir
Definition: cipher_mode.h:23
Botan::DECRYPTION
@ DECRYPTION
Definition: cipher_mode.h:23
Botan::ENCRYPTION
@ ENCRYPTION
Definition: cipher_mode.h:23

References BOTAN_CIPHER_INIT_FLAG_ENCRYPT, BOTAN_CIPHER_INIT_FLAG_MASK_DIRECTION, BOTAN_FFI_ERROR_NOT_IMPLEMENTED, BOTAN_FFI_SUCCESS, Botan::Cipher_Mode::create(), Botan::DECRYPTION, Botan::ENCRYPTION, Botan_FFI::ffi_guard_thunk(), and Botan::PKCS11::flags().

## ◆ botan_cipher_name()

int botan_cipher_name | ( | botan_cipher_t | cipher,
|  | char * | name,
|  | size_t * | name_len
| ) |  |

Return the name of the cipher object

Definition at line 227 of file ffi_cipher.cpp.

228 {
229 return BOTAN_FFI_DO(Botan::Cipher_Mode, cipher, c, {
230 return write_str_output(name, name_len, c.name()); });
231 }
name
std::string name
Definition: commoncrypto_hash.cpp:24
Botan_FFI::write_str_output
int write_str_output(uint8_t out[], size_t *out_len, const std::string &str)
Definition: ffi_util.h:160

References BOTAN_FFI_DO, name, and Botan_FFI::write_str_output().

## ◆ botan_cipher_output_length()

int botan_cipher_output_length | ( | botan_cipher_t | cipher,
|  | size_t | in_len,
|  | size_t * | out_len
| ) |  |

Return the output length of this cipher, for a particular input length.

Definition at line 49 of file ffi_cipher.cpp.

50 {
51 if(out_len == nullptr)
52 return BOTAN_FFI_ERROR_NULL_POINTER;
53
54 return BOTAN_FFI_DO(Botan::Cipher_Mode, cipher, c, { *out_len = c.output_length(in_len); });
55 }
Botan::Cipher_Mode::output_length
virtual size_t output_length(size_t input_length) const =0
BOTAN_FFI_ERROR_NULL_POINTER
@ BOTAN_FFI_ERROR_NULL_POINTER
Definition: ffi.h:77

References BOTAN_FFI_DO, BOTAN_FFI_ERROR_NULL_POINTER, and Botan::Cipher_Mode::output_length().

## ◆ botan_cipher_query_keylen()

int botan_cipher_query_keylen | ( | botan_cipher_t | cipher,
|  | size_t * | out_minimum_keylength,
|  | size_t * | out_maximum_keylength
| ) |  |

Get information about the key lengths. Prefer botan_cipher_get_keyspec

Definition at line 57 of file ffi_cipher.cpp.

60 {
61 return BOTAN_FFI_DO(Botan::Cipher_Mode, cipher, c, {
62 *out_minimum_keylength = c.key_spec().minimum_keylength();
63 *out_maximum_keylength = c.key_spec().maximum_keylength();
64 });
65 }

References BOTAN_FFI_DO, and Botan::SymmetricAlgorithm::key_spec().

## ◆ botan_cipher_reset()

int botan_cipher_reset | ( | botan_cipher_t | cipher | ) |

Reset the message specific state for this cipher. Without resetting the keys, this resets the nonce, and any state associated with any message bits that have been processed so far.

It is conceptually equivalent to calling botan_cipher_clear followed by botan_cipher_set_key with the original key.

Definition at line 44 of file ffi_cipher.cpp.

45 {
46 return BOTAN_FFI_DO(Botan::Cipher_Mode, cipher, c, { c.reset(); });
47 }
Botan::Cipher_Mode::reset
virtual void reset()=0

References BOTAN_FFI_DO, and Botan::Cipher_Mode::reset().

## ◆ botan_cipher_set_associated_data()

int botan_cipher_set_associated_data | ( | botan_cipher_t | cipher,
|  | const uint8_t * | ad,
|  | size_t | ad_len
| ) |  |

Set the associated data. Will fail if cipher is not an AEAD

Definition at line 191 of file ffi_cipher.cpp.

194 {
195 return BOTAN_FFI_RETURNING(Botan::Cipher_Mode, cipher, c, {
196 if(Botan::AEAD_Mode* aead = dynamic_cast<Botan::AEAD_Mode*>(&c))
197 {
198 aead->set_associated_data(ad, ad_len);
199 return BOTAN_FFI_SUCCESS;
200 }
201 return BOTAN_FFI_ERROR_BAD_PARAMETER;
202 });
203 }
Botan::AEAD_Mode
Definition: aead.h:23
BOTAN_FFI_ERROR_BAD_PARAMETER
@ BOTAN_FFI_ERROR_BAD_PARAMETER
Definition: ffi.h:78
BOTAN_FFI_RETURNING
#define BOTAN_FFI_RETURNING(T, obj, param, block)
Definition: ffi_util.h:101

References BOTAN_FFI_ERROR_BAD_PARAMETER, BOTAN_FFI_RETURNING, and BOTAN_FFI_SUCCESS.

## ◆ botan_cipher_set_key()

int botan_cipher_set_key | ( | botan_cipher_t | cipher,
|  | const uint8_t * | key,
|  | size_t | key_len
| ) |  |

Set the key for this cipher object

Definition at line 82 of file ffi_cipher.cpp.

84 {
85 return BOTAN_FFI_DO(Botan::Cipher_Mode, cipher, c, { c.set_key(key, key_len); });
86 }
Botan::SymmetricAlgorithm::set_key
void set_key(const SymmetricKey &key)
Definition: sym_algo.h:147

References BOTAN_FFI_DO, and Botan::SymmetricAlgorithm::set_key().

## ◆ botan_cipher_start()

int botan_cipher_start | ( | botan_cipher_t | cipher,
|  | const uint8_t * | nonce,
|  | size_t | nonce_len
| ) |  |

Begin processing a new message using the provided nonce

Definition at line 88 of file ffi_cipher.cpp.

90 {
91 return ffi_guard_thunk(__func__, [=]() -> int {
92 Botan::Cipher_Mode& cipher = safe_get(cipher_obj);
93 cipher.start(nonce, nonce_len);
94 cipher_obj->m_buf.reserve(cipher.update_granularity());
95 return BOTAN_FFI_SUCCESS;
96 });
97 }
Botan::Cipher_Mode::start
void start(const std::vector< uint8_t, Alloc > &nonce)
Definition: cipher_mode.h:69
Botan_FFI::safe_get
T & safe_get(botan_struct< T, M > *p)
Definition: ffi_util.h:61

References BOTAN_FFI_SUCCESS, Botan_FFI::ffi_guard_thunk(), Botan_FFI::safe_get(), Botan::Cipher_Mode::start(), and Botan::Cipher_Mode::update_granularity().

## ◆ botan_cipher_update()

int botan_cipher_update | ( | botan_cipher_t | cipher,
|  | uint32_t | flags,
|  | uint8_t | output[],
|  | size_t | output_size,
|  | size_t * | output_written,
|  | const uint8_t | input_bytes[],
|  | size_t | input_size,
|  | size_t * | input_consumed
| ) |  |

Encrypt some data

Definition at line 99 of file ffi_cipher.cpp.

107 {
108 return ffi_guard_thunk(__func__, [=]() -> int {
109
110 size_t input_size = orig_input_size;
111 size_t output_size = orig_output_size;
112 const uint8_t* input = input_ptr;
113 uint8_t* output = output_ptr;
114
115 using namespace Botan;
116 Cipher_Mode& cipher = safe_get(cipher_obj);
117 secure_vector<uint8_t>& mbuf = cipher_obj->m_buf;
118
119 const bool final_input = (flags & BOTAN_CIPHER_UPDATE_FLAG_FINAL);
120
121 if(final_input)
122 {
123 mbuf.assign(input, input + input_size);
124 *input_consumed = input_size;
125 *output_written = 0;
126
127 try
128 {
129 cipher.finish(mbuf);
130 }
131 catch(Invalid_Authentication_Tag&)
132 {
133 return BOTAN_FFI_ERROR_BAD_MAC;
134 }
135
136 *output_written = mbuf.size();
137
138 if(mbuf.size() <= output_size)
139 {
140 copy_mem(output, mbuf.data(), mbuf.size());
141 mbuf.clear();
142 return BOTAN_FFI_SUCCESS;
143 }
144
145 return -1;
146 }
147
148 if(input_size == 0)
149 {
150 // Currently must take entire buffer in this case
151 *output_written = mbuf.size();
152 if(output_size >= mbuf.size())
153 {
154 copy_mem(output, mbuf.data(), mbuf.size());
155 mbuf.clear();
156 return BOTAN_FFI_SUCCESS;
157 }
158
159 return -1;
160 }
161
162 const size_t ud = cipher.update_granularity();
163 BOTAN_ASSERT(cipher.update_granularity() > cipher.minimum_final_size(), "logic error");
164
165 mbuf.resize(ud);
166 size_t taken = 0, written = 0;
167
168 while(input_size >= ud && output_size >= ud)
169 {
170 // FIXME we can use process here and avoid the copy
171 copy_mem(mbuf.data(), input, ud);
172 cipher.update(mbuf);
173
174 input_size -= ud;
175 copy_mem(output, mbuf.data(), ud);
176 input += ud;
177 taken += ud;
178
179 output_size -= ud;
180 output += ud;
181 written += ud;
182 }
183
184 *output_written = written;
185 *input_consumed = taken;
186
187 return BOTAN_FFI_SUCCESS;
188 });
189 }
BOTAN_ASSERT
#define BOTAN_ASSERT(expr, assertion_made)
Definition: assert.h:55
Botan::Cipher_Mode::finish
virtual void finish(secure_vector< uint8_t > &final_block, size_t offset=0)=0
Botan::Cipher_Mode::update
void update(secure_vector< uint8_t > &buffer, size_t offset=0)
Definition: cipher_mode.h:112
Botan::Cipher_Mode::minimum_final_size
virtual size_t minimum_final_size() const =0
Botan::Invalid_Authentication_Tag
Definition: exceptn.h:291
BOTAN_CIPHER_UPDATE_FLAG_FINAL
#define BOTAN_CIPHER_UPDATE_FLAG_FINAL
Definition: ffi.h:522
BOTAN_FFI_ERROR_BAD_MAC
@ BOTAN_FFI_ERROR_BAD_MAC
Definition: ffi.h:67
Botan
Definition: alg_id.cpp:13
Botan::copy_mem
void copy_mem(T *out, const T *in, size_t n)
Definition: mem_ops.h:133
Botan::secure_vector
std::vector< T, secure_allocator< T > > secure_vector
Definition: secmem.h:65

References BOTAN_ASSERT, BOTAN_CIPHER_UPDATE_FLAG_FINAL, BOTAN_FFI_ERROR_BAD_MAC, BOTAN_FFI_SUCCESS, Botan::copy_mem(), Botan_FFI::ffi_guard_thunk(), Botan::Cipher_Mode::finish(), Botan::PKCS11::flags(), Botan::Cipher_Mode::minimum_final_size(), Botan_FFI::safe_get(), Botan::Cipher_Mode::update(), and Botan::Cipher_Mode::update_granularity().

## ◆ botan_cipher_valid_nonce_length()

int botan_cipher_valid_nonce_length | ( | botan_cipher_t | cipher,
|  | size_t | nl
| ) |  |

Return if the specified nonce length is valid for this cipher

Definition at line 205 of file ffi_cipher.cpp.

206 {
207 return BOTAN_FFI_RETURNING(Botan::Cipher_Mode, cipher, c, {
208 return c.valid_nonce_length(nl) ? 1 : 0;
209 });
210 }
Botan::Cipher_Mode::valid_nonce_length
virtual bool valid_nonce_length(size_t nonce_len) const =0

References BOTAN_FFI_RETURNING, and Botan::Cipher_Mode::valid_nonce_length().