Coverage Report

Created: 2022-06-23 06:44

/src/botan/build/include/botan/pk_keys.h
Line
Count
Source (jump to first uncovered line)
1
/*
2
* PK Key Types
3
* (C) 1999-2007,2018 Jack Lloyd
4
*
5
* Botan is released under the Simplified BSD License (see license.txt)
6
*/
7
8
#ifndef BOTAN_PK_KEYS_H_
9
#define BOTAN_PK_KEYS_H_
10
11
#include <botan/secmem.h>
12
#include <botan/asn1_obj.h>
13
#include <botan/pk_ops_fwd.h>
14
#include <string>
15
16
namespace Botan {
17
18
class RandomNumberGenerator;
19
20
/**
21
* The two types of signature format supported by Botan.
22
*/
23
enum Signature_Format { IEEE_1363, DER_SEQUENCE };
24
25
/**
26
* Public Key Base Class.
27
*/
28
class BOTAN_PUBLIC_API(2,0) Public_Key
29
   {
30
   public:
31
30.6k
      Public_Key() = default;
32
0
      Public_Key(const Public_Key& other) = default;
33
0
      Public_Key& operator=(const Public_Key& other) = default;
34
30.6k
      virtual ~Public_Key() = default;
35
36
      /**
37
      * Get the name of the underlying public key scheme.
38
      * @return name of the public key scheme
39
      */
40
      virtual std::string algo_name() const = 0;
41
42
      /**
43
      * Return the estimated strength of the underlying key against
44
      * the best currently known attack. Note that this ignores anything
45
      * but pure attacks against the key itself and do not take into
46
      * account padding schemes, usage mistakes, etc which might reduce
47
      * the strength. However it does suffice to provide an upper bound.
48
      *
49
      * @return estimated strength in bits
50
      */
51
      virtual size_t estimated_strength() const = 0;
52
53
      /**
54
      * Return an integer value best approximating the length of the
55
      * primary security parameter. For example for RSA this will be
56
      * the size of the modulus, for ECDSA the size of the ECC group,
57
      * and for McEliece the size of the code will be returned.
58
      */
59
      virtual size_t key_length() const = 0;
60
61
      /**
62
      * Get the OID of the underlying public key scheme.
63
      * @return OID of the public key scheme
64
      */
65
      virtual OID get_oid() const;
66
67
      /**
68
      * Test the key values for consistency.
69
      * @param rng rng to use
70
      * @param strong whether to perform strong and lengthy version
71
      * of the test
72
      * @return true if the test is passed
73
      */
74
      virtual bool check_key(RandomNumberGenerator& rng,
75
                             bool strong) const = 0;
76
77
78
      /**
79
      * @return X.509 AlgorithmIdentifier for this key
80
      */
81
      virtual AlgorithmIdentifier algorithm_identifier() const = 0;
82
83
      /**
84
      * @return BER encoded public key bits
85
      */
86
      virtual std::vector<uint8_t> public_key_bits() const = 0;
87
88
      /**
89
      * @return X.509 subject key encoding for this key object
90
      */
91
      std::vector<uint8_t> subject_public_key() const;
92
93
      /**
94
       * @return Hash of the subject public key
95
       */
96
      std::string fingerprint_public(const std::string& alg = "SHA-256") const;
97
98
      // Internal or non-public declarations follow
99
100
      /**
101
      * Returns more than 1 if the output of this algorithm
102
      * (ciphertext, signature) should be treated as more than one
103
      * value. This is used for algorithms like DSA and ECDSA, where
104
      * the (r,s) output pair can be encoded as either a plain binary
105
      * list or a TLV tagged DER encoding depending on the protocol.
106
      *
107
      * This function is public but applications should have few
108
      * reasons to ever call this.
109
      *
110
      * @return number of message parts
111
      */
112
12.5k
      virtual size_t message_parts() const { return 1; }
113
114
      /**
115
      * Returns how large each of the message parts refered to
116
      * by message_parts() is
117
      *
118
      * This function is public but applications should have few
119
      * reasons to ever call this.
120
      *
121
      * @return size of the message parts in bits
122
      */
123
6.23k
      virtual size_t message_part_size() const { return 0; }
124
125
      virtual Signature_Format default_x509_signature_format() const
126
6.85k
         {
127
6.85k
         return (this->message_parts() >= 2) ? DER_SEQUENCE : IEEE_1363;
128
6.85k
         }
129
130
      /**
131
      * This is an internal library function exposed on key types.
132
      * In almost all cases applications should use wrappers in pubkey.h
133
      *
134
      * Return an encryption operation for this key/params or throw
135
      *
136
      * @param rng a random number generator. The PK_Op may maintain a
137
      * reference to the RNG and use it many times. The rng must outlive
138
      * any operations which reference it.
139
      * @param params additional parameters
140
      * @param provider the provider to use
141
      */
142
      virtual std::unique_ptr<PK_Ops::Encryption>
143
         create_encryption_op(RandomNumberGenerator& rng,
144
                              const std::string& params,
145
                              const std::string& provider) const;
146
147
      /**
148
      * This is an internal library function exposed on key types.
149
      * In almost all cases applications should use wrappers in pubkey.h
150
      *
151
      * Return a KEM encryption operation for this key/params or throw
152
      *
153
      * @param rng a random number generator. The PK_Op may maintain a
154
      * reference to the RNG and use it many times. The rng must outlive
155
      * any operations which reference it.
156
      * @param params additional parameters
157
      * @param provider the provider to use
158
      */
159
      virtual std::unique_ptr<PK_Ops::KEM_Encryption>
160
         create_kem_encryption_op(RandomNumberGenerator& rng,
161
                                  const std::string& params,
162
                                  const std::string& provider) const;
163
164
      /**
165
      * This is an internal library function exposed on key types.
166
      * In almost all cases applications should use wrappers in pubkey.h
167
      *
168
      * Return a verification operation for this key/params or throw
169
      * @param params additional parameters
170
      * @param provider the provider to use
171
      */
172
      virtual std::unique_ptr<PK_Ops::Verification>
173
         create_verification_op(const std::string& params,
174
                                const std::string& provider) const;
175
   };
176
177
/**
178
* Private Key Base Class
179
*/
180
class BOTAN_PUBLIC_API(2,0) Private_Key : public virtual Public_Key
181
   {
182
   public:
183
22.3k
      Private_Key() = default;
184
0
      Private_Key(const Private_Key& other) = default;
185
0
      Private_Key& operator=(const Private_Key& other) = default;
186
22.3k
      virtual ~Private_Key() = default;
187
188
0
      virtual bool stateful_operation() const { return false; }
189
190
      /**
191
      * @return BER encoded private key bits
192
      */
193
      virtual secure_vector<uint8_t> private_key_bits() const = 0;
194
195
      /**
196
      * Allocate a new object for the public key associated with this
197
      * private key.
198
      *
199
      * @return public key
200
      */
201
      virtual std::unique_ptr<Public_Key> public_key() const = 0;
202
203
      /**
204
      * @return PKCS #8 private key encoding for this key object
205
      */
206
      secure_vector<uint8_t> private_key_info() const;
207
208
      /**
209
      * @return PKCS #8 AlgorithmIdentifier for this key
210
      * Might be different from the X.509 identifier, but normally is not
211
      */
212
      virtual AlgorithmIdentifier pkcs8_algorithm_identifier() const
213
0
         { return algorithm_identifier(); }
214
215
      // Internal or non-public declarations follow
216
217
      /**
218
       * @return Hash of the PKCS #8 encoding for this key object
219
       */
220
      std::string fingerprint_private(const std::string& alg) const;
221
222
      /**
223
      * This is an internal library function exposed on key types.
224
      * In almost all cases applications should use wrappers in pubkey.h
225
      *
226
      * Return an decryption operation for this key/params or throw
227
      *
228
      * @param rng a random number generator. The PK_Op may maintain a
229
      * reference to the RNG and use it many times. The rng must outlive
230
      * any operations which reference it.
231
      * @param params additional parameters
232
      * @param provider the provider to use
233
      *
234
      */
235
      virtual std::unique_ptr<PK_Ops::Decryption>
236
         create_decryption_op(RandomNumberGenerator& rng,
237
                              const std::string& params,
238
                              const std::string& provider) const;
239
240
      /**
241
      * This is an internal library function exposed on key types.
242
      * In almost all cases applications should use wrappers in pubkey.h
243
      *
244
      * Return a KEM decryption operation for this key/params or throw
245
      *
246
      * @param rng a random number generator. The PK_Op may maintain a
247
      * reference to the RNG and use it many times. The rng must outlive
248
      * any operations which reference it.
249
      * @param params additional parameters
250
      * @param provider the provider to use
251
      */
252
      virtual std::unique_ptr<PK_Ops::KEM_Decryption>
253
         create_kem_decryption_op(RandomNumberGenerator& rng,
254
                                  const std::string& params,
255
                                  const std::string& provider) const;
256
257
      /**
258
      * This is an internal library function exposed on key types.
259
      * In almost all cases applications should use wrappers in pubkey.h
260
      *
261
      * Return a signature operation for this key/params or throw
262
      *
263
      * @param rng a random number generator. The PK_Op may maintain a
264
      * reference to the RNG and use it many times. The rng must outlive
265
      * any operations which reference it.
266
      * @param params additional parameters
267
      * @param provider the provider to use
268
      */
269
      virtual std::unique_ptr<PK_Ops::Signature>
270
         create_signature_op(RandomNumberGenerator& rng,
271
                             const std::string& params,
272
                             const std::string& provider) const;
273
274
      /**
275
      * This is an internal library function exposed on key types.
276
      * In almost all cases applications should use wrappers in pubkey.h
277
      *
278
      * Return a key agreement operation for this key/params or throw
279
      *
280
      * @param rng a random number generator. The PK_Op may maintain a
281
      * reference to the RNG and use it many times. The rng must outlive
282
      * any operations which reference it.
283
      * @param params additional parameters
284
      * @param provider the provider to use
285
      */
286
      virtual std::unique_ptr<PK_Ops::Key_Agreement>
287
         create_key_agreement_op(RandomNumberGenerator& rng,
288
                                 const std::string& params,
289
                                 const std::string& provider) const;
290
   };
291
292
/**
293
* PK Secret Value Derivation Key
294
*/
295
class BOTAN_PUBLIC_API(2,0) PK_Key_Agreement_Key : public virtual Private_Key
296
   {
297
   public:
298
      /*
299
      * @return public component of this key
300
      */
301
      virtual std::vector<uint8_t> public_value() const = 0;
302
303
19.8k
      PK_Key_Agreement_Key() = default;
304
      PK_Key_Agreement_Key(const PK_Key_Agreement_Key&) = default;
305
      PK_Key_Agreement_Key& operator=(const PK_Key_Agreement_Key&) = default;
306
19.8k
      virtual ~PK_Key_Agreement_Key() = default;
307
   };
308
309
/*
310
* Old compat typedefs
311
* TODO: remove these?
312
*/
313
typedef PK_Key_Agreement_Key PK_KA_Key;
314
typedef Public_Key X509_PublicKey;
315
typedef Private_Key PKCS8_PrivateKey;
316
317
std::string BOTAN_PUBLIC_API(2,4)
318
   create_hex_fingerprint(const uint8_t bits[], size_t len,
319
                          const std::string& hash_name);
320
321
template<typename Alloc>
322
std::string create_hex_fingerprint(const std::vector<uint8_t, Alloc>& vec,
323
                                   const std::string& hash_name)
324
20.4k
   {
325
20.4k
   return create_hex_fingerprint(vec.data(), vec.size(), hash_name);
326
20.4k
   }
std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > Botan::create_hex_fingerprint<std::__1::allocator<unsigned char> >(std::__1::vector<unsigned char, std::__1::allocator<unsigned char> > const&, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > const&)
Line
Count
Source
324
20.4k
   {
325
20.4k
   return create_hex_fingerprint(vec.data(), vec.size(), hash_name);
326
20.4k
   }
Unexecuted instantiation: std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > Botan::create_hex_fingerprint<Botan::secure_allocator<unsigned char> >(std::__1::vector<unsigned char, Botan::secure_allocator<unsigned char> > const&, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > const&)
327
328
329
}
330
331
#endif