Botan 3.14.1
Crypto and TLS for C&
pk_options_impl.cpp
Go to the documentation of this file.
1/*
2* (C) 2024 Jack Lloyd
3*
4* Botan is released under the Simplified BSD License (see license.txt)
5*/
6
7#include <botan/internal/pk_options_impl.h>
8
9#include <botan/assert.h>
10#include <botan/exceptn.h>
11#include <botan/internal/algorithm_spec.h>
12#include <botan/internal/fmt.h>
13
14namespace Botan {
15
16PK_Signature_Options parse_legacy_sig_options(const Public_Key& key, std::string_view params) {
17 /*
18 * This is a convoluted mess because we must handle dispatch for every algorithm
19 * specific detail of how padding strings were formatted in versions prior to the
20 * introduction of PK_Signature_Options.
21 *
22 * This will all go away once the deprecated constructors of PK_Signer and PK_Verifier
23 * are removed in Botan4.
24 */
25
26 const std::string algo = key.algo_name();
27
28 if(algo.starts_with("Dilithium") || algo.starts_with("ML-DSA") || algo == "SLH-DSA" || algo == "SPHINCS+") {
29 if(!params.empty() && params != "Randomized" && params != "Deterministic" && params != "Pure") {
30 throw Invalid_Argument(fmt("Unexpected parameters '{}' for signing with {}", params, algo));
31 }
32
33 if(params == "Deterministic" || params == "Pure") {
35 } else {
36 return PK_Signature_Options();
37 }
38 }
39
40 if(algo == "SM2") {
41 /*
42 * SM2 parameters have the following possible formats:
43 * Ident [since 2.2.0]
44 * Ident,Hash [since 2.3.0]
45 *
46 * Historically a completely empty parameter string was treated as
47 * if the identity was empty. This probably should have instead been
48 * treated as if it was the "default userid" ("1234567812345678") but
49 * there was a bug and it wasn't.
50 *
51 * TODO(Botan4) evaluate if this should be changed
52 */
53 std::string userid;
54 std::string hash = "SM3";
55 const auto comma = params.find(',');
56 if(comma == std::string::npos) {
57 userid = params;
58 } else {
59 userid = params.substr(0, comma);
60 hash = params.substr(comma + 1, std::string::npos);
61 }
62
63 // With a "Raw" hash there is no ZA computation, and the identity was always ignored
64 if(hash == "Raw") {
66 }
67
68 return PK_Signature_Options().with_hash(hash).with_context(userid);
69 }
70
71 if(algo == "Ed25519") {
72 if(params.empty() || params == "Identity" || params == "Pure") {
73 return PK_Signature_Options();
74 } else if(params == "Ed25519ph") {
76 } else {
77 return PK_Signature_Options().with_prehash(std::string(params));
78 }
79 }
80
81 if(algo == "Ed448") {
82 if(params.empty() || params == "Identity" || params == "Pure" || params == "Ed448") {
83 return PK_Signature_Options();
84 } else if(params == "Ed448ph") {
86 } else {
87 return PK_Signature_Options().with_prehash(std::string(params));
88 }
89 }
90
91 if(algo == "RSA") {
92 // handling various deprecated aliases that have accumulated over the years ...
93 const auto canonical_padding = [](std::string_view alg) -> std::string_view {
94 // TODO(Botan4) Remove all but "PKCSv15"
95 if(alg == "EMSA_PKCS1" || alg == "EMSA-PKCS1-v1_5" || alg == "EMSA3") {
96 return "PKCS1v15";
97 }
98
99 // TODO(Botan4) Remove this alias
100 if(alg == "PSSR_Raw") {
101 return "PSS_Raw";
102 }
103
104 // TODO(Botan4) Remove all but "PSS"
105 if(alg == "PSSR" || alg == "EMSA-PSS" || alg == "PSS-MGF1" || alg == "EMSA4") {
106 return "PSS";
107 }
108
109 // TODO(Botan4) Remove all but "X9.31"
110 if(alg == "EMSA_X931" || alg == "EMSA2" || alg == "X9.31") {
111 return "X9.31";
112 }
113
114 return alg;
115 };
116
117 const AlgorithmSpec given(params);
118 const AlgorithmSpec req = given.with_head(canonical_padding(given.head()));
119
120 if(auto m = req.match("Raw({hash?})")) {
121 if(m->has("hash")) {
123 std::string(m->str("hash")));
124 }
125 return PK_Signature_Options().with_padding("Raw");
126 }
127
128 if(auto m = req.match("PKCS1v15(Raw,{hash?})")) {
129 if(m->has("hash")) {
130 return PK_Signature_Options()
131 .with_padding("PKCS1v15")
132 .with_externally_computed_prehash(std::string(m->str("hash")));
133 }
135 }
136
137 if(auto m = req.match("PKCS1v15({hash})")) {
138 return PK_Signature_Options().with_padding("PKCS1v15").with_hash(m->str("hash"));
139 }
140
141 // Only supported by PKCS#11 (CKM_RSA_9796)
142 if(req.matches("ISO9796")) {
143 return PK_Signature_Options().with_padding("ISO9796");
144 }
145
146 if(req.matches("PSS(Raw)")) {
148 }
149
150 if(auto m = req.match("PSS|PSS_Raw({hash})")) {
151 return PK_Signature_Options().with_padding(m->head()).with_hash(m->str("hash"));
152 }
153
154 if(auto m = req.match("PSS|PSS_Raw({hash},MGF1,{salt_len:int?})")) {
155 auto pss_opt = PK_Signature_Options().with_padding(m->head()).with_hash(m->str("hash"));
156
157 if(m->has("salt_len")) {
158 return std::move(pss_opt).with_salt_size(m->integer("salt_len"));
159 }
160 return pss_opt;
161 }
162
163 if(auto m = req.match("ISO_9796_DS2({hash},{trailer:str=exp},{salt_len:int?})")) {
164 const auto trailer = m->str("trailer");
165 if(trailer != "imp" && trailer != "exp") {
166 throw Invalid_Argument(fmt("Unexpected parameters '{}' for signing with {}", params, algo));
167 }
168
169 auto opt = PK_Signature_Options()
170 .with_padding("ISO_9796_DS2")
171 .with_hash(m->str("hash"))
172 .with_explicit_trailer_field(trailer == "exp");
173
174 if(m->has("salt_len")) {
175 return std::move(opt).with_salt_size(m->integer("salt_len"));
176 }
177 return opt;
178 }
179
180 //ISO-9796-2 DS 3 is deterministic and DS2 without a salt
181 if(auto m = req.match("ISO_9796_DS3({hash},{trailer:str=exp})")) {
182 const auto trailer = m->str("trailer");
183 if(trailer != "imp" && trailer != "exp") {
184 throw Invalid_Argument(fmt("Unexpected parameters '{}' for signing with {}", params, algo));
185 }
186
187 return PK_Signature_Options()
188 .with_padding("ISO_9796_DS3")
189 .with_hash(m->str("hash"))
190 .with_explicit_trailer_field(trailer == "exp");
191 }
192
193 if(req.matches("X9.31(Raw)")) {
195 }
196
197 if(auto m = req.match("X9.31({hash})")) {
198 return PK_Signature_Options().with_padding("X9.31").with_hash(m->str("hash"));
199 }
200 } // RSA block
201
202 if(params.empty()) {
203 return PK_Signature_Options();
204 }
205
206 // ECDSA/DSA/ECKCDSA/etc
207
208 /*
209 * Stopgap until PK_Signature_Options is exposed through the FFI: a
210 * trailing ",Deterministic" (eg "SHA-256,Deterministic") requests a
211 * deterministic signature, so that RFC 6979 ECDSA remains reachable
212 * through the string based interfaces.
213 */
214 const std::string_view det_suffix = ",Deterministic";
215 const bool deterministic = params.ends_with(det_suffix);
216 const std::string_view hash_params = deterministic ? params.substr(0, params.size() - det_suffix.size()) : params;
217
218 // "Raw" or "Raw(hash)" means the caller provides the digest
219 if(hash_params.starts_with("Raw")) {
220 const AlgorithmSpec req(hash_params);
221 const auto m = req.match("Raw({hash?})");
222 if(!m) {
223 throw Invalid_Argument(fmt("Unexpected parameters '{}' for signing with {}", params, algo));
224 }
225 auto raw_opt = PK_Signature_Options().with_deterministic_signature(deterministic);
226 if(m->has("hash")) {
227 return std::move(raw_opt).with_externally_computed_prehash(std::string(m->str("hash")));
228 }
229 return std::move(raw_opt).with_externally_computed_prehash();
230 }
231
232 const auto hash = [&]() -> std::string {
233 if(hash_params.starts_with("EMSA1")) {
234 const AlgorithmSpec req(hash_params);
235 const auto m = req.match("EMSA1({hash})");
236 if(!m) {
237 throw Invalid_Argument(fmt("Unexpected parameters '{}' for signing with {}", params, algo));
238 }
239 return std::string(m->str("hash"));
240 } else {
241 return std::string(hash_params);
242 }
243 }();
244
245 return PK_Signature_Options().with_hash(hash).with_deterministic_signature(deterministic);
246}
247
248PK_Encryption_Options parse_legacy_enc_options(const Public_Key& key, std::string_view params) {
249 /*
250 * As with parse_legacy_sig_options, this handles the padding strings accepted
251 * prior to the introduction of PK_Encryption_Options.
252 */
253
254 if(key.algo_name() == "SM2") {
255 // The only parameter is the hash function, which defaults to SM3
256 return PK_Encryption_Options().with_hash(params);
257 }
258
259 /*
260 * Everything else (RSA, ElGamal, and the RSA implementations of the hardware
261 * providers) takes an EME specification:
262 *
263 * Raw
264 * PKCS1v15 (or the alias EME-PKCS1-v1_5)
265 * OAEP(hash), OAEP(hash,MGF1), OAEP(hash,MGF1,label), OAEP(hash,MGF1(mgf_hash)),
266 * OAEP(hash,MGF1(mgf_hash),label) (or the aliases EME-OAEP and EME1)
267 */
268
269 // TODO(Botan4) Remove all but "PKCS1v15"
270 if(params == "PKCS1v15" || params == "EME-PKCS1-v1_5") {
271 return PK_Encryption_Options().with_padding("PKCS1v15");
272 }
273
274 // Schemes which require a padding reject this when the operation is created
275 if(params.empty()) {
276 return PK_Encryption_Options();
277 }
278
279 // TODO(Botan4) Remove all but "OAEP" here
280 if(params.starts_with("OAEP") || params.starts_with("EME-OAEP") || params.starts_with("EME1")) {
281 const AlgorithmSpec req(params);
282
283 auto oaep_opt = PK_Encryption_Options().with_padding("OAEP");
284
285 if(auto m = req.match("OAEP|EME-OAEP|EME1({hash})")) {
286 return oaep_opt.with_hash(m->str("hash"));
287 }
288
289 if(auto m = req.match("OAEP|EME-OAEP|EME1({hash},MGF1,{label:str=})")) {
290 return oaep_opt.with_hash(m->str("hash")).with_context(m->str("label"));
291 }
292
293 if(auto m = req.match("OAEP|EME-OAEP|EME1({hash},MGF1({mgf_hash}),{label:str=})")) {
294 return oaep_opt.with_hash(m->str("hash")).with_mgf1_hash(m->str("mgf_hash")).with_context(m->str("label"));
295 }
296 }
297
298 // Anything else, including "Raw", is treated as the name of a padding scheme
299 return PK_Encryption_Options().with_padding(params);
300}
301
302PK_KEM_Options parse_legacy_kem_options(std::string_view params) {
303 // The string interface has always required naming a KDF (or "Raw")
304 if(params.empty()) {
305 throw Invalid_Argument("KEM requires specifying a KDF, or Raw to use the shared key directly");
306 } else if(params == "Raw") {
308 } else {
309 return PK_KEM_Options().with_kdf(params);
310 }
311}
312
314 // The string interface has always required naming a KDF (or "Raw")
315 if(params.empty()) {
316 throw Invalid_Argument("Key agreement requires specifying a KDF, or Raw to use the agreed value directly");
317 } else if(params == "Raw") {
319 } else {
320 return PK_Key_Agreement_Options().with_kdf(params);
321 }
322}
323
325 std::string_view algo_name,
326 std::string_view hash_fn) {
327 if(options.using_hash() && options.hash_function_name() != hash_fn) {
328 throw Invalid_Argument(
329 fmt("This {} key can only be used with {}, not {}", algo_name, hash_fn, options.hash_function_name()));
330 }
331}
332
333std::optional<std::string> externally_computed_prehash_name(const PK_Signature_Options_Reader& options) {
335
336 const auto& prehash = options.externally_computed_prehash_function();
337 const auto& hash = options.hash_function();
338
339 if(prehash.has_value() && hash.has_value() && *prehash != *hash) {
340 throw Invalid_Argument(
341 fmt("Externally computed prehash was named as {} but the hash option specified {}", *prehash, *hash));
342 }
343
344 return prehash.has_value() ? prehash : hash;
345}
346
350
351} // namespace Botan
#define BOTAN_UNUSED
Definition assert.h:151
#define BOTAN_STATE_CHECK(expr)
Definition assert.h:49
AlgorithmSpec with_head(std::string_view head) const
bool matches(const AlgorithmPattern &pattern) const
std::optional< AlgorithmMatch > match(const AlgorithmPattern &pattern) const &
std::string_view head() const
virtual std::string algo_name() const =0
PK_Encryption_Options with_padding(std::string_view padding)
PK_Encryption_Options with_hash(std::string_view hash)
PK_KEM_Options with_kdf(std::string_view kdf)
PK_KEM_Options with_raw_shared_key()
PK_Key_Agreement_Options with_kdf(std::string_view kdf)
PK_Key_Agreement_Options with_raw_shared_key()
const std::optional< std::string > & hash_function() const
const std::optional< std::string > & externally_computed_prehash_function() const
const std::string & hash_function_name() const
PK_Signature_Options with_explicit_trailer_field(bool trailer=true)
PK_Signature_Options with_deterministic_signature(bool deterministic=true)
PK_Signature_Options with_padding(std::string_view padding)
PK_Signature_Options with_hash(std::string_view hash)
PK_Signature_Options with_prehash(std::optional< std::string > prehash=std::nullopt)
PK_Signature_Options with_context(std::span< const uint8_t > context)
PK_Signature_Options with_externally_computed_prehash(std::optional< std::string > hash=std::nullopt)
PK_Encryption_Options parse_legacy_enc_options(const Public_Key &key, std::string_view params)
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53
void acknowledge_always_deterministic(const PK_Signature_Options_Reader &options)
PK_KEM_Options parse_legacy_kem_options(std::string_view params)
PK_Key_Agreement_Options parse_legacy_ka_options(std::string_view params)
void validate_for_hash_based_signature(const PK_Signature_Options_Reader &options, std::string_view algo_name, std::string_view hash_fn)
PK_Signature_Options parse_legacy_sig_options(const Public_Key &key, std::string_view params)
std::optional< std::string > externally_computed_prehash_name(const PK_Signature_Options_Reader &options)