Botan  2.17.3
Crypto and TLS for C++11
pk_keys.h
Go to the documentation of this file.
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_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 */
24 
25 /**
26 * Public Key Base Class.
27 */
29  {
30  public:
31  Public_Key() =default;
32  Public_Key(const Public_Key& other) = default;
33  Public_Key& operator=(const Public_Key& other) = default;
34  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  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  virtual size_t message_part_size() const { return 0; }
124 
126  {
127  return (this->message_parts() >= 2) ? DER_SEQUENCE : IEEE_1363;
128  }
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  Private_Key() = default;
184  Private_Key(const Private_Key& other) = default;
185  Private_Key& operator=(const Private_Key& other) = default;
186  virtual ~Private_Key() = default;
187 
188  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  * @return PKCS #8 private key encoding for this key object
197  */
198  secure_vector<uint8_t> private_key_info() const;
199 
200  /**
201  * @return PKCS #8 AlgorithmIdentifier for this key
202  * Might be different from the X.509 identifier, but normally is not
203  */
205  { return algorithm_identifier(); }
206 
207  // Internal or non-public declarations follow
208 
209  /**
210  * @return Hash of the PKCS #8 encoding for this key object
211  */
212  std::string fingerprint_private(const std::string& alg) const;
213 
214  BOTAN_DEPRECATED("Use fingerprint_private or fingerprint_public")
215  inline std::string fingerprint(const std::string& alg) const
216  {
217  return fingerprint_private(alg); // match behavior in previous versions
218  }
219 
220  /**
221  * This is an internal library function exposed on key types.
222  * In almost all cases applications should use wrappers in pubkey.h
223  *
224  * Return an decryption operation for this key/params or throw
225  *
226  * @param rng a random number generator. The PK_Op may maintain a
227  * reference to the RNG and use it many times. The rng must outlive
228  * any operations which reference it.
229  * @param params additional parameters
230  * @param provider the provider to use
231  *
232  */
233  virtual std::unique_ptr<PK_Ops::Decryption>
234  create_decryption_op(RandomNumberGenerator& rng,
235  const std::string& params,
236  const std::string& provider) const;
237 
238  /**
239  * This is an internal library function exposed on key types.
240  * In almost all cases applications should use wrappers in pubkey.h
241  *
242  * Return a KEM decryption operation for this key/params or throw
243  *
244  * @param rng a random number generator. The PK_Op may maintain a
245  * reference to the RNG and use it many times. The rng must outlive
246  * any operations which reference it.
247  * @param params additional parameters
248  * @param provider the provider to use
249  */
250  virtual std::unique_ptr<PK_Ops::KEM_Decryption>
251  create_kem_decryption_op(RandomNumberGenerator& rng,
252  const std::string& params,
253  const std::string& provider) const;
254 
255  /**
256  * This is an internal library function exposed on key types.
257  * In almost all cases applications should use wrappers in pubkey.h
258  *
259  * Return a signature operation for this key/params or throw
260  *
261  * @param rng a random number generator. The PK_Op may maintain a
262  * reference to the RNG and use it many times. The rng must outlive
263  * any operations which reference it.
264  * @param params additional parameters
265  * @param provider the provider to use
266  */
267  virtual std::unique_ptr<PK_Ops::Signature>
268  create_signature_op(RandomNumberGenerator& rng,
269  const std::string& params,
270  const std::string& provider) const;
271 
272  /**
273  * This is an internal library function exposed on key types.
274  * In almost all cases applications should use wrappers in pubkey.h
275  *
276  * Return a key agreement operation for this key/params or throw
277  *
278  * @param rng a random number generator. The PK_Op may maintain a
279  * reference to the RNG and use it many times. The rng must outlive
280  * any operations which reference it.
281  * @param params additional parameters
282  * @param provider the provider to use
283  */
284  virtual std::unique_ptr<PK_Ops::Key_Agreement>
285  create_key_agreement_op(RandomNumberGenerator& rng,
286  const std::string& params,
287  const std::string& provider) const;
288  };
289 
290 /**
291 * PK Secret Value Derivation Key
292 */
294  {
295  public:
296  /*
297  * @return public component of this key
298  */
299  virtual std::vector<uint8_t> public_value() const = 0;
300 
301  PK_Key_Agreement_Key() = default;
302  PK_Key_Agreement_Key(const PK_Key_Agreement_Key&) = default;
303  PK_Key_Agreement_Key& operator=(const PK_Key_Agreement_Key&) = default;
304  virtual ~PK_Key_Agreement_Key() = default;
305  };
306 
307 /*
308 * Old compat typedefs
309 * TODO: remove these?
310 */
314 
315 std::string BOTAN_PUBLIC_API(2,4)
316  create_hex_fingerprint(const uint8_t bits[], size_t len,
317  const std::string& hash_name);
318 
319 template<typename Alloc>
320 std::string create_hex_fingerprint(const std::vector<uint8_t, Alloc>& vec,
321  const std::string& hash_name)
322  {
323  return create_hex_fingerprint(vec.data(), vec.size(), hash_name);
324  }
325 
326 
327 }
328 
329 #endif
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:31
Signature_Format
Definition: pk_keys.h:23
Definition: bigint.h:1143
Private_Key PKCS8_PrivateKey
Definition: pk_keys.h:313
Public_Key X509_PublicKey
Definition: pk_keys.h:312
PK_Key_Agreement_Key PK_KA_Key
Definition: pk_keys.h:311
virtual Signature_Format default_x509_signature_format() const
Definition: pk_keys.h:125
virtual size_t message_part_size() const
Definition: pk_keys.h:123
Definition: alg_id.cpp:13
std::string create_hex_fingerprint(const uint8_t bits[], size_t bits_len, const std::string &hash_name)
Definition: pk_keys.cpp:17
std::vector< T, secure_allocator< T > > secure_vector
Definition: secmem.h:65
virtual bool stateful_operation() const
Definition: pk_keys.h:188
virtual AlgorithmIdentifier pkcs8_algorithm_identifier() const
Definition: pk_keys.h:204
virtual size_t message_parts() const
Definition: pk_keys.h:112