Botan 3.14.1
Crypto and TLS for C&
p11_mechanism.cpp
Go to the documentation of this file.
1/*
2* PKCS#11 Mechanism
3* (C) 2016 Daniel Neus, Sirrix AG
4* (C) 2016 Philipp Weber, Sirrix AG
5*
6* Botan is released under the Simplified BSD License (see license.txt)
7*/
8
9#include <botan/p11_mechanism.h>
10
11#include <botan/pk_options.h>
12#include <botan/pk_options_readers.h>
13#include <botan/internal/algorithm_spec.h>
14#include <botan/internal/fmt.h>
15#include <botan/internal/parsing.h>
16#include <botan/internal/pk_options_impl.h>
17#include <tuple>
18
19namespace Botan::PKCS11 {
20
21namespace {
22using PKCS11_PSS_Params = std::tuple<size_t, MechanismType, MGF>;
23
24// maps a PSS mechanism type to the number of bytes used for the salt, the mechanism type of the underlying hash algorithm and the MGF
25const std::map<MechanismType, PKCS11_PSS_Params>& PssOptions() {
26 static const std::map<MechanismType, PKCS11_PSS_Params> pss_options = {
33
34 return pss_options;
35}
36
37class MechanismData {
38 public:
39 explicit MechanismData(MechanismType type) : m_type(type) {}
40
41 MechanismData(const MechanismData& other) = default;
42 MechanismData(MechanismData&& other) = default;
43
44 MechanismData& operator=(const MechanismData& other) = default;
45 MechanismData& operator=(MechanismData&& other) = default;
46
47 virtual ~MechanismData() = default;
48
49 MechanismType type() const { return m_type; }
50
51 private:
52 // the mechanism to perform
53 MechanismType m_type;
54};
55
56class RSA_SignMechanism final : public MechanismData {
57 public:
58 explicit RSA_SignMechanism(MechanismType typ) :
59 MechanismData(typ), m_hash(static_cast<MechanismType>(0)), m_mgf(MGF::MgfUnused), m_salt_size(0) {
60 const auto pss_option = PssOptions().find(type());
61 if(pss_option != PssOptions().end()) {
62 m_hash = std::get<1>(pss_option->second);
63 m_mgf = std::get<2>(pss_option->second);
64 m_salt_size = std::get<0>(pss_option->second);
65 }
66 }
67
68 MechanismType hash() const { return m_hash; }
69
70 MGF mgf() const { return m_mgf; }
71
72 size_t salt_size() const { return m_salt_size; }
73
74 private:
75 /*
76 hash algorithm used in the PSS encoding; if the signature
77 mechanism does not include message hashing, then this value must
78 be the mechanism used by the application to generate the message
79 hash; if the signature mechanism includes hashing, then this
80 value must match the hash algorithm indicated by the signature mechanism
81 */
82 MechanismType m_hash;
83
84 // mask generation function to use on the encoded block
85 MGF m_mgf;
86
87 // length, in bytes, of the salt value used in the PSS encoding; typical values are the length of the message hash and zero
88 size_t m_salt_size;
89};
90
91} // namespace
92
94 m_mechanism({static_cast<CK_MECHANISM_TYPE>(mechanism_type), nullptr, 0}), m_parameters(nullptr) {}
95
97 if(!options.using_padding()) {
98 throw Lookup_Error("PKCS#11 RSA encrypt/decrypt requires specifying a padding scheme");
99 }
100
101 const std::string& padding = options.padding().value();
102
103 if(padding == "Raw") {
105 mech.m_padding_size = 0;
106 return mech;
107 }
108
109 if(padding == "PKCS1v15") {
111 mech.m_padding_size = 11;
112 return mech;
113 }
114
115 if(padding == "OAEP") {
116 // note: when updating this map, update the documentation for `MechanismWrapper::create_rsa_crypt_mechanism`
117 struct OaepHash {
118 MechanismType hash;
119 MGF mgf;
120 size_t output_length;
121 };
122
123 static const std::map<std::string_view, OaepHash> OaepHashes = {
124 {"SHA-1", {MechanismType::Sha1, MGF::Mgf1Sha1, 20}},
125 {"SHA-224", {MechanismType::Sha224, MGF::Mgf1Sha224, 28}},
126 {"SHA-256", {MechanismType::Sha256, MGF::Mgf1Sha256, 32}},
127 {"SHA-384", {MechanismType::Sha384, MGF::Mgf1Sha384, 48}},
128 {"SHA-512", {MechanismType::Sha512, MGF::Mgf1Sha512, 64}},
129 };
130
131 if(!options.using_hash()) {
132 throw Lookup_Error("PKCS#11 RSA OAEP requires specifying a hash function");
133 }
134
135 const std::string& hash_name = options.hash_function_name();
136 const auto hash = OaepHashes.find(hash_name);
137 if(hash == OaepHashes.end()) {
138 throw Lookup_Error(fmt("PKCS#11 RSA OAEP does not support hash function '{}'", hash_name));
139 }
140
141 MGF mgf = hash->second.mgf;
142 if(options.using_mgf1_hash()) {
143 const std::string mgf1_hash_name = options.mgf1_hash_function().value();
144 const auto mgf1_hash = OaepHashes.find(mgf1_hash_name);
145 if(mgf1_hash == OaepHashes.end()) {
146 throw Lookup_Error(fmt("PKCS#11 RSA OAEP does not support MGF1 hash function '{}'", mgf1_hash_name));
147 }
148 mgf = mgf1_hash->second.mgf;
149 }
150
152 mech.m_parameters = std::make_shared<MechanismParameters>();
153 mech.m_parameters->oaep_params.hashAlg = static_cast<CK_MECHANISM_TYPE>(hash->second.hash);
154 mech.m_parameters->oaep_params.mgf = static_cast<CK_RSA_PKCS_MGF_TYPE>(mgf);
155 mech.m_parameters->oaep_params.source = CKZ_DATA_SPECIFIED;
156
157 if(const auto& label = options.context(); label.has_value() && !label->empty()) {
158 mech.m_oaep_label = std::make_shared<const std::vector<uint8_t>>(*label);
159 mech.m_parameters->oaep_params.pSourceData = const_cast<uint8_t*>(mech.m_oaep_label->data());
160 mech.m_parameters->oaep_params.ulSourceDataLen = checked_ulong_cast(mech.m_oaep_label->size());
161 } else {
162 mech.m_parameters->oaep_params.pSourceData = nullptr;
163 mech.m_parameters->oaep_params.ulSourceDataLen = 0;
164 }
165
166 mech.m_mechanism.pParameter = mech.m_parameters.get();
167 mech.m_mechanism.ulParameterLen = sizeof(RsaPkcsOaepParams);
168 mech.m_padding_size = 2 + 2 * hash->second.output_length;
169 return mech;
170 }
171
172 throw Lookup_Error(fmt("PKCS#11 RSA encrypt/decrypt does not support padding with '{}'", padding));
173}
174
176 // note: when updating this map, update the documentation for `MechanismWrapper::create_rsa_sign_mechanism`
177 static const std::map<std::string_view, RSA_SignMechanism> SignMechanisms = {
178 {"Raw", RSA_SignMechanism(MechanismType::RsaX509)},
179
180 // X9.31
181 {"X9.31(Raw)", RSA_SignMechanism(MechanismType::RsaX931)},
182 {"X9.31(SHA-1)", RSA_SignMechanism(MechanismType::Sha1RsaX931)},
183
184 // RSASSA PKCS#1 v1.5
185 {"PKCS1v15(Raw)", RSA_SignMechanism(MechanismType::RsaPkcs)},
186 {"PKCS1v15(SHA-1)", RSA_SignMechanism(MechanismType::Sha1RsaPkcs)},
187 {"PKCS1v15(SHA-224)", RSA_SignMechanism(MechanismType::Sha224RsaPkcs)},
188 {"PKCS1v15(SHA-256)", RSA_SignMechanism(MechanismType::Sha256RsaPkcs)},
189 {"PKCS1v15(SHA-384)", RSA_SignMechanism(MechanismType::Sha384RsaPkcs)},
190 {"PKCS1v15(SHA-512)", RSA_SignMechanism(MechanismType::Sha512RsaPkcs)},
191
192 // PSS PKCS#1 v2.0
193 {"PSS(Raw)", RSA_SignMechanism(MechanismType::RsaPkcsPss)},
194
195 {"PSS(SHA-1)", RSA_SignMechanism(MechanismType::Sha1RsaPkcsPss)},
196 {"PSS(SHA-1,MGF1,20)", RSA_SignMechanism(MechanismType::Sha1RsaPkcsPss)},
197
198 {"PSS(SHA-224)", RSA_SignMechanism(MechanismType::Sha224RsaPkcsPss)},
199 {"PSS(SHA-224,MGF1,28)", RSA_SignMechanism(MechanismType::Sha224RsaPkcsPss)},
200
201 {"PSS(SHA-256)", RSA_SignMechanism(MechanismType::Sha256RsaPkcsPss)},
202 {"PSS(SHA-256,MGF1,32)", RSA_SignMechanism(MechanismType::Sha256RsaPkcsPss)},
203
204 {"PSS(SHA-384)", RSA_SignMechanism(MechanismType::Sha384RsaPkcsPss)},
205 {"PSS(SHA-384,MGF1,48)", RSA_SignMechanism(MechanismType::Sha384RsaPkcsPss)},
206
207 {"PSS(SHA-512)", RSA_SignMechanism(MechanismType::Sha512RsaPkcsPss)},
208 {"PSS(SHA-512,MGF1,64)", RSA_SignMechanism(MechanismType::Sha512RsaPkcsPss)},
209
210 // ISO 9796 - this is the obsolete and insecure DS1 scheme, not the PSS-based DS2/DS3
211 // TODO(Botan4) remove this
212 {"ISO9796", RSA_SignMechanism(MechanismType::Rsa9796)},
213
214 // Deprecated aliases
215 // TODO(Botan4) remove these
216 {"EMSA2(Raw)", RSA_SignMechanism(MechanismType::RsaX931)},
217 {"EMSA2(SHA-1)", RSA_SignMechanism(MechanismType::Sha1RsaX931)},
218
219 {"EMSA3(Raw)", RSA_SignMechanism(MechanismType::RsaPkcs)},
220 {"EMSA3(SHA-1)", RSA_SignMechanism(MechanismType::Sha1RsaPkcs)},
221 {"EMSA3(SHA-224)", RSA_SignMechanism(MechanismType::Sha224RsaPkcs)},
222 {"EMSA3(SHA-256)", RSA_SignMechanism(MechanismType::Sha256RsaPkcs)},
223 {"EMSA3(SHA-384)", RSA_SignMechanism(MechanismType::Sha384RsaPkcs)},
224 {"EMSA3(SHA-512)", RSA_SignMechanism(MechanismType::Sha512RsaPkcs)},
225
226 {"EMSA_PKCS1(SHA-1)", RSA_SignMechanism(MechanismType::Sha1RsaPkcs)},
227 {"EMSA_PKCS1(SHA-224)", RSA_SignMechanism(MechanismType::Sha224RsaPkcs)},
228 {"EMSA_PKCS1(SHA-256)", RSA_SignMechanism(MechanismType::Sha256RsaPkcs)},
229 {"EMSA_PKCS1(SHA-384)", RSA_SignMechanism(MechanismType::Sha384RsaPkcs)},
230 {"EMSA_PKCS1(SHA-512)", RSA_SignMechanism(MechanismType::Sha512RsaPkcs)},
231
232 {"EMSA4(Raw)", RSA_SignMechanism(MechanismType::RsaPkcsPss)},
233 {"EMSA4(SHA-1)", RSA_SignMechanism(MechanismType::Sha1RsaPkcsPss)},
234 {"EMSA4(SHA-224)", RSA_SignMechanism(MechanismType::Sha224RsaPkcsPss)},
235
236 {"EMSA4(SHA-256)", RSA_SignMechanism(MechanismType::Sha256RsaPkcsPss)},
237 {"EMSA4(SHA-256,MGF1,32)", RSA_SignMechanism(MechanismType::Sha256RsaPkcsPss)},
238 {"PSSR(SHA-256,MGF1,32)", RSA_SignMechanism(MechanismType::Sha256RsaPkcsPss)},
239
240 {"EMSA4(SHA-384)", RSA_SignMechanism(MechanismType::Sha384RsaPkcsPss)},
241 {"EMSA4(SHA-384,MGF1,48)", RSA_SignMechanism(MechanismType::Sha384RsaPkcsPss)},
242 {"PSSR(SHA-384,MGF1,48)", RSA_SignMechanism(MechanismType::Sha384RsaPkcsPss)},
243
244 {"EMSA4(SHA-512)", RSA_SignMechanism(MechanismType::Sha512RsaPkcsPss)},
245 {"EMSA4(SHA-512,MGF1,64)", RSA_SignMechanism(MechanismType::Sha512RsaPkcsPss)},
246 {"PSSR(SHA-512,MGF1,64)", RSA_SignMechanism(MechanismType::Sha512RsaPkcsPss)},
247 };
248
249 const std::string padding = [&]() {
250 if(!options.using_padding()) {
251 throw Invalid_Argument("PKCS#11 RSA signature requires a padding scheme");
252 }
253
254 const std::string scheme = options.padding().value();
255
257 // The token pads the digest as given, so it cannot add a DigestInfo for a named hash
258 if(auto prehash = externally_computed_prehash_name(options)) {
259 throw Not_Implemented(fmt("PKCS#11 RSA {} signing of an externally computed {} prehash", scheme, *prehash));
260 }
261 return (scheme == "Raw") ? scheme : fmt("{}(Raw)", scheme);
262 }
263
264 if(options.using_hash()) {
265 if(options.using_salt_size()) {
266 return fmt("{}({},MGF1,{})", scheme, options.hash_function_name(), options.salt_size().value());
267 }
268 return fmt("{}({})", scheme, options.hash_function_name());
269 }
270
271 return scheme; // NOLINT(*-no-automatic-move)
272 }();
273
274 const auto mechanism_info_it = SignMechanisms.find(padding);
275 if(mechanism_info_it == SignMechanisms.end()) {
276 // at this point it would be possible to support additional configurations that are not predefined above by parsing `padding`
277 throw Lookup_Error(fmt("PKCS#11 RSA sign/verify does not support padding with '{}'", padding));
278 }
279 const RSA_SignMechanism mechanism_info = mechanism_info_it->second;
280
281 // Only PSS is randomized; the token generates the salt itself
282 if(options.using_deterministic_signature() && PssOptions().contains(mechanism_info.type())) {
283 throw Invalid_Argument(fmt("PKCS#11 RSA signing with {} cannot produce deterministic signatures", padding));
284 }
285
286 MechanismWrapper mech(mechanism_info.type());
287 if(PssOptions().contains(mechanism_info.type())) {
288 mech.m_parameters = std::make_shared<MechanismParameters>();
289 mech.m_parameters->pss_params.hashAlg = static_cast<CK_MECHANISM_TYPE>(mechanism_info.hash());
290 mech.m_parameters->pss_params.mgf = static_cast<CK_RSA_PKCS_MGF_TYPE>(mechanism_info.mgf());
291 mech.m_parameters->pss_params.sLen = checked_ulong_cast(mechanism_info.salt_size());
292 mech.m_mechanism.pParameter = mech.m_parameters.get();
293 mech.m_mechanism.ulParameterLen = sizeof(RsaPkcsPssParams);
294 }
295 return mech;
296}
297
299 // note: when updating this map, update the documentation for `MechanismWrapper::create_ecdsa_mechanism`
300 static const std::map<std::string_view, MechanismType> EcdsaHash = {{"Raw", MechanismType::Ecdsa},
301 {"SHA-1", MechanismType::EcdsaSha1},
302 {"SHA-224", MechanismType::EcdsaSha224},
303 {"SHA-256", MechanismType::EcdsaSha256},
304 {"SHA-384", MechanismType::EcdsaSha384},
305 {"SHA-512", MechanismType::EcdsaSha512}};
306
307 const std::string hash_spec(hash_spec_view);
308 auto mechanism = EcdsaHash.find(hash_spec);
309 if(mechanism != EcdsaHash.end()) {
310 return MechanismWrapper(mechanism->second);
311 }
312
313 const AlgorithmSpec req(hash_spec);
314
315 if(auto m = req.match("EMSA1({hash})")) {
316 mechanism = EcdsaHash.find(m->str("hash"));
317 if(mechanism != EcdsaHash.end()) {
318 return MechanismWrapper(mechanism->second);
319 }
320 }
321
322 throw Lookup_Error(fmt("PKCS #11 ECDSA sign/verify does not support {}", hash_spec));
323}
324
326 // note: when updating this map, update the documentation for `MechanismWrapper::create_ecdh_mechanism`
327 static const std::map<std::string_view, KeyDerivation> EcdhHash = {{"Raw", KeyDerivation::Null},
328 {"SHA-1", KeyDerivation::Sha1Kdf},
329 {"SHA-224", KeyDerivation::Sha224Kdf},
330 {"SHA-256", KeyDerivation::Sha256Kdf},
331 {"SHA-384", KeyDerivation::Sha384Kdf},
332 {"SHA-512", KeyDerivation::Sha512Kdf}};
333
334 const std::vector<std::string> param_parts = split_on(params, ',');
335
336 if(param_parts.empty() || param_parts.size() > 2) {
337 throw Invalid_Argument(fmt("PKCS #11 ECDH key derivation bad params {}", params));
338 }
339
340 // TODO(Botan4) remove this cofactor nonsense
341 bool use_cofactor = false;
342 std::string kdf_name;
343 for(const auto& part : param_parts) {
344 if(part == "Cofactor") {
345 if(use_cofactor) {
346 throw Invalid_Argument(fmt("PKCS #11 ECDH key derivation bad params {}", params));
347 }
348 use_cofactor = true;
349 } else {
350 if(!kdf_name.empty()) {
351 throw Invalid_Argument(fmt("PKCS #11 ECDH key derivation bad params {}", params));
352 }
353 kdf_name = part;
354 }
355 }
356
357 if(kdf_name.empty()) {
358 throw Invalid_Argument(fmt("PKCS #11 ECDH key derivation bad params {}", params));
359 }
360
361 const auto kdf = EcdhHash.find(kdf_name);
362 if(kdf == EcdhHash.end()) {
363 throw Lookup_Error("PKCS#11 ECDH key derivation does not support KDF " + kdf_name);
364 }
366 mech.m_parameters = std::make_shared<MechanismParameters>();
367 mech.m_parameters->ecdh_params.kdf = static_cast<CK_EC_KDF_TYPE>(kdf->second);
368 mech.m_mechanism.pParameter = mech.m_parameters.get();
369 mech.m_mechanism.ulParameterLen = sizeof(Ecdh1DeriveParams);
370 return mech;
371}
372
373} // namespace Botan::PKCS11
std::optional< AlgorithmMatch > match(const AlgorithmPattern &pattern) const &
static MechanismWrapper create_rsa_sign_mechanism(const PK_Signature_Options_Reader &options)
static MechanismWrapper create_ecdh_mechanism(std::string_view params)
MechanismType mechanism_type() const
static MechanismWrapper create_ecdsa_mechanism(std::string_view hash)
MechanismWrapper(MechanismType mechanism_type)
static MechanismWrapper create_rsa_crypt_mechanism(const PK_Encryption_Options_Reader &options)
const std::optional< std::vector< uint8_t > > & context() const
const std::optional< std::string > & padding() const
const std::optional< std::string > & mgf1_hash_function() const
const std::string & hash_function_name() const
const std::optional< std::string > & padding() const
const std::string & hash_function_name() const
const std::optional< size_t > & salt_size() const
CK_RSA_PKCS_OAEP_PARAMS RsaPkcsOaepParams
Definition p11.h:1216
Ulong checked_ulong_cast(size_t v)
Definition p11.h:1228
CK_ECDH1_DERIVE_PARAMS Ecdh1DeriveParams
Definition p11.h:1218
CK_RSA_PKCS_PSS_PARAMS RsaPkcsPssParams
Definition p11.h:1217
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)
CK_ULONG CK_EC_KDF_TYPE
Definition pkcs11.h:47
#define CKZ_DATA_SPECIFIED
Definition pkcs11.h:1229
CK_ULONG CK_RSA_PKCS_MGF_TYPE
Definition pkcs11.h:71
CK_ULONG CK_MECHANISM_TYPE
Definition pkcs11.h:59
CK_ULONG ulParameterLen
Definition pkcs11.h:1314
void * pParameter
Definition pkcs11.h:1313