Crypto++ 8.7
Free C++ class library of cryptographic schemes
Classes | Macros | Enumerations | Functions
fips140.h File Reference

Classes and functions for the FIPS 140-2 validated library. More...

Go to the source code of this file.

Classes

class  SelfTestFailure
 Exception thrown when a crypto algorithm is used after a self test fails. More...
 

Macros

#define CRYPTOPP_DUMMY_DLL_MAC   "MAC_51f34b8db820ae8"
 The placeholder used prior to embedding the actual MAC in the module. More...
 

Enumerations

enum  PowerUpSelfTestStatus { POWER_UP_SELF_TEST_NOT_DONE , POWER_UP_SELF_TEST_FAILED , POWER_UP_SELF_TEST_PASSED }
 Status of the power-up self test. More...
 

Functions

CRYPTOPP_DLL bool FIPS_140_2_ComplianceEnabled ()
 Determines whether the library provides FIPS validated cryptography. More...
 
CRYPTOPP_DLL void DoPowerUpSelfTest (const char *moduleFilename, const byte *expectedModuleMac)
 Performs the power-up self test. More...
 
CRYPTOPP_DLL void DoDllPowerUpSelfTest ()
 Performs the power-up self test on the DLL. More...
 
CRYPTOPP_DLL void SimulatePowerUpSelfTestFailure ()
 Sets the power-up self test status to POWER_UP_SELF_TEST_FAILED. More...
 
CRYPTOPP_DLL PowerUpSelfTestStatus GetPowerUpSelfTestStatus ()
 Provides the current power-up self test status. More...
 
CRYPTOPP_DLL MessageAuthenticationCodeNewIntegrityCheckingMAC ()
 Class object that calculates the MAC on the module. More...
 
CRYPTOPP_DLL bool IntegrityCheckModule (const char *moduleFilename, const byte *expectedModuleMac, SecByteBlock *pActualMac=NULL, unsigned long *pMacFileLocation=NULL)
 Verifies the MAC on the module. More...
 

Detailed Description

Classes and functions for the FIPS 140-2 validated library.

The FIPS validated library is only available on Windows as a DLL. Once compiled, the library is always in FIPS mode contingent upon successful execution of DoPowerUpSelfTest() or DoDllPowerUpSelfTest().

See also
Visual Studio and config.h on the Crypto++ wiki.

Definition in file fips140.h.

Macro Definition Documentation

◆ CRYPTOPP_DUMMY_DLL_MAC

#define CRYPTOPP_DUMMY_DLL_MAC   "MAC_51f34b8db820ae8"

The placeholder used prior to embedding the actual MAC in the module.

After the DLL is built but before it is MAC'd, the string CRYPTOPP_DUMMY_DLL_MAC is used as a placeholder for the actual MAC. A post-build step is performed which calculates the MAC of the DLL and embeds it in the module. The actual MAC is written by the cryptest.exe program using the mac_dll subcommand.

Definition at line 108 of file fips140.h.

Enumeration Type Documentation

◆ PowerUpSelfTestStatus

Status of the power-up self test.

Enumerator
POWER_UP_SELF_TEST_NOT_DONE 

The self tests have not been performed.

POWER_UP_SELF_TEST_FAILED 

The self tests were executed via DoPowerUpSelfTest() or DoDllPowerUpSelfTest(), but the result was failure.

POWER_UP_SELF_TEST_PASSED 

The self tests were executed via DoPowerUpSelfTest() or DoDllPowerUpSelfTest(), and the result was success.

Definition at line 37 of file fips140.h.

Function Documentation

◆ FIPS_140_2_ComplianceEnabled()

CRYPTOPP_DLL bool FIPS_140_2_ComplianceEnabled ( )

Determines whether the library provides FIPS validated cryptography.

Returns
true if FIPS 140-2 validated features were enabled at compile time.

true if FIPS 140-2 validated features were enabled at compile time, false otherwise.

Note
FIPS mode is enabled at compile time. A program or other module cannot arbitrarily enter or exit the mode.

◆ DoPowerUpSelfTest()

CRYPTOPP_DLL void DoPowerUpSelfTest ( const char *  moduleFilename,
const byte expectedModuleMac 
)

Performs the power-up self test.

Parameters
moduleFilenamethe fully qualified name of the module
expectedModuleMacthe expected MAC of the components protected by the integrity check

Performs the power-up self test, and sets the self test status to POWER_UP_SELF_TEST_PASSED or POWER_UP_SELF_TEST_FAILED.

The self tests for an algorithm are performed by the Algorithm class when CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 is defined.

◆ DoDllPowerUpSelfTest()

CRYPTOPP_DLL void DoDllPowerUpSelfTest ( )

Performs the power-up self test on the DLL.

Performs the power-up self test using the filename of this DLL and the embedded module MAC, and sets the self test status to POWER_UP_SELF_TEST_PASSED or POWER_UP_SELF_TEST_FAILED.

The self tests for an algorithm are performed by the Algorithm class when CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 is defined.

◆ SimulatePowerUpSelfTestFailure()

CRYPTOPP_DLL void SimulatePowerUpSelfTestFailure ( )

Sets the power-up self test status to POWER_UP_SELF_TEST_FAILED.

Sets the power-up self test status to POWER_UP_SELF_TEST_FAILED to simulate failure.

◆ GetPowerUpSelfTestStatus()

CRYPTOPP_DLL PowerUpSelfTestStatus GetPowerUpSelfTestStatus ( )

Provides the current power-up self test status.

Returns
the current power-up self test status

◆ NewIntegrityCheckingMAC()

CRYPTOPP_DLL MessageAuthenticationCode * NewIntegrityCheckingMAC ( )

Class object that calculates the MAC on the module.

Returns
the MAC for the module

◆ IntegrityCheckModule()

CRYPTOPP_DLL bool IntegrityCheckModule ( const char *  moduleFilename,
const byte expectedModuleMac,
SecByteBlock pActualMac = NULL,
unsigned long *  pMacFileLocation = NULL 
)

Verifies the MAC on the module.

Parameters
moduleFilenamethe fully qualified name of the module
expectedModuleMacthe expected MAC of the components protected by the integrity check
pActualMacthe actual MAC of the components calculated by the integrity check
pMacFileLocationthe offset of the MAC in the PE/PE+ module
Returns
true if the MAC is valid, false otherwise