Botan 3.0.0
Crypto and TLS for C&
pk_keys.h
Go to the documentation of this file.
1/*
2* PK Key Types
3* (C) 1999-2007,2018 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_view>
15#include <string>
16#include <span>
17
18namespace Botan {
19
20class BigInt;
21class RandomNumberGenerator;
22
23/**
24* Enumeration specifying the signature format.
25*
26* This is mostly used for requesting DER encoding of ECDSA signatures;
27* most other algorithms only support "standard".
28*/
29enum class Signature_Format {
32
33 IEEE_1363 BOTAN_DEPRECATED("Use Standard") = Standard,
34 DER_SEQUENCE BOTAN_DEPRECATED("Use DerSequence") = DerSequence,
35};
36
37/**
38* Enumeration of possible operations a public key could be used for.
39*
40* It is possible to query if a key supports a particular operation
41* type using Asymmetric_Key::supports_operation()
42*/
48};
49
50/**
51* An interface for objects that are keys in public key algorithms
52*
53* This is derived for both public and private keys
54*/
56 {
57 public:
58 virtual ~Asymmetric_Key() = default;
59
60 /**
61 * Get the name of the underlying public key scheme.
62 * @return name of the public key scheme
63 */
64 virtual std::string algo_name() const = 0;
65
66 /**
67 * Return the estimated strength of the underlying key against
68 * the best currently known attack. Note that this ignores anything
69 * but pure attacks against the key itself and do not take into
70 * account padding schemes, usage mistakes, etc which might reduce
71 * the strength. However it does suffice to provide an upper bound.
72 *
73 * @return estimated strength in bits
74 */
75 virtual size_t estimated_strength() const = 0;
76
77 /**
78 * Get the OID of the underlying public key scheme.
79 * @return OID of the public key scheme
80 */
81 virtual OID object_identifier() const;
82
83 /**
84 * Access an algorithm specific field
85 *
86 * If the field is not known for this algorithm, an Invalid_Argument is
87 * thrown. The interpretation of the result requires knowledge of which
88 * algorithm is involved. For instance for RSA "p" represents one of the
89 * secret primes, while for DSA "p" is the public prime.
90 *
91 * Some algorithms may not implement this method at all.
92 *
93 * This is primarily used to implement the FFI botan_pubkey_get_field
94 * and botan_privkey_get_field functions.
95 */
96 virtual const BigInt& get_int_field(std::string_view field) const;
97
98 /**
99 * Return true if this key could be used for the specified type
100 * of operation.
101 */
102 virtual bool supports_operation(PublicKeyOperation op) const = 0;
103 };
104
105/*
106* Public Key Base Class.
107*/
108class BOTAN_PUBLIC_API(2,0) Public_Key : public virtual Asymmetric_Key
109 {
110 public:
111 /**
112 * Return an integer value best approximating the length of the
113 * primary security parameter. For example for RSA this will be
114 * the size of the modulus, for ECDSA the size of the ECC group,
115 * and for McEliece the size of the code will be returned.
116 */
117 virtual size_t key_length() const = 0;
118
119 /**
120 * Deprecated version of object_identifier
121 */
122 BOTAN_DEPRECATED("Use object_identifier") OID get_oid() const
123 {
124 return this->object_identifier();
125 }
126
127 /*
128 * Test the key values for consistency.
129 * @param rng rng to use
130 * @param strong whether to perform strong and lengthy version
131 * of the test
132 * @return true if the test is passed
133 */
135 bool strong) const = 0;
136
137 /**
138 * @return X.509 AlgorithmIdentifier for this key
139 */
141
142 /**
143 * @return BER encoded public key bits
144 */
145 virtual std::vector<uint8_t> public_key_bits() const = 0;
146
147 /**
148 * @return X.509 subject key encoding for this key object
149 */
150 std::vector<uint8_t> subject_public_key() const;
151
152 /**
153 * @return Hash of the subject public key
154 */
155 std::string fingerprint_public(std::string_view alg = "SHA-256") const;
156
157 // Internal or non-public declarations follow
158
159 /**
160 * Returns more than 1 if the output of this algorithm
161 * (ciphertext, signature) should be treated as more than one
162 * value. This is used for algorithms like DSA and ECDSA, where
163 * the (r,s) output pair can be encoded as either a plain binary
164 * list or a TLV tagged DER encoding depending on the protocol.
165 *
166 * This function is public but applications should have few
167 * reasons to ever call this.
168 *
169 * @return number of message parts
170 */
171 virtual size_t message_parts() const { return 1; }
172
173 /**
174 * Returns how large each of the message parts refered to
175 * by message_parts() is
176 *
177 * This function is public but applications should have few
178 * reasons to ever call this.
179 *
180 * @return size of the message parts in bits
181 */
182 virtual size_t message_part_size() const { return 0; }
183
185 {
186 return (this->message_parts() >= 2) ? Signature_Format::DerSequence : Signature_Format::Standard;
187 }
188
189 /**
190 * This is an internal library function exposed on key types.
191 * In almost all cases applications should use wrappers in pubkey.h
192 *
193 * Return an encryption operation for this key/params or throw
194 *
195 * @param rng a random number generator. The PK_Op may maintain a
196 * reference to the RNG and use it many times. The rng must outlive
197 * any operations which reference it.
198 * @param params additional parameters
199 * @param provider the provider to use
200 */
201 virtual std::unique_ptr<PK_Ops::Encryption>
202 create_encryption_op(RandomNumberGenerator& rng,
203 std::string_view params,
204 std::string_view provider) const;
205
206 /**
207 * This is an internal library function exposed on key types.
208 * In almost all cases applications should use wrappers in pubkey.h
209 *
210 * Return a KEM encryption operation for this key/params or throw
211 *
212 * @param params additional parameters
213 * @param provider the provider to use
214 */
215 virtual std::unique_ptr<PK_Ops::KEM_Encryption>
216 create_kem_encryption_op(std::string_view params,
217 std::string_view provider) const;
218
219 /**
220 * This is an internal library function exposed on key types.
221 * In all cases applications should use wrappers in pubkey.h
222 *
223 * Return a verification operation for this key/params or throw
224 * @param params additional parameters
225 * @param provider the provider to use
226 */
227 virtual std::unique_ptr<PK_Ops::Verification>
228 create_verification_op(std::string_view params,
229 std::string_view provider) const;
230
231 /**
232 * This is an internal library function exposed on key types.
233 * In all cases applications should use wrappers in pubkey.h
234 *
235 * Return a verification operation for this combination of key and
236 * signature algorithm or throw.
237 *
238 * @param signature_algorithm is the X.509 algorithm identifier encoding the padding
239 * scheme and hash hash function used in the signature if applicable.
240 *
241 * @param provider the provider to use
242 */
243 virtual std::unique_ptr<PK_Ops::Verification>
244 create_x509_verification_op(const AlgorithmIdentifier& signature_algorithm,
245 std::string_view provider) const;
246 };
247
248/**
249* Private Key Base Class
250*/
251class BOTAN_PUBLIC_API(2,0) Private_Key : public virtual Public_Key
252 {
253 public:
254 /**
255 * @return BER encoded private key bits
256 */
258
259 /**
260 * @return binary private key bits, with no additional encoding
261 *
262 * Note: some algorithms (for example RSA) do not have an obvious encoding
263 * for this value due to having many different values, and thus not implement
264 * this function. The default implementation throws Not_Implemented
265 */
266 virtual secure_vector<uint8_t> raw_private_key_bits() const;
267
268 /**
269 * Allocate a new object for the public key associated with this
270 * private key.
271 *
272 * @return public key
273 */
274 virtual std::unique_ptr<Public_Key> public_key() const = 0;
275
276 /**
277 * @return PKCS #8 private key encoding for this key object
278 */
279 secure_vector<uint8_t> private_key_info() const;
280
281 /**
282 * @return PKCS #8 AlgorithmIdentifier for this key
283 * Might be different from the X.509 identifier, but normally is not
284 */
286 { return algorithm_identifier(); }
287
288 /**
289 * Indicates if this key is stateful, ie that performing a private
290 * key operation requires updating the key storage.
291 */
292 virtual bool stateful_operation() const { return false; }
293
294 // Internal or non-public declarations follow
295
296 /**
297 * @return Hash of the PKCS #8 encoding for this key object
298 */
299 std::string fingerprint_private(std::string_view alg) const;
300
301 /**
302 * This is an internal library function exposed on key types.
303 * In all cases applications should use wrappers in pubkey.h
304 *
305 * Return an decryption operation for this key/params or throw
306 *
307 * @param rng a random number generator. The PK_Op may maintain a
308 * reference to the RNG and use it many times. The rng must outlive
309 * any operations which reference it.
310 * @param params additional parameters
311 * @param provider the provider to use
312 *
313 */
314 virtual std::unique_ptr<PK_Ops::Decryption>
315 create_decryption_op(RandomNumberGenerator& rng,
316 std::string_view params,
317 std::string_view provider) const;
318
319 /**
320 * This is an internal library function exposed on key types.
321 * In all cases applications should use wrappers in pubkey.h
322 *
323 * Return a KEM decryption operation for this key/params or throw
324 *
325 * @param rng a random number generator. The PK_Op may maintain a
326 * reference to the RNG and use it many times. The rng must outlive
327 * any operations which reference it.
328 * @param params additional parameters
329 * @param provider the provider to use
330 */
331 virtual std::unique_ptr<PK_Ops::KEM_Decryption>
332 create_kem_decryption_op(RandomNumberGenerator& rng,
333 std::string_view params,
334 std::string_view provider) const;
335
336 /**
337 * This is an internal library function exposed on key types.
338 * In all cases applications should use wrappers in pubkey.h
339 *
340 * Return a signature operation for this key/params or throw
341 *
342 * @param rng a random number generator. The PK_Op may maintain a
343 * reference to the RNG and use it many times. The rng must outlive
344 * any operations which reference it.
345 * @param params additional parameters
346 * @param provider the provider to use
347 */
348 virtual std::unique_ptr<PK_Ops::Signature>
349 create_signature_op(RandomNumberGenerator& rng,
350 std::string_view params,
351 std::string_view provider) const;
352
353 /**
354 * This is an internal library function exposed on key types.
355 * In all cases applications should use wrappers in pubkey.h
356 *
357 * Return a key agreement operation for this key/params or throw
358 *
359 * @param rng a random number generator. The PK_Op may maintain a
360 * reference to the RNG and use it many times. The rng must outlive
361 * any operations which reference it.
362 * @param params additional parameters
363 * @param provider the provider to use
364 */
365 virtual std::unique_ptr<PK_Ops::Key_Agreement>
366 create_key_agreement_op(RandomNumberGenerator& rng,
367 std::string_view params,
368 std::string_view provider) const;
369 };
370
371/**
372* PK Secret Value Derivation Key
373*/
375 {
376 public:
377 /*
378 * @return public component of this key
379 */
380 virtual std::vector<uint8_t> public_value() const = 0;
381 };
382
383std::string BOTAN_PUBLIC_API(2,4)
384 create_hex_fingerprint(const uint8_t bits[], size_t len,
385 std::string_view hash_name);
386
387inline std::string create_hex_fingerprint(std::span<const uint8_t> vec,
388 std::string_view hash_name)
389 {
390 return create_hex_fingerprint(vec.data(), vec.size(), hash_name);
391 }
392
393
394}
395
396#endif
virtual std::string algo_name() const =0
virtual ~Asymmetric_Key()=default
virtual bool supports_operation(PublicKeyOperation op) const =0
virtual size_t estimated_strength() const =0
virtual std::vector< uint8_t > public_value() const =0
virtual std::unique_ptr< Public_Key > public_key() const =0
virtual AlgorithmIdentifier pkcs8_algorithm_identifier() const
Definition: pk_keys.h:285
virtual bool stateful_operation() const
Definition: pk_keys.h:292
virtual secure_vector< uint8_t > private_key_bits() const =0
virtual AlgorithmIdentifier algorithm_identifier() const =0
virtual std::vector< uint8_t > public_key_bits() const =0
virtual Signature_Format default_x509_signature_format() const
Definition: pk_keys.h:184
virtual bool check_key(RandomNumberGenerator &rng, bool strong) const =0
virtual size_t key_length() const =0
virtual size_t message_part_size() const
Definition: pk_keys.h:182
virtual size_t message_parts() const
Definition: pk_keys.h:171
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:31
Definition: alg_id.cpp:12
PublicKeyOperation
Definition: pk_keys.h:43
std::string create_hex_fingerprint(const uint8_t bits[], size_t bits_len, std::string_view hash_name)
Definition: pk_keys.cpp:34
Signature_Format
Definition: pk_keys.h:29
std::vector< T, secure_allocator< T > > secure_vector
Definition: secmem.h:64
Definition: bigint.h:1092