Botan  2.12.1
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_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 */
25 
26 /**
27 * Public Key Base Class.
28 */
30  {
31  public:
32  Public_Key() =default;
33  Public_Key(const Public_Key& other) = default;
34  Public_Key& operator=(const Public_Key& other) = default;
35  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  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  virtual size_t message_part_size() const { return 0; }
125 
127  {
128  return (this->message_parts() >= 2) ? DER_SEQUENCE : IEEE_1363;
129  }
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  Private_Key() = default;
185  Private_Key(const Private_Key& other) = default;
186  Private_Key& operator=(const Private_Key& other) = default;
187  virtual ~Private_Key() = default;
188 
189  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  */
206  { 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  {
218  return fingerprint_private(alg); // match behavior in previous versions
219  }
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 */
295  {
296  public:
297  /*
298  * @return public component of this key
299  */
300  virtual std::vector<uint8_t> public_value() const = 0;
301 
302  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  virtual ~PK_Key_Agreement_Key() = default;
306  };
307 
308 /*
309 * Old compat typedefs
310 * TODO: remove these?
311 */
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  {
324  return create_hex_fingerprint(vec.data(), vec.size(), hash_name);
325  }
326 
327 
328 }
329 
330 #endif
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:31
Signature_Format
Definition: pk_keys.h:24
Definition: bigint.h:1135
Private_Key PKCS8_PrivateKey
Definition: pk_keys.h:314
Public_Key X509_PublicKey
Definition: pk_keys.h:313
PK_Key_Agreement_Key PK_KA_Key
Definition: pk_keys.h:312
virtual Signature_Format default_x509_signature_format() const
Definition: pk_keys.h:126
virtual size_t message_part_size() const
Definition: pk_keys.h:124
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:189
virtual AlgorithmIdentifier pkcs8_algorithm_identifier() const
Definition: pk_keys.h:205
virtual size_t message_parts() const
Definition: pk_keys.h:113