crys_dh

nRF5 SDK v14.0.0
Data Structures | Macros | Enumerations | Functions

This module defines the API that supports Diffie-Hellman key exchange, as defined in [PKCS3] and in [X9.42] (key lengths 1024 and 2048 bits). More...

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 / 8)
#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_COUNT_OF_OTHER_INFO_ENTRIES CRYS_KDF_COUNT_OF_OTHER_INFO_ENTRIES
#define CRYS_DH_MAX_SIZE_OF_OTHER_INFO_ENTRY CRYS_KDF_MAX_SIZE_OF_OTHER_INFO_ENTRY
#define CRYS_DH_MAX_SIZE_OF_KEYING_DATA CRYS_KDF_MAX_SIZE_OF_KEYING_DATA
#define CRYS_DH_PKCS3_GeneratePubPrv (rndContext_ptr, 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 (rndContext_ptr, 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 ( CRYS_RND_Context_t *rndContext_ptr, 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

This module defines the API that supports Diffie-Hellman key exchange, as defined in [PKCS3] and in [X9.42] (key lengths 1024 and 2048 bits).

Macro Definition Documentation

#define CRYS_DH_ANSI_X942_GeneratePubPrv ( rndContext_ptr,
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 (rndContext_ptr, (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_MAX_SIZE_OF_KEYING_DATA   CRYS_KDF_MAX_SIZE_OF_KEYING_DATA

Size is in bytes

#define CRYS_DH_MAX_SIZE_OF_OTHER_INFO_ENTRY CRYS_KDF_MAX_SIZE_OF_OTHER_INFO_ENTRY

Size is in bytes

#define CRYS_DH_MIN_VALID_KEY_SIZE_VALUE_IN_BITS   1024

Size limitation according to ANSI standard

#define CRYS_DH_PKCS3_GeneratePubPrv ( rndContext_ptr,
Generator_ptr,
GeneratorSize,
Prime_ptr,
PrimeSize,
L,
tmpPubKey_ptr,
tmpPrimeData_ptr,
ClientPrvKey_ptr,
ClientPrvKeySize_ptr,
ClientPub_ptr,
ClientPubSize_ptr
)
Value:
_DX_DH_GeneratePubPrv (rndContext_ptr, (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 .

Function Documentation

CRYSError_t _DX_DH_GeneratePubPrv ( CRYS_RND_Context_t * rndContext_ptr ,
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:

  1. Randomly generate the client private key according to the choosen version [PKCS3] or [ANSI X9.42].
  2. 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
Parameters
[in,out] rndContext_ptr Pointer to the RND context buffer.
[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.
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.
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 or crys_kdf_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.