Skip to content

Commit

Permalink
Align with BouncyCastle and Botan for DLIES and ECIES. Updated docume…
Browse files Browse the repository at this point in the history 
…ntation
  • Loading branch information
@noloader
noloader committed Oct 18, 2016
1 parent b5f04e5 commit c3e2e0f
Show file tree
Hide file tree
Showing 2 changed files with 254 additions and 101 deletions.
109 changes: 88 additions & 21 deletions eccrypto.h
View file
Expand Up @@ -147,7 +147,9 @@ class DL_GroupParameters_EC : public DL_GroupParametersImpl<EcPrecomputation<EC>
mutable bool m_compress, m_encodeAsOID; // presentation details
};

//! EC public key
//! \class DL_PublicKey_EC
//! \brief Elliptic Curve Discrete Log (DL) public key
//! \tparam EC elliptic curve field
template <class EC>
class DL_PublicKey_EC : public DL_PublicKeyImpl<DL_GroupParameters_EC<EC> >
{
Expand All @@ -168,7 +170,9 @@ class DL_PublicKey_EC : public DL_PublicKeyImpl<DL_GroupParameters_EC<EC> >
void DEREncodePublicKey(BufferedTransformation &bt) const;
};

//! EC private key
//! \class DL_PrivateKey_EC
//! \brief Elliptic Curve Discrete Log (DL) private key
//! \tparam EC elliptic curve field
template <class EC>
class DL_PrivateKey_EC : public DL_PrivateKeyImpl<DL_GroupParameters_EC<EC> >
{
Expand All @@ -193,7 +197,11 @@ class DL_PrivateKey_EC : public DL_PrivateKeyImpl<DL_GroupParameters_EC<EC> >
void DEREncodePrivateKey(BufferedTransformation &bt) const;
};

//! Elliptic Curve Diffie-Hellman, AKA <a href="http://www.weidai.com/scan-mirror/ka.html#ECDH">ECDH</a>
//! \class ECDH
//! \brief Elliptic Curve Diffie-Hellman
//! \tparam EC elliptic curve field
//! \tparam COFACTOR_OPTION \ref CofactorMultiplicationOption "cofactor multiplication option"
//! \sa <a href="http://www.weidai.com/scan-mirror/ka.html#ECDH">Elliptic Curve Diffie-Hellman, AKA ECDH</a>
template <class EC, class COFACTOR_OPTION = CPP_TYPENAME DL_GroupParameters_EC<EC>::DefaultCofactorOption>
struct ECDH
{
Expand All @@ -204,7 +212,11 @@ struct ECDH
#endif
};

/// Elliptic Curve Menezes-Qu-Vanstone, AKA <a href="http://www.weidai.com/scan-mirror/ka.html#ECMQV">ECMQV</a>
//! \class ECMQV
//! \brief Elliptic Curve Menezes-Qu-Vanstone
//! \tparam EC elliptic curve field
//! \tparam COFACTOR_OPTION \ref CofactorMultiplicationOption "cofactor multiplication option"
/// \sa <a href="http://www.weidai.com/scan-mirror/ka.html#ECMQV">Elliptic Curve Menezes-Qu-Vanstone, AKA ECMQV</a>
template <class EC, class COFACTOR_OPTION = CPP_TYPENAME DL_GroupParameters_EC<EC>::DefaultCofactorOption>
struct ECMQV
{
Expand All @@ -215,7 +227,10 @@ struct ECMQV
#endif
};

//! \brief Hashed Menezes-Qu-Vanstone in ECP or EC2N
//! \class ECHMQV
//! \brief Hashed Elliptic Curve Menezes-Qu-Vanstone
//! \tparam EC elliptic curve field
//! \tparam COFACTOR_OPTION \ref CofactorMultiplicationOption "cofactor multiplication option"
//! \details This implementation follows Hugo Krawczyk's <a href="http://eprint.iacr.org/2005/176">HMQV: A High-Performance
//! Secure Diffie-Hellman Protocol</a>. Note: this implements HMQV only. HMQV-C with Key Confirmation is not provided.
template <class EC, class COFACTOR_OPTION = CPP_TYPENAME DL_GroupParameters_EC<EC>::DefaultCofactorOption, class HASH = SHA256>
Expand All @@ -233,7 +248,10 @@ typedef ECHMQV< ECP, DL_GroupParameters_EC< ECP >::DefaultCofactorOption, SHA256
typedef ECHMQV< ECP, DL_GroupParameters_EC< ECP >::DefaultCofactorOption, SHA384 >::Domain ECHMQV384;
typedef ECHMQV< ECP, DL_GroupParameters_EC< ECP >::DefaultCofactorOption, SHA512 >::Domain ECHMQV512;

//! \brief Fully Hashed Menezes-Qu-Vanstone in ECP or EC2N
//! \class ECFHMQV
//! \brief Fully Hashed Elliptic Curve Menezes-Qu-Vanstone
//! \tparam EC elliptic curve field
//! \tparam COFACTOR_OPTION \ref CofactorMultiplicationOption "cofactor multiplication option"
//! \details This implementation follows Augustin P. Sarr and Philippe Elbaz–Vincent, and Jean–Claude Bajard's
//! <a href="http://eprint.iacr.org/2009/408">A Secure and Efficient Authenticated Diffie-Hellman Protocol</a>.
//! Note: this is FHMQV, Protocol 5, from page 11; and not FHMQV-C.
Expand All @@ -252,7 +270,9 @@ typedef ECFHMQV< ECP, DL_GroupParameters_EC< ECP >::DefaultCofactorOption, SHA25
typedef ECFHMQV< ECP, DL_GroupParameters_EC< ECP >::DefaultCofactorOption, SHA384 >::Domain ECFHMQV384;
typedef ECFHMQV< ECP, DL_GroupParameters_EC< ECP >::DefaultCofactorOption, SHA512 >::Domain ECFHMQV512;

//! EC keys
//! \class DL_Keys_EC
//! \brief Elliptic Curve Discrete Log (DL) keys
//! \tparam EC elliptic curve field
template <class EC>
struct DL_Keys_EC
{
Expand All @@ -264,10 +284,16 @@ struct DL_Keys_EC
#endif
};

//! \class ECDSA
//! \brief Elliptic Curve DSA
//! \tparam EC elliptic curve field
//! \tparam H HashTransformation derived class
template <class EC, class H>
struct ECDSA;

//! ECDSA keys
//! \class DL_Keys_ECDSA
//! \brief Elliptic Curve DSA keys
//! \tparam EC elliptic curve field
template <class EC>
struct DL_Keys_ECDSA
{
Expand All @@ -279,7 +305,9 @@ struct DL_Keys_ECDSA
#endif
};

//! ECDSA algorithm
//! \class DL_Algorithm_ECDSA
//! \brief Elliptic Curve DSA (ECDSA) signature algorithm
//! \tparam EC elliptic curve field
template <class EC>
class DL_Algorithm_ECDSA : public DL_Algorithm_GDSA<typename EC::Point>
{
Expand All @@ -291,7 +319,9 @@ class DL_Algorithm_ECDSA : public DL_Algorithm_GDSA<typename EC::Point>
#endif
};

//! ECNR algorithm
//! \class DL_Algorithm_ECNR
//! \brief Elliptic Curve NR (ECNR) signature algorithm
//! \tparam EC elliptic curve field
template <class EC>
class DL_Algorithm_ECNR : public DL_Algorithm_NR<typename EC::Point>
{
Expand All @@ -303,7 +333,11 @@ class DL_Algorithm_ECNR : public DL_Algorithm_NR<typename EC::Point>
#endif
};

//! <a href="http://www.weidai.com/scan-mirror/sig.html#ECDSA">ECDSA</a>
//! \class ECDSA
//! \brief Elliptic Curve DSA (ECDSA) signature scheme
//! \tparam EC elliptic curve field
//! \tparam H HashTransformation derived class
//! \sa <a href="http://www.weidai.com/scan-mirror/sig.html#ECDSA">ECDSA</a>
template <class EC, class H>
struct ECDSA : public DL_SS<DL_Keys_ECDSA<EC>, DL_Algorithm_ECDSA<EC>, DL_SignatureMessageEncodingMethod_DSA, H>
{
Expand All @@ -312,7 +346,10 @@ struct ECDSA : public DL_SS<DL_Keys_ECDSA<EC>, DL_Algorithm_ECDSA<EC>, DL_Signat
#endif
};

//! ECNR
//! \class ECNR
//! \brief Elliptic Curve NR (ECNR) signature scheme
//! \tparam EC elliptic curve field
//! \tparam H HashTransformation derived class
template <class EC, class H = SHA>
struct ECNR : public DL_SS<DL_Keys_EC<EC>, DL_Algorithm_ECNR<EC>, DL_SignatureMessageEncodingMethod_NR, H>
{
Expand All @@ -321,26 +358,56 @@ struct ECNR : public DL_SS<DL_Keys_EC<EC>, DL_Algorithm_ECNR<EC>, DL_SignatureMe
#endif
};

//! Elliptic Curve Integrated Encryption Scheme, AKA <a href="http://www.weidai.com/scan-mirror/ca.html#ECIES">ECIES</a>
/*! Default to (NoCofactorMultiplication and DHAES_MODE = false) for compatibilty with SEC1 and Crypto++ 4.2.
The combination of (IncompatibleCofactorMultiplication and DHAES_MODE = true) is recommended for best
efficiency and security. */
template <class EC, class COFACTOR_OPTION = NoCofactorMultiplication, bool DHAES_MODE = false>

//! \class ECIES
//! \brief Elliptic Curve Integrated Encryption Scheme
//! \tparam COFACTOR_OPTION \ref CofactorMultiplicationOption "cofactor multiplication option"
//! \tparam HASH HashTransformation derived class used for key drivation and MAC computation
//! \tparam DHAES_MODE flag indicating if the MAC includes additional context parameters such as <em>u·V</em>, <em>v·U</em> and label
//! \tparam LABEL_OCTETS flag indicating if the label size is specified in octets or bits
//! \details ECIES is an Elliptic Curve based Integrated Encryption Scheme (IES). The scheme combines a Key Encapsulation
//! Method (KEM) with a Data Encapsulation Method (DEM) and a MAC tag. The scheme is
//! <A HREF="http://en.wikipedia.org/wiki/ciphertext_indistinguishability">IND-CCA2</A>, which is a strong notion of security.
//! You should prefer an Integrated Encryption Scheme over homegrown schemes.
//! \details The library's original implementation is based on an early P1363 draft, which itself appears to be based on an early Certicom
//! SEC-1 draft (or an early SEC-1 draft was based on a P1363 draft). Crypto++ 4.2 used the early draft in its Integrated Ecryption
//! Schemes with <tt>NoCofactorMultiplication</tt>, <tt>DHAES_MODE=false</tt> and <tt>LABEL_OCTETS=true</tt>.
//! \details If you desire an Integrated Encryption Scheme with Crypto++ 4.2 compatibility, then use the ECIES template class with
//! <tt>NoCofactorMultiplication</tt>, <tt>DHAES_MODE=false</tt> and <tt>LABEL_OCTETS=true</tt>.
//! \details If you desire an Integrated Encryption Scheme with Bouncy Castle 1.55 and Botan 1.11 compatibility, then use the ECIES
//! template class with <tt>NoCofactorMultiplication</tt>, <tt>DHAES_MODE=true</tt> and <tt>LABEL_OCTETS=false</tt>.
//! \details Bouncy Castle 1.55 and Botan 1.11 compatibility are the default template parameters. The combination of
//! <tt>IncompatibleCofactorMultiplication</tt> and <tt>DHAES_MODE=true</tt> is recommended for best efficiency and security.
//! SHA1 is used for compatibility reasons, but it can be changed of if desired. SHA-256 or another hash will likely improve the
//! security provided by the MAC. The hash is also used in the key derivation function as a PRF.
//! \details Below is an example of constructing a Crypto++ 4.2 compatible ECIES encryptor and decryptor.
//! <pre>
//! AutoSeededRandomPool prng;
//! DL_PrivateKey_EC<ECP> key;
//! key.Initialize(prng, ASN1::secp160r1());
//!
//! ECIES<ECP,SHA1,NoCofactorMultiplication,true,true>::Decryptor decryptor(key);
//! ECIES<ECP,SHA1,NoCofactorMultiplication,true,true>::Encryptor encryptor(decryptor);
//! </pre>
//! \sa DLIES, <a href="http://www.weidai.com/scan-mirror/ca.html#ECIES">Elliptic Curve Integrated Encryption Scheme (ECIES)</a>,
//! Martínez, Encinas, and Ávila's <A HREF="http://digital.csic.es/bitstream/10261/32671/1/V2-I2-P7-13.pdf">A Survey of the Elliptic
//! Curve Integrated Encryption Schemes</A>
//! \since Crypto++ 4.0
template <class EC, class HASH = SHA1, class COFACTOR_OPTION = NoCofactorMultiplication, bool DHAES_MODE = true, bool LABEL_OCTETS = false>
struct ECIES
: public DL_ES<
DL_Keys_EC<EC>,
DL_KeyAgreementAlgorithm_DH<typename EC::Point, COFACTOR_OPTION>,
DL_KeyDerivationAlgorithm_P1363<typename EC::Point, DHAES_MODE, P1363_KDF2<SHA1> >,
DL_EncryptionAlgorithm_Xor<HMAC<SHA1>, DHAES_MODE>,
DL_KeyDerivationAlgorithm_P1363<typename EC::Point, DHAES_MODE, P1363_KDF2<HASH> >,
DL_EncryptionAlgorithm_Xor<HMAC<HASH>, DHAES_MODE, LABEL_OCTETS>,
ECIES<EC> >
{
static std::string CRYPTOPP_API StaticAlgorithmName() {return "ECIES";} // TODO: fix this after name is standardized

#ifndef CRYPTOPP_MAINTAIN_BACKWARDS_COMPATIBILITY_562
virtual ~ECIES() {}
#endif

} CRYPTOPP_DEPRECATED ("ECIES will be changing in the near future due to an interop issue");
};

NAMESPACE_END

Expand Down

2 comments on commit c3e2e0f

@noloader
Copy link
Collaborator Author

@noloader noloader commented on c3e2e0f Oct 18, 2016 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is Uri's patch from Pull Request 216. The patch was getting stale. It sat idle because of concerns over Crypto++ 5.6.2 compatibility.

In the bigger picture, "Perfection became the enemy of the good". More folks will benefit in the long term with BouncyCastle and Botan compatibility out of the box. We document the steps necessary for 5.6.2 compatibility for those who need it.

Also see Issue 21 and Issue 307.

@noloader
Copy link
Collaborator Author

@noloader noloader commented on c3e2e0f Jul 3, 2019 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This commit introduced a bug that was cleared at Issue 856, ECIES and GetSymmetricKeyLength no longer uses MAC::DEFAULT_KEYLENGTH. I believe the bug was introduced by JW, not UB.

Please sign in to comment.