Coverage Report

Created: 2021-05-04 09:02

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