bZRTP
bZRTP is an opensource implementation of ZRTP keys exchange protocol
Loading...
Searching...
No Matches
Macros | Typedefs | 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
 

Typedefs

typedef struct bzrtp_KEMContext_struct bzrtp_KEMContext_t
 

Functions

uint8_t bzrtpUtils_getAvailableCryptoTypes (uint8_t algoType, uint8_t availableTypes[7])
 
uint8_t bzrtpUtils_getAllAvailableCryptoTypes (uint8_t algoType, uint8_t availableTypes[256])
 
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 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.
 
BZRTP_EXPORT 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.
 
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
 
BZRTP_EXPORT 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.
 
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
 
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.
 
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.
 
BZRTP_EXPORT 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.
 
BZRTP_EXPORT uint16_t bzrtp_computeKeyAgreementPublicValueLength (uint8_t keyAgreementAlgo, uint8_t messageTyoe)
 
uint16_t bzrtp_computeKeyAgreementSharedSecretLength (uint8_t keyAgreementAlgo, uint8_t hashLength)
 
bool_t bzrtp_isKem (uint8_t keyAgreementAlgo)
 
uint16_t bzrtp_computeCommitMessageVariableLength (uint8_t keyAgreementAlgo)
 
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)
 

Macro Definition Documentation

◆ ZRTP_CRYPTOAGREEMENT_INVALIDAUTHTAG

#define ZRTP_CRYPTOAGREEMENT_INVALIDAUTHTAG   0x1007

◆ ZRTP_CRYPTOAGREEMENT_INVALIDCIPHER

#define ZRTP_CRYPTOAGREEMENT_INVALIDCIPHER   0x1005

◆ ZRTP_CRYPTOAGREEMENT_INVALIDCONTEXT

#define ZRTP_CRYPTOAGREEMENT_INVALIDCONTEXT   0x1001

◆ ZRTP_CRYPTOAGREEMENT_INVALIDHASH

#define ZRTP_CRYPTOAGREEMENT_INVALIDHASH   0x1006

◆ ZRTP_CRYPTOAGREEMENT_INVALIDMESSAGE

#define ZRTP_CRYPTOAGREEMENT_INVALIDMESSAGE   0x1002

◆ ZRTP_CRYPTOAGREEMENT_INVALIDSAS

#define ZRTP_CRYPTOAGREEMENT_INVALIDSAS   0x1008

◆ ZRTP_CRYPTOAGREEMENT_INVALIDSELFALGO

#define ZRTP_CRYPTOAGREEMENT_INVALIDSELFALGO   0x1003

◆ ZRTP_CRYPTOAGREEMENT_NOCOMMONALGOFOUND

#define ZRTP_CRYPTOAGREEMENT_NOCOMMONALGOFOUND   0x1004

Typedef Documentation

◆ bzrtp_KEMContext_t

typedef struct bzrtp_KEMContext_struct bzrtp_KEMContext_t

Function Documentation

◆ bzrtp_addMandatoryCryptoTypesIfNeeded()

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

◆ 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()

BZRTP_EXPORT 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()

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_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()

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_cryptoAlgoTypeIntToString()

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_cryptoAlgoTypeStringToInt()

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_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()

BZRTP_EXPORT 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_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_keyDerivationFunction()

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

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

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