bZRTP
bZRTP is an opensource implementation of ZRTP keys exchange protocol
Macros | Functions | Variables
cryptoUtils.c 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

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 uint16_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. More...
 
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. More...
 
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. More...
 
uint32_t bzrtp_CRC32 (uint8_t *input, uint16_t length)
 CRC32 as defined in RFC4960 Appendix B - Polynomial is 0x1EDC6F41. More...
 
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 More...
 
int bzrtp_updateCryptoFunctionPointers (bzrtpChannelContext_t *zrtpChannelContext)
 Update context crypto function pointer according to related values of choosen algorithms fields (hashAlgo, cipherAlgo, etc..) More...
 
uint8_t selectCommonAlgo (uint8_t masterArray[7], uint8_t masterArrayLength, uint8_t slaveArray[7], 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. More...
 
void bzrtp_addMandatoryCryptoTypesIfNeeded (uint8_t algoType, uint8_t algoTypes[7], uint8_t *algoTypesCount)
 add mandatory crypto functions if they are not already included More...
 
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. More...
 
void bzrtp_cryptoAlgoTypeIntToString (uint8_t algoTypeInt, uint8_t algoTypeString[4])
 Unmap the string description of algo type to an int defined in cryptoWrapper.h. More...
 
void bzrtp_DestroyKey (uint8_t *key, uint8_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. More...
 
void bzrtp_strToUint8 (uint8_t *outputBytes, uint8_t *inputString, uint16_t inputStringLength)
 Convert an hexadecimal string into the corresponding byte buffer. More...
 
void bzrtp_int8ToStr (uint8_t *outputString, uint8_t *inputBytes, uint16_t inputBytesLength)
 Convert a byte buffer into the corresponding hexadecimal string. More...
 
uint8_t bzrtp_charToByte (uint8_t inputChar)
 convert an hexa char [0-9a-fA-F] into the corresponding unsigned integer value Any invalid char will be converted to zero without any warning More...
 
uint8_t bzrtp_byteToChar (uint8_t inputByte)
 convert a byte which value is in range [0-15] into an hexa char [0-9a-fA-F] More...
 

Variables

uint32_t CRC32LookupTable [256]
 

Macro Definition Documentation

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

Function Documentation

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
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
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
uint8_t bzrtp_byteToChar ( uint8_t  inputByte)

convert a byte which value is in range [0-15] into an hexa char [0-9a-fA-F]

Parameters
[in]inputBytean integer which shall be in range [0-15]
Returns
the hexa char [0-9a-f] corresponding to the input
uint8_t bzrtp_charToByte ( uint8_t  inputChar)

convert an hexa char [0-9a-fA-F] into the corresponding unsigned integer value Any invalid char will be converted to zero without any warning

Parameters
[in]inputChara char which shall be in range [0-9a-fA-F]
Returns
the unsigned integer value in range [0-15]
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
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

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
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
void bzrtp_DestroyKey ( uint8_t key,
uint8_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
void bzrtp_int8ToStr ( uint8_t outputString,
uint8_t inputBytes,
uint16_t  inputBytesLength 
)

Convert a byte buffer into the corresponding hexadecimal string.

Parameters
[out]outputStringThe output string buffer, must have a length of twice the input bytes buffer
[in]inputBytesThe input bytes buffer
[in]inputBytesLengthThe length in bytes buffer, output is twice this length
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 uint16_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
void bzrtp_strToUint8 ( uint8_t outputBytes,
uint8_t inputString,
uint16_t  inputStringLength 
)

Convert an hexadecimal string into the corresponding byte buffer.

Parameters
[out]outputBytesThe output bytes buffer, must have a length of half the input string buffer
[in]inputStringThe input string buffer, must be hexadecimal(it is not checked by function, any non hexa char is converted to 0)
[in]inputStringLengthThe length in chars of the string buffer, output is half this length
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
uint8_t bzrtpUtils_getAvailableCryptoTypes ( uint8_t  algoType,
uint8_t  availableTypes[7] 
)

Return available crypto functions. For now we have

  • Hash: HMAC-SHA256(Mandatory)
  • CipherBlock: AES128(Mandatory), AES256(optional)
  • 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: ECDH25519(not mentionned in RFC), ECDH448(not mentionned in RFC), DHM3k(Mandatory), DHM2k(optional and shall not be used except on low power devices)
  • Sas: base32(Mandatory), b256(pgp words, optional)
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
uint8_t selectCommonAlgo ( uint8_t  masterArray[7],
uint8_t  masterArrayLength,
uint8_t  slaveArray[7],
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

Variable Documentation

uint32_t CRC32LookupTable[256]