Botan 2.19.5 Crypto and TLS for C&

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