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