Botan 2.1.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/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 */
188 virtual AlgorithmIdentifier pkcs8_algorithm_identifier() const
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 */
289 typedef PK_Key_Agreement_Key PK_KA_Key;
290 typedef Public_Key X509_PublicKey;
291 typedef Private_Key PKCS8_PrivateKey;
292
293 }
294
295 #endif
Botan::RandomNumberGenerator
Definition: rng.h:25
Botan::Private_Key
Definition: pk_keys.h:166
Botan::Public_Key::message_part_size
virtual size_t message_part_size() const
Definition: pk_keys.h:114
Botan::PKCS8_PrivateKey
Private_Key PKCS8_PrivateKey
Definition: pk_keys.h:291
Botan::X509_PublicKey
Public_Key X509_PublicKey
Definition: pk_keys.h:290
Botan::PK_KA_Key
PK_Key_Agreement_Key PK_KA_Key
Definition: pk_keys.h:289
Botan::secure_vector
std::vector< T, secure_allocator< T >> secure_vector
Definition: secmem.h:121
Botan::Public_Key::message_parts
virtual size_t message_parts() const
Definition: pk_keys.h:103
Botan::Private_Key::pkcs8_algorithm_identifier
virtual AlgorithmIdentifier pkcs8_algorithm_identifier() const
Definition: pk_keys.h:188
Botan
Definition: alg_id.cpp:13
Botan::Public_Key
Definition: pk_keys.h:24
Botan::PK_Key_Agreement_Key
Definition: pk_keys.h:271
Botan::AlgorithmIdentifier
Definition: alg_id.h:20
Botan::OID
Definition: asn1_oid.h:20