sha256.h File Reference

SHA - Secure Hash Algorithm Header. More...

Go to the source code of this file.

Typedefs
typedef struct SW_SHA256_CTX	SHA256_CTX
typedef struct SW_SHA256_CTX	sha256Descr
typedef struct SW_SHA256_CTX	sha256DescrHS

Functions
MOC_EXTERN MSTATUS	SHA224_allocDigest (MOC_HASH(hwAccelDescr hwAccelCtx) BulkCtx *pp_shaContext)
	Allocate SHA224 operation context data structure. More...
MOC_EXTERN MSTATUS	SHA224_cloneCtx (MOC_HASH(hwAccelDescr hwAccelCtx) SHA224_CTX *pDest, SHA224_CTX *pSrc)
	Makes a clone of a previously allocated SHA224_CTX. More...
MOC_EXTERN MSTATUS	SHA224_completeDigest (MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte *pData, ubyte4 dataLen, ubyte *pShaOutput)
	Calculate single item's SHA224 digest value (with a single function call). More...
MOC_EXTERN MSTATUS	SHA224_finalDigest (MOC_HASH(hwAccelDescr hwAccelCtx) SHA224_CTX *pCtx, ubyte *pOutput)
	Calculate final SHA224 digest value. More...
MOC_EXTERN MSTATUS	SHA224_freeDigest (MOC_HASH(hwAccelDescr hwAccelCtx) BulkCtx *pp_shaContext)
	Free (delete) SHA224 operation context data structure. More...
MOC_EXTERN MSTATUS	SHA224_initDigest (MOC_HASH(hwAccelDescr hwAccelCtx) SHA224_CTX *pCtx)
	Initialize an SHA224 operation context data structure. More...
MOC_EXTERN MSTATUS	SHA224_updateDigest (MOC_HASH(hwAccelDescr hwAccelCtx) sha256Descr *pCtx, const ubyte *pData, ubyte4 dataLen)
	Calculate and update intermediate SHA224 digest value. More...
MOC_EXTERN MSTATUS	SHA256_allocDigest (MOC_HASH(hwAccelDescr hwAccelCtx) BulkCtx *pp_shaContext)
	Allocate SHA256 operation context data structure. More...
MOC_EXTERN MSTATUS	SHA256_cloneCtx (MOC_HASH(hwAccelDescr hwAccelCtx) SHA256_CTX *pDest, SHA256_CTX *pSrc)
	Makes a clone of a previously allocated SHA256_CTX. More...
MOC_EXTERN MSTATUS	SHA256_completeDigest (MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte *pData, ubyte4 dataLen, ubyte *pShaOutput)
	Calculate single item's SHA256 digest value (with a single function call). More...
MOC_EXTERN MSTATUS	SHA256_finalDigest (MOC_HASH(hwAccelDescr hwAccelCtx) sha256Descr *pCtx, ubyte *pOutput)
	Calculate final SHA256 digest value. More...
MOC_EXTERN MSTATUS	SHA256_freeDigest (MOC_HASH(hwAccelDescr hwAccelCtx) BulkCtx *pp_shaContext)
	Free (delete) SHA256 operation context data structure. More...
MOC_EXTERN MSTATUS	SHA256_initDigest (MOC_HASH(hwAccelDescr hwAccelCtx) sha256Descr *pCtx)
	Initialize SHA256 operation context data structure. More...
MOC_EXTERN MSTATUS	SHA256_updateDigest (MOC_HASH(hwAccelDescr hwAccelCtx) sha256Descr *pCtx, const ubyte *pData, ubyte4 dataLen)
	Calculate and update intermediate SHA256 digest value. More...

Detailed Description

Copyright 2019-2024 DigiCert, Inc. All Rights Reserved. Proprietary and Confidential Material.

Function Documentation

SHA224_allocDigest()

MOC_EXTERN MSTATUS SHA224_allocDigest

(

MOC_HASH(hwAccelDescr hwAccelCtx) BulkCtx *

pp_shaContext

)

This function allocates a context data structure for SHA224 operations.

Although applications can allocate the structure directly, it's recommended that this function be used to ensure future portability.

Note

If you need a SHA224 value for only a single message, it is more efficient to call the SHA224_completeDigest() function.

FIPS Approved
Suite B Algorithm
Flowchart	SHA224

To enable this function, the following flag must not be defined:

• __DISABLE_MOCANA_SHA224__

sha256.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pp_context	On return, pointer to allocated context data structure.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

sha256.h

SHA224_cloneCtx()

MOC_EXTERN MSTATUS SHA224_cloneCtx	(	MOC_HASH(hwAccelDescr hwAccelCtx) SHA224_CTX *	pDest,
		SHA224_CTX *	pSrc
	)

Makes a clone of a previously allocated SHA224_CTX.

sha256.h

Parameters

pDest	Pointer to an already allocated destination context.
pSrc	Pointer to the context to be copied.

Returns

OK (0) if successful, otherwise a negative number error code from merrors.h.

SHA224_completeDigest()

MOC_EXTERN MSTATUS SHA224_completeDigest	(	MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte *	pData,
		ubyte4	dataLen,
		ubyte *	pShaOutput
	)

This function calculates an SHA224 digest value for a single item.

Note

This function is the most efficient method to calculate the SHA224 value for a single message, saving both memory and time. However, if you need to calculate the SHA224 for two or more messages, you must use the "separate steps" methods, SHA224_allocDigest(), SHA224_initDigest(), SHA224_updateDigest(), SHA224_finalDigest(), and SHA224_freeDigest().

Warning

Before calling this function, be sure that the buffer pointed to by the pShaOutput parameter is large enough (at least SHA224_RESULT_SIZE(28) bytes); otherwise, buffer overflow will occur.

FIPS Approved
Suite B Algorithm
Flowchart	SHA224

To enable this function, the following flag must not be defined:

• __DISABLE_MOCANA_SHA224__

sha256.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pData	Pointer to data to hash or digest.
dataLen	Number of bytes of data to hash or digest (pData).
pShaOutput	On return, pointer to resultant SHA224 digest value. (The calling function must allocate sufficient memory — at least SHA224_RESULT_SIZE(28) bytes — for the pShaOutput; otherwise buffer overflow may occur.)

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

sha256.h

SHA224_finalDigest()

MOC_EXTERN MSTATUS SHA224_finalDigest	(	MOC_HASH(hwAccelDescr hwAccelCtx) SHA224_CTX *	pCtx,
		ubyte *	pOutput
	)

This function calculates the final SHA224 digest value. Applications must call this function after completing their calls to SHA224_updateDigest().

Note

If you need a SHA224 value for only a single message, it is more efficient to call the SHA224_completeDigest() function.

Warning

Before calling this function, be sure that the buffer pointed to by the pOutput parameter is large enough (at least SHA224_RESULT_SIZE(28) bytes); otherwise, buffer overflow will occur.

FIPS Approved
Suite B Algorithm
Flowchart	SHA224

To enable this function, the following flag must not be defined:

• __DISABLE_MOCANA_SHA224__

sha256.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pContext	Pointer to SHA224 context.
pOutput	On return, pointer to final SHA224 digest value. (The calling function must allocate sufficient memory — at least SHA224_RESULT_SIZE(28) bytes — for the resulting pOutput; otherwise buffer overflow will occur.)

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

sha256.h

SHA224_freeDigest()

MOC_EXTERN MSTATUS SHA224_freeDigest

(

MOC_HASH(hwAccelDescr hwAccelCtx) BulkCtx *

pp_shaContext

)

This function frees (deletes) an SHA224 operation context data structure.

Note

If you need a SHA224 value for only a single message, it is more efficient to call the SHA224_completeDigest() function.

The sha512.h header file defines SHA224_freeDigest as:

    #define SHA224_freeDigest SHA256_freeDigest

Therefore, when you call SHA224_freeDigest(), you are actually making a call to SHA256_freeDigest(). However, to keep your code more readable and unambiguous when working with SHA224, you should use SHA224_freeDigest(), not SHA256_freeDigest().

FIPS Approved
Suite B Algorithm
Flowchart	SHA224

To enable this function, the following flag must not be defined:

• __DISABLE_MOCANA_SHA224__

sha256.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pp_shaContext	Double pointer to context to free (delete). On return, value is NULL.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

sha256.h

SHA224_initDigest()

MOC_EXTERN MSTATUS SHA224_initDigest

(

MOC_HASH(hwAccelDescr hwAccelCtx) SHA224_CTX *

pCtx

)

This function initializes an SHA224 operation context data structure. Applications should call this function before beginning the hashing operation.

The sha256.h header file defines SHA224_initDigest as:

    #define SHA224_initDigest SHA256_initDigest

Therefore, when you call SHA224_initDigest(), you are actually making a call to SHA256_initDigest(). However, to keep your code more readable and unambiguous when working with SHA224, you should use SHA224_initDigest(), not SHA256_initDigest().

Warning

Be sure to check this function's return status. An unsuccessful return will cause subsequent SHA224 operations to fail.

Note

If you need a SHA224 value for only a single message, it is more efficient to call the SHA224_completeDigest() function.

Context pointers returned by the SHA224_allocDigest() function should be typecast to (shaDescr *) before calling this function.

FIPS Approved
Suite B Algorithm
Flowchart	SHA224

To enable this function, the following flag must not be defined:

• __DISABLE_MOCANA_SHA224__

sha256.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pContext	Pointer to SHA224 context to initialize.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

sha256.h

SHA224_updateDigest()

MOC_EXTERN MSTATUS SHA224_updateDigest	(	MOC_HASH(hwAccelDescr hwAccelCtx) sha256Descr *	pCtx,
		const ubyte *	pData,
		ubyte4	dataLen
	)

This function calculates an intermediate SHA224 digest value.

Applications can repeatedly call this function to calculate digests for different data items. Every time this function is called, the intermediate digest value is stored within the SHA224 context data structure.

Note

If you need a SHA224 value for only a single message, it is more efficient to call the SHA224_completeDigest() function.

FIPS Approved
Suite B Algorithm
Flowchart	SHA224

To enable this function, the following flag must not be defined:

• __DISABLE_MOCANA_SHA256__

sha256.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pContext	Pointer to SHA224 context.
pData	Pointer to data to be hashed or digested.
dataLen	Number of bytes of data to be hashed or digested (pData).

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

sha256.h

SHA256_allocDigest()

MOC_EXTERN MSTATUS SHA256_allocDigest

(

MOC_HASH(hwAccelDescr hwAccelCtx) BulkCtx *

pp_shaContext

)

This function allocates a context data structure for SHA256 operations.

Although applications can allocate the structure directly, it's recommended that this function be used to ensure future portability.

Note

If you need a SHA256 value for only a single message, it is more efficient to call the SHA256_completeDigest() function.

FIPS Approved
Suite B Algorithm
Flowchart	SHA256

To enable this function, the following flag must not be defined:

• __DISABLE_MOCANA_SHA256__

sha256.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing. But... what does the user specify? In the 5.3.1 docs, we just said that this was "Reserved for future use." Ditto this for all sha256.{c,h} functions.
pp_context	On return, pointer to allocated context data structure.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

sha256.h

SHA256_cloneCtx()

MOC_EXTERN MSTATUS SHA256_cloneCtx	(	MOC_HASH(hwAccelDescr hwAccelCtx) SHA256_CTX *	pDest,
		SHA256_CTX *	pSrc
	)

Makes a clone of a previously allocated SHA256_CTX.

sha256.h

Parameters

pDest	Pointer to an already allocated destination context.
pSrc	Pointer to the context to be copied.

Returns

OK (0) if successful, otherwise a negative number error code from merrors.h.

SHA256_completeDigest()

MOC_EXTERN MSTATUS SHA256_completeDigest	(	MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte *	pData,
		ubyte4	dataLen,
		ubyte *	pShaOutput
	)

This function calculates an SHA256 digest value for a single item.

Note

This function is the most efficient method to calculate the SHA256 value for a single message, saving both memory and time. However, if you need to calculate the SHA256 for two or more messages, you must use the "separate steps" methods, SHA256_allocDigest(), SHA256_initDigest(), SHA256_updateDigest(), SHA256_finalDigest(), and SHA256_freeDigest().

Warning

Before calling this function, be sure that the buffer pointed to by the pShaOutput parameter is large enough (at least SHA256_RESULT_SIZE(32) bytes); otherwise, buffer overflow will occur.

FIPS Approved
Suite B Algorithm
Flowchart	SHA256

To enable this function, the following flag must not be defined:

• __DISABLE_MOCANA_SHA256__

sha256.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pData	Pointer to data to hash or digest.
dataLen	Number of bytes of data to hash or digest (pData).
pShaOutput	On return, pointer to resultant SHA256 digest value. (The calling function must allocate sufficient memory — at least SHA256_RESULT_SIZE(32) bytes — for the pShaOutput; otherwise buffer overflow may occur.)

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

sha256.h

SHA256_finalDigest()

MOC_EXTERN MSTATUS SHA256_finalDigest	(	MOC_HASH(hwAccelDescr hwAccelCtx) sha256Descr *	pCtx,
		ubyte *	pOutput
	)

This function calculates the final SHA256 digest value. Applications must call this function after completing their calls to SHA256_updateDigest().

Note

If you need a SHA256 value for only a single message, it is more efficient to call the SHA256_completeDigest() function.

Warning

Before calling this function, be sure that the buffer pointed to by the pOutput parameter is large enough (at least SHA256_RESULT_SIZE(32) bytes); otherwise, buffer overflow will occur.

FIPS Approved
Suite B Algorithm
Flowchart	SHA256

To enable this function, the following flag must not be defined:

• __DISABLE_MOCANA_SHA256__

sha256.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pContext	Pointer to SHA256 context.
pOutput	On return, pointer to final SHA256 digest value. (The calling function must allocate sufficient memory — at least SHA256_RESULT_SIZE(32) bytes — for the resulting pOutput; otherwise buffer overflow will occur.)

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

sha256.h

SHA256_freeDigest()

MOC_EXTERN MSTATUS SHA256_freeDigest

(

MOC_HASH(hwAccelDescr hwAccelCtx) BulkCtx *

pp_shaContext

)

This function frees (deletes) an SHA256 operation context data structure.

Note

If you need a SHA256 value for only a single message, it is more efficient to call the SHA256_completeDigest() function.

FIPS Approved
Suite B Algorithm
Flowchart	SHA256

To enable this function, the following flag must not be defined:

• __DISABLE_MOCANA_SHA256__

sha256.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pp_context	Pointer to context to free (delete). On return, value is NULL.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

sha256.h

SHA256_initDigest()

MOC_EXTERN MSTATUS SHA256_initDigest

(

MOC_HASH(hwAccelDescr hwAccelCtx) sha256Descr *

pCtx

)

This function initializes an SHA256 context data structure. Applications should call this function before beginning the hashing operation.

Warning

Be sure to check this function's return status. An unsuccessful return will cause subsequent SHA256 operations to fail.

Note

If you need a SHA256 value for only a single message, it is more efficient to call the SHA256_completeDigest() function.

Before calling this function, typecast the context pointers returned by the SHA256_allocDigest() function to (shaDescr ).

FIPS Approved
Suite B Algorithm
Flowchart	SHA256

To enable this function, the following flag must not be defined:

• __DISABLE_MOCANA_SHA256__

sha256.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pContext	Pointer to SHA256 context to initialize.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

sha256.h

SHA256_updateDigest()

MOC_EXTERN MSTATUS SHA256_updateDigest	(	MOC_HASH(hwAccelDescr hwAccelCtx) sha256Descr *	pCtx,
		const ubyte *	pData,
		ubyte4	dataLen
	)

This function calculates an intermediate SHA256 digest value.

Applications can repeatedly call this function to calculate digests for different data items. Every time this function is called, the intermediate digest value is stored within the SHA256 context data structure.

Note

If you need a SHA256 value for only a single message, it is more efficient to call the SHA256_completeDigest() function.

FIPS Approved
Suite B Algorithm
Flowchart	SHA256

To enable this function, the following flag must not be defined:

• __DISABLE_MOCANA_SHA256__

sha256.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pContext	Pointer to SHA256 context.
pData	Pointer to data to be hashed or digested.
dataLen	Number of bytes of data to be hashed or digested (pData).

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

sha256.h