Crypto++  5.6.3
Free C++ class library of cryptographic schemes
fips140.h
Go to the documentation of this file.
1 // fips140.h - written and placed in the public domain by Wei Dai
2 
3 //! \file fips140.h
4 //! \brief Classes and functions for the FIPS 140-2 validated library
5 //! \details The FIPS validated library is only available on Windows as a DLL. Once compiled,
6 //! the library is always in FIPS mode contingent upon successful execution of
7 //! DoPowerUpSelfTest() or DoDllPowerUpSelfTest().
8 //! \sa <A HREF="http://cryptopp.com/wiki/Visual_Studio">Visual Studio</A> and
9 //! <A HREF="http://cryptopp.com/wiki/config.h">config.h</A> on the Crypto++ wiki.
10 
11 #ifndef CRYPTOPP_FIPS140_H
12 #define CRYPTOPP_FIPS140_H
13 
14 #include "cryptlib.h"
15 #include "secblock.h"
16 
17 NAMESPACE_BEGIN(CryptoPP)
18 
19 //! \class SelfTestFailure
20 //! Exception thrown when a crypto algorithm is used after a self test fails
21 //! \details The self tests for an algorithm are performed by Algortihm class
22 //! when CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 is defined.
23 class CRYPTOPP_DLL SelfTestFailure : public Exception
24 {
25 public:
26  explicit SelfTestFailure(const std::string &s) : Exception(OTHER_ERROR, s) {}
27 };
28 
29 //! \brief Determines whether the library provides FIPS validated cryptography
30 //! \returns true if FIPS 140-2 validated features were enabled at compile time.
31 //! \details true if FIPS 140-2 validated features were enabled at compile time,
32 //! false otherwise.
33 //! \note FIPS mode is enabled at compile time. A program or other module cannot
34 //! arbitrarily enter or exit the mode.
35 CRYPTOPP_DLL bool CRYPTOPP_API FIPS_140_2_ComplianceEnabled();
36 
37 //! \brief Status of the power-up self test
39 
40  //! \brief The self tests have not been performed.
42  //! \brief The self tests were executed via DoPowerUpSelfTest() or
43  //! DoDllPowerUpSelfTest(), but the result was failure.
45  //! \brief The self tests were executed via DoPowerUpSelfTest() or
46  //! DoDllPowerUpSelfTest(), and the result was success.
48 };
49 
50 //! \brief Performs the power-up self test
51 //! \param moduleFilename the fully qualified name of the module
52 //! \param expectedModuleMac the expected MAC of the components protected by the integrity check
53 //! \details Performs the power-up self test, and sets the self test status to
54 //! POWER_UP_SELF_TEST_PASSED or POWER_UP_SELF_TEST_FAILED.
55 //! \details The self tests for an algorithm are performed by the Algortihm class
56 //! when CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 is defined.
57 CRYPTOPP_DLL void CRYPTOPP_API DoPowerUpSelfTest(const char *moduleFilename, const byte *expectedModuleMac);
58 
59 //! \brief Performs the power-up self test on the DLL
60 //! \details Performs the power-up self test using the filename of this DLL and the
61 //! embedded module MAC, and sets the self test status to POWER_UP_SELF_TEST_PASSED or
62 //! POWER_UP_SELF_TEST_FAILED.
63 //! \details The self tests for an algorithm are performed by the Algortihm class
64 //! when CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 is defined.
65 CRYPTOPP_DLL void CRYPTOPP_API DoDllPowerUpSelfTest();
66 
67 //! \brief Sets the power-up self test status to POWER_UP_SELF_TEST_FAILED
68 //! \details Sets the power-up self test status to POWER_UP_SELF_TEST_FAILED to simulate failure.
69 CRYPTOPP_DLL void CRYPTOPP_API SimulatePowerUpSelfTestFailure();
70 
71 //! \brief Provides the current power-up self test status
72 //! \returns the current power-up self test status
73 CRYPTOPP_DLL PowerUpSelfTestStatus CRYPTOPP_API GetPowerUpSelfTestStatus();
74 
75 #ifndef CRYPTOPP_DOXYGEN_PROCESSING
76 typedef PowerUpSelfTestStatus (CRYPTOPP_API * PGetPowerUpSelfTestStatus)();
77 #endif
78 
79 //! \brief Class object that calculates the MAC on the module
80 //! \returns the MAC for the module
81 CRYPTOPP_DLL MessageAuthenticationCode * CRYPTOPP_API NewIntegrityCheckingMAC();
82 
83 //! \brief Verifies the MAC on the module
84 //! \param moduleFilename the fully qualified name of the module
85 //! \param expectedModuleMac the expected MAC of the components protected by the integrity check
86 //! \param pActualMac the actual MAC of the components calculated by the integrity check
87 //! \param pMacFileLocation the offest of the MAC in the PE/PE+ module
88 //! \returns true if the MAC is valid, false otherwise
89 CRYPTOPP_DLL bool CRYPTOPP_API IntegrityCheckModule(const char *moduleFilename, const byte *expectedModuleMac, SecByteBlock *pActualMac = NULL, unsigned long *pMacFileLocation = NULL);
90 
91 #ifndef CRYPTOPP_DOXYGEN_PROCESSING
92 // this is used by Algorithm constructor to allow Algorithm objects to be constructed for the self test
93 bool PowerUpSelfTestInProgressOnThisThread();
94 
95 void SetPowerUpSelfTestInProgressOnThisThread(bool inProgress);
96 
97 void SignaturePairwiseConsistencyTest(const PK_Signer &signer, const PK_Verifier &verifier);
98 void EncryptionPairwiseConsistencyTest(const PK_Encryptor &encryptor, const PK_Decryptor &decryptor);
99 
100 void SignaturePairwiseConsistencyTest_FIPS_140_Only(const PK_Signer &signer, const PK_Verifier &verifier);
101 void EncryptionPairwiseConsistencyTest_FIPS_140_Only(const PK_Encryptor &encryptor, const PK_Decryptor &decryptor);
102 #endif
103 
104 //! \brief The placeholder used prior to embedding the actual MAC in the module.
105 //! \details After the DLL is built but before it is MAC'd, the string CRYPTOPP_DUMMY_DLL_MAC
106 //! is used as a placeholder for the actual MAC. A post-build step is performed which calculates
107 //! the MAC of the DLL and embeds it in the module. The actual MAC is written by the
108 //! <tt>cryptest.exe</tt> program using the <tt>mac_dll</tt> subcommand.
109 #define CRYPTOPP_DUMMY_DLL_MAC "MAC_51f34b8db820ae8"
110 
111 NAMESPACE_END
112 
113 #endif
Base class for all exceptions thrown by the library.
Definition: cryptlib.h:139
The self tests were executed via DoPowerUpSelfTest() or DoDllPowerUpSelfTest(), and the result was su...
Definition: fips140.h:47
Interface for message authentication codes.
Definition: cryptlib.h:1107
Interface for public-key signers.
Definition: cryptlib.h:2534
Interface for public-key encryptors.
Definition: cryptlib.h:2342
Abstract base classes that provide a uniform interface to this library.
The self tests were executed via DoPowerUpSelfTest() or DoDllPowerUpSelfTest(), but the result was fa...
Definition: fips140.h:44
SecBlock typedef.
Definition: secblock.h:734
bool IntegrityCheckModule(const char *moduleFilename, const byte *expectedModuleMac, SecByteBlock *pActualMac=NULL, unsigned long *pMacFileLocation=NULL)
Verifies the MAC on the module.
Definition: fipstest.cpp:273
Classes and functions for secure memory allocations.
bool FIPS_140_2_ComplianceEnabled()
Determines whether the library provides FIPS validated cryptography.
Definition: fips140.cpp:29
Interface for public-key decryptors.
Definition: cryptlib.h:2378
Exception thrown when a crypto algorithm is used after a self test fails.
Definition: fips140.h:23
MessageAuthenticationCode * NewIntegrityCheckingMAC()
Class object that calculates the MAC on the module.
Definition: fipstest.cpp:267
void SimulatePowerUpSelfTestFailure()
Sets the power-up self test status to POWER_UP_SELF_TEST_FAILED.
Definition: fips140.cpp:34
void DoDllPowerUpSelfTest()
Performs the power-up self test on the DLL.
Definition: fipstest.cpp:595
PowerUpSelfTestStatus GetPowerUpSelfTestStatus()
Provides the current power-up self test status.
Definition: fips140.cpp:39
The self tests have not been performed.
Definition: fips140.h:41
Interface for public-key signature verifiers.
Definition: cryptlib.h:2601
void DoPowerUpSelfTest(const char *moduleFilename, const byte *expectedModuleMac)
Performs the power-up self test.
Definition: fipstest.cpp:442
PowerUpSelfTestStatus
Status of the power-up self test.
Definition: fips140.h:38
Crypto++ library namespace.