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