Botan 3.14.1
Crypto and TLS for C&
tls_signature_scheme.cpp
Go to the documentation of this file.
1/*
2* (C) 2022,2023 Jack Lloyd
3* (C) 2022 René Meusel, Hannes Rantzsch - neXenio GmbH
4*
5* Botan is released under the Simplified BSD License (see license.txt)
6*/
7
8#include <botan/assert.h>
9#include <botan/tls_signature_scheme.h>
10
11#include <botan/ec_group.h>
12#include <botan/ecc_key.h>
13#include <botan/hex.h>
14#include <botan/pk_keys.h>
15#include <botan/pss_params.h>
16#include <botan/tls_version.h>
17#include <botan/internal/fmt.h>
18#include <botan/internal/loadstor.h>
19#include <botan/internal/stl_util.h>
20
21namespace Botan::TLS {
22
23const std::vector<Signature_Scheme>& Signature_Scheme::all_available_schemes() {
24 /*
25 * This is ordered in some approximate order of preference
26 */
27 static const std::vector<Signature_Scheme> all_schemes = {
28
29 // EdDSA 25519 is currently not supported as a signature scheme for certificates
30 // certificate authentication.
31 // See: https://github.com/randombit/botan/pull/2958#discussion_r851294715
32 //
33 // #if defined(BOTAN_HAS_ED25519)
34 // EDDSA_25519,
35 // #endif
36
40
41#if defined(BOTAN_HAS_RSA) && defined(BOTAN_HAS_EMSA_PSSR)
45#endif
46
50
51#if defined(BOTAN_HAS_RSA) && defined(BOTAN_HAS_EMSA_PKCS1)
55#endif
56 };
57
58 return all_schemes;
59}
60
62 if(str == "RSA_PKCS1_SHA1") {
63 return RSA_PKCS1_SHA1;
64 }
65 if(str == "RSA_PKCS1_SHA256") {
66 return RSA_PKCS1_SHA256;
67 }
68 if(str == "RSA_PKCS1_SHA384") {
69 return RSA_PKCS1_SHA384;
70 }
71 if(str == "RSA_PKCS1_SHA512") {
72 return RSA_PKCS1_SHA512;
73 }
74
75 if(str == "ECDSA_SHA1") {
76 return ECDSA_SHA1;
77 }
78 if(str == "ECDSA_SHA256" || str == "ECDSA_SECP256R1_TLS13_SHA256") {
80 }
81 if(str == "ECDSA_SHA384" || str == "ECDSA_SECP384R1_TLS13_SHA384") {
83 }
84 if(str == "ECDSA_SHA512" || str == "ECDSA_SECP521R1_TLS13_SHA512") {
86 }
87
88 if(str == "RSA_PSS_SHA256") {
89 return RSA_PSS_SHA256;
90 }
91 if(str == "RSA_PSS_SHA384") {
92 return RSA_PSS_SHA384;
93 }
94 if(str == "RSA_PSS_SHA512") {
95 return RSA_PSS_SHA512;
96 }
97
98 if(str == "ECDSA_BRAINPOOL256R1_TLS13_SHA256") {
100 }
101 if(str == "ECDSA_BRAINPOOL384R1_TLS13_SHA384") {
103 }
104 if(str == "ECDSA_BRAINPOOL512R1_TLS13_SHA512") {
106 }
107
108 // Parse signature schemes passed as hexadecimal code points (e.g. "0x081A")
109 if(str.size() == 6 && str.starts_with("0x")) {
110 try {
111 std::array<uint8_t, 2> wire_code{};
112 Botan::hex_decode(wire_code, str.substr(2), false /* no white space */);
114 } catch(const Invalid_Argument&) {
115 // pass, will throw below
116 }
117 }
118
119 throw Invalid_Argument(fmt("Unknown TLS signature scheme '{}'", str));
120}
121
123
125
127
128bool Signature_Scheme::is_available() const noexcept {
129 switch(m_code) {
130#if defined(BOTAN_HAS_RSA) && defined(BOTAN_HAS_EMSA_PSSR)
131 case RSA_PSS_SHA384:
132 case RSA_PSS_SHA256:
133 case RSA_PSS_SHA512:
134#endif
135#if defined(BOTAN_HAS_RSA) && defined(BOTAN_HAS_EMSA_PKCS1)
136 case RSA_PKCS1_SHA384:
137 case RSA_PKCS1_SHA512:
138 case RSA_PKCS1_SHA256:
139#endif
146 return true;
147 default:
148 return false;
149 }
150}
151
152bool Signature_Scheme::is_set() const noexcept {
153 return m_code != NONE;
154}
155
156std::string Signature_Scheme::to_string() const {
157 switch(m_code) {
158 case RSA_PKCS1_SHA1:
159 return "RSA_PKCS1_SHA1";
160 case RSA_PKCS1_SHA256:
161 return "RSA_PKCS1_SHA256";
162 case RSA_PKCS1_SHA384:
163 return "RSA_PKCS1_SHA384";
164 case RSA_PKCS1_SHA512:
165 return "RSA_PKCS1_SHA512";
166
167 case ECDSA_SHA1:
168 return "ECDSA_SHA1";
170 return "ECDSA_SHA256";
172 return "ECDSA_SHA384";
174 return "ECDSA_SHA512";
175
177 return "ECDSA_BRAINPOOL256R1_TLS13_SHA256";
179 return "ECDSA_BRAINPOOL384R1_TLS13_SHA384";
181 return "ECDSA_BRAINPOOL512R1_TLS13_SHA512";
182
183 case RSA_PSS_SHA256:
184 return "RSA_PSS_SHA256";
185 case RSA_PSS_SHA384:
186 return "RSA_PSS_SHA384";
187 case RSA_PSS_SHA512:
188 return "RSA_PSS_SHA512";
189
190 case EDDSA_25519:
191 return "EDDSA_25519";
192 case EDDSA_448:
193 return "EDDSA_448";
194
195 default:
196 return "Unknown signature scheme: " + std::to_string(m_code);
197 }
198}
199
201 switch(m_code) {
202 case RSA_PKCS1_SHA1:
203 case ECDSA_SHA1:
204 return "SHA-1";
205
207 case RSA_PKCS1_SHA256:
208 case RSA_PSS_SHA256:
210 return "SHA-256";
211
213 case RSA_PKCS1_SHA384:
214 case RSA_PSS_SHA384:
216 return "SHA-384";
217
219 case RSA_PKCS1_SHA512:
220 case RSA_PSS_SHA512:
222 return "SHA-512";
223
224 case EDDSA_25519:
225 case EDDSA_448:
226 return "Pure";
227
228 default:
229 return "Unknown hash function";
230 }
231}
232
234 switch(m_code) {
235 case RSA_PKCS1_SHA1:
236 return "PKCS1v15(SHA-1)";
237 case RSA_PKCS1_SHA256:
238 return "PKCS1v15(SHA-256)";
239 case RSA_PKCS1_SHA384:
240 return "PKCS1v15(SHA-384)";
241 case RSA_PKCS1_SHA512:
242 return "PKCS1v15(SHA-512)";
243
244 case ECDSA_SHA1:
245 return "SHA-1";
248 return "SHA-256";
251 return "SHA-384";
254 return "SHA-512";
255
256 case RSA_PSS_SHA256:
257 return "PSS(SHA-256,MGF1,32)";
258 case RSA_PSS_SHA384:
259 return "PSS(SHA-384,MGF1,48)";
260 case RSA_PSS_SHA512:
261 return "PSS(SHA-512,MGF1,64)";
262
263 case EDDSA_25519:
264 case EDDSA_448:
265 return "Pure";
266
267 default:
268 return "Unknown padding";
269 }
270}
271
273 switch(m_code) {
274 case RSA_PKCS1_SHA1:
275 case RSA_PKCS1_SHA256:
276 case RSA_PKCS1_SHA384:
277 case RSA_PKCS1_SHA512:
278 case RSA_PSS_SHA256:
279 case RSA_PSS_SHA384:
280 case RSA_PSS_SHA512:
281 return "RSA";
282
283 case ECDSA_SHA1:
290 return "ECDSA";
291
292 case EDDSA_25519:
293 return "Ed25519";
294
295 case EDDSA_448:
296 return "Ed448";
297
298 default:
299 return "Unknown algorithm";
300 }
301}
302
304 const auto der_encode_oid = [](const std::string_view oid_name) {
305 try {
306 if(auto oid = OID::from_name(oid_name)) {
307 return oid->BER_encode();
308 }
309 } catch(...) {}
311 };
312
313 switch(m_code) {
314 // case ECDSA_SHA1: not defined
316 return {"ECDSA", der_encode_oid("secp256r1")};
318 return {"ECDSA", der_encode_oid("secp384r1")};
320 return {"ECDSA", der_encode_oid("secp521r1")};
321
323 return {"ECDSA", der_encode_oid("brainpool256r1")};
325 return {"ECDSA", der_encode_oid("brainpool384r1")};
327 return {"ECDSA", der_encode_oid("brainpool512r1")};
328
329 case EDDSA_25519:
330 return {"Ed25519", AlgorithmIdentifier::USE_EMPTY_PARAM};
331 case EDDSA_448:
332 return {"Ed448", AlgorithmIdentifier::USE_EMPTY_PARAM};
333
334 case RSA_PKCS1_SHA1:
335 case RSA_PKCS1_SHA256:
336 case RSA_PKCS1_SHA384:
337 case RSA_PKCS1_SHA512:
338 case RSA_PSS_SHA256:
339 case RSA_PSS_SHA384:
340 case RSA_PSS_SHA512:
342
343 default:
344 return AlgorithmIdentifier();
345 }
346}
347
349 switch(m_code) {
350 case RSA_PKCS1_SHA1:
352 case RSA_PKCS1_SHA256:
354 case RSA_PKCS1_SHA384:
356 case RSA_PKCS1_SHA512:
358
359 case ECDSA_SHA1:
370
371 case RSA_PSS_SHA256:
372 return AlgorithmIdentifier(OID::from_string("RSA/PSS"), PSS_Params("SHA-256", 32).serialize());
373 case RSA_PSS_SHA384:
374 return AlgorithmIdentifier(OID::from_string("RSA/PSS"), PSS_Params("SHA-384", 48).serialize());
375 case RSA_PSS_SHA512:
376 return AlgorithmIdentifier(OID::from_string("RSA/PSS"), PSS_Params("SHA-512", 64).serialize());
377
378 default:
379 // Note that Ed25519 and Ed448 end up here
380 return AlgorithmIdentifier();
381 }
382}
383
384std::optional<Signature_Format> Signature_Scheme::format() const noexcept {
385 switch(m_code) {
386 case RSA_PKCS1_SHA1:
387 case RSA_PKCS1_SHA256:
388 case RSA_PKCS1_SHA384:
389 case RSA_PKCS1_SHA512:
390 case RSA_PSS_SHA256:
391 case RSA_PSS_SHA384:
392 case RSA_PSS_SHA512:
393 case EDDSA_25519:
394 case EDDSA_448:
396
397 case ECDSA_SHA1:
405
406 default:
407 return std::nullopt;
408 }
409}
410
411bool Signature_Scheme::is_compatible_with(const Protocol_Version& protocol_version) const noexcept {
412 // RFC 8446 4.4.3:
413 // The SHA-1 algorithm MUST NOT be used in any signatures of
414 // CertificateVerify messages.
415 //
416 // Note that Botan enforces that for TLS 1.2 as well.
417 if(m_code == RSA_PKCS1_SHA1 || m_code == ECDSA_SHA1) {
418 return false;
419 }
420
421 // RFC 8446 4.4.3:
422 // RSA signatures MUST use an RSASSA-PSS algorithm, regardless of whether
423 // RSASSA-PKCS1-v1_5 algorithms appear in "signature_algorithms".
424 //
425 // Note that this is enforced for TLS 1.3 and above only.
426 if(!protocol_version.is_pre_tls_13() && (m_code == RSA_PKCS1_SHA1 || m_code == RSA_PKCS1_SHA256 ||
427 m_code == RSA_PKCS1_SHA384 || m_code == RSA_PKCS1_SHA512)) {
428 return false;
429 }
430
431 // RFC 8734 defines these code points for TLS 1.3 only
432 if(protocol_version.is_pre_tls_13() &&
435 return false;
436 }
437
438 return true;
439}
440
441bool Signature_Scheme::is_suitable_for(const Private_Key& private_key) const {
442 if(algorithm_name() != private_key.algo_name()) {
443 return false;
444 }
445
446 // Keys this small are not suitable for any scheme
447 const auto keylen = private_key.key_length();
448 if(keylen <= 250) {
449 return false;
450 }
451
452 // Each TLS 1.3 ECDSA scheme names the curve of the key
453 if(algorithm_name() == "ECDSA") {
454 // Compare the curve itself, as an EC_PublicKey may be set to encode it explicitly
455 if(const auto* ec_key = dynamic_cast<const EC_PublicKey*>(&private_key)) {
456 const auto& curve = ec_key->domain().get_curve_oid();
457 return curve.has_value() && curve.BER_encode() == key_algorithm_identifier().parameters();
458 }
459 return key_algorithm_identifier() == private_key.algorithm_identifier();
460 }
461
462 return true;
463}
464
465std::vector<AlgorithmIdentifier> to_algorithm_identifiers(const std::vector<Signature_Scheme>& schemes) {
466 std::vector<AlgorithmIdentifier> result;
467 result.reserve(schemes.size());
468 for(const auto& scheme : schemes) {
469 result.push_back(scheme.algorithm_identifier());
470 }
471 return result;
472}
473
474std::vector<std::string> filter_signature_schemes(const std::vector<Signature_Scheme>& schemes,
475 const Protocol_Version& version) {
476 std::vector<std::string> key_types;
477 for(const auto& scheme : schemes) {
478 if(scheme.is_available() && scheme.is_compatible_with(version)) {
479 const auto algo_name = scheme.algorithm_name();
480 if(!value_exists(key_types, algo_name)) {
481 key_types.push_back(algo_name);
482 }
483 }
484 }
485 return key_types;
486}
487
488} // namespace Botan::TLS
#define BOTAN_ASSERT_UNREACHABLE()
Definition assert.h:173
const std::vector< uint8_t > & parameters() const
Definition asn1_obj.h:693
virtual std::string algo_name() const =0
static std::optional< OID > from_name(std::string_view name)
Definition asn1_oid.cpp:66
static OID from_string(std::string_view str)
Definition asn1_oid.cpp:80
virtual AlgorithmIdentifier algorithm_identifier() const =0
virtual size_t key_length() const =0
bool is_compatible_with(const Protocol_Version &protocol_version) const noexcept
bool is_suitable_for(const Private_Key &private_key) const
AlgorithmIdentifier key_algorithm_identifier() const
Signature_Scheme::Code wire_code() const noexcept
std::optional< Signature_Format > format() const noexcept
static Signature_Scheme from_string(std::string_view str)
AlgorithmIdentifier algorithm_identifier() const
static const std::vector< Signature_Scheme > & all_available_schemes()
std::vector< AlgorithmIdentifier > to_algorithm_identifiers(const std::vector< Signature_Scheme > &schemes)
std::vector< std::string > filter_signature_schemes(const std::vector< Signature_Scheme > &schemes, const Protocol_Version &version)
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53
bool value_exists(const std::vector< T > &vec, const V &val)
Definition stl_util.h:44
size_t hex_decode(uint8_t output[], const char input[], size_t input_length, size_t &input_consumed, bool ignore_ws)
Definition hex.cpp:75
constexpr auto load_be(ParamTs &&... params)
Definition loadstor.h:504