bZRTP
bZRTP is an opensource implementation of ZRTP keys exchange protocol
Macros | Functions
cryptoUtils.h File Reference

Go to the source code of this file.

Macros

#define ZRTP_CRYPTOAGREEMENT_INVALIDCONTEXT   0x1001
 
#define ZRTP_CRYPTOAGREEMENT_INVALIDMESSAGE   0x1002
 
#define ZRTP_CRYPTOAGREEMENT_INVALIDSELFALGO   0x1003
 
#define ZRTP_CRYPTOAGREEMENT_NOCOMMONALGOFOUND   0x1004
 
#define ZRTP_CRYPTOAGREEMENT_INVALIDCIPHER   0x1005
 
#define ZRTP_CRYPTOAGREEMENT_INVALIDHASH   0x1006
 
#define ZRTP_CRYPTOAGREEMENT_INVALIDAUTHTAG   0x1007
 
#define ZRTP_CRYPTOAGREEMENT_INVALIDSAS   0x1008
 

Functions

uint8_t bzrtpUtils_getAvailableCryptoTypes (uint8_t algoType, uint8_t availableTypes[7])
 
BZRTP_EXPORT 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...
 
BZRTP_EXPORT uint32_t bzrtp_CRC32 (uint8_t *input, uint16_t length)
 CRC32 as defined in RFC4960 Appendix B - Polynomial is 0x1EDC6F41. More...
 
BZRTP_EXPORT 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...
 
BZRTP_EXPORT 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...
 
BZRTP_EXPORT void bzrtp_addMandatoryCryptoTypesIfNeeded (uint8_t algoType, uint8_t algoTypes[7], uint8_t *algoTypesCount)
 add mandatory crypto functions if they are not already included More...
 
BZRTP_EXPORT 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...
 
BZRTP_EXPORT 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...
 
BZRTP_EXPORT 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...
 

Macro Definition Documentation

#define ZRTP_CRYPTOAGREEMENT_INVALIDAUTHTAG   0x1007
#define ZRTP_CRYPTOAGREEMENT_INVALIDCIPHER   0x1005
#define ZRTP_CRYPTOAGREEMENT_INVALIDCONTEXT   0x1001
#define ZRTP_CRYPTOAGREEMENT_INVALIDHASH   0x1006
#define ZRTP_CRYPTOAGREEMENT_INVALIDMESSAGE   0x1002
#define ZRTP_CRYPTOAGREEMENT_INVALIDSAS   0x1008
#define ZRTP_CRYPTOAGREEMENT_INVALIDSELFALGO   0x1003
#define ZRTP_CRYPTOAGREEMENT_NOCOMMONALGOFOUND   0x1004

Function Documentation

BZRTP_EXPORT 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]
BZRTP_EXPORT 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_EXPORT 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_EXPORT 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_EXPORT 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_EXPORT 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
BZRTP_EXPORT 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
BZRTP_EXPORT 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)
  • 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)
  • Sas: base32(Mandatory), b256(pgp words)

    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 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