Modules
	CryptoCell DH specific errors

	CryptoCell DH Key Generation APIs

Data Structures
struct	CRYS_DH_ExpTemp_t

struct	CRYS_DH_Temp_t

struct	CRYS_DH_HybrTemp_t

struct	CRYS_DH_FipsKat_t

Macros
#define	CRYS_DHPubKey_t CRYSRSAPubKey_t

#define	CRYS_DH_MAX_VALID_KEY_SIZE_VALUE_IN_BITS CRYS_RSA_MAX_VALID_KEY_SIZE_VALUE_IN_BITS

#define	CRYS_DH_MIN_VALID_KEY_SIZE_VALUE_IN_BITS 1024

#define	CRYS_DH_MAX_MOD_SIZE_IN_BYTES ( CRYS_DH_MAX_VALID_KEY_SIZE_VALUE_IN_BITS / SASI_BITS_IN_BYTE )

#define	CRYS_DH_MAX_MOD_SIZE_IN_WORDS ( CRYS_DH_MAX_MOD_SIZE_IN_BYTES /sizeof(uint32_t))

#define	CRYS_DH_MAX_MOD_BUFFER_SIZE_IN_WORDS ( CRYS_DH_MAX_MOD_SIZE_IN_WORDS + 2)

#define	CRYS_DH_DOMAIN_GENERATION_MAX_SIZE_BITS CRYS_RSA_MAX_KEY_GENERATION_SIZE_BITS

#define	CRYS_DHPrimeData_t CRYS_RSAPrimeData_t

#define	CRYS_DHUserPubKey_t CRYS_RSAUserPubKey_t

#define	CRYS_DH_OtherInfo_t CRYS_KDF_OtherInfo_t

#define	CRYS_DH_MAX_SIZE_OF_KEYING_DATA CRYS_KDF_MAX_SIZE_OF_KEYING_DATA

#define	CRYS_DH_PKCS3_GeneratePubPrv (rndState_ptr, rndGenerateVectFunc, Generator_ptr, GeneratorSize, Prime_ptr, PrimeSize, L, tmpPubKey_ptr, tmpPrimeData_ptr, ClientPrvKey_ptr, ClientPrvKeySize_ptr, ClientPub_ptr, ClientPubSize_ptr)

#define	CRYS_DH_ANSI_X942_GeneratePubPrv (rndState_ptr, rndGenerateVectFunc, Generator_ptr, GeneratorSize, Prime_ptr, PrimeSize, Q_ptr, QSize, tmpPubKey_ptr, tmpPrimeData_ptr, ClientPrvKey_ptr, ClientPrvKeySize_ptr, ClientPub_ptr, ClientPubSize_ptr)

#define	CRYS_DH_X942_GetSecretDataAsn1 (ClientPrvKey_ptr, ClientPrvKeySize, ServerPubKey_ptr, ServerPubKeySize, Prime_ptr, PrimeSize, otherInfo_ptr, hashMode, tmpBuff_ptr, SecretKeyingData_ptr, SecretKeyingDataSize) CRYS_DH_X942_GetSecretData ((ClientPrvKey_ptr),(ClientPrvKeySize),(ServerPubKey_ptr),(ServerPubKeySize),(Prime_ptr),(PrimeSize),(otherInfo_ptr),(hashMode),( CRYS_DH_ASN1_Der_mode ),(tmpBuff_ptr),(SecretKeyingData_ptr),(SecretKeyingDataSize))

#define	CRYS_DH_X942_GetSecretDataConcat (ClientPrvKey_ptr, ClientPrvKeySize, ServerPubKey_ptr, ServerPubKeySize, Prime_ptr, PrimeSize, otherInfo_ptr, hashMode, tmpBuff_ptr, SecretKeyingData_ptr, SecretKeyingDataSize) CRYS_DH_X942_GetSecretData ((ClientPrvKey_ptr),(ClientPrvKeySize),(ServerPubKey_ptr),(ServerPubKeySize),(Prime_ptr),(PrimeSize),(otherInfo_ptr),(hashMode),( CRYS_DH_Concat_Der_mode ),(tmpBuff_ptr),(SecretKeyingData_ptr),(SecretKeyingDataSize))

#define	CRYS_DH_X942_HybridGetSecretDataAsn1 (ClientPrvKey_ptr1, ClientPrvKeySize1, ClientPrvKey_ptr2, ClientPrvKeySize2, ServerPubKey_ptr1, ServerPubKeySize1, ServerPubKey_ptr2, ServerPubKeySize2, Prime_ptr, PrimeSize, otherInfo_ptr, hashFunc, tmpDhHybr_ptr, SecretKeyingData_ptr, SecretKeyingDataSize) CRYS_DH_X942_HybridGetSecretData ((ClientPrvKey_ptr1),(ClientPrvKeySize1),(ClientPrvKey_ptr2),(ClientPrvKeySize2),(ServerPubKey_ptr1),(ServerPubKeySize1),(ServerPubKey_ptr2),(ServerPubKeySize2),(Prime_ptr),(PrimeSize),(otherInfo_ptr),(hashFunc), CRYS_DH_ASN1_Der_mode ,(tmpDhHybr_ptr),(SecretKeyingData_ptr),(SecretKeyingDataSize))

#define	CRYS_DH_X942_HybridGetSecretDataConcat (ClientPrvKey_ptr1, ClientPrvKeySize1, ClientPrvKey_ptr2, ClientPrvKeySize2, ServerPubKey_ptr1, ServerPubKeySize1, ServerPubKey_ptr2, ServerPubKeySize2, Prime_ptr, PrimeSize, otherInfo_ptr, hashFunc, tmpDhHybr_ptr, SecretKeyingData_ptr, SecretKeyingDataSize) CRYS_DH_X942_HybridGetSecretData ((ClientPrvKey_ptr1),(ClientPrvKeySize1),(ClientPrvKey_ptr2),(ClientPrvKeySize2),(ServerPubKey_ptr1),(ServerPubKeySize1),(ServerPubKey_ptr2),(ServerPubKeySize2),(Prime_ptr),(PrimeSize),(otherInfo_ptr),(hashFunc), CRYS_DH_Concat_Der_mode ,(tmpDhHybr_ptr),(SecretKeyingData_ptr),(SecretKeyingDataSize))

Enumerations
enum	CRYS_DH_OpMode_t { CRYS_DH_PKCS3_mode = 0, CRYS_DH_ANSI_X942_mode = 1, CRYS_DH_NumOfModes , CRYS_DH_OpModeLast = 0x7FFFFFFF }

enum	CRYS_DH_HASH_OpMode_t { CRYS_DH_HASH_SHA1_mode = CRYS_HASH_SHA1_mode, CRYS_DH_HASH_SHA224_mode = CRYS_HASH_SHA224_mode, CRYS_DH_HASH_SHA256_mode = CRYS_HASH_SHA256_mode, CRYS_DH_HASH_SHA384_mode = CRYS_HASH_SHA384_mode, CRYS_DH_HASH_SHA512_mode = CRYS_HASH_SHA512_mode, CRYS_DH_HASH_MD5_mode = CRYS_HASH_MD5_mode, CRYS_DH_HASH_NumOfModes = CRYS_HASH_MD5_mode, CRYS_DH_HASH_OperationModeLast = 0x7FFFFFFF }

enum	CRYS_DH_DerivationFunc_Mode { CRYS_DH_ASN1_Der_mode = CRYS_KDF_ASN1_DerivMode, CRYS_DH_Concat_Der_mode = CRYS_KDF_ConcatDerivMode, CRYS_DH_X963_DerMode = CRYS_KDF_ConcatDerivMode, CRYS_DH_DerivationFunc_ModeLast = 0x7FFFFFFF }

Functions
CRYSError_t	_DX_DH_GeneratePubPrv (void rndState_ptr, SaSiRndGenerateVectWorkFunc_t rndGenerateVectFunc, uint8_t Generator_ptr, uint16_t GeneratorSize, uint8_t Prime_ptr, uint16_t PrimeSize, uint16_t L, uint8_t Q_ptr, uint16_t QSize, CRYS_DH_OpMode_t DH_mode, CRYS_RSAUserPubKey_t tmpPubKey_ptr, CRYS_RSAPrimeData_t tmpPrimeData_ptr, uint8_t ClientPrvKey_ptr, uint16_t ClientPrvKeySize_ptr, uint8_t ClientPub1_ptr, uint16_t ClientPubSize_ptr)
	This function has two purposes: More...

CRYSError_t	CRYS_DH_GetSecretKey (uint8_t ClientPrvKey_ptr, uint16_t ClientPrvKeySize, uint8_t ServerPubKey_ptr, uint16_t ServerPubKeySize, uint8_t Prime_ptr, uint16_t PrimeSize, CRYS_RSAUserPubKey_t tmpPubKey_ptr, CRYS_RSAPrimeData_t tmpPrimeData_ptr, uint8_t SecretKey_ptr, uint16_t *SecretKeySize_ptr)
	This function computes the shared secret key (value) accordng to [ANSI X9.42], 7.5.1: SecretKey = ServerPubKey ^ ClientPrvKey mod Prime. More...

CRYSError_t	CRYS_DH_X942_GetSecretData (uint8_t ClientPrvKey_ptr, uint16_t ClientPrvKeySize, uint8_t ServerPubKey_ptr, uint16_t ServerPubKeySize, uint8_t Prime_ptr, uint16_t PrimeSize, CRYS_KDF_OtherInfo_t otherInfo_ptr, CRYS_DH_HASH_OpMode_t hashMode, CRYS_DH_DerivationFunc_Mode DerivFunc_mode, CRYS_DH_Temp_t tmpBuff_ptr, uint8_t SecretKeyingData_ptr, uint16_t SecretKeyingDataSize)
	This function extracts the shared secret keying data from the shared secret value. It should be called by using macros CRYS_DH_X942_GetSecretDataAsn1 and CRYS_DH_X942_GetSecretDataConcat . More...

CRYSError_t	CRYS_DH_X942_HybridGetSecretData (uint8_t ClientPrvKey_ptr1, uint16_t ClientPrvKeySize1, uint8_t ClientPrvKey_ptr2, uint16_t ClientPrvKeySize2, uint8_t ServerPubKey_ptr1, uint16_t ServerPubKeySize1, uint8_t ServerPubKey_ptr2, uint16_t ServerPubKeySize2, uint8_t Prime_ptr, uint16_t PrimeSize, CRYS_KDF_OtherInfo_t otherInfo_ptr, CRYS_DH_HASH_OpMode_t hashMode, CRYS_DH_DerivationFunc_Mode DerivFunc_mode, CRYS_DH_HybrTemp_t tmpDhHybr_ptr, uint8_t SecretKeyingData_ptr, uint16_t SecretKeyingDataSize)
	The function computes shared secret data using two pairs of public and private keys: More...

CRYSError_t	CRYS_DH_CheckPubKey (uint8_t modP_ptr, uint32_t modPsizeBytes, uint8_t orderQ_ptr, uint32_t orderQsizeBytes, uint8_t pubKey_ptr, uint32_t pubKeySizeBytes, CRYS_DH_Temp_t tempBuff_ptr)
	The function checks the obtained DH public key according to its domain parameters [ANSI X9.42-2001]. More...

Detailed Description

Macro Definition Documentation

#define CRYS_DH_ANSI_X942_GeneratePubPrv	(	rndState_ptr,
		rndGenerateVectFunc,
		Generator_ptr,
		GeneratorSize,
		Prime_ptr,
		PrimeSize,
		Q_ptr,
		QSize,
		tmpPubKey_ptr,
		tmpPrimeData_ptr,
		ClientPrvKey_ptr,
		ClientPrvKeySize_ptr,
		ClientPub_ptr,
		ClientPubSize_ptr
	)

Value:

         
          _DX_DH_GeneratePubPrv
         
         (rndState_ptr, rndGenerateVectFunc, (Generator_ptr),(GeneratorSize),\
        
         (Prime_ptr),(PrimeSize),\
        
         (uint16_t)0,\
        
         (Q_ptr),(QSize),\
        
          CRYS_DH_ANSI_X942_mode
         
         ,\
        
         (tmpPubKey_ptr),(tmpPrimeData_ptr),\
        
         (ClientPrvKey_ptr),(ClientPrvKeySize_ptr),\
        
         (ClientPub_ptr),(ClientPubSize_ptr))

This macro is used to generate the public and private DH keys according to [ANSI X9.42]. For a description of the parameters see _DX_DH_GeneratePubPrv .

#define CRYS_DH_DOMAIN_GENERATION_MAX_SIZE_BITS CRYS_RSA_MAX_KEY_GENERATION_SIZE_BITS

Maximal domain generation size in bits.

#define CRYS_DH_MAX_MOD_BUFFER_SIZE_IN_WORDS ( CRYS_DH_MAX_MOD_SIZE_IN_WORDS + 2)

Modulus buffer size in words.

#define CRYS_DH_MAX_MOD_SIZE_IN_BYTES ( CRYS_DH_MAX_VALID_KEY_SIZE_VALUE_IN_BITS / SASI_BITS_IN_BYTE )

Maximal modulus size in bytes.

#define CRYS_DH_MAX_MOD_SIZE_IN_WORDS ( CRYS_DH_MAX_MOD_SIZE_IN_BYTES /sizeof(uint32_t))

Maximal modulus size in words.

#define CRYS_DH_MAX_SIZE_OF_KEYING_DATA CRYS_KDF_MAX_SIZE_OF_KEYING_DATA

Keying data size is in bytes

#define CRYS_DH_MAX_VALID_KEY_SIZE_VALUE_IN_BITS CRYS_RSA_MAX_VALID_KEY_SIZE_VALUE_IN_BITS

Maximal valid key size in bits.

#define CRYS_DH_MIN_VALID_KEY_SIZE_VALUE_IN_BITS 1024

Minimal valid key size in bits. Size limitation according to ANSI standard

#define CRYS_DH_OtherInfo_t CRYS_KDF_OtherInfo_t

Defintion for DH other info.

#define CRYS_DH_PKCS3_GeneratePubPrv	(	rndState_ptr,
		rndGenerateVectFunc,
		Generator_ptr,
		GeneratorSize,
		Prime_ptr,
		PrimeSize,
		L,
		tmpPubKey_ptr,
		tmpPrimeData_ptr,
		ClientPrvKey_ptr,
		ClientPrvKeySize_ptr,
		ClientPub_ptr,
		ClientPubSize_ptr
	)

Value:

         
          _DX_DH_GeneratePubPrv
         
         (rndState_ptr, rndGenerateVectFunc, (Generator_ptr),(GeneratorSize),\
        
         (Prime_ptr),(PrimeSize),\
        
         (L),\
        
         (uint8_t *)NULL,(uint16_t)0,\
        
          CRYS_DH_PKCS3_mode
         
         ,\
        
         (tmpPubKey_ptr),(tmpPrimeData_ptr),\
        
         (ClientPrvKey_ptr),(ClientPrvKeySize_ptr),\
        
         (ClientPub_ptr),(ClientPubSize_ptr))

This macro is used to generate the public and private DH keys according to [PKCS3]. For a description of the parameters see _DX_DH_GeneratePubPrv .

#define CRYS_DH_X942_GetSecretDataAsn1	(	ClientPrvKey_ptr,
		ClientPrvKeySize,
		ServerPubKey_ptr,
		ServerPubKeySize,
		Prime_ptr,
		PrimeSize,
		otherInfo_ptr,
		hashMode,
		tmpBuff_ptr,
		SecretKeyingData_ptr,
		SecretKeyingDataSize
	)	CRYS_DH_X942_GetSecretData ((ClientPrvKey_ptr),(ClientPrvKeySize),(ServerPubKey_ptr),(ServerPubKeySize),(Prime_ptr),(PrimeSize),(otherInfo_ptr),(hashMode),( CRYS_DH_ASN1_Der_mode ),(tmpBuff_ptr),(SecretKeyingData_ptr),(SecretKeyingDataSize))

This macro implements the DH [ANSI X9.42] standard. It derives a secret key using the Derivation function based on ASN.1. For a description of the parameters see CRYS_DH_X942_GetSecretData .

#define CRYS_DH_X942_GetSecretDataConcat	(	ClientPrvKey_ptr,
		ClientPrvKeySize,
		ServerPubKey_ptr,
		ServerPubKeySize,
		Prime_ptr,
		PrimeSize,
		otherInfo_ptr,
		hashMode,
		tmpBuff_ptr,
		SecretKeyingData_ptr,
		SecretKeyingDataSize
	)	CRYS_DH_X942_GetSecretData ((ClientPrvKey_ptr),(ClientPrvKeySize),(ServerPubKey_ptr),(ServerPubKeySize),(Prime_ptr),(PrimeSize),(otherInfo_ptr),(hashMode),( CRYS_DH_Concat_Der_mode ),(tmpBuff_ptr),(SecretKeyingData_ptr),(SecretKeyingDataSize))

This macro implements the DH [ANSI X9.42] standard. It derives a secret key using the Derivation function based on concatenation of HASHed data. For a description of the parameters see CRYS_DH_X942_GetSecretData .

#define CRYS_DH_X942_HybridGetSecretDataAsn1	(	ClientPrvKey_ptr1,
		ClientPrvKeySize1,
		ClientPrvKey_ptr2,
		ClientPrvKeySize2,
		ServerPubKey_ptr1,
		ServerPubKeySize1,
		ServerPubKey_ptr2,
		ServerPubKeySize2,
		Prime_ptr,
		PrimeSize,
		otherInfo_ptr,
		hashFunc,
		tmpDhHybr_ptr,
		SecretKeyingData_ptr,
		SecretKeyingDataSize
	)	CRYS_DH_X942_HybridGetSecretData ((ClientPrvKey_ptr1),(ClientPrvKeySize1),(ClientPrvKey_ptr2),(ClientPrvKeySize2),(ServerPubKey_ptr1),(ServerPubKeySize1),(ServerPubKey_ptr2),(ServerPubKeySize2),(Prime_ptr),(PrimeSize),(otherInfo_ptr),(hashFunc), CRYS_DH_ASN1_Der_mode ,(tmpDhHybr_ptr),(SecretKeyingData_ptr),(SecretKeyingDataSize))

This macro implements the DH [X9.42] standard deriving a hybrid secret key from two public-private pair of keys using the Derivation function based on ASN.1. For a description of the parameters see CRYS_DH_X942_HybridGetSecretData .

#define CRYS_DH_X942_HybridGetSecretDataConcat	(	ClientPrvKey_ptr1,
		ClientPrvKeySize1,
		ClientPrvKey_ptr2,
		ClientPrvKeySize2,
		ServerPubKey_ptr1,
		ServerPubKeySize1,
		ServerPubKey_ptr2,
		ServerPubKeySize2,
		Prime_ptr,
		PrimeSize,
		otherInfo_ptr,
		hashFunc,
		tmpDhHybr_ptr,
		SecretKeyingData_ptr,
		SecretKeyingDataSize
	)	CRYS_DH_X942_HybridGetSecretData ((ClientPrvKey_ptr1),(ClientPrvKeySize1),(ClientPrvKey_ptr2),(ClientPrvKeySize2),(ServerPubKey_ptr1),(ServerPubKeySize1),(ServerPubKey_ptr2),(ServerPubKeySize2),(Prime_ptr),(PrimeSize),(otherInfo_ptr),(hashFunc), CRYS_DH_Concat_Der_mode ,(tmpDhHybr_ptr),(SecretKeyingData_ptr),(SecretKeyingDataSize))

This macro implements the DH [X9.42] standard, deriving a hybrid secret key from two pairs of public-private keys, using the Derivation function based on concatenation using SHA-x HASH. For a description of the parameters see CRYS_DH_X942_HybridGetSecretData .

#define CRYS_DHPrimeData_t CRYS_RSAPrimeData_t

Defintion for DH primitives data.

#define CRYS_DHPubKey_t CRYSRSAPubKey_t

Defintion for DH public key.

#define CRYS_DHUserPubKey_t CRYS_RSAUserPubKey_t

Defintion for DH public key.

Enumeration Type Documentation

enum CRYS_DH_DerivationFunc_Mode

Key derivation modes.

Enumerator
CRYS_DH_ASN1_Der_mode	ASN1 derivation mode.
CRYS_DH_Concat_Der_mode	Concatination derivation mode.
CRYS_DH_X963_DerMode	X963 derivation mode.
CRYS_DH_DerivationFunc_ModeLast	Reserved.

enum CRYS_DH_HASH_OpMode_t

HASH operation modes

Enumerator
CRYS_DH_HASH_SHA1_mode	SHA1 operation mode.
CRYS_DH_HASH_SHA224_mode	SHA224 operation mode.
CRYS_DH_HASH_SHA256_mode	SHA256 operation mode.
CRYS_DH_HASH_SHA384_mode	SHA384 operation mode.
CRYS_DH_HASH_SHA512_mode	SHA512 operation mode.
CRYS_DH_HASH_MD5_mode	MD5 operation mode (not used in DH).
CRYS_DH_HASH_NumOfModes	Total number of HASH modes.
CRYS_DH_HASH_OperationModeLast	Reserved.

enum CRYS_DH_OpMode_t

DH operations mode

Enumerator
CRYS_DH_PKCS3_mode	PKCS3 operation mode.
CRYS_DH_ANSI_X942_mode	ANSI X942 operation mode.
CRYS_DH_NumOfModes	Total number of operation modes.
CRYS_DH_OpModeLast	Reserved.

Function Documentation

CRYSError_t _DX_DH_GeneratePubPrv	(	void *	rndState_ptr ,
		SaSiRndGenerateVectWorkFunc_t	rndGenerateVectFunc ,
		uint8_t *	Generator_ptr ,
		uint16_t	GeneratorSize ,
		uint8_t *	Prime_ptr ,
		uint16_t	PrimeSize ,
		uint16_t	L ,
		uint8_t *	Q_ptr ,
		uint16_t	QSize ,
		CRYS_DH_OpMode_t	DH_mode ,
		CRYS_RSAUserPubKey_t *	tmpPubKey_ptr ,
		CRYS_RSAPrimeData_t *	tmpPrimeData_ptr ,
		uint8_t *	ClientPrvKey_ptr ,
		uint16_t *	ClientPrvKeySize_ptr ,
		uint8_t *	ClientPub1_ptr ,
		uint16_t *	ClientPubSize_ptr
	)

This function has two purposes:

Randomly generate the client private key according to the choosen version [PKCS3] or [ANSI X9.42].
Computes the client public key as follows: ClientPub = Generator^Prv mod Prime, where '^' is the symbol of exponentiation.

This function should not be called directly. Instead, use the macros CRYS_DH_PKCS3_GeneratePubPrv and CRYS_DH_ANSI_X942_GeneratePubPrv .

Note: All buffer parameters should be in Big-Endian form.

Returns: CRYS_OK on success.; A non-zero value on failure as defined crys_dh_error.h, crys_rnd_error.h or crys_rsa_error.h.

Parameters

[in,out]	rndState_ptr	Pointer to the RND state structure.
[in]	rndGenerateVectFunc	Pointer to the random vector generation function.
[in]	Generator_ptr	Pointer to the Generator octet string.
[in]	GeneratorSize	The size of the Generator string (in bytes).
[in]	Prime_ptr	Pointer to the Prime octet string P (used as modulus in the algorithm).
[in]	PrimeSize	The size of the Prime string in bytes.
[in]	L	Exact size in bits of the Prime to be generated (relevant only for [PKCS3]): If L!=0, force the private key to be [2^(L-1) ? Prv < 2^L], where '^' indicates exponentiation. If L = 0 then [0 < Prv < P-1].
[in]	Q_ptr	Relevant only for [ANSI X9.42] - Pointer to the Q octet string in the range: 1 <= Prv <= Q-1 or 1 < Prv < Q-1.
[in]	QSize	Relevant only for [ANSI X9.42] - Size of the Q string (in bytes).
[in]	DH_mode	An enumerator declaring whether this is [PKCS3] or [ANSI X9.42] mode.
[in]	tmpPubKey_ptr	Pointer to a temporary buffer for public key structure. Used for the exponentiation function.
[in]	tmpPrimeData_ptr	Pointer to a structure holding internal temporary buffers.
[out]	ClientPrvKey_ptr	Pointer to the Private key Prv. This buffer should be at least the following size (in bytes): If L is provided: (L+7)/8. If L is NULL: `PrimeSize` .
[in,out]	ClientPrvKeySize_ptr	Pointer to the Private key size: Input - size of the given buffer. Output - actual size of the generated private key.
[out]	ClientPub1_ptr	Pointer to the Public key. This buffer should be at least `PrimeSize` bytes.
[in,out]	ClientPubSize_ptr	Pointer to the Public key size: Input - size of the given buffer. Output - actual size of the generated public key.

CRYSError_t CRYS_DH_CheckPubKey	(	uint8_t *	modP_ptr ,
		uint32_t	modPsizeBytes ,
		uint8_t *	orderQ_ptr ,
		uint32_t	orderQsizeBytes ,
		uint8_t *	pubKey_ptr ,
		uint32_t	pubKeySizeBytes ,
		CRYS_DH_Temp_t *	tempBuff_ptr
	)

The function checks the obtained DH public key according to its domain parameters [ANSI X9.42-2001].

Note: Assuming: The DH domain parameters are valid.

Returns: CRYS_OK on success.; A non-zero value on failure as defined in crys_dh_error.h.

Parameters

[in]	modP_ptr	The pointer to the modulus (prime) P.
[in]	modPsizeBytes	The modulus size in bytes.
[in]	orderQ_ptr	The pointer to the prime order Q of generator.
[in]	orderQsizeBytes	The size of order of generator in bytes.
[in]	pubKey_ptr	The pointer to the public key to be validated.
[in]	pubKeySizeBytes	The public key size in bytes.
[in]	tempBuff_ptr	The temp buffer for internal calculations.

CRYSError_t CRYS_DH_GetSecretKey	(	uint8_t *	ClientPrvKey_ptr ,
		uint16_t	ClientPrvKeySize ,
		uint8_t *	ServerPubKey_ptr ,
		uint16_t	ServerPubKeySize ,
		uint8_t *	Prime_ptr ,
		uint16_t	PrimeSize ,
		CRYS_RSAUserPubKey_t *	tmpPubKey_ptr ,
		CRYS_RSAPrimeData_t *	tmpPrimeData_ptr ,
		uint8_t *	SecretKey_ptr ,
		uint16_t *	SecretKeySize_ptr
	)

This function computes the shared secret key (value) accordng to [ANSI X9.42], 7.5.1: SecretKey = ServerPubKey ^ ClientPrvKey mod Prime.

Note

All buffer parameters should be in Big-Endian form.
The user must obtain assurance of validity of the public key, using one of methods, described in [ANSI X9.42] paragraph 7.4.
The actual size of the private key (in bits) must be not less than 2 and not greater than the actual size of the Prime (modulus in bits).

Returns: CRYS_OK on success.; A non-zero value on failure as defined in crys_dh_error.h or crys_rsa_error.h.

Parameters

[in]	ClientPrvKey_ptr	Pointer to the Private key octet string Prv < Prime.
[in]	ClientPrvKeySize	The Private key Size (in bytes).
[in]	ServerPubKey_ptr	Pointer to the Server public key octet string.
[in]	ServerPubKeySize	The Server Public key Size (in bytes).
[in]	Prime_ptr	Pointer to the Prime octet string.
[in]	PrimeSize	The size of the Prime string.
[in]	tmpPubKey_ptr	Pointer to the public key structure. Used for the exponentiation operation function. Need not be initialized.
[in]	tmpPrimeData_ptr	Pointer to a structure containing internal temp buffers.
[out]	SecretKey_ptr	Pointer to the secret key octet string. This buffer should be at least PrimeSize bytes.
[in,out]	SecretKeySize_ptr	Pointer to the secret key Buffer Size. This buffer should be at least of PrimeSize bytes: Input - size of the given buffer. Output - actual size.

CRYSError_t CRYS_DH_X942_GetSecretData	(	uint8_t *	ClientPrvKey_ptr ,
		uint16_t	ClientPrvKeySize ,
		uint8_t *	ServerPubKey_ptr ,
		uint16_t	ServerPubKeySize ,
		uint8_t *	Prime_ptr ,
		uint16_t	PrimeSize ,
		CRYS_KDF_OtherInfo_t *	otherInfo_ptr ,
		CRYS_DH_HASH_OpMode_t	hashMode ,
		CRYS_DH_DerivationFunc_Mode	DerivFunc_mode ,
		CRYS_DH_Temp_t *	tmpBuff_ptr ,
		uint8_t *	SecretKeyingData_ptr ,
		uint16_t	SecretKeyingDataSize
	)

This function extracts the shared secret keying data from the shared secret value. It should be called by using macros CRYS_DH_X942_GetSecretDataAsn1 and CRYS_DH_X942_GetSecretDataConcat .

Note

The "other info" argument and its AlgorithmID entry are mandatory only for ASN1 key derivation, and optional for the other derivation modes.
If used, all entries of the structure should be initialized with relevant data and size, prior to calling this function (entry size of empty fields must be set to 0).
All buffers arguments are represented in Big-Endian form.

Returns: CRYS_OK on success.; A non-zero value on failure as defined in crys_dh_error.h, crys_rsa_error.h, crys_kdf_error.h or crys_hash_error.h.

Parameters

[in]	ClientPrvKey_ptr	Pointer to the Private key octet string.
[in]	ClientPrvKeySize	The Private key size (in bytes).
[in]	ServerPubKey_ptr	Pointer to the Server public key octet string.
[in]	ServerPubKeySize	The Server Public key size (in bytes).
[in]	Prime_ptr	Pointer to the Prime octet string.
[in]	PrimeSize	The size of the Prime string.
[in]	otherInfo_ptr	Pointer to structure containing other data, shared by two entities sharing the secret keying data. The Maximal size of each data entry of "other info" is limited - see crys_kdf.h for the defined value.
[in]	hashMode	One of the supported SHA-x HASH modes. The supported modes are according to the supported HASH modes for the product (and MD5 is not supported).
[in]	DerivFunc_mode	The enumerator ID of key derivation function mode. ASN1 or Concatenation modes are supported.
[in]	tmpBuff_ptr	A pointer to the DH temp buffer structure. Not initialized.
[out]	SecretKeyingData_ptr	Pointer to the secret key octet string. This buffer should be at least PrimeSize bytes.
[in]	SecretKeyingDataSize	The required Secret Keying data size (in bytes). Must be larger than 0, and smaller than the maximal - CRYS_DH_MAX_SIZE_OF_KEYING_DATA.

CRYSError_t CRYS_DH_X942_HybridGetSecretData	(	uint8_t *	ClientPrvKey_ptr1 ,
		uint16_t	ClientPrvKeySize1 ,
		uint8_t *	ClientPrvKey_ptr2 ,
		uint16_t	ClientPrvKeySize2 ,
		uint8_t *	ServerPubKey_ptr1 ,
		uint16_t	ServerPubKeySize1 ,
		uint8_t *	ServerPubKey_ptr2 ,
		uint16_t	ServerPubKeySize2 ,
		uint8_t *	Prime_ptr ,
		uint16_t	PrimeSize ,
		CRYS_KDF_OtherInfo_t *	otherInfo_ptr ,
		CRYS_DH_HASH_OpMode_t	hashMode ,
		CRYS_DH_DerivationFunc_Mode	DerivFunc_mode ,
		CRYS_DH_HybrTemp_t *	tmpDhHybr_ptr ,
		uint8_t *	SecretKeyingData_ptr ,
		uint16_t	SecretKeyingDataSize
	)

The function computes shared secret data using two pairs of public and private keys:

SecretKey1 = ServerPubKey1^ClientPrvKey1 mod Prime.
SecretKey2 = ServerPubKey2^ClientPrvKey2 mod Prime.

It uses the Derivation function to derive secret keying data from the two secret keys (values). This function may be called directly, or by using macros CRYS_DH_X942_HybridGetSecretDataAsn1 and CRYS_DH_X942_HybridGetSecretDataConcat described above.

Note

The "other info" argument and its AlgorithmID entry are mandatory only for ASN1 key derivation, and optional for the other derivation modes. If used, all entries of the structure should be initialized with relevant data and size, prior to calling this function (entry size of empty fields must be set to 0).
All buffers arguments are represented in Big-Endian form.

Returns: CRYS_OK on success.; A non-zero value on failure as defined in crys_dh_error.h, crys_rsa_error.h or crys_hash_error.h.

Parameters

[in]	ClientPrvKey_ptr1	Pointer to the First Private key octet string number.
[in]	ClientPrvKeySize1	The First Private key Size (in bytes).
[in]	ClientPrvKey_ptr2	Pointer to the Second Private key octet string.
[in]	ClientPrvKeySize2	The Second Private key Size (in bytes).
[in]	ServerPubKey_ptr1	Pointer to the First Server public key octet string.
[in]	ServerPubKeySize1	The First Server Public key Size (in bytes).
[in]	ServerPubKey_ptr2	Pointer to the Second Server public key octet string.
[in]	ServerPubKeySize2	The Second Server Public key Size (in bytes).
[in]	Prime_ptr	Pointer to the Prime octet string.
[in]	PrimeSize	The size of the Prime string.
[in]	otherInfo_ptr	Pointer to structure containing optional other data, shared by two entities sharing the secret keying data.
[in]	hashMode	One of the supported SHA-x HASH modes. The supported modes are according to the supported HASH modes for the product (and MD5 is not supported).
[in]	DerivFunc_mode	The type of function to use to derive the secret key to the key data. ASN.1 or Concatenation modes are supported.
[in]	tmpDhHybr_ptr	Pointer to a CRYS_DH_Temp_t structure that contains temp buffers for internal operations.
[out]	SecretKeyingData_ptr	Pointer to the secret key octet string. This buffer should be at least of size PrimeSize bytes.
[in]	SecretKeyingDataSize	The required Secret Keying data size (in bytes). Must be larger than 0, and smaller than CRYS_DH_MAX_SIZE_OF_KEYING_DATA.

CryptoCell DH APIs

nRF5 SDK v17.1.0

Modules

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation