Botan 3.14.1
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/pk_keys.h>
12#include <botan/pk_ops_fwd.h>
13#include <botan/pk_options.h>
14#include <botan/symkey.h>
15#include <span>
16#include <string>
17#include <string_view>
18#include <utility>
19
20namespace Botan {
21
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 ptext_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 /**
138 * Return an upper bound on the ciphertext length for a particular
139 * plaintext input length.
140 */
141 virtual size_t ciphertext_length(size_t ptext_len) const = 0;
142
143 PK_Decryptor() = default;
144 virtual ~PK_Decryptor() = default;
145
146 PK_Decryptor(const PK_Decryptor&) = delete;
148
149 PK_Decryptor(PK_Decryptor&&) noexcept = default;
150 PK_Decryptor& operator=(PK_Decryptor&&) noexcept = default;
151
152 private:
153 /**
154 * Decrypt a ciphertext, writing the plaintext to the start of ptext
155 *
156 * @param valid_mask set to 0xFF if the ciphertext was valid, otherwise 0
157 * @param ptext the output, which is at least plaintext_length(ctext.size())
158 * bytes long
159 * @param ctext the ciphertext
160 * @return the length of the plaintext, which is meaningless if the
161 * ciphertext was invalid
162 *
163 * decrypt_or_random relies on neither the validity of the ciphertext nor
164 * the length of the plaintext being revealed.
165 */
166 virtual size_t do_decrypt(uint8_t& valid_mask,
167 std::span<uint8_t> ptext,
168 std::span<const uint8_t> ctext) const = 0;
169};
170
171/**
172* Public Key Signer. Use the sign_message() functions for small
173* messages. Use multiple calls update() to process large messages and
174* generate the signature by finally calling signature().
175*/
176class BOTAN_PUBLIC_API(2, 0) PK_Signer final {
177 public:
178 /**
179 * Construct a PK signer
180 *
181 * @param key the key to use to generate signatures
182 * @param rng a RNG object which must outlive this operation object
183 * @param options controls the behavior of the signature generation, eg which hash function to use
184 *
185 * Note that most common algorithms (eg RSA or ECDSA) require an options
186 * parameter to specify at least which hash function to use. Schemes without
187 * any parameters (eg Ed25519, ML-DSA, XMSS) can be used with the default.
188 */
189 PK_Signer(const Private_Key& key,
191 const PK_Signature_Options& options = PK_Signature_Options());
192
193 /**
194 * Construct a PK Signer.
195 * @param key the key to use inside this signer
196 * @param rng a RNG object which must outlive this operation object
197 * @param padding the padding/hash to use, eg "SHA-512" or "PSS(SHA-256)"
198 * @param format the signature format to use
199 * @param provider the provider to use
200 */
201 PK_Signer(const Private_Key& key,
203 std::string_view padding,
205 std::string_view provider = "");
206
208
209 PK_Signer(const PK_Signer&) = delete;
210 PK_Signer& operator=(const PK_Signer&) = delete;
211
212 PK_Signer(PK_Signer&&) noexcept;
213 PK_Signer& operator=(PK_Signer&&) noexcept;
214
215 /**
216 * Sign a message all in one go
217 * @param in the message to sign as a byte array
218 * @param length the length of the above byte array
219 * @param rng the rng to use
220 * @return signature
221 */
222 std::vector<uint8_t> sign_message(const uint8_t in[], size_t length, RandomNumberGenerator& rng) {
223 this->update(in, length);
224 return this->signature(rng);
225 }
226
227 /**
228 * Sign a message.
229 * @param in the message to sign
230 * @param rng the rng to use
231 * @return signature
232 */
233 std::vector<uint8_t> sign_message(std::span<const uint8_t> in, RandomNumberGenerator& rng) {
234 return sign_message(in.data(), in.size(), rng);
235 }
236
237 /**
238 * Add a message part (single byte).
239 * @param in the byte to add
240 */
241 void update(uint8_t in) { update(&in, 1); }
242
243 /**
244 * Add a message part.
245 * @param in the message part to add as a byte array
246 * @param length the length of the above byte array
247 */
248 void update(const uint8_t in[], size_t length);
249
250 /**
251 * Add a message part.
252 * @param in the message part to add
253 */
254 void update(std::span<const uint8_t> in) { update(in.data(), in.size()); }
255
256 /**
257 * Add a message part.
258 * @param in the message part to add
259 */
260 void update(std::string_view in);
261
262 /**
263 * Get the signature of the so far processed message (provided by the
264 * calls to update()).
265 * @param rng the rng to use
266 * @return signature of the total message
267 */
268 std::vector<uint8_t> signature(RandomNumberGenerator& rng);
269
270 /**
271 * Set the output format of the signature.
272 * @param format the signature format to use
273 */
274 void set_output_format(Signature_Format format);
275
276 /**
277 * Return an upper bound on the length of the signatures this
278 * PK_Signer will produce
279 */
280 size_t signature_length() const;
281
282 /**
283 * Return an AlgorithmIdentifier appropriate for identifying the signature
284 * method being generated by this PK_Signer. Throws an exception if this
285 * is not available for the current signature scheme.
286 */
287 AlgorithmIdentifier algorithm_identifier() const;
288
289 /**
290 * Return the hash function which is being used to create signatures.
291 * This should never return an empty string however it may return a string
292 * which does not map directly to a hash function, in particular if "Raw"
293 * (unhashed) encoding is being used.
294 */
295 std::string hash_function() const;
296
297 private:
298 std::unique_ptr<PK_Ops::Signature> m_op;
299 Signature_Format m_sig_format;
300 std::optional<size_t> m_sig_element_size;
301};
302
303/**
304* Public Key Verifier. Use the verify_message() functions for small
305* messages. Use multiple calls update() to process large messages and
306* verify the signature by finally calling check_signature().
307*/
308class BOTAN_PUBLIC_API(2, 0) PK_Verifier final {
309 public:
310 /**
311 * Construct a PK Verifier.
312 * @param pub_key the public key to verify against
313 * @param options relating to the signature; schemes without any parameters
314 * (eg Ed25519, ML-DSA, XMSS) can be used with the default.
315 */
316 explicit PK_Verifier(const Public_Key& pub_key, const PK_Signature_Options& options = PK_Signature_Options());
317
318 /**
319 * Construct a PK Verifier.
320 * @param pub_key the public key to verify against
321 * @param padding the padding/hash to use (eg "EMSA_PKCS1(SHA-256)")
322 * @param format the signature format to use
323 * @param provider the provider to use
324 */
325 PK_Verifier(const Public_Key& pub_key,
326 std::string_view padding,
328 std::string_view provider = "");
329
330 /**
331 * Construct a PK Verifier (X.509 specific)
332 *
333 * This constructor will attempt to decode signature_format relative
334 * to the public key provided. If they seem to be inconsistent or
335 * otherwise unsupported, a Decoding_Error is thrown.
336 *
337 * @param pub_key the public key to verify against
338 * @param signature_algorithm the supposed signature algorithm
339 * @param provider the provider to use
340 */
341 PK_Verifier(const Public_Key& pub_key,
342 const AlgorithmIdentifier& signature_algorithm,
343 std::string_view provider = "");
344
346
347 PK_Verifier(const PK_Verifier&) = delete;
349
351 PK_Verifier& operator=(PK_Verifier&&) noexcept;
352
353 /**
354 * Verify a signature.
355 * @param msg the message that the signature belongs to, as a byte array
356 * @param msg_length the length of the above byte array msg
357 * @param sig the signature as a byte array
358 * @param sig_length the length of the above byte array sig
359 * @return true if the signature is valid
360 */
361 bool verify_message(const uint8_t msg[], size_t msg_length, const uint8_t sig[], size_t sig_length);
362
363 /**
364 * Verify a signature.
365 * @param msg the message that the signature belongs to
366 * @param sig the signature
367 * @return true if the signature is valid
368 */
369 bool verify_message(std::span<const uint8_t> msg, std::span<const uint8_t> sig) {
370 return verify_message(msg.data(), msg.size(), sig.data(), sig.size());
371 }
372
373 /**
374 * Add a message part (single byte) of the message corresponding to the
375 * signature to be verified.
376 * @param in the byte to add
377 */
378 void update(uint8_t in) { update(&in, 1); }
379
380 /**
381 * Add a message part of the message corresponding to the
382 * signature to be verified.
383 * @param msg_part the new message part as a byte array
384 * @param length the length of the above byte array
385 */
386 void update(const uint8_t msg_part[], size_t length);
387
388 /**
389 * Add a message part of the message corresponding to the
390 * signature to be verified.
391 * @param in the new message part
392 */
393 void update(std::span<const uint8_t> in) { update(in.data(), in.size()); }
394
395 /**
396 * Add a message part of the message corresponding to the
397 * signature to be verified.
398 */
399 void update(std::string_view in);
400
401 /**
402 * Check the signature of the buffered message, i.e. the one build
403 * by successive calls to update.
404 * @param sig the signature to be verified as a byte array
405 * @param length the length of the above byte array
406 * @return true if the signature is valid, false otherwise
407 */
408 bool check_signature(const uint8_t sig[], size_t length);
409
410 /**
411 * Check the signature of the buffered message, i.e. the one build
412 * by successive calls to update.
413 * @param sig the signature to be verified
414 * @return true if the signature is valid, false otherwise
415 */
416 bool check_signature(std::span<const uint8_t> sig) { return check_signature(sig.data(), sig.size()); }
417
418 /**
419 * Set the format of the signatures fed to this verifier.
420 * @param format the signature format to use
421 */
422 BOTAN_DEPRECATED("Provide Signature_Format to the constructor") void set_input_format(Signature_Format format);
423
424 /**
425 * Return the hash function which is being used to verify signatures.
426 * This should never return an empty string however it may return a string
427 * which does not map directly to a hash function, in particular if "Raw"
428 * (unhashed) encoding is being used.
429 */
430 std::string hash_function() const;
431
432 private:
433 std::unique_ptr<PK_Ops::Verification> m_op;
434 Signature_Format m_sig_format;
435 std::optional<size_t> m_sig_element_size;
436};
437
438/**
439* Object used for key agreement
440*/
442 public:
443 /**
444 * Construct a PK Key Agreement.
445 * @param key the key to use
446 * @param rng a RNG object which must outlive this operation object
447 * @param options controls the behavior of the key agreement, eg which KDF to use
448 */
450
451 /**
452 * Construct a PK Key Agreement.
453 * @param key the key to use
454 * @param rng a RNG object which must outlive this operation object
455 * @param kdf name of the KDF to use (or 'Raw' for no KDF)
456 * @param provider the algo provider to use (or empty for default)
457 */
458 PK_Key_Agreement(const Private_Key& key,
460 std::string_view kdf,
461 std::string_view provider = "");
462
464
467
469 PK_Key_Agreement& operator=(PK_Key_Agreement&&) noexcept;
470
471 /**
472 * Perform Key Agreement Operation
473 * @param key_len the desired key output size (ignored if "Raw" KDF is used)
474 * @param peer_key the other parties key
475 * @param salt extra derivation salt
476 */
477 SymmetricKey derive_key(size_t key_len, std::span<const uint8_t> peer_key, std::span<const uint8_t> salt) const;
478
479 /**
480 * Perform Key Agreement Operation
481 * @param key_len the desired key output size (ignored if "Raw" KDF is used)
482 * @param peer_key the other parties key
483 * @param peer_key_len the length of peer_key in bytes
484 * @param salt extra derivation salt
485 * @param salt_len the length of salt in bytes
486 */
488 size_t key_len, const uint8_t peer_key[], size_t peer_key_len, const uint8_t salt[], size_t salt_len) const {
489 return this->derive_key(key_len, {peer_key, peer_key_len}, {salt, salt_len});
490 }
491
492 /**
493 * Perform Key Agreement Operation
494 * @param key_len the desired key output size (ignored if "Raw" KDF is used)
495 * @param peer_key the other parties key
496 * @param salt extra derivation salt
497 * @param salt_len the length of salt in bytes
498 */
499 SymmetricKey derive_key(size_t key_len,
500 std::span<const uint8_t> peer_key,
501 const uint8_t salt[],
502 size_t salt_len) const {
503 return derive_key(key_len, peer_key.data(), peer_key.size(), salt, salt_len);
504 }
505
506 /**
507 * Perform Key Agreement Operation
508 * @param key_len the desired key output size (ignored if "Raw" KDF is used)
509 * @param peer_key the other parties key
510 * @param peer_key_len the length of peer_key in bytes
511 * @param salt extra derivation info
512 */
513 SymmetricKey derive_key(size_t key_len,
514 const uint8_t peer_key[],
515 size_t peer_key_len,
516 std::string_view salt = "") const;
517
518 /**
519 * Perform Key Agreement Operation
520 * @param key_len the desired key output size (ignored if "Raw" KDF is used)
521 * @param peer_key the other parties key
522 * @param salt extra derivation info
523 */
524 SymmetricKey derive_key(size_t key_len, std::span<const uint8_t> peer_key, std::string_view salt = "") const;
525
526 /**
527 * Return the underlying size of the value that is agreed.
528 * If derive_key is called with a length of 0 with a "Raw"
529 * KDF, it will return a value of this size.
530 */
531 size_t agreed_value_size() const;
532
533 private:
534 std::unique_ptr<PK_Ops::Key_Agreement> m_op;
535};
536
537/**
538* Encryption using a standard message recovery algorithm like RSA or
539* ElGamal, paired with an encoding scheme like OAEP.
540*/
542 public:
543 size_t maximum_input_size() const override;
544
545 /**
546 * Construct an instance.
547 * @param key the key to use inside the encryptor
548 * @param rng a RNG object which must outlive this operation object
549 * @param options controls the behavior of the encryption, eg which padding to use
550 *
551 * Note that RSA requires the options to specify at least a padding scheme,
552 * and for OAEP also a hash function.
553 */
555
556 /**
557 * Construct an instance.
558 * @param key the key to use inside the encryptor
559 * @param rng a RNG object which must outlive this operation object
560 * @param padding the message encoding scheme to use (eg "OAEP(SHA-256)")
561 * @param provider the provider to use
562 */
563 PK_Encryptor_EME(const Public_Key& key,
565 std::string_view padding,
566 std::string_view provider = "");
567
569
572
574 PK_Encryptor_EME& operator=(PK_Encryptor_EME&&) noexcept;
575
576 /**
577 * Return an upper bound on the ciphertext length for a particular
578 * plaintext input length
579 */
580 size_t ciphertext_length(size_t ptext_len) const override;
581
582 private:
583 std::vector<uint8_t> enc(const uint8_t ptext[], size_t len, RandomNumberGenerator& rng) const override;
584
585 std::unique_ptr<PK_Ops::Encryption> m_op;
586};
587
588/**
589* Decryption with a padding scheme.
590*
591* This is typically only used with RSA
592*/
594 public:
595 /**
596 * Construct an instance.
597 * @param key the key to use inside the decryptor
598 * @param rng a RNG object which must outlive this operation object
599 * @param options controls the behavior of the decryption, eg which padding to use
600 */
602
603 /**
604 * Construct an instance.
605 * @param key the key to use inside the decryptor
606 * @param rng a RNG object which must outlive this operation object
607 * @param padding the padding scheme to use
608 * @param provider the provider to use
609 */
610 PK_Decryptor_EME(const Private_Key& key,
612 std::string_view padding,
613 std::string_view provider = "");
614
615 size_t plaintext_length(size_t ctext_len) const override;
616
617 size_t ciphertext_length(size_t ptext_len) const override;
618
620
623
625 PK_Decryptor_EME& operator=(PK_Decryptor_EME&&) noexcept;
626
627 private:
628 size_t do_decrypt(uint8_t& valid_mask, std::span<uint8_t> ptext, std::span<const uint8_t> ctext) const override;
629
630 std::unique_ptr<PK_Ops::Decryption> m_op;
631};
632
633/**
634* Result of a key encapsulation operation.
635*/
636class KEM_Encapsulation final {
637 public:
639 m_encapsulated_shared_key(std::move(encapsulated_shared_key)), m_shared_key(std::move(shared_key)) {}
640
641 /**
642 * @returns the encapsulated shared secret (encrypted with the public key)
643 */
644 const std::vector<uint8_t>& encapsulated_shared_key() const { return m_encapsulated_shared_key; }
645
646 /**
647 * @returns the plaintext shared secret
648 */
649 const secure_vector<uint8_t>& shared_key() const { return m_shared_key; }
650
651 /**
652 * @returns the pair (encapsulated key, key) extracted from @p kem
653 */
654 static std::pair<std::vector<uint8_t>, secure_vector<uint8_t>> destructure(
655 KEM_Encapsulation&& kem) /* NOLINT(*param-not-moved*) */ {
656 return std::make_pair(std::exchange(kem.m_encapsulated_shared_key, {}), std::exchange(kem.m_shared_key, {}));
657 }
658
659 private:
660 friend class PK_KEM_Encryptor;
661
662 KEM_Encapsulation(size_t encapsulated_size, size_t shared_key_size) :
663 m_encapsulated_shared_key(encapsulated_size), m_shared_key(shared_key_size) {}
664
665 private:
666 std::vector<uint8_t> m_encapsulated_shared_key;
667 secure_vector<uint8_t> m_shared_key;
668};
669
670/**
671* Public Key Key Encapsulation Mechanism Encryption.
672*/
674 public:
675 /**
676 * Construct an instance.
677 * @param key the key to encrypt to
678 * @param options controls the behavior of the KEM, eg which KDF to use
679 */
680 PK_KEM_Encryptor(const Public_Key& key, const PK_KEM_Options& options);
681
682 /**
683 * Construct an instance.
684 * @param key the key to encrypt to
685 * @param kem_param additional KEM parameters
686 * @param provider the provider to use
687 */
689 std::string_view kem_param = "",
690 std::string_view provider = "");
691
692 /**
693 * Construct an instance.
694 * @param key the key to encrypt to
695 * @param rng a RNG object which must outlive this operation object
696 * @param kem_param additional KEM parameters
697 * @param provider the provider to use
698 */
699 BOTAN_DEPRECATED("Use constructor that does not take RNG")
700 PK_KEM_Encryptor(const Public_Key& key,
702 std::string_view kem_param = "",
703 std::string_view provider = "");
704
706
709
711 PK_KEM_Encryptor& operator=(PK_KEM_Encryptor&&) noexcept;
712
713 /**
714 * Return the length of the shared key returned by this KEM
715 *
716 * If this KEM was used with a KDF, then it will always return
717 * exactly the desired key length, because the output of the KEM
718 * will be hashed by the KDF.
719 *
720 * However if the KEM was used without a KDF (with_raw_shared_key, or
721 * the legacy "Raw" kdf string), to request the algorithmic output of
722 * the KEM directly, then the desired key length will be ignored and
723 * a bytestring that depends on the algorithm is returned
724 *
725 * @param desired_shared_key_len is the requested length
726 */
727 size_t shared_key_length(size_t desired_shared_key_len) const;
728
729 /**
730 * Return the length in bytes of encapsulated keys returned by this KEM
731 */
732 size_t encapsulated_key_length() const;
733
734 /**
735 * Generate a shared key for data encryption.
736 *
737 * @param rng the RNG to use
738 * @param desired_shared_key_len desired size of the shared key in bytes for the KDF
739 * (ignored if no KDF is used)
740 * @param salt a salt value used in the KDF
741 * (ignored if no KDF is used)
742 *
743 * @returns a struct with both the shared secret and its encapsulation
744 */
746 size_t desired_shared_key_len = 32,
747 std::span<const uint8_t> salt = {}) {
748 std::vector<uint8_t> encapsulated_shared_key(encapsulated_key_length());
749 secure_vector<uint8_t> shared_key(shared_key_length(desired_shared_key_len));
750
751 encrypt(std::span{encapsulated_shared_key}, std::span{shared_key}, rng, desired_shared_key_len, salt);
752 return KEM_Encapsulation(std::move(encapsulated_shared_key), std::move(shared_key));
753 }
754
755 /**
756 * Generate a shared key for data encryption.
757 * @param out_encapsulated_key the generated encapsulated key
758 * @param out_shared_key the generated shared key
759 * @param rng the RNG to use
760 * @param desired_shared_key_len desired size of the shared key in bytes
761 * (ignored if no KDF is used)
762 * @param salt a salt value used in the KDF
763 * (ignored if no KDF is used)
764 */
765 void encrypt(secure_vector<uint8_t>& out_encapsulated_key,
766 secure_vector<uint8_t>& out_shared_key,
768 size_t desired_shared_key_len = 32,
769 std::span<const uint8_t> salt = {}) {
770 out_encapsulated_key.resize(encapsulated_key_length());
771 out_shared_key.resize(shared_key_length(desired_shared_key_len));
772 encrypt(std::span{out_encapsulated_key}, std::span{out_shared_key}, rng, desired_shared_key_len, salt);
773 }
774
775 /**
776 * Generate a shared key for data encryption.
777 * @param out_encapsulated_key the generated encapsulated key
778 * @param out_shared_key the generated shared key
779 * @param rng the RNG to use
780 * @param desired_shared_key_len desired size of the shared key in bytes
781 * (ignored if no KDF is used)
782 * @param salt a salt value used in the KDF
783 * (ignored if no KDF is used)
784 */
785 void encrypt(std::span<uint8_t> out_encapsulated_key,
786 std::span<uint8_t> out_shared_key,
787 RandomNumberGenerator& rng,
788 size_t desired_shared_key_len = 32,
789 std::span<const uint8_t> salt = {});
790
791 BOTAN_DEPRECATED("use overload with salt as std::span<>")
792 void encrypt(secure_vector<uint8_t>& out_encapsulated_key,
793 secure_vector<uint8_t>& out_shared_key,
794 size_t desired_shared_key_len,
796 const uint8_t salt[],
797 size_t salt_len) {
798 this->encrypt(out_encapsulated_key, out_shared_key, rng, desired_shared_key_len, {salt, salt_len});
799 }
800
801 BOTAN_DEPRECATED("use overload where rng comes after the out-parameters")
802 void encrypt(secure_vector<uint8_t>& out_encapsulated_key,
803 secure_vector<uint8_t>& out_shared_key,
804 size_t desired_shared_key_len,
806 std::span<const uint8_t> salt = {}) {
807 out_encapsulated_key.resize(encapsulated_key_length());
808 out_shared_key.resize(shared_key_length(desired_shared_key_len));
809 encrypt(out_encapsulated_key, out_shared_key, rng, desired_shared_key_len, salt);
810 }
811
812 private:
813 std::unique_ptr<PK_Ops::KEM_Encryption> m_op;
814};
815
816/**
817* Public Key Key Encapsulation Mechanism Decryption.
818*/
820 public:
821 /**
822 * Construct an instance.
823 * @param key the key to use inside the decryptor
824 * @param rng a RNG object which must outlive this operation object
825 * @param options controls the behavior of the KEM, eg which KDF to use
826 */
827 PK_KEM_Decryptor(const Private_Key& key, RandomNumberGenerator& rng, const PK_KEM_Options& options);
828
829 /**
830 * Construct an instance.
831 * @param key the key to use inside the decryptor
832 * @param rng a RNG object which must outlive this operation object
833 * @param kem_param additional KEM parameters
834 * @param provider the provider to use
835 */
836 PK_KEM_Decryptor(const Private_Key& key,
838 std::string_view kem_param = "",
839 std::string_view provider = "");
840
844
846 PK_KEM_Decryptor& operator=(PK_KEM_Decryptor&&) noexcept;
847
848 /**
849 * Return the length of the shared key returned by this KEM
850 *
851 * If this KEM was used with a KDF, then it will always return
852 * exactly the desired key length, because the output of the KEM
853 * will be hashed by the KDF.
854 *
855 * However if the KEM was used without a KDF (with_raw_shared_key, or
856 * the legacy "Raw" kdf string), to request the algorithmic output of
857 * the KEM directly, then the desired key length will be ignored and
858 * a bytestring that depends on the algorithm is returned
859 *
860 * @param desired_shared_key_len is the requested length.
861 */
862 size_t shared_key_length(size_t desired_shared_key_len) const;
863
864 /**
865 * Return the length of the encapsulated key expected by this KEM
866 */
867 size_t encapsulated_key_length() const;
868
869 /**
870 * Decrypts the shared key for data encryption.
871 *
872 * @param out_shared_key the generated shared key
873 * @param encap_key the encapsulated key
874 * @param desired_shared_key_len desired size of the shared key in bytes
875 * (ignored if no KDF is used)
876 * @param salt a salt value used in the KDF
877 * (ignored if no KDF is used)
878 */
879 void decrypt(std::span<uint8_t> out_shared_key,
880 std::span<const uint8_t> encap_key,
881 size_t desired_shared_key_len = 32,
882 std::span<const uint8_t> salt = {});
883
884 /**
885 * Decrypts the shared key for data encryption.
886 *
887 * @param encap_key the encapsulated key
888 * @param encap_key_len size of the encapsulated key in bytes
889 * @param desired_shared_key_len desired size of the shared key in bytes
890 * (ignored if no KDF is used)
891 * @param salt a salt value used in the KDF
892 * (ignored if no KDF is used)
893 * @param salt_len size of the salt value in bytes
894 * (ignored if no KDF is used)
895 *
896 * @return the shared data encryption key
897 */
898 secure_vector<uint8_t> decrypt(const uint8_t encap_key[],
899 size_t encap_key_len,
900 size_t desired_shared_key_len,
901 const uint8_t salt[] = nullptr,
902 size_t salt_len = 0) {
903 secure_vector<uint8_t> shared_key(shared_key_length(desired_shared_key_len));
904 decrypt(shared_key, {encap_key, encap_key_len}, desired_shared_key_len, {salt, salt_len});
905 return shared_key;
906 }
907
908 /**
909 * Decrypts the shared key for data encryption.
910 *
911 * @param encap_key the encapsulated key
912 * @param desired_shared_key_len desired size of the shared key in bytes
913 * (ignored if no KDF is used)
914 * @param salt a salt value used in the KDF
915 * (ignored if no KDF is used)
916 *
917 * @return the shared data encryption key
918 */
919 secure_vector<uint8_t> decrypt(std::span<const uint8_t> encap_key,
920 size_t desired_shared_key_len = 32,
921 std::span<const uint8_t> salt = {}) {
922 secure_vector<uint8_t> shared_key(shared_key_length(desired_shared_key_len));
923 decrypt(shared_key, encap_key, desired_shared_key_len, salt);
924 return shared_key;
925 }
926
927 private:
928 std::unique_ptr<PK_Ops::KEM_Decryption> m_op;
929};
930
931} // namespace Botan
932
933#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
#define BOTAN_DEPRECATED(msg)
Definition api.h:73
#define BOTAN_FUTURE_EXPLICIT
Definition api.h:52
KEM_Encapsulation(std::vector< uint8_t > encapsulated_shared_key, secure_vector< uint8_t > shared_key)
Definition pubkey.h:638
const secure_vector< uint8_t > & shared_key() const
Definition pubkey.h:649
friend class PK_KEM_Encryptor
Definition pubkey.h:660
static std::pair< std::vector< uint8_t >, secure_vector< uint8_t > > destructure(KEM_Encapsulation &&kem)
Definition pubkey.h:654
const std::vector< uint8_t > & encapsulated_shared_key() const
Definition pubkey.h:644
PK_Decryptor_EME(const Private_Key &key, RandomNumberGenerator &rng, const PK_Encryption_Options &options)
Definition pubkey.cpp:147
~PK_Decryptor_EME() override
PK_Decryptor_EME(PK_Decryptor_EME &&) noexcept
PK_Decryptor_EME(const PK_Decryptor_EME &)=delete
size_t plaintext_length(size_t ctext_len) const override
Definition pubkey.cpp:165
PK_Decryptor_EME & operator=(const PK_Decryptor_EME &)=delete
size_t ciphertext_length(size_t ptext_len) const override
Definition pubkey.cpp:169
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
virtual size_t ciphertext_length(size_t ptext_len) const =0
PK_Decryptor()=default
secure_vector< uint8_t > decrypt(const uint8_t in[], size_t length) const
Definition pubkey.cpp:24
PK_Decryptor(const PK_Decryptor &)=delete
~PK_Encryptor_EME() override
PK_Encryptor_EME(const Public_Key &key, RandomNumberGenerator &rng, const PK_Encryption_Options &options)
Definition pubkey.cpp:111
size_t maximum_input_size() const override
Definition pubkey.cpp:137
PK_Encryptor_EME & operator=(const PK_Encryptor_EME &)=delete
size_t ciphertext_length(size_t ptext_len) const override
Definition pubkey.cpp:129
PK_Encryptor_EME(PK_Encryptor_EME &&) noexcept
PK_Encryptor_EME(const PK_Encryptor_EME &)=delete
virtual size_t ciphertext_length(size_t ptext_len) const =0
PK_Encryptor & operator=(const PK_Encryptor &)=delete
virtual size_t maximum_input_size() 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:898
size_t encapsulated_key_length() const
Definition pubkey.cpp:229
PK_KEM_Decryptor(PK_KEM_Decryptor &&) noexcept
PK_KEM_Decryptor(const Private_Key &key, RandomNumberGenerator &rng, const PK_KEM_Options &options)
Definition pubkey.cpp:239
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:919
size_t shared_key_length(size_t desired_shared_key_len) const
Definition pubkey.cpp:225
void decrypt(std::span< uint8_t > out_shared_key, std::span< const uint8_t > encap_key, size_t desired_shared_key_len=32, std::span< const uint8_t > salt={})
Definition pubkey.cpp:255
PK_KEM_Encryptor(const Public_Key &key, const PK_KEM_Options &options)
Definition pubkey.cpp:182
KEM_Encapsulation encrypt(RandomNumberGenerator &rng, size_t desired_shared_key_len=32, std::span< const uint8_t > salt={})
Definition pubkey.h:745
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:765
PK_KEM_Encryptor(PK_KEM_Encryptor &&) noexcept
size_t shared_key_length(size_t desired_shared_key_len) const
Definition pubkey.cpp:206
size_t encapsulated_key_length() const
Definition pubkey.cpp:210
PK_KEM_Encryptor(const PK_KEM_Encryptor &)=delete
PK_KEM_Encryptor & operator=(const PK_KEM_Encryptor &)=delete
SymmetricKey derive_key(size_t key_len, std::span< const uint8_t > peer_key, std::span< const uint8_t > salt) const
Definition pubkey.cpp:305
PK_Key_Agreement(const Private_Key &key, RandomNumberGenerator &rng, const PK_Key_Agreement_Options &options)
Definition pubkey.cpp:270
SymmetricKey derive_key(size_t key_len, std::span< const uint8_t > peer_key, const uint8_t salt[], size_t salt_len) const
Definition pubkey.h:499
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:241
std::vector< uint8_t > sign_message(std::span< const uint8_t > in, RandomNumberGenerator &rng)
Definition pubkey.h:233
PK_Signer(const Private_Key &key, RandomNumberGenerator &rng, const PK_Signature_Options &options=PK_Signature_Options())
Definition pubkey.cpp:322
void update(std::span< const uint8_t > in)
Definition pubkey.h:254
std::vector< uint8_t > signature(RandomNumberGenerator &rng)
Definition pubkey.cpp:433
PK_Signer & operator=(const PK_Signer &)=delete
PK_Signer(const PK_Signer &)=delete
std::vector< uint8_t > sign_message(const uint8_t in[], size_t length, RandomNumberGenerator &rng)
Definition pubkey.h:222
PK_Verifier(const Public_Key &pub_key, const PK_Signature_Options &options=PK_Signature_Options())
Definition pubkey.cpp:454
PK_Verifier(PK_Verifier &&) noexcept
void update(uint8_t in)
Definition pubkey.h:378
bool verify_message(const uint8_t msg[], size_t msg_length, const uint8_t sig[], size_t sig_length)
Definition pubkey.cpp:501
void update(std::span< const uint8_t > in)
Definition pubkey.h:393
PK_Verifier(const PK_Verifier &)=delete
bool check_signature(std::span< const uint8_t > sig)
Definition pubkey.h:416
PK_Verifier & operator=(const PK_Verifier &)=delete
std::string encrypt(const uint8_t input[], size_t input_len, std::string_view passphrase, RandomNumberGenerator &rng)
Definition cryptobox.cpp:44
OctetString SymmetricKey
Definition symkey.h:153
Signature_Format
Definition pk_keys.h:36
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128