dh.h File Reference

Header file for the NanoCyrpto Diffie-Hellman (DH) API. More...

Go to the source code of this file.

Data Structures
struct	diffieHellmanContext
	Context information for an exercise of the DH protocol. More...

Functions
MOC_EXTERN MSTATUS	DH_allocate (diffieHellmanContext **pp_dhContext)
	Allocate and initialize a diffieHellmanContext structure. More...
MOC_EXTERN MSTATUS	DH_allocateClient (MOC_DH(hwAccelDescr hwAccelCtx) randomContext *pRandomContext, diffieHellmanContext **pp_dhContext, ubyte4 groupNum)
	Allocate and initialize resources for a DH client. More...
MOC_EXTERN MSTATUS	DH_allocateClientAux (MOC_DH(hwAccelDescr hwAccelCtx) randomContext *pRandomContext, diffieHellmanContext **pp_dhContext, ubyte4 groupNum)
	Allocate and initialize resources for a DH client with the group generator G. More...
MOC_EXTERN MSTATUS	DH_allocateServer (MOC_DH(hwAccelDescr hwAccelCtx) randomContext *pRandomContext, diffieHellmanContext **pp_dhContext, ubyte4 groupNum)
	Allocate and initialize resources for a DH server. More...
MOC_EXTERN MSTATUS	DH_computeKeyExchange (MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext *p_dhContext, vlong **ppVlongQueue)
	Compute the shared secret. More...
MOC_EXTERN MSTATUS	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	DH_freeDhContext (diffieHellmanContext **pp_dhContext, vlong **ppVlongQueue)
	Free the memory allocated for a diffieHellmanContext structure. More...
MOC_EXTERN MSTATUS	DH_freeKeyTemplate (diffieHellmanContext *pCtx, MDhKeyTemplate *pTemplate)
	Zeros and frees each parameter stored in pTemplate. More...
MOC_EXTERN MSTATUS	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	DH_getG (ubyte4 groupNum, vlong **ppRetG)
	Get a Generator value for DH calculations. More...
MOC_EXTERN MSTATUS	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	DH_getP (ubyte4 groupNum, vlong **ppRetP)
	Get a large prime number to use as your DH private key. More...
MOC_EXTERN MSTATUS	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	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	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	DH_setKeyParameters (MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext *pTargetCtx, MDhKeyTemplate *pSrcTemplate)
	Sets the key parameters stored in pSrcTemplate in the pTargetCtx. More...
MOC_EXTERN MSTATUS	DH_setPG (MOC_DH(hwAccelDescr hwAccelCtx) randomContext *pRandomContext, ubyte4 lengthY, diffieHellmanContext *p_dhContext, const vlong *P, const vlong *G)
	Assign a prime and a generator to an allocated DH context. More...
MOC_EXTERN MSTATUS	DH_setPGQ (MOC_DH(hwAccelDescr hwAccelCtx) randomContext *pRandomContext, ubyte4 lengthY, diffieHellmanContext *p_dhContext, const vlong *P, const vlong *G, const vlong *Q)
	Assign a prime and a generator to an allocated DH context. More...
MOC_EXTERN MSTATUS	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	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	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	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

Header file for the NanoCyrpto Diffie-Hellman (DH) API.

See also

For information about the NanoCrypto Ecliptic Curve (EC) DH API, see primeec.h

All the explanatory write-up was added after the 5.3.1 release, and should be eng-reviewed for accuracy and appropriateness.

About the DH Cipher

In the standard DH scenario, two participants publicly negotiate a Generator value and a Large Prime modulus value. In private, both participants then select a random number (their private key). Using these values, each participant generates a public key: the Generator raised to the power of the private key, modulo the Large Prime. (This calculation is presented in the table below.) Each participant then sends its public key to the other. Using these openly communicated values and their private keys, each participant can generate an identical shared secret value. (The calculation is presented in the table below.)

Using this shared secret value as a key, both parties can encrypt their subsequent communications using a symmetric cipher. The following table summarizes the standard DH protocol and how one uses the fundamental DigiCert TrustCore SDK DH API to implement that protocol. In this table, you will see references to a "client" and a "server." In this case, the client is the initiator of the negotiation, and the server is the responder to the initial request.

Step	Action	Role of Client and Server
1	Call DH_allocate().	Both client and server use this function to allocate and initialize a diffieHellmanContext structure, which is used by the DH API to maintain DH context information. For details, see the description of the diffieHellmanContext structure and its members.
2	Negotiate the Generator and the Large Prime.	During this step of the protocol, the client should contact the server and negotiate the values for the Large Prime and the Generator. The security of the protocol depends on the Large Prime being truly large. For the Generator, agree on a primitive root of the Large Prime. To enhance security, choose a Generator that generates a large subgroup of the multiplicative group mod Large Prime; a single-digit prime number is the usual choice. To generate suitable Generator and Large Prime values for the negotiation, use the functions, DH_getP() and DH_getG(). When exchanging Generator and Large Prime values with a peer, use the ASN.1 object and identifiers specified in the RSA document, PKCS #3: Diffie-Hellman Key-Agreement Standard, a publication of RSA Laboratories. Section 9 of the publication defines the following: dhKeyAgreement OBJECT IDENTIFIER ::= { pkcs-3 1 pkcs-3 OBJECT IDENTIFIER ::= { iso(1) member-body(2) US(840) rsadsi(113549) pkcs(1) 3 } DHParameter ::= SEQUENCE { prime INTEGER, – p base INTEGER, – g privateValueLength INTEGER OPTIONAL }
3	Call DH_setPG().	Both the client and server use this function to add the Generator and the Large Prime to the context information stored in their respective diffieHellmanContext structures. The Generator and the Large Prime are stored under the members, dh_g and dh_p. The DH_setPG() function also selects the caller's Private Key, a random number. After selecting the caller's Private Key, this function calculates the caller's Public Key, using the formula: Note Using the DH_setPG() function, you do not directly access your Private Key. If you need to access the Private Key, read the dh_y member of the diffieHellmanContext structure, but keep in mind that this is the private key and that you must keep it private. Also, note that each exercise of this protocol makes its own call to DH_setPG(), and therefore the Private Key changes from exercise to exercise, which is required for the security of the DH protocol. Do not reuse the Private Key from one exercise to the next.
4	Send your Public Key to the peer.	To obtain this Public Key, read the dh_f member of the diffieHellmanContext structure after a successful call to DH_setPG(). Note Both client and server find their respective Public Key values in the dh_f member of their diffieHellmanContext structure. The dh_f member stores the local Public Key.
5	Receive the Public Key from the peer.	Upon receiving the peer's Public Key, both client and server store it in the dh_e member of their respective diffieHellmanContext structures. Note Whether you are client or server, use the dh_e member to store the Public Key of the other.
6	Call DH_computeKeyExchange().	After the successful completion of a DH_computeKeyExchange() call, both client and server can find the shared secret in the dh_k member of their respective diffieHellmanContext structures. Note Internally, DH_computeKeyExchange() validates the public key that is received from the other. An invalid key could indicate manipulation by a man in the middle. In this case, you should stop any further processing of this protocol. Because the standard DH protocol does not include a means of authentication, it is susceptible to the man in the middle attack.
7	DH_freeDhContext()	After you are done with the shared secret or have copied it to a secure location, use DH_freeDhContext() to free the diffieHellmanContext structure allocated by the call to DH_allocate().

Using DH_allocateClient() and DH_allocateServer()

Before negotiating with the server for the Generator and Large Prime values, the client calls DH_allocateClient(), which does the following: +# Allocates a diffieHellmanContext structure for the client. +# Chooses a Large Prime value, which it stores in diffieHellmanContext::dh_p member. +# Chooses a private key for the client, which it stores in diffieHellmanContext::dh_y member.

Calling DH_allocateClient() does not choose a Generator value. To get a Generator value for your negotiation with the server, call DH_getG(). After completing the negotiation with the server for the Generator and Large Prime, the client continues the protocol from step 3 in the table above.

After receiving a request from a client, the server calls DH_allocateServer(), which does the following:

1. Allocates a diffieHellmanContext structure.
2. Picks a Generator value, which it stores in diffieHellmanContext::dh_g.
3. Picks a Large Prime value, which it stores in diffieHellmanContext::dh_p.
4. Picks a Private Key, which it stores in diffieHellmanContext::dh_y.
5. Generates the Public Key, which it stores in diffieHellmanContext::dh_f.

The DH_allocateServer() function's default operation assumes that the negotiation over the Generator and Large Prime modulus value consists of the server telling the client what the values will be. If that is the case, the server continues the protocol from step 4 in the table above. If that is not the case — that is, if the server truly negotiates these values with the client — the server picks up the protocol from step 3 in the table above.

There are no flag dependencies for the functions in this API.

dh.h

Function Documentation

DH_allocate()

MOC_EXTERN MSTATUS DH_allocate

(

diffieHellmanContext **

pp_dhContext

)

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

FIPS Approved
Suite B Algorithm
Flowchart	DH

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.

There are no flag dependencies to enable this function.

dh.h

Parameters

pp_dhContext

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. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

dh.c

DH_allocateClient()

MOC_EXTERN MSTATUS DH_allocateClient	(	MOC_DH(hwAccelDescr hwAccelCtx) randomContext *	pRandomContext,
		diffieHellmanContext **	pp_dhContext,
		ubyte4	groupNum
	)

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

1. Allocates a diffieHellmanContext structure for the client.
2. Chooses a Large Prime value, which it stores in diffieHellmanContext::dh_p member.
3. Chooses a private key for the client, which it stores in diffieHellmanContext::dh_y member.

FIPS Approved
Suite B Algorithm
Flowchart	DH

(This function writeup is new since 5.3.1; don't know why it wasn't in the old documentation...)

This function does not choose a Generator value. The Generator value and the Large Prime value are usually negotiated with the server. Therefore, upon receiving new values for the Generator and the Large Prime modulus, you must call DH_setPG() to populate the dh_g and dh_p members of the diffieHellmanContext structure, as well as to re-select your private key and generate your public key. You must then send this public key to the server.

When you receive the server's public key, store it in the dh_e member of your diffieHellmanContext structure, and then call DH_computeKeyExchange().

There are no flag dependencies to enable this function.

dh.h

Parameters

pRandomContext	Pointer to a randomContext structure, which is used internally to store the information needed to manage the generation of a random number using the NanoCrypto Random API (see random.c). To allocate the structure, call RANDOM_acquireContext(). To release the memory of the structure, call RANDOM_releaseContext().
pp_dhContext	On return, pointer to address of allocated diffieHellmanContext structure.
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.

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.

dh.c

DH_allocateClientAux()

MOC_EXTERN MSTATUS DH_allocateClientAux	(	MOC_DH(hwAccelDescr hwAccelCtx) randomContext *	pRandomContext,
		diffieHellmanContext **	pp_dhContext,
		ubyte4	groupNum
	)

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

1. Allocates a diffieHellmanContext structure for the client.
2. Chooses a Large Prime value, which it stores in diffieHellmanContext::dh_p member.
3. Chooses a Generator value, which it stores in diffieHellmanContext::dh_g member.
4. Chooses a private key for the client, which it stores in diffieHellmanContext::dh_y member.

FIPS Approved
Suite B Algorithm
Flowchart	DH

(This function writeup is new since 5.3.1; don't know why it wasn't in the old documentation...)

This function does not choose a Generator value. The Generator value and the Large Prime value are usually negotiated with the server. Therefore, upon receiving new values for the Generator and the Large Prime modulus, you must call DH_setPG() to populate the dh_g and dh_p members of the diffieHellmanContext structure, as well as to re-select your private key and generate your public key. You must then send this public key to the server.

When you receive the server's public key, store it in the dh_e member of your diffieHellmanContext structure, and then call DH_computeKeyExchange().

There are no flag dependencies to enable this function.

dh.h

Parameters

pRandomContext	Pointer to a randomContext structure, which is used internally to store the information needed to manage the generation of a random number using the NanoCrypto Random API (see random.c). To allocate the structure, call RANDOM_acquireContext(). To release the memory of the structure, call RANDOM_releaseContext().
pp_dhContext	On return, pointer to address of allocated diffieHellmanContext structure.
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.

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.

dh.c

DH_allocateServer()

MOC_EXTERN MSTATUS DH_allocateServer	(	MOC_DH(hwAccelDescr hwAccelCtx) randomContext *	pRandomContext,
		diffieHellmanContext **	pp_dhContext,
		ubyte4	groupNum
	)

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

1. Picks a Generator value, which it stores in diffieHellmanContext::dh_g.
2. Picks a Large Prime value, which it stores in diffieHellmanContext::dh_p.
3. Picks a Private Key, which it stores in diffieHellmanContext::dh_y.
4. Generates the Public Key, which it stores in diffieHellmanContext::dh_f.

The DH_allocateServer() function's default operation assumes that the negotiation over the Generator and Large Prime modulus value consists of the server telling the client what the values will be. If that is the case, the server continues the protocol from step 4 in the process table in About the DH Cipher. If that is not the case — that is, if the server truly negotiates these values with the client — the server picks up the protocol from step 3 in the process table in About the DH Cipher.

(This function writeup is new since 5.3.1; don't know why it wasn't in the old documentation...)

FIPS Approved
Suite B Algorithm
Flowchart	DH

There are no flag dependencies to enable this function.

dh.h

Parameters

pRandomContext	Pointer to a randomContext structure, which is used internally to store the information needed to manage the generation of a random number using the NanoCrypto Random API (see random.c). To allocate the structure, call RANDOM_acquireContext(). To release the memory of the structure, call RANDOM_releaseContext().
pp_dhContext	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 DH_computeKeyExchange() to compute the shared secret.
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.

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.

dh.c

DH_computeKeyExchange()

MOC_EXTERN MSTATUS DH_computeKeyExchange	(	MOC_DH(hwAccelDescr hwAccelCtx) diffieHellmanContext *	p_dhContext,
		vlong **	ppVlongQueue
	)

This function computes the shared secret. Call this function after you call DH_setPG() to populate the diffieHellmanContext structure with a Generator value (diffieHellmanContext::dh_g), a Large Prime modulus value (diffieHellmanContext::dh_p), and your private key (diffieHellmanContext::dh_y), and after you store the other participant's public key in the dh_e member of your diffieHellmanContext structure. The shared computed shared secret value is stored in diffieHellmanContext::dh_k member of the specified diffieHellmanContext structure.

FIPS Approved
Suite B Algorithm
Flowchart	DH

There are no flag dependencies to enable this function.

dh.h

Parameters

p_dhContext

Pointer to the diffieHellmanContext structure that you allocated for this exercise of the DH protocol. To allocate a diffieHellmanContext structure, call DH_allocate().

ppVlongQueue

Pointer to memory queue to reduce memory allocaiton penalty; may be NULL. If you pass a pointer to the address of a pre-allocated memory queue for vlong values, the memory required for the DH calculations is taken from this pre-allocated memory queue. If you have not set up a pre-allocated memory queue for this purpose, pass in NULL, in which case the memory for the calculations is allocated from the heap as needed.

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.

dh.c

DH_computeKeyExchangeEx()

MOC_EXTERN MSTATUS 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 for all non-MQV modes.
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.

DH_freeDhContext()

MOC_EXTERN MSTATUS DH_freeDhContext	(	diffieHellmanContext **	pp_dhContext,
		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.

FIPS Approved
Suite B Algorithm
Flowchart	DH

There are no flag dependencies to enable this function.

dh.h

Parameters

pp_dhContext	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. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

dh.c

DH_freeKeyTemplate()

MOC_EXTERN MSTATUS 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.

DH_generateKeyPair()

MOC_EXTERN MSTATUS 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.

DH_getG()

MOC_EXTERN MSTATUS DH_getG	(	ubyte4	groupNum,
		vlong **	ppRetG
	)

This function returns a Generator value for DH calculations.

(This function writeup is new since 5.3.1; don't know why it wasn't in the old documentation...)

FIPS Approved
Suite B Algorithm
Flowchart	DH

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.
ppRetG	On return, pointer to the address of a vlong value containing a Generator value suitable for DH calculations.

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.

dh.c

DH_getKeyParametersAlloc()

MOC_EXTERN MSTATUS 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.

DH_getP()

MOC_EXTERN MSTATUS DH_getP	(	ubyte4	groupNum,
		vlong **	ppRetP
	)

This function returns a large prime number for use as a DH private key. In its original description, DH does not mention Oakley group primes. However, they are required when you integrate DH with protocols such as IKE and IKEv2. For example, for a standard (not elliptic curve (EC)) DH implementation, you would use Oakley Group 1 (the 768-bit prime modulus group) or Oakley Group 2 (the 1,024-bit prime modulus group).

FIPS Approved
Suite B Algorithm
Flowchart	DH

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.
ppRetP	On return, pointer to a buffer containing Oakley Group Prime.

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.

dh.c

DH_getPByteString()

MOC_EXTERN MSTATUS 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.

dh.c

DH_getPublicKey()

MOC_EXTERN MSTATUS 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.

DH_keyAgreementScheme()

MOC_EXTERN MSTATUS 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.

To use this method one must define ENABLE_MOCANA_DH_MODES

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

DH_setKeyParameters()

MOC_EXTERN MSTATUS 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.

DH_setPG()

MOC_EXTERN MSTATUS DH_setPG	(	MOC_DH(hwAccelDescr hwAccelCtx) randomContext *	pRandomContext,
		ubyte4	lengthY,
		diffieHellmanContext *	p_dhContext,
		const vlong *	P,
		const vlong *	G
	)

This function stores a given Large Prime and Generator in the specified diffieHellmanContext structure. For convenience, this function then chooses a secret key — a random number of the specified length — which is then used to compute a Public Key to share with a peer in this exercise of the DH protocol for establishing a shared secret.

FIPS Approved
Suite B Algorithm
Flowchart	DH

There are no flag dependencies to enable this function.

dh.h

Parameters

pRandomContext	Pointer to a randomContext structure, which is used internally to store the information needed to manage the generation of a random number using the NanoCrypto Random API (see random.c). To allocate the structure, call RANDOM_acquireContext(). To release the memory of the structure, call RANDOM_releaseContext().
lengthY	Number of bytes of the random number to use as the secret key. This key is stored in the dh_y member of the p_dhContext argument's diffieHellmanContext structure.
p_dhContext	Pointer to the diffieHellmanContext structure that you allocated for this exercise of the DH protocol. To allocate a diffieHellmanContext structure, call DH_allocate(). To free the memory of the structure, call DH_freeDhContext().
P	Pointer to the Large Prime modulus value (shared prime) agreed to by your peer in this exercise of the DH protocol. The security of the protocol depends on this value being large. While negotiating this value, you can use DH_GetP() to get a suitable value to propose to your peer.
G	Pointer to the shared Generator value that you negotiated with your peer in this exercise of the DH protocol. The Generator value should be a primitive root of the Large Prime. Typically, the Generator is a single-digit prime number that generates a large subgroup of the multiplicative group mod the Large Prime; therefore a single-digit prime number, such as 2, is the usual choice. To get a suitable value to propose to your peer in this exercise of the DH protocol, call use DH_GetG().

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.

dh.c

DH_setPGQ()

MOC_EXTERN MSTATUS DH_setPGQ	(	MOC_DH(hwAccelDescr hwAccelCtx) randomContext *	pRandomContext,
		ubyte4	lengthY,
		diffieHellmanContext *	p_dhContext,
		const vlong *	P,
		const vlong *	G,
		const vlong *	Q
	)

This function stores a given Large Prime and Generator in the specified diffieHellmanContext structure. For convenience, this function then chooses a secret key — a random number of the specified length — which is then used to compute a Public Key to share with a peer in this exercise of the DH protocol for establishing a shared secret.

FIPS Approved
Suite B Algorithm
Flowchart	DH

There are no flag dependencies to enable this function.

dh.h

Parameters

pRandomContext	Pointer to a randomContext structure, which is used internally to store the information needed to manage the generation of a random number using the NanoCrypto Random API (see random.c). To allocate the structure, call RANDOM_acquireContext(). To release the memory of the structure, call RANDOM_releaseContext().
lengthY	Number of bytes of the random number to use as the secret key. This key is stored in the dh_y member of the p_dhContext argument's diffieHellmanContext structure.
p_dhContext	Pointer to the diffieHellmanContext structure that you allocated for this exercise of the DH protocol. To allocate a diffieHellmanContext structure, call DH_allocate(). To free the memory of the structure, call DH_freeDhContext().
P	Pointer to the Large Prime modulus value (shared prime) agreed to by your peer in this exercise of the DH protocol. The security of the protocol depends on this value being large. While negotiating this value, you can use DH_GetP() to get a suitable value to propose to your peer.
G	Pointer to the shared Generator value that you negotiated with your peer in this exercise of the DH protocol. The Generator value should be a primitive root of the Large Prime. Typically, the Generator is a single-digit prime number that generates a large subgroup of the multiplicative group mod the Large Prime; therefore a single-digit prime number, such as 2, is the usual choice. To get a suitable value to propose to your peer in this exercise of the DH protocol, call use DH_GetG().
Q	Pointer to the Prime Divisor modulus value (shared prime) agreed to by your peer in this exercise of the DH protocol. Need TO FIX TEXT HERE...

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.

dh.c

DH_validateDomainParams()

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

DH_verifyG()

MOC_EXTERN MSTATUS 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. s

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

DH_verifyPQ_FIPS1864()

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

DH_verifySafePG()

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