Coverage Report

Created: 2024-11-21 07:03

/src/cryptopp/fips140.h
Line
Count
Source (jump to first uncovered line)
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
0
  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