00001 // fips140.h - written and placed in the public domain by Wei Dai 00002 00003 //! \file fips140.h 00004 //! \brief Classes and functions for the FIPS 140-2 validated library 00005 //! \details The FIPS validated library is only available on Windows as a DLL. Once compiled, 00006 //! the library is always in FIPS mode contingent upon successful execution of 00007 //! DoPowerUpSelfTest() or DoDllPowerUpSelfTest(). 00008 //! \sa <A HREF="http://cryptopp.com/wiki/Visual_Studio">Visual Studio</A> and 00009 //! <A HREF="http://cryptopp.com/wiki/config.h">config.h</A> on the Crypto++ wiki. 00010 00011 #ifndef CRYPTOPP_FIPS140_H 00012 #define CRYPTOPP_FIPS140_H 00013 00014 #include "cryptlib.h" 00015 #include "secblock.h" 00016 00017 NAMESPACE_BEGIN(CryptoPP) 00018 00019 //! \class SelfTestFailure 00020 //! Exception thrown when a crypto algorithm is used after a self test fails 00021 //! \details The self tests for an algorithm are performed by Algortihm class 00022 //! when CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 is defined. 00023 class CRYPTOPP_DLL SelfTestFailure : public Exception 00024 { 00025 public: 00026 explicit SelfTestFailure(const std::string &s) : Exception(OTHER_ERROR, s) {} 00027 }; 00028 00029 //! \brief Determines whether the library provides FIPS validated cryptography 00030 //! \returns true if FIPS 140-2 validated features were enabled at compile time. 00031 //! \details true if FIPS 140-2 validated features were enabled at compile time, 00032 //! false otherwise. 00033 //! \note FIPS mode is enabled at compile time. A program or other module cannot 00034 //! arbitrarily enter or exit the mode. 00035 CRYPTOPP_DLL bool CRYPTOPP_API FIPS_140_2_ComplianceEnabled(); 00036 00037 //! \brief Status of the power-up self test 00038 enum PowerUpSelfTestStatus { 00039 00040 //! \brief The self tests have not been performed. 00041 POWER_UP_SELF_TEST_NOT_DONE, 00042 //! \brief The self tests were executed via DoPowerUpSelfTest() or 00043 //! DoDllPowerUpSelfTest(), but the result was failure. 00044 POWER_UP_SELF_TEST_FAILED, 00045 //! \brief The self tests were executed via DoPowerUpSelfTest() or 00046 //! DoDllPowerUpSelfTest(), and the result was success. 00047 POWER_UP_SELF_TEST_PASSED 00048 }; 00049 00050 //! \brief Performs the power-up self test 00051 //! \param moduleFilename the fully qualified name of the module 00052 //! \param expectedModuleMac the expected MAC of the components protected by the integrity check 00053 //! \details Performs the power-up self test, and sets the self test status to 00054 //! POWER_UP_SELF_TEST_PASSED or POWER_UP_SELF_TEST_FAILED. 00055 //! \details The self tests for an algorithm are performed by the Algortihm class 00056 //! when CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 is defined. 00057 CRYPTOPP_DLL void CRYPTOPP_API DoPowerUpSelfTest(const char *moduleFilename, const byte *expectedModuleMac); 00058 00059 //! \brief Performs the power-up self test on the DLL 00060 //! \details Performs the power-up self test using the filename of this DLL and the 00061 //! embedded module MAC, and sets the self test status to POWER_UP_SELF_TEST_PASSED or 00062 //! POWER_UP_SELF_TEST_FAILED. 00063 //! \details The self tests for an algorithm are performed by the Algortihm class 00064 //! when CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 is defined. 00065 CRYPTOPP_DLL void CRYPTOPP_API DoDllPowerUpSelfTest(); 00066 00067 //! \brief Sets the power-up self test status to POWER_UP_SELF_TEST_FAILED 00068 //! \details Sets the power-up self test status to POWER_UP_SELF_TEST_FAILED to simulate failure. 00069 CRYPTOPP_DLL void CRYPTOPP_API SimulatePowerUpSelfTestFailure(); 00070 00071 //! \brief Provides the current power-up self test status 00072 //! \returns the current power-up self test status 00073 CRYPTOPP_DLL PowerUpSelfTestStatus CRYPTOPP_API GetPowerUpSelfTestStatus(); 00074 00075 #ifndef CRYPTOPP_DOXYGEN_PROCESSING 00076 typedef PowerUpSelfTestStatus (CRYPTOPP_API * PGetPowerUpSelfTestStatus)(); 00077 #endif 00078 00079 //! \brief Class object that calculates the MAC on the module 00080 //! \returns the MAC for the module 00081 CRYPTOPP_DLL MessageAuthenticationCode * CRYPTOPP_API NewIntegrityCheckingMAC(); 00082 00083 //! \brief Verifies the MAC on the module 00084 //! \param moduleFilename the fully qualified name of the module 00085 //! \param expectedModuleMac the expected MAC of the components protected by the integrity check 00086 //! \param pActualMac the actual MAC of the components calculated by the integrity check 00087 //! \param pMacFileLocation the offest of the MAC in the PE/PE+ module 00088 //! \returns true if the MAC is valid, false otherwise 00089 CRYPTOPP_DLL bool CRYPTOPP_API IntegrityCheckModule(const char *moduleFilename, const byte *expectedModuleMac, SecByteBlock *pActualMac = NULL, unsigned long *pMacFileLocation = NULL); 00090 00091 #ifndef CRYPTOPP_DOXYGEN_PROCESSING 00092 // this is used by Algorithm constructor to allow Algorithm objects to be constructed for the self test 00093 bool PowerUpSelfTestInProgressOnThisThread(); 00094 00095 void SetPowerUpSelfTestInProgressOnThisThread(bool inProgress); 00096 00097 void SignaturePairwiseConsistencyTest(const PK_Signer &signer, const PK_Verifier &verifier); 00098 void EncryptionPairwiseConsistencyTest(const PK_Encryptor &encryptor, const PK_Decryptor &decryptor); 00099 00100 void SignaturePairwiseConsistencyTest_FIPS_140_Only(const PK_Signer &signer, const PK_Verifier &verifier); 00101 void EncryptionPairwiseConsistencyTest_FIPS_140_Only(const PK_Encryptor &encryptor, const PK_Decryptor &decryptor); 00102 #endif 00103 00104 //! \brief The placeholder used prior to embedding the actual MAC in the module. 00105 //! \details After the DLL is built but before it is MAC'd, the string CRYPTOPP_DUMMY_DLL_MAC 00106 //! is used as a placeholder for the actual MAC. A post-build step is performed which calculates 00107 //! the MAC of the DLL and embeds it in the module. The actual MAC is written by the 00108 //! <tt>cryptest.exe</tt> program using the <tt>mac_dll</tt> subcommand. 00109 #define CRYPTOPP_DUMMY_DLL_MAC "MAC_51f34b8db820ae8" 00110 00111 NAMESPACE_END 00112 00113 #endif