bZRTP
bZRTP is an opensource implementation of ZRTP keys exchange protocol
Loading...
Searching...
No Matches
Macros | Functions | Variables
cryptoUtils.cc File Reference

Macros

#define BITS_PRO_INT   8*sizeof(int)
 
#define BITMASK_256_SIZE   256/BITS_PRO_INT
 
#define BITMASK_256_SET_ZERO(bitmask)   memset(bitmask, 0, sizeof(int)*BITMASK_256_SIZE)
 
#define BITMASK_256_SET(bitmask, value)   bitmask[value/BITS_PRO_INT] |= 1 << (value % BITS_PRO_INT)
 
#define BITMASK_256_UNSET(bitmask, value)   bitmask[value/BITS_PRO_INT] &= ~(1 << (value % BITS_PRO_INT))
 
#define BITMASK_256_CHECK(bitmask, value)   (bitmask[value/BITS_PRO_INT] & 1 << (value % BITS_PRO_INT))
 

Functions

static uint32_t bzrtp_key_agreement_algo_list (void)
 
uint8_t bzrtpUtils_getAllAvailableCryptoTypes (uint8_t algoType, uint8_t availableTypes[256])
 
uint8_t bzrtp_available_key_agreement (uint8_t algos[256])
 Retrieve the list of available key agreements algorithms.
 
bool_t bzrtp_is_PQ_available (void)
 check is Post Quantum algorithms are available
 
uint8_t bzrtpUtils_getAvailableCryptoTypes (uint8_t algoType, uint8_t availableTypes[7])
 
uint8_t bzrtpUtils_getMandatoryCryptoTypes (uint8_t algoType, uint8_t mandatoryTypes[7])
 
int bzrtp_keyDerivationFunction (const uint8_t *key, const size_t keyLength, const uint8_t *label, const size_t labelLength, const uint8_t *context, const size_t contextLength, const uint8_t hmacLength, void(*hmacFunction)(const uint8_t *, size_t, const uint8_t *, size_t, uint8_t, uint8_t *), uint8_t *output)
 ZRTP Key Derivation Function as in rfc 4.5.1.
 
void bzrtp_base32 (uint32_t sas, char *output, int outputSize)
 SAS rendering from 32 bits to 4 characters Function defined in rfc section 5.1.6.
 
void bzrtp_base256 (uint32_t sas, char *output, int outputSize)
 SAS rendering from 32 bits to pgp word list Function defined in rfc section 5.1.6.
 
uint32_t bzrtp_CRC32 (uint8_t *input, uint16_t length)
 CRC32 as defined in RFC4960 Appendix B - Polynomial is 0x1EDC6F41.
 
bool_t bzrtp_isPostQuantum (uint8_t keyAgreementAlgo)
 Check if the keyAgreementAlgo is a post quantum algorithm.
 
int bzrtp_cryptoAlgoAgreement (bzrtpContext_t *zrtpContext, bzrtpChannelContext_t *zrtpChannelContext, bzrtpHelloMessage_t *peerHelloMessage)
 select a key agreement algorithm from the one available in context and the one provided by peer in Hello Message as described in rfc section 4.1.2
 
int bzrtp_updateCryptoFunctionPointers (bzrtpChannelContext_t *zrtpChannelContext)
 Update context crypto function pointer according to related values of choosen algorithms fields (hashAlgo, cipherAlgo, etc..)
 
uint8_t bzrtp_selectCommonAlgo (uint8_t masterArray[7], uint8_t masterArrayLength, uint8_t *slaveArray, uint8_t slaveArrayLength, uint8_t commonArray[7])
 Select common algorithm from the given array where algo are represented by their 4 chars string defined in rfc section 5.1.2 to 5.1.6 Master array is the one given the preference order All algo are designed by their uint8_t mapped values.
 
void bzrtp_addMandatoryCryptoTypesIfNeeded (uint8_t algoType, uint8_t algoTypes[7], uint8_t *algoTypesCount)
 add mandatory crypto functions if they are not already included
 
uint8_t bzrtp_cryptoAlgoTypeStringToInt (uint8_t algoType[4], uint8_t algoFamily)
 Map the string description of algo type to an int defined in cryptoWrapper.h.
 
void bzrtp_cryptoAlgoTypeIntToString (uint8_t algoTypeInt, uint8_t algoTypeString[4])
 Unmap the string description of algo type to an int defined in cryptoWrapper.h.
 
void bzrtp_DestroyKey (uint8_t *key, size_t keyLength, void *rngContext)
 Destroy a key by setting it to a random number Key is not freed, caller must deal with memory management. Does nothing if the key pointer is NULL.
 
void bzrtp_destroyKeyMaterial (bzrtpContext_t *zrtpContext, bzrtpChannelContext_t *zrtpChannelContext)
 Destroy all the key material of a channel context.
 
static uint16_t bzrt_getKEMPublicKeyLength (uint8_t keyAgreementAlgo)
 
static uint16_t bzrt_getKEMCipherTextLength (uint8_t keyAgreementAlgo)
 
uint16_t bzrtp_computeKeyAgreementPublicValueLength (uint8_t keyAgreementAlgo, uint8_t messageType)
 
uint16_t bzrtp_computeKeyAgreementSharedSecretLength (uint8_t keyAgreementAlgo, uint8_t hashLength)
 
bool_t bzrtp_isKem (uint8_t keyAgreementAlgo)
 
uint16_t bzrtp_computeCommitMessageVariableLength (uint8_t keyAgreementAlgo)
 
static int bzrtp_getHashAlgoId (uint8_t hashAlgo)
 Convert the bzrtp hash id to its bctoolbox hash id.
 
bzrtp_KEMContext_tbzrtp_createKEMContext (uint8_t keyAgreementAlgo, uint8_t hashAlgo)
 
int bzrtp_KEM_generateKeyPair (bzrtp_KEMContext_t *ctx)
 
int bzrtp_KEM_getPublicKey (bzrtp_KEMContext_t *ctx, uint8_t *publicKey)
 
int bzrtp_KEM_getSharedSecret (bzrtp_KEMContext_t *ctx, uint8_t *sharedSecret)
 
int bzrtp_KEM_encaps (bzrtp_KEMContext_t *ctx, uint8_t *publicKey, uint8_t *cipherText)
 
int bzrtp_KEM_decaps (bzrtp_KEMContext_t *ctx, uint8_t *cipherText)
 
int bzrtp_destroyKEMContext (bzrtp_KEMContext_t *ctx)
 

Variables

uint32_t CRC32LookupTable [256]
 

Macro Definition Documentation

◆ BITMASK_256_CHECK

#define BITMASK_256_CHECK (   bitmask,
  value 
)    (bitmask[value/BITS_PRO_INT] & 1 << (value % BITS_PRO_INT))

◆ BITMASK_256_SET

#define BITMASK_256_SET (   bitmask,
  value 
)    bitmask[value/BITS_PRO_INT] |= 1 << (value % BITS_PRO_INT)

◆ BITMASK_256_SET_ZERO

#define BITMASK_256_SET_ZERO (   bitmask)    memset(bitmask, 0, sizeof(int)*BITMASK_256_SIZE)

◆ BITMASK_256_SIZE

#define BITMASK_256_SIZE   256/BITS_PRO_INT

◆ BITMASK_256_UNSET

#define BITMASK_256_UNSET (   bitmask,
  value 
)    bitmask[value/BITS_PRO_INT] &= ~(1 << (value % BITS_PRO_INT))

◆ BITS_PRO_INT

#define BITS_PRO_INT   8*sizeof(int)

Function Documentation

◆ bzrt_getKEMCipherTextLength()

static uint16_t bzrt_getKEMCipherTextLength ( uint8_t  keyAgreementAlgo)
static

Returns cipher text size in bytes for any supported KEM algo

Parameters
[in]keyAgreementAlgo
Returns
The cipher text size in bytes

◆ bzrt_getKEMPublicKeyLength()

static uint16_t bzrt_getKEMPublicKeyLength ( uint8_t  keyAgreementAlgo)
static

Returns public key size in bytes for any supported KEM algo

Parameters
[in]keyAgreementAlgo
Returns
The public key size in bytes

◆ bzrtp_addMandatoryCryptoTypesIfNeeded()

void bzrtp_addMandatoryCryptoTypesIfNeeded ( uint8_t  algoType,
uint8_t  algoTypes[7],
uint8_t algoTypesCount 
)

add mandatory crypto functions if they are not already included

  • Hash function
  • Cipher Block
  • Auth Tag
  • Key agreement
  • SAS
Parameters
[in]algoTypemapped to defines, must be in [ZRTP_HASH_TYPE, ZRTP_CIPHERBLOCK_TYPE, ZRTP_AUTHTAG_TYPE, ZRTP_KEYAGREEMENT_TYPE or ZRTP_SAS_TYPE]
[in,out]algoTypesmapped to uint8_t value of the 4 char strings giving the algo types as string according to rfc section 5.1.2 to 5.1.6
[in,out]algoTypesCountnumber of algo types

◆ bzrtp_available_key_agreement()

uint8_t bzrtp_available_key_agreement ( uint8_t  availableTypes[256])

Retrieve the list of available key agreements algorithms.

Parameters
[in/out]algos an array containing the list of available algorithms mapped on uint8 as defined in this header(ZRTP_KEYAGREEMENT_<ID>). Caller is responsible for the array allocation
Returns
The number of available key agreement algorithms

◆ bzrtp_base256()

void bzrtp_base256 ( uint32_t  sas,
char *  output,
int  outputSize 
)

SAS rendering from 32 bits to pgp word list Function defined in rfc section 5.1.6.

Parameters
[in]sasThe 32 bits SAS
[out]outputThe output list. Passed in array must be at least 32 bytes
[in]outputSizesize of the ouput buffer

◆ bzrtp_base32()

void bzrtp_base32 ( uint32_t  sas,
char *  output,
int  outputSize 
)

SAS rendering from 32 bits to 4 characters Function defined in rfc section 5.1.6.

Parameters
[in]sasThe 32 bits SAS
[out]outputThe 4 chars string to be displayed to user for vocal confirmation
[in]outputSizesize of the ouput buffer

◆ bzrtp_computeCommitMessageVariableLength()

uint16_t bzrtp_computeCommitMessageVariableLength ( uint8_t  keyAgreementAlgo)

Compute the variable size of data in a Commit message based on the given key agreement algorithm For DH types, it is the hvi size, for KEM types, it is the hvi size + public key size, for preShared or multistream the nonce size

Parameters
[in]keyAgreementAlgoa key agreement algo mapped on a uint8_t
Returns
the size in bytes of the variable part in a Commit message, 0 in case of unknown keyAgreementAlgo

◆ bzrtp_computeKeyAgreementPublicValueLength()

uint16_t bzrtp_computeKeyAgreementPublicValueLength ( uint8_t  keyAgreementAlgo,
uint8_t  messageTyoe 
)

Return the public value(public key or ciphertext) length in bytes according to given key agreement algorithm and packet type packet type is used to determine public value type when in KEM mode:

  • commit holds a public key
  • DHPart1 holds a ciphertext
  • DHPart2 holds a nonce
Parameters
[in]keyAgreementAlgoThe key agreement algo mapped to an integer as defined in cryptoUtils.h
[in]messageTypeMSGTYPE_COMMIT, MSGTYPE_DHPART1i or MSGTYPE_DHPART2: needed for KEM mode
Returns
the public value length in bytes

◆ bzrtp_computeKeyAgreementSharedSecretLength()

uint16_t bzrtp_computeKeyAgreementSharedSecretLength ( uint8_t  keyAgreementAlgo,
uint8_t  hashLength 
)

Return the shared secret size in bytes according to given key agreement algorithm

Parameters
[in]keyAgreementAlgoThe key agreement algo mapped to an integer as defined in cryptoUtils.h
Returns
the shared secrert length in bytes

◆ bzrtp_CRC32()

uint32_t bzrtp_CRC32 ( uint8_t input,
uint16_t  length 
)

CRC32 as defined in RFC4960 Appendix B - Polynomial is 0x1EDC6F41.

CRC is computed in reverse bit mode (least significant bit first within each byte) reversed value of polynom (0x82F63B78) was used to compute the lookup table (source http://en.wikipedia.org/wiki/Cyclic_redundancy_check#Commonly_used_and_standardized_CRCs)

Parameters
[in]inputinput data
[in]lengthlength of data in bytes
Returns
the 32 bits CRC value

◆ bzrtp_createKEMContext()

bzrtp_KEMContext_t * bzrtp_createKEMContext ( uint8_t  keyAgreementAlgo,
uint8_t  hashAlgo 
)

Create the KEM context

Parameters
[in]keyAgreementAlgoone of ZRTP_KEYAGREEMENT_KYB1, ZRTP_KEYAGREEMENT_KYB2, ZRTP_KEYAGREEMENT_KYB3, ZRTP_KEYAGREEMENT_HQC1, ZRTP_KEYAGREEMENT_HQC2, ZRTP_KEYAGREEMENT_HQC3, ZRTP_KEYAGREEMENT_K255_KYB512, ZRTP_KEYAGREEMENT_K255_HQC128, ZRTP_KEYAGREEMENT_K448_KYB1024, ZRTP_KEYAGREEMENT_K448_HQC256 ZRTP_KEYAGREEMENT_K255_KYB512_HQC128, ZRTP_KEYAGREEMENT_K448_KYB1024_HQC256,
Returns
a pointer to the created context, NULL in case of failure

◆ bzrtp_cryptoAlgoAgreement()

int bzrtp_cryptoAlgoAgreement ( bzrtpContext_t zrtpContext,
bzrtpChannelContext_t zrtpChannelContext,
bzrtpHelloMessage_t peerHelloMessage 
)

select a key agreement algorithm from the one available in context and the one provided by peer in Hello Message as described in rfc section 4.1.2

  • other algorithm are selected according to availability and selected key agreement as described in rfc section 5.1.5 The other algorithm choice will finally be set by the endpoint acting as initiator in the commit packet
Parameters
[in]zrtpContextThe context contains the list of available algo
[out]zrtpChannelContextThe bzrtp channel context to be updated
[in]peerHelloMessageThe peer hello message containing his set of available algos

return 0 on succes, error code otherwise

◆ bzrtp_cryptoAlgoTypeIntToString()

void bzrtp_cryptoAlgoTypeIntToString ( uint8_t  algoTypeInt,
uint8_t  algoTypeString[4] 
)

Unmap the string description of algo type to an int defined in cryptoWrapper.h.

Parameters
[in]algoTypeIntThe integer algo type defined in crypoWrapper.h
[in]algoTypeStringThe string code for the algorithm as defined in rfc 5.1.2 to 5.1.6

◆ bzrtp_cryptoAlgoTypeStringToInt()

uint8_t bzrtp_cryptoAlgoTypeStringToInt ( uint8_t  algoType[4],
uint8_t  algoFamily 
)

Map the string description of algo type to an int defined in cryptoWrapper.h.

Parameters
[in]algoTypeA 4 chars string containing the algo type as listed in rfc sections 5.1.2 to 5.1.6
[in]algoFamilyThe integer mapped algo family (ZRTP_HASH_TYPE, ZRTP_CIPHERBLOCK_TYPE, ZRTP_AUTHTAG_TYPE, ZRTP_KEYAGREEMENT_TYPE or ZRTP_SAS_TYPE)
Returns
The int value mapped to the algo type, ZRTP_UNSET_ALGO on error

◆ bzrtp_destroyKEMContext()

int bzrtp_destroyKEMContext ( bzrtp_KEMContext_t ctx)

Destroy a KEM context. Safely clean any secrets it may holding

Parameters
[in]ctxa valid KEM context
Returns
0 on success

◆ bzrtp_DestroyKey()

void bzrtp_DestroyKey ( uint8_t key,
size_t  keyLength,
void *  rngContext 
)

Destroy a key by setting it to a random number Key is not freed, caller must deal with memory management. Does nothing if the key pointer is NULL.

Parameters
[in,out]keyThe key to be destroyed
[in]keyLengthThe keyLength in bytes
[in]rngContextThe context for RNG

◆ bzrtp_destroyKeyMaterial()

void bzrtp_destroyKeyMaterial ( bzrtpContext_t zrtpContext,
bzrtpChannelContext_t zrtpChannelContext 
)

Destroy all the key material of a channel context.

Parameters
[in,out]zrtpContextThe zrtp context
[in,out]zrtpChannelContextThe channel context

◆ bzrtp_getHashAlgoId()

static int bzrtp_getHashAlgoId ( uint8_t  hashAlgo)
static

Convert the bzrtp hash id to its bctoolbox hash id.

Parameters
[in]hashAlgobzrtp hash id
Returns
The bctoolbox hash id

◆ bzrtp_is_PQ_available()

bool_t bzrtp_is_PQ_available ( void  )

check is Post Quantum algorithms are available

Returns
TRUE when PQ key exchange algorithms are available, FALSE otherwise

◆ bzrtp_isKem()

bool_t bzrtp_isKem ( uint8_t  keyAgreementAlgo)

Check a given key agrement algorithm is a KEM or not

Parameters
[in]keyAgreementAlgoa key agreement algo mapped on a uint8_t
Returns
TRUE if the algorithm is of type KEM, FALSE otherwise

◆ bzrtp_isPostQuantum()

bool_t bzrtp_isPostQuantum ( uint8_t  keyAgreementAlgo)

Check if the keyAgreementAlgo is a post quantum algorithm.

Parameters
[in]keyAgreementAlgoThe key agreement algorithm
Returns
TRUE if the keyAgreementAlgo is a post quantum algorithm

◆ bzrtp_KEM_decaps()

int bzrtp_KEM_decaps ( bzrtp_KEMContext_t ctx,
uint8_t cipherText 
)

Decapsulate a key, shared secret is stored in the context

Parameters
[in]ctxa valid KEM context holding the secret Key needed to decapsulate
[in]cipherTextthe encapsulated secret
Returns
0 on success

◆ bzrtp_KEM_encaps()

int bzrtp_KEM_encaps ( bzrtp_KEMContext_t ctx,
uint8_t publicKey,
uint8_t cipherText 
)

Generate and encapsulate a secret given a public key, shared secret is stored in the context

Parameters
[in]ctxa valid KEM context
[in]publicKeythe public key we want to encapsulate to
[out]cipherTextthe encapsulated secret
Returns
0 on success

◆ bzrtp_KEM_generateKeyPair()

int bzrtp_KEM_generateKeyPair ( bzrtp_KEMContext_t ctx)

Generate a key pair and store it in the context

Returns
0 on success

◆ bzrtp_KEM_getPublicKey()

int bzrtp_KEM_getPublicKey ( bzrtp_KEMContext_t ctx,
uint8_t publicKey 
)

Extract the public key from context

Parameters
[in]ctxa valid KEM context
[out]publicKeythe key in this context. Data is copied in this buffer, caller must ensure it is the correct size
Returns
0 on success

◆ bzrtp_KEM_getSharedSecret()

int bzrtp_KEM_getSharedSecret ( bzrtp_KEMContext_t ctx,
uint8_t sharedSecret 
)

Extract the shared secret from context

Parameters
[in]ctxa valid KEM context
[out]sharedSecretthe shared secret in this context. Data is copied in this buffer, caller must ensure it is the correct size
Returns
0 on success

◆ bzrtp_key_agreement_algo_list()

static uint32_t bzrtp_key_agreement_algo_list ( void  )
static

◆ bzrtp_keyDerivationFunction()

int bzrtp_keyDerivationFunction ( const uint8_t key,
const size_t  keyLength,
const uint8_t label,
const size_t  labelLength,
const uint8_t context,
const size_t  contextLength,
const uint8_t  hmacLength,
void(*)(const uint8_t *, size_t, const uint8_t *, size_t, uint8_t, uint8_t *)  hmacFunction,
uint8_t output 
)

ZRTP Key Derivation Function as in rfc 4.5.1.

KDF(KI, Label, Context, L) = HMAC(KI, i || Label || 0x00 || Context || L) where

  • i is a 32-bits integer fixed to 0x00000001
  • L is a 32-bit big-endian positive integer, not to exceed the length in bits of the output of the HMAC. The output of the KDF is truncated to the leftmost L bits.
Parameters
[in]keyThe key for HMAC
[in]keyLengthLength of the key in bytes
[in]labelA string to be included in the hash
[in]labelLengthLength of the label in bytes
[in]contexta context string for the key derivation
[in]contextLengthLength of the context string in bytes
[in]hmacLengthThe output of the KDF is the HMAC truncated to the leftmost L bytes
[in]hmacFunctionThe hashmac function to be used to compute the KDF
[out]outputA buffer to store the hmacLength bytes of output
Returns
0 on succes, error code otherwise

◆ bzrtp_selectCommonAlgo()

uint8_t bzrtp_selectCommonAlgo ( uint8_t  masterArray[7],
uint8_t  masterArrayLength,
uint8_t slaveArray,
uint8_t  slaveArrayLength,
uint8_t  commonArray[7] 
)

Select common algorithm from the given array where algo are represented by their 4 chars string defined in rfc section 5.1.2 to 5.1.6 Master array is the one given the preference order All algo are designed by their uint8_t mapped values.

Parameters
[in]masterArrayThe ordered available algo, result will follow this ordering
[in]masterArrayLengthNumber of valids element in the master array
[in]slaveArrayThe available algo, order is not taken in account
[in]slaveArrayLengthNumber of valids element in the slave array
[out]commonArrayCommon algorithms found, max size 7
Returns
the number of common algorithms found

◆ bzrtp_updateCryptoFunctionPointers()

int bzrtp_updateCryptoFunctionPointers ( bzrtpChannelContext_t zrtpChannelContext)

Update context crypto function pointer according to related values of choosen algorithms fields (hashAlgo, cipherAlgo, etc..)

Parameters
[in,out]zrtpChannelContextThe bzrtp channel context to be updated
Returns
0 on succes

◆ bzrtpUtils_getAllAvailableCryptoTypes()

uint8_t bzrtpUtils_getAllAvailableCryptoTypes ( uint8_t  algoType,
uint8_t  availableTypes[256] 
)

Return available crypto functions. WARNING: this function can return more than 7 items, do not use it for something else than checking the values forced by bzrtp_setSupportedCryptoTypes

◆ bzrtpUtils_getAvailableCryptoTypes()

uint8_t bzrtpUtils_getAvailableCryptoTypes ( uint8_t  algoType,
uint8_t  availableTypes[7] 
)

Return available crypto functions. If more than 7 are available, returns the 7 first

  • Hash: HMAC-SHA256(Mandatory), HMAC-SHA384
  • CipherBlock: AES128(Mandatory), AES256
  • Auth Tag: HMAC-SHA132 and HMAC-SHA180 (These are mandatory for SRTP and depends on the SRTP implementation thus we can just suppose they are both available)
  • Key Agreement: DHM3k(Mandatory), DHM2k(optional and shall not be used except on low power devices), X25519, X448
  • Sas: base32(Mandatory), b256(pgp words)

◆ bzrtpUtils_getMandatoryCryptoTypes()

uint8_t bzrtpUtils_getMandatoryCryptoTypes ( uint8_t  algoType,
uint8_t  mandatoryTypes[7] 
)

Return mandatory crypto functions. For now we have

  • Hash: HMAC-SHA256
  • CipherBlock: AES128
  • Auth Tag: HMAC-SHA132 and HMAC-SHA180
  • Key Agreement: DHM3k
  • Sas: base32

Variable Documentation

◆ CRC32LookupTable

uint32_t CRC32LookupTable[256]