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