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

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
bool	FIPS_140_2_ComplianceEnabled ()
	Determines whether the library provides FIPS validated cryptography. More...

void	DoPowerUpSelfTest (const char moduleFilename, const byte expectedModuleMac)
	Performs the power-up self test. More...

void	DoDllPowerUpSelfTest ()
	Performs the power-up self test on the DLL. More...

void	SimulatePowerUpSelfTestFailure ()
	Sets the power-up self test status to POWER_UP_SELF_TEST_FAILED. More...

PowerUpSelfTestStatus	GetPowerUpSelfTestStatus ()
	Provides the current power-up self test status. More...

MessageAuthenticationCode *	NewIntegrityCheckingMAC ()
	Class object that calculates the MAC on the module. More...

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

enum 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()

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.

Definition at line 24 of file fips140.cpp.

◆ DoPowerUpSelfTest()

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

Performs the power-up self test.

Parameters

moduleFilename	the fully qualified name of the module
expectedModuleMac	the 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 Algortihm class when CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 is defined.

◆ DoDllPowerUpSelfTest()

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 Algortihm class when CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 is defined.

◆ SimulatePowerUpSelfTestFailure()

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.

Definition at line 29 of file fips140.cpp.

◆ GetPowerUpSelfTestStatus()

PowerUpSelfTestStatus GetPowerUpSelfTestStatus ( )

Provides the current power-up self test status.

Returns: the current power-up self test status

Definition at line 34 of file fips140.cpp.

◆ NewIntegrityCheckingMAC()

MessageAuthenticationCode* NewIntegrityCheckingMAC ( )

Class object that calculates the MAC on the module.

Returns: the MAC for the module

◆ IntegrityCheckModule()

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

Verifies the MAC on the module.