Coverage Report

Created: 2020-05-23 13:54

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