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