# Intel® Enhanced Privacy ID SDK: common

common
epid

Common code shared between core sub-components. More...

## Modules

| math
| Math Primitives and Group Operations.
| errors
| Error reporting interface.
| fileparser
| Parser for issuer material.
| print_utils
| Debug print routines.
| types
| SDK data types.

## Data Structures

struct | CommitValues
| Storage for values to create commitment in Sign and Verify algorithms. More...
struct | Epid2Params_
| Internal representation of Epid2Params. More...
struct | GroupPubKey_
| Internal representation of GroupPubKey. More...
struct | PrivKey_
| Internal implementation of PrivKey. More...

## Macros

#define | ntohl(u32)
| Macros to transform oct str 32 into uint_32. More...
#define | EPID_ENABLE_EPID_ZERO_MEMORY_ON_FREE
| When enabled secrets are wiped out from the memory by EpidFree.
#define | SAFE_ALLOC(size) EpidAlloc(size);
| Allocates zero initalized block of memory.
#define | SAFE_FREE(ptr)
| Deallocates space allocated by SAFE_ALLOC() and nulls pointer. More...
#define | SAFE_REALLOC(ptr, size) EpidRealloc((ptr), (size))
| Changes the size of the memory block pointed to by ptr.

## Typedefs

typedef int(__STDCALL * | BitSupplier) (unsigned int *rand_data, int num_bits, void *user_data)
| Generates random data. More...

## Functions

EpidStatus | SetKeySpecificCommitValues (GroupPubKey const *pub_key, CommitValues *values)
| Set group public key related fields from CommitValues structure. More...
EpidStatus | SetCalculatedCommitValues (G1ElemStr const *B, G1ElemStr const *K, G1ElemStr const *T, EcPoint const *R1, EcGroup *G1, FfElement const *R2, FiniteField *GT, CommitValues *values)
| Set CommitValues structure fields calculated in algorithm. More...
EpidStatus | CalculateCommitmentHash (CommitValues const *values, FiniteField *Fp, HashAlg hash_alg, void const *msg, size_t msg_len, FfElement *c)
| Calculate Fp.hash(t3 || m) for Sign and Verfiy algorithms. More...
EpidStatus | CreateEpid2Params (Epid2Params_ **params)
| Constructs the internal representation of Epid2Params. More...
void | DeleteEpid2Params (Epid2Params_ **epid_params)
| Deallocates storage for internal representation of Epid2Params. More...
EpidStatus | CreateGroupPubKey (GroupPubKey const *pub_key_str, EcGroup *G1, EcGroup *G2, GroupPubKey_ **pub_key)
| Constructs internal representation of GroupPubKey. More...
void | DeleteGroupPubKey (GroupPubKey_ **pub_key)
| Deallocates storage for internal representation of GroupPubKey. More...
void | EpidZeroMemory (void *ptr, size_t size)
| Clear information stored in block of memory pointer to by ptr. More...
void * | EpidAlloc (size_t size)
| Allocates memory of size bytes. More...
void * | EpidRealloc (void *ptr, size_t new_size)
| Reallocates memory allocated by EpidAlloc. More...
void | EpidFree (void *ptr)
| Frees memory allocated by EpidAlloc. More...
int | memcpy_S (void *dest, size_t destsz, void const *src, size_t count)
| Copies bytes between buffers with security ehancements. More...
bool | IsSigRlValid (GroupId const *gid, SigRl const *sig_rl, size_t sig_rl_size)
| Function to verify if signature based revocation list is valid. More...
bool | CreateStack (size_t element_size, Stack **stack)
| Create stack. More...
void * | StackPushN (Stack *stack, size_t n, void *elements)
| Push multiple elements to the stack. More...
bool | StackPopN (Stack *stack, size_t n, void *elements)
| Pop multiple elements from the stack. More...
size_t | StackGetSize (Stack const *stack)
| Get number of elements in the stack. More...
void | DeleteStack (Stack **stack)
| Deallocates memory used for the stack. More...
EpidStatus | CreatePrivKey (PrivKey const *priv_key_str, EcGroup *G1, FiniteField *Fp, PrivKey_ **priv_key)
| Constructs internal representation of PrivKey. More...
void | DeletePrivKey (PrivKey_ **priv_key)
| Deallocate storage for internal representation of PrivKey. More...

## Detailed Description

Common code shared between core sub-components.

Constants, utility functions, and libraries that are used widely in the implementation or definition of APIs and samples.

## Macro Definition Documentation

#define ntohl | ( |  | u32 | ) |

Value:
((uint32_t)(((((unsigned char*)&(u32))[0]) << 24) + \
((((unsigned char*)&(u32))[1]) << 16) + \
((((unsigned char*)&(u32))[2]) << 8) + \
(((unsigned char*)&(u32))[3])))

Macros to transform oct str 32 into uint_32.

#define SAFE_FREE | ( |  | ptr | ) |

Value:
{ \
if (NULL != (ptr)) { \
EpidFree(ptr); \
(ptr) = NULL; \
} \
}

Deallocates space allocated by SAFE_ALLOC() and nulls pointer.

## Typedef Documentation

typedef int(__STDCALL* BitSupplier) (unsigned int *rand_data, int num_bits, void *user_data)

Generates random data.

It is the responsibility of the caller of the SDK interfaces to implement a function of this prototype and to then pass a pointer to this function into methods that require it.

Parameters

  [out] | rand_data | destination buffer
  [in] | num_bits | size of rand_data in bits
  [in] | user_data | user data passed through from api call.

Returns
  zero on success and non-zero value on error.

## Function Documentation

EpidStatus CalculateCommitmentHash | ( | CommitValues const * | values,
|  | FiniteField * | Fp,
|  | HashAlg | hash_alg,
|  | void const * | msg,
|  | size_t | msg_len,
|  | FfElement * | c
| ) |  |

Calculate Fp.hash(t3 || m) for Sign and Verfiy algorithms.

Calculate c = Fp.hash(t3 || m) where t3 is Fp.hash(p || g1 || g2 || h1 || h2 || w || B || K || T || R1 || R2).

Parameters

  [in] | values | Commit values to hash
  [in] | Fp | Finite field to perfom hash operation in
  [in] | hash_alg | Hash algorithm to use
  [in] | msg | Message to hash
  [in] | msg_len | Size of msg buffer in bytes
  [out] | c | Result of calculation

Returns
  EpidStatus

See also
  SetKeySpecificCommitValues
  SetCalculatedCommitValues

EpidStatus CreateEpid2Params | ( | Epid2Params_ ** | params | ) |

Constructs the internal representation of Epid2Params.

Allocates memory for the internal representation of Epid2Params. Initialize the Epid2Params. Use DeleteEpid2Params() to deallocate memory.

Parameters

  [in,out] | params | Internal Epid2Params

Returns
  EpidStatus

See also
  DeleteEpid2Params

EpidStatus CreateGroupPubKey | ( | GroupPubKey const * | pub_key_str,
|  | EcGroup * | G1,
|  | EcGroup * | G2,
|  | GroupPubKey_ ** | pub_key
| ) |  |

Constructs internal representation of GroupPubKey.

Allocates memory and initializes gid, h1, h2, w parameters. Use DeleteGroupPubKey() to deallocate memory

Parameters

  [in] | pub_key_str | Oct string representation of group public key
  [in] | G1 | EcGroup containing elements h1 and h2
  [in] | G2 | EcGroup containing element w
  [out] | pub_key | Group public key: (gid, h1, h2, w)

Returns
  EpidStatus

See also
  DeleteGroupPubKey

EpidStatus CreatePrivKey | ( | PrivKey const * | priv_key_str,
|  | EcGroup * | G1,
|  | FiniteField * | Fp,
|  | PrivKey_ ** | priv_key
| ) |  |

Constructs internal representation of PrivKey.

This function allocates memory and initializes gid, A, x, f parameters.

Parameters

  [in] | priv_key_str | Serialized representation of private key
  [in] | G1 | EcGroup containing element A
  [in] | Fp | FiniteField containing elements x and f
  [out] | priv_key | Newly created private key: (gid, A, x, f)

Returns
  EpidStatus

bool CreateStack | ( | size_t | element_size,
|  | Stack ** | stack
| ) |  |

Create stack.

Parameters

  [in] | element_size | Size of stack element
  [out] | stack | Stack context to be created

Returns
  true is operation succeed, false if stack were failed to allocate

See also
  DeleteStack

void DeleteEpid2Params | ( | Epid2Params_ ** | epid_params | ) |

Deallocates storage for internal representation of Epid2Params.

Frees the memory and nulls the pointer.

Parameters

  [in,out] | epid_params | params to be deallocated

See also
  CreateEpid2Params

void DeleteGroupPubKey | ( | GroupPubKey_ ** | pub_key | ) |

Deallocates storage for internal representation of GroupPubKey.

Frees memory pointed to by Group public key. Nulls the pointer.

Parameters

  [in] | pub_key | Group public key to be freed

See also
  CreateGroupPubKey

void DeletePrivKey | ( | PrivKey_ ** | priv_key | ) |

Deallocate storage for internal representation of PrivKey.

Frees memory pointed to by Member private key. Nulls the pointer.

Parameters

  [in] | priv_key | Member private key to be freed

void DeleteStack | ( | Stack ** | stack | ) |

Deallocates memory used for the stack.

Parameters

  [in,out] | stack | Stack context

See also
  CreateStack

void* EpidAlloc | ( | size_t | size | ) |

Allocates memory of size bytes.

The content of memory is initialized with zeros. Memory must be freed with EpidFree function.

Parameters

  [in] | size | number of bytes to allocate

Returns
  pointer to allocated memory.

void EpidFree | ( | void * | ptr | ) |

Frees memory allocated by EpidAlloc.

Clears information stored in the block of memory.

Parameters

  [in] | ptr | pointer to allocated memory block

void* EpidRealloc | ( | void * | ptr,
|  | size_t | new_size
| ) |  |

Reallocates memory allocated by EpidAlloc.

In case of error NULL pointer is returned and input memory block is not changed. Memory must be freed with EpidFree function.

Parameters

  [in] | ptr | pointer to memory block to reallocate
  [in] | new_size | number of bytes to reallocate for

Returns
  pointer to allocated memory.

void EpidZeroMemory | ( | void * | ptr,
|  | size_t | size
| ) |  |

Clear information stored in block of memory pointer to by ptr.

Warning
  This function may be optimized away by some compilers. If it is, you should consider using a compiler or operating system specific memory sanitization function (e.g. memcpy_s or SecureZeroMemory).

Parameters

  [in] | ptr | pointer to memory block
  [in] | size | number of bytes to clear

bool IsSigRlValid | ( | GroupId const * | gid,
|  | SigRl const * | sig_rl,
|  | size_t | sig_rl_size
| ) |  |

Function to verify if signature based revocation list is valid.

Parameters

  [in] | gid | Group id
  [in] | sig_rl | Signature based revocation list
  [in] | sig_rl_size | Size of signature based revocation list

Returns
  true if revocation list is valid
  false if revocation list is invalid

int memcpy_S | ( | void * | dest,
|  | size_t | destsz,
|  | void const * | src,
|  | size_t | count
| ) |  |

Copies bytes between buffers with security ehancements.

Copies count bytes from src to dest. If the source and destination overlap, the behavior is undefined.

Parameters

  [out] | dest | pointer to the object to copy to
  [in] | destsz | max number of bytes to modify in the destination (typically the size of the destination object)
  [in] | src | pointer to the object to copy from
  [in] | count | number of bytes to copy

Returns
  zero on success and non-zero value on error.

Copies bytes between buffers with security ehancements.

Note
  Implementation follows C11 memcpy_s but with checks always enabled

EpidStatus SetCalculatedCommitValues | ( | G1ElemStr const * | B,
|  | G1ElemStr const * | K,
|  | G1ElemStr const * | T,
|  | EcPoint const * | R1,
|  | EcGroup * | G1,
|  | FfElement const * | R2,
|  | FiniteField * | GT,
|  | CommitValues * | values
| ) |  |

Set CommitValues structure fields calculated in algorithm.

Set B, K, T, R1 and R2 fields of values argument.

Parameters

  [in] | B | Value of B to set
  [in] | K | Value of K to set
  [in] | T | Value of T to set
  [in] | R1 | Value of R1 to set
  [in] | G1 | EcGroup containing element R1
  [in] | R2 | Value of R2 to set
  [in] | GT | FiniteField containing element R2
  [out] | values | Pointer to CommitValues structure to fill.

Returns
  EpidStatus

See also
  CalculateCommitmentHash

EpidStatus SetKeySpecificCommitValues | ( | GroupPubKey const * | pub_key,
|  | CommitValues * | values
| ) |  |

Set group public key related fields from CommitValues structure.

Set p, g1, g2, h1, h2 and w fields of values argument.

Parameters

  [in] | pub_key | Group public key
  [out] | values | Pointer to CommitValues structure to fill.

Returns
  EpidStatus

See also
  CalculateCommitmentHash

size_t StackGetSize | ( | Stack const * | stack | ) |

Get number of elements in the stack.

Parameters

  [in] | stack | Stack context

Returns
  Number of elements in the stack or 0 if stack is NULL

See also
  CreateStack

bool StackPopN | ( | Stack * | stack,
|  | size_t | n,
|  | void * | elements
| ) |  |

Pop multiple elements from the stack.

Parameters

  [in,out] | stack | Stack context
  [in] | n | Number of elements to pop from the stack
  [out] | elements | Pointer to a buffer to store elements removed from the stack

Returns
  true is operation succeed, false otherwise

See also
  CreateStack

void* StackPushN | ( | Stack * | stack,
|  | size_t | n,
|  | void * | elements
| ) |  |

Push multiple elements to the stack.

Parameters

  [in,out] | stack | Stack context
  [in] | n | Number of elements to push to the stack
  [in] | elements | Array of elements to push to the stack. Can be NULL

Returns
  A pointer to an array of new elements in the stack or NULL if stack is empty or push operation were failed.

See also
  CreateStack