Botan 3.14.1
Crypto and TLS for C&
x25519.cpp
Go to the documentation of this file.
1/*
2* X25519
3* (C) 2014,2024 Jack Lloyd
4*
5* Botan is released under the Simplified BSD License (see license.txt)
6*/
7
8#include <botan/x25519.h>
9
10#include <botan/ber_dec.h>
11#include <botan/der_enc.h>
12#include <botan/rng.h>
13#include <botan/internal/ct_utils.h>
14#include <botan/internal/fmt.h>
15#include <botan/internal/pk_ops_impl.h>
16#include <botan/internal/pk_options_impl.h>
17#include <botan/internal/x25519_internal.h>
18#include <array>
19
20namespace Botan {
21
22class X25519_PublicKey_Data final {
23 public:
24 explicit X25519_PublicKey_Data(std::vector<uint8_t> key) : m_key(std::move(key)) {}
25
26 const std::vector<uint8_t>& key() const { return m_key; }
27
28 private:
29 std::vector<uint8_t> m_key;
30};
31
32class X25519_PrivateKey_Data final {
33 public:
34 explicit X25519_PrivateKey_Data(secure_vector<uint8_t> key) : m_key(std::move(key)) {}
35
36 const secure_vector<uint8_t>& key() const { return m_key; }
37
38 private:
40};
41
43 return m_private->key();
44}
45
47 return m_private->key();
48}
49
50namespace {
51
52void size_check(size_t size, const char* thing) {
53 if(size != 32) {
54 throw Decoding_Error(fmt("Invalid size {} for X25519 {}", size, thing));
55 }
56}
57
58// X25519 agreement, shared by agree() and the PK_Key_Agreement operation
59secure_vector<uint8_t> x25519_agree(const secure_vector<uint8_t>& secret, const uint8_t pubval[32]) {
60 BOTAN_ASSERT_NOMSG(secret.size() == 32);
61 const auto scope = CT::scoped_poison(secret);
62 secure_vector<uint8_t> shared_key(32);
63 x25519_scalarmult(std::span<uint8_t, 32>(shared_key.data(), 32),
64 std::span<const uint8_t, 32>(secret.data(), 32),
65 std::span<const uint8_t, 32>(pubval, 32));
66
67 // RFC 7748 Section 6.1
68 // Both [parties] MAY check, without leaking extra information about
69 // the value of K, whether K is the all-zero value and abort if so.
70 //
71 // TODO: once the generic Key Agreement operation creation is equipped
72 // with a more flexible parameterization, this check could be
73 // made optional.
74 // For instance: `sk->agree().with_optional_sanity_checks(true)`.
75 // See also: https://github.com/randombit/botan/pull/4318
76 if(CT::all_zeros(shared_key.data(), shared_key.size()).as_bool()) {
77 throw Invalid_Argument("X25519 public point appears to be of low order");
78 }
79
80 // Any further secret handling of the output is up to the caller
81 CT::unpoison(shared_key);
82 return shared_key;
83}
84
85// Given a 32-byte secret key compute the public value and build the immutable
86// public and private key data objects.
87void load_x25519_keypair(secure_vector<uint8_t> secret,
88 std::shared_ptr<const X25519_PublicKey_Data>& pk_out,
89 std::shared_ptr<const X25519_PrivateKey_Data>& sk_out) {
90 BOTAN_ASSERT_NOMSG(secret.size() == 32);
91 std::vector<uint8_t> pub(32);
92 {
93 const auto scope = CT::scoped_poison(secret);
94 x25519_basepoint(std::span<uint8_t, 32>(pub.data(), 32), std::span<const uint8_t, 32>(secret.data(), 32));
95 CT::unpoison(pub);
96 }
97 pk_out = std::make_shared<const X25519_PublicKey_Data>(std::move(pub));
98 sk_out = std::make_shared<const X25519_PrivateKey_Data>(std::move(secret));
99}
100
101} // namespace
102
106
107bool X25519_PublicKey::check_key(RandomNumberGenerator& /*rng*/, bool /*strong*/) const {
108 /*
109 * Every clamped scalar is a multiple of the cofactor, so multiplying by one
110 * sends exactly the points of low order to the identity (all zero output).
111 * Nothing else can be checked for a Montgomery u-coordinate.
112 */
113 const std::array<uint8_t, 32> scalar{}; // clamped to 2^254 by x25519_scalarmult
114 std::array<uint8_t, 32> out{};
115 x25519_scalarmult(out, scalar, std::span<const uint8_t, 32>(m_public->key().data(), 32));
116 return !CT::all_zeros(out.data(), out.size()).as_bool();
117}
118
119X25519_PublicKey::X25519_PublicKey(const AlgorithmIdentifier& alg_id, std::span<const uint8_t> key_bits) :
120 X25519_PublicKey(key_bits) {
121 // RFC 8410 Section 3: "the parameters MUST be absent".
122 if(!alg_id.parameters_are_empty()) {
123 throw Decoding_Error("Unexpected parameters for X25519 public key");
124 }
125}
126
127X25519_PublicKey::X25519_PublicKey(std::span<const uint8_t> pub) {
128 size_check(pub.size(), "public key");
129 m_public = std::make_shared<const X25519_PublicKey_Data>(std::vector<uint8_t>(pub.begin(), pub.end()));
130}
131
132std::vector<uint8_t> X25519_PublicKey::raw_public_key_bits() const {
133 return m_public->key();
134}
135
136std::vector<uint8_t> X25519_PublicKey::public_key_bits() const {
137 return raw_public_key_bits();
138}
139
140std::unique_ptr<Private_Key> X25519_PublicKey::generate_another(RandomNumberGenerator& rng) const {
141 return std::make_unique<X25519_PrivateKey>(rng);
142}
143
144X25519_PrivateKey::X25519_PrivateKey(std::span<const uint8_t> secret_key) {
145 if(secret_key.size() != 32) {
146 throw Decoding_Error("Invalid size for X25519 private key");
147 }
148
149 load_x25519_keypair(secure_vector<uint8_t>(secret_key.begin(), secret_key.end()), m_public, m_private);
150}
151
153 load_x25519_keypair(rng.random_vec(32), m_public, m_private);
154}
155
156X25519_PrivateKey::X25519_PrivateKey(const AlgorithmIdentifier& alg_id, std::span<const uint8_t> key_bits) {
157 // RFC 8410 Section 3: "the parameters MUST be absent".
158 if(!alg_id.parameters_are_empty()) {
159 throw Decoding_Error("Unexpected parameters for X25519 private key");
160 }
161
162 secure_vector<uint8_t> secret_key;
164
165 size_check(secret_key.size(), "private key");
166 load_x25519_keypair(std::move(secret_key), m_public, m_private);
167}
168
169std::unique_ptr<Public_Key> X25519_PrivateKey::public_key() const {
170 return std::make_unique<X25519_PublicKey>(public_value());
171}
172
176
177bool X25519_PrivateKey::check_key(RandomNumberGenerator& /*rng*/, bool /*strong*/) const {
178 std::vector<uint8_t> public_point(32);
179 const auto scope = CT::scoped_poison(m_private->key());
180 x25519_basepoint(std::span<uint8_t, 32>(public_point.data(), 32),
181 std::span<const uint8_t, 32>(m_private->key().data(), 32));
182 CT::unpoison(public_point);
183 return public_point == m_public->key();
184}
185
186secure_vector<uint8_t> X25519_PrivateKey::agree(const uint8_t w[], size_t w_len) const {
187 size_check(w_len, "public value");
188 return x25519_agree(m_private->key(), w);
189}
190
191namespace {
192
193/**
194* X25519 operation
195*/
196class X25519_KA_Operation final : public PK_Ops::Key_Agreement_with_KDF {
197 public:
198 X25519_KA_Operation(std::shared_ptr<const X25519_PrivateKey_Data> key,
199 const PK_Key_Agreement_Options_Reader& options) :
200 PK_Ops::Key_Agreement_with_KDF(options), m_key(std::move(key)) {}
201
202 size_t agreed_value_size() const override { return 32; }
203
204 secure_vector<uint8_t> raw_agree(const uint8_t w[], size_t w_len) override {
205 size_check(w_len, "public value");
206 return x25519_agree(m_key->key(), w);
207 }
208
209 private:
210 std::shared_ptr<const X25519_PrivateKey_Data> m_key;
211};
212
213} // namespace
214
215std::unique_ptr<PK_Ops::Key_Agreement> X25519_PrivateKey::_create_key_agreement_op(
216 RandomNumberGenerator& /*rng*/, const PK_Key_Agreement_Options_Reader& options) const {
218
219 return std::make_unique<X25519_KA_Operation>(m_private, options);
220}
221
222// Deprecated free functions, not used by the library itself
223
224void curve25519_donna(uint8_t mypublic[32], const uint8_t secret[32], const uint8_t basepoint[32]) {
225 x25519_scalarmult(std::span<uint8_t, 32>(mypublic, 32),
226 std::span<const uint8_t, 32>(secret, 32),
227 std::span<const uint8_t, 32>(basepoint, 32));
228}
229
230void curve25519_basepoint(uint8_t mypublic[32], const uint8_t secret[32]) {
231 x25519_basepoint(std::span<uint8_t, 32>(mypublic, 32), std::span<const uint8_t, 32>(secret, 32));
232}
233
234} // namespace Botan
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
bool parameters_are_empty() const
Definition asn1_obj.h:715
virtual OID object_identifier() const
Definition pk_keys.cpp:24
static Limits DER()
Definition ber_dec.h:44
BER_Decoder & decode(bool &out)
Definition ber_dec.h:361
BER_Decoder & verify_end()
Definition ber_dec.cpp:471
secure_vector< uint8_t > get_contents()
Definition der_enc.cpp:161
DER_Encoder & encode(bool b)
Definition der_enc.cpp:313
void random_vec(std::span< uint8_t > v)
Definition rng.h:254
secure_vector< uint8_t > private_key_bits() const override
Definition x25519.cpp:173
secure_vector< uint8_t > agree(const uint8_t w[], size_t w_len) const
Definition x25519.cpp:186
std::unique_ptr< Public_Key > public_key() const override
Definition x25519.cpp:169
bool check_key(RandomNumberGenerator &rng, bool strong) const override
Definition x25519.cpp:177
std::unique_ptr< PK_Ops::Key_Agreement > _create_key_agreement_op(RandomNumberGenerator &rng, const PK_Key_Agreement_Options_Reader &options) const override
Definition x25519.cpp:215
const secure_vector< uint8_t > & get_x() const
Definition x25519.cpp:42
std::vector< uint8_t > public_value() const override
Definition x25519.h:87
secure_vector< uint8_t > raw_private_key_bits() const override
Definition x25519.cpp:46
X25519_PrivateKey(const AlgorithmIdentifier &alg_id, std::span< const uint8_t > key_bits)
Definition x25519.cpp:156
std::shared_ptr< const X25519_PublicKey_Data > m_public
Definition x25519.h:58
bool check_key(RandomNumberGenerator &rng, bool strong) const override
Definition x25519.cpp:107
std::string algo_name() const override
Definition x25519.h:21
std::vector< uint8_t > raw_public_key_bits() const override
Definition x25519.cpp:132
AlgorithmIdentifier algorithm_identifier() const override
Definition x25519.cpp:103
std::vector< uint8_t > public_key_bits() const override
Definition x25519.cpp:136
std::unique_ptr< Private_Key > generate_another(RandomNumberGenerator &rng) const final
Definition x25519.cpp:140
X25519_PublicKey(const AlgorithmIdentifier &alg_id, std::span< const uint8_t > key_bits)
Definition x25519.cpp:119
constexpr auto scoped_poison(const Ts &... xs)
Definition ct_utils.h:222
constexpr void unpoison(const T *p, size_t n)
Definition ct_utils.h:67
constexpr CT::Mask< T > all_zeros(const T elem[], size_t len)
Definition ct_utils.h:790
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53
void x25519_scalarmult(std::span< uint8_t, 32 > out, std::span< const uint8_t, 32 > scalar, std::span< const uint8_t, 32 > u)
void require_software_provider(const OptionsT &options, std::string_view algo_name)
void x25519_basepoint(std::span< uint8_t, 32 > out, std::span< const uint8_t, 32 > scalar)
void curve25519_donna(uint8_t mypublic[32], const uint8_t secret[32], const uint8_t basepoint[32])
Definition x25519.cpp:224
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128
void curve25519_basepoint(uint8_t mypublic[32], const uint8_t secret[32])
Definition x25519.cpp:230