/src/botan/build/include/botan/pk_keys.h

Source (jump to first uncovered line)
/*
* PK Key Types
* (C) 1999-2007,2018 Jack Lloyd
*
* Botan is released under the Simplified BSD License (see license.txt)
*/

#ifndef BOTAN_PK_KEYS_H_
#define BOTAN_PK_KEYS_H_

#include <botan/secmem.h>
#include <botan/asn1_obj.h>
#include <botan/pk_ops_fwd.h>
#include <string>

namespace Botan {

class BigInt;
class RandomNumberGenerator;

/**
* The two types of signature format supported by Botan.
*/
enum class Signature_Format {
   Standard,
   DerSequence,

   IEEE_1363 BOTAN_DEPRECATED("Use Standard") = Standard,
   DER_SEQUENCE BOTAN_DEPRECATED("Use DerSequence") = DerSequence,
};

/**
* An interface for objects that are keys in public key algorithms
*
* This is derived for both public and private keys
*/
class BOTAN_PUBLIC_API(3,0) Asymmetric_Key
   {
   public:
      virtual ~Asymmetric_Key() = default;

      /**
      * Get the name of the underlying public key scheme.
      * @return name of the public key scheme
      */
      virtual std::string algo_name() const = 0;

      /**
      * Return the estimated strength of the underlying key against
      * the best currently known attack. Note that this ignores anything
      * but pure attacks against the key itself and do not take into
      * account padding schemes, usage mistakes, etc which might reduce
      * the strength. However it does suffice to provide an upper bound.
      *
      * @return estimated strength in bits
      */
      virtual size_t estimated_strength() const = 0;

      /**
      * Get the OID of the underlying public key scheme.
      * @return OID of the public key scheme
      */
      virtual OID object_identifier() const;

      /**
      * Access an algorithm specific field
      *
      * If the field is not known for this algorithm, an Invalid_Argument is
      * thrown. The interpretation of the result requires knowledge of which
      * algorithm is involved. For instance for RSA "p" represents one of the
      * secret primes, while for DSA "p" is the public prime.
      *
      * Some algorithms may not implement this method at all.
      *
      * This is primarily used to implement the FFI botan_pubkey_get_field
      * and botan_privkey_get_field functions.
      */
      virtual const BigInt& get_int_field(const std::string& field) const;
   };

/*
* Public Key Base Class.
*/
class BOTAN_PUBLIC_API(2,0) Public_Key : public virtual Asymmetric_Key
   {
   public:
      /**
      * Return an integer value best approximating the length of the
      * primary security parameter. For example for RSA this will be
      * the size of the modulus, for ECDSA the size of the ECC group,
      * and for McEliece the size of the code will be returned.
      */
      virtual size_t key_length() const = 0;

      /**
      * Deprecated version of object_identifier
      */
      BOTAN_DEPRECATED("Use object_identifier") OID get_oid() const
         {
         return this->object_identifier();
         }

      /*
      * Test the key values for consistency.
      * @param rng rng to use
      * @param strong whether to perform strong and lengthy version
      * of the test
      * @return true if the test is passed
      */
      virtual bool check_key(RandomNumberGenerator& rng,
                             bool strong) const = 0;

      /**
      * @return X.509 AlgorithmIdentifier for this key
      */
      virtual AlgorithmIdentifier algorithm_identifier() const = 0;

      /**
      * @return BER encoded public key bits
      */
      virtual std::vector<uint8_t> public_key_bits() const = 0;

      /**
      * @return X.509 subject key encoding for this key object
      */
      std::vector<uint8_t> subject_public_key() const;

      /**
       * @return Hash of the subject public key
       */
      std::string fingerprint_public(const std::string& alg = "SHA-256") const;

      // Internal or non-public declarations follow

      /**
      * Returns more than 1 if the output of this algorithm
      * (ciphertext, signature) should be treated as more than one
      * value. This is used for algorithms like DSA and ECDSA, where
      * the (r,s) output pair can be encoded as either a plain binary
      * list or a TLV tagged DER encoding depending on the protocol.
      *
      * This function is public but applications should have few
      * reasons to ever call this.
      *
      * @return number of message parts
      */
      virtual size_t message_parts() const { return 1; }

      /**
      * Returns how large each of the message parts refered to
      * by message_parts() is
      *
      * This function is public but applications should have few
      * reasons to ever call this.
      *
      * @return size of the message parts in bits
      */
      virtual size_t message_part_size() const { return 0; }

      virtual Signature_Format default_x509_signature_format() const
         {
         return (this->message_parts() >= 2) ? Signature_Format::DerSequence : Signature_Format::Standard;
         }

      /**
      * This is an internal library function exposed on key types.
      * In almost all cases applications should use wrappers in pubkey.h
      *
      * Return an encryption operation for this key/params or throw
      *
      * @param rng a random number generator. The PK_Op may maintain a
      * reference to the RNG and use it many times. The rng must outlive
      * any operations which reference it.
      * @param params additional parameters
      * @param provider the provider to use
      */
      virtual std::unique_ptr<PK_Ops::Encryption>
         create_encryption_op(RandomNumberGenerator& rng,
                              const std::string& params,
                              const std::string& provider) const;

      /**
      * This is an internal library function exposed on key types.
      * In almost all cases applications should use wrappers in pubkey.h
      *
      * Return a KEM encryption operation for this key/params or throw
      *
      * @param rng a random number generator. The PK_Op may maintain a
      * reference to the RNG and use it many times. The rng must outlive
      * any operations which reference it.
      * @param params additional parameters
      * @param provider the provider to use
      */
      virtual std::unique_ptr<PK_Ops::KEM_Encryption>
         create_kem_encryption_op(RandomNumberGenerator& rng,
                                  const std::string& params,
                                  const std::string& provider) const;

      /**
      * This is an internal library function exposed on key types.
      * In almost all cases applications should use wrappers in pubkey.h
      *
      * Return a verification operation for this key/params or throw
      * @param params additional parameters
      * @param provider the provider to use
      */
      virtual std::unique_ptr<PK_Ops::Verification>
         create_verification_op(const std::string& params,
                                const std::string& provider) const;
   };

/**
* Private Key Base Class
*/
class BOTAN_PUBLIC_API(2,0) Private_Key : public virtual Public_Key
   {
   public:
      /**
      * @return BER encoded private key bits
      */
      virtual secure_vector<uint8_t> private_key_bits() const = 0;

      /**
      * Allocate a new object for the public key associated with this
      * private key.
      *
      * @return public key
      */
      virtual std::unique_ptr<Public_Key> public_key() const = 0;

      /**
      * @return PKCS #8 private key encoding for this key object
      */
      secure_vector<uint8_t> private_key_info() const;

      /**
      * @return PKCS #8 AlgorithmIdentifier for this key
      * Might be different from the X.509 identifier, but normally is not
      */
      virtual AlgorithmIdentifier pkcs8_algorithm_identifier() const
         { return algorithm_identifier(); }

      /**
      * Indicates if this key is stateful, ie that performing a private
      * key operation requires updating the key storage.
      */
      virtual bool stateful_operation() const { return false; }

      // Internal or non-public declarations follow

      /**
       * @return Hash of the PKCS #8 encoding for this key object
       */
      std::string fingerprint_private(const std::string& alg) const;

      /**
      * This is an internal library function exposed on key types.
      * In almost all cases applications should use wrappers in pubkey.h
      *
      * Return an decryption operation for this key/params or throw
      *
      * @param rng a random number generator. The PK_Op may maintain a
      * reference to the RNG and use it many times. The rng must outlive
      * any operations which reference it.
      * @param params additional parameters
      * @param provider the provider to use
      *
      */
      virtual std::unique_ptr<PK_Ops::Decryption>
         create_decryption_op(RandomNumberGenerator& rng,
                              const std::string& params,
                              const std::string& provider) const;

      /**
      * This is an internal library function exposed on key types.
      * In almost all cases applications should use wrappers in pubkey.h
      *
      * Return a KEM decryption operation for this key/params or throw
      *
      * @param rng a random number generator. The PK_Op may maintain a
      * reference to the RNG and use it many times. The rng must outlive
      * any operations which reference it.
      * @param params additional parameters
      * @param provider the provider to use
      */
      virtual std::unique_ptr<PK_Ops::KEM_Decryption>
         create_kem_decryption_op(RandomNumberGenerator& rng,
                                  const std::string& params,
                                  const std::string& provider) const;

      /**
      * This is an internal library function exposed on key types.
      * In almost all cases applications should use wrappers in pubkey.h
      *
      * Return a signature operation for this key/params or throw
      *
      * @param rng a random number generator. The PK_Op may maintain a
      * reference to the RNG and use it many times. The rng must outlive
      * any operations which reference it.
      * @param params additional parameters
      * @param provider the provider to use
      */
      virtual std::unique_ptr<PK_Ops::Signature>
         create_signature_op(RandomNumberGenerator& rng,
                             const std::string& params,
                             const std::string& provider) const;

      /**
      * This is an internal library function exposed on key types.
      * In almost all cases applications should use wrappers in pubkey.h
      *
      * Return a key agreement operation for this key/params or throw
      *
      * @param rng a random number generator. The PK_Op may maintain a
      * reference to the RNG and use it many times. The rng must outlive
      * any operations which reference it.
      * @param params additional parameters
      * @param provider the provider to use
      */
      virtual std::unique_ptr<PK_Ops::Key_Agreement>
         create_key_agreement_op(RandomNumberGenerator& rng,
                                 const std::string& params,
                                 const std::string& provider) const;
   };

/**
* PK Secret Value Derivation Key
*/
class BOTAN_PUBLIC_API(2,0) PK_Key_Agreement_Key : public virtual Private_Key
   {
   public:
      /*
      * @return public component of this key
      */
      virtual std::vector<uint8_t> public_value() const = 0;
   };

std::string BOTAN_PUBLIC_API(2,4)
   create_hex_fingerprint(const uint8_t bits[], size_t len,
                          const std::string& hash_name);

template<typename Alloc>
std::string create_hex_fingerprint(const std::vector<uint8_t, Alloc>& vec,
                                   const std::string& hash_name)
   {
   return create_hex_fingerprint(vec.data(), vec.size(), hash_name);
   }


}

#endif

Coverage Report

Created: 2023-02-22 06:14

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