Botan 2.13.0 Crypto and TLS for C++11

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

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 */
24 enum Signature_Format { IEEE_1363, DER_SEQUENCE };
25
26 /**
27 * Public Key Base Class.
28 */
29 class BOTAN_PUBLIC_API(2,0) Public_Key
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
126 virtual Signature_Format default_x509_signature_format() const
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 */
205 virtual AlgorithmIdentifier pkcs8_algorithm_identifier() const
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 */
294 class BOTAN_PUBLIC_API(2,0) PK_Key_Agreement_Key : public virtual Private_Key
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 */
312 typedef PK_Key_Agreement_Key PK_KA_Key;
313 typedef Public_Key X509_PublicKey;
314 typedef Private_Key PKCS8_PrivateKey;
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
Botan::RandomNumberGenerator
Definition: rng.h:24
Botan::Private_Key
Definition: pk_keys.h:181
Botan::Public_Key::message_part_size
virtual size_t message_part_size() const
Definition: pk_keys.h:124
BOTAN_PUBLIC_API
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:31
Botan::Signature_Format
Signature_Format
Definition: pk_keys.h:24
std
Definition: bigint.h:1135
Botan::PKCS8_PrivateKey
Private_Key PKCS8_PrivateKey
Definition: pk_keys.h:314
Botan::X509_PublicKey
Public_Key X509_PublicKey
Definition: pk_keys.h:313
Botan::PK_KA_Key
PK_Key_Agreement_Key PK_KA_Key
Definition: pk_keys.h:312
Botan::secure_vector
std::vector< T, secure_allocator< T >> secure_vector
Definition: secmem.h:65
Botan::Public_Key::message_parts
virtual size_t message_parts() const
Definition: pk_keys.h:113
Botan::Private_Key::pkcs8_algorithm_identifier
virtual AlgorithmIdentifier pkcs8_algorithm_identifier() const
Definition: pk_keys.h:205
Botan
Definition: alg_id.cpp:13
Botan::Public_Key
Definition: pk_keys.h:29
Botan::IEEE_1363
Definition: pk_keys.h:24
Botan::create_hex_fingerprint
std::string create_hex_fingerprint(const uint8_t bits[], size_t bits_len, const std::string &hash_name)
Definition: pk_keys.cpp:17
Botan::PK_Key_Agreement_Key
Definition: pk_keys.h:294
Botan::AlgorithmIdentifier
Definition: alg_id.h:21
Botan::DER_SEQUENCE
Definition: pk_keys.h:24
Botan::OID
Definition: asn1_oid.h:20
Botan::Private_Key::stateful_operation
virtual bool stateful_operation() const
Definition: pk_keys.h:189
Botan::Public_Key::default_x509_signature_format
virtual Signature_Format default_x509_signature_format() const
Definition: pk_keys.h:126