Random Proximity Identifier

Proximity Identifier functionality. More...

Files
file	rpi.c
	Random Proximity Identifier functionality.
file	rpi.h
	Random Proximity Identifier functionality.

Data Structures
struct	Rpi
	The structure used to represent a Rolling Proximity Identifier. More...

Macros
#define	RPI_INFO_PREFIX   "CT-RPI"
#define	RPI_SIZE   (16)
#define	RPI_SIZE_BASE64   (24)
#define	RPI_INTERVAL_MAX   (144)

Functions
Rpi *	rpi_new ()
void	rpi_delete (Rpi *data)
bool	rpi_generate_proximity_id (Rpi *data, Dtk const *dtk, uint8_t time_interval_number)
unsigned char const *	rpi_get_proximity_id (Rpi const *data)
uint8_t	rpi_get_time_interval_number (Rpi const *data)
void	rpi_assign (Rpi *data, unsigned char const *rpi_bytes, uint8_t time_interval_number)
bool	rpi_compare (Rpi const *data, Rpi const *comparitor)

Detailed Description

Proximity Identifier functionality.

This class is used to generate and manage the Random Proximity Identifier (RPI). It's largely internal. The functionality from Contrac should generally be used in preference to this.

Macro Definition Documentation

RPI_INFO_PREFIX

#define RPI_INFO_PREFIX   "CT-RPI"

Used internally.

This is the prefix for the Info parameter provided to the HMAC and used to generate the RPI.

RPI_INTERVAL_MAX

#define RPI_INTERVAL_MAX   (144)

The maximum value a time interval number can take. Time interval numbers are measured from the start of the day and increment every 10 minutes, so must fall within the interval [0, 143].

RPI_SIZE

#define RPI_SIZE   (16)

The size in bytes of an RPI in binary format.

RPI_SIZE_BASE64

#define RPI_SIZE_BASE64   (24)

The size in bytes of an RPI in base64 format, not including the null terminator.

Function Documentation

rpi_assign()

void rpi_assign	(	Rpi *	data,
		unsigned char const *	rpi_bytes,
		uint8_t	time_interval_number
	)

Populates the data structure.

Allows the RPI and time interval number values of the object to be set explicitly.

For internal use. To set the RPI it generally makes more sense to use one of eiher contrac_set_time_interval_number() or contrac_update_current_time() instead.

The rpi_bytes buffer passed in must contain exactly RPI_SIZE (16) bytes of data. It doen't have to be null terminated.

Parameters

data	The context object to work with.
rpi_bytes	The RPI value to set, in binary format.
day_number	The time interval number to associate with this RPI.

rpi_compare()

bool rpi_compare	(	Rpi const *	data,
		Rpi const *	comparitor
	)

Compares two RPI values.

Parameters

data	The RPI to compare with.
comparitor	The RPI to compare against.

Returns

true if the two RPIs are the same, false otherwise.

rpi_delete()

void rpi_delete

(

Rpi *

data

)

Deletes an instance of the class, freeing up the memory allocated to it.

Parameters

data	The instance to free.

rpi_generate_proximity_id()

bool rpi_generate_proximity_id	(	Rpi *	data,
		Dtk const *	dtk,
		uint8_t	time_interval_number
	)

Generates a Rolling Proximity Identifier based on the time interval number provided.

The operation may fail under certain circumstances, such as if the HMAC operation fails for some reason.

For internal use. It generally makes more sense to use the contrac_set_time_interval_number() function instead.

Parameters

data	The context object to work with.
time_interval_number	The time interval number to use to generate the key.

Returns

true if the operation completed successfully, false otherwise.

rpi_get_proximity_id()

unsigned char const * rpi_get_proximity_id

(

Rpi const *

data

)

Gets the Rolling Proximity Identifier for the device in binary format.

For internal use. It generally makes more sense to use the contrac_get_proximity_id() function instead.

This allows the Rolling Proximity Identifier to be extracted. The Rolling Proximity Identifier is public, in the sense that it is usual to broadcast the value in Bluetooth beacons.

The buffer returned will contain exactly RPI_SIZE (16) bytes of data in binary format. This may therefore contain null bytes, and the buffer will not necessarily be null terminated. Future operations may cause the data to change, so the caller should make a copy of the buffer rather than keeping a pointer to it.

Parameters

data	The context object to work with.

Returns

The Rolling Proximity Identifier in binary format, not null terminated.

rpi_get_time_interval_number()

uint8_t rpi_get_time_interval_number

(

Rpi const *

data

)

Gets the time interval number that applies to the current RPI.

For internal use. It generally makes more sense to use the contrac_set_time_interval_number() function instead.

Parameters

data	The context object to work with.

Returns

The time interval number stored in the object.

rpi_new()

Rpi * rpi_new

(

)

Creates a new instance of the class.

Returns

The newly created object.