Crypto++  8.6
Free C++ class library of cryptographic schemes
fips140.h
Go to the documentation of this file.
1 // fips140.h - originally 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 /// Exception thrown when a crypto algorithm is used after a self test fails
20 /// \details The self tests for an algorithm are performed by Algorithm class
21 /// when CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 is defined.
22 class CRYPTOPP_DLL SelfTestFailure : public Exception
23 {
24 public:
25  explicit SelfTestFailure(const std::string &s) : Exception(OTHER_ERROR, s) {}
26 };
27 
28 /// \brief Determines whether the library provides FIPS validated cryptography
29 /// \return true if FIPS 140-2 validated features were enabled at compile time.
30 /// \details true if FIPS 140-2 validated features were enabled at compile time,
31 /// false otherwise.
32 /// \note FIPS mode is enabled at compile time. A program or other module cannot
33 /// arbitrarily enter or exit the mode.
34 CRYPTOPP_DLL bool CRYPTOPP_API FIPS_140_2_ComplianceEnabled();
35 
36 /// \brief Status of the power-up self test
38 
39  /// \brief The self tests have not been performed.
41  /// \brief The self tests were executed via DoPowerUpSelfTest() or
42  /// DoDllPowerUpSelfTest(), but the result was failure.
44  /// \brief The self tests were executed via DoPowerUpSelfTest() or
45  /// DoDllPowerUpSelfTest(), and the result was success.
47 };
48 
49 /// \brief Performs the power-up self test
50 /// \param moduleFilename the fully qualified name of the module
51 /// \param expectedModuleMac the expected MAC of the components protected by the integrity check
52 /// \details Performs the power-up self test, and sets the self test status to
53 /// POWER_UP_SELF_TEST_PASSED or POWER_UP_SELF_TEST_FAILED.
54 /// \details The self tests for an algorithm are performed by the Algorithm class
55 /// when CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 is defined.
56 CRYPTOPP_DLL void CRYPTOPP_API DoPowerUpSelfTest(const char *moduleFilename, const byte *expectedModuleMac);
57 
58 /// \brief Performs the power-up self test on the DLL
59 /// \details Performs the power-up self test using the filename of this DLL and the
60 /// embedded module MAC, and sets the self test status to POWER_UP_SELF_TEST_PASSED or
61 /// POWER_UP_SELF_TEST_FAILED.
62 /// \details The self tests for an algorithm are performed by the Algorithm class
63 /// when CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 is defined.
64 CRYPTOPP_DLL void CRYPTOPP_API DoDllPowerUpSelfTest();
65 
66 /// \brief Sets the power-up self test status to POWER_UP_SELF_TEST_FAILED
67 /// \details Sets the power-up self test status to POWER_UP_SELF_TEST_FAILED to simulate failure.
69 
70 /// \brief Provides the current power-up self test status
71 /// \return the current power-up self test status
73 
74 #ifndef CRYPTOPP_DOXYGEN_PROCESSING
75 typedef PowerUpSelfTestStatus (CRYPTOPP_API * PGetPowerUpSelfTestStatus)();
76 #endif
77 
78 /// \brief Class object that calculates the MAC on the module
79 /// \return the MAC for the module
81 
82 /// \brief Verifies the MAC on the module
83 /// \param moduleFilename the fully qualified name of the module
84 /// \param expectedModuleMac the expected MAC of the components protected by the integrity check
85 /// \param pActualMac the actual MAC of the components calculated by the integrity check
86 /// \param pMacFileLocation the offset of the MAC in the PE/PE+ module
87 /// \return true if the MAC is valid, false otherwise
88 CRYPTOPP_DLL bool CRYPTOPP_API IntegrityCheckModule(const char *moduleFilename, const byte *expectedModuleMac, SecByteBlock *pActualMac = NULLPTR, unsigned long *pMacFileLocation = NULLPTR);
89 
90 #ifndef CRYPTOPP_DOXYGEN_PROCESSING
91 // this is used by Algorithm constructor to allow Algorithm objects to be constructed for the self test
92 bool PowerUpSelfTestInProgressOnThisThread();
93 
94 void SetPowerUpSelfTestInProgressOnThisThread(bool inProgress);
95 
96 void SignaturePairwiseConsistencyTest(const PK_Signer &signer, const PK_Verifier &verifier);
97 void EncryptionPairwiseConsistencyTest(const PK_Encryptor &encryptor, const PK_Decryptor &decryptor);
98 
99 void SignaturePairwiseConsistencyTest_FIPS_140_Only(const PK_Signer &signer, const PK_Verifier &verifier);
100 void EncryptionPairwiseConsistencyTest_FIPS_140_Only(const PK_Encryptor &encryptor, const PK_Decryptor &decryptor);
101 #endif
102 
103 /// \brief The placeholder used prior to embedding the actual MAC in the module.
104 /// \details After the DLL is built but before it is MAC'd, the string CRYPTOPP_DUMMY_DLL_MAC
105 /// is used as a placeholder for the actual MAC. A post-build step is performed which calculates
106 /// the MAC of the DLL and embeds it in the module. The actual MAC is written by the
107 /// <tt>cryptest.exe</tt> program using the <tt>mac_dll</tt> subcommand.
108 #define CRYPTOPP_DUMMY_DLL_MAC "MAC_51f34b8db820ae8"
109 
110 NAMESPACE_END
111 
112 #endif
PK_Encryptor
Interface for public-key encryptors.
Definition: cryptlib.h:2697
secblock.h
Classes and functions for secure memory allocations.
SecByteBlock
SecBlock<byte> typedef.
Definition: secblock.h:1226
PK_Decryptor
Interface for public-key decryptors.
Definition: cryptlib.h:2732
SimulatePowerUpSelfTestFailure
CRYPTOPP_DLL void SimulatePowerUpSelfTestFailure()
Sets the power-up self test status to POWER_UP_SELF_TEST_FAILED.
IntegrityCheckModule
CRYPTOPP_DLL bool IntegrityCheckModule(const char *moduleFilename, const byte *expectedModuleMac, SecByteBlock *pActualMac=NULL, unsigned long *pMacFileLocation=NULL)
Verifies the MAC on the module.
PK_Signer
Interface for public-key signers.
Definition: cryptlib.h:2876
DoDllPowerUpSelfTest
CRYPTOPP_DLL void DoDllPowerUpSelfTest()
Performs the power-up self test on the DLL.
Exception
Base class for all exceptions thrown by the library.
Definition: cryptlib.h:158
DoPowerUpSelfTest
CRYPTOPP_DLL void DoPowerUpSelfTest(const char *moduleFilename, const byte *expectedModuleMac)
Performs the power-up self test.
NewIntegrityCheckingMAC
CRYPTOPP_DLL MessageAuthenticationCode * NewIntegrityCheckingMAC()
Class object that calculates the MAC on the module.
POWER_UP_SELF_TEST_FAILED
@ POWER_UP_SELF_TEST_FAILED
The self tests were executed via DoPowerUpSelfTest() or DoDllPowerUpSelfTest(), but the result was fa...
Definition: fips140.h:43
PowerUpSelfTestStatus
PowerUpSelfTestStatus
Status of the power-up self test.
Definition: fips140.h:37
GetPowerUpSelfTestStatus
CRYPTOPP_DLL PowerUpSelfTestStatus GetPowerUpSelfTestStatus()
Provides the current power-up self test status.
FIPS_140_2_ComplianceEnabled
CRYPTOPP_DLL bool FIPS_140_2_ComplianceEnabled()
Determines whether the library provides FIPS validated cryptography.
PK_Verifier
Interface for public-key signature verifiers.
Definition: cryptlib.h:2940
CryptoPP
Crypto++ library namespace.
CRYPTOPP_API
#define CRYPTOPP_API
Win32 calling convention.
Definition: config_dll.h:119
POWER_UP_SELF_TEST_NOT_DONE
@ POWER_UP_SELF_TEST_NOT_DONE
The self tests have not been performed.
Definition: fips140.h:40
MessageAuthenticationCode
Interface for message authentication codes.
Definition: cryptlib.h:1298
POWER_UP_SELF_TEST_PASSED
@ POWER_UP_SELF_TEST_PASSED
The self tests were executed via DoPowerUpSelfTest() or DoDllPowerUpSelfTest(), and the result was su...
Definition: fips140.h:46
cryptlib.h
Abstract base classes that provide a uniform interface to this library.
SelfTestFailure
Exception thrown when a crypto algorithm is used after a self test fails.
Definition: fips140.h:22