iqr_fips140.h File Reference

ISARA Radiate Security Solution Suite's FIPS 140-2 support. More...

Enumerations
enum	iqr_FIPS140State {   IQR_FIPS140_DISABLED = 0,   IQR_FIPS140_ENABLED = 1 }

Functions
IQR_API iqr_retval	iqr_FIPS140GetState (iqr_FIPS140State *state)
IQR_API iqr_retval	iqr_FIPS140SetState (iqr_FIPS140State state)
IQR_API iqr_retval	iqr_FIPS140RNGTest (iqr_Context *ctx)
IQR_API iqr_retval	iqr_FIPS140HashTest (iqr_Context *ctx, iqr_HashAlgorithmType algo)
IQR_API iqr_retval	iqr_FIPS140HMACTest (iqr_Context *ctx, iqr_HashAlgorithmType algo)
IQR_API iqr_retval	iqr_FIPS140HMACDRBGTest (iqr_Context *ctx, iqr_HashAlgorithmType algo)
IQR_API iqr_retval	iqr_FIPS140SHAKETest (iqr_Context *ctx, size_t size)
IQR_API iqr_retval	iqr_FIPS140ConcatenationKDFTest (iqr_Context *ctx, iqr_HashAlgorithmType algo)
IQR_API iqr_retval	iqr_FIPS140ECDHTest (iqr_Context *ctx, const iqr_ECDHCurve *curve)

Enumeration Type Documentation

iqr_FIPS140State

enum iqr_FIPS140State

FIPS 140-2 modes.

IQR_FIPS140_DISABLED is the only supported value unless you're using a FIPS 140-2 version of the toolkit.

Enumerator
IQR_FIPS140_DISABLED	FIPS 140-2 support is disabled.
IQR_FIPS140_ENABLED	FIPS 140-2 support is enabled.

Function Documentation

iqr_FIPS140ConcatenationKDFTest()

IQR_API iqr_retval iqr_FIPS140ConcatenationKDFTest	(	iqr_Context *	ctx,
		iqr_HashAlgorithmType	algo
	)

On-demand known-answer test for Approved Concatenation KDFs.

Runs a known-answer test for Concatenation KDF with the given hash algorithm to ensure that it's functioning correctly.

Parameters

[in]	ctx	An iqr_Context object. The hash algorithm must have been registered with iqr_HashRegisterCallbacks().
[in]	algo	The hash algorithm to test.

Returns

IQR_OK for success, or IQR_EFIPS140_FAILED. Other values from iqr_retval.h are possible depending on the nature of the failures.

iqr_FIPS140ECDHTest()

IQR_API iqr_retval iqr_FIPS140ECDHTest	(	iqr_Context *	ctx,
		const iqr_ECDHCurve *	curve
	)

On-demand known-answer test for Approved ECDH curves.

Runs a known-answer test for the given ECDH curve to ensure that it's functioning correctly.

Parameters

[in]	ctx	An iqr_Context object.
[in]	curve	An Approved ECDH curve (NIST P-256, P-384, or P-521).

Returns

IQR_OK for success, or IQR_EFIPS140_FAILED. Other values from iqr_retval.h are possible depending on the nature of the failures.

iqr_FIPS140GetState()

IQR_API iqr_retval iqr_FIPS140GetState

(

iqr_FIPS140State *

state

)

Get the current FIPS 140-2 state.

Immediately after loading the toolkit, this will return IQR_FIPS140_DISABLED if the library doesn't support FIPS 140-2 mode. If the library does support FIPS 140-2 mode, this function returns IQR_FIPS140_ENABLED.

Otherwise, this function returns the current FIPS 140-2 mode, as set with the iqr_FIPS140SetState() function.

Parameters

[out]

state

The current FIPS 140-2 state of the library.

Returns

IQR_OK for success, or IQR_EFIPS140_FAILED if the FIPS 140-2 self-tests failed.

iqr_FIPS140HashTest()

IQR_API iqr_retval iqr_FIPS140HashTest	(	iqr_Context *	ctx,
		iqr_HashAlgorithmType	algo
	)

On-demand known-answer test for Approved hashes.

Runs a known-answer test for the given hash to ensure that it's functioning correctly.

Parameters

[in]	ctx	An iqr_Context object. The hash algorithm must have been registered with iqr_HashRegisterCallbacks().
[in]	algo	The hash algorithm to test.

Returns

IQR_OK for success, or IQR_EFIPS140_FAILED. Other values from iqr_retval.h are possible depending on the nature of the failures.

iqr_FIPS140HMACDRBGTest()

IQR_API iqr_retval iqr_FIPS140HMACDRBGTest	(	iqr_Context *	ctx,
		iqr_HashAlgorithmType	algo
	)

On-demand known-answer test for Approved HMAC-DRBGs.

Runs a known-answer test for HMAC-DRBG with the given hash algorithm to ensure that it's functioning correctly.

Parameters

[in]	ctx	An iqr_Context object. The hash algorithm must have been registered with iqr_HashRegisterCallbacks().
[in]	algo	The hash algorithm to test.

Returns

IQR_OK for success, or IQR_EFIPS140_FAILED. Other values from iqr_retval.h are possible depending on the nature of the failures.

iqr_FIPS140HMACTest()

IQR_API iqr_retval iqr_FIPS140HMACTest	(	iqr_Context *	ctx,
		iqr_HashAlgorithmType	algo
	)

On-demand known-answer test for Approved HMACs.

Runs a known-answer test for HMAC with the given hash algorithm to ensure that it's functioning correctly.

Parameters

[in]	ctx	An iqr_Context object. The hash algorithm must have been registered with iqr_HashRegisterCallbacks().
[in]	algo	The hash algorithm to test.

Returns

IQR_OK for success, or IQR_EFIPS140_FAILED. Other values from iqr_retval.h are possible depending on the nature of the failures.

iqr_FIPS140RNGTest()

IQR_API iqr_retval iqr_FIPS140RNGTest

(

iqr_Context *

ctx

)

On-demand generation/reseed test for Approved RNGs.

Runs HMAC-DRBG and SHAKE known-answer tests to ensure that byte generation and reseed operations are functioning as expected.

Parameters

[in]

ctx

An iqr_Context object. The SHA2-256, SHA2-384, SHA2-512, SHA3-256, and SHA3-512 hash implementations must have been registered with iqr_HashRegisterCallbacks().

Returns

IQR_OK for success, or IQR_EFIPS140_FAILED. Other values from iqr_retval.h are also possible depending on the nature of the failures.

iqr_FIPS140SetState()

IQR_API iqr_retval iqr_FIPS140SetState

(

iqr_FIPS140State

state

)

Set the current FIPS 140-2 state.

Switching from IQR_FIPS140_DISABLED to IQR_FIPS140_ENABLED mode triggers the library's FIPS 140-2 self-tests.

Parameters

[in]

state

The desired FIPS 140-2 state of the library.

Returns

IQR_OK for success, IQR_EFIPS140_FAILED if the FIPS 140-2 self-tests failed, or IQR_EFIPS140_NOTAVAIL if FIPS 140-2 mode is not available in this library.

iqr_FIPS140SHAKETest()

IQR_API iqr_retval iqr_FIPS140SHAKETest	(	iqr_Context *	ctx,
		size_t	size
	)

On-demand known-answer test for Approved SHAKE XOFs.

Runs a known-answer test for SHAKE with the given size to ensure that it's functioning correctly.

Parameters

[in]	ctx	An iqr_Context object.
[in]	size	The SHAKE size to test.

Returns

IQR_OK for success, or IQR_EFIPS140_FAILED. Other values from iqr_retval.h are possible depending on the nature of the failures.

Detailed Description

ISARA Radiate Security Solution Suite's FIPS 140-2 support.

The toolkit is being certified for Level 1 of FIPS 140-2 Security Requirements for Cryptographic Modules. If your toolkit has been compiled with FIPS 140-2 support, two modes are available:

• IQR_FIPS140_DISABLED
• IQR_FIPS140_ENABLED

These FIPS 140-2 Approved functions are present in our toolkit:

• SHA2-256, SHA2-384, SHA2-512, SHA3-256, and SHA3-512
• SHAKE128, and SHAKE256
• HMAC with SHA2-256, SHA2-384, SHA2-512, SHA3-256, or SHA3-512
• HMAC-DRBG with SHA2-256, SHA2-384, SHA2-512, SHA3-256, or SHA3-512
• ECDH with the NIST curves (NIST P-256, NIST P-384, NIST P-521)

The IQR_FIPS140_ENABLED mode adds some additional behaviour to the toolkit:

• On library load, a code integrity test and various operational tests are performed. These tests are also performed when switching from IQR_FIPS140_DISABLED to IQR_FIPS140_ENABLED mode.
• ECDH key pairs will perform a self test during generation.
• ECDH keys generated in FIPS 140-2 mode cannot be used when FIPS 140-2 mode is disabled. ECDH keys generated when FIPS 140-2 mode is disabled cannot be used when in FIPS 140-2 mode.
• Code stripping will be unable to strip unused hash implementations due to the random number generator on-demand tests and operational tests.

If the FIPS 140-2 tests fail, Approved functions will return an error; non-Approved functions will still operate. Note that many non-Approved functions depend on Approved functions (for example, HSS is useless if SHA2-256 is broken).

For the library integrity tests to succeed, you must set the following environment variables:

• ISARA_FIPS140_KEY - Full path to the lib_iqrtoolkit.key file shipped with your ISARA Radiate toolkit shared library.
• ISARA_FIPS140_TAG - Full path to the lib_iqrtoolkit.tag file shipped with your ISARA Radiate toolkit shared library.

These files must be read-only regular files.

Copyright

Copyright 2017-2018, ISARA Corporation, All Rights Reserved.

License

The code and other content set out herein is not in the public domain, is considered a trade secret and is confidential to ISARA Corporation. Use, reproduction or distribution, in whole or in part, of such code or other content is strictly prohibited except by express written permission of ISARA Corporation. Please contact ISARA Corporation at info@.nosp@m.isar.nosp@m.a.com for more information.