Botan  2.1.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/rng.h>
15 #include <botan/pk_ops_fwd.h>
16 
17 namespace Botan {
18 
19 class RandomNumberGenerator;
20 
21 /**
22 * Public Key Base Class.
23 */
24 class BOTAN_DLL Public_Key
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  // Internal or non-public declarations follow
90 
91  /**
92  * Returns more than 1 if the output of this algorithm
93  * (ciphertext, signature) should be treated as more than one
94  * value. This is used for algorithms like DSA and ECDSA, where
95  * the (r,s) output pair can be encoded as either a plain binary
96  * list or a TLV tagged DER encoding depending on the protocol.
97  *
98  * This function is public but applications should have few
99  * reasons to ever call this.
100  *
101  * @return number of message parts
102  */
103  virtual size_t message_parts() const { return 1; }
104 
105  /**
106  * Returns how large each of the message parts refered to
107  * by message_parts() is
108  *
109  * This function is public but applications should have few
110  * reasons to ever call this.
111  *
112  * @return size of the message parts in bits
113  */
114  virtual size_t message_part_size() const { return 0; }
115 
116  /**
117  * This is an internal library function exposed on key types.
118  * In almost all cases applications should use wrappers in pubkey.h
119  *
120  * Return an encryption operation for this key/params or throw
121  *
122  * @param rng a random number generator. The PK_Op may maintain a
123  * reference to the RNG and use it many times. The rng must outlive
124  * any operations which reference it.
125  * @param params additional parameters
126  * @param provider the provider to use
127  */
128  virtual std::unique_ptr<PK_Ops::Encryption>
129  create_encryption_op(RandomNumberGenerator& rng,
130  const std::string& params,
131  const std::string& provider) const;
132 
133  /**
134  * This is an internal library function exposed on key types.
135  * In almost all cases applications should use wrappers in pubkey.h
136  *
137  * Return a KEM encryption operation for this key/params or throw
138  *
139  * @param rng a random number generator. The PK_Op may maintain a
140  * reference to the RNG and use it many times. The rng must outlive
141  * any operations which reference it.
142  * @param params additional parameters
143  * @param provider the provider to use
144  */
145  virtual std::unique_ptr<PK_Ops::KEM_Encryption>
146  create_kem_encryption_op(RandomNumberGenerator& rng,
147  const std::string& params,
148  const std::string& provider) const;
149 
150  /**
151  * This is an internal library function exposed on key types.
152  * In almost all cases applications should use wrappers in pubkey.h
153  *
154  * Return a verification operation for this key/params or throw
155  * @param params additional parameters
156  * @param provider the provider to use
157  */
158  virtual std::unique_ptr<PK_Ops::Verification>
159  create_verification_op(const std::string& params,
160  const std::string& provider) const;
161  };
162 
163 /**
164 * Private Key Base Class
165 */
166 class BOTAN_DLL Private_Key : public virtual Public_Key
167  {
168  public:
169  Private_Key() = default;
170  Private_Key(const Private_Key& other) = default;
171  Private_Key& operator=(const Private_Key& other) = default;
172  virtual ~Private_Key() = default;
173 
174  /**
175  * @return BER encoded private key bits
176  */
177  virtual secure_vector<uint8_t> private_key_bits() const = 0;
178 
179  /**
180  * @return PKCS #8 private key encoding for this key object
181  */
182  secure_vector<uint8_t> private_key_info() const;
183 
184  /**
185  * @return PKCS #8 AlgorithmIdentifier for this key
186  * Might be different from the X.509 identifier, but normally is not
187  */
189  { return algorithm_identifier(); }
190 
191  // Internal or non-public declarations follow
192 
193  /**
194  * @return Hash of the PKCS #8 encoding for this key object
195  */
196  std::string fingerprint(const std::string& alg = "SHA") const;
197 
198  /**
199  * This is an internal library function exposed on key types.
200  * In almost all cases applications should use wrappers in pubkey.h
201  *
202  * Return an decryption operation for this key/params or throw
203  *
204  * @param rng a random number generator. The PK_Op may maintain a
205  * reference to the RNG and use it many times. The rng must outlive
206  * any operations which reference it.
207  * @param params additional parameters
208  * @param provider the provider to use
209  *
210  */
211  virtual std::unique_ptr<PK_Ops::Decryption>
212  create_decryption_op(RandomNumberGenerator& rng,
213  const std::string& params,
214  const std::string& provider) const;
215 
216  /**
217  * This is an internal library function exposed on key types.
218  * In almost all cases applications should use wrappers in pubkey.h
219  *
220  * Return a KEM decryption operation for this key/params or throw
221  *
222  * @param rng a random number generator. The PK_Op may maintain a
223  * reference to the RNG and use it many times. The rng must outlive
224  * any operations which reference it.
225  * @param params additional parameters
226  * @param provider the provider to use
227  */
228  virtual std::unique_ptr<PK_Ops::KEM_Decryption>
229  create_kem_decryption_op(RandomNumberGenerator& rng,
230  const std::string& params,
231  const std::string& provider) const;
232 
233  /**
234  * This is an internal library function exposed on key types.
235  * In almost all cases applications should use wrappers in pubkey.h
236  *
237  * Return a signature operation for this key/params or throw
238  *
239  * @param rng a random number generator. The PK_Op may maintain a
240  * reference to the RNG and use it many times. The rng must outlive
241  * any operations which reference it.
242  * @param params additional parameters
243  * @param provider the provider to use
244  */
245  virtual std::unique_ptr<PK_Ops::Signature>
246  create_signature_op(RandomNumberGenerator& rng,
247  const std::string& params,
248  const std::string& provider) const;
249 
250  /**
251  * This is an internal library function exposed on key types.
252  * In almost all cases applications should use wrappers in pubkey.h
253  *
254  * Return a key agreement operation for this key/params or throw
255  *
256  * @param rng a random number generator. The PK_Op may maintain a
257  * reference to the RNG and use it many times. The rng must outlive
258  * any operations which reference it.
259  * @param params additional parameters
260  * @param provider the provider to use
261  */
262  virtual std::unique_ptr<PK_Ops::Key_Agreement>
263  create_key_agreement_op(RandomNumberGenerator& rng,
264  const std::string& params,
265  const std::string& provider) const;
266  };
267 
268 /**
269 * PK Secret Value Derivation Key
270 */
271 class BOTAN_DLL PK_Key_Agreement_Key : public virtual Private_Key
272  {
273  public:
274  /*
275  * @return public component of this key
276  */
277  virtual std::vector<uint8_t> public_value() const = 0;
278 
279  PK_Key_Agreement_Key() = default;
280  PK_Key_Agreement_Key(const PK_Key_Agreement_Key&) = default;
281  PK_Key_Agreement_Key& operator=(const PK_Key_Agreement_Key&) = default;
282  virtual ~PK_Key_Agreement_Key() = default;
283  };
284 
285 /*
286 * Old compat typedefs
287 * TODO: remove these?
288 */
292 
293 }
294 
295 #endif
virtual size_t message_part_size() const
Definition: pk_keys.h:114
Private_Key PKCS8_PrivateKey
Definition: pk_keys.h:291
Public_Key X509_PublicKey
Definition: pk_keys.h:290
PK_Key_Agreement_Key PK_KA_Key
Definition: pk_keys.h:289
std::vector< T, secure_allocator< T >> secure_vector
Definition: secmem.h:121
virtual size_t message_parts() const
Definition: pk_keys.h:103
virtual AlgorithmIdentifier pkcs8_algorithm_identifier() const
Definition: pk_keys.h:188
Definition: alg_id.cpp:13