Botan 3.14.1
Crypto and TLS for C&
pk_ops.cpp
Go to the documentation of this file.
1/*
2* PK Operation Types
3* (C) 2010,2015,2023 Jack Lloyd
4*
5* Botan is released under the Simplified BSD License (see license.txt)
6*/
7
8#include <botan/internal/pk_ops_impl.h>
9
10#include <botan/assert.h>
11#include <botan/hash.h>
12#include <botan/kdf.h>
13#include <botan/pk_options_readers.h>
14#include <botan/rng.h>
15#include <botan/internal/ct_utils.h>
16#include <botan/internal/fmt.h>
17#include <botan/internal/parsing.h>
18#include <botan/internal/pk_options_impl.h>
19
20#if defined(BOTAN_HAS_RAW_HASH_FN)
21 #include <botan/internal/raw_hash.h>
22#endif
23
24#if defined(BOTAN_HAS_RSA_ENCRYPTION_PADDING)
25 #include <botan/internal/enc_padding.h>
26#endif
27
28namespace Botan {
29
31 throw Not_Implemented("This signature scheme does not have an algorithm identifier available");
32}
33
34#if defined(BOTAN_HAS_RSA_ENCRYPTION_PADDING)
35
36PK_Ops::Encryption_with_Padding::Encryption_with_Padding(const PK_Encryption_Options_Reader& options) :
37 m_padding(EncryptionPaddingScheme::create_or_throw(options)) {}
38
39PK_Ops::Encryption_with_Padding::~Encryption_with_Padding() = default;
40
41size_t PK_Ops::Encryption_with_Padding::max_input_bits() const {
42 return 8 * m_padding->maximum_input_size(max_ptext_input_bits());
43}
44
45std::vector<uint8_t> PK_Ops::Encryption_with_Padding::encrypt(std::span<const uint8_t> msg,
46 RandomNumberGenerator& rng) {
47 const size_t max_input_bits = max_ptext_input_bits();
48 const size_t max_input_bytes = (max_input_bits + 7) / 8;
49 BOTAN_ARG_CHECK(msg.size() <= max_input_bytes, "Plaintext too large");
50
51 secure_vector<uint8_t> padded_ptext(max_input_bytes);
52 const size_t written = m_padding->pad(padded_ptext, msg, max_input_bits, rng);
53 return raw_encrypt(std::span{padded_ptext}.first(written), rng);
54}
55
56PK_Ops::Decryption_with_Padding::Decryption_with_Padding(const PK_Encryption_Options_Reader& options) :
57 m_padding(EncryptionPaddingScheme::create_or_throw(options)) {}
58
59PK_Ops::Decryption_with_Padding::~Decryption_with_Padding() = default;
60
61size_t PK_Ops::Decryption_with_Padding::decrypt(uint8_t& valid_mask,
62 std::span<uint8_t> ptext,
63 std::span<const uint8_t> ctext) {
64 const secure_vector<uint8_t> raw = raw_decrypt(ctext);
65
66 // Unpadding requires space for the entire encoded message
67 BOTAN_ARG_CHECK(ptext.size() >= raw.size(), "Output buffer too small for decryption");
68
69 const auto len = m_padding->unpad(ptext, raw);
70
71 valid_mask = CT::Mask<uint8_t>::from_choice(len.has_value()).if_set_return(0xFF);
72 return len.value_or(0);
73}
74
75#endif
76
78 if(options.using_kdf()) {
79 m_kdf = KDF::create_or_throw(options.kdf().value());
80 } else if(!options.using_raw_shared_key()) {
81 throw Invalid_Argument(
82 "Key agreement does not produce a uniform shared key, so a KDF must be specified (or the raw shared key "
83 "explicitly requested)");
84 }
85}
86
88
90 std::span<const uint8_t> other_key,
91 std::span<const uint8_t> salt) {
92 if(!salt.empty() && m_kdf == nullptr) {
93 throw Invalid_Argument("PK_Key_Agreement::derive_key requires a KDF to use a salt");
94 }
95
96 secure_vector<uint8_t> z = raw_agree(other_key.data(), other_key.size());
97 if(m_kdf) {
98 return m_kdf->derive_key(key_len, z, salt.data(), salt.size());
99 }
100 return z;
101}
102
103namespace {
104
105std::unique_ptr<HashFunction> validate_options_returning_hash(const PK_Signature_Options_Reader& options) {
106 // The caller provides the digest; if they named the hash, its length is checked
108#if defined(BOTAN_HAS_RAW_HASH_FN)
109 if(auto prehash = externally_computed_prehash_name(options)) {
110 return std::make_unique<RawHashFunction>(HashFunction::create_or_throw(*prehash));
111 }
112 return std::make_unique<RawHashFunction>("Raw", 0);
113#else
114 throw Lookup_Error("Signing an externally computed prehash requires the raw_hash module");
115#endif
116 }
117
118 BOTAN_ARG_CHECK(!options.hash_function_name().empty(), "This algorithm requires a hash function for signing");
119
120 /*
121 * In a sense ECDSA/DSA are *always* in prehashing mode, so we accept the case
122 * where prehashing is requested as long as the prehash hash matches the signature hash.
123 */
124 if(options.using_prehash()) {
125 if(!options.prehash_function().has_value() ||
126 options.prehash_function().value() != options.hash_function_name()) {
127 throw Invalid_Argument("This algorithm does not support prehashing with a different hash");
128 }
129 }
130
132}
133
134} // namespace
135
137 Signature(), m_hash(validate_options_returning_hash(options)) {}
138
140
141#if defined(BOTAN_HAS_RFC6979_GENERATOR)
142std::string PK_Ops::Signature_with_Hash::rfc6979_hash_function() const {
143 std::string hash = m_hash->name();
144 if(hash != "Raw") {
145 return hash;
146 }
147 return "SHA-512";
148}
149#endif
150
152 return m_hash->name();
153}
154
155void PK_Ops::Signature_with_Hash::update(std::span<const uint8_t> msg) {
156 m_hash->update(msg);
157}
158
160 const std::vector<uint8_t> msg = m_hash->final_stdvec();
161 return raw_sign(msg, rng);
162}
163
165 Verification(), m_hash(validate_options_returning_hash(options)) {}
166
168
170 return m_hash->name();
171}
172
174 std::string_view pk_algo,
175 bool allow_null_parameters) {
176 const auto oid_name = alg_id.oid().registered_name();
177 if(!oid_name) {
178 throw Decoding_Error(
179 fmt("Unexpected AlgorithmIdentifier OID {} in association with {} key", alg_id.oid(), pk_algo));
180 }
181
182 const auto oid_info = split_on(*oid_name, '/');
183
184 if(oid_info.size() != 2 || oid_info[0] != pk_algo) {
185 throw Decoding_Error(
186 fmt("Unexpected AlgorithmIdentifier OID {} in association with {} key", alg_id.oid(), pk_algo));
187 }
188
189 if(!alg_id.parameters_are_empty()) {
190 if(alg_id.parameters_are_null()) {
191 if(!allow_null_parameters) {
192 throw Decoding_Error(fmt("Unexpected NULL AlgorithmIdentifier parameters for {}", pk_algo));
193 }
194 } else {
195 throw Decoding_Error(fmt("Unexpected AlgorithmIdentifier parameters for {}", pk_algo));
196 }
197 }
198
199 m_hash = HashFunction::create_or_throw(oid_info[1]);
200}
201
202void PK_Ops::Verification_with_Hash::update(std::span<const uint8_t> msg) {
203 m_hash->update(msg);
204}
205
206bool PK_Ops::Verification_with_Hash::is_valid_signature(std::span<const uint8_t> sig) {
207 const std::vector<uint8_t> msg = m_hash->final_stdvec();
208 return verify(msg, sig);
209}
210
211size_t PK_Ops::KEM_Encryption_with_KDF::shared_key_length(size_t desired_shared_key_len) const {
212 if(m_kdf) {
213 return desired_shared_key_len;
214 } else {
215 return this->raw_kem_shared_key_length();
216 }
217}
218
219void PK_Ops::KEM_Encryption_with_KDF::kem_encrypt(std::span<uint8_t> out_encapsulated_key,
220 std::span<uint8_t> out_shared_key,
222 size_t desired_shared_key_len,
223 std::span<const uint8_t> salt) {
224 BOTAN_ARG_CHECK(salt.empty() || m_kdf, "PK_KEM_Encryptor::encrypt requires a KDF to use a salt");
225 BOTAN_ASSERT_NOMSG(out_encapsulated_key.size() == encapsulated_key_length());
226
227 if(m_kdf) {
229 out_shared_key.size(), desired_shared_key_len, "KDF output length and shared key length match");
230
232 this->raw_kem_encrypt(out_encapsulated_key, raw_shared, rng);
233 m_kdf->derive_key(out_shared_key, raw_shared, salt, {});
234 } else {
235 BOTAN_ASSERT_EQUAL(out_shared_key.size(), raw_kem_shared_key_length(), "Shared key has raw KEM output length");
236 this->raw_kem_encrypt(out_encapsulated_key, out_shared_key, rng);
237 }
238}
239
240namespace {
241
242std::unique_ptr<KDF> kem_kdf_from_options(const PK_KEM_Options_Reader& options, PK_Ops::KemSharedKeyQuality raw_key) {
243 if(options.using_kdf()) {
244 return KDF::create_or_throw(options.kdf().value());
245 }
246
248 throw Invalid_Argument(
249 "This KEM does not produce a uniform shared key, so a KDF must be specified (or the raw shared key "
250 "explicitly requested)");
251 }
252
253 // No KDF; the raw shared key is used directly
254 return nullptr;
255}
256
257} // namespace
258
260 KemSharedKeyQuality raw_key) :
261 m_kdf(kem_kdf_from_options(options, raw_key)) {}
262
264
265size_t PK_Ops::KEM_Decryption_with_KDF::shared_key_length(size_t desired_shared_key_len) const {
266 if(m_kdf) {
267 return desired_shared_key_len;
268 } else {
269 return this->raw_kem_shared_key_length();
270 }
271}
272
273void PK_Ops::KEM_Decryption_with_KDF::kem_decrypt(std::span<uint8_t> out_shared_key,
274 std::span<const uint8_t> encapsulated_key,
275 size_t desired_shared_key_len,
276 std::span<const uint8_t> salt) {
277 BOTAN_ARG_CHECK(salt.empty() || m_kdf, "PK_KEM_Decryptor::decrypt requires a KDF to use a salt");
278
279 if(m_kdf) {
281 out_shared_key.size(), desired_shared_key_len, "KDF output length and shared key length match");
282
284 this->raw_kem_decrypt(raw_shared, encapsulated_key);
285 m_kdf->derive_key(out_shared_key, raw_shared, salt, {});
286 } else {
287 BOTAN_ASSERT_EQUAL(out_shared_key.size(), raw_kem_shared_key_length(), "Shared key has raw KEM output length");
288 this->raw_kem_decrypt(out_shared_key, encapsulated_key);
289 }
290}
291
293 KemSharedKeyQuality raw_key) :
294 m_kdf(kem_kdf_from_options(options, raw_key)) {}
295
297
298} // namespace Botan
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
#define BOTAN_ASSERT_EQUAL(expr1, expr2, assertion_made)
Definition assert.h:95
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
bool parameters_are_empty() const
Definition asn1_obj.h:715
bool parameters_are_null() const
Definition alg_id.cpp:50
const OID & oid() const
Definition asn1_obj.h:688
static constexpr Mask< T > from_choice(Choice c)
Definition ct_utils.h:407
static std::unique_ptr< HashFunction > create_or_throw(std::string_view algo_spec, std::string_view provider="")
Definition hash.cpp:311
static std::unique_ptr< KDF > create_or_throw(std::string_view algo_spec, std::string_view provider="")
Definition kdf.cpp:208
std::optional< std::string > registered_name() const
Definition asn1_oid.cpp:149
const std::optional< std::string > & kdf() const
const std::optional< std::string > & kdf() const
KEM_Decryption_with_KDF(const PK_KEM_Options_Reader &options, KemSharedKeyQuality raw_key)
Definition pk_ops.cpp:292
void kem_decrypt(std::span< uint8_t > out_shared_key, std::span< const uint8_t > encapsulated_key, size_t desired_shared_key_len, std::span< const uint8_t > salt) final
Definition pk_ops.cpp:273
virtual void raw_kem_decrypt(std::span< uint8_t > out_raw_shared_key, std::span< const uint8_t > encapsulated_key)=0
size_t shared_key_length(size_t desired_shared_key_len) const final
Definition pk_ops.cpp:265
virtual size_t raw_kem_shared_key_length() const =0
void kem_encrypt(std::span< uint8_t > out_encapsulated_key, std::span< uint8_t > out_shared_key, RandomNumberGenerator &rng, size_t desired_shared_key_len, std::span< const uint8_t > salt) final
Definition pk_ops.cpp:219
virtual size_t raw_kem_shared_key_length() const =0
KEM_Encryption_with_KDF(const PK_KEM_Options_Reader &options, KemSharedKeyQuality raw_key)
Definition pk_ops.cpp:259
size_t shared_key_length(size_t desired_shared_key_len) const final
Definition pk_ops.cpp:211
virtual void raw_kem_encrypt(std::span< uint8_t > out_encapsulated_key, std::span< uint8_t > out_raw_shared_key, RandomNumberGenerator &rng)=0
virtual size_t encapsulated_key_length() const =0
Key_Agreement_with_KDF(const PK_Key_Agreement_Options_Reader &options)
Definition pk_ops.cpp:77
secure_vector< uint8_t > agree(size_t key_len, std::span< const uint8_t > other_key, std::span< const uint8_t > salt) override
Definition pk_ops.cpp:89
std::vector< uint8_t > sign(RandomNumberGenerator &rng) override
Definition pk_ops.cpp:159
Signature_with_Hash(const PK_Signature_Options_Reader &options)
Definition pk_ops.cpp:136
std::string hash_function() const final
Definition pk_ops.cpp:151
void update(std::span< const uint8_t > input) override
Definition pk_ops.cpp:155
virtual AlgorithmIdentifier algorithm_identifier() const
Definition pk_ops.cpp:30
virtual void update(std::span< const uint8_t > input)=0
std::string hash_function() const final
Definition pk_ops.cpp:169
void update(std::span< const uint8_t > input) override
Definition pk_ops.cpp:202
virtual bool verify(std::span< const uint8_t > msg, std::span< const uint8_t > sig)=0
Verification_with_Hash(const PK_Signature_Options_Reader &options)
Definition pk_ops.cpp:164
bool is_valid_signature(std::span< const uint8_t > sig) override
Definition pk_ops.cpp:206
const std::optional< std::string > & prehash_function() const
const std::string & hash_function_name() const
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53
std::vector< std::string > split_on(std::string_view str, char delim)
Definition parsing.cpp:83
std::optional< std::string > externally_computed_prehash_name(const PK_Signature_Options_Reader &options)
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128