Knight KE / Mbed OS Game_Master

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Embed: (wiki syntax)

« Back to documentation index

CryptoCell DH APIs
Data Structures | Modules | Enumerations | Functions

CryptoCell DH APIs

Data Structures

struct  CRYS_DH_ExpTemp_t
struct  CRYS_DH_Temp_t
struct  CRYS_DH_HybrTemp_t
struct  CRYS_DH_FipsKat_t

Modules

 CryptoCell DH specific errors
 CryptoCell DH Key Generation APIs

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

CIMPORT_C 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_DHUserPubKey_t *tmpPubKey_ptr, CRYS_DHPrimeData_t *tmpPrimeData_ptr, uint8_t *ClientPrvKey_ptr, uint16_t *ClientPrvKeySize_ptr, uint8_t *ClientPub1_ptr, uint16_t *ClientPubSize_ptr)
 This function has two purposes:
CIMPORT_C 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_DHUserPubKey_t *tmpPubKey_ptr, CRYS_DHPrimeData_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.
CIMPORT_C 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_DH_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.
CIMPORT_C 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_DH_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:
CIMPORT_C 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].

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.

Definition at line 128 of file crys_dh.h.

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.

Definition at line 106 of file crys_dh.h.

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.

Definition at line 91 of file crys_dh.h.

Function Documentation

CIMPORT_C 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_DHUserPubKey_t *  tmpPubKey_ptr,
CRYS_DHPrimeData_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, crys_rnd_error.h or crys_rsa_error.h.
Parameters:
[in,out]rndState_ptrPointer to the RND state structure.
[in]rndGenerateVectFuncPointer to the random vector generation function.
[in]Generator_ptrPointer to the Generator octet string.
[in]GeneratorSizeThe size of the Generator string (in bytes).
[in]Prime_ptrPointer to the Prime octet string P (used as modulus in the algorithm).
[in]PrimeSizeThe size of the Prime string in bytes.
[in]LExact 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_ptrRelevant only for [ANSI X9.42] - Pointer to the Q octet string in the range: 1 <= Prv <= Q-1 or 1 < Prv < Q-1.
[in]QSizeRelevant only for [ANSI X9.42] - Size of the Q string (in bytes).
[in]DH_modeAn enumerator declaring whether this is [PKCS3] or [ANSI X9.42] mode.
[in]tmpPubKey_ptrPointer to a temporary buffer for public key structure. Used for the exponentiation function.
[in]tmpPrimeData_ptrPointer to a structure holding internal temporary buffers.
[out]ClientPrvKey_ptrPointer 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_ptrPointer to the Private key size:

  • Input - size of the given buffer.
  • Output - actual size of the generated private key.
[out]ClientPub1_ptrPointer to the Public key. This buffer should be at least PrimeSize bytes.
[in,out]ClientPubSize_ptrPointer to the Public key size:

  • Input - size of the given buffer.
  • Output - actual size of the generated public key.
CIMPORT_C 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_ptrThe pointer to the modulus (prime) P.
[in]modPsizeBytesThe modulus size in bytes.
[in]orderQ_ptrThe pointer to the prime order Q of generator.
[in]orderQsizeBytesThe size of order of generator in bytes.
[in]pubKey_ptrThe pointer to the public key to be validated.
[in]pubKeySizeBytesThe public key size in bytes.
[in]tempBuff_ptrThe temp buffer for internal calculations.
CIMPORT_C 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_DHUserPubKey_t *  tmpPubKey_ptr,
CRYS_DHPrimeData_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_ptrPointer to the Private key octet string Prv < Prime.
[in]ClientPrvKeySizeThe Private key Size (in bytes).
[in]ServerPubKey_ptrPointer to the Server public key octet string.
[in]ServerPubKeySizeThe Server Public key Size (in bytes).
[in]Prime_ptrPointer to the Prime octet string.
[in]PrimeSizeThe size of the Prime string.
[in]tmpPubKey_ptrPointer to the public key structure. Used for the exponentiation operation function. Need not be initialized.
[in]tmpPrimeData_ptrPointer to a structure containing internal temp buffers.
[out]SecretKey_ptrPointer to the secret key octet string. This buffer should be at least PrimeSize bytes.
[in,out]SecretKeySize_ptrPointer to the secret key Buffer Size. This buffer should be at least of PrimeSize bytes:

  • Input - size of the given buffer.
  • Output - actual size.
CIMPORT_C 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_DH_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_ptrPointer to the Private key octet string.
[in]ClientPrvKeySizeThe Private key size (in bytes).
[in]ServerPubKey_ptrPointer to the Server public key octet string.
[in]ServerPubKeySizeThe Server Public key size (in bytes).
[in]Prime_ptrPointer to the Prime octet string.
[in]PrimeSizeThe size of the Prime string.
[in]otherInfo_ptrPointer 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]hashModeOne 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_modeThe enumerator ID of key derivation function mode. ASN1 or Concatenation modes are supported.
[in]tmpBuff_ptrA pointer to the DH temp buffer structure. Not initialized.
[out]SecretKeyingData_ptrPointer to the secret key octet string. This buffer should be at least PrimeSize bytes.
[in]SecretKeyingDataSizeThe required Secret Keying data size (in bytes). Must be larger than 0, and smaller than the maximal - CRYS_DH_MAX_SIZE_OF_KEYING_DATA.
CIMPORT_C 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_DH_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_ptr1Pointer to the First Private key octet string number.
[in]ClientPrvKeySize1The First Private key Size (in bytes).
[in]ClientPrvKey_ptr2Pointer to the Second Private key octet string.
[in]ClientPrvKeySize2The Second Private key Size (in bytes).
[in]ServerPubKey_ptr1Pointer to the First Server public key octet string.
[in]ServerPubKeySize1The First Server Public key Size (in bytes).
[in]ServerPubKey_ptr2Pointer to the Second Server public key octet string.
[in]ServerPubKeySize2The Second Server Public key Size (in bytes).
[in]Prime_ptrPointer to the Prime octet string.
[in]PrimeSizeThe size of the Prime string.
[in]otherInfo_ptrPointer to structure containing optional other data, shared by two entities sharing the secret keying data.
[in]hashModeOne 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_modeThe type of function to use to derive the secret key to the key data. ASN.1 or Concatenation modes are supported.
[in]tmpDhHybr_ptrPointer to a CRYS_DH_Temp_t structure that contains temp buffers for internal operations.
[out]SecretKeyingData_ptrPointer to the secret key octet string. This buffer should be at least of size PrimeSize bytes.
[in]SecretKeyingDataSizeThe required Secret Keying data size (in bytes). Must be larger than 0, and smaller than CRYS_DH_MAX_SIZE_OF_KEYING_DATA.
Generated on Tue Jul 12 2022 12:46:36 by  doxygen 1.7.2