Botan 3.14.1
Crypto and TLS for C&
sp800_56c_one_step.cpp
Go to the documentation of this file.
1/*
2* KDF defined in NIST SP 800-56a revision 2 (Single-step key-derivation function)
3* or in NIST SP 800-56C revision 2 (Section 4 - One-Step KDM)
4*
5* (C) 2017 Ribose Inc. Written by Krzysztof Kwiatkowski.
6* (C) 2024 Fabian Albert - Rohde & Schwarz Cybersecurity
7* (C) 2024 René Meusel - Rohde & Schwarz Cybersecurity
8*
9* Botan is released under the Simplified BSD License (see license.txt)
10*/
11
12#include <botan/internal/sp800_56c_one_step.h>
13
14#include <botan/exceptn.h>
15#include <botan/internal/bit_ops.h>
16#include <botan/internal/buffer_stuffer.h>
17#include <botan/internal/fmt.h>
18#include <botan/internal/kmac.h>
19
20#include <functional>
21
22namespace Botan {
23
24namespace {
25template <typename T>
26concept hash_or_mac_type = std::is_same_v<T, HashFunction> || std::is_same_v<T, MessageAuthenticationCode>;
27
28/**
29 * @brief One-Step Key Derivation as defined in SP800-56Cr2 Section 4
30 */
31template <hash_or_mac_type HashOrMacType>
32void kdm_internal(std::span<uint8_t> output_buffer,
33 std::span<const uint8_t> z,
34 std::span<const uint8_t> fixed_info,
35 HashOrMacType& hash_or_mac,
36 const std::function<void(HashOrMacType&)>& init_h_callback) {
37 // 1. If L > 0, then set reps = ceil(L / H_outputBits); otherwise,
38 // output an error indicator and exit this process without
39 // performing the remaining actions (i.e., omit steps 2 through 8).
40 //
41 // We follow the usual convention within the library that a KDF request for
42 // zero bytes is valid and, exactly as requested, outputs nothing.
43 if(output_buffer.empty()) {
44 return;
45 }
46
47 const size_t output_len = output_buffer.size();
48 const size_t h_output_len = hash_or_mac.output_length();
49 const size_t reps = ceil_division(output_len, h_output_len);
50
51 // 2. If reps > (2^32 - 1), then output an error indicator and exit this
52 // process without performing the remaining actions
53 // (i.e., omit steps 3 through 8).
54 BOTAN_ARG_CHECK(reps <= 0xFFFFFFFF, "Too large KDM output length");
55
56 // 3. Initialize a big-endian 4-byte unsigned integer counter as
57 // 0x00000000, corresponding to a 32-bit binary representation of
58 // the number zero.
59 uint32_t counter = 0;
60
61 // 4. If counter || Z || FixedInfo is more than max_H_inputBits bits
62 // long, then output an error indicator and exit this process
63 // without performing any of the remaining actions (i.e., omit
64 // steps 5 through 8). => SHA3 and KMAC are unlimited
65
66 // 5-7. Derive keying material directly into the output buffer.
67 BufferStuffer k(output_buffer);
68 for(size_t i = 1; i <= reps; i++) {
69 // 6.1. Increment counter by 1.
70 counter++;
71 // Reset the hash/MAC object. For MAC, also set the key (salt) and IV.
72 hash_or_mac.clear();
73 init_h_callback(hash_or_mac);
74
75 // 6.2 Compute K(i) = H(counter || Z || FixedInfo).
76 hash_or_mac.update_be(counter);
77 hash_or_mac.update(z);
78 hash_or_mac.update(fixed_info);
79
80 // 6.3. Set Result(i) = Result(i-1) || K(i).
81 if(k.remaining_capacity() >= h_output_len) {
82 hash_or_mac.final(k.next(h_output_len));
83 } else {
84 // Needs truncation so can't write directly to the output buffer
85 const auto k_i = hash_or_mac.final();
86 k.append(std::span{k_i}.first(k.remaining_capacity()));
87 }
88 }
89
90 BOTAN_ASSERT_NOMSG(k.full());
91}
92
93} // namespace
94
95void SP800_56C_One_Step_Hash::perform_kdf(std::span<uint8_t> key,
96 std::span<const uint8_t> secret,
97 std::span<const uint8_t> salt,
98 std::span<const uint8_t> label) const {
99 BOTAN_ARG_CHECK(salt.empty(), "SP800-56C KDF with hash does not support using a salt parameter");
100 kdm_internal<HashFunction>(key, secret, label, *m_hash, [](HashFunction&) { /* NOP */ });
101}
102
103std::string SP800_56C_One_Step_Hash::name() const {
104 return fmt("SP800-56A({})", m_hash->name());
105}
106
107std::unique_ptr<KDF> SP800_56C_One_Step_Hash::new_object() const {
108 return std::make_unique<SP800_56C_One_Step_Hash>(m_hash->new_object());
109}
110
111SP800_56C_One_Step_HMAC::SP800_56C_One_Step_HMAC(std::unique_ptr<MessageAuthenticationCode> mac) :
112 m_mac(std::move(mac)) {
113 // TODO: we need a MessageAuthenticationCode::is_hmac
114 if(!m_mac->name().starts_with("HMAC(")) {
115 throw Algorithm_Not_Found("Only HMAC can be used with SP800_56A_HMAC");
116 }
117}
118
119void SP800_56C_One_Step_HMAC::perform_kdf(std::span<uint8_t> key,
120 std::span<const uint8_t> secret,
121 std::span<const uint8_t> salt,
122 std::span<const uint8_t> label) const {
123 kdm_internal<MessageAuthenticationCode>(key, secret, label, *m_mac, [&](MessageAuthenticationCode& kdf_mac) {
124 // 4.1 Option 2 and 3 - An implementation dependent byte string, salt,
125 // whose (non-null) value may be optionally provided in
126 // OtherInput, serves as the HMAC# key ..
127
128 // SP 800-56Cr2 specifies if the salt is empty then a block of zeros
129 // equal to the hash's underlying block size are used. However for HMAC
130 // this is equivalent to setting a zero-length key, so the same call
131 // works for either case.
132 kdf_mac.set_key(salt);
133 });
134}
135
136std::string SP800_56C_One_Step_HMAC::name() const {
137 return fmt("SP800-56A({})", m_mac->name());
138}
139
140std::unique_ptr<KDF> SP800_56C_One_Step_HMAC::new_object() const {
141 return std::make_unique<SP800_56C_One_Step_HMAC>(m_mac->new_object());
142}
143
144// Option 3 - KMAC
145void SP800_56A_One_Step_KMAC_Abstract::perform_kdf(std::span<uint8_t> key,
146 std::span<const uint8_t> secret,
147 std::span<const uint8_t> salt,
148 std::span<const uint8_t> label) const {
149 // We follow the usual convention within the library that a KDF request for
150 // zero bytes is valid and, exactly as requested, outputs nothing.
151 if(key.empty()) {
152 return;
153 }
154 auto mac = create_kmac_instance(key.size());
155 kdm_internal<MessageAuthenticationCode>(key, secret, label, *mac, [&](MessageAuthenticationCode& kdf_mac) {
156 // 4.1 Option 2 and 3 - An implementation dependent byte string, salt,
157 // whose (non-null) value may be optionally provided in
158 // OtherInput, serves as the KMAC# key ...
159 if(salt.empty()) {
160 // 4.1 Implementation-Dependent Parameters 3
161 // If H(x) = KMAC128[or 256](salt, x, H_outputBits, "KDF"),
162 // then - in the absence of an agreed-upon alternative -
163 // the default_salt shall be an all - zero string of
164 // 164 bytes [or 132 bytes]
165 kdf_mac.set_key(std::vector<uint8_t>(default_salt_length(), 0));
166 } else {
167 kdf_mac.set_key(salt);
168 }
169
170 // 4.1 Option 3 - The "customization string" S shall be the byte string
171 // 01001011 || 01000100 || 01000110, which represents the sequence
172 // of characters 'K', 'D', and 'F' in 8-bit ASCII.
173 kdf_mac.start(std::array<uint8_t, 3>{'K', 'D', 'F'});
174 });
175}
176
177std::unique_ptr<MessageAuthenticationCode> SP800_56C_One_Step_KMAC128::create_kmac_instance(
178 size_t output_byte_len) const {
179 return std::make_unique<KMAC128>(output_byte_len * 8);
180}
181
182std::unique_ptr<MessageAuthenticationCode> SP800_56C_One_Step_KMAC256::create_kmac_instance(
183 size_t output_byte_len) const {
184 return std::make_unique<KMAC256>(output_byte_len * 8);
185}
186
187} // namespace Botan
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
Helper class to ease in-place marshalling of concatenated fixed-length values.
virtual std::unique_ptr< MessageAuthenticationCode > create_kmac_instance(size_t output_byte_len) const =0
virtual size_t default_salt_length() const =0
See SP800-56C Section 4.1 - Implementation-Dependent Parameters 3.
SP800_56C_One_Step_HMAC(std::unique_ptr< MessageAuthenticationCode > mac)
std::string name() const override
std::unique_ptr< KDF > new_object() const override
std::string name() const override
std::unique_ptr< KDF > new_object() const override
void set_key(const OctetString &key)
Definition sym_algo.cpp:14
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53
BOTAN_FORCE_INLINE constexpr T ceil_division(T a, T b)
Definition bit_ops.h:167