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