Botan 3.3.0
Crypto and TLS for C&
pubkey.h
Go to the documentation of this file.
1/*
2* Public Key Interface
3* (C) 1999-2010 Jack Lloyd
4*
5* Botan is released under the Simplified BSD License (see license.txt)
6*/
7
8#ifndef BOTAN_PUBKEY_H_
9#define BOTAN_PUBKEY_H_
10
11#include <botan/asn1_obj.h>
12#include <botan/pk_keys.h>
13#include <botan/pk_ops_fwd.h>
14#include <botan/symkey.h>
15#include <span>
16#include <string>
17#include <string_view>
18#include <utility>
19
20namespace Botan {
21
22class RandomNumberGenerator;
23
24/**
25* Public Key Encryptor
26* This is the primary interface for public key encryption
27*/
29 public:
30 /**
31 * Encrypt a message.
32 * @param in the message as a byte array
33 * @param length the length of the above byte array
34 * @param rng the random number source to use
35 * @return encrypted message
36 */
37 std::vector<uint8_t> encrypt(const uint8_t in[], size_t length, RandomNumberGenerator& rng) const {
38 return enc(in, length, rng);
39 }
40
41 /**
42 * Encrypt a message.
43 * @param in the message
44 * @param rng the random number source to use
45 * @return encrypted message
46 */
47 std::vector<uint8_t> encrypt(std::span<const uint8_t> in, RandomNumberGenerator& rng) const {
48 return enc(in.data(), in.size(), rng);
49 }
50
51 /**
52 * Return the maximum allowed message size in bytes.
53 * @return maximum message size in bytes
54 */
55 virtual size_t maximum_input_size() const = 0;
56
57 /**
58 * Return an upper bound on the ciphertext length
59 */
60 virtual size_t ciphertext_length(size_t ctext_len) const = 0;
61
62 PK_Encryptor() = default;
63 virtual ~PK_Encryptor() = default;
64
65 PK_Encryptor(const PK_Encryptor&) = delete;
67
68 PK_Encryptor(PK_Encryptor&&) noexcept = default;
69 PK_Encryptor& operator=(PK_Encryptor&&) noexcept = default;
70
71 private:
72 virtual std::vector<uint8_t> enc(const uint8_t[], size_t, RandomNumberGenerator&) const = 0;
73};
74
75/**
76* Public Key Decryptor
77*/
79 public:
80 /**
81 * Decrypt a ciphertext, throwing an exception if the input
82 * seems to be invalid (eg due to an accidental or malicious
83 * error in the ciphertext).
84 *
85 * @param in the ciphertext as a byte array
86 * @param length the length of the above byte array
87 * @return decrypted message
88 */
89 secure_vector<uint8_t> decrypt(const uint8_t in[], size_t length) const;
90
91 /**
92 * Same as above, but taking a vector
93 * @param in the ciphertext
94 * @return decrypted message
95 */
96 secure_vector<uint8_t> decrypt(std::span<const uint8_t> in) const { return decrypt(in.data(), in.size()); }
97
98 /**
99 * Decrypt a ciphertext. If the ciphertext is invalid (eg due to
100 * invalid padding) or is not the expected length, instead
101 * returns a random string of the expected length. Use to avoid
102 * oracle attacks, especially against PKCS #1 v1.5 decryption.
103 */
104 secure_vector<uint8_t> decrypt_or_random(const uint8_t in[],
105 size_t length,
106 size_t expected_pt_len,
107 RandomNumberGenerator& rng) const;
108
109 /**
110 * Decrypt a ciphertext. If the ciphertext is invalid (eg due to
111 * invalid padding) or is not the expected length, instead
112 * returns a random string of the expected length. Use to avoid
113 * oracle attacks, especially against PKCS #1 v1.5 decryption.
114 *
115 * Additionally checks (also in const time) that:
116 * contents[required_content_offsets[i]] == required_content_bytes[i]
117 * for 0 <= i < required_contents
118 *
119 * Used for example in TLS, which encodes the client version in
120 * the content bytes: if there is any timing variation the version
121 * check can be used as an oracle to recover the key.
122 */
123 secure_vector<uint8_t> decrypt_or_random(const uint8_t in[],
124 size_t length,
125 size_t expected_pt_len,
127 const uint8_t required_content_bytes[],
128 const uint8_t required_content_offsets[],
129 size_t required_contents) const;
130
131 /**
132 * Return an upper bound on the plaintext length for a particular
133 * ciphertext input length
134 */
135 virtual size_t plaintext_length(size_t ctext_len) const = 0;
136
137 PK_Decryptor() = default;
138 virtual ~PK_Decryptor() = default;
139
140 PK_Decryptor(const PK_Decryptor&) = delete;
142
143 PK_Decryptor(PK_Decryptor&&) noexcept = default;
144 PK_Decryptor& operator=(PK_Decryptor&&) noexcept = default;
145
146 private:
147 virtual secure_vector<uint8_t> do_decrypt(uint8_t& valid_mask, const uint8_t in[], size_t in_len) const = 0;
148};
149
150/**
151* Public Key Signer. Use the sign_message() functions for small
152* messages. Use multiple calls update() to process large messages and
153* generate the signature by finally calling signature().
154*/
156 public:
157 /**
158 * Construct a PK Signer.
159 * @param key the key to use inside this signer
160 * @param rng the random generator to use
161 * @param padding the padding/hash to use, eg "EMSA_PKCS1(SHA-256)"
162 * @param format the signature format to use
163 * @param provider the provider to use
164 */
165 PK_Signer(const Private_Key& key,
167 std::string_view padding,
168 Signature_Format format = Signature_Format::Standard,
169 std::string_view provider = "");
170
172
173 PK_Signer(const PK_Signer&) = delete;
174 PK_Signer& operator=(const PK_Signer&) = delete;
175
176 PK_Signer(PK_Signer&&) noexcept;
177 PK_Signer& operator=(PK_Signer&&) noexcept;
178
179 /**
180 * Sign a message all in one go
181 * @param in the message to sign as a byte array
182 * @param length the length of the above byte array
183 * @param rng the rng to use
184 * @return signature
185 */
186 std::vector<uint8_t> sign_message(const uint8_t in[], size_t length, RandomNumberGenerator& rng) {
187 this->update(in, length);
188 return this->signature(rng);
189 }
190
191 /**
192 * Sign a message.
193 * @param in the message to sign
194 * @param rng the rng to use
195 * @return signature
196 */
197 std::vector<uint8_t> sign_message(std::span<const uint8_t> in, RandomNumberGenerator& rng) {
198 return sign_message(in.data(), in.size(), rng);
199 }
200
201 /**
202 * Add a message part (single byte).
203 * @param in the byte to add
204 */
205 void update(uint8_t in) { update(&in, 1); }
206
207 /**
208 * Add a message part.
209 * @param in the message part to add as a byte array
210 * @param length the length of the above byte array
211 */
212 void update(const uint8_t in[], size_t length);
213
214 /**
215 * Add a message part.
216 * @param in the message part to add
217 */
218 void update(std::span<const uint8_t> in) { update(in.data(), in.size()); }
219
220 /**
221 * Add a message part.
222 * @param in the message part to add
223 */
224 void update(std::string_view in);
225
226 /**
227 * Get the signature of the so far processed message (provided by the
228 * calls to update()).
229 * @param rng the rng to use
230 * @return signature of the total message
231 */
232 std::vector<uint8_t> signature(RandomNumberGenerator& rng);
233
234 /**
235 * Set the output format of the signature.
236 * @param format the signature format to use
237 */
238 void set_output_format(Signature_Format format) { m_sig_format = format; }
239
240 /**
241 * Return an upper bound on the length of the signatures this
242 * PK_Signer will produce
243 */
244 size_t signature_length() const;
245
246 /**
247 * Return an AlgorithmIdentifier appropriate for identifying the signature
248 * method being generated by this PK_Signer. Throws an exception if this
249 * is not available for the current signature scheme.
250 */
251 AlgorithmIdentifier algorithm_identifier() const;
252
253 /**
254 * Return the hash function which is being used to create signatures.
255 * This should never return an empty string however it may return a string
256 * which does not map directly to a hash function, in particular if "Raw"
257 * (unhashed) encoding is being used.
258 */
259 std::string hash_function() const;
260
261 private:
262 std::unique_ptr<PK_Ops::Signature> m_op;
263 Signature_Format m_sig_format;
264 size_t m_parts, m_part_size;
265};
266
267/**
268* Public Key Verifier. Use the verify_message() functions for small
269* messages. Use multiple calls update() to process large messages and
270* verify the signature by finally calling check_signature().
271*/
273 public:
274 /**
275 * Construct a PK Verifier.
276 * @param pub_key the public key to verify against
277 * @param padding the padding/hash to use (eg "EMSA_PKCS1(SHA-256)")
278 * @param format the signature format to use
279 * @param provider the provider to use
280 */
281 PK_Verifier(const Public_Key& pub_key,
282 std::string_view padding,
283 Signature_Format format = Signature_Format::Standard,
284 std::string_view provider = "");
285
286 /**
287 * Construct a PK Verifier (X.509 specific)
288 *
289 * This constructor will attempt to decode signature_format relative
290 * to the public key provided. If they seem to be inconsistent or
291 * otherwise unsupported, a Decoding_Error is thrown.
292 *
293 * @param pub_key the public key to verify against
294 * @param signature_algorithm the supposed signature algorithm
295 * @param provider the provider to use
296 */
297 PK_Verifier(const Public_Key& pub_key,
298 const AlgorithmIdentifier& signature_algorithm,
299 std::string_view provider = "");
300
302
303 PK_Verifier(const PK_Verifier&) = delete;
305
307 PK_Verifier& operator=(PK_Verifier&&) noexcept;
308
309 /**
310 * Verify a signature.
311 * @param msg the message that the signature belongs to, as a byte array
312 * @param msg_length the length of the above byte array msg
313 * @param sig the signature as a byte array
314 * @param sig_length the length of the above byte array sig
315 * @return true if the signature is valid
316 */
317 bool verify_message(const uint8_t msg[], size_t msg_length, const uint8_t sig[], size_t sig_length);
318
319 /**
320 * Verify a signature.
321 * @param msg the message that the signature belongs to
322 * @param sig the signature
323 * @return true if the signature is valid
324 */
325 bool verify_message(std::span<const uint8_t> msg, std::span<const uint8_t> sig) {
326 return verify_message(msg.data(), msg.size(), sig.data(), sig.size());
327 }
328
329 /**
330 * Add a message part (single byte) of the message corresponding to the
331 * signature to be verified.
332 * @param in the byte to add
333 */
334 void update(uint8_t in) { update(&in, 1); }
335
336 /**
337 * Add a message part of the message corresponding to the
338 * signature to be verified.
339 * @param msg_part the new message part as a byte array
340 * @param length the length of the above byte array
341 */
342 void update(const uint8_t msg_part[], size_t length);
343
344 /**
345 * Add a message part of the message corresponding to the
346 * signature to be verified.
347 * @param in the new message part
348 */
349 void update(std::span<const uint8_t> in) { update(in.data(), in.size()); }
350
351 /**
352 * Add a message part of the message corresponding to the
353 * signature to be verified.
354 */
355 void update(std::string_view in);
356
357 /**
358 * Check the signature of the buffered message, i.e. the one build
359 * by successive calls to update.
360 * @param sig the signature to be verified as a byte array
361 * @param length the length of the above byte array
362 * @return true if the signature is valid, false otherwise
363 */
364 bool check_signature(const uint8_t sig[], size_t length);
365
366 /**
367 * Check the signature of the buffered message, i.e. the one build
368 * by successive calls to update.
369 * @param sig the signature to be verified
370 * @return true if the signature is valid, false otherwise
371 */
372 bool check_signature(std::span<const uint8_t> sig) { return check_signature(sig.data(), sig.size()); }
373
374 /**
375 * Set the format of the signatures fed to this verifier.
376 * @param format the signature format to use
377 */
378 void set_input_format(Signature_Format format);
379
380 /**
381 * Return the hash function which is being used to verify signatures.
382 * This should never return an empty string however it may return a string
383 * which does not map directly to a hash function, in particular if "Raw"
384 * (unhashed) encoding is being used.
385 */
386 std::string hash_function() const;
387
388 private:
389 std::unique_ptr<PK_Ops::Verification> m_op;
390 Signature_Format m_sig_format;
391 size_t m_parts, m_part_size;
392};
393
394/**
395* Object used for key agreement
396*/
398 public:
399 /**
400 * Construct a PK Key Agreement.
401 * @param key the key to use
402 * @param rng the random generator to use
403 * @param kdf name of the KDF to use (or 'Raw' for no KDF)
404 * @param provider the algo provider to use (or empty for default)
405 */
406 PK_Key_Agreement(const Private_Key& key,
408 std::string_view kdf,
409 std::string_view provider = "");
410
412
415
417 PK_Key_Agreement& operator=(PK_Key_Agreement&&) noexcept;
418
419 /**
420 * Perform Key Agreement Operation
421 * @param key_len the desired key output size (ignored if "Raw" KDF is used)
422 * @param in the other parties key
423 * @param in_len the length of in in bytes
424 * @param params extra derivation params
425 * @param params_len the length of params in bytes
426 */
427 SymmetricKey derive_key(
428 size_t key_len, const uint8_t in[], size_t in_len, const uint8_t params[], size_t params_len) const;
429
430 /**
431 * Perform Key Agreement Operation
432 * @param key_len the desired key output size (ignored if "Raw" KDF is used)
433 * @param in the other parties key
434 * @param params extra derivation params
435 * @param params_len the length of params in bytes
436 */
437 SymmetricKey derive_key(size_t key_len,
438 std::span<const uint8_t> in,
439 const uint8_t params[],
440 size_t params_len) const {
441 return derive_key(key_len, in.data(), in.size(), params, params_len);
442 }
443
444 /**
445 * Perform Key Agreement Operation
446 * @param key_len the desired key output size (ignored if "Raw" KDF is used)
447 * @param in the other parties key
448 * @param in_len the length of in in bytes
449 * @param params extra derivation params
450 */
451 SymmetricKey derive_key(size_t key_len, const uint8_t in[], size_t in_len, std::string_view params = "") const;
452
453 /**
454 * Perform Key Agreement Operation
455 * @param key_len the desired key output size (ignored if "Raw" KDF is used)
456 * @param in the other parties key
457 * @param params extra derivation params
458 */
459 SymmetricKey derive_key(size_t key_len, const std::span<const uint8_t> in, std::string_view params = "") const;
460
461 /**
462 * Return the underlying size of the value that is agreed.
463 * If derive_key is called with a length of 0 with a "Raw"
464 * KDF, it will return a value of this size.
465 */
466 size_t agreed_value_size() const;
467
468 private:
469 std::unique_ptr<PK_Ops::Key_Agreement> m_op;
470};
471
472/**
473* Encryption using a standard message recovery algorithm like RSA or
474* ElGamal, paired with an encoding scheme like OAEP.
475*/
477 public:
478 size_t maximum_input_size() const override;
479
480 /**
481 * Construct an instance.
482 * @param key the key to use inside the encryptor
483 * @param rng the RNG to use
484 * @param padding the message encoding scheme to use (eg "OAEP(SHA-256)")
485 * @param provider the provider to use
486 */
487 PK_Encryptor_EME(const Public_Key& key,
489 std::string_view padding,
490 std::string_view provider = "");
491
493
496
498 PK_Encryptor_EME& operator=(PK_Encryptor_EME&&) noexcept;
499
500 /**
501 * Return an upper bound on the ciphertext length for a particular
502 * plaintext input length
503 */
504 size_t ciphertext_length(size_t ptext_len) const override;
505
506 private:
507 std::vector<uint8_t> enc(const uint8_t[], size_t, RandomNumberGenerator& rng) const override;
508
509 std::unique_ptr<PK_Ops::Encryption> m_op;
510};
511
512/**
513* Decryption with an MR algorithm and an EME.
514*/
516 public:
517 /**
518 * Construct an instance.
519 * @param key the key to use inside the decryptor
520 * @param rng the random generator to use
521 * @param eme the EME to use
522 * @param provider the provider to use
523 */
524 PK_Decryptor_EME(const Private_Key& key,
526 std::string_view eme,
527 std::string_view provider = "");
528
529 size_t plaintext_length(size_t ptext_len) const override;
530
532
535
537 PK_Decryptor_EME& operator=(PK_Decryptor_EME&&) noexcept;
538
539 private:
540 secure_vector<uint8_t> do_decrypt(uint8_t& valid_mask, const uint8_t in[], size_t in_len) const override;
541
542 std::unique_ptr<PK_Ops::Decryption> m_op;
543};
544
545/**
546* Result of a key encapsulation operation.
547*/
549 public:
550 KEM_Encapsulation(std::vector<uint8_t> encapsulated_shared_key, secure_vector<uint8_t> shared_key) :
551 m_encapsulated_shared_key(std::move(encapsulated_shared_key)), m_shared_key(std::move(shared_key)) {}
552
553 /**
554 * @returns the encapsulated shared secret (encrypted with the public key)
555 */
556 const std::vector<uint8_t>& encapsulated_shared_key() const { return m_encapsulated_shared_key; }
557
558 /**
559 * @returns the plaintext shared secret
560 */
561 const secure_vector<uint8_t>& shared_key() const { return m_shared_key; }
562
563 /**
564 * @returns the pair (encapsulated key, key) extracted from @p kem
565 */
566 static std::pair<std::vector<uint8_t>, secure_vector<uint8_t>> destructure(KEM_Encapsulation&& kem) {
567 return std::make_pair(std::exchange(kem.m_encapsulated_shared_key, {}), std::exchange(kem.m_shared_key, {}));
568 }
569
570 private:
571 friend class PK_KEM_Encryptor;
572
573 KEM_Encapsulation(size_t encapsulated_size, size_t shared_key_size) :
574 m_encapsulated_shared_key(encapsulated_size), m_shared_key(shared_key_size) {}
575
576 private:
577 std::vector<uint8_t> m_encapsulated_shared_key;
578 secure_vector<uint8_t> m_shared_key;
579};
580
581/**
582* Public Key Key Encapsulation Mechanism Encryption.
583*/
585 public:
586 /**
587 * Construct an instance.
588 * @param key the key to encrypt to
589 * @param kem_param additional KEM parameters
590 * @param provider the provider to use
591 */
592 PK_KEM_Encryptor(const Public_Key& key, std::string_view kem_param = "", std::string_view provider = "");
593
594 /**
595 * Construct an instance.
596 * @param key the key to encrypt to
597 * @param rng the RNG to use
598 * @param kem_param additional KEM parameters
599 * @param provider the provider to use
600 */
601 BOTAN_DEPRECATED("Use constructor that does not take RNG")
602
605 std::string_view kem_param = "",
606 std::string_view provider = "") :
607 PK_KEM_Encryptor(key, kem_param, provider) {
608 BOTAN_UNUSED(rng);
609 }
610
612
615
617 PK_KEM_Encryptor& operator=(PK_KEM_Encryptor&&) noexcept;
618
619 /**
620 * Return the length of the shared key returned by this KEM
621 *
622 * If this KEM was used with a KDF, then it will always return
623 * exactly the desired key length, because the output of the KEM
624 * will be hashed by the KDF.
625 *
626 * However if the KEM was used with "Raw" kdf, to request the
627 * algorithmic output of the KEM directly, then the desired key
628 * length will be ignored and a bytestring that depends on the
629 * algorithm is returned
630 *
631 * @param desired_shared_key_len is the requested length
632 */
633 size_t shared_key_length(size_t desired_shared_key_len) const;
634
635 /**
636 * Return the length in bytes of encapsulated keys returned by this KEM
637 */
638 size_t encapsulated_key_length() const;
639
640 /**
641 * Generate a shared key for data encryption.
642 *
643 * @param rng the RNG to use
644 * @param desired_shared_key_len desired size of the shared key in bytes for the KDF
645 * (ignored if no KDF is used)
646 * @param salt a salt value used in the KDF
647 * (ignored if no KDF is used)
648 *
649 * @returns a struct with both the shared secret and its encapsulation
650 */
652 size_t desired_shared_key_len = 32,
653 std::span<const uint8_t> salt = {}) {
654 std::vector<uint8_t> encapsulated_shared_key(encapsulated_key_length());
655 secure_vector<uint8_t> shared_key(shared_key_length(desired_shared_key_len));
656
657 encrypt(std::span{encapsulated_shared_key}, std::span{shared_key}, rng, desired_shared_key_len, salt);
658 return KEM_Encapsulation(std::move(encapsulated_shared_key), std::move(shared_key));
659 }
660
661 /**
662 * Generate a shared key for data encryption.
663 * @param out_encapsulated_key the generated encapsulated key
664 * @param out_shared_key the generated shared key
665 * @param rng the RNG to use
666 * @param desired_shared_key_len desired size of the shared key in bytes
667 * (ignored if no KDF is used)
668 * @param salt a salt value used in the KDF
669 * (ignored if no KDF is used)
670 */
671 void encrypt(secure_vector<uint8_t>& out_encapsulated_key,
672 secure_vector<uint8_t>& out_shared_key,
674 size_t desired_shared_key_len = 32,
675 std::span<const uint8_t> salt = {}) {
676 out_encapsulated_key.resize(encapsulated_key_length());
677 out_shared_key.resize(shared_key_length(desired_shared_key_len));
678 encrypt(std::span{out_encapsulated_key}, std::span{out_shared_key}, rng, desired_shared_key_len, salt);
679 }
680
681 /**
682 * Generate a shared key for data encryption.
683 * @param out_encapsulated_key the generated encapsulated key
684 * @param out_shared_key the generated shared key
685 * @param rng the RNG to use
686 * @param desired_shared_key_len desired size of the shared key in bytes
687 * (ignored if no KDF is used)
688 * @param salt a salt value used in the KDF
689 * (ignored if no KDF is used)
690 */
691 void encrypt(std::span<uint8_t> out_encapsulated_key,
692 std::span<uint8_t> out_shared_key,
693 RandomNumberGenerator& rng,
694 size_t desired_shared_key_len = 32,
695 std::span<const uint8_t> salt = {});
696
697 BOTAN_DEPRECATED("use overload with salt as std::span<>")
698
699 void encrypt(secure_vector<uint8_t>& out_encapsulated_key,
700 secure_vector<uint8_t>& out_shared_key,
701 size_t desired_shared_key_len,
703 const uint8_t salt[],
704 size_t salt_len) {
705 this->encrypt(out_encapsulated_key, out_shared_key, rng, desired_shared_key_len, {salt, salt_len});
706 }
707
708 BOTAN_DEPRECATED("use overload where rng comes after the out-paramters")
709
710 void encrypt(secure_vector<uint8_t>& out_encapsulated_key,
711 secure_vector<uint8_t>& out_shared_key,
712 size_t desired_shared_key_len,
714 std::span<const uint8_t> salt = {}) {
715 out_encapsulated_key.resize(encapsulated_key_length());
716 out_shared_key.resize(shared_key_length(desired_shared_key_len));
717 encrypt(out_encapsulated_key, out_shared_key, rng, desired_shared_key_len, salt);
718 }
719
720 private:
721 std::unique_ptr<PK_Ops::KEM_Encryption> m_op;
722};
723
724/**
725* Public Key Key Encapsulation Mechanism Decryption.
726*/
728 public:
729 /**
730 * Construct an instance.
731 * @param key the key to use inside the decryptor
732 * @param rng the RNG to use
733 * @param kem_param additional KEM parameters
734 * @param provider the provider to use
735 */
736 PK_KEM_Decryptor(const Private_Key& key,
738 std::string_view kem_param = "",
739 std::string_view provider = "");
740
744
746 PK_KEM_Decryptor& operator=(PK_KEM_Decryptor&&) noexcept;
747
748 /**
749 * Return the length of the shared key returned by this KEM
750 *
751 * If this KEM was used with a KDF, then it will always return
752 * exactly the desired key length, because the output of the KEM
753 * will be hashed by the KDF.
754 *
755 * However if the KEM was used with "Raw" kdf, to request the
756 * algorithmic output of the KEM directly, then the desired key
757 * length will be ignored and a bytestring that depends on the
758 * algorithm is returned
759 *
760 * @param desired_shared_key_len is the requested length.
761 */
762 size_t shared_key_length(size_t desired_shared_key_len) const;
763
764 /**
765 * Return the length of the encapsulated key expected by this KEM
766 */
767 size_t encapsulated_key_length() const;
768
769 /**
770 * Decrypts the shared key for data encryption.
771 *
772 * @param out_shared_key the generated shared key
773 * @param encap_key the encapsulated key
774 * @param desired_shared_key_len desired size of the shared key in bytes
775 * (ignored if no KDF is used)
776 * @param salt a salt value used in the KDF
777 * (ignored if no KDF is used)
778 */
779 void decrypt(std::span<uint8_t> out_shared_key,
780 std::span<const uint8_t> encap_key,
781 size_t desired_shared_key_len = 32,
782 std::span<const uint8_t> salt = {});
783
784 /**
785 * Decrypts the shared key for data encryption.
786 *
787 * @param encap_key the encapsulated key
788 * @param encap_key_len size of the encapsulated key in bytes
789 * @param desired_shared_key_len desired size of the shared key in bytes
790 * (ignored if no KDF is used)
791 * @param salt a salt value used in the KDF
792 * (ignored if no KDF is used)
793 * @param salt_len size of the salt value in bytes
794 * (ignored if no KDF is used)
795 *
796 * @return the shared data encryption key
797 */
798 secure_vector<uint8_t> decrypt(const uint8_t encap_key[],
799 size_t encap_key_len,
800 size_t desired_shared_key_len,
801 const uint8_t salt[] = nullptr,
802 size_t salt_len = 0) {
803 secure_vector<uint8_t> shared_key(shared_key_length(desired_shared_key_len));
804 decrypt(shared_key, {encap_key, encap_key_len}, desired_shared_key_len, {salt, salt_len});
805 return shared_key;
806 }
807
808 /**
809 * Decrypts the shared key for data encryption.
810 *
811 * @param encap_key the encapsulated key
812 * @param desired_shared_key_len desired size of the shared key in bytes
813 * (ignored if no KDF is used)
814 * @param salt a salt value used in the KDF
815 * (ignored if no KDF is used)
816 *
817 * @return the shared data encryption key
818 */
819 secure_vector<uint8_t> decrypt(std::span<const uint8_t> encap_key,
820 size_t desired_shared_key_len = 32,
821 std::span<const uint8_t> salt = {}) {
822 secure_vector<uint8_t> shared_key(shared_key_length(desired_shared_key_len));
823 decrypt(shared_key, encap_key, desired_shared_key_len, salt);
824 return shared_key;
825 }
826
827 private:
828 std::unique_ptr<PK_Ops::KEM_Decryption> m_op;
829};
830
831} // namespace Botan
832
833#endif
#define BOTAN_UNUSED
Definition assert.h:118
KEM_Encapsulation(std::vector< uint8_t > encapsulated_shared_key, secure_vector< uint8_t > shared_key)
Definition pubkey.h:550
const secure_vector< uint8_t > & shared_key() const
Definition pubkey.h:561
static std::pair< std::vector< uint8_t >, secure_vector< uint8_t > > destructure(KEM_Encapsulation &&kem)
Definition pubkey.h:566
const std::vector< uint8_t > & encapsulated_shared_key() const
Definition pubkey.h:556
~PK_Decryptor_EME() override
PK_Decryptor_EME(PK_Decryptor_EME &&) noexcept
PK_Decryptor_EME(const PK_Decryptor_EME &)=delete
PK_Decryptor_EME & operator=(const PK_Decryptor_EME &)=delete
virtual ~PK_Decryptor()=default
virtual size_t plaintext_length(size_t ctext_len) const =0
secure_vector< uint8_t > decrypt(std::span< const uint8_t > in) const
Definition pubkey.h:96
PK_Decryptor & operator=(const PK_Decryptor &)=delete
PK_Decryptor(PK_Decryptor &&) noexcept=default
PK_Decryptor()=default
PK_Decryptor(const PK_Decryptor &)=delete
~PK_Encryptor_EME() override
PK_Encryptor_EME & operator=(const PK_Encryptor_EME &)=delete
PK_Encryptor_EME(PK_Encryptor_EME &&) noexcept
PK_Encryptor_EME(const PK_Encryptor_EME &)=delete
PK_Encryptor & operator=(const PK_Encryptor &)=delete
virtual size_t maximum_input_size() const =0
virtual size_t ciphertext_length(size_t ctext_len) const =0
std::vector< uint8_t > encrypt(std::span< const uint8_t > in, RandomNumberGenerator &rng) const
Definition pubkey.h:47
virtual ~PK_Encryptor()=default
std::vector< uint8_t > encrypt(const uint8_t in[], size_t length, RandomNumberGenerator &rng) const
Definition pubkey.h:37
PK_Encryptor(const PK_Encryptor &)=delete
PK_Encryptor(PK_Encryptor &&) noexcept=default
PK_Encryptor()=default
secure_vector< uint8_t > decrypt(const uint8_t encap_key[], size_t encap_key_len, size_t desired_shared_key_len, const uint8_t salt[]=nullptr, size_t salt_len=0)
Definition pubkey.h:798
PK_KEM_Decryptor(PK_KEM_Decryptor &&) noexcept
PK_KEM_Decryptor & operator=(const PK_KEM_Decryptor &)=delete
PK_KEM_Decryptor(const PK_KEM_Decryptor &)=delete
secure_vector< uint8_t > decrypt(std::span< const uint8_t > encap_key, size_t desired_shared_key_len=32, std::span< const uint8_t > salt={})
Definition pubkey.h:819
void encrypt(secure_vector< uint8_t > &out_encapsulated_key, secure_vector< uint8_t > &out_shared_key, RandomNumberGenerator &rng, size_t desired_shared_key_len=32, std::span< const uint8_t > salt={})
Definition pubkey.h:671
PK_KEM_Encryptor(PK_KEM_Encryptor &&) noexcept
PK_KEM_Encryptor(const PK_KEM_Encryptor &)=delete
PK_KEM_Encryptor & operator=(const PK_KEM_Encryptor &)=delete
PK_Key_Agreement & operator=(const PK_Key_Agreement &)=delete
PK_Key_Agreement(const PK_Key_Agreement &)=delete
PK_Key_Agreement(PK_Key_Agreement &&) noexcept
PK_Signer(PK_Signer &&) noexcept
void update(uint8_t in)
Definition pubkey.h:205
std::vector< uint8_t > sign_message(std::span< const uint8_t > in, RandomNumberGenerator &rng)
Definition pubkey.h:197
void update(std::span< const uint8_t > in)
Definition pubkey.h:218
PK_Signer & operator=(const PK_Signer &)=delete
void set_output_format(Signature_Format format)
Definition pubkey.h:238
PK_Signer(const PK_Signer &)=delete
PK_Verifier(PK_Verifier &&) noexcept
void update(uint8_t in)
Definition pubkey.h:334
void update(std::span< const uint8_t > in)
Definition pubkey.h:349
PK_Verifier(const PK_Verifier &)=delete
bool check_signature(std::span< const uint8_t > sig)
Definition pubkey.h:372
PK_Verifier & operator=(const PK_Verifier &)=delete
int(* update)(CTX *, const void *, CC_LONG len)
int(* final)(unsigned char *, CTX *)
#define BOTAN_PUBLIC_API(maj, min)
Definition compiler.h:31
#define BOTAN_DEPRECATED(msg)
Definition compiler.h:125
std::string encrypt(const uint8_t input[], size_t input_len, std::string_view passphrase, RandomNumberGenerator &rng)
Definition cryptobox.cpp:42
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:61
Signature_Format
Definition pk_keys.h:31