Botan 3.7.1
Crypto and TLS for C&
eckcdsa.cpp
Go to the documentation of this file.
1/*
2* ECKCDSA (ISO/IEC 14888-3:2006/Cor.2:2009)
3* (C) 2016 René Korthaus, Sirrix AG
4* (C) 2018,2024 Jack Lloyd
5* (C) 2023 Philippe Lieser - Rohde & Schwarz Cybersecurity
6*
7* Botan is released under the Simplified BSD License (see license.txt)
8*/
9
10#include <botan/eckcdsa.h>
11
12#include <botan/hash.h>
13#include <botan/rng.h>
14#include <botan/internal/fmt.h>
15#include <botan/internal/keypair.h>
16#include <botan/internal/parsing.h>
17#include <botan/internal/pk_ops_impl.h>
18#include <botan/internal/scan_name.h>
19#include <botan/internal/stl_util.h>
20
21namespace Botan {
22
23std::unique_ptr<Public_Key> ECKCDSA_PrivateKey::public_key() const {
24 return std::make_unique<ECKCDSA_PublicKey>(domain(), _public_ec_point());
25}
26
28 if(!EC_PrivateKey::check_key(rng, strong)) {
29 return false;
30 }
31
32 if(!strong) {
33 return true;
34 }
35
36 return KeyPair::signature_consistency_check(rng, *this, "SHA-256");
37}
38
39namespace {
40
41std::unique_ptr<HashFunction> eckcdsa_signature_hash(std::string_view padding) {
42 if(auto hash = HashFunction::create(padding)) {
43 return hash;
44 }
45
46 SCAN_Name req(padding);
47
48 if(req.algo_name() == "EMSA1" && req.arg_count() == 1) {
49 if(auto hash = HashFunction::create(req.arg(0))) {
50 return hash;
51 }
52 }
53
54 // intentionally not supporting Raw for ECKCDSA, we need to know
55 // the length in advance which complicates the logic for Raw
56
57 throw Algorithm_Not_Found(padding);
58}
59
60std::unique_ptr<HashFunction> eckcdsa_signature_hash(const AlgorithmIdentifier& alg_id) {
61 const auto oid_info = split_on(alg_id.oid().to_formatted_string(), '/');
62
63 if(oid_info.size() != 2 || oid_info[0] != "ECKCDSA") {
64 throw Decoding_Error(fmt("Unexpected AlgorithmIdentifier OID {} in association with ECKCDSA key", alg_id.oid()));
65 }
66
67 if(!alg_id.parameters_are_empty()) {
68 throw Decoding_Error("Unexpected non-empty AlgorithmIdentifier parameters for ECKCDSA");
69 }
70
71 return HashFunction::create_or_throw(oid_info[1]);
72}
73
74std::vector<uint8_t> eckcdsa_prefix(const EC_AffinePoint& point, size_t hash_block_size) {
75 auto prefix = point.xy_bytes<std::vector<uint8_t>>();
76
77 // Either truncate or zero-extend to match the hash block size
78 prefix.resize(hash_block_size);
79
80 return prefix;
81}
82
83/**
84 * @brief Truncate hash output if needed.
85 *
86 * If the output length of the hash function exceeds the size of the group order,
87 * ISO/IEC 14888-3:2018 specifies a truncation of the hash output
88 * when calculating the witness R (the first part of the signature) and H.
89 *
90 * The truncation is specified as follows:
91 *
92 * R = I2BS(beta', BS2I(gamma, R) mod 2^beta')
93 * H = I2BS(beta', BS2I(gamma, H) mod 2^beta')
94 *
95 * where
96 * - gamma: the output bit-length of the hash-function
97 * - beta: the bit-length of the prime number q (i.e. the group order size)
98 * - beta' = 8 * ceil(beta / 8)
99 *
100 * This essentially means a truncation on the byte level
101 * happens from the low side of the hash.
102 *
103 * @param[in,out] digest The hash output to potentially truncate.
104 * @param[in] group_order_bytes Size of the group order.
105 */
106void truncate_hash_if_needed(std::vector<uint8_t>& digest, size_t group_order_bytes) {
107 if(digest.size() > group_order_bytes) {
108 const size_t bytes_to_truncate = digest.size() - group_order_bytes;
109 digest.erase(digest.begin(), digest.begin() + bytes_to_truncate);
110 }
111}
112
113/**
114* ECKCDSA signature operation
115*/
116class ECKCDSA_Signature_Operation final : public PK_Ops::Signature {
117 public:
118 ECKCDSA_Signature_Operation(const ECKCDSA_PrivateKey& eckcdsa, std::string_view padding) :
119 m_group(eckcdsa.domain()),
120 m_x(eckcdsa._private_key()),
121 m_hash(eckcdsa_signature_hash(padding)),
122 m_prefix(eckcdsa_prefix(eckcdsa._public_ec_point(), m_hash->hash_block_size())),
123 m_prefix_used(false) {}
124
125 void update(std::span<const uint8_t> input) override {
126 if(!m_prefix_used) {
127 m_hash->update(m_prefix);
128 m_prefix_used = true;
129 }
130 m_hash->update(input);
131 }
132
133 std::vector<uint8_t> sign(RandomNumberGenerator& rng) override {
134 m_prefix_used = false;
135 std::vector<uint8_t> digest = m_hash->final_stdvec();
136 truncate_hash_if_needed(digest, m_group.get_order_bytes());
137 return raw_sign(digest, rng);
138 }
139
140 size_t signature_length() const override { return 2 * m_group.get_order_bytes(); }
141
142 AlgorithmIdentifier algorithm_identifier() const override;
143
144 std::string hash_function() const override { return m_hash->name(); }
145
146 private:
147 std::vector<uint8_t> raw_sign(std::span<const uint8_t> msg, RandomNumberGenerator& rng);
148
149 const EC_Group m_group;
150 const EC_Scalar m_x;
151 std::unique_ptr<HashFunction> m_hash;
152 std::vector<uint8_t> m_prefix;
153 std::vector<BigInt> m_ws;
154 bool m_prefix_used;
155};
156
157AlgorithmIdentifier ECKCDSA_Signature_Operation::algorithm_identifier() const {
158 const std::string full_name = "ECKCDSA/" + m_hash->name();
159 const OID oid = OID::from_string(full_name);
160 return AlgorithmIdentifier(oid, AlgorithmIdentifier::USE_EMPTY_PARAM);
161}
162
163std::vector<uint8_t> ECKCDSA_Signature_Operation::raw_sign(std::span<const uint8_t> msg, RandomNumberGenerator& rng) {
164 const auto k = EC_Scalar::random(m_group, rng);
165
166 // We cannot use gk_x_mod_order because ECKCDSA, unlike ECDSA or ECGDSA, does
167 // not reduce the x coordinate modulo the group order.
168 m_hash->update(EC_AffinePoint::g_mul(k, rng, m_ws).x_bytes());
169 auto c = m_hash->final_stdvec();
170 truncate_hash_if_needed(c, m_group.get_order_bytes());
171
172 const auto r = c;
173
174 xor_buf(c, msg);
175 const auto w = EC_Scalar::from_bytes_mod_order(m_group, c);
176
177 const auto s = m_x * (k - w);
178 if(s.is_zero()) {
179 throw Internal_Error("During ECKCDSA signature generation created zero s");
180 }
181
182 return concat(r, s.serialize());
183}
184
185/**
186* ECKCDSA verification operation
187*/
188class ECKCDSA_Verification_Operation final : public PK_Ops::Verification {
189 public:
190 ECKCDSA_Verification_Operation(const ECKCDSA_PublicKey& eckcdsa, std::string_view padding) :
191 m_group(eckcdsa.domain()),
192 m_gy_mul(eckcdsa._public_ec_point()),
193 m_hash(eckcdsa_signature_hash(padding)),
194 m_prefix(eckcdsa_prefix(eckcdsa._public_ec_point(), m_hash->hash_block_size())),
195 m_prefix_used(false) {}
196
197 ECKCDSA_Verification_Operation(const ECKCDSA_PublicKey& eckcdsa, const AlgorithmIdentifier& alg_id) :
198 m_group(eckcdsa.domain()),
199 m_gy_mul(eckcdsa._public_ec_point()),
200 m_hash(eckcdsa_signature_hash(alg_id)),
201 m_prefix(eckcdsa_prefix(eckcdsa._public_ec_point(), m_hash->hash_block_size())),
202 m_prefix_used(false) {}
203
204 void update(std::span<const uint8_t> msg) override;
205
206 bool is_valid_signature(std::span<const uint8_t> sig) override;
207
208 std::string hash_function() const override { return m_hash->name(); }
209
210 private:
211 bool verify(std::span<const uint8_t> msg, std::span<const uint8_t> sig);
212
213 const EC_Group m_group;
214 const EC_Group::Mul2Table m_gy_mul;
215 std::unique_ptr<HashFunction> m_hash;
216 std::vector<uint8_t> m_prefix;
217 bool m_prefix_used;
218};
219
220void ECKCDSA_Verification_Operation::update(std::span<const uint8_t> msg) {
221 if(!m_prefix_used) {
222 m_prefix_used = true;
223 m_hash->update(m_prefix.data(), m_prefix.size());
224 }
225 m_hash->update(msg);
226}
227
228bool ECKCDSA_Verification_Operation::is_valid_signature(std::span<const uint8_t> sig) {
229 m_prefix_used = false;
230 std::vector<uint8_t> digest = m_hash->final_stdvec();
231 truncate_hash_if_needed(digest, m_group.get_order_bytes());
232 return verify(digest, sig);
233}
234
235bool ECKCDSA_Verification_Operation::verify(std::span<const uint8_t> msg, std::span<const uint8_t> sig) {
236 const size_t order_bytes = m_group.get_order_bytes();
237
238 const size_t size_r = std::min(msg.size(), order_bytes);
239 if(sig.size() != size_r + order_bytes) {
240 return false;
241 }
242
243 auto r = sig.first(size_r);
244
245 if(auto s = EC_Scalar::deserialize(m_group, sig.last(order_bytes))) {
246 std::vector<uint8_t> r_xor_e(r.size());
247 xor_buf(r_xor_e, r, msg.first(size_r));
248
249 const auto w = EC_Scalar::from_bytes_mod_order(m_group, r_xor_e);
250
251 if(auto q = m_gy_mul.mul2_vartime(w, s.value())) {
252 std::vector<uint8_t> v = m_hash->process<std::vector<uint8_t>>(q->x_bytes());
253 truncate_hash_if_needed(v, m_group.get_order_bytes());
254 return constant_time_compare(v, r);
255 }
256 }
257
258 return false;
259}
260
261} // namespace
262
263std::unique_ptr<Private_Key> ECKCDSA_PublicKey::generate_another(RandomNumberGenerator& rng) const {
264 return std::make_unique<ECKCDSA_PrivateKey>(rng, domain());
265}
266
267std::unique_ptr<PK_Ops::Verification> ECKCDSA_PublicKey::create_verification_op(std::string_view params,
268 std::string_view provider) const {
269 if(provider == "base" || provider.empty()) {
270 return std::make_unique<ECKCDSA_Verification_Operation>(*this, params);
271 }
272 throw Provider_Not_Found(algo_name(), provider);
273}
274
275std::unique_ptr<PK_Ops::Verification> ECKCDSA_PublicKey::create_x509_verification_op(
276 const AlgorithmIdentifier& signature_algorithm, std::string_view provider) const {
277 if(provider == "base" || provider.empty()) {
278 return std::make_unique<ECKCDSA_Verification_Operation>(*this, signature_algorithm);
279 }
280
281 throw Provider_Not_Found(algo_name(), provider);
282}
283
284std::unique_ptr<PK_Ops::Signature> ECKCDSA_PrivateKey::create_signature_op(RandomNumberGenerator& /*rng*/,
285 std::string_view params,
286 std::string_view provider) const {
287 if(provider == "base" || provider.empty()) {
288 return std::make_unique<ECKCDSA_Signature_Operation>(*this, params);
289 }
290 throw Provider_Not_Found(algo_name(), provider);
291}
292
293} // namespace Botan
std::unique_ptr< PK_Ops::Signature > create_signature_op(RandomNumberGenerator &rng, std::string_view params, std::string_view provider) const override
Definition eckcdsa.cpp:284
std::unique_ptr< Public_Key > public_key() const override
Definition eckcdsa.cpp:23
bool check_key(RandomNumberGenerator &rng, bool) const override
Definition eckcdsa.cpp:27
std::unique_ptr< PK_Ops::Verification > create_x509_verification_op(const AlgorithmIdentifier &signature_algorithm, std::string_view provider) const override
Definition eckcdsa.cpp:275
std::unique_ptr< PK_Ops::Verification > create_verification_op(std::string_view params, std::string_view provider) const override
Definition eckcdsa.cpp:267
std::unique_ptr< Private_Key > generate_another(RandomNumberGenerator &rng) const final
Definition eckcdsa.cpp:263
std::optional< EC_AffinePoint > mul2_vartime(const EC_Scalar &x, const EC_Scalar &y) const
Definition ec_group.cpp:734
size_t get_order_bytes() const
Definition ec_group.cpp:510
bool check_key(RandomNumberGenerator &rng, bool strong) const override
Definition ecc_key.cpp:200
const EC_Group & domain() const
Definition ecc_key.cpp:63
const EC_AffinePoint & _public_ec_point() const
Definition ecc_key.cpp:75
static std::unique_ptr< HashFunction > create_or_throw(std::string_view algo_spec, std::string_view provider="")
Definition hash.cpp:298
static std::unique_ptr< HashFunction > create(std::string_view algo_spec, std::string_view provider="")
Definition hash.cpp:107
int(* update)(CTX *, const void *, CC_LONG len)
int(* final)(unsigned char *, CTX *)
bool signature_consistency_check(RandomNumberGenerator &rng, const Private_Key &private_key, const Public_Key &public_key, std::string_view padding)
Definition keypair.cpp:49
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:111
constexpr auto concat(Rs &&... ranges)
Definition stl_util.h:263
constexpr void xor_buf(ranges::contiguous_output_range< uint8_t > auto &&out, ranges::contiguous_range< uint8_t > auto &&in)
Definition mem_ops.h:342
bool constant_time_compare(std::span< const uint8_t > x, std::span< const uint8_t > y)
Definition mem_ops.cpp:17