From ecababa006ed22b6df42ea43ef5986bcec78aa28 Mon Sep 17 00:00:00 2001 From: Jeffrey Walton Date: Fri, 6 Jul 2018 02:57:48 -0400 Subject: [PATCH] Update documentation --- cryptlib.h | 4 +++- modes.h | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++---- seckey.h | 5 ++-- 3 files changed, 70 insertions(+), 8 deletions(-) diff --git a/cryptlib.h b/cryptlib.h index 3c5127f4..49ee654f 100644 --- a/cryptlib.h +++ b/cryptlib.h @@ -605,11 +605,13 @@ public: /// \brief Returns smallest valid key length /// \returns the minimum key length, in bytes virtual size_t MinKeyLength() const =0; + /// \brief Returns largest valid key length /// \returns the maximum key length, in bytes virtual size_t MaxKeyLength() const =0; + /// \brief Returns default key length - /// \returns the default (recommended) key length, in bytes + /// \returns the default key length, in bytes virtual size_t DefaultKeyLength() const =0; /// \brief Returns a valid key length for the algorithm diff --git a/modes.h b/modes.h index ca1c90f8..b6be8716 100644 --- a/modes.h +++ b/modes.h @@ -50,17 +50,53 @@ class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE CipherModeBase : public SymmetricCipher { public: virtual ~CipherModeBase() {} - size_t MinKeyLength() const {return m_cipher->MinKeyLength();} - size_t MaxKeyLength() const {return m_cipher->MaxKeyLength();} - size_t DefaultKeyLength() const {return m_cipher->DefaultKeyLength();} - size_t GetValidKeyLength(size_t n) const {return m_cipher->GetValidKeyLength(n);} - bool IsValidKeyLength(size_t n) const {return m_cipher->IsValidKeyLength(n);} + /// \brief Returns smallest valid key length + /// \returns the minimum key length, in bytes + size_t MinKeyLength() const {return m_cipher->MinKeyLength();} + + /// \brief Returns largest valid key length + /// \returns the maximum key length, in bytes + size_t MaxKeyLength() const {return m_cipher->MaxKeyLength();} + + /// \brief Returns default key length + /// \returns the default key length, in bytes + size_t DefaultKeyLength() const {return m_cipher->DefaultKeyLength();} + + /// \brief Returns a valid key length for the algorithm + /// \param keylength the size of the key, in bytes + /// \returns the valid key length, in bytes + /// \details keylength is provided in bytes, not bits. If keylength is less than MIN_KEYLENGTH, + /// then the function returns MIN_KEYLENGTH. If keylength is greater than MAX_KEYLENGTH, + /// then the function returns MAX_KEYLENGTH. if If keylength is a multiple of KEYLENGTH_MULTIPLE, + /// then keylength is returned. Otherwise, the function returns a \a lower multiple of + /// KEYLENGTH_MULTIPLE. + size_t GetValidKeyLength(size_t keylength) const {return m_cipher->GetValidKeyLength(keylength);} + + /// \brief Returns whether keylength is a valid key length + /// \param keylength the requested keylength + /// \return true if keylength is valid, false otherwise + /// \details Internally the function calls GetValidKeyLength() + bool IsValidKeyLength(size_t keylength) const {return m_cipher->IsValidKeyLength(keylength);} + + /// \brief Provides input and output data alignment for optimal performance. + /// \return the input data alignment that provides optimal performance + /// \sa GetAlignment() and OptimalBlockSize() unsigned int OptimalDataAlignment() const {return m_cipher->OptimalDataAlignment();} + /// \brief Returns length of the IV accepted by this object + /// \return the size of an IV, in bytes + /// \throws NotImplemented() if the object does not support resynchronization + /// \details The default implementation throws NotImplemented unsigned int IVSize() const {return BlockSize();} + + /// \brief Minimal requirement for secure IVs + /// \return the secure IV requirement of the algorithm virtual IV_Requirement IVRequirement() const =0; + /// \brief Set external block cipher + /// \param cipher An external block cipher + /// \details The cipher should be keyed. void SetCipher(BlockCipher &cipher) { this->ThrowIfResynchronizable(); @@ -68,6 +104,11 @@ public: this->ResizeBuffers(); } + /// \brief Set external block cipher and IV + /// \param cipher An external block cipher + /// \param iv a byte array used to resynchronize the cipher + /// \param feedbackSize the feedback size, in bytes + /// \details The cipher should be keyed. void SetCipherWithIV(BlockCipher &cipher, const byte *iv, int feedbackSize = 0) { this->ThrowIfInvalidIV(iv); @@ -315,12 +356,30 @@ template class CipherModeFinalTemplate_ExternalCipher : public BASE { public: + /// \brief Construct a default CipherModeFinalTemplate + /// \details The cipher is not keyed. CipherModeFinalTemplate_ExternalCipher() {} + + /// \brief Construct a CipherModeFinalTemplate + /// \param cipher An external block cipher + /// \details The cipher should be keyed. CipherModeFinalTemplate_ExternalCipher(BlockCipher &cipher) {this->SetCipher(cipher);} + + /// \brief Construct a CipherModeFinalTemplate + /// \param cipher An external block cipher + /// \param iv a byte array used to resynchronize the cipher + /// \param feedbackSize the feedback size, in bytes + /// \details The cipher should be keyed. CipherModeFinalTemplate_ExternalCipher(BlockCipher &cipher, const byte *iv, int feedbackSize = 0) {this->SetCipherWithIV(cipher, iv, feedbackSize);} + /// \brief Provides the name of this algorithm + /// \return the standard algorithm name + /// \details The standard algorithm name can be a name like \a AES or \a AES/GCM. Some algorithms + /// do not have standard names yet. For example, there is no standard algorithm name for + /// Shoup's ECIES. + /// \note AlgorithmName is not universally implemented yet std::string AlgorithmName() const {return (this->m_cipher ? this->m_cipher->AlgorithmName() + "/" : std::string("")) + BASE::StaticAlgorithmName();} }; diff --git a/seckey.h b/seckey.h index 38fd14a8..7a711a65 100644 --- a/seckey.h +++ b/seckey.h @@ -311,8 +311,9 @@ public: SimpleKeyingInterface::IV_Requirement IVRequirement() const {return (SimpleKeyingInterface::IV_Requirement)INFO::IV_REQUIREMENT;} - /// \brief The default initialization vector length for the algorithm - /// \details IVSize is provided in bytes, not bits. The default implementation uses IV_LENGTH, which is 0. + /// \brief The initialization vector length for the algorithm + /// \details IVSize is provided in bytes, not bits. The default implementation uses + /// IV_LENGTH, which is 0. unsigned int IVSize() const {return INFO::IV_LENGTH;} };