Coverage Report

Created: 2020-06-30 13:58

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