/src/botan/build/include/botan/pk_keys.h
Line | Count | Source (jump to first uncovered line) |
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 | 33.8k | Public_Key() =default; |
33 | 0 | Public_Key(const Public_Key& other) = default; |
34 | 0 | Public_Key& operator=(const Public_Key& other) = default; |
35 | 33.8k | 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 | 12.8k | 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 | 6.43k | virtual size_t message_part_size() const { return 0; } |
125 | | |
126 | | virtual Signature_Format default_x509_signature_format() const |
127 | 7.81k | { |
128 | 7.81k | return (this->message_parts() >= 2) ? DER_SEQUENCE : IEEE_1363; |
129 | 7.81k | } |
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 | 23.1k | Private_Key() = default; |
185 | 0 | Private_Key(const Private_Key& other) = default; |
186 | 0 | Private_Key& operator=(const Private_Key& other) = default; |
187 | 23.1k | virtual ~Private_Key() = default; |
188 | | |
189 | 0 | 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 | 0 | { 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 | 0 | { |
218 | 0 | return fingerprint_private(alg); // match behavior in previous versions |
219 | 0 | } |
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 | 21.8k | 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 | 21.8k | 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 | 12.1k | { |
324 | 12.1k | return create_hex_fingerprint(vec.data(), vec.size(), hash_name); |
325 | 12.1k | } std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > Botan::create_hex_fingerprint<std::__1::allocator<unsigned char> >(std::__1::vector<unsigned char, std::__1::allocator<unsigned char> > const&, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > const&) Line | Count | Source | 323 | 12.1k | { | 324 | 12.1k | return create_hex_fingerprint(vec.data(), vec.size(), hash_name); | 325 | 12.1k | } |
Unexecuted instantiation: std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > Botan::create_hex_fingerprint<Botan::secure_allocator<unsigned char> >(std::__1::vector<unsigned char, Botan::secure_allocator<unsigned char> > const&, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > const&) |
326 | | |
327 | | |
328 | | } |
329 | | |
330 | | #endif |