Cryptographic Interface header file for declaring DH functions. More...

Functions
MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_allocate (diffieHellmanContext **ppNewCtx)
	Allocate and initialize a `diffieHellmanContext` structure. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_allocateClientAux (MOC_DH(hwAccelDescr hwAccelCtx) randomContext pRandomContext, diffieHellmanContext *ppNewCtx, ubyte4 groupNum)
	Allocate and initialize resources for a DH client. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_allocateClientAuxExt (MOC_DH(hwAccelDescr hwAccelCtx) randomContext pRandomContext, diffieHellmanContext ppNewCtx, ubyte4 groupNum, void pExtCtx)
	Allocate and initialize resources for a DH client. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_allocateExt (diffieHellmanContext *ppNewCtx, void pExtCtx)
	Allocate and initialize a `diffieHellmanContext` structure. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_allocateServer (MOC_DH(hwAccelDescr hwAccelCtx) randomContext pRandomContext, diffieHellmanContext *ppNewCtx, ubyte4 groupNum)
	Allocate and initialize resources for a DH server. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_allocateServerExt (MOC_DH(hwAccelDescr hwAccelCtx) randomContext pRandomContext, diffieHellmanContext ppNewCtx, ubyte4 groupNum, void pExtCtx)
	Allocate and initialize resources for a DH server. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_computeKeyExchangeEx (MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext pCtx, randomContext pRandomContext, ubyte pOtherPartysPublicKey, ubyte4 publicKeyLen, ubyte ppSharedSecret, ubyte4 pSharedSecretLen)
	Generates a shared secret from the domain parameters and our private key stored in the context, and the other partys public key as passed in. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_computeKeyExchangeExExt (MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext pCtx, randomContext pRandomContext, ubyte pOtherPartysPublicKey, ubyte4 publicKeyLen, ubyte ppSharedSecret, ubyte4 pSharedSecretLen, void *pExtCtx)
	Generates a shared secret from the domain parameters and our private key stored in the context, and the other partys public key as passed in. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_freeDhContext (diffieHellmanContext ppDhCtx, vlong ppVlongQueue)
	Free the memory allocated for a `diffieHellmanContext` structure. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_freeDhContextExt (diffieHellmanContext ppDhCtx, vlong ppVlongQueue, void *pExtCtx)
	Free the memory allocated for a `diffieHellmanContext` structure. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_freeKeyTemplate (diffieHellmanContext pCtx, MDhKeyTemplate pTemplate)
	Zeros and frees each parameter stored in pTemplate. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_freeKeyTemplateExt (diffieHellmanContext pCtx, MDhKeyTemplate pTemplate, void *pExtCtx)
	Zeros and frees each parameter stored in pTemplate. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_generateDomainParams (MOC_FFC(hwAccelDescr hwAccelCtx) diffieHellmanContext pCtx, randomContext pFipsRngCtx, ubyte4 keySize, ubyte4 qSize, FFCHashType hashType, vlong **ppVlongQueue)
	Generates Diffie-Hellman domain params P,Q,G. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_generateKeyPair (MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext pCtx, randomContext pRandomContext, ubyte4 numBytes)
	This method generates a key pair (y,f) within a context that has already had had the domain params p and g set. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_generateKeyPairExt (MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext pCtx, randomContext pRandomContext, ubyte4 numBytes, void *pExtCtx)
	This method generates a key pair (y,f) within a context that has already had had the domain params p and g set. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_getKeyParametersAlloc (MOC_DH(hwAccelDescr hwAccelCtx) MDhKeyTemplate pTargetTemplate, diffieHellmanContext pSrcCtx, ubyte keyType)
	For each parameter value g, p, q, y, f that is stored in the pSrcCtx, this method will allocate space for it within pTargetTemplate, and copy it there as a Big Endian byte array. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_getKeyParametersAllocExt (MOC_DH(hwAccelDescr hwAccelCtx) MDhKeyTemplate pTargetTemplate, diffieHellmanContext pSrcCtx, ubyte keyType, void *pExtCtx)
	For each parameter value g, p, q, y, f that is stored in the pSrcCtx, this method will allocate space for it within pTargetTemplate, and copy it there as a Big Endian byte array. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_getPByteString (ubyte4 groupNum, const ubyte *ppBytes, sbyte4 pLen)
	Get a large prime number to use as your DH private key as a Big Endian byte array. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_getPublicKey (MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext pCtx, ubyte ppPublicKey, ubyte4 pPublicKeyLen)
	This method will allocate a buffer and fill it with our public key in Big Endian binary. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_getPublicKeyExt (MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext pCtx, ubyte ppPublicKey, ubyte4 pPublicKeyLen, void *pExtCtx)
	This method will allocate a buffer and fill it with our public key in Big Endian binary. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_keyAgreementScheme (MOC_DH(hwAccelDescr hwAccelCtx) ubyte4 mode, randomContext pRandomContext, diffieHellmanContext pStatic, diffieHellmanContext pEphemeral, ubyte pOtherPartysStatic, ubyte4 otherStaticLen, ubyte pOtherPartysEphemeral, ubyte4 otherEphemeralLen, ubyte ppSharedSecret, ubyte4 pSharedSecretLen)
	Generates a Diffie-Hellman shared secret via one of the major modes. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_setKeyParameters (MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext pTargetCtx, MDhKeyTemplate pSrcTemplate)
	Sets the key parameters stored in pSrcTemplate in the pTargetCtx. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_setKeyParametersExt (MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext pTargetCtx, MDhKeyTemplate pSrcTemplate, void *pExtCtx)
	Sets the key parameters stored in pSrcTemplate in the pTargetCtx. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_validateDomainParams (MOC_DH(hwAccelDescr hwAccelCtx) randomContext pFipsRngCtx, diffieHellmanContext pCtx, FFCHashType hashType, ubyte4 C, ubyte pSeed, ubyte4 seedSize, intBoolean pIsValid, ubyte4 pPriKeyLen, vlong *ppVlongQueue)
	Validates the Diffie-Hellman domain parameters. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_verifyG (MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext pCtx, intBoolean pIsValid, vlong **ppVlongQueue)
	Verifies the domain parameter G is valid with respect to the P and Q parameters in a `diffieHellmanContext`. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_verifyKeyPair (MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext pCtx, intBoolean pIsValid, vlong **ppVlongQueue)
	Validates a DH private/public key pair. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_verifyPQ_FIPS1864 (MOC_DH(hwAccelDescr hwAccelCtx) randomContext pFipsRngCtx, diffieHellmanContext pCtx, FFCHashType hashType, ubyte4 C, ubyte pSeed, ubyte4 seedSize, intBoolean pIsValid, vlong **ppVlongQueue)
	Verifies the domain parameters P and Q in a context come from the FIPS 186-4 algorithm. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_verifyPrivateKey (MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext pCtx, intBoolean pIsValid, vlong **ppVlongQueue)
	Validates a DH private key. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_verifyPublicKey (MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext pCtx, intBoolean pIsValid, vlong **ppVlongQueue)
	Validates a DH public key. More...

MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_DH_verifySafePG (diffieHellmanContext pCtx, intBoolean pIsValid, ubyte4 pPriKeyLen, vlong *ppVlongQueue)
	Validates that the P and G domain parameters come from one of the pre approved safe prime groups. More...

Detailed Description

crypto_interface_dh.h

Function Documentation

◆ CRYPTO_INTERFACE_DH_allocate()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_allocate ( diffieHellmanContext ** ppNewCtx )

This function allocates and initializes a diffieHellmanContext structure, which the NanoCrypto DH API uses to store information that defines a Diffie-Hellman context.

The diffieHellmanContext returned by this function structure is empty of any context information. To supply the context information, select an appropriate generator and prime, compute a public value, and then compute a shared secret.

Parameters

ppNewCtx On return, pointer to the address of an initialized diffieHellmanContext structure that you can use to store a Diffie-Hellman context. The structure does not yet contain any context information.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h.

◆ CRYPTO_INTERFACE_DH_allocateClientAux()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_allocateClientAux	(	MOC_DH(hwAccelDescr hwAccelCtx) randomContext *	pRandomContext,
		diffieHellmanContext **	ppNewCtx,
		ubyte4	groupNum
	)

This function is a convenience function that performs the following tasks that normally require separate calls to the NanoCrypto DH API:

Allocates a diffieHellmanContext structure for the client.
Chooses a Large Prime value, which it stores in diffieHellmanContext.
Chooses a Generator value, which it stores in diffieHellmanContext.
Chooses a private key for the client, which it stores in diffieHellmanContext. NOTE: depending on the underlying implementation the public key may also be calculated.

Parameters

pRandomContext	Pointer to a `randomContext` structure, which is used internally to store the information needed to manage the generation of random numbers. To allocate the structure, call CRYPTO_createMocSymRandom(). To release the memory of the structure, call CRYPTO_freeMocSymRandom().
ppNewCtx	On return, pointer to address of allocated `diffieHellmanContext` structure.
groupNum	The group number of a pre-defined Diffie-Hellman group which may be hardcoded into the underlying implemenation. These may be the Oakley Prime Groups for example.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h.

◆ CRYPTO_INTERFACE_DH_allocateClientAuxExt()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_allocateClientAuxExt	(	MOC_DH(hwAccelDescr hwAccelCtx) randomContext *	pRandomContext,
		diffieHellmanContext **	ppNewCtx,
		ubyte4	groupNum,
		void *	pExtCtx
	)

This function is a convenience function that performs the following tasks that normally require separate calls to the NanoCrypto DH API:

Allocates a diffieHellmanContext structure for the client.
Chooses a Large Prime value, which it stores in diffieHellmanContext.
Chooses a Generator value, which it stores in diffieHellmanContext.
Chooses a private key for the client, which it stores in diffieHellmanContext. NOTE: depending on the underlying implementation the public key may also be calculated.

Parameters

pRandomContext	Pointer to a `randomContext` structure, which is used internally to store the information needed to manage the generation of random numbers. To allocate the structure, call CRYPTO_createMocSymRandom(). To release the memory of the structure, call CRYPTO_freeMocSymRandom().
ppNewCtx	On return, pointer to address of allocated `diffieHellmanContext` structure.
groupNum	The group number of a pre-defined Diffie-Hellman group which may be hardcoded into the underlying implemenation. These may be the Oakley Prime Groups for example.
pExtCtx	Extended Context for future use.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h.

◆ CRYPTO_INTERFACE_DH_allocateExt()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_allocateExt	(	diffieHellmanContext **	ppNewCtx,
		void *	pExtCtx
	)

This function allocates and initializes a diffieHellmanContext structure, which the NanoCrypto DH API uses to store information that defines a Diffie-Hellman context.

The diffieHellmanContext returned by this function structure is empty of any context information. To supply the context information, select an appropriate generator and prime, compute a public value, and then compute a shared secret.

Parameters

ppNewCtx	On return, pointer to the address of an initialized `diffieHellmanContext` structure that you can use to store a Diffie-Hellman context. The structure does not yet contain any context information.
pExtCtx	Extended Context for future use.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h.

◆ CRYPTO_INTERFACE_DH_allocateServer()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_allocateServer	(	MOC_DH(hwAccelDescr hwAccelCtx) randomContext *	pRandomContext,
		diffieHellmanContext **	ppNewCtx,
		ubyte4	groupNum
	)

This function is a convenience function that performs the following tasks that normally require separate calls to the NanoCrypto DH API:

Picks a Generator value, which it stores in diffieHellmanContext.
Picks a Large Prime value, which it stores in diffieHellmanContext.
Picks a Private Key, which it stores in diffieHellmanContext.
Generates the Public Key, which it stores in diffieHellmanContext.

Parameters

pRandomContext	Pointer to a `randomContext` structure, which is used internally to store the information needed to manage the generation of random numbers. To allocate the structure, call CRYPTO_createMocSymRandom(). To release the memory of the structure, call CRYPTO_freeMocSymRandom().
ppNewCtx	On return, pointer to address of allocated and partially populated `diffieHellmanContext` structure. Before you can use this structure to calculate the shared secret, you must get the public key from the client and store it in the `dh_e` member of this structure. You can then call CRYPTO_INTERFACE_DH_computeKeyExchangeEx() to compute the shared secret.
groupNum	The group number of a pre-defined Diffie-Hellman group which may be hardcoded into the underlying implemenation. These may be the Oakley Prime Groups for example.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h.

◆ CRYPTO_INTERFACE_DH_allocateServerExt()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_allocateServerExt	(	MOC_DH(hwAccelDescr hwAccelCtx) randomContext *	pRandomContext,
		diffieHellmanContext **	ppNewCtx,
		ubyte4	groupNum,
		void *	pExtCtx
	)

This function is a convenience function that performs the following tasks that normally require separate calls to the NanoCrypto DH API:

Picks a Generator value, which it stores in diffieHellmanContext.
Picks a Large Prime value, which it stores in diffieHellmanContext.
Picks a Private Key, which it stores in diffieHellmanContext.
Generates the Public Key, which it stores in diffieHellmanContext.

Parameters

pRandomContext	Pointer to a `randomContext` structure, which is used internally to store the information needed to manage the generation of random numbers. To allocate the structure, call CRYPTO_createMocSymRandom(). To release the memory of the structure, call CRYPTO_freeMocSymRandom().
ppNewCtx	On return, pointer to address of allocated and partially populated `diffieHellmanContext` structure. Before you can use this structure to calculate the shared secret, you must get the public key from the client and store it in the `dh_e` member of this structure. You can then call CRYPTO_INTERFACE_DH_computeKeyExchangeEx() to compute the shared secret.
groupNum	The group number of a pre-defined Diffie-Hellman group which may be hardcoded into the underlying implemenation. These may be the Oakley Prime Groups for example.
pExtCtx	Extended Context for future use.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h.

◆ CRYPTO_INTERFACE_DH_computeKeyExchangeEx()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_computeKeyExchangeEx	(	MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext *	pCtx,
		randomContext *	pRandomContext,
		ubyte *	pOtherPartysPublicKey,
		ubyte4	publicKeyLen,
		ubyte **	ppSharedSecret,
		ubyte4 *	pSharedSecretLen
	)

Parameters

pCtx	Pointer to the context holding at least the domain params p and g and our private key y.
pRandomContext	Pointer to a random Context. If non-NULL then blinding will be done.
pOtherPartysPublicKey	Pointer to the the other party's public key as a Big Endian byte string.
publicKeyLen	Length in bytes of the other party's public key.
ppSharedSecret	Pointer to a buffer that will be allocated and filled with the shared secret in Big Endian binary.
pSharedSecretLen	Pointer to a ubyte4 that will be filled with the length of the shared secret in bytes.

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

◆ CRYPTO_INTERFACE_DH_computeKeyExchangeExExt()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_computeKeyExchangeExExt	(	MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext *	pCtx,
		randomContext *	pRandomContext,
		ubyte *	pOtherPartysPublicKey,
		ubyte4	publicKeyLen,
		ubyte **	ppSharedSecret,
		ubyte4 *	pSharedSecretLen,
		void *	pExtCtx
	)

Parameters

pCtx	Pointer to the context holding at least the domain params p and g and our private key y.
pRandomContext	Pointer to a random Context. If non-NULL then blinding will be done.
pOtherPartysPublicKey	Pointer to the the other party's public key as a Big Endian byte string.
publicKeyLen	Length in bytes of the other party's public key.
ppSharedSecret	Pointer to a buffer that will be allocated and filled with the shared secret in Big Endian binary.
pSharedSecretLen	Pointer to a ubyte4 that will be filled with the length of the shared secret in bytes.
pExtCtx	Extended Context for future use.

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

◆ CRYPTO_INTERFACE_DH_freeDhContext()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_freeDhContext	(	diffieHellmanContext **	ppDhCtx,
		vlong **	ppVlongQueue
	)

This function releases (frees) the memory allocated to a diffieHellmanContext structure. If the structure contains memory from a pre-allocated memory queue, use the ppVlongQueue parameter to identify that queue and free (reallocate) that memory back to the queue. All other allocated memory is freed back to the heap.

Parameters

ppDhCtx	Pointer to the `diffieHellmanContext` structure to free. On return, this value is NULL.
ppVlongQueue	Pointer to the pre-allocated vlong memory queue used for the DH calculations. If the `diffieHellmanContext` structure contains memory allocated from that queue, it is returned there. If you did not use a pre-allocated memory queue, pass in NULL.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h.

◆ CRYPTO_INTERFACE_DH_freeDhContextExt()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_freeDhContextExt	(	diffieHellmanContext **	ppDhCtx,
		vlong **	ppVlongQueue,
		void *	pExtCtx
	)

This function releases (frees) the memory allocated to a diffieHellmanContext structure. If the structure contains memory from a pre-allocated memory queue, use the ppVlongQueue parameter to identify that queue and free (reallocate) that memory back to the queue. All other allocated memory is freed back to the heap.

Parameters

ppDhCtx	Pointer to the `diffieHellmanContext` structure to free. On return, this value is NULL.
ppVlongQueue	Pointer to the pre-allocated vlong memory queue used for the DH calculations. If the `diffieHellmanContext` structure contains memory allocated from that queue, it is returned there. If you did not use a pre-allocated memory queue, pass in NULL.
pExtCtx	Extended Context for future use.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h.

◆ CRYPTO_INTERFACE_DH_freeKeyTemplate()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_freeKeyTemplate	(	diffieHellmanContext *	pCtx,
		MDhKeyTemplate *	pTemplate
	)

Parameters

pCtx	Pointer to a context. This is not needed and may be NULL.
pTemplate	Pointer to the template to be zeroed and freed.

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

◆ CRYPTO_INTERFACE_DH_freeKeyTemplateExt()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_freeKeyTemplateExt	(	diffieHellmanContext *	pCtx,
		MDhKeyTemplate *	pTemplate,
		void *	pExtCtx
	)

Parameters

pCtx	Pointer to a context. This is not needed and may be NULL.
pTemplate	Pointer to the template to be zeroed and freed.
pExtCtx	Extended Context for future use.

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

◆ CRYPTO_INTERFACE_DH_generateDomainParams()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_generateDomainParams	(	MOC_FFC(hwAccelDescr hwAccelCtx) diffieHellmanContext *	pCtx,
		randomContext *	pFipsRngCtx,
		ubyte4	keySize,
		ubyte4	qSize,
		FFCHashType	hashType,
		vlong **	ppVlongQueue
	)

Generates Diffie-Hellman domain params P,Q,G.

Parameters

pCtx	A previously allocated Diffie-Hellman context.
pFipsRngCtx	A RNG context.
keySize	The size in bits of the prime P to be generated.
qSize	The size in bits of the prime Q to be generated.
hashType	The hashing method to be used in domain param generation.
ppVlongQueue	On return, pointer to location in the `vlong` queue that contains this function's intermediate value, which can subsequently be used and eventually discarded. (Before ending, your application should be sure to free the entire queue.)

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.

crypto_interface_dh.c

◆ CRYPTO_INTERFACE_DH_generateKeyPair()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_generateKeyPair	(	MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext *	pCtx,
		randomContext *	pRandomContext,
		ubyte4	numBytes
	)

Parameters

pCtx	Pointer to the context holding at least the domain params p and g.
pRandomContext	Pointer to a random context.
numBytes	The number of bytes that a newly generated private key will consist of.

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

◆ CRYPTO_INTERFACE_DH_generateKeyPairExt()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_generateKeyPairExt	(	MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext *	pCtx,
		randomContext *	pRandomContext,
		ubyte4	numBytes,
		void *	pExtCtx
	)

Parameters

pCtx	Pointer to the context holding at least the domain params p and g.
pRandomContext	Pointer to a random context.
numBytes	The number of bytes that a newly generated private key will consist of.
pExtCtx	Extended Context for future use.

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

◆ CRYPTO_INTERFACE_DH_getKeyParametersAlloc()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_getKeyParametersAlloc	(	MOC_DH(hwAccelDescr hwAccelCtx) MDhKeyTemplate *	pTargetTemplate,
		diffieHellmanContext *	pSrcCtx,
		ubyte	keyType
	)

Parameters

pTargetTemplate	Pointer to the template that will hold the key parameters in Big Endian byte array form.
pSrcCtx	Pointer to the context already holding the key parameters.
keyType	one of MOC_GET_PRIVATE_KEY_DATA or MOC_GET_PUBLIC_KEY_DATA.

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

◆ CRYPTO_INTERFACE_DH_getKeyParametersAllocExt()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_getKeyParametersAllocExt	(	MOC_DH(hwAccelDescr hwAccelCtx) MDhKeyTemplate *	pTargetTemplate,
		diffieHellmanContext *	pSrcCtx,
		ubyte	keyType,
		void *	pExtCtx
	)

Parameters

pTargetTemplate	Pointer to the template that will hold the key parameters in Big Endian byte array form.
pSrcCtx	Pointer to the context already holding the key parameters.
keyType	one of MOC_GET_PRIVATE_KEY_DATA or MOC_GET_PUBLIC_KEY_DATA.
pExtCtx	Extended Context for future use.

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

◆ CRYPTO_INTERFACE_DH_getPByteString()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_getPByteString	(	ubyte4	groupNum,
		const ubyte **	ppBytes,
		sbyte4 *	pLen
	)

Get a large prime number to use as your DH private key as a Big Endian byte array. This method does not allocate memory.

There are no flag dependencies to enable this function.

dh.h

Parameters

groupNum	Group number. Use whichever group number is appropriate for your application from among the following values: 1, 2, 5, 14, 15, 16, 17, 18, 24, 0x100, 0x101, 0x102, 0x103, 0x104.
ppBytes	Pointer to a byte array that will be set to the hard coded value of P for the groupNum passed in.
pLen	Will be set with the length of P in bytes.

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.

crypto_interface_dh.c

◆ CRYPTO_INTERFACE_DH_getPublicKey()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_getPublicKey	(	MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext *	pCtx,
		ubyte **	ppPublicKey,
		ubyte4 *	pPublicKeyLen
	)

Parameters

pCtx	Pointer to the context holding a public key.
ppPublicKey	Pointer to a buffer that will be allocated and filled with our public key in Big Endian binary.
pPublicKeyLen	Pointer to a ubyte4 that will be filled with the length of the public key in bytes.

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

◆ CRYPTO_INTERFACE_DH_getPublicKeyExt()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_getPublicKeyExt	(	MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext *	pCtx,
		ubyte **	ppPublicKey,
		ubyte4 *	pPublicKeyLen,
		void *	pExtCtx
	)

Parameters

pCtx	Pointer to the context holding a public key.
ppPublicKey	Pointer to a buffer that will be allocated and filled with our public key in Big Endian binary.
pPublicKeyLen	Pointer to a ubyte4 that will be filled with the length of the public key in bytes.
pExtCtx	Extended Context for future use.

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

◆ CRYPTO_INTERFACE_DH_keyAgreementScheme()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_keyAgreementScheme	(	MOC_DH(hwAccelDescr hwAccelCtx) ubyte4	mode,
		randomContext *	pRandomContext,
		diffieHellmanContext *	pStatic,
		diffieHellmanContext *	pEphemeral,
		ubyte *	pOtherPartysStatic,
		ubyte4	otherStaticLen,
		ubyte *	pOtherPartysEphemeral,
		ubyte4	otherEphemeralLen,
		ubyte **	ppSharedSecret,
		ubyte4 *	pSharedSecretLen
	)

Generates a Diffie-Hellman shared secret via one of the major modes. This method allocates a buffer to hold the secret. Be sure to FREE this buffer when done with it.

Parameters

mode	One of the following macro values `DH_HYBRID1` `MQV2` `DH_EPHEMERAL` `DH_HYBRID_ONE_FLOW_U` `DH_HYBRID_ONE_FLOW_V` `MQV1_U` `MQV2_V` `DH_ONE_FLOW_U` `DH_ONE_FLOW_V` `DH_STATIC`
pRandomContext	Pointer to a random Context. If non-NULL then blinding will be done.
pStatic	Our private static key.
pEphemeral	Our private ephemeral key.
pOtherPartysStatic	The other party's static public key as an uncompressed form byte array.
otherStaticLen	The length of the uncompressed form static key byte array in bytes.
pOtherPartysEphemeral	The other party's ephemeral public key as an uncompressed form byte array.
otherEphemeralLen	The length of the uncompressed form ephemeral key byte array in bytes.
ppSharedSecret	Pointer to the location of the newly allocated buffer that will store the shared secret.
pSharedSecretLen	Contents will be set to the length of the shared secret in bytes.

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

◆ CRYPTO_INTERFACE_DH_setKeyParameters()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_setKeyParameters	(	MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext *	pTargetCtx,
		MDhKeyTemplate *	pSrcTemplate
	)

pSrcTemplate may hold a groupNum of a pre-defined Diffie-Hellman group, or it may hold any combination of g, p, q, y, f. If a groupNum is non-zero then only p and g will be set and the rest of the template will be ignored. If groupNum is DH_GROUP_TBD (0) then whatever parameters g, p, q, y, f, that are defined in the template, will be set in the pTargetCtx. Any already existing parameters will be overwritten.

Parameters

pTargetCtx	Pointer to the context whose parameters will be set.
pSrcTemplate	Pointer to the template containing the parameters to be set.

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

◆ CRYPTO_INTERFACE_DH_setKeyParametersExt()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_setKeyParametersExt	(	MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext *	pTargetCtx,
		MDhKeyTemplate *	pSrcTemplate,
		void *	pExtCtx
	)

pSrcTemplate may hold a groupNum of a pre-defined Diffie-Hellman group, or it may hold any combination of g, p, q, y, f. If a groupNum is non-zero then only p and g will be set and the rest of the template will be ignored. If groupNum is DH_GROUP_TBD (0) then whatever parameters g, p, q, y, f, that are defined in the template, will be set in the pTargetCtx. Any already existing parameters will be overwritten.

Parameters

pTargetCtx	Pointer to the context whose parameters will be set.
pSrcTemplate	Pointer to the template containing the parameters to be set.
pExtCtx	Extended Context for future use.

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

◆ CRYPTO_INTERFACE_DH_validateDomainParams()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_validateDomainParams	(	MOC_DH(hwAccelDescr hwAccelCtx) randomContext *	pFipsRngCtx,
		diffieHellmanContext *	pCtx,
		FFCHashType	hashType,
		ubyte4	C,
		ubyte *	pSeed,
		ubyte4	seedSize,
		intBoolean *	pIsValid,
		ubyte4 *	pPriKeyLen,
		vlong **	ppVlongQueue
	)

Validates the Diffie-Hellman domain parameters. If a seed, counter, and hashType are provided it validates that the context contains primes P and Q generated via FIPS186-4, and that G is a valid generator. If the a seed and counter are not provided, it validates that P and G are one of the fixed safe prime groups.

dh.h

Parameters

pFipsRngCtx	Optional. Pointer to a FIPS 186 RNG context.
pCtx	Pointer to a context containing a P, G, and (optional) Q to validate.
hashType	Optional. The hash algorithm used for generating P and Q. This is one of the `FFCHashType` values... FFC_sha1 FFC_sha224 FFC_sha256 FFC_sha384 FFC_sha512
C	Optional. The counter value returned when P and Q were generated.
pSeed	Optional. The seed used for generating P and Q.
seedSize	The length of the seed in bytes.
pIsValid	Contents will be set to `TRUE` for a valid P and Q and `FALSE` if otherwise.
pPriKeyLen	For valid parameters, contents will be set to the minimum allowable private key size in bytes.
ppVlongQueue	Optional pointer to a `vlong` queue.

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.

Warning: Be sure to check for both a return status of OK and a pIsValid value of TRUE before accepting that a context has valid parameters.

dh.c

◆ CRYPTO_INTERFACE_DH_verifyG()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_verifyG	(	MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext *	pCtx,
		intBoolean *	pIsValid,
		vlong **	ppVlongQueue
	)

Verifies the domain parameter G is valid with respect to the P and Q parameters in a diffieHellmanContext.

dh.h

Parameters

pCtx	Pointer to a context containing a G, P and Q to validate.
pIsValid	Contents will be set to `TRUE` for a valid G and `FALSE` if otherwise.
ppVlongQueue	Optional pointer to a `vlong` queue.

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.

Warning: Be sure to check for both a return status of OK and a pIsValid value of TRUE before accepting that G is valid with respect to P and Q.

dh.c

◆ CRYPTO_INTERFACE_DH_verifyKeyPair()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_verifyKeyPair	(	MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext *	pCtx,
		intBoolean *	pIsValid,
		vlong **	ppVlongQueue
	)

Validates a DH private/public key pair.

Parameters

pCtx	A key context containing a private and public key.
pIsValid	Contents will be set to `TRUE` if the key is valid and `FALSE` otherwise.
ppVlongQueue	On return, pointer to location in the `vlong` queue that contains this function's intermediate value, which can subsequently be used and eventually discarded. (Before ending, your application should be sure to free the entire queue.)

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.

crypto_interface_dh.c

◆ CRYPTO_INTERFACE_DH_verifyPQ_FIPS1864()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_verifyPQ_FIPS1864	(	MOC_DH(hwAccelDescr hwAccelCtx) randomContext *	pFipsRngCtx,
		diffieHellmanContext *	pCtx,
		FFCHashType	hashType,
		ubyte4	C,
		ubyte *	pSeed,
		ubyte4	seedSize,
		intBoolean *	pIsValid,
		vlong **	ppVlongQueue
	)

Verifies the domain parameters P and Q in a comtext come from the FIPS 186-4 algorithm.

dh.h

Parameters

pFipsRngCtx	Pointer to a FIPS 186 RNG context.
pCtx	Pointer to a context containing a P and Q to validate.
hashType	The hash algorithm used for generating P and Q. This is one of the `FFCHashType` values... FFC_sha1 FFC_sha224 FFC_sha256 FFC_sha384 FFC_sha512
C	The counter value returned when P and Q were generated.
pSeed	The seed used for generating P and Q.
seedSize	The length of the seed in bytes.
pIsValid	Contents will be set to `TRUE` for a valid P and Q and `FALSE` if otherwise.
ppVlongQueue	Optional pointer to a `vlong` queue.

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.

Warning: Be sure to check for both a return status of OK and a pIsValid value of TRUE before accepting that a context has a valid P and Q.

dh.c

◆ CRYPTO_INTERFACE_DH_verifyPrivateKey()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_verifyPrivateKey	(	MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext *	pCtx,
		intBoolean *	pIsValid,
		vlong **	ppVlongQueue
	)

Validates a DH private key.

Parameters

pCtx	A key context containing a private key.
pIsValid	Contents will be set to `TRUE` if the key is valid and `FALSE` otherwise.
ppVlongQueue	On return, pointer to location in the `vlong` queue that contains this function's intermediate value, which can subsequently be used and eventually discarded. (Before ending, your application should be sure to free the entire queue.)

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.

crypto_interface_dh.c

◆ CRYPTO_INTERFACE_DH_verifyPublicKey()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_verifyPublicKey	(	MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext *	pCtx,
		intBoolean *	pIsValid,
		vlong **	ppVlongQueue
	)

Validates a DH public key.

Parameters

pCtx	A key context containing a public key.
pIsValid	Contents will be set to `TRUE` if the key is valid and `FALSE` otherwise.
ppVlongQueue	On return, pointer to location in the `vlong` queue that contains this function's intermediate value, which can subsequently be used and eventually discarded. (Before ending, your application should be sure to free the entire queue.)

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.

crypto_interface_dh.c

◆ CRYPTO_INTERFACE_DH_verifySafePG()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_DH_verifySafePG	(	diffieHellmanContext *	pCtx,
		intBoolean *	pIsValid,
		ubyte4 *	pPriKeyLen,
		vlong **	ppVlongQueue
	)

Validates that the P and G domain parameters come from one of the pre approved safe prime groups.

dh.h

Parameters

pCtx	Pointer to a context containing a P and G to validate.
pIsValid	Contents will be set to `TRUE` for a valid P and G and `FALSE` if otherwise.
pPriKeyLen	For a valid P and G, contents will be set to the minimum allowable private key size in bytes.
ppVlongQueue	Optional pointer to a `vlong` queue.

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.

Warning: Be sure to check for both a return status of OK and a pIsValid value of TRUE before accepting that a context has a valid P and G.

dh.c

Functions

Detailed Description

Function Documentation

◆ CRYPTO_INTERFACE_DH_allocate()

◆ CRYPTO_INTERFACE_DH_allocateClientAux()

◆ CRYPTO_INTERFACE_DH_allocateClientAuxExt()

◆ CRYPTO_INTERFACE_DH_allocateExt()

◆ CRYPTO_INTERFACE_DH_allocateServer()

◆ CRYPTO_INTERFACE_DH_allocateServerExt()

◆ CRYPTO_INTERFACE_DH_computeKeyExchangeEx()

◆ CRYPTO_INTERFACE_DH_computeKeyExchangeExExt()

◆ CRYPTO_INTERFACE_DH_freeDhContext()

◆ CRYPTO_INTERFACE_DH_freeDhContextExt()

◆ CRYPTO_INTERFACE_DH_freeKeyTemplate()

◆ CRYPTO_INTERFACE_DH_freeKeyTemplateExt()

◆ CRYPTO_INTERFACE_DH_generateDomainParams()

◆ CRYPTO_INTERFACE_DH_generateKeyPair()

◆ CRYPTO_INTERFACE_DH_generateKeyPairExt()

◆ CRYPTO_INTERFACE_DH_getKeyParametersAlloc()

◆ CRYPTO_INTERFACE_DH_getKeyParametersAllocExt()

◆ CRYPTO_INTERFACE_DH_getPByteString()

◆ CRYPTO_INTERFACE_DH_getPublicKey()

◆ CRYPTO_INTERFACE_DH_getPublicKeyExt()

◆ CRYPTO_INTERFACE_DH_keyAgreementScheme()

◆ CRYPTO_INTERFACE_DH_setKeyParameters()

◆ CRYPTO_INTERFACE_DH_setKeyParametersExt()

◆ CRYPTO_INTERFACE_DH_validateDomainParams()

◆ CRYPTO_INTERFACE_DH_verifyG()

◆ CRYPTO_INTERFACE_DH_verifyKeyPair()

◆ CRYPTO_INTERFACE_DH_verifyPQ_FIPS1864()

◆ CRYPTO_INTERFACE_DH_verifyPrivateKey()

◆ CRYPTO_INTERFACE_DH_verifyPublicKey()

◆ CRYPTO_INTERFACE_DH_verifySafePG()