diff options
| author | Jack Lloyd <[email protected]> | 2016-10-20 20:11:59 -0400 |
|---|---|---|
| committer | Jack Lloyd <[email protected]> | 2016-10-20 20:11:59 -0400 |
| commit | bad4cafce3c592cddbbecd7c99b5f99a53815ff8 (patch) | |
| tree | 50eeffe155deb4e873fff35b09a3acb20cc00cd9 | |
| parent | d1817c9960f619b130388a570ed09ccbed568e2e (diff) | |
| parent | d2fd41d1ea1ac6211705ba88de6828693a10c0b4 (diff) | |
Merge GH #670 Improve Doxygen coverage
93 files changed, 882 insertions, 142 deletions
diff --git a/src/build-data/botan.doxy.in b/src/build-data/botan.doxy.in index 013334766..90f2b9502 100644 --- a/src/build-data/botan.doxy.in +++ b/src/build-data/botan.doxy.in @@ -119,7 +119,6 @@ HTML_FILE_EXTENSION = .html HTML_HEADER = HTML_FOOTER = HTML_STYLESHEET = -HTML_ALIGN_MEMBERS = YES GENERATE_HTMLHELP = NO HTML_DYNAMIC_SECTIONS = NO CHM_FILE = @@ -149,7 +148,14 @@ EXPAND_ONLY_PREDEF = NO SEARCH_INCLUDES = YES INCLUDE_PATH = INCLUDE_FILE_PATTERNS = -PREDEFINED = +PREDEFINED = BOTAN_HAS_AES_SSSE3 \ + BOTAN_HAS_AES_NI \ + BOTAN_HAS_IDEA_SSE2 \ + BOTAN_HAS_NOEKEON_SIMD \ + BOTAN_HAS_SERPENT_SIMD \ + BOTAN_HAS_THREEFISH_512_AVX2 \ + BOTAN_HAS_SHA1_SSE2 \ + BOTAN_HAS_CHACHA_SSE2 EXPAND_AS_DEFINED = SKIP_FUNCTION_MACROS = YES diff --git a/src/lib/base/lookup.h b/src/lib/base/lookup.h index 8bf1d7ad4..391891d09 100644 --- a/src/lib/base/lookup.h +++ b/src/lib/base/lookup.h @@ -34,6 +34,7 @@ namespace Botan { * Block cipher factory method. * * @param algo_spec the name of the desired block cipher +* @param provider the provider to use * @return pointer to the block cipher object */ BOTAN_DEPRECATED("Use BlockCipher::create") @@ -63,6 +64,7 @@ inline std::vector<std::string> get_block_cipher_providers(const std::string& al * Stream cipher factory method. * * @param algo_spec the name of the desired stream cipher +* @param provider the provider to use * @return pointer to the stream cipher object */ BOTAN_DEPRECATED("Use StreamCipher::create") @@ -92,6 +94,7 @@ inline std::vector<std::string> get_stream_cipher_providers(const std::string& a * Hash function factory method. * * @param algo_spec the name of the desired hash function +* @param provider the provider to use * @return pointer to the hash function object */ BOTAN_DEPRECATED("Use HashFunction::create") @@ -128,6 +131,7 @@ inline std::vector<std::string> get_hash_function_providers(const std::string& a * MAC factory method. * * @param algo_spec the name of the desired MAC +* @param provider the provider to use * @return pointer to the MAC object */ BOTAN_DEPRECATED("MessageAuthenticationCode::create") diff --git a/src/lib/base/sym_algo.h b/src/lib/base/sym_algo.h index c8c93ba34..a3f301b37 100644 --- a/src/lib/base/sym_algo.h +++ b/src/lib/base/sym_algo.h @@ -86,7 +86,7 @@ class BOTAN_DLL SymmetricAlgorithm key_schedule(key, length); } - /* + /** * @return the algorithm name */ virtual std::string name() const = 0; diff --git a/src/lib/block/block_cipher.h b/src/lib/block/block_cipher.h index b16468958..7c7084155 100644 --- a/src/lib/block/block_cipher.h +++ b/src/lib/block/block_cipher.h @@ -24,14 +24,17 @@ class BOTAN_DLL BlockCipher : public SymmetricAlgorithm /** * Create an instance based on a name - * Will return a null pointer if the algo/provider combination cannot - * be found. If provider is empty then best available is chosen. + * If provider is empty then best available is chosen. + * @param algo_spec algorithm name + * @param provider provider implementation to choose + * @return a null pointer if the algo/provider combination cannot be found */ static std::unique_ptr<BlockCipher> create(const std::string& algo_spec, const std::string& provider = ""); /** - * Returns the list of available providers for this algorithm, empty if not available + * @return list of available providers for this algorithm, empty if not available + * @param algo_spec algorithm name */ static std::vector<std::string> providers(const std::string& algo_spec); diff --git a/src/lib/cert/x509/certstor_sqlite3/certstor_sqlite.h b/src/lib/cert/x509/certstor_sqlite3/certstor_sqlite.h index 11ad811ff..d1a1e3d21 100644 --- a/src/lib/cert/x509/certstor_sqlite3/certstor_sqlite.h +++ b/src/lib/cert/x509/certstor_sqlite3/certstor_sqlite.h @@ -20,7 +20,7 @@ class BOTAN_DLL Certificate_Store_In_SQLite : public Certificate_Store_In_SQL public: /** * Create/open a certificate store. - * @param db underlying database storage + * @param db_path path to the database file * @param passwd password to encrypt private keys in the database * @param rng used for encrypting keys * @param table_prefix optional prefix for db table names diff --git a/src/lib/cert/x509/key_constraint.h b/src/lib/cert/x509/key_constraint.h index b67eb7010..02c65acec 100644 --- a/src/lib/cert/x509/key_constraint.h +++ b/src/lib/cert/x509/key_constraint.h @@ -35,7 +35,7 @@ class Public_Key; /** * Check that key constraints are permitted for a specific public key. * @param pub_key the public key on which the constraints shall be enforced on -* @param constrains the constraints that shall be enforced on the key +* @param constraints the constraints that shall be enforced on the key * @throw Exception if the given constraints are not permitted for this key */ BOTAN_DLL void verify_cert_constraints_valid_for_key_type(const Public_Key& pub_key, diff --git a/src/lib/cert/x509/x509_ca.h b/src/lib/cert/x509/x509_ca.h index 218ee0803..c96a709d5 100644 --- a/src/lib/cert/x509/x509_ca.h +++ b/src/lib/cert/x509/x509_ca.h @@ -96,6 +96,7 @@ class BOTAN_DLL X509_CA * @param ca_certificate the certificate of the CA * @param key the private key of the CA * @param hash_fn name of a hash function to use for signing + * @param rng the random generator to use */ X509_CA(const X509_Certificate& ca_certificate, const Private_Key& key, @@ -129,6 +130,7 @@ class BOTAN_DLL X509_CA * Choose the default signature format for a certain public key signature * scheme. * @param key will be the key to choose a padding scheme for +* @param rng the random generator to use * @param hash_fn is the desired hash function * @param alg_id will be set to the chosen scheme * @return A PK_Signer object for generating signatures diff --git a/src/lib/cert/x509/x509path.h b/src/lib/cert/x509/x509path.h index cfcf44511..362f65852 100644 --- a/src/lib/cert/x509/x509path.h +++ b/src/lib/cert/x509/x509path.h @@ -130,7 +130,7 @@ class BOTAN_DLL Path_Validation_Result std::string result_string() const; /** - * @param validation status code + * @param code validation status code * @return corresponding validation status message */ static const char* status_string(Certificate_Status_Code code); @@ -145,7 +145,7 @@ class BOTAN_DLL Path_Validation_Result /** * Create a Path_Validation_Result - * @status status validation status code + * @param status validation status code */ explicit Path_Validation_Result(Certificate_Status_Code status) : m_overall(status) {} diff --git a/src/lib/compression/compression.h b/src/lib/compression/compression.h index db2722305..f135f6d04 100644 --- a/src/lib/compression/compression.h +++ b/src/lib/compression/compression.h @@ -33,7 +33,7 @@ class BOTAN_DLL Compression_Algorithm /** * Process some data. Input must be in size update_granularity() byte blocks. - * @param blocks in/out parameter which will possibly be resized or swapped + * @param buf in/out parameter which will possibly be resized or swapped * @param offset an offset into blocks to begin processing * @param flush if true the compressor will be told to flush state */ @@ -77,7 +77,7 @@ class BOTAN_DLL Decompression_Algorithm /** * Process some data. Input must be in size update_granularity() byte blocks. - * @param blocks in/out parameter which will possibly be resized or swapped + * @param buf in/out parameter which will possibly be resized or swapped * @param offset an offset into blocks to begin processing */ virtual void update(secure_vector<byte>& buf, size_t offset = 0) = 0; diff --git a/src/lib/entropy/unix_procs/unix_procs.cpp b/src/lib/entropy/unix_procs/unix_procs.cpp index d8dceba52..eae1b5255 100644 --- a/src/lib/entropy/unix_procs/unix_procs.cpp +++ b/src/lib/entropy/unix_procs/unix_procs.cpp @@ -60,10 +60,10 @@ size_t concurrent_processes(size_t user_request) /** * Unix_EntropySource Constructor */ -Unix_EntropySource::Unix_EntropySource(const std::vector<std::string>& trusted_path, - size_t proc_cnt) : - m_trusted_paths(trusted_path), - m_concurrent(concurrent_processes(proc_cnt)) +Unix_EntropySource::Unix_EntropySource(const std::vector<std::string>& trusted_paths, + size_t proc_count) : + m_trusted_paths(trusted_paths), + m_concurrent(concurrent_processes(proc_count)) { } diff --git a/src/lib/entropy/unix_procs/unix_procs.h b/src/lib/entropy/unix_procs/unix_procs.h index f87881d54..24c10fff0 100644 --- a/src/lib/entropy/unix_procs/unix_procs.h +++ b/src/lib/entropy/unix_procs/unix_procs.h @@ -32,9 +32,11 @@ class Unix_EntropySource final : public Entropy_Source * to contain only 'safe' binaries. If an attacker can write * an executable to one of these directories then we will * run arbitrary code. + * @param proc_count number of concurrent processes executing, + * when set to zero, number of processors is used */ Unix_EntropySource(const std::vector<std::string>& trusted_paths, - size_t concurrent_processes = 0); + size_t proc_count = 0); private: static std::vector<std::vector<std::string>> get_default_sources(); diff --git a/src/lib/filters/filters.h b/src/lib/filters/filters.h index 4f559587f..2b6e2b1cd 100644 --- a/src/lib/filters/filters.h +++ b/src/lib/filters/filters.h @@ -106,7 +106,7 @@ class BOTAN_DLL Hash_Filter : public Filter /** * Construct a hash filter. - * @param hash_fun the hash function to use + * @param hash the hash function to use * @param len the output length of this filter. Leave the default * value 0 if you want to use the full output of the hashfunction * hash. Otherwise, specify a smaller value here so that the diff --git a/src/lib/hash/hash.h b/src/lib/hash/hash.h index 08b5d5243..206333b9f 100644 --- a/src/lib/hash/hash.h +++ b/src/lib/hash/hash.h @@ -24,14 +24,17 @@ class BOTAN_DLL HashFunction : public Buffered_Computation /** * Create an instance based on a name - * Will return a null pointer if the algo/provider combination cannot - * be found. If provider is empty then best available is chosen. + * If provider is empty then best available is chosen. + * @param algo_spec algorithm name + * @param provider provider implementation to use + * @return a null pointer if the algo/provider combination cannot be found */ static std::unique_ptr<HashFunction> create(const std::string& algo_spec, const std::string& provider = ""); /** - * Returns the list of available providers for this algorithm, empty if not available + * @return list of available providers for this algorithm, empty if not available + * @param algo_spec algorithm name */ static std::vector<std::string> providers(const std::string& algo_spec); @@ -50,8 +53,14 @@ class BOTAN_DLL HashFunction : public Buffered_Computation virtual ~HashFunction(); + /** + * Reset the state. + */ virtual void clear() = 0; + /** + * @return the hash function name + */ virtual std::string name() const = 0; /** diff --git a/src/lib/kdf/hkdf/hkdf.h b/src/lib/kdf/hkdf/hkdf.h index 1dba82ee2..ea17f8c01 100644 --- a/src/lib/kdf/hkdf/hkdf.h +++ b/src/lib/kdf/hkdf/hkdf.h @@ -15,12 +15,16 @@ namespace Botan { /** -* HKDF, see @rfc 5869 for details -* This is only the expansion portion of HKDF +* HKDF, see RFC 5869 for details. +* This is only the expansion portion of HKDF. +* An appropriate extraction function should be used before. */ class BOTAN_DLL HKDF final : public KDF { public: + /** + * @param prf MAC algorithm to use + */ explicit HKDF(MessageAuthenticationCode* prf) : m_prf(prf) {} static HKDF* make(const Spec& spec); diff --git a/src/lib/kdf/kdf.h b/src/lib/kdf/kdf.h index 3c8a7a013..f9acb9d38 100644 --- a/src/lib/kdf/kdf.h +++ b/src/lib/kdf/kdf.h @@ -25,25 +25,41 @@ class BOTAN_DLL KDF /** * Create an instance based on a name - * Will return a null pointer if the algo/provider combination cannot - * be found. If provider is empty then best available is chosen. + * If provider is empty then best available is chosen. + * @param algo_spec algorithm name + * @param provider provider implementation to choose + * @return a null pointer if the algo/provider combination cannot be found */ static std::unique_ptr<KDF> create(const std::string& algo_spec, const std::string& provider = ""); /** - * Returns the list of available providers for this algorithm, empty if not available + * @return list of available providers for this algorithm, empty if not available */ static std::vector<std::string> providers(const std::string& algo_spec); + /** + * @return KDF name + */ virtual std::string name() const = 0; + /** + * Derive a key + * @param key buffer holding the derived key, must be of length key_len + * @param key_len the desired output length in bytes + * @param secret the secret input + * @param secret_len size of secret in bytes + * @param salt a diversifier + * @param salt_len size of salt in bytes + * @param label purpose for the derived keying material + * @param label_len size of label in bytes + * @return the derived key + */ virtual size_t kdf(byte key[], size_t key_len, const byte secret[], size_t secret_len, const byte salt[], size_t salt_len, const byte label[], size_t label_len) const = 0; - /** * Derive a key * @param key_len the desired output length in bytes @@ -53,6 +69,7 @@ class BOTAN_DLL KDF * @param salt_len size of salt in bytes * @param label purpose for the derived keying material * @param label_len size of label in bytes + * @return the derived key */ secure_vector<byte> derive_key(size_t key_len, const byte secret[], @@ -73,6 +90,7 @@ class BOTAN_DLL KDF * @param secret the secret input * @param salt a diversifier * @param label purpose for the derived keying material + * @return the derived key */ secure_vector<byte> derive_key(size_t key_len, const secure_vector<byte>& secret, @@ -93,6 +111,7 @@ class BOTAN_DLL KDF * @param secret the secret input * @param salt a diversifier * @param label purpose for the derived keying material + * @return the derived key */ template<typename Alloc, typename Alloc2, typename Alloc3> secure_vector<byte> derive_key(size_t key_len, @@ -113,6 +132,7 @@ class BOTAN_DLL KDF * @param salt a diversifier * @param salt_len size of salt in bytes * @param label purpose for the derived keying material + * @return the derived key */ secure_vector<byte> derive_key(size_t key_len, const secure_vector<byte>& secret, @@ -134,6 +154,7 @@ class BOTAN_DLL KDF * @param secret_len size of secret in bytes * @param salt a diversifier * @param label purpose for the derived keying material + * @return the derived key */ secure_vector<byte> derive_key(size_t key_len, const byte secret[], @@ -148,10 +169,12 @@ class BOTAN_DLL KDF label.length()); } + /** + * @return new object representing the same algorithm as *this + */ virtual KDF* clone() const = 0; typedef SCAN_Name Spec; - }; /** @@ -159,7 +182,7 @@ class BOTAN_DLL KDF * @param algo_spec the name of the KDF to create * @return pointer to newly allocated object of that type */ -BOTAN_DLL KDF* get_kdf(const std::string& algo_spec); +BOTAN_DLL KDF* get_kdf(const std::string& algo_spec); } diff --git a/src/lib/kdf/kdf1/kdf1.h b/src/lib/kdf/kdf1/kdf1.h index 59bff4d8d..db8b3b062 100644 --- a/src/lib/kdf/kdf1/kdf1.h +++ b/src/lib/kdf/kdf1/kdf1.h @@ -28,6 +28,9 @@ class BOTAN_DLL KDF1 final : public KDF const byte salt[], size_t salt_len, const byte label[], size_t label_len) const override; + /** + * @param h hash function to use + */ explicit KDF1(HashFunction* h) : m_hash(h) {} private: std::unique_ptr<HashFunction> m_hash; diff --git a/src/lib/kdf/kdf1_iso18033/kdf1_iso18033.h b/src/lib/kdf/kdf1_iso18033/kdf1_iso18033.h index f61864d1f..08e2d5c61 100644 --- a/src/lib/kdf/kdf1_iso18033/kdf1_iso18033.h +++ b/src/lib/kdf/kdf1_iso18033/kdf1_iso18033.h @@ -28,6 +28,9 @@ class BOTAN_DLL KDF1_18033 : public KDF const byte salt[], size_t salt_len, const byte label[], size_t label_len) const override; + /** + * @param h hash function to use + */ KDF1_18033(HashFunction* h) : m_hash(h) {} private: std::unique_ptr<HashFunction> m_hash; diff --git a/src/lib/kdf/kdf2/kdf2.h b/src/lib/kdf/kdf2/kdf2.h index 600f7c91c..2ead49530 100644 --- a/src/lib/kdf/kdf2/kdf2.h +++ b/src/lib/kdf/kdf2/kdf2.h @@ -28,6 +28,9 @@ class BOTAN_DLL KDF2 final : public KDF const byte salt[], size_t salt_len, const byte label[], size_t label_len) const override; + /** + * @param h hash function to use + */ explicit KDF2(HashFunction* h) : m_hash(h) {} private: std::unique_ptr<HashFunction> m_hash; diff --git a/src/lib/kdf/prf_tls/prf_tls.h b/src/lib/kdf/prf_tls/prf_tls.h index 37a517125..58cd5758e 100644 --- a/src/lib/kdf/prf_tls/prf_tls.h +++ b/src/lib/kdf/prf_tls/prf_tls.h @@ -49,6 +49,9 @@ class BOTAN_DLL TLS_12_PRF final : public KDF const byte salt[], size_t salt_len, const byte label[], size_t label_len) const override; + /** + * @param mac MAC algorithm to use + */ explicit TLS_12_PRF(MessageAuthenticationCode* mac) : m_mac(mac) {} static TLS_12_PRF* make(const Spec& spec); diff --git a/src/lib/kdf/sp800_108/sp800_108.h b/src/lib/kdf/sp800_108/sp800_108.h index 71a918c15..2d4d028b2 100644 --- a/src/lib/kdf/sp800_108/sp800_108.h +++ b/src/lib/kdf/sp800_108/sp800_108.h @@ -45,6 +45,9 @@ class BOTAN_DLL SP800_108_Counter : public KDF const byte salt[], size_t salt_len, const byte label[], size_t label_len) const override; + /** + * @param mac MAC algorithm to use + */ SP800_108_Counter(MessageAuthenticationCode* mac) : m_prf(mac) {} static SP800_108_Counter* make(const Spec& spec); diff --git a/src/lib/kdf/sp800_56c/sp800_56c.h b/src/lib/kdf/sp800_56c/sp800_56c.h index 1281ed314..83f11906a 100644 --- a/src/lib/kdf/sp800_56c/sp800_56c.h +++ b/src/lib/kdf/sp800_56c/sp800_56c.h @@ -45,6 +45,10 @@ class BOTAN_DLL SP800_56C : public KDF const byte salt[], size_t salt_len, const byte label[], size_t label_len) const override; + /** + * @param mac MAC algorithm used for randomness extraction + * @param exp KDF used for key expansion + */ SP800_56C(MessageAuthenticationCode* mac, KDF* exp) : m_prf(mac), m_exp(exp) {} static SP800_56C* make(const Spec& spec); diff --git a/src/lib/mac/cbc_mac/cbc_mac.h b/src/lib/mac/cbc_mac/cbc_mac.h index cd2ebd18f..4a3dece95 100644 --- a/src/lib/mac/cbc_mac/cbc_mac.h +++ b/src/lib/mac/cbc_mac/cbc_mac.h @@ -30,7 +30,7 @@ class BOTAN_DLL CBC_MAC final : public MessageAuthenticationCode } /** - * @param cipher the underlying block cipher to use + * @param cipher the block cipher to use */ explicit CBC_MAC(BlockCipher* cipher); diff --git a/src/lib/mac/cmac/cmac.h b/src/lib/mac/cmac/cmac.h index 0e973b79d..fac754e62 100644 --- a/src/lib/mac/cmac/cmac.h +++ b/src/lib/mac/cmac/cmac.h @@ -33,12 +33,11 @@ class BOTAN_DLL CMAC final : public MessageAuthenticationCode /** * CMAC's polynomial doubling operation * @param in the input - * @param polynomial the byte value of the polynomial */ static secure_vector<byte> poly_double(const secure_vector<byte>& in); /** - * @param cipher the underlying block cipher to use + * @param cipher the block cipher to use */ explicit CMAC(BlockCipher* cipher); diff --git a/src/lib/mac/mac.h b/src/lib/mac/mac.h index ae8ea5405..69b7ea581 100644 --- a/src/lib/mac/mac.h +++ b/src/lib/mac/mac.h @@ -26,14 +26,16 @@ class BOTAN_DLL MessageAuthenticationCode : public Buffered_Computation, /** * Create an instance based on a name - * Will return a null pointer if the algo/provider combination cannot - * be found. If provider is empty then best available is chosen. + * If provider is empty then best available is chosen. + * @param algo_spec algorithm name + * @param provider provider implementation to use + * @return a null pointer if the algo/provider combination cannot be found */ static std::unique_ptr<MessageAuthenticationCode> create(const std::string& algo_spec, const std::string& provider = ""); /** - * Returns the list of available providers for this algorithm, empty if not available + * @return list of available providers for this algorithm, empty if not available */ static std::vector<std::string> providers(const std::string& algo_spec); @@ -48,7 +50,7 @@ class BOTAN_DLL MessageAuthenticationCode : public Buffered_Computation, virtual bool verify_mac(const byte in[], size_t length); /** - * Get a new object representing the same algorithm as *this + * @return a new object representing the same algorithm as *this */ virtual MessageAuthenticationCode* clone() const = 0; diff --git a/src/lib/math/numbertheory/numthry.h b/src/lib/math/numbertheory/numthry.h index 591b61f6a..172c56a34 100644 --- a/src/lib/math/numbertheory/numthry.h +++ b/src/lib/math/numbertheory/numthry.h @@ -204,7 +204,6 @@ BigInt BOTAN_DLL random_safe_prime(RandomNumberGenerator& rng, /** * Generate DSA parameters using the FIPS 186 kosherizer * @param rng a random number generator -* @param af an algorithm factory * @param p_out where the prime p will be stored * @param q_out where the prime q will be stored * @param pbits how long p will be in bits @@ -219,7 +218,6 @@ generate_dsa_primes(RandomNumberGenerator& rng, /** * Generate DSA parameters using the FIPS 186 kosherizer * @param rng a random number generator -* @param af an algorithm factory * @param p_out where the prime p will be stored * @param q_out where the prime q will be stored * @param pbits how long p will be in bits diff --git a/src/lib/misc/pbes2/pbes2.h b/src/lib/misc/pbes2/pbes2.h index ea2f9aa1d..7c8c4095d 100644 --- a/src/lib/misc/pbes2/pbes2.h +++ b/src/lib/misc/pbes2/pbes2.h @@ -16,6 +16,7 @@ namespace Botan { /** * Encrypt with PBES2 from PKCS #5 v2.0 +* @param key_bits the input * @param passphrase the passphrase to use for encryption * @param msec how many milliseconds to run PBKDF2 * @param cipher specifies the block cipher to use to encrypt diff --git a/src/lib/misc/pem/pem.h b/src/lib/misc/pem/pem.h index aaae5ee35..acbd40a77 100644 --- a/src/lib/misc/pem/pem.h +++ b/src/lib/misc/pem/pem.h @@ -16,6 +16,10 @@ namespace PEM_Code { /** * Encode some binary data in PEM format +* @param data binary data to encode +* @param data_len length of binary data in bytes +* @param label PEM label put after BEGIN and END +* @param line_width after this many characters, a new line is inserted */ BOTAN_DLL std::string encode(const byte data[], size_t data_len, @@ -24,6 +28,9 @@ BOTAN_DLL std::string encode(const byte data[], /** * Encode some binary data in PEM format +* @param data binary data to encode +* @param label PEM label +* @param line_width after this many characters, a new line is inserted */ inline std::string encode(const std::vector<byte>& data, const std::string& label, @@ -34,6 +41,9 @@ inline std::string encode(const std::vector<byte>& data, /** * Encode some binary data in PEM format +* @param data binary data to encode +* @param label PEM label put after BEGIN and END +* @param line_width after this many characters, a new line is inserted */ inline std::string encode(const secure_vector<byte>& data, const std::string& label, diff --git a/src/lib/misc/rfc3394/rfc3394.h b/src/lib/misc/rfc3394/rfc3394.h index fab6bc3cb..af869505a 100644 --- a/src/lib/misc/rfc3394/rfc3394.h +++ b/src/lib/misc/rfc3394/rfc3394.h @@ -29,7 +29,6 @@ secure_vector<byte> BOTAN_DLL rfc3394_keywrap(const secure_vector<byte>& key, * * @param key the encrypted key to decrypt * @param kek the key encryption key -* @param af an algorithm factory * @return key decrypted under kek */ secure_vector<byte> BOTAN_DLL rfc3394_keyunwrap(const secure_vector<byte>& key, diff --git a/src/lib/misc/srp6/srp6_files.h b/src/lib/misc/srp6/srp6_files.h index db128727e..8c899aad6 100644 --- a/src/lib/misc/srp6/srp6_files.h +++ b/src/lib/misc/srp6/srp6_files.h @@ -27,6 +27,14 @@ class BOTAN_DLL SRP6_Authenticator_File */ explicit SRP6_Authenticator_File(std::istream& input); + /** + * Looks up a user in the authenticator file. + * @param username user to look up + * @param v set to the host's password verifier + * @param salt set to the user's salt value + * @param group_id set to the user's group value + * @return whether a user exists in the authenticator file + */ bool lookup_user(const std::string& username, BigInt& v, std::vector<byte>& salt, diff --git a/src/lib/modes/aead/aead.h b/src/lib/modes/aead/aead.h index 3214187db..0769a1829 100644 --- a/src/lib/modes/aead/aead.h +++ b/src/lib/modes/aead/aead.h @@ -38,12 +38,30 @@ class BOTAN_DLL AEAD_Mode : public Cipher_Mode */ virtual void set_associated_data(const byte ad[], size_t ad_len) = 0; + /** + * Set associated data that is not included in the ciphertext but + * that should be authenticated. Must be called after set_key and + * before start. + * + * See @ref set_associated_data(). + * + * @param ad the associated data + */ template<typename Alloc> void set_associated_data_vec(const std::vector<byte, Alloc>& ad) { set_associated_data(ad.data(), ad.size()); } + /** + * Set associated data that is not included in the ciphertext but + * that should be authenticated. Must be called after set_key and + * before start. + * + * See @ref set_associated_data(). + * + * @param ad the associated data + */ template<typename Alloc> void set_ad(const std::vector<byte, Alloc>& ad) { @@ -51,8 +69,8 @@ class BOTAN_DLL AEAD_Mode : public Cipher_Mode } /** - * Default AEAD nonce size (a commonly supported value among AEAD - * modes, and large enough that random collisions are unlikely). + * @return default AEAD nonce size (a commonly supported value among AEAD + * modes, and large enough that random collisions are unlikely) */ size_t default_nonce_length() const override { return 12; } @@ -61,6 +79,8 @@ class BOTAN_DLL AEAD_Mode : public Cipher_Mode /** * Get an AEAD mode by name (eg "AES-128/GCM" or "Serpent/EAX") +* @param name AEAD name +* @param direction ENCRYPTION or DECRYPTION */ BOTAN_DLL AEAD_Mode* get_aead(const std::string& name, Cipher_Dir direction); diff --git a/src/lib/modes/aead/siv/siv.h b/src/lib/modes/aead/siv/siv.h index 6acfe515a..ca3e7df37 100644 --- a/src/lib/modes/aead/siv/siv.h +++ b/src/lib/modes/aead/siv/siv.h @@ -23,6 +23,12 @@ class BOTAN_DLL SIV_Mode : public AEAD_Mode public: size_t process(uint8_t buf[], size_t size) override; + /** + * Sets the nth element of the vector of associated data + * @param n index into the AD vector + * @param ad associated data + * @param ad_len length of associated data in bytes + */ void set_associated_data_n(size_t n, const byte ad[], size_t ad_len); void set_associated_data(const byte ad[], size_t ad_len) override diff --git a/src/lib/modes/cbc/cbc.h b/src/lib/modes/cbc/cbc.h index caad102d4..c6b6e4e4b 100644 --- a/src/lib/modes/cbc/cbc.h +++ b/src/lib/modes/cbc/cbc.h @@ -62,6 +62,10 @@ class BOTAN_DLL CBC_Mode : public Cipher_Mode class BOTAN_DLL CBC_Encryption : public CBC_Mode { public: + /** + * @param cipher block cipher to use + * @param padding padding method to use + */ CBC_Encryption(BlockCipher* cipher, BlockCipherModePaddingMethod* padding) : CBC_Mode(cipher, padding) {} @@ -80,6 +84,9 @@ class BOTAN_DLL CBC_Encryption : public CBC_Mode class BOTAN_DLL CTS_Encryption final : public CBC_Encryption { public: + /** + * @param cipher block cipher to use + */ explicit CTS_Encryption(BlockCipher* cipher) : CBC_Encryption(cipher, nullptr) {} size_t output_length(size_t input_length) const override; @@ -97,6 +104,10 @@ class BOTAN_DLL CTS_Encryption final : public CBC_Encryption class BOTAN_DLL CBC_Decryption : public CBC_Mode { public: + /** + * @param cipher block cipher to use + * @param padding padding method to use + */ CBC_Decryption(BlockCipher* cipher, BlockCipherModePaddingMethod* padding) : CBC_Mode(cipher, padding), m_tempbuf(update_granularity()) {} @@ -117,6 +128,9 @@ class BOTAN_DLL CBC_Decryption : public CBC_Mode class BOTAN_DLL CTS_Decryption final : public CBC_Decryption { public: + /** + * @param cipher block cipher to use + */ explicit CTS_Decryption(BlockCipher* cipher) : CBC_Decryption(cipher, nullptr) {} void finish(secure_vector<byte>& final_block, size_t offset = 0) override; diff --git a/src/lib/modes/cfb/cfb.h b/src/lib/modes/cfb/cfb.h index 2ec87244e..318bdab64 100644 --- a/src/lib/modes/cfb/cfb.h +++ b/src/lib/modes/cfb/cfb.h @@ -61,6 +61,12 @@ class BOTAN_DLL CFB_Mode : public Cipher_Mode class BOTAN_DLL CFB_Encryption final : public CFB_Mode { public: + /** + * If feedback_bits is zero, cipher->block_size() bytes will be used. + * @param cipher block cipher to use + * @param feedback_bits number of bits fed back into the shift register, + * must be a multiple of 8 + */ CFB_Encryption(BlockCipher* cipher, size_t feedback_bits) : CFB_Mode(cipher, feedback_bits) {} @@ -75,6 +81,12 @@ class BOTAN_DLL CFB_Encryption final : public CFB_Mode class BOTAN_DLL CFB_Decryption final : public CFB_Mode { public: + /** + * If feedback_bits is zero, cipher->block_size() bytes will be used. + * @param cipher block cipher to use + * @param feedback_bits number of bits fed back into the shift register, + * must be a multiple of 8 + */ CFB_Decryption(BlockCipher* cipher, size_t feedback_bits) : CFB_Mode(cipher, feedback_bits) {} diff --git a/src/lib/modes/cipher_mode.h b/src/lib/modes/cipher_mode.h index d890870c1..f08989a9e 100644 --- a/src/lib/modes/cipher_mode.h +++ b/src/lib/modes/cipher_mode.h @@ -69,13 +69,16 @@ class BOTAN_DLL Cipher_Mode * Processes msg in place and returns bytes written. Normally * this will be either msg_len (indicating the entire message was * processes) or for certain AEAD modes zero (indicating that the - * mode requires the entire message be processed in one pass. + * mode requires the entire message be processed in one pass). + * + * @param msg the message to be processed + * @param msg_len length of the message in bytes */ virtual size_t process(uint8_t msg[], size_t msg_len) = 0; /** * Process some data. Input must be in size update_granularity() byte blocks. - * @param blocks in/out parameter which will possibly be resized + * @param buffer in/out parameter which will possibly be resized * @param offset an offset into blocks to begin processing */ void update(secure_vector<byte>& buffer, size_t offset = 0) @@ -116,12 +119,12 @@ class BOTAN_DLL Cipher_Mode virtual size_t minimum_final_size() const = 0; /** - * Return the default size for a nonce + * @return the default size for a nonce */ virtual size_t default_nonce_length() const = 0; /** - * Return true iff nonce_len is a valid length for the nonce + * @return true iff nonce_len is a valid length for the nonce */ virtual bool valid_nonce_length(size_t nonce_len) const = 0; @@ -130,13 +133,13 @@ class BOTAN_DLL Cipher_Mode virtual void clear() = 0; /** - * Returns true iff this mode provides authentication as well as + * @return true iff this mode provides authentication as well as * confidentiality. */ virtual bool authenticated() const { return false; } /** - * Return the size of the authentication tag used (in bytes) + * @return the size of the authentication tag used (in bytes) */ virtual size_t tag_size() const { return 0; } @@ -155,12 +158,20 @@ class BOTAN_DLL Cipher_Mode return key_spec().valid_keylength(length); } + /** + * Set the symmetric key of this transform + * @param key contains the key material + */ template<typename Alloc> void set_key(const std::vector<byte, Alloc>& key) { set_key(key.data(), key.size()); } + /** + * Set the symmetric key of this transform + * @param key contains the key material + */ void set_key(const SymmetricKey& key) { set_key(key.begin(), key.length()); @@ -194,6 +205,11 @@ class BOTAN_DLL Cipher_Mode */ enum Cipher_Dir { ENCRYPTION, DECRYPTION }; +/** +* Get a cipher mode by name (eg "AES-128/CBC" or "Serpent/XTS") +* @param algo_spec cipher name +* @param direction ENCRYPTION or DECRYPTION +*/ BOTAN_DLL Cipher_Mode* get_cipher_mode(const std::string& algo_spec, Cipher_Dir direction); } diff --git a/src/lib/modes/ecb/ecb.h b/src/lib/modes/ecb/ecb.h index 9ebbf76a4..4d2a11d05 100644 --- a/src/lib/modes/ecb/ecb.h +++ b/src/lib/modes/ecb/ecb.h @@ -52,6 +52,10 @@ class BOTAN_DLL ECB_Mode : public Cipher_Mode class BOTAN_DLL ECB_Encryption final : public ECB_Mode { public: + /** + * @param cipher block cipher to use + * @param padding padding method to use + */ ECB_Encryption(BlockCipher* cipher, BlockCipherModePaddingMethod* padding) : ECB_Mode(cipher, padding) {} @@ -70,6 +74,10 @@ class BOTAN_DLL ECB_Encryption final : public ECB_Mode class BOTAN_DLL ECB_Decryption final : public ECB_Mode { public: + /** + * @param cipher block cipher to use + * @param padding padding method to use + */ ECB_Decryption(BlockCipher* cipher, BlockCipherModePaddingMethod* padding) : ECB_Mode(cipher, padding) {} diff --git a/src/lib/modes/mode_pad/mode_pad.h b/src/lib/modes/mode_pad/mode_pad.h index bc2b7c132..d52fbd7b6 100644 --- a/src/lib/modes/mode_pad/mode_pad.h +++ b/src/lib/modes/mode_pad/mode_pad.h @@ -25,13 +25,20 @@ namespace Botan { class BOTAN_DLL BlockCipherModePaddingMethod { public: + /** + * Add padding bytes to buffer. + * @param buffer data to pad + * @param final_block_bytes size of the final block in bytes + * @param block_size size of each block in bytes + */ virtual void add_padding(secure_vector<byte>& buffer, size_t final_block_bytes, size_t block_size) const = 0; /** + * Remove padding bytes from block * @param block the last block - * @param size the of the block + * @param size the size of the block in bytes * @return number of padding bytes */ virtual size_t unpad(const byte block[], @@ -120,6 +127,10 @@ class BOTAN_DLL Null_Padding final : public BlockCipherModePaddingMethod std::string name() const override { return "NoPadding"; } }; +/** +* Get a block cipher padding mode by name (eg "NoPadding" or "PKCS7") +* @param algo_spec block cipher padding mode name +*/ BOTAN_DLL BlockCipherModePaddingMethod* get_bc_pad(const std::string& algo_spec); } diff --git a/src/lib/modes/stream_mode.h b/src/lib/modes/stream_mode.h index f59f6d9ba..3a0c8574c 100644 --- a/src/lib/modes/stream_mode.h +++ b/src/lib/modes/stream_mode.h @@ -15,6 +15,9 @@ namespace Botan { class BOTAN_DLL Stream_Cipher_Mode : public Cipher_Mode { public: + /** + * @param cipher underyling stream cipher + */ explicit Stream_Cipher_Mode(StreamCipher* cipher) : m_cipher(cipher) {} size_t process(uint8_t buf[], size_t sz) override diff --git a/src/lib/modes/xts/xts.h b/src/lib/modes/xts/xts.h index 6c4ba8d99..1216251c2 100644 --- a/src/lib/modes/xts/xts.h +++ b/src/lib/modes/xts/xts.h @@ -55,6 +55,9 @@ class BOTAN_DLL XTS_Mode : public Cipher_Mode class BOTAN_DLL XTS_Encryption final : public XTS_Mode { public: + /** + * @param cipher underlying block cipher + */ explicit XTS_Encryption(BlockCipher* cipher) : XTS_Mode(cipher) {} size_t process(uint8_t buf[], size_t size) override; @@ -70,6 +73,9 @@ class BOTAN_DLL XTS_Encryption final : public XTS_Mode class BOTAN_DLL XTS_Decryption final : public XTS_Mode { public: + /** + * @param cipher underlying block cipher + */ explicit XTS_Decryption(BlockCipher* cipher) : XTS_Mode(cipher) {} size_t process(uint8_t buf[], size_t size) override; diff --git a/src/lib/pbkdf/pbkdf.h b/src/lib/pbkdf/pbkdf.h index 495da0ac9..63a8a82f0 100644 --- a/src/lib/pbkdf/pbkdf.h +++ b/src/lib/pbkdf/pbkdf.h @@ -26,14 +26,16 @@ class BOTAN_DLL PBKDF public: /** * Create an instance based on a name - * Will return a null pointer if the algo/provider combination cannot - * be found. If provider is empty then best available is chosen. + * If provider is empty then best available is chosen. + * @param algo_spec algorithm name + * @param provider provider implementation to choose + * @return a null pointer if the algo/provider combination cannot be found */ static std::unique_ptr<PBKDF> create(const std::string& algo_spec, const std::string& provider = ""); /** - * Returns the list of available providers for this algorithm, empty if not available + * @return list of available providers for this algorithm, empty if not available */ static std::vector<std::string> providers(const std::string& algo_spec); @@ -44,6 +46,9 @@ class BOTAN_DLL PBKDF */ virtual PBKDF* clone() const = 0; + /** + * @return name of this PBKDF + */ virtual std::string name() const = 0; virtual ~PBKDF(); @@ -51,8 +56,9 @@ class BOTAN_DLL PBKDF /** * Derive a key from a passphrase for a number of iterations * specified by either iterations or if iterations == 0 then - * running until seconds time has elapsed. + * running until msec time has elapsed. * + * @param out buffer to store the derived key, must be of out_len bytes * @param out_len the desired length of the key to produce * @param passphrase the password to derive the key from * @param salt a randomly chosen salt @@ -68,22 +74,66 @@ class BOTAN_DLL PBKDF size_t iterations, std::chrono::milliseconds msec) const = 0; + /** + * Derive a key from a passphrase for a number of iterations. + * + * @param out buffer to store the derived key, must be of out_len bytes + * @param out_len the desired length of the key to produce + * @param passphrase the password to derive the key from + * @param salt a randomly chosen salt + * @param salt_len length of salt in bytes + * @param iterations the number of iterations to use (use 10K or more) + */ void pbkdf_iterations(byte out[], size_t out_len, const std::string& passphrase, const byte salt[], size_t salt_len, size_t iterations) const; + /** + * Derive a key from a passphrase, running until msec time has elapsed. + * + * @param out buffer to store the derived key, must be of out_len bytes + * @param out_len the desired length of the key to produce + * @param passphrase the password to derive the key from + * @param salt a randomly chosen salt + * @param salt_len length of salt in bytes + * @param msec if iterations is zero, then instead the PBKDF is + * run until msec milliseconds has passed. + * @param iterations set to the number iterations executed + */ void pbkdf_timed(byte out[], size_t out_len, const std::string& passphrase, const byte salt[], size_t salt_len, std::chrono::milliseconds msec, size_t& iterations) const; + /** + * Derive a key from a passphrase for a number of iterations. + * + * @param out_len the desired length of the key to produce + * @param passphrase the password to derive the key from + * @param salt a randomly chosen salt + * @param salt_len length of salt in bytes + * @param iterations the number of iterations to use (use 10K or more) + * @return the derived key + */ secure_vector<byte> pbkdf_iterations(size_t out_len, const std::string& passphrase, const byte salt[], size_t salt_len, size_t iterations) const; + /** + * Derive a key from a passphrase, running until msec time has elapsed. + * + * @param out_len the desired length of the key to produce + * @param passphrase the password to derive the key from + * @param salt a randomly chosen salt + * @param salt_len length of salt in bytes + * @param msec if iterations is zero, then instead the PBKDF is + * run until msec milliseconds has passed. + * @param iterations set to the number iterations executed + * @return the derived key + */ secure_vector<byte> pbkdf_timed(size_t out_len, const std::string& passphrase, const byte salt[], size_t salt_len, @@ -164,6 +214,7 @@ class BOTAN_DLL PBKDF /** * Password based key derivation function factory method * @param algo_spec the name of the desired PBKDF algorithm +* @param provider the provider to use * @return pointer to newly allocated object of that type */ inline PBKDF* get_pbkdf(const std::string& algo_spec, diff --git a/src/lib/pk_pad/eme_oaep/oaep.h b/src/lib/pk_pad/eme_oaep/oaep.h index 8b21ea81d..2a0f0f28c 100644 --- a/src/lib/pk_pad/eme_oaep/oaep.h +++ b/src/lib/pk_pad/eme_oaep/oaep.h @@ -24,7 +24,7 @@ class BOTAN_DLL OAEP final : public EME static OAEP* make(const Spec& spec); /** - * @param hash object to use for hashing (takes ownership) + * @param hash function to use for hashing (takes ownership) * @param P an optional label. Normally empty. */ OAEP(HashFunction* hash, const std::string& P = ""); diff --git a/src/lib/pk_pad/emsa.h b/src/lib/pk_pad/emsa.h index f4697d100..8e8720a66 100644 --- a/src/lib/pk_pad/emsa.h +++ b/src/lib/pk_pad/emsa.h @@ -60,6 +60,9 @@ class BOTAN_DLL EMSA virtual ~EMSA(); + /** + * @return a new object representing the same encoding method as *this + */ virtual EMSA* clone() = 0; }; diff --git a/src/lib/pk_pad/emsa_pkcs1/emsa_pkcs1.h b/src/lib/pk_pad/emsa_pkcs1/emsa_pkcs1.h index 0773ed2c4..917f03ac8 100644 --- a/src/lib/pk_pad/emsa_pkcs1/emsa_pkcs1.h +++ b/src/lib/pk_pad/emsa_pkcs1/emsa_pkcs1.h @@ -24,7 +24,7 @@ class BOTAN_DLL EMSA_PKCS1v15 final : public EMSA static EMSA* make(const EMSA::Spec& spec); /** - * @param hash the hash object to use + * @param hash the hash function to use */ explicit EMSA_PKCS1v15(HashFunction* hash); diff --git a/src/lib/pk_pad/emsa_pssr/pssr.h b/src/lib/pk_pad/emsa_pssr/pssr.h index 9b39417a5..fa8687fee 100644 --- a/src/lib/pk_pad/emsa_pssr/pssr.h +++ b/src/lib/pk_pad/emsa_pssr/pssr.h @@ -21,12 +21,12 @@ class BOTAN_DLL PSSR final : public EMSA public: /** - * @param hash the hash object to use + * @param hash the hash function to use */ explicit PSSR(HashFunction* hash); /** - * @param hash the hash object to use + * @param hash the hash function to use * @param salt_size the size of the salt to use in bytes */ PSSR(HashFunction* hash, size_t salt_size); diff --git a/src/lib/pk_pad/emsa_x931/emsa_x931.h b/src/lib/pk_pad/emsa_x931/emsa_x931.h index 56754d3b1..fe5866002 100644 --- a/src/lib/pk_pad/emsa_x931/emsa_x931.h +++ b/src/lib/pk_pad/emsa_x931/emsa_x931.h @@ -22,7 +22,7 @@ class BOTAN_DLL EMSA_X931 final : public EMSA { public: /** - * @param hash the hash object to use + * @param hash the hash function to use */ explicit EMSA_X931(HashFunction* hash); diff --git a/src/lib/pk_pad/mgf1/mgf1.h b/src/lib/pk_pad/mgf1/mgf1.h index bddb8bba8..034b0328e 100644 --- a/src/lib/pk_pad/mgf1/mgf1.h +++ b/src/lib/pk_pad/mgf1/mgf1.h @@ -14,6 +14,11 @@ namespace Botan { /** * MGF1 from PKCS #1 v2.0 +* @param hash hash function to use +* @param in input buffer +* @param in_len size of the input buffer in bytes +* @param out output buffer +* @param out_len size of the output buffer in bytes */ void BOTAN_DLL mgf1_mask(HashFunction& hash, const byte in[], size_t in_len, diff --git a/src/lib/prov/pkcs11/p11.h b/src/lib/prov/pkcs11/p11.h index c18c07d59..cacf613a4 100644 --- a/src/lib/prov/pkcs11/p11.h +++ b/src/lib/prov/pkcs11/p11.h @@ -1325,7 +1325,7 @@ class BOTAN_DLL LowLevel /** * C_GetSessionInfo obtains information about the session. * @param session the session's handle - * @param info receives session info + * @param info_ptr receives session info * @param return_value default value (`ThrowException`): throw exception on error. * if a non-NULL pointer is passed: return_value receives the return value of the PKCS#11 function and no exception is thrown. * At least the following PKCS#11 return values may be returned: @@ -1639,7 +1639,7 @@ class BOTAN_DLL LowLevel * C_SetAttributeValue modifies the value of one or more object attributes. * @param session the session's handle * @param object the object's handle - * @param attributes specifies attrs and values + * @param attribute_values specifies attrs and values * @param return_value default value (`ThrowException`): throw exception on error. * if a non-NULL pointer is passed: return_value receives the return value of the PKCS#11 function and no exception is thrown. * At least the following PKCS#11 return values may be returned: @@ -1692,9 +1692,9 @@ class BOTAN_DLL LowLevel /** * C_FindObjects continues a search for token and session objects that match a template, obtaining additional object handles. * @param session session's handle - * @param object gets obj. handles + * @param object_ptr gets obj. handles * @param max_object_count max handles to get - * @param object_count actual # returned + * @param object_count_ptr actual # returned * @param return_value default value (`ThrowException`): throw exception on error. * if a non-NULL pointer is passed: return_value receives the return value of the PKCS#11 function and no exception is thrown. * At least the following PKCS#11 return values may be returned: @@ -1753,9 +1753,9 @@ class BOTAN_DLL LowLevel * C_Encrypt encrypts single-part data. * @param session session's handle * @param data_ptr the plaintext data - * @param encrypted_data_len_ptr bytes of plaintext + * @param data_len size of plaintext data in bytes * @param encrypted_data gets ciphertext - * @param encrypted_data_len gets c-text size + * @param encrypted_data_len_ptr gets c-text size * @param return_value default value (`ThrowException`): throw exception on error. * if a non-NULL pointer is passed: return_value receives the return value of the PKCS#11 function and no exception is thrown. * At least the following PKCS#11 return values may be returned: diff --git a/src/lib/prov/pkcs11/p11_ecc_key.h b/src/lib/prov/pkcs11/p11_ecc_key.h index 3d10ae85e..8b2ede566 100644 --- a/src/lib/prov/pkcs11/p11_ecc_key.h +++ b/src/lib/prov/pkcs11/p11_ecc_key.h @@ -181,12 +181,11 @@ class BOTAN_DLL PKCS11_EC_PrivateKey : public virtual Private_Key, /** * Gets the public_point - * @note: the public key must be set using `set_public_point` - * because it is not possible to infer the public key from a PKCS#11 EC private key + * @note the public key must be set using `set_public_point` + * because it is not possible to infer the public key from a PKCS#11 EC private key * @return the public point of the private key * @throws Exception if the public point was not set using set_public_point() */ - const PointGFp& public_point() const { if(m_public_key.is_zero()) diff --git a/src/lib/prov/pkcs11/p11_mechanism.h b/src/lib/prov/pkcs11/p11_mechanism.h index 0f7b6f07c..dde5e5b07 100644 --- a/src/lib/prov/pkcs11/p11_mechanism.h +++ b/src/lib/prov/pkcs11/p11_mechanism.h @@ -21,7 +21,7 @@ namespace PKCS11 { /** * Simple class to build and hold the data for a CK_MECHANISM struct * for RSA (encryption/decryption, signature/verification) -* and EC (ecdsa signature/verification, ecdh key derivation) +* and EC (ECDSA signature/verification, ECDH key derivation). */ class MechanismWrapper final { @@ -58,14 +58,22 @@ class MechanismWrapper final */ static MechanismWrapper create_ecdh_mechanism(const std::string& params); - /// Sets the salt for the ECDH mechanism parameters + /** + * Sets the salt for the ECDH mechanism parameters. + * @param salt the salt + * @param salt_len size of the salt in bytes + */ inline void set_ecdh_salt(const byte salt[], size_t salt_len) { m_parameters->ecdh_params.pSharedData = const_cast<byte*>(salt); m_parameters->ecdh_params.ulSharedDataLen = salt_len; } - /// Sets the public key of the other party for the ECDH mechanism parameters + /** + * Sets the public key of the other party for the ECDH mechanism parameters. + * @param other_key key of the other party + * @param other_key_len size of the key of the other party in bytes + */ inline void set_ecdh_other_key(const byte other_key[], size_t other_key_len) { m_parameters->ecdh_params.pPublicData = const_cast<byte*>(other_key); diff --git a/src/lib/prov/pkcs11/p11_object.h b/src/lib/prov/pkcs11/p11_object.h index 4a6a54b20..75b178c62 100644 --- a/src/lib/prov/pkcs11/p11_object.h +++ b/src/lib/prov/pkcs11/p11_object.h @@ -52,6 +52,7 @@ class BOTAN_DLL AttributeContainer return m_attributes; } + /// @return raw attribute data inline Attribute* data() const { return const_cast< Attribute* >(m_attributes.data()); @@ -63,26 +64,50 @@ class BOTAN_DLL AttributeContainer return m_attributes.size(); } - /// Add a class attribute (CKA_CLASS / AttributeType::Class) + /** + * Add a class attribute (CKA_CLASS / AttributeType::Class). + * @param object_class class attribute to add + */ void add_class(ObjectClass object_class); - /// Add a string attribute (e.g. CKA_LABEL / AttributeType::Label) + /** + * Add a string attribute (e.g. CKA_LABEL / AttributeType::Label). + * @param attribute attribute type + * @param value string value to add + */ void add_string(AttributeType attribute, const std::string& value); - /// Add a binary attribute (e.g. CKA_ID / AttributeType::Id) + /** + * Add a binary attribute (e.g. CKA_ID / AttributeType::Id). + * @param attribute attribute type + * @param value binary attribute value to add + * @param length size of the binary attribute value in bytes + */ void add_binary(AttributeType attribute, const byte* value, size_t length); - /// Add a binary attribute (e.g. CKA_ID / AttributeType::Id) + /** + * Add a binary attribute (e.g. CKA_ID / AttributeType::Id). + * @param attribute attribute type + * @param binary binary attribute value to add + */ template<typename TAlloc> void add_binary(AttributeType attribute, const std::vector<byte, TAlloc>& binary) { add_binary(attribute, binary.data(), binary.size()); } - /// Add a bool attribute (e.g. CKA_SENSITIVE / AttributeType::Sensitive) + /** + * Add a bool attribute (e.g. CKA_SENSITIVE / AttributeType::Sensitive). + * @param attribute attribute type + * @param value boolean value to add + */ void add_bool(AttributeType attribute, bool value); - /// Add a numeric attribute (e.g. CKA_MODULUS_BITS / AttributeType::ModulusBits) + /** + * Add a numeric attribute (e.g. CKA_MODULUS_BITS / AttributeType::ModulusBits). + * @param attribute attribute type + * @param value numeric value to add + */ template<typename T> void add_numeric(AttributeType attribute, T value) { @@ -92,7 +117,7 @@ class BOTAN_DLL AttributeContainer } protected: - /// Add a attribute with the given value and size to the attribute collection `m_attributes` + /// Add an attribute with the given value and size to the attribute collection `m_attributes` void add_attribute(AttributeType attribute, const byte* value, uint32_t size); private: @@ -610,6 +635,9 @@ class BOTAN_DLL DomainParameterProperties : public StorageObjectProperties const KeyType m_key_type; }; +/** +* Represents a PKCS#11 object. +*/ class BOTAN_DLL Object { public: diff --git a/src/lib/pubkey/blinding.h b/src/lib/pubkey/blinding.h index a6b266807..bc05d97e7 100644 --- a/src/lib/pubkey/blinding.h +++ b/src/lib/pubkey/blinding.h @@ -17,15 +17,38 @@ namespace Botan { class RandomNumberGenerator; /** -* Blinding Function Object +* Blinding Function Object. */ class BOTAN_DLL Blinder { public: + /** + * Blind a value. + * The blinding nonce k is freshly generated after + * BOTAN_BLINDING_REINIT_INTERVAL calls to blind(). + * BOTAN_BLINDING_REINIT_INTERVAL = 0 means a fresh + * nonce is only generated once. On every other call, + * an updated nonce is used for blinding: k' = k*k mod n. + * @param x value to blind + * @return blinded value + */ BigInt blind(const BigInt& x) const; + /** + * Unblind a value. + * @param x value to unblind + * @return unblinded value + */ BigInt unblind(const BigInt& x) const; + /** + * @param modulus the modulus + * @param rng the RNG to use for generating the nonce + * @param fwd_func a function that calculates the modular + * exponentiation of the public exponent and the given value (the nonce) + * @param inv_func a function that calculates the modular inverse + * of the given value (the nonce) + */ Blinder(const BigInt& modulus, RandomNumberGenerator& rng, std::function<BigInt (const BigInt&)> fwd_func, diff --git a/src/lib/pubkey/curve25519/curve25519.h b/src/lib/pubkey/curve25519/curve25519.h index fe39d9dd6..476db80d1 100644 --- a/src/lib/pubkey/curve25519/curve25519.h +++ b/src/lib/pubkey/curve25519/curve25519.h @@ -29,9 +29,18 @@ class BOTAN_DLL Curve25519_PublicKey : public virtual Public_Key std::vector<byte> public_value() const { return unlock(m_public); } + /** + * Create a Curve25519 Public Key. + * @param alg_id the X.509 algorithm identifier + * @param key_bits X.509 subject public key info structure + */ Curve25519_PublicKey(const AlgorithmIdentifier& alg_id, const secure_vector<byte>& key_bits); + /** + * Create a Curve25519 Public Key. + * @param pub DER encoded public key bits + */ explicit Curve25519_PublicKey(const secure_vector<byte>& pub) : m_public(pub) {} protected: @@ -44,12 +53,26 @@ class BOTAN_DLL Curve25519_PrivateKey : public Curve25519_PublicKey, public virtual PK_Key_Agreement_Key { public: + /** + * Construct a private key from the specified parameters. + * @param alg_id the X.509 algorithm identifier + * @param key_bits PKCS #8 structure + * @param rng the RNG to use + */ Curve25519_PrivateKey(const AlgorithmIdentifier& alg_id, const secure_vector<byte>& key_bits, RandomNumberGenerator& rng); + /** + * Generate a private key. + * @param rng the RNG to use + */ explicit Curve25519_PrivateKey(RandomNumberGenerator& rng); + /** + * Construct a private key from the specified parameters. + * @param secret_key DER encoded private key bits + */ explicit Curve25519_PrivateKey(const secure_vector<byte>& secret_key); std::vector<byte> public_value() const override { return Curve25519_PublicKey::public_value(); } diff --git a/src/lib/pubkey/dh/dh.h b/src/lib/pubkey/dh/dh.h index d15bc5eb3..e46a35dff 100644 --- a/src/lib/pubkey/dh/dh.h +++ b/src/lib/pubkey/dh/dh.h @@ -25,6 +25,11 @@ class BOTAN_DLL DH_PublicKey : public virtual DL_Scheme_PublicKey DL_Group::Format group_format() const override { return DL_Group::ANSI_X9_42; } + /** + * Create a public key. + * @param alg_id the X.509 algorithm identifier + * @param key_bits X.509 subject public key info structure + */ DH_PublicKey(const AlgorithmIdentifier& alg_id, const secure_vector<byte>& key_bits) : DL_Scheme_PublicKey(alg_id, key_bits, DL_Group::ANSI_X9_42) {} @@ -50,9 +55,9 @@ class BOTAN_DLL DH_PrivateKey : public DH_PublicKey, std::vector<byte> public_value() const override; /** - * Load a DH private key - * @param alg_id the algorithm id - * @param key_bits the subject public key + * Load a private key. + * @param alg_id the X.509 algorithm identifier + * @param key_bits PKCS #8 structure * @param rng a random number generator */ DH_PrivateKey(const AlgorithmIdentifier& alg_id, @@ -60,7 +65,7 @@ class BOTAN_DLL DH_PrivateKey : public DH_PublicKey, RandomNumberGenerator& rng); /** - * Construct a private key with predetermined value. + * Create a private key. * @param rng random number generator to use * @param grp the group to be used in the key * @param x the key's secret value (or if zero, generate a new key) diff --git a/src/lib/pubkey/dl_algo/dl_algo.h b/src/lib/pubkey/dl_algo/dl_algo.h index 705cce8b3..78816935e 100644 --- a/src/lib/pubkey/dl_algo/dl_algo.h +++ b/src/lib/pubkey/dl_algo/dl_algo.h @@ -62,6 +62,12 @@ class BOTAN_DLL DL_Scheme_PublicKey : public virtual Public_Key size_t estimated_strength() const override; + /** + * Create a public key. + * @param alg_id the X.509 algorithm identifier + * @param key_bits X.509 subject public key info structure + * @param group_format the underlying groups encoding format + */ DL_Scheme_PublicKey(const AlgorithmIdentifier& alg_id, const secure_vector<byte>& key_bits, DL_Group::Format group_format); @@ -97,6 +103,12 @@ class BOTAN_DLL DL_Scheme_PrivateKey : public virtual DL_Scheme_PublicKey, secure_vector<byte> pkcs8_private_key() const override; + /** + * Create a private key. + * @param alg_id the X.509 algorithm identifier + * @param key_bits DER encoded private key bits + * @param group_format the underlying groups encoding format + */ DL_Scheme_PrivateKey(const AlgorithmIdentifier& alg_id, const secure_vector<byte>& key_bits, DL_Group::Format group_format); diff --git a/src/lib/pubkey/dlies/dlies.h b/src/lib/pubkey/dlies/dlies.h index f6bf9c6dd..6e56c3da5 100644 --- a/src/lib/pubkey/dlies/dlies.h +++ b/src/lib/pubkey/dlies/dlies.h @@ -27,6 +27,7 @@ class BOTAN_DLL DLIES_Encryptor : public PK_Encryptor * Stream mode: use KDF to provide a stream of bytes to xor with the message * * @param own_priv_key own (ephemeral) DH private key + * @param rng the RNG to use * @param kdf the KDF that should be used * @param mac the MAC function that should be used * @param mac_key_len key length of the MAC function. Default = 20 bytes @@ -43,6 +44,7 @@ class BOTAN_DLL DLIES_Encryptor : public PK_Encryptor * Block cipher mode * * @param own_priv_key own (ephemeral) DH private key + * @param rng the RNG to use * @param kdf the KDF that should be used * @param cipher the block cipher that should be used * @param cipher_key_len the key length of the block cipher @@ -98,6 +100,7 @@ class BOTAN_DLL DLIES_Decryptor : public PK_Decryptor * Stream mode: use KDF to provide a stream of bytes to xor with the message * * @param own_priv_key own (ephemeral) DH private key + * @param rng the RNG to use * @param kdf the KDF that should be used * @param mac the MAC function that should be used * @param mac_key_len key length of the MAC function. Default = 20 bytes @@ -114,6 +117,7 @@ class BOTAN_DLL DLIES_Decryptor : public PK_Decryptor * Block cipher mode * * @param own_priv_key own (ephemeral) DH private key + * @param rng the RNG to use * @param kdf the KDF that should be used * @param cipher the block cipher that should be used * @param cipher_key_len the key length of the block cipher diff --git a/src/lib/pubkey/dsa/dsa.h b/src/lib/pubkey/dsa/dsa.h index 57c7b7c5c..5ca7b8698 100644 --- a/src/lib/pubkey/dsa/dsa.h +++ b/src/lib/pubkey/dsa/dsa.h @@ -25,12 +25,22 @@ class BOTAN_DLL DSA_PublicKey : public virtual DL_Scheme_PublicKey size_t message_part_size() const override { return group_q().bytes(); } size_t max_input_bits() const override { return group_q().bits(); } + /** + * Load a public key. + * @param alg_id the X.509 algorithm identifier + * @param key_bits DER encoded public key bits + */ DSA_PublicKey(const AlgorithmIdentifier& alg_id, const secure_vector<byte>& key_bits) : DL_Scheme_PublicKey(alg_id, key_bits, DL_Group::ANSI_X9_57) { } + /** + * Create a public key. + * @param group the underlying DL group + * @param y the public value y = g^x mod p + */ DSA_PublicKey(const DL_Group& group, const BigInt& y); std::unique_ptr<PK_Ops::Verification> @@ -47,10 +57,22 @@ class BOTAN_DLL DSA_PrivateKey : public DSA_PublicKey, public virtual DL_Scheme_PrivateKey { public: + /** + * Load a private key. + * @param alg_id the X.509 algorithm identifier + * @param key_bits PKCS#8 structure + * @param rng the RNG to use + */ DSA_PrivateKey(const AlgorithmIdentifier& alg_id, const secure_vector<byte>& key_bits, RandomNumberGenerator& rng); + /** + * Create a private key. + * @param rng the RNG to use + * @param group the underlying DL group + * @param private_key the private key (if zero, a new random key is generated) + */ DSA_PrivateKey(RandomNumberGenerator& rng, const DL_Group& group, const BigInt& private_key = 0); diff --git a/src/lib/pubkey/ecc_key/ecc_key.h b/src/lib/pubkey/ecc_key/ecc_key.h index a8e77b895..ec6806931 100644 --- a/src/lib/pubkey/ecc_key/ecc_key.h +++ b/src/lib/pubkey/ecc_key/ecc_key.h @@ -29,9 +29,19 @@ namespace Botan { class BOTAN_DLL EC_PublicKey : public virtual Public_Key { public: + /** + * Create a public key. + * @param dom_par EC domain parameters + * @param pub_point public point on the curve + */ EC_PublicKey(const EC_Group& dom_par, const PointGFp& pub_point); + /** + * Load a public key. + * @param alg_id the X.509 algorithm identifier + * @param key_bits PKCS #8 structure + */ EC_PublicKey(const AlgorithmIdentifier& alg_id, const secure_vector<byte>& key_bits); diff --git a/src/lib/pubkey/ecdh/ecdh.h b/src/lib/pubkey/ecdh/ecdh.h index 5b6ec7261..132a3d47d 100644 --- a/src/lib/pubkey/ecdh/ecdh.h +++ b/src/lib/pubkey/ecdh/ecdh.h @@ -20,7 +20,11 @@ namespace Botan { class BOTAN_DLL ECDH_PublicKey : public virtual EC_PublicKey { public: - + /** + * Create an ECDH public key. + * @param alg_id algorithm identifier + * @param key_bits DER encoded public key bits + */ ECDH_PublicKey(const AlgorithmIdentifier& alg_id, const secure_vector<byte>& key_bits) : EC_PublicKey(alg_id, key_bits) {} @@ -74,6 +78,11 @@ class BOTAN_DLL ECDH_PrivateKey : public ECDH_PublicKey, { public: + /** + * Create an ECDH public key. + * @param alg_id the X.509 algorithm identifier + * @param key_bits X.509 subject public key info structure + */ ECDH_PrivateKey(const AlgorithmIdentifier& alg_id, const secure_vector<byte>& key_bits) : EC_PrivateKey(alg_id, key_bits) {} diff --git a/src/lib/pubkey/ecdsa/ecdsa.h b/src/lib/pubkey/ecdsa/ecdsa.h index d9dcacd06..9fad4e921 100644 --- a/src/lib/pubkey/ecdsa/ecdsa.h +++ b/src/lib/pubkey/ecdsa/ecdsa.h @@ -22,7 +22,7 @@ class BOTAN_DLL ECDSA_PublicKey : public virtual EC_PublicKey public: /** - * Construct a public key from a given public point. + * Create a public key from a given public point. * @param dom_par the domain parameters associated with this key * @param public_point the public point defining this key */ @@ -30,6 +30,11 @@ class BOTAN_DLL ECDSA_PublicKey : public virtual EC_PublicKey const PointGFp& public_point) : EC_PublicKey(dom_par, public_point) {} + /** + * Load a public key. + * @param alg_id the X.509 algorithm identifier + * @param key_bits X.509 subject public key info structure + */ ECDSA_PublicKey(const AlgorithmIdentifier& alg_id, const secure_vector<byte>& key_bits) : EC_PublicKey(alg_id, key_bits) {} @@ -78,7 +83,7 @@ class BOTAN_DLL ECDSA_PrivateKey : public ECDSA_PublicKey, EC_PrivateKey(alg_id, key_bits) {} /** - * Generate a new private key + * Create a private key. * @param rng a random number generator * @param domain parameters to used for this key * @param x the private key (if zero, generate a new random key) diff --git a/src/lib/pubkey/ecgdsa/ecgdsa.h b/src/lib/pubkey/ecgdsa/ecgdsa.h index 203e8d0a8..f90f7bfd4 100644 --- a/src/lib/pubkey/ecgdsa/ecgdsa.h +++ b/src/lib/pubkey/ecgdsa/ecgdsa.h @@ -28,6 +28,11 @@ class BOTAN_DLL ECGDSA_PublicKey : public virtual EC_PublicKey const PointGFp& public_point) : EC_PublicKey(dom_par, public_point) {} + /** + * Load a public key. + * @param alg_id the X.509 algorithm identifier + * @param key_bits X.509 subject public key info structure + */ ECGDSA_PublicKey(const AlgorithmIdentifier& alg_id, const secure_vector<byte>& key_bits) : EC_PublicKey(alg_id, key_bits) {} @@ -67,7 +72,7 @@ class BOTAN_DLL ECGDSA_PrivateKey : public ECGDSA_PublicKey, public: /** - * Load a private key + * Load a private key. * @param alg_id the X.509 algorithm identifier * @param key_bits PKCS #8 structure */ @@ -76,7 +81,7 @@ class BOTAN_DLL ECGDSA_PrivateKey : public ECGDSA_PublicKey, EC_PrivateKey(alg_id, key_bits, true) {} /** - * Generate a new private key + * Generate a new private key. * @param rng a random number generator * @param domain parameters to used for this key * @param x the private key (if zero, generate a new random key) diff --git a/src/lib/pubkey/ecies/ecies.h b/src/lib/pubkey/ecies/ecies.h index 6b9eba31d..94b0bd576 100644 --- a/src/lib/pubkey/ecies/ecies.h +++ b/src/lib/pubkey/ecies/ecies.h @@ -53,7 +53,7 @@ inline ECIES_Flags operator &(ECIES_Flags a, ECIES_Flags b) } /** -* Parameters for ecies secret derivation +* Parameters for ECIES secret derivation */ class BOTAN_DLL ECIES_KA_Params { @@ -183,6 +183,7 @@ class BOTAN_DLL ECIES_KA_Operation * @param ecies_params settings for ecies * @param for_encryption disable cofactor mode if the secret will be used for encryption * (according to ISO 18033 cofactor mode is only used during decryption) + * @param rng the RNG to use */ ECIES_KA_Operation(const PK_Key_Agreement_Key& private_key, const ECIES_KA_Params& ecies_params, @@ -212,6 +213,7 @@ class BOTAN_DLL ECIES_Encryptor : public PK_Encryptor /** * @param private_key the (ephemeral) private key which is used for the key agreement * @param ecies_params settings for ecies + * @param rng random generator to use */ ECIES_Encryptor(const PK_Key_Agreement_Key& private_key, const ECIES_System_Params& ecies_params, @@ -268,6 +270,7 @@ class BOTAN_DLL ECIES_Decryptor : public PK_Decryptor /** * @param private_key the private key which is used for the key agreement * @param ecies_params settings for ecies + * @param rng the random generator to use */ ECIES_Decryptor(const PK_Key_Agreement_Key& private_key, const ECIES_System_Params& ecies_params, diff --git a/src/lib/pubkey/eckcdsa/eckcdsa.h b/src/lib/pubkey/eckcdsa/eckcdsa.h index 09ee34ed5..be5daf2da 100644 --- a/src/lib/pubkey/eckcdsa/eckcdsa.h +++ b/src/lib/pubkey/eckcdsa/eckcdsa.h @@ -28,6 +28,11 @@ class BOTAN_DLL ECKCDSA_PublicKey : public virtual EC_PublicKey const PointGFp& public_point) : EC_PublicKey(dom_par, public_point) {} + /** + * Load a public key. + * @param alg_id the X.509 algorithm identifier + * @param key_bits X.509 subject public key info structure + */ ECKCDSA_PublicKey(const AlgorithmIdentifier& alg_id, const secure_vector<byte>& key_bits) : EC_PublicKey(alg_id, key_bits) {} @@ -67,7 +72,7 @@ class BOTAN_DLL ECKCDSA_PrivateKey : public ECKCDSA_PublicKey, public: /** - * Load a private key + * Load a private key. * @param alg_id the X.509 algorithm identifier * @param key_bits PKCS #8 structure */ @@ -76,7 +81,7 @@ class BOTAN_DLL ECKCDSA_PrivateKey : public ECKCDSA_PublicKey, EC_PrivateKey(alg_id, key_bits, true) {} /** - * Generate a new private key + * Create a private key. * @param rng a random number generator * @param domain parameters to used for this key * @param x the private key (if zero, generate a new random key) diff --git a/src/lib/pubkey/elgamal/elgamal.h b/src/lib/pubkey/elgamal/elgamal.h index 8ca4facc2..102d5ad91 100644 --- a/src/lib/pubkey/elgamal/elgamal.h +++ b/src/lib/pubkey/elgamal/elgamal.h @@ -23,11 +23,21 @@ class BOTAN_DLL ElGamal_PublicKey : public virtual DL_Scheme_PublicKey size_t max_input_bits() const override { return (group_p().bits() - 1); } + /** + * Load a public key. + * @param alg_id the X.509 algorithm identifier + * @param key_bits X.509 subject public key info structure + */ ElGamal_PublicKey(const AlgorithmIdentifier& alg_id, const secure_vector<byte>& key_bits) : DL_Scheme_PublicKey(alg_id, key_bits, DL_Group::ANSI_X9_42) {} + /** + * Create a public key. + * @param group the underlying DL group + * @param y the public value y = g^x mod p + */ ElGamal_PublicKey(const DL_Group& group, const BigInt& y); std::unique_ptr<PK_Ops::Encryption> @@ -48,10 +58,22 @@ class BOTAN_DLL ElGamal_PrivateKey : public ElGamal_PublicKey, public: bool check_key(RandomNumberGenerator& rng, bool) const override; + /** + * Load a private key. + * @param alg_id the X.509 algorithm identifier + * @param key_bits PKCS #8 structure + * @param rng the RNG to use + */ ElGamal_PrivateKey(const AlgorithmIdentifier& alg_id, const secure_vector<byte>& key_bits, RandomNumberGenerator& rng); + /** + * Create a private key. + * @param rng random number generator to use + * @param group the group to be used in the key + * @param priv_key the key's secret value (or if zero, generate a new key) + */ ElGamal_PrivateKey(RandomNumberGenerator& rng, const DL_Group& group, const BigInt& priv_key = 0); diff --git a/src/lib/pubkey/gost_3410/gost_3410.h b/src/lib/pubkey/gost_3410/gost_3410.h index cca811896..1fe4435c4 100644 --- a/src/lib/pubkey/gost_3410/gost_3410.h +++ b/src/lib/pubkey/gost_3410/gost_3410.h @@ -31,7 +31,9 @@ class BOTAN_DLL GOST_3410_PublicKey : public virtual EC_PublicKey EC_PublicKey(dom_par, public_point) {} /** - * Construct from X.509 algorithm id and subject public key bits + * Load a public key. + * @param alg_id the X.509 algorithm identifier + * @param key_bits X.509 subject public key info structure */ GOST_3410_PublicKey(const AlgorithmIdentifier& alg_id, const secure_vector<byte>& key_bits); @@ -74,7 +76,11 @@ class BOTAN_DLL GOST_3410_PrivateKey : public GOST_3410_PublicKey, public EC_PrivateKey { public: - + /** + * Load a private key. + * @param alg_id the X.509 algorithm identifier + * @param key_bits PKCS #8 structure + */ GOST_3410_PrivateKey(const AlgorithmIdentifier& alg_id, const secure_vector<byte>& key_bits) : EC_PrivateKey(alg_id, key_bits) {} diff --git a/src/lib/pubkey/mce/gf2m_rootfind_dcmp.cpp b/src/lib/pubkey/mce/gf2m_rootfind_dcmp.cpp index acae036db..c9d82fdbf 100644 --- a/src/lib/pubkey/mce/gf2m_rootfind_dcmp.cpp +++ b/src/lib/pubkey/mce/gf2m_rootfind_dcmp.cpp @@ -86,14 +86,6 @@ u32bit brootf_decomp__calc_sum_limit(u32bit t) return result; } -} - -secure_vector<gf2m> find_roots_gf2m_decomp(const polyn_gf2m & polyn, u32bit code_length) - { - gf2m_decomp_rootfind_state state(polyn, code_length); - return state.find_roots(polyn); - } - gf2m_decomp_rootfind_state::gf2m_decomp_rootfind_state(const polyn_gf2m & polyn, u32bit the_code_length) : code_length(the_code_length), m_j(0), m_j_gray(0) { @@ -314,4 +306,12 @@ secure_vector<gf2m> gf2m_decomp_rootfind_state::find_roots(const polyn_gf2m & si return result; } +} // end anonymous namespace + +secure_vector<gf2m> find_roots_gf2m_decomp(const polyn_gf2m & polyn, u32bit code_length) + { + gf2m_decomp_rootfind_state state(polyn, code_length); + return state.find_roots(polyn); + } + } // end namespace Botan diff --git a/src/lib/pubkey/mce/goppa_code.cpp b/src/lib/pubkey/mce/goppa_code.cpp index 2657beee9..e866a1631 100644 --- a/src/lib/pubkey/mce/goppa_code.cpp +++ b/src/lib/pubkey/mce/goppa_code.cpp @@ -157,8 +157,8 @@ void mceliece_decrypt( } /** -* @param p_err_pos_len must point to the available length of err_pos on input, the -* function will set it to the actual number of errors returned in the err_pos +* @p p_err_pos_len must point to the available length of @p error_pos on input, the +* function will set it to the actual number of errors returned in the @p error_pos * array */ secure_vector<byte> mceliece_decrypt( secure_vector<gf2m> & error_pos, diff --git a/src/lib/pubkey/pk_keys.h b/src/lib/pubkey/pk_keys.h index 5521f5b2c..abba9062d 100644 --- a/src/lib/pubkey/pk_keys.h +++ b/src/lib/pubkey/pk_keys.h @@ -109,6 +109,8 @@ class BOTAN_DLL Public_Key * @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, @@ -124,6 +126,8 @@ class BOTAN_DLL Public_Key * @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, @@ -135,6 +139,8 @@ class BOTAN_DLL Public_Key * 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, @@ -182,6 +188,9 @@ class BOTAN_DLL Private_Key : public virtual Public_Key * @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, @@ -197,6 +206,8 @@ class BOTAN_DLL Private_Key : public virtual Public_Key * @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, @@ -212,6 +223,8 @@ class BOTAN_DLL Private_Key : public virtual Public_Key * @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, @@ -227,6 +240,8 @@ class BOTAN_DLL Private_Key : public virtual Public_Key * @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, diff --git a/src/lib/pubkey/pubkey.h b/src/lib/pubkey/pubkey.h index 94332c8f0..b9ad0672d 100644 --- a/src/lib/pubkey/pubkey.h +++ b/src/lib/pubkey/pubkey.h @@ -164,9 +164,11 @@ class BOTAN_DLL PK_Signer final /** * Construct a PK Signer. * @param key the key to use inside this signer + * @param rng the random generator to use * @param emsa the EMSA to use * An example would be "EMSA1(SHA-224)". * @param format the signature format to use + * @param provider the provider to use */ PK_Signer(const Private_Key& key, RandomNumberGenerator& rng, @@ -220,6 +222,12 @@ class BOTAN_DLL PK_Signer final RandomNumberGenerator& rng) { return sign_message(in.data(), in.size(), rng); } + /** + * Sign a message. + * @param in the message to sign + * @param rng the rng to use + * @return signature + */ std::vector<byte> sign_message(const secure_vector<byte>& in, RandomNumberGenerator& rng) { return sign_message(in.data(), in.size(), rng); } @@ -283,6 +291,7 @@ class BOTAN_DLL PK_Verifier final * @param pub_key the public key to verify against * @param emsa the EMSA to use (eg "EMSA3(SHA-1)") * @param format the signature format to use + * @param provider the provider to use */ PK_Verifier(const Public_Key& pub_key, const std::string& emsa, @@ -392,6 +401,7 @@ class BOTAN_DLL PK_Key_Agreement final /** * Construct a PK Key Agreement. * @param key the key to use + * @param rng the random generator to use * @param kdf name of the KDF to use (or 'Raw' for no KDF) * @param provider the algo provider to use (or empty for default) */ @@ -502,7 +512,9 @@ class BOTAN_DLL PK_Encryptor_EME final : public PK_Encryptor /** * Construct an instance. * @param key the key to use inside the encryptor + * @param rng the RNG to use * @param padding the message encoding scheme to use (eg "OAEP(SHA-256)") + * @param provider the provider to use */ PK_Encryptor_EME(const Public_Key& key, RandomNumberGenerator& rng, @@ -542,8 +554,9 @@ class BOTAN_DLL PK_Decryptor_EME final : public PK_Decryptor /** * Construct an instance. * @param key the key to use inside the decryptor + * @param rng the random generator to use * @param eme the EME to use - * @param provider + * @param provider the provider to use */ PK_Decryptor_EME(const Private_Key& key, RandomNumberGenerator& rng, @@ -575,9 +588,19 @@ class BOTAN_DLL PK_Decryptor_EME final : public PK_Decryptor std::unique_ptr<PK_Ops::Decryption> m_op; }; +/** +* Public Key Key Encapsulation Mechanism Encryption. +*/ class BOTAN_DLL PK_KEM_Encryptor final { public: + /** + * Construct an instance. + * @param key the key to use inside the encryptor + * @param rng the RNG to use + * @param kem_param additional KEM parameters + * @param provider the provider to use + */ PK_KEM_Encryptor(const Public_Key& key, RandomNumberGenerator& rng, const std::string& kem_param = "", @@ -596,6 +619,15 @@ class BOTAN_DLL PK_KEM_Encryptor final PK_KEM_Encryptor& operator=(const PK_KEM_Encryptor&) = delete; PK_KEM_Encryptor(const PK_KEM_Encryptor&) = delete; + /** + * Generate a shared key for data encryption. + * @param out_encapsulated_key the generated encapsulated key + * @param out_shared_key the generated shared key + * @param desired_shared_key_len desired size of the shared key in bytes + * @param rng the RNG to use + * @param salt a salt value used in the KDF + * @param salt_len size of the salt value in bytes + */ void encrypt(secure_vector<byte>& out_encapsulated_key, secure_vector<byte>& out_shared_key, size_t desired_shared_key_len, @@ -603,6 +635,14 @@ class BOTAN_DLL PK_KEM_Encryptor final const uint8_t salt[], size_t salt_len); + /** + * Generate a shared key for data encryption. + * @param out_encapsulated_key the generated encapsulated key + * @param out_shared_key the generated shared key + * @param desired_shared_key_len desired size of the shared key in bytes + * @param rng the RNG to use + * @param salt a salt value used in the KDF + */ template<typename Alloc> void encrypt(secure_vector<byte>& out_encapsulated_key, secure_vector<byte>& out_shared_key, @@ -617,6 +657,14 @@ class BOTAN_DLL PK_KEM_Encryptor final salt.data(), salt.size()); } + + /** + * Generate a shared key for data encryption. + * @param out_encapsulated_key the generated encapsulated key + * @param out_shared_key the generated shared key + * @param desired_shared_key_len desired size of the shared key in bytes + * @param rng the RNG to use + */ void encrypt(secure_vector<byte>& out_encapsulated_key, secure_vector<byte>& out_shared_key, size_t desired_shared_key_len, @@ -634,9 +682,19 @@ class BOTAN_DLL PK_KEM_Encryptor final std::unique_ptr<PK_Ops::KEM_Encryption> m_op; }; +/** +* Public Key Key Encapsulation Mechanism Decryption. +*/ class BOTAN_DLL PK_KEM_Decryptor final { public: + /** + * Construct an instance. + * @param key the key to use inside the decryptor + * @param rng the RNG to use + * @param kem_param additional KEM parameters + * @param provider the provider to use + */ PK_KEM_Decryptor(const Private_Key& key, RandomNumberGenerator& rng, const std::string& kem_param = "", @@ -655,12 +713,28 @@ class BOTAN_DLL PK_KEM_Decryptor final PK_KEM_Decryptor& operator=(const PK_KEM_Decryptor&) = delete; PK_KEM_Decryptor(const PK_KEM_Decryptor&) = delete; + /** + * Decrypts the shared key for data encryption. + * @param encap_key the encapsulated key + * @param encap_key_len size of the encapsulated key in bytes + * @param desired_shared_key_len desired size of the shared key in bytes + * @param salt a salt value used in the KDF + * @param salt_len size of the salt value in bytes + * @return the shared data encryption key + */ secure_vector<byte> decrypt(const byte encap_key[], size_t encap_key_len, size_t desired_shared_key_len, const uint8_t salt[], size_t salt_len); + /** + * Decrypts the shared key for data encryption. + * @param encap_key the encapsulated key + * @param encap_key_len size of the encapsulated key in bytes + * @param desired_shared_key_len desired size of the shared key in bytes + * @return the shared data encryption key + */ secure_vector<byte> decrypt(const byte encap_key[], size_t encap_key_len, size_t desired_shared_key_len) @@ -670,6 +744,13 @@ class BOTAN_DLL PK_KEM_Decryptor final nullptr, 0); } + /** + * Decrypts the shared key for data encryption. + * @param encap_key the encapsulated key + * @param desired_shared_key_len desired size of the shared key in bytes + * @param salt a salt value used in the KDF + * @return the shared data encryption key + */ template<typename Alloc1, typename Alloc2> secure_vector<byte> decrypt(const std::vector<byte, Alloc1>& encap_key, size_t desired_shared_key_len, diff --git a/src/lib/pubkey/rsa/rsa.h b/src/lib/pubkey/rsa/rsa.h index ddfd23b05..18faef652 100644 --- a/src/lib/pubkey/rsa/rsa.h +++ b/src/lib/pubkey/rsa/rsa.h @@ -19,11 +19,16 @@ namespace Botan { class BOTAN_DLL RSA_PublicKey : public virtual Public_Key { public: + /** + * Load a public key. + * @param alg_id the X.509 algorithm identifier + * @param key_bits X.509 subject public key info structure + */ RSA_PublicKey(const AlgorithmIdentifier& alg_id, const secure_vector<byte>& key_bits); /** - * Create a RSA_PublicKey + * Create a public key. * @arg n the modulus * @arg e the exponent */ @@ -78,6 +83,12 @@ class BOTAN_DLL RSA_PublicKey : public virtual Public_Key class BOTAN_DLL RSA_PrivateKey : public Private_Key, public RSA_PublicKey { public: + /** + * Load a private key. + * @param alg_id the X.509 algorithm identifier + * @param key_bits PKCS #8 structure + * @param rng a random number generator + */ RSA_PrivateKey(const AlgorithmIdentifier& alg_id, const secure_vector<byte>& key_bits, RandomNumberGenerator& rng); diff --git a/src/lib/rng/auto_rng/auto_rng.h b/src/lib/rng/auto_rng/auto_rng.h index 6ef1aa291..9ae9b9c38 100644 --- a/src/lib/rng/auto_rng/auto_rng.h +++ b/src/lib/rng/auto_rng/auto_rng.h @@ -27,6 +27,9 @@ class BOTAN_DLL AutoSeeded_RNG final : public RandomNumberGenerator bool is_seeded() const override; + /** + * Mark state as requiring a reseed on next use + */ void force_reseed(); size_t reseed(Entropy_Sources& srcs, @@ -40,18 +43,44 @@ class BOTAN_DLL AutoSeeded_RNG final : public RandomNumberGenerator void clear() override; /** - * If no RNG or entropy sources are provided to AutoSeeded_RNG, it uses the system RNG - * (if available) or else a default group of entropy sources (all other systems) to - * gather seed material. + * Uses the system RNG (if available) or else a default group of + * entropy sources (all other systems) to gather seed material. + * + * @param reseed_interval specifies a limit of how many times + * the RNG will be called before automatic reseeding is performed */ AutoSeeded_RNG(size_t reseed_interval = BOTAN_RNG_DEFAULT_RESEED_INTERVAL); + /** + * Uses the BOTAN_AUTO_RNG_DRBG RNG to gather seed material. + * + * @param underlying_rng is a reference to some RNG which will be used + * to perform the periodic reseeding + * @param reseed_interval specifies a limit of how many times + * the RNG will be called before automatic reseeding is performed + */ AutoSeeded_RNG(RandomNumberGenerator& underlying_rng, size_t reseed_interval = BOTAN_RNG_DEFAULT_RESEED_INTERVAL); + /** + * Uses the BOTAN_AUTO_RNG_DRBG RNG to gather seed material. + * + * @param entropy_sources will be polled to perform reseeding periodically + * @param reseed_interval specifies a limit of how many times + * the RNG will be called before automatic reseeding is performed + */ AutoSeeded_RNG(Entropy_Sources& entropy_sources, size_t reseed_interval = BOTAN_RNG_DEFAULT_RESEED_INTERVAL); + /** + * Uses the BOTAN_AUTO_RNG_DRBG RNG to gather seed material. + * + * @param underlying_rng is a reference to some RNG which will be used + * to perform the periodic reseeding + * @param entropy_sources will be polled to perform reseeding periodically + * @param reseed_interval specifies a limit of how many times + * the RNG will be called before automatic reseeding is performed + */ AutoSeeded_RNG(RandomNumberGenerator& underlying_rng, Entropy_Sources& entropy_sources, size_t reseed_interval = BOTAN_RNG_DEFAULT_RESEED_INTERVAL); diff --git a/src/lib/rng/hmac_drbg/hmac_drbg.h b/src/lib/rng/hmac_drbg/hmac_drbg.h index 4f96af816..11d355d70 100644 --- a/src/lib/rng/hmac_drbg/hmac_drbg.h +++ b/src/lib/rng/hmac_drbg/hmac_drbg.h @@ -36,10 +36,14 @@ class BOTAN_DLL HMAC_DRBG final : public Stateful_RNG /** * Initialize an HMAC_DRBG instance with the given MAC as PRF (normally HMAC) * + * Automatic reseeding from @p underlying_rng will take place after + * @p reseed_interval many requests or after a fork was detected. + * + * @param prf MAC to use as a PRF * @param underlying_rng is a reference to some RNG which will be used * to perform the periodic reseeding * @param reseed_interval specifies a limit of how many times - * the RNG will be called before automatic reseeding is performed. + * the RNG will be called before automatic reseeding is performed */ HMAC_DRBG(std::unique_ptr<MessageAuthenticationCode> prf, RandomNumberGenerator& underlying_rng, @@ -48,6 +52,10 @@ class BOTAN_DLL HMAC_DRBG final : public Stateful_RNG /** * Initialize an HMAC_DRBG instance with the given MAC as PRF (normally HMAC) * + * Automatic reseeding from @p entropy_sources will take place after + * @p reseed_interval many requests or after a fork was detected. + * + * @param prf MAC to use as a PRF * @param entropy_sources will be polled to perform reseeding periodically * @param reseed_interval specifies a limit of how many times * the RNG will be called before automatic reseeding is performed. @@ -59,6 +67,11 @@ class BOTAN_DLL HMAC_DRBG final : public Stateful_RNG /** * Initialize an HMAC_DRBG instance with the given MAC as PRF (normally HMAC) * + * Automatic reseeding from @p underlying_rng and @p entropy_sources + * will take place after @p reseed_interval many requests or after + * a fork was detected. + * + * @param prf MAC to use as a PRF * @param underlying_rng is a reference to some RNG which will be used * to perform the periodic reseeding * @param entropy_sources will be polled to perform reseeding periodically diff --git a/src/lib/rng/hmac_rng/hmac_rng.h b/src/lib/rng/hmac_rng/hmac_rng.h index d6e9b4896..e4cb4a2bf 100644 --- a/src/lib/rng/hmac_rng/hmac_rng.h +++ b/src/lib/rng/hmac_rng/hmac_rng.h @@ -28,6 +28,7 @@ class BOTAN_DLL HMAC_RNG final : public Stateful_RNG public: /** * Initialize an HMAC_RNG instance with the given MAC as PRF (normally HMAC) + * @param prf MAC to use as a PRF * @param underlying_rng is a reference to some RNG which will be used * to perform the periodic reseeding. * @param entropy_sources will be polled to perform reseeding periodically @@ -41,6 +42,7 @@ class BOTAN_DLL HMAC_RNG final : public Stateful_RNG /** * Initialize an HMAC_RNG instance with the given MAC as PRF (normally HMAC) + * @param prf MAC to use as a PRF * @param underlying_rng is a reference to some RNG which will be used * to perform the periodic reseeding. * @param reseed_interval specifies a limit of how many times @@ -52,6 +54,7 @@ class BOTAN_DLL HMAC_RNG final : public Stateful_RNG /* * Initialize an HMAC_RNG instance with the given MAC as PRF (normally HMAC) + * @param prf MAC to use as a PRF * @param entropy_sources will be polled to perform reseeding periodically * @param reseed_interval specifies a limit of how many times * the RNG will be called before automatic reseeding is performed. @@ -63,6 +66,7 @@ class BOTAN_DLL HMAC_RNG final : public Stateful_RNG /** * Initialize an HMAC_RNG instance with the given MAC as PRF (normally HMAC) * Automatic reseeding is disabled completely. + * @param prf MAC to use as a PRF */ HMAC_RNG(std::unique_ptr<MessageAuthenticationCode> prf); diff --git a/src/lib/rng/rdrand_rng/rdrand_rng.h b/src/lib/rng/rdrand_rng/rdrand_rng.h index fcd54035b..94363b89c 100644 --- a/src/lib/rng/rdrand_rng/rdrand_rng.h +++ b/src/lib/rng/rdrand_rng/rdrand_rng.h @@ -45,6 +45,9 @@ class BOTAN_DLL RDRAND_RNG : public Hardware_RNG void add_entropy(const uint8_t[], size_t) override { /* no op */ } + /* + * No way to reseed RDRAND generator, so reseed is ignored + */ size_t reseed(Entropy_Sources&, size_t, std::chrono::milliseconds) override { return 0; /* no op */ } diff --git a/src/lib/rng/rng.h b/src/lib/rng/rng.h index e3640a32f..879c1acb7 100644 --- a/src/lib/rng/rng.h +++ b/src/lib/rng/rng.h @@ -38,7 +38,7 @@ class BOTAN_DLL RandomNumberGenerator /** * Randomize a byte array. * @param output the byte array to hold the random output. - * @param length the length of the byte array output. + * @param length the length of the byte array output in bytes. */ virtual void randomize(byte output[], size_t length) = 0; @@ -49,7 +49,7 @@ class BOTAN_DLL RandomNumberGenerator * A few RNG types do not accept any externally provided input, * in which case this function is a no-op. * - * @param inputs a byte array containg the entropy to be added + * @param input a byte array containg the entropy to be added * @param length the length of the byte array in */ virtual void add_entropy(const byte input[], size_t length) = 0; @@ -70,7 +70,12 @@ class BOTAN_DLL RandomNumberGenerator * Use this to further bind the outputs to your current * process/protocol state. For instance if generating a new key * for use in a session, include a session ID or other such - * value. See NIST SP 800-90 A, B, C series for more ideas. + * value. See NIST SP 800-90 A, B, C series for more ideas. + * + * @param output buffer to hold the random output + * @param output_len size of the output buffer in bytes + * @param input entropy buffer to incorporate + * @param input_len size of the input buffer in bytes */ virtual void randomize_with_input(byte output[], size_t output_len, const byte input[], size_t input_len); @@ -78,8 +83,8 @@ class BOTAN_DLL RandomNumberGenerator /** * This calls `randomize_with_input` using some timestamps as extra input. * - * For a stateful RNG using non-random but potentially unique data as the - * additional_input can help protect against problems with fork, VM state + * For a stateful RNG using non-random but potentially unique data the + * extra input can help protect against problems with fork, VM state * rollback, or other cases where somehow an RNG state is duplicated. If * both of the duplicated RNG states later incorporate a timestamp (and the * timestamps don't themselves repeat), their outputs will diverge. @@ -87,7 +92,7 @@ class BOTAN_DLL RandomNumberGenerator virtual void randomize_with_ts_input(byte output[], size_t output_len); /** - * Return the name of this RNG type + * @return the name of this RNG type */ virtual std::string name() const = 0; @@ -143,6 +148,9 @@ class BOTAN_DLL RandomNumberGenerator return b; } + /** + * @return a random byte that is not the zero byte + */ byte next_nonzero_byte() { byte b = this->next_byte(); diff --git a/src/lib/rng/stateful_rng/stateful_rng.h b/src/lib/rng/stateful_rng/stateful_rng.h index 11f0c7e3d..e2b45f8fa 100644 --- a/src/lib/rng/stateful_rng/stateful_rng.h +++ b/src/lib/rng/stateful_rng/stateful_rng.h @@ -25,6 +25,13 @@ namespace Botan { class BOTAN_DLL Stateful_RNG : public RandomNumberGenerator { public: + /** + * @param rng is a reference to some RNG which will be used + * to perform the periodic reseeding + * @param entropy_sources will be polled to perform reseeding periodically + * @param reseed_interval specifies a limit of how many times + * the RNG will be called before automatic reseeding is performed + */ Stateful_RNG(RandomNumberGenerator& rng, Entropy_Sources& entropy_sources, size_t reseed_interval) : @@ -33,11 +40,22 @@ class BOTAN_DLL Stateful_RNG : public RandomNumberGenerator m_reseed_interval(reseed_interval) {} + /** + * @param rng is a reference to some RNG which will be used + * to perform the periodic reseeding + * @param reseed_interval specifies a limit of how many times + * the RNG will be called before automatic reseeding is performed + */ Stateful_RNG(RandomNumberGenerator& rng, size_t reseed_interval) : m_underlying_rng(&rng), m_reseed_interval(reseed_interval) {} + /** + * @param entropy_sources will be polled to perform reseeding periodically + * @param reseed_interval specifies a limit of how many times + * the RNG will be called before automatic reseeding is performed + */ Stateful_RNG(Entropy_Sources& entropy_sources, size_t reseed_interval) : m_entropy_sources(&entropy_sources), m_reseed_interval(reseed_interval) @@ -81,7 +99,7 @@ class BOTAN_DLL Stateful_RNG : public RandomNumberGenerator std::chrono::milliseconds poll_timeout = BOTAN_RNG_RESEED_DEFAULT_TIMEOUT) override; /** - * Return intended security level of this DRBG + * @return intended security level of this DRBG */ virtual size_t security_level() const = 0; diff --git a/src/lib/rng/system_rng/system_rng.h b/src/lib/rng/system_rng/system_rng.h index 9cf31e78b..a31bb1dba 100644 --- a/src/lib/rng/system_rng/system_rng.h +++ b/src/lib/rng/system_rng/system_rng.h @@ -20,7 +20,7 @@ namespace Botan { BOTAN_DLL RandomNumberGenerator& system_rng(); /* -* Instantiatable reference to the system RNG. +* Instantiable reference to the system RNG. */ class BOTAN_DLL System_RNG final : public RandomNumberGenerator { diff --git a/src/lib/stream/chacha/chacha.h b/src/lib/stream/chacha/chacha.h index eafeac2fd..6b1c989e2 100644 --- a/src/lib/stream/chacha/chacha.h +++ b/src/lib/stream/chacha/chacha.h @@ -21,7 +21,8 @@ class BOTAN_DLL ChaCha final : public StreamCipher StreamCipher* clone() const override { return new ChaCha(m_rounds); } /** - * Currently only 8, 12 or 20 rounds are supported, all others + * @param rounds number of rounds + * @note Currently only 8, 12 or 20 rounds are supported, all others * will throw an exception */ ChaCha(size_t rounds = 20); diff --git a/src/lib/stream/ctr/ctr.h b/src/lib/stream/ctr/ctr.h index 5d5556254..385edac54 100644 --- a/src/lib/stream/ctr/ctr.h +++ b/src/lib/stream/ctr/ctr.h @@ -41,7 +41,7 @@ class BOTAN_DLL CTR_BE final : public StreamCipher static CTR_BE* make(const Spec& spec); /** - * @param cipher the underlying block cipher to use + * @param cipher the block cipher to use */ explicit CTR_BE(BlockCipher* cipher); diff --git a/src/lib/stream/ofb/ofb.h b/src/lib/stream/ofb/ofb.h index 127a06578..7d77bae7a 100644 --- a/src/lib/stream/ofb/ofb.h +++ b/src/lib/stream/ofb/ofb.h @@ -41,7 +41,7 @@ class BOTAN_DLL OFB final : public StreamCipher static OFB* make(const Spec& spec); /** - * @param cipher the underlying block cipher to use + * @param cipher the block cipher to use */ explicit OFB(BlockCipher* cipher); diff --git a/src/lib/stream/stream_cipher.h b/src/lib/stream/stream_cipher.h index b24a99e39..0cbdf3c65 100644 --- a/src/lib/stream/stream_cipher.h +++ b/src/lib/stream/stream_cipher.h @@ -23,14 +23,16 @@ class BOTAN_DLL StreamCipher : public SymmetricAlgorithm /** * Create an instance based on a name - * Will return a null pointer if the algo/provider combination cannot - * be found. If provider is empty then best available is chosen. + * If provider is empty then best available is chosen. + * @param algo_spec algorithm name + * @param provider provider implementation to use + * @return a null pointer if the algo/provider combination cannot be found */ static std::unique_ptr<StreamCipher> create(const std::string& algo_spec, const std::string& provider = ""); /** - * Returns the list of available providers for this algorithm, empty if not available + * @return list of available providers for this algorithm, empty if not available */ static std::vector<std::string> providers(const std::string& algo_spec); @@ -44,20 +46,36 @@ class BOTAN_DLL StreamCipher : public SymmetricAlgorithm /** * Encrypt or decrypt a message + * The message is encrypted/decrypted in place. * @param buf the plaintext / ciphertext * @param len the length of buf in bytes */ void cipher1(byte buf[], size_t len) { cipher(buf, buf, len); } + /** + * Encrypt a message + * The message is encrypted/decrypted in place. + * @param inout the plaintext / ciphertext + */ template<typename Alloc> void encipher(std::vector<byte, Alloc>& inout) { cipher(inout.data(), inout.data(), inout.size()); } + /** + * Encrypt a message + * The message is encrypted in place. + * @param inout the plaintext / ciphertext + */ template<typename Alloc> void encrypt(std::vector<byte, Alloc>& inout) { cipher(inout.data(), inout.data(), inout.size()); } + /** + * Decrypt a message in place + * The message is decrypted in place. + * @param inout the plaintext / ciphertext + */ template<typename Alloc> void decrypt(std::vector<byte, Alloc>& inout) { cipher(inout.data(), inout.data(), inout.size()); } @@ -67,7 +85,7 @@ class BOTAN_DLL StreamCipher : public SymmetricAlgorithm * @param iv the initialization vector * @param iv_len the length of the IV in bytes */ - virtual void set_iv(const byte[], size_t iv_len) = 0; + virtual void set_iv(const byte iv[], size_t iv_len) = 0; /** * @param iv_len the length of the IV in bytes @@ -76,7 +94,7 @@ class BOTAN_DLL StreamCipher : public SymmetricAlgorithm virtual bool valid_iv_length(size_t iv_len) const { return (iv_len == 0); } /** - * Get a new object representing the same algorithm as *this + * @return a new object representing the same algorithm as *this */ virtual StreamCipher* clone() const = 0; diff --git a/src/lib/tls/tls_callbacks.h b/src/lib/tls/tls_callbacks.h index 75887c23f..17cd19b81 100644 --- a/src/lib/tls/tls_callbacks.h +++ b/src/lib/tls/tls_callbacks.h @@ -126,23 +126,27 @@ class BOTAN_DLL Compat_Callbacks final : public Callbacks * * @param alert_cb is called when a TLS alert is received * - * @param handshake_cb is called when a handshake is completed + * @param hs_cb is called when a handshake is completed + * + * @param hs_msg_cb is called for each handshake message received + * + * @param next_proto is called with ALPN protocol data sent by the client */ BOTAN_DEPRECATED("Use TLS::Callbacks (virtual interface).") - Compat_Callbacks(output_fn out, data_cb app_data_cb, alert_cb alert_cb, + Compat_Callbacks(output_fn output_fn, data_cb app_data_cb, alert_cb alert_cb, handshake_cb hs_cb, handshake_msg_cb hs_msg_cb = nullptr, next_protocol_fn next_proto = nullptr) - : m_output_function(out), m_app_data_cb(app_data_cb), + : m_output_function(output_fn), m_app_data_cb(app_data_cb), m_alert_cb(std::bind(alert_cb, std::placeholders::_1, nullptr, 0)), m_hs_cb(hs_cb), m_hs_msg_cb(hs_msg_cb), m_next_proto(next_proto) {} BOTAN_DEPRECATED("Use TLS::Callbacks (virtual interface).") - Compat_Callbacks(output_fn out, data_cb app_data_cb, + Compat_Callbacks(output_fn output_fn, data_cb app_data_cb, std::function<void (Alert)> alert_cb, handshake_cb hs_cb, handshake_msg_cb hs_msg_cb = nullptr, next_protocol_fn next_proto = nullptr) - : m_output_function(out), m_app_data_cb(app_data_cb), + : m_output_function(output_fn), m_app_data_cb(app_data_cb), m_alert_cb(alert_cb), m_hs_cb(hs_cb), m_hs_msg_cb(hs_msg_cb), m_next_proto(next_proto) {} diff --git a/src/lib/tls/tls_channel.h b/src/lib/tls/tls_channel.h index 073af760f..2f4793211 100644 --- a/src/lib/tls/tls_channel.h +++ b/src/lib/tls/tls_channel.h @@ -27,6 +27,8 @@ class Connection_Cipher_State; class Connection_Sequence_Numbers; class Handshake_State; class Handshake_Message; +class Client_Hello; +class Server_Hello; /** * Generic interface for TLS endpoint @@ -41,6 +43,24 @@ class BOTAN_DLL Channel typedef std::function<void (const Handshake_Message&)> handshake_msg_cb; static size_t IO_BUF_DEFAULT_SIZE; + /** + * Set up a new TLS session + * + * @param callbacks contains a set of callback function references + * required by the TLS endpoint. + * + * @param session_manager manages session state + * + * @param rng a random number generator + * + * @param policy specifies other connection policy information + * + * @param is_datagram whether this is a DTLS session + * + * @param io_buf_sz This many bytes of memory will + * be preallocated for the read and write buffers. Smaller + * values just mean reallocations and copies are more likely. + */ Channel(Callbacks& callbacks, Session_Manager& session_manager, RandomNumberGenerator& rng, @@ -203,8 +223,8 @@ class BOTAN_DLL Channel /* secure renegotiation handling */ - void secure_renegotiation_check(const class Client_Hello* client_hello); - void secure_renegotiation_check(const class Server_Hello* server_hello); + void secure_renegotiation_check(const Client_Hello* client_hello); + void secure_renegotiation_check(const Server_Hello* server_hello); std::vector<byte> secure_renegotiation_data_for_client_hello() const; std::vector<byte> secure_renegotiation_data_for_server_hello() const; diff --git a/src/lib/tls/tls_client.h b/src/lib/tls/tls_client.h index 09af053af..d3cff147e 100644 --- a/src/lib/tls/tls_client.h +++ b/src/lib/tls/tls_client.h @@ -72,7 +72,7 @@ class BOTAN_DLL Client final : public Channel * * @param alert_cb is called when a TLS alert is received * - * @param handshake_cb is called when a handshake is completed + * @param hs_cb is called when a handshake is completed * * @param session_manager manages session state * @@ -94,7 +94,7 @@ class BOTAN_DLL Client final : public Channel * values just mean reallocations and copies are more likely. */ BOTAN_DEPRECATED("Use TLS::Client(TLS::Callbacks ...)") - Client(output_fn out, + Client(output_fn output_fn, data_cb app_data_cb, alert_cb alert_cb, handshake_cb hs_cb, @@ -127,6 +127,9 @@ class BOTAN_DLL Client final : public Channel const std::vector<std::string>& next_protocols = {} ); + /** + * @return network protocol as advertised by the TLS server, if server sent the ALPN extension + */ const std::string& application_protocol() const { return m_application_protocol; } private: void init(const Protocol_Version& protocol_version, diff --git a/src/lib/tls/tls_handshake_msg.h b/src/lib/tls/tls_handshake_msg.h index 618ae8d76..c1d3bfdc7 100644 --- a/src/lib/tls/tls_handshake_msg.h +++ b/src/lib/tls/tls_handshake_msg.h @@ -26,10 +26,19 @@ class Handshake_Hash; class BOTAN_DLL Handshake_Message { public: + /** + * @return string representation of this message type + */ std::string type_string() const; + /** + * @return the message type + */ virtual Handshake_Type type() const = 0; + /** + * @return DER representation of this message + */ virtual std::vector<byte> serialize() const = 0; virtual ~Handshake_Message() {} diff --git a/src/lib/tls/tls_messages.h b/src/lib/tls/tls_messages.h index 25228c865..1e012a899 100644 --- a/src/lib/tls/tls_messages.h +++ b/src/lib/tls/tls_messages.h @@ -479,6 +479,7 @@ class BOTAN_DLL Certificate_Verify final : public Handshake_Message * Check the signature on a certificate verify message * @param cert the purported certificate * @param state the handshake state + * @param policy the TLS policy */ bool verify(const X509_Certificate& cert, const Handshake_State& state, diff --git a/src/lib/tls/tls_policy.h b/src/lib/tls/tls_policy.h index 47ac51685..f387361f6 100644 --- a/src/lib/tls/tls_policy.h +++ b/src/lib/tls/tls_policy.h @@ -248,19 +248,32 @@ class BOTAN_DLL Policy virtual std::vector<u16bit> ciphersuite_list(Protocol_Version version, bool have_srp) const; + /** + * @return the default MTU for DTLS + */ virtual size_t dtls_default_mtu() const; + /** + * @return the initial timeout for DTLS + */ virtual size_t dtls_initial_timeout() const; + /** + * @return the maximum timeout for DTLS + */ virtual size_t dtls_maximum_timeout() const; + /** + * Convert this policy to a printable format. + * @param o stream to be printed to + */ virtual void print(std::ostream& o) const; virtual ~Policy() {} }; /** -* NSA Suite B 128-bit security level (see @rfc 6460) +* NSA Suite B 128-bit security level (RFC 6460) */ class BOTAN_DLL NSA_Suite_B_128 : public Policy { @@ -291,7 +304,7 @@ class BOTAN_DLL NSA_Suite_B_128 : public Policy }; /** -* Policy for DTLS. We require DTLS v1.2 and an AEAD mode +* Policy for DTLS. We require DTLS v1.2 and an AEAD mode. */ class BOTAN_DLL Datagram_Policy : public Policy { diff --git a/src/lib/tls/tls_record.h b/src/lib/tls/tls_record.h index b17d0a7b6..d4a2a9372 100644 --- a/src/lib/tls/tls_record.h +++ b/src/lib/tls/tls_record.h @@ -149,14 +149,11 @@ class Record_Raw_Input /** * Create a TLS record * @param write_buffer the output record is placed here -* @param msg_type is the type of the message (handshake, alert, ...) -* @param msg is the plaintext message -* @param msg_length is the length of msg -* @param msg_sequence is the sequence number +* @param rec_msg is the plaintext message * @param version is the protocol version +* @param msg_sequence is the sequence number * @param cipherstate is the writing cipher state * @param rng is a random number generator -* @return number of bytes written to write_buffer */ void write_record(secure_vector<byte>& write_buffer, Record_Message rec_msg, diff --git a/src/lib/tls/tls_server_info.h b/src/lib/tls/tls_server_info.h index 4ae291d3a..cd46aea3f 100644 --- a/src/lib/tls/tls_server_info.h +++ b/src/lib/tls/tls_server_info.h @@ -47,12 +47,25 @@ class BOTAN_DLL Server_Information u16bit port = 0) : m_hostname(hostname), m_service(service), m_port(port) {} + /** + * @return the host's DNS name, if known + */ std::string hostname() const { return m_hostname; } + /** + * @return text string of the service type, e.g., + * "https", "tor", or "git" + */ std::string service() const { return m_service; } + /** + * @return the protocol port of the server, or zero if unknown + */ u16bit port() const { return m_port; } + /** + * @return whether the hostname is known + */ bool empty() const { return m_hostname.empty(); } private: diff --git a/src/lib/tls/tls_session.h b/src/lib/tls/tls_session.h index 643b79ac6..5530632db 100644 --- a/src/lib/tls/tls_session.h +++ b/src/lib/tls/tls_session.h @@ -61,11 +61,14 @@ class BOTAN_DLL Session /** * Load a session from DER representation (created by DER_encode) + * @param ber DER representation buffer + * @param ber_len size of buffer in bytes */ Session(const byte ber[], size_t ber_len); /** * Load a session from PEM representation (created by PEM_encode) + * @param pem PEM representation */ explicit Session(const std::string& pem); @@ -181,6 +184,9 @@ class BOTAN_DLL Session */ const std::vector<byte>& session_ticket() const { return m_session_ticket; } + /** + * @return information about the TLS server + */ const Server_Information& server_info() const { return m_server_info; } private: diff --git a/src/lib/tls/tls_session_key.h b/src/lib/tls/tls_session_key.h index 2ea18d636..8399a9676 100644 --- a/src/lib/tls/tls_session_key.h +++ b/src/lib/tls/tls_session_key.h @@ -14,27 +14,58 @@ namespace Botan { namespace TLS { +class Handshake_State; + /** * TLS Session Keys */ class Session_Keys { public: + /** + * @return client encipherment key + */ const SymmetricKey& client_cipher_key() const { return m_c_cipher; } + + /** + * @return client encipherment key + */ const SymmetricKey& server_cipher_key() const { return m_s_cipher; } + /** + * @return client MAC key + */ const SymmetricKey& client_mac_key() const { return m_c_mac; } + + /** + * @return server MAC key + */ const SymmetricKey& server_mac_key() const { return m_s_mac; } + /** + * @return client IV + */ const InitializationVector& client_iv() const { return m_c_iv; } + + /** + * @return server IV + */ const InitializationVector& server_iv() const { return m_s_iv; } + /** + * @return TLS master secret + */ const secure_vector<byte>& master_secret() const { return m_master_sec; } Session_Keys() {} - Session_Keys(const class Handshake_State* state, - const secure_vector<byte>& pre_master, + /** + * @param state state the handshake state + * @param pre_master_secret the pre-master secret + * @param resuming whether this TLS session is resumed + */ + Session_Keys(const Handshake_State* state, + const secure_vector<byte>& pre_master_secret, bool resuming); private: diff --git a/src/lib/tls/tls_session_manager.h b/src/lib/tls/tls_session_manager.h index 49f4925d8..ca6712e1f 100644 --- a/src/lib/tls/tls_session_manager.h +++ b/src/lib/tls/tls_session_manager.h @@ -109,6 +109,8 @@ class BOTAN_DLL Session_Manager_In_Memory : public Session_Manager { public: /** + * @param rng a RNG used for generating session key and for + * session encryption * @param max_sessions a hint on the maximum number of sessions * to keep in memory at any one time. (If zero, don't cap) * @param session_lifetime sessions are expired after this many diff --git a/src/lib/tls/tls_version.h b/src/lib/tls/tls_version.h index 73968bb8c..29839502d 100644 --- a/src/lib/tls/tls_version.h +++ b/src/lib/tls/tls_version.h @@ -30,11 +30,17 @@ class BOTAN_DLL Protocol_Version DTLS_V12 = 0xFEFD }; + /** + * @return latest known TLS version + */ static Protocol_Version latest_tls_version() { return Protocol_Version(TLS_V12); } + /** + * @return latest known DTLS version + */ static Protocol_Version latest_dtls_version() { return Protocol_Version(DTLS_V12); diff --git a/src/lib/utils/parsing.h b/src/lib/utils/parsing.h index db8db198e..c609e821d 100644 --- a/src/lib/utils/parsing.h +++ b/src/lib/utils/parsing.h @@ -39,6 +39,7 @@ BOTAN_DLL std::vector<std::string> split_on( /** * Split a string on a character predicate * @param str the input string +* @param pred the predicate */ BOTAN_DLL std::vector<std::string> split_on_pred(const std::string& str, diff --git a/src/lib/utils/version.h b/src/lib/utils/version.h index 406deae66..6e9e231bc 100644 --- a/src/lib/utils/version.h +++ b/src/lib/utils/version.h @@ -58,7 +58,7 @@ BOTAN_DLL u32bit version_patch(); * Usable for checking that the DLL version loaded at runtime exactly * matches the compile-time version. Call using BOTAN_VERSION_* macro * values. Returns the empty string if an exact match, otherwise an -* appropriate message. @added 1.11.26 +* appropriate message. Added with 1.11.26. */ BOTAN_DLL std::string runtime_version_check(u32bit major, |