Botan 3.14.1
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/asn1_obj.h>
12#include <botan/pk_ops_fwd.h>
13#include <botan/secmem.h>
14
15#include <memory>
16#include <optional>
17#include <span>
18#include <string>
19#include <string_view>
20
21namespace Botan {
22
23class BigInt;
29
30/**
31* Enumeration specifying the signature format.
32*
33* This is mostly used for requesting DER encoding of ECDSA signatures;
34* most other algorithms only support "standard".
35*/
36enum class Signature_Format : uint8_t {
39
42};
43
44/**
45* Enumeration of possible operations a public key could be used for.
46*
47* It is possible to query if a key supports a particular operation
48* type using Asymmetric_Key::supports_operation()
49*/
56
57class Private_Key;
58
59/**
60* An interface for objects that are keys in public key algorithms
61*
62* This is derived for both public and private keys
63*/
64class BOTAN_PUBLIC_API(3, 0) Asymmetric_Key /* NOLINT(*special-member-functions) */ {
65 public:
66 virtual ~Asymmetric_Key() = default;
67
68 /**
69 * Get the name of the underlying public key scheme.
70 * @return name of the public key scheme
71 */
72 virtual std::string algo_name() const = 0;
73
74 /**
75 * Return the estimated strength of the underlying key against
76 * the best currently known attack. Note that this ignores anything
77 * but pure attacks against the key itself and do not take into
78 * account padding schemes, usage mistakes, etc which might reduce
79 * the strength. However it does suffice to provide an upper bound.
80 *
81 * @return estimated strength in bits
82 */
83 virtual size_t estimated_strength() const = 0;
84
85 /**
86 * Get the OID of the underlying public key scheme.
87 * @return OID of the public key scheme
88 */
89 virtual OID object_identifier() const;
90
91 /**
92 * Access an algorithm specific field
93 *
94 * If the field is not known for this algorithm, an Invalid_Argument is
95 * thrown. The interpretation of the result requires knowledge of which
96 * algorithm is involved. For instance for RSA "p" represents one of the
97 * secret primes, while for DSA "p" is the public prime.
98 *
99 * Some algorithms may not implement this method at all.
100 *
101 * This is primarily used to implement the FFI botan_pubkey_get_field
102 * and botan_privkey_get_field functions.
103 *
104 * TODO(Botan4) Change this to return by value
105 */
106 virtual const BigInt& get_int_field(std::string_view field) const;
107
108 /**
109 * Return true if this key could be used for the specified type
110 * of operation.
111 */
112 virtual bool supports_operation(PublicKeyOperation op) const = 0;
113
114 /**
115 * Generate another (cryptographically independent) key pair using the
116 * same algorithm parameters as this key. This is most useful for algorithms
117 * that support PublicKeyOperation::KeyAgreement to generate a fitting ephemeral
118 * key pair. For other key types it might throw `Not_Implemented`.
119 */
120 virtual std::unique_ptr<Private_Key> generate_another(RandomNumberGenerator& rng) const = 0;
121
122 /**
123 * Test the key values for consistency.
124 *
125 * Note this function is always "best effort"; for many algorithms it is
126 * not computationally possible to ensure the key is correctly formed in
127 * all respects. There is always the possibility a malformed key will be
128 * accepted; this is especially the case for public keys.
129 *
130 * @param rng rng to use for randomized testing (may be ignored)
131 * @param strong whether to perform strong and lengthy version of the test,
132 * however for many algorithms this has no effect
133 * @return true if the tests passed
134 */
135 virtual bool check_key(RandomNumberGenerator& rng, bool strong) const = 0;
136
137 // Declarations for internal library functions not covered by SemVer follow
138
139 /**
140 * Certain signatures schemes such as ECDSA have more than
141 * one element, and certain unfortunate protocols decided the
142 * thing to do was not concatenate them as normally done, but
143 * instead DER encode each of the elements as independent values.
144 *
145 * If this returns a value x then the signature is checked to
146 * be exactly 2*x bytes and split in half for DER encoding.
147 */
148 virtual std::optional<size_t> _signature_element_size_for_DER_encoding() const { return {}; }
149
150 /*
151 * Return the format normally used by this algorithm for X.509 signatures
152 */
153 virtual Signature_Format _default_x509_signature_format() const;
154};
155
156/*
157* Public Key Base Class.
158*/
159class BOTAN_PUBLIC_API(2, 0) Public_Key : public virtual Asymmetric_Key {
160 public:
161 /**
162 * Return an integer value best approximating the length of the
163 * primary security parameter. For example for RSA this will be
164 * the size of the modulus, for ECDSA the size of the ECC group,
165 * and for McEliece the size of the code will be returned.
166 */
167 virtual size_t key_length() const = 0;
168
169 /**
170 * Deprecated version of object_identifier
171 */
172 BOTAN_DEPRECATED("Use object_identifier") OID get_oid() const { return this->object_identifier(); }
173
174 /**
175 * Return the X.509 AlgorithmIdentifier for this key
176 */
178
179 /**
180 * Return the raw public key bits (algorithm specific) with no extra encoding
181 *
182 * For key agreements this is an alias for PK_Key_Agreement_Key::public_value.
183 *
184 * @note some algorithms (for example RSA) do not have an obvious encoding
185 * for this value due to having many different values, and thus throw
186 * `Not_Implemented` when invoking this method.
187 */
188 virtual std::vector<uint8_t> raw_public_key_bits() const = 0;
189
190 /**
191 * Return the subject public key encoding of this public key
192 *
193 * @note this excludes the parameters field and may not be reliably decodable
194 */
195 virtual std::vector<uint8_t> public_key_bits() const = 0;
196
197 /**
198 * Return the SubjectPublicKeyInfo encoding of this public key
199 *
200 * This is the subjectPublicKey field plus the algorithm-specific parameters
201 */
202 std::vector<uint8_t> subject_public_key() const;
203
204 /**
205 * @return Hash of the subject public key
206 */
207 std::string fingerprint_public(std::string_view alg = "SHA-256") const;
208
209 // Declarations for internal library functions not covered by SemVer follow
210
211 /**
212 * Returns more than 1 if the output of this algorithm
213 * (ciphertext, signature) should be treated as more than one
214 * value. This is used for algorithms like DSA and ECDSA, where
215 * the (r,s) output pair can be encoded as either a plain binary
216 * list or a TLV tagged DER encoding depending on the protocol.
217 *
218 * This function is public but applications should have few
219 * reasons to ever call this.
220 *
221 * @return number of message parts
222 */
223 BOTAN_DEPRECATED("Deprecated no replacement") size_t message_parts() const {
225 }
226
227 /**
228 * Returns how large each of the message parts referred to
229 * by message_parts() is
230 *
231 * This function is public but applications should have few
232 * reasons to ever call this.
233 *
234 * @return size of the message parts in bits
235 */
236 BOTAN_DEPRECATED("Deprecated no replacement") size_t message_part_size() const {
237 return _signature_element_size_for_DER_encoding().value_or(0);
238 }
239
240 // NOLINTBEGIN(bugprone-virtual-near-miss)
241
242 /*
243 * Return the format normally used by this algorithm for X.509 signatures
244 */
247 }
248
249 // NOLINTEND(bugprone-virtual-near-miss)
250
251 /**
252 * This is an internal library function exposed on key types.
253 * In almost all cases applications should use wrappers in pubkey.h
254 *
255 * Return an encryption operation for this key/options or throw
256 *
257 * @param rng a random number generator. The PK_Op may maintain a
258 * reference to the RNG and use it many times. The rng must outlive
259 * any operations which reference it.
260 * @param options which specify parameters of the encryption beyond those
261 * implicit to the public key itself
262 */
263 virtual std::unique_ptr<PK_Ops::Encryption> _create_encryption_op(
264 RandomNumberGenerator& rng, const PK_Encryption_Options_Reader& options) const;
265
266 /**
267 * This is an internal library function exposed on key types.
268 * In almost all cases applications should use wrappers in pubkey.h
269 *
270 * Return an encryption operation for this key/params or throw
271 *
272 * @param rng a random number generator. The PK_Op may maintain a
273 * reference to the RNG and use it many times. The rng must outlive
274 * any operations which reference it.
275 * @param params additional parameters
276 * @param provider the provider to use
277 */
278 BOTAN_DEPRECATED("Use PK_Encryptor_EME")
279 std::unique_ptr<PK_Ops::Encryption> create_encryption_op(RandomNumberGenerator& rng,
280 std::string_view params,
281 std::string_view provider) const;
282
283 /**
284 * This is an internal library function exposed on key types.
285 * In almost all cases applications should use wrappers in pubkey.h
286 *
287 * Return a KEM encryption operation for this key/options or throw
288 *
289 * @param options which specify parameters of the KEM beyond those
290 * implicit to the public key itself
291 */
292 virtual std::unique_ptr<PK_Ops::KEM_Encryption> _create_kem_encryption_op(
293 const PK_KEM_Options_Reader& options) const;
294
295 /**
296 * This is an internal library function exposed on key types.
297 * In almost all cases applications should use wrappers in pubkey.h
298 *
299 * Return a KEM encryption operation for this key/params or throw
300 *
301 * @param params additional parameters
302 * @param provider the provider to use
303 */
304 BOTAN_DEPRECATED("Use PK_KEM_Encryptor")
305 std::unique_ptr<PK_Ops::KEM_Encryption> create_kem_encryption_op(std::string_view params,
306 std::string_view provider) const;
307
308 /**
309 * This is an internal library function exposed on key types.
310 * In all cases applications should use wrappers in pubkey.h
311 *
312 * Return a verification operation for this key/params or throw
313 *
314 * @param options which specify parameters of the signature beyond those
315 * implicit to the public key itself
316 */
317 virtual std::unique_ptr<PK_Ops::Verification> _create_verification_op(
318 const PK_Signature_Options_Reader& options) const;
319
320 /**
321 * This is an internal library function exposed on key types.
322 * In all cases applications should use wrappers in pubkey.h
323 *
324 * Return a verification operation for this key/params or throw
325 *
326 * @param params additional parameters
327 * @param provider the provider to use
328 */
329 BOTAN_DEPRECATED("Use PK_Verifier")
330 std::unique_ptr<PK_Ops::Verification> create_verification_op(std::string_view params,
331 std::string_view provider) const;
332
333 /**
334 * This is an internal library function exposed on key types.
335 * In all cases applications should use wrappers in pubkey.h
336 *
337 * Return a verification operation for this combination of key and
338 * signature algorithm or throw.
339 *
340 * @param signature_algorithm is the X.509 algorithm identifier encoding the padding
341 * scheme and hash hash function used in the signature if applicable.
342 *
343 * @param provider the provider to use
344 */
345 virtual std::unique_ptr<PK_Ops::Verification> create_x509_verification_op(
346 const AlgorithmIdentifier& signature_algorithm, std::string_view provider) const;
347};
348
349/**
350* Private Key Base Class
351*/
352class BOTAN_PUBLIC_API(2, 0) Private_Key : public virtual Public_Key {
353 public:
354 /**
355 * Return the PKCS8 private key encoding
356 *
357 * @note this encoding omits the outer PKCS8 algorithm identifiers and will
358 * not be portably decodable on its own. Prefer `private_key_info`.
359 */
361
362 /**
363 * Return the binary private key bits, with no additional encoding
364 *
365 * @note some algorithms (for example RSA) do not have an obvious encoding
366 * for this value due to having many different values, and thus not implement
367 * this function. The default implementation throws `Not_Implemented`
368 */
370
371 /**
372 * Allocate a new object for the public key associated with this
373 * private key.
374 *
375 * @return public key
376 */
377 virtual std::unique_ptr<Public_Key> public_key() const = 0;
378
379 /**
380 * Return PKCS #8 private key encoding for this key object
381 */
383
384 /**
385 * Return the PKCS #8 AlgorithmIdentifier for this key
386 *
387 * @note normally this is the same as the public key identifier, but a few
388 * oddball algorithms use a different value
389 */
391
392 /**
393 * Indicates if this key is stateful, ie that performing a private
394 * key operation requires updating the key storage.
395 */
396 virtual bool stateful_operation() const { return false; }
397
398 /**
399 * @brief Retrieves the number of remaining operations if this is a stateful private key.
400 *
401 * @returns the number of remaining operations or std::nullopt if not applicable.
402 */
403 virtual std::optional<uint64_t> remaining_operations() const { return std::nullopt; }
404
405 // Declarations for internal library functions not covered by SemVer follow
406
407 /**
408 * @return Hash of the algorithm specific private key encoding
409 *
410 * @warning This hashes private_key_bits(), which does not include the
411 * algorithm identifier; keys of different algorithms with identical raw
412 * encodings (such as an Ed25519 and an X25519 key built from the same 32
413 * bytes) share a fingerprint.
414 */
415 std::string fingerprint_private(std::string_view alg) const;
416
417 /**
418 * This is an internal library function exposed on key types.
419 * In all cases applications should use wrappers in pubkey.h
420 *
421 * Return a decryption operation for this key/options or throw
422 *
423 * @param rng a random number generator. The PK_Op may maintain a
424 * reference to the RNG and use it many times. The rng must outlive
425 * any operations which reference it.
426 * @param options which specify parameters of the encryption beyond those
427 * implicit to the key itself
428 */
429 virtual std::unique_ptr<PK_Ops::Decryption> _create_decryption_op(
430 RandomNumberGenerator& rng, const PK_Encryption_Options_Reader& options) const;
431
432 /**
433 * This is an internal library function exposed on key types.
434 * In all cases applications should use wrappers in pubkey.h
435 *
436 * Return an decryption operation for this key/params or throw
437 *
438 * @param rng a random number generator. The PK_Op may maintain a
439 * reference to the RNG and use it many times. The rng must outlive
440 * any operations which reference it.
441 * @param params additional parameters
442 * @param provider the provider to use
443 *
444 */
445 BOTAN_DEPRECATED("Use PK_Decryptor_EME")
446 std::unique_ptr<PK_Ops::Decryption> create_decryption_op(RandomNumberGenerator& rng,
447 std::string_view params,
448 std::string_view provider) const;
449
450 /**
451 * This is an internal library function exposed on key types.
452 * In all cases applications should use wrappers in pubkey.h
453 *
454 * Return a KEM decryption operation for this key/options or throw
455 *
456 * @param rng a random number generator. The PK_Op may maintain a
457 * reference to the RNG and use it many times. The rng must outlive
458 * any operations which reference it.
459 * @param options which specify parameters of the KEM beyond those
460 * implicit to the key itself
461 */
462 virtual std::unique_ptr<PK_Ops::KEM_Decryption> _create_kem_decryption_op(
463 RandomNumberGenerator& rng, const PK_KEM_Options_Reader& options) const;
464
465 /**
466 * This is an internal library function exposed on key types.
467 * In all cases applications should use wrappers in pubkey.h
468 *
469 * Return a KEM decryption operation for this key/params or throw
470 *
471 * @param rng a random number generator. The PK_Op may maintain a
472 * reference to the RNG and use it many times. The rng must outlive
473 * any operations which reference it.
474 * @param params additional parameters
475 * @param provider the provider to use
476 */
477 BOTAN_DEPRECATED("Use PK_KEM_Decryptor")
478 std::unique_ptr<PK_Ops::KEM_Decryption> create_kem_decryption_op(RandomNumberGenerator& rng,
479 std::string_view params,
480 std::string_view provider) const;
481
482 /**
483 * This is an internal library function exposed on key types.
484 * In all cases applications should use wrappers in pubkey.h
485 *
486 * Return a signature operation for this key/params or throw
487 *
488 * @param rng a random number generator. The PK_Op may maintain a
489 * reference to the RNG and use it many times. The rng must outlive
490 * any operations which reference it.
491 *
492 * @param options allow controlling behavior
493 */
494 virtual std::unique_ptr<PK_Ops::Signature> _create_signature_op(RandomNumberGenerator& rng,
495 const PK_Signature_Options_Reader& options) const;
496
497 /**
498 * This is an internal library function exposed on key types.
499 * In all cases applications should use wrappers in pubkey.h
500 *
501 * Return a signature operation for this key/params or throw
502 *
503 * @param rng a random number generator. The PK_Op may maintain a
504 * reference to the RNG and use it many times. The rng must outlive
505 * any operations which reference it.
506 *
507 * @param params additional parameters
508 * @param provider the provider to use
509 */
510 BOTAN_DEPRECATED("Use PK_Signer")
511 std::unique_ptr<PK_Ops::Signature> create_signature_op(RandomNumberGenerator& rng,
512 std::string_view params,
513 std::string_view provider) const;
514
515 /**
516 * This is an internal library function exposed on key types.
517 * In all cases applications should use wrappers in pubkey.h
518 *
519 * Return a key agreement operation for this key/options or throw
520 *
521 * @param rng a random number generator. The PK_Op may maintain a
522 * reference to the RNG and use it many times. The rng must outlive
523 * any operations which reference it.
524 * @param options which specify parameters of the key agreement beyond
525 * those implicit to the key itself
526 */
527 virtual std::unique_ptr<PK_Ops::Key_Agreement> _create_key_agreement_op(
528 RandomNumberGenerator& rng, const PK_Key_Agreement_Options_Reader& options) const;
529
530 /**
531 * This is an internal library function exposed on key types.
532 * In all cases applications should use wrappers in pubkey.h
533 *
534 * Return a key agreement operation for this key/params or throw
535 *
536 * @param rng a random number generator. The PK_Op may maintain a
537 * reference to the RNG and use it many times. The rng must outlive
538 * any operations which reference it.
539 * @param params additional parameters
540 * @param provider the provider to use
541 */
542 BOTAN_DEPRECATED("Use PK_Key_Agreement")
543 std::unique_ptr<PK_Ops::Key_Agreement> create_key_agreement_op(RandomNumberGenerator& rng,
544 std::string_view params,
545 std::string_view provider) const;
546};
547
548/**
549* PK Secret Value Derivation Key
550*/
552 public:
553 /**
554 * Return the public value used to effect key exchange
555 */
556 virtual std::vector<uint8_t> public_value() const = 0;
557};
558
559/**
560* Hex encode the data and separate them in blocks with `:` characters
561*/
562std::string BOTAN_PUBLIC_API(3, 12) format_hex_fingerprint(std::span<const uint8_t> bits);
563
564/**
565* Hash the input then format that hash using format_hex_fingerprint
566*/
567std::string BOTAN_PUBLIC_API(3, 0) create_hex_fingerprint(std::span<const uint8_t> bits, std::string_view hash_name);
568
569/**
570* Old interface for create_hex_fingerprint added in 2.4 pre-span
571*/
572inline std::string create_hex_fingerprint(const uint8_t bits[], size_t len, std::string_view hash_name) {
573 return create_hex_fingerprint({bits, len}, hash_name);
574}
575
576} // namespace Botan
577
578#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
#define BOTAN_DEPRECATED(msg)
Definition api.h:73
virtual std::string algo_name() const =0
virtual ~Asymmetric_Key()=default
virtual bool check_key(RandomNumberGenerator &rng, bool strong) const =0
virtual bool supports_operation(PublicKeyOperation op) const =0
virtual std::unique_ptr< Private_Key > generate_another(RandomNumberGenerator &rng) const =0
virtual const BigInt & get_int_field(std::string_view field) const
Definition pk_keys.cpp:20
virtual OID object_identifier() const
Definition pk_keys.cpp:24
virtual std::optional< size_t > _signature_element_size_for_DER_encoding() const
Definition pk_keys.h:148
virtual Signature_Format _default_x509_signature_format() const
Definition pk_keys.cpp:32
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:390
virtual secure_vector< uint8_t > raw_private_key_bits() const
Definition pk_keys.cpp:89
virtual std::optional< uint64_t > remaining_operations() const
Retrieves the number of remaining operations if this is a stateful private key.
Definition pk_keys.h:403
secure_vector< uint8_t > private_key_info() const
Definition pk_keys.cpp:77
virtual bool stateful_operation() const
Definition pk_keys.h:396
virtual secure_vector< uint8_t > private_key_bits() const =0
std::string fingerprint_public(std::string_view alg="SHA-256") const
Definition pk_keys.cpp:96
OID get_oid() const
Definition pk_keys.h:172
virtual AlgorithmIdentifier algorithm_identifier() const =0
virtual std::vector< uint8_t > public_key_bits() const =0
size_t message_part_size() const
Definition pk_keys.h:236
Signature_Format default_x509_signature_format() const
Definition pk_keys.h:245
virtual std::vector< uint8_t > raw_public_key_bits() const =0
virtual size_t key_length() const =0
size_t message_parts() const
Definition pk_keys.h:223
std::vector< uint8_t > subject_public_key() const
Definition pk_keys.cpp:65
std::string create_hex_fingerprint(std::span< const uint8_t > bits, std::string_view hash_name)
Definition pk_keys.cpp:40
PublicKeyOperation
Definition pk_keys.h:50
Signature_Format
Definition pk_keys.h:36
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128
std::string format_hex_fingerprint(std::span< const uint8_t > bits)
Definition pk_keys.cpp:47