Botan 3.14.1
Crypto and TLS for C&
iso9796.cpp
Go to the documentation of this file.
1/*
2 * ISO-9796-2 - Digital signature schemes giving message recovery schemes 2 and 3
3 * (C) 2016 Tobias Niemann, Hackmanit GmbH
4 * 2025 Jack Lloyd
5 *
6 * Botan is released under the Simplified BSD License (see license.txt)
7 */
8
9#include <botan/internal/iso9796.h>
10
11#include <botan/assert.h>
12#include <botan/exceptn.h>
13#include <botan/hash.h>
14#include <botan/pk_options_readers.h>
15#include <botan/rng.h>
16#include <botan/internal/buffer_stuffer.h>
17#include <botan/internal/ct_utils.h>
18#include <botan/internal/fmt.h>
19#include <botan/internal/hash_id.h>
20#include <botan/internal/mgf1.h>
21#include <botan/internal/pk_options_impl.h>
22
23namespace Botan {
24
25namespace {
26
27std::vector<uint8_t> iso9796_hash(HashFunction& hash,
28 std::span<const uint8_t> msg1,
29 std::span<const uint8_t> hmsg2,
30 std::span<const uint8_t> salt) {
31 // Compute H(C || msg1 || H(msg2) || S) as described in the ISO text
32 hash.update_be(static_cast<uint64_t>(msg1.size()) * 8);
33 hash.update(msg1);
34 hash.update(hmsg2);
35 hash.update(salt);
36 return hash.final_stdvec();
37}
38
39std::vector<uint8_t> iso9796_encoding(std::span<const uint8_t> msg,
40 size_t output_bits,
41 std::unique_ptr<HashFunction>& hash,
42 size_t salt_len,
43 bool implicit,
45 const size_t output_length = (output_bits + 7) / 8;
46
47 //set trailer length
48 const size_t trailer_len = (implicit) ? 1 : 2;
49
50 const size_t hash_len = hash->output_length();
51
52 if(output_length <= hash_len + salt_len + trailer_len) {
53 throw Encoding_Error("ISO9796-2::encoding_of: Output length is too small");
54 }
55
56 //calculate message capacity
57 const size_t capacity = output_length - hash_len - salt_len - trailer_len - 1;
58
59 // msg1 is the recoverable part and hmsg2 is the hash of the unrecoverable message part.
60 const size_t msg1_len = std::min(capacity, msg.size());
61 const auto msg1 = msg.first(msg1_len); // the first capacity bytes
62 const auto msg2 = msg.subspan(msg1_len); // the rest; possibly empty
63
64 const auto hmsg2 = hash->process<std::vector<uint8_t>>(msg2);
65 const auto salt = rng.random_vec<std::vector<uint8_t>>(salt_len);
66
67 const auto H = iso9796_hash(*hash, msg1, hmsg2, salt);
68
69 std::vector<uint8_t> EM(output_length);
70
71 BufferStuffer stuffer(EM);
72 stuffer.append(0x00, stuffer.remaining_capacity() - (hash_len + salt_len + trailer_len + msg1_len + 1));
73 stuffer.append(0x01);
74 stuffer.append(msg1);
75 stuffer.append(salt);
76
77 //apply mask
78 const size_t mgf1_bytes = EM.size() - hash_len - trailer_len;
79 mgf1_mask(*hash, H, std::span{EM}.first(mgf1_bytes));
80
81 //clear the unused leftmost bits so the representative is < the modulus
82 EM[0] &= 0xFF >> (8 * output_length - output_bits);
83
84 stuffer.append(H);
85
86 // set implicit/ISO trailer
87
88 if(implicit) {
89 stuffer.append(0xBC);
90 } else {
91 const uint8_t hash_id = ieee1363_hash_id(hash->name());
92 if(hash_id == 0) {
93 throw Encoding_Error("ISO-9796: no hash identifier for " + hash->name());
94 }
95 stuffer.append(hash_id);
96 stuffer.append(0xCC);
97 }
98
99 BOTAN_ASSERT_NOMSG(stuffer.full());
100
101 return EM;
102}
103
104bool iso9796_verification(std::span<const uint8_t> repr,
105 std::span<const uint8_t> raw,
106 size_t key_bits,
107 std::unique_ptr<HashFunction>& hash,
108 size_t salt_len,
109 bool implicit) {
110 const size_t key_bytes = ceil_tobytes(key_bits);
111
112 if(repr.size() > key_bytes) {
113 return false;
114 }
115
116 // The recovered representative is minimally encoded, so left-pad a value
117 // with leading zero bytes back to the full width before parsing (cf PSS).
118 std::vector<uint8_t> coded(key_bytes);
119 {
120 BufferStuffer stuffer(coded);
121 stuffer.append(0x00, key_bytes - repr.size());
122 stuffer.append(repr);
123 }
124
125 if(coded.empty()) {
126 return false;
127 }
128
129 //the trailer length is fixed by the configured mode, and the verifier
130 //rejects a signature whose trailer does not match that mode
131
132 const size_t trailer_len = implicit ? 1 : 2;
133
134 const size_t hash_len = hash->output_length();
135
136 // The encoder requires output_length > hash_len + salt_len + trailer_len so
137 // that the message capacity is at least zero; match that here (the <= rejects
138 // the boundary case where the later capacity computation would underflow).
139 if(coded.size() <= hash_len + trailer_len + salt_len) {
140 return false;
141 }
142
143 if(implicit) {
144 if(coded[coded.size() - 1] != 0xBC) {
145 return false;
146 }
147 } else {
148 const uint8_t hash_id = ieee1363_hash_id(hash->name());
149 if(hash_id == 0) {
150 throw Decoding_Error("ISO-9796: no hash identifier for " + hash->name());
151 }
152
153 const uint8_t trailer_0 = coded[coded.size() - 2];
154 const uint8_t trailer_1 = coded[coded.size() - 1];
155
156 if(trailer_0 != hash_id || trailer_1 != 0xCC) {
157 return false;
158 }
159 }
160
161 // The encoder clears the unused leftmost bits of the representative, so a
162 // valid signature always has them zero; reject otherwise (cf PSS).
163 const size_t top_bits = 8 * key_bytes - key_bits;
164 if(top_bits > 8 - high_bit(coded[0])) {
165 return false;
166 }
167
168 CT::poison(coded.data(), coded.size());
169 //remove mask
170 uint8_t* DB = coded.data();
171 const size_t DB_size = coded.size() - hash_len - trailer_len;
172
173 const uint8_t* H = &coded[DB_size];
174
175 mgf1_mask(*hash, {H, hash_len}, {DB, DB_size});
176 //clear the unused leftmost bits (matching the encoding mask)
177 DB[0] &= 0xFF >> top_bits;
178
179 //recover msg1 and salt
180 size_t msg1_offset = 1;
181
182 auto waiting_for_delim = CT::Mask<uint8_t>::set();
183 auto bad_input = CT::Mask<uint8_t>::cleared();
184
185 for(size_t j = 0; j < DB_size; ++j) {
186 const auto is_zero = CT::Mask<uint8_t>::is_zero(DB[j]);
187 const auto is_one = CT::Mask<uint8_t>::is_equal(DB[j], 0x01);
188
189 const auto add_m = waiting_for_delim & is_zero;
190
191 bad_input |= waiting_for_delim & ~(is_zero | is_one);
192 msg1_offset += add_m.if_set_return(1);
193
194 waiting_for_delim &= is_zero;
195 }
196
197 //invalid, if delimiter 0x01 was not found or msg1_offset is too big
198 bad_input |= waiting_for_delim;
199
200 const auto bad_offset = CT::Mask<size_t>::is_lt(coded.size(), trailer_len + hash_len + msg1_offset + salt_len);
201 bad_input |= CT::Mask<uint8_t>(bad_offset);
202
203 //in case that msg1_offset is too big, just continue with offset = 0.
204 msg1_offset = CT::Mask<size_t>::expand(bad_input.value()).if_not_set_return(msg1_offset);
205
206 CT::unpoison(coded.data(), coded.size());
207 CT::unpoison(msg1_offset);
208
209 const size_t msg1_len = coded.size() - (trailer_len + hash_len + msg1_offset + salt_len);
210
211 const auto msg1 = std::span(coded).subspan(msg1_offset, msg1_len);
212 const auto salt = std::span(coded).subspan(msg1_offset + msg1.size(), salt_len);
213
214 //compute H2(C||msg1||H(msg2)||S*). * indicates a recovered value
215 // key_bytes == ceil_tobytes(key_bits) == the encoder's output_length, so the
216 // verifier splits the message at exactly the capacity the encoder used.
217 const size_t capacity = key_bytes - hash_len - salt_len - trailer_len - 1;
218
219 std::span<const uint8_t> msg1raw = raw;
220 if(msg1raw.size() > capacity) {
221 hash->update(msg1raw.subspan(capacity));
222 msg1raw = msg1raw.first(capacity);
223 }
224
225 const auto hmsg2 = hash->final_stdvec();
226
227 // Compute H(C*||msg1*||H(msg2)||S*) where '*' indicates a recovered value
228 const auto H2 = iso9796_hash(*hash, msg1, hmsg2, salt);
229
230 // Check if H == H2
231 bad_input |= CT::is_not_equal(H, H2.data(), hash_len);
232
233 // Check that msg after MGF1 matches msg in the original
234 bad_input |= ~CT::Mask<uint8_t>(CT::Mask<size_t>::is_equal(msg1.size(), msg1raw.size()));
235 bad_input |= ~CT::is_equal(msg1.data(), msg1raw.data(), std::min(msg1.size(), msg1raw.size()));
236
237 CT::unpoison(bad_input);
238 return (bad_input.as_bool() == false);
239}
240
241} // namespace
242
244 m_hash(HashFunction::create_or_throw(options.hash_function_name())),
245 m_implicit(!options.using_explicit_trailer_field()),
246 m_salt_len(options.salt_size().value_or(m_hash->output_length())) {
247 if(options.using_deterministic_signature() && m_salt_len > 0) {
248 throw Invalid_Argument("ISO_9796_DS2 with a non-zero salt cannot produce deterministic signatures");
249 }
250}
251
252/*
253 * ISO-9796-2 signature scheme 2
254 * DS 2 is probabilistic
255 */
256void ISO_9796_DS2::update(const uint8_t input[], size_t length) {
257 //need to buffer message completely, before digest
258 if(length > 0) {
259 m_msg_buffer.insert(m_msg_buffer.end(), input, input + length);
260 }
261}
262
263/*
264 * Return the raw (unencoded) data
265 */
266std::vector<uint8_t> ISO_9796_DS2::raw_data() {
267 std::vector<uint8_t> retbuffer = m_msg_buffer;
268 m_msg_buffer.clear();
269 return retbuffer;
270}
271
272/*
273 * ISO-9796-2 scheme 2 encode operation
274 */
275std::vector<uint8_t> ISO_9796_DS2::encoding_of(std::span<const uint8_t> msg,
276 size_t output_bits,
278 return iso9796_encoding(msg, output_bits, m_hash, m_salt_len, m_implicit, rng);
279}
280
281/*
282 * ISO-9796-2 scheme 2 verify operation
283 */
284bool ISO_9796_DS2::verify(std::span<const uint8_t> repr, std::span<const uint8_t> raw, size_t key_bits) {
285 return iso9796_verification(repr, raw, key_bits, m_hash, m_salt_len, m_implicit);
286}
287
288std::string ISO_9796_DS2::hash_function() const {
289 return m_hash->name();
290}
291
292/*
293 * Return the SCAN name
294 */
295std::string ISO_9796_DS2::name() const {
296 return fmt("ISO_9796_DS2({},{},{})", m_hash->name(), (m_implicit ? "imp" : "exp"), m_salt_len);
297}
298
300 m_hash(HashFunction::create_or_throw(options.hash_function_name())),
301 m_implicit(!options.using_explicit_trailer_field()) {
303}
304
305/*
306 * ISO-9796-2 signature scheme 3
307 * DS 3 is deterministic and equals DS2 without salt
308 */
309void ISO_9796_DS3::update(const uint8_t input[], size_t length) {
310 //need to buffer message completely, before digest
311 if(length > 0) {
312 m_msg_buffer.insert(m_msg_buffer.end(), input, input + length);
313 }
314}
315
316/*
317 * Return the raw (unencoded) data
318 */
319std::vector<uint8_t> ISO_9796_DS3::raw_data() {
320 std::vector<uint8_t> retbuffer = m_msg_buffer;
321 m_msg_buffer.clear();
322 return retbuffer;
323}
324
325/*
326 * ISO-9796-2 scheme 3 encode operation
327 */
328std::vector<uint8_t> ISO_9796_DS3::encoding_of(std::span<const uint8_t> msg,
329 size_t output_bits,
331 return iso9796_encoding(msg, output_bits, m_hash, 0, m_implicit, rng);
332}
333
334/*
335 * ISO-9796-2 scheme 3 verify operation
336 */
337bool ISO_9796_DS3::verify(std::span<const uint8_t> repr, std::span<const uint8_t> raw, size_t key_bits) {
338 return iso9796_verification(repr, raw, key_bits, m_hash, 0, m_implicit);
339}
340
341std::string ISO_9796_DS3::hash_function() const {
342 return m_hash->name();
343}
344
345/*
346 * Return the SCAN name
347 */
348std::string ISO_9796_DS3::name() const {
349 return fmt("ISO_9796_DS3({},{})", m_hash->name(), (m_implicit ? "imp" : "exp"));
350}
351
352} // namespace Botan
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
Helper class to ease in-place marshalling of concatenated fixed-length values.
static constexpr Mask< T > set()
Definition ct_utils.h:387
static constexpr Mask< T > expand(T v)
Definition ct_utils.h:397
static constexpr Mask< T > is_equal(T x, T y)
Definition ct_utils.h:447
static constexpr Mask< T > is_lt(T x, T y)
Definition ct_utils.h:455
static constexpr Mask< T > is_zero(T x)
Definition ct_utils.h:442
static constexpr Mask< T > cleared()
Definition ct_utils.h:392
std::string name() const override
Definition iso9796.cpp:295
ISO_9796_DS2(const PK_Signature_Options_Reader &options)
Definition iso9796.cpp:243
std::string hash_function() const override
Definition iso9796.cpp:288
std::string hash_function() const override
Definition iso9796.cpp:341
ISO_9796_DS3(const PK_Signature_Options_Reader &options)
Definition iso9796.cpp:299
std::string name() const override
Definition iso9796.cpp:348
static std::unique_ptr< SignaturePaddingScheme > create_or_throw(const PK_Signature_Options_Reader &options)
virtual std::vector< uint8_t > raw_data()=0
constexpr CT::Mask< T > is_not_equal(const T x[], const T y[], size_t len)
Definition ct_utils.h:843
constexpr void unpoison(const T *p, size_t n)
Definition ct_utils.h:67
constexpr void poison(const T *p, size_t n)
Definition ct_utils.h:56
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53
void mgf1_mask(HashFunction &hash, std::span< const uint8_t > input, std::span< uint8_t > output)
Definition mgf1.cpp:15
void acknowledge_always_deterministic(const PK_Signature_Options_Reader &options)
BOTAN_FORCE_INLINE constexpr T ceil_tobytes(T bits)
Definition bit_ops.h:176
uint8_t ieee1363_hash_id(std::string_view name)
Definition hash_id.cpp:144
BOTAN_FORCE_INLINE constexpr size_t high_bit(T n)
Definition bit_ops.h:73