Crypto++ 8.9 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
37 enum PowerUpSelfTestStatus {
38
39 /// \brief The self tests have not been performed.
40 POWER_UP_SELF_TEST_NOT_DONE,
41 /// \brief The self tests were executed via DoPowerUpSelfTest() or
42 /// DoDllPowerUpSelfTest(), but the result was failure.
43 POWER_UP_SELF_TEST_FAILED,
44 /// \brief The self tests were executed via DoPowerUpSelfTest() or
45 /// DoDllPowerUpSelfTest(), and the result was success.
46 POWER_UP_SELF_TEST_PASSED
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.
68 CRYPTOPP_DLL void CRYPTOPP_API SimulatePowerUpSelfTestFailure();
69
70 /// \brief Provides the current power-up self test status
71 /// \return the current power-up self test status
72 CRYPTOPP_DLL PowerUpSelfTestStatus CRYPTOPP_API GetPowerUpSelfTestStatus();
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
80 CRYPTOPP_DLL MessageAuthenticationCode * CRYPTOPP_API NewIntegrityCheckingMAC();
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
Exception
Base class for all exceptions thrown by the library.
Definition: cryptlib.h:164
MessageAuthenticationCode
Interface for message authentication codes.
Definition: cryptlib.h:1304
PK_Decryptor
Interface for public-key decryptors.
Definition: cryptlib.h:2738
PK_Encryptor
Interface for public-key encryptors.
Definition: cryptlib.h:2703
PK_Signer
Interface for public-key signers.
Definition: cryptlib.h:2882
PK_Verifier
Interface for public-key signature verifiers.
Definition: cryptlib.h:2946
SecByteBlock
SecBlock<byte> typedef.
Definition: secblock.h:1226
SelfTestFailure
Exception thrown when a crypto algorithm is used after a self test fails.
Definition: fips140.h:23
CRYPTOPP_API
#define CRYPTOPP_API
Win32 calling convention.
Definition: config_dll.h:119
cryptlib.h
Abstract base classes that provide a uniform interface to this library.
FIPS_140_2_ComplianceEnabled
CRYPTOPP_DLL bool FIPS_140_2_ComplianceEnabled()
Determines whether the library provides FIPS validated cryptography.
GetPowerUpSelfTestStatus
CRYPTOPP_DLL PowerUpSelfTestStatus GetPowerUpSelfTestStatus()
Provides the current power-up self test status.
IntegrityCheckModule
CRYPTOPP_DLL bool IntegrityCheckModule(const char *moduleFilename, const byte *expectedModuleMac, SecByteBlock *pActualMac=NULL, unsigned long *pMacFileLocation=NULL)
Verifies the MAC on the module.
PowerUpSelfTestStatus
PowerUpSelfTestStatus
Status of the power-up self test.
Definition: fips140.h:37
POWER_UP_SELF_TEST_NOT_DONE
@ POWER_UP_SELF_TEST_NOT_DONE
The self tests have not been performed.
Definition: fips140.h:40
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
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
NewIntegrityCheckingMAC
CRYPTOPP_DLL MessageAuthenticationCode * NewIntegrityCheckingMAC()
Class object that calculates the MAC on the module.
DoPowerUpSelfTest
CRYPTOPP_DLL void DoPowerUpSelfTest(const char *moduleFilename, const byte *expectedModuleMac)
Performs the power-up self test.
SimulatePowerUpSelfTestFailure
CRYPTOPP_DLL void SimulatePowerUpSelfTestFailure()
Sets the power-up self test status to POWER_UP_SELF_TEST_FAILED.
DoDllPowerUpSelfTest
CRYPTOPP_DLL void DoDllPowerUpSelfTest()
Performs the power-up self test on the DLL.
CryptoPP
Crypto++ library namespace.
secblock.h
Classes and functions for secure memory allocations.