sha512.h File Reference

SHA512 - Secure Hash Algorithm Header. More...

Go to the source code of this file.

Typedefs
typedef SHA512_CTX	sha384Descr
typedef SHA512_CTX	sha512Descr

Functions
MOC_EXTERN MSTATUS	SHA384_allocDigest (MOC_HASH(hwAccelDescr hwAccelCtx) BulkCtx *pp_shaContext)
	Allocate SHA384 operation context data structure. More...
MOC_EXTERN MSTATUS	SHA384_cloneCtx (MOC_HASH(hwAccelDescr hwAccelCtx) SHA384_CTX *pDest, SHA384_CTX *pSrc)
	Makes a clone of a previously allocated SHA384_CTX. More...
MOC_EXTERN MSTATUS	SHA384_completeDigest (MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte *pData, ubyte4 dataLen, ubyte *pShaOutput)
	Calculate single item's SHA384 digest value (with a single function call). More...
MOC_EXTERN MSTATUS	SHA384_finalDigest (MOC_HASH(hwAccelDescr hwAccelCtx) SHA384_CTX *pCtx, ubyte *pOutput)
	Calculate final SHA384 digest value. More...
MOC_EXTERN MSTATUS	SHA384_freeDigest (MOC_HASH(hwAccelDescr hwAccelCtx) BulkCtx *pp_shaContext)
	Free (delete) SHA384 operation context data structure. More...
MOC_EXTERN MSTATUS	SHA384_initDigest (MOC_HASH(hwAccelDescr hwAccelCtx) SHA384_CTX *pCtx)
	Initialize SHA384 operation context data structure. More...
MOC_EXTERN MSTATUS	SHA384_updateDigest (MOC_HASH(hwAccelDescr hwAccelCtx) SHA512_CTX *pCtx, const ubyte *pData, ubyte4 dataLen)
	Calculate and update intermediate SHA384 digest value. More...
MOC_EXTERN MSTATUS	SHA512_allocDigest (MOC_HASH(hwAccelDescr hwAccelCtx) BulkCtx *pp_shaContext)
	Allocate SHA512 operation context data structure. More...
MOC_EXTERN MSTATUS	SHA512_cloneCtx (MOC_HASH(hwAccelDescr hwAccelCtx) SHA512_CTX *pDest, SHA512_CTX *pSrc)
	Makes a clone of a previously allocated SHA512_CTX. More...
MOC_EXTERN MSTATUS	SHA512_completeDigest (MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte *pData, ubyte4 dataLen, ubyte *pShaOutput)
	Calculate single item's SHA512 digest value (with a single function call). More...
MOC_EXTERN MSTATUS	SHA512_finalDigest (MOC_HASH(hwAccelDescr hwAccelCtx) SHA512_CTX *pCtx, ubyte *pOutput)
	Calculate final SHA512 digest value. More...
MOC_EXTERN MSTATUS	SHA512_freeDigest (MOC_HASH(hwAccelDescr hwAccelCtx) BulkCtx *pp_shaContext)
	Free (delete) SHA512 operation context data structure. More...
MOC_EXTERN MSTATUS	SHA512_initDigest (MOC_HASH(hwAccelDescr hwAccelCtx) SHA512_CTX *pCtx)
	Initialize SHA512 operation context data structure. More...
MOC_EXTERN MSTATUS	SHA512_updateDigest (MOC_HASH(hwAccelDescr hwAccelCtx) SHA512_CTX *pCtx, const ubyte *pData, ubyte4 dataLen)
	Calculate and update intermediate SHA512 digest value. More...

Detailed Description

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

Function Documentation

SHA384_allocDigest()

MOC_EXTERN MSTATUS SHA384_allocDigest

(

MOC_HASH(hwAccelDescr hwAccelCtx) BulkCtx *

pp_shaContext

)

This function allocates a context data structure for SHA384 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 SHA384 value for only a single message, it is more efficient to call the SHA384_completeDigest() function.

FIPS Approved
Suite B Algorithm
Flowchart	SHA384

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

• __DISABLE_MOCANA_SHA384__

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

sha512.h

SHA384_cloneCtx()

MOC_EXTERN MSTATUS SHA384_cloneCtx	(	MOC_HASH(hwAccelDescr hwAccelCtx) SHA384_CTX *	pDest,
		SHA384_CTX *	pSrc
	)

Makes a clone of a previously allocated SHA384_CTX.

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

SHA384_completeDigest()

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

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

Note

This function is the most efficient method to calculate the SHA384 value for a single message, saving both memory and time. However, if you need to calculate the SHA384 for two or more messages, you must use the "separate steps" methods, SHA384_allocDigest(), SHA384_initDigest(), SHA384_updateDigest(), SHA384_finalDigest(), and SHA384_freeDigest().

Warning

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

FIPS Approved
Suite B Algorithm
Flowchart	SHA384

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

• __DISABLE_MOCANA_SHA384__
• __SHA384_ONE_STEP_HARDWARE_HASH__

sha512.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 SHA384 digest value. (The calling function must allocate sufficient memory — at least SHA384_RESULT_SIZE(48) 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.

sha512.h

SHA384_finalDigest()

MOC_EXTERN MSTATUS SHA384_finalDigest	(	MOC_HASH(hwAccelDescr hwAccelCtx) SHA384_CTX *	pCtx,
		ubyte *	pOutput
	)

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

Note

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

FIPS Approved
Suite B Algorithm
Flowchart	SHA384

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

• __DISABLE_MOCANA_SHA384__

Warning

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

sha512.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 SHA384 context.
pOutput	On return, pointer to final SHA384 digest value. (The calling function must allocate sufficient memory — at least SHA384_RESULT_SIZE(48) 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.

sha512.h

SHA384_freeDigest()

MOC_EXTERN MSTATUS SHA384_freeDigest

(

MOC_HASH(hwAccelDescr hwAccelCtx) BulkCtx *

pp_shaContext

)

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

Note

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

The sha512.h header file defines SHA384_freeDigest as:

    #define SHA384_freeDigest SHA512_freeDigest

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

FIPS Approved
Suite B Algorithm
Flowchart	SHA384

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

• __DISABLE_MOCANA_SHA384__

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

sha512.h

SHA384_initDigest()

MOC_EXTERN MSTATUS SHA384_initDigest

(

MOC_HASH(hwAccelDescr hwAccelCtx) SHA384_CTX *

pCtx

)

This function initializes an SHA384 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 SHA384 operations to fail.

Note

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

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

FIPS Approved
Suite B Algorithm
Flowchart	SHA384

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

• __DISABLE_MOCANA_SHA384__

sha512.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 SHA384 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.

sha512.h

SHA384_updateDigest()

MOC_EXTERN MSTATUS SHA384_updateDigest	(	MOC_HASH(hwAccelDescr hwAccelCtx) SHA512_CTX *	pCtx,
		const ubyte *	pData,
		ubyte4	dataLen
	)

This function calculates an intermediate SHA384 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 SHA384 context data structure.

Note

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

FIPS Approved
Suite B Algorithm
Flowchart	SHA384

The sha512.h header file defines SHA384_updateDigest as:

    #define SHA384_updateDigest SHA512_updateDigest

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

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

• __DISABLE_MOCANA_SHA384__

sha512.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.
pCtx	Pointer to SHA384 context. How should this pCtx param be explained given that the function signature has it as a SHA512_CTX?
pData	Pointer to data to hash or digest.
dataLen	Number of bytes of data to hash or digest (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.

sha512.h

SHA512_allocDigest()

MOC_EXTERN MSTATUS SHA512_allocDigest

(

MOC_HASH(hwAccelDescr hwAccelCtx) BulkCtx *

pp_shaContext

)

This function allocates a context data structure for SHA512 operations.

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

Note

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

FIPS Approved
Suite B Algorithm
Flowchart	SHA512

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

• __DISABLE_MOCANA_SHA512__

sha512.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 sha512.{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.

sha512.h

SHA512_cloneCtx()

MOC_EXTERN MSTATUS SHA512_cloneCtx	(	MOC_HASH(hwAccelDescr hwAccelCtx) SHA512_CTX *	pDest,
		SHA512_CTX *	pSrc
	)

Makes a clone of a previously allocated SHA512_CTX.

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

SHA512_completeDigest()

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

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

Note

This function is the most efficient method to calculate the SHA512 value for a single message, saving both memory and time. However, if you need to calculate the SHA512 for two or more messages, you must use the "separate steps" methods, SHA512_allocDigest(), SHA512_initDigest(), SHA512_updateDigest(), SHA512_finalDigest(), and SHA512_freeDigest().

Warning

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

FIPS Approved
Suite B Algorithm
Flowchart	SHA512

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

• __DISABLE_MOCANA_SHA512__
• __SHA512_ONE_STEP_HARDWARE_HASH__

sha512.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 SHA512 digest value. (The calling function must allocate sufficient memory — at least SHA512_RESULT_SIZE(64) 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.

sha512.h

SHA512_finalDigest()

MOC_EXTERN MSTATUS SHA512_finalDigest	(	MOC_HASH(hwAccelDescr hwAccelCtx) SHA512_CTX *	pCtx,
		ubyte *	pOutput
	)

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

Note

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

FIPS Approved
Suite B Algorithm
Flowchart	SHA512

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

• __DISABLE_MOCANA_SHA512__

Warning

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

sha512.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 SHA512 context.
pOutput	On return, pointer to final SHA512 digest value. (The calling function must allocate sufficient memory — at least SHA512_RESULT_SIZE(64) 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.

sha512.h

SHA512_freeDigest()

MOC_EXTERN MSTATUS SHA512_freeDigest

(

MOC_HASH(hwAccelDescr hwAccelCtx) BulkCtx *

pp_shaContext

)

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

Note

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

FIPS Approved
Suite B Algorithm
Flowchart	SHA512

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

• __DISABLE_MOCANA_SHA512__

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

sha512.h

SHA512_initDigest()

MOC_EXTERN MSTATUS SHA512_initDigest

(

MOC_HASH(hwAccelDescr hwAccelCtx) SHA512_CTX *

pCtx

)

This function initializes an SHA512 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 SHA512 operations to fail.

Note

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

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

FIPS Approved
Suite B Algorithm
Flowchart	SHA512

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

• __DISABLE_MOCANA_SHA512__

sha512.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 SHA512 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.

sha512.h

SHA512_updateDigest()

MOC_EXTERN MSTATUS SHA512_updateDigest	(	MOC_HASH(hwAccelDescr hwAccelCtx) SHA512_CTX *	pCtx,
		const ubyte *	pData,
		ubyte4	dataLen
	)

This function calculates an intermediate SHA512 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 SHA512 context data structure.

Note

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

FIPS Approved
Suite B Algorithm
Flowchart	SHA512

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

• __DISABLE_MOCANA_SHA512__

sha512.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 SHA512 context.
pData	Pointer to data to hash or digest.
dataLen	Number of bytes of data to hash or digest (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.

sha512.h