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.

## 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.
CRYPTOPP_DLL void | DoPowerUpSelfTest (const char *moduleFilename, const byte *expectedModuleMac)
| Performs the power-up self test.
CRYPTOPP_DLL void | DoDllPowerUpSelfTest ()
| Performs the power-up self test on the DLL.
CRYPTOPP_DLL void | SimulatePowerUpSelfTestFailure ()
| Sets the power-up self test status to POWER_UP_SELF_TEST_FAILED.
CRYPTOPP_DLL PowerUpSelfTestStatus | GetPowerUpSelfTestStatus ()
| Provides the current power-up self test status.
CRYPTOPP_DLL MessageAuthenticationCode * | NewIntegrityCheckingMAC ()
| Class object that calculates the MAC on the module.
CRYPTOPP_DLL bool | IntegrityCheckModule (const char *moduleFilename, const byte *expectedModuleMac, SecByteBlock *pActualMac=NULL, unsigned long *pMacFileLocation=NULL)
| Verifies the MAC on the module.

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

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

  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 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

  moduleFilename | the fully qualified name of the module
  expectedModuleMac | the expected MAC of the components protected by the integrity check
  pActualMac | the actual MAC of the components calculated by the integrity check
  pMacFileLocation | the offset of the MAC in the PE/PE+ module

Returns
  true if the MAC is valid, false otherwise