My Project
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Functions
otz_api.c File Reference
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <errno.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <sys/ioctl.h>
#include <sys/mman.h>
#include <fcntl.h>
#include <otz_api.h>
#include <otz_client.h>
#include <otz_id.h>

Functions

otz_return_t otz_device_open (void const *pk_device_name, void const *pk_init, otz_device_t *ps_device)
 This function opens a connection with the device in the underlying operating environment that represents the secure environment. When the client no longer requires the device it must call otz_device_close to close the connection and free any associated resources. This function accepts a pointer to a otz_device_t structure assumed to be in the OTZ_STATE_UNDEFINED state. On success this function must set the device structure *ps_device to the state OTZ_STATE_OPEN with a session count of zero. On failure, the device is set to the state OTZ_STATE_INVALID. It is possible to create multiple concurrent device connections from a single client. The number of devices that can be supported globally within the entire system, or locally within a single client, is implementation-defined. More...
 
otz_return_t otz_device_get_timelimit (otz_device_t *ps_device, uint32_t ui_timeout, otz_timelimit_t *ps_timelimit)
 Calling this function generates a device-local absolute time limit in the structure pointed to by ps_time_limit from a timeout value ui_timeout. The absolute time limit is equal to the current time plus the specified timeout. More...
 
otz_return_t otz_operation_prepare_open (otz_device_t *ps_device, int pks_service, otz_login_t const *pks_login, otz_timelimit_t const *pks_timelimit, otz_session_t *ps_session, otz_operation_t *ps_operation)
 This function is responsible for locally preparing an operation that can be used to connect with the service defined by the UUID pointed to by pks_service, using the timeout pointed to by pks_time_limit and the login credentials specified in pks_login. More...
 
otz_return_t otz_operation_prepare_invoke (otz_session_t *ps_session, uint32_t ui_command, otz_timelimit_t const *pks_timelimit, otz_operation_t *ps_operation)
 This function is responsible for locally preparing an operation that can be used to issue a command to a service with which the client has already created a session. More...
 
otz_return_t otz_operation_prepare_close (otz_session_t *ps_session, otz_operation_t *ps_operation)
 Prepare the operation for close session. More...
 
otz_return_t otz_operation_perform (otz_operation_t *ps_operation, otz_return_t *pui_service_return)
 Performs the previously prepared operation. More...
 
void otz_free_temp_shared_mem (otz_operation_t *ps_operation)
 Frees the Temporary shared Memory. More...
 
void otz_operation_release (otz_operation_t *ps_operation)
 Release operation. More...
 
void otz_operation_cancel (otz_operation_t *ps_operation)
 This function Cancels the operation. More...
 
otz_return_t otz_shared_memory_allocate (otz_session_t *ps_session, otz_shared_mem_t *ps_shared_mem)
 This function allocates a block of memory, defined by the structure pointed to by ps_shared_mem, which is shared between the client and the service it is connected to. More...
 
otz_return_t otz_shared_memory_register (otz_session_t *ps_session, otz_shared_mem_t *ps_shared_mem)
 
void otz_shared_memory_release (otz_shared_mem_t *ps_shared_mem)
 This function allocates a block of memory, defined by the structure pointed to by ps_shared_mem, which is shared between the client and the service it is connected to. This function marks a block of shared memory associated with a session as no longer shared. More...
 
otz_return_t otz_device_close (otz_device_t *ps_device)
 Close the device connection. More...
 
void otz_encode_uint32 (otz_operation_t *ps_operation, void const *data, int param_type)
 Encode unsigned 32-bit integer. More...
 
void otz_encode_array (otz_operation_t *ps_operation, void const *pk_array, uint32_t length, int param_type)
 Encode binary array to the encoded message. More...
 
void * otz_encode_array_space (otz_operation_t *ps_operation, uint32_t length, int param_type)
 Encode empty binary array to the encoded message. More...
 
void otz_encode_memory_reference (otz_operation_t *ps_operation, otz_shared_mem_t *ps_shared_mem, uint32_t offset, uint32_t length, uint32_t flags, int param_type)
 Appends a reference of previously allocated shared block to the encoded buffer. More...
 
uint32_t otz_decode_uint32 (otz_operation_t *ps_operation)
 Decode a unsigned 32-bit integer value from message. More...
 
void * otz_decode_array_space (otz_operation_t *ps_operation, uint32_t *plength)
 Decode a block of binary data from the message. More...
 
uint32_t otz_decode_get_type (otz_operation_t *ps_operation)
 Returns the decoder stream data type. More...
 
otz_return_t otz_decode_get_error (otz_operation_t *ps_operation)
 Get decode error. More...
 

Function Documentation

void* otz_decode_array_space ( otz_operation_t ps_operation,
uint32_t plength 
)

Decode a block of binary data from the message.

This function decodes a block of binary data from the current offset in the structured message returned by the service. The length of the block is returned in *pui_length and the base pointer is the function return value.

Parameters
ps_operation
plength
Returns
otz_return_t otz_decode_get_error ( otz_operation_t ps_operation)

Get decode error.

This function returns the error state of the decoder associated with the given operation.

This function does not affect the error state of the decoder.

Parameters
ps_operation
Returns
uint32_t otz_decode_get_type ( otz_operation_t ps_operation)

Returns the decoder stream data type.

This function returns the type of the data at the current offset in the decoder stream.

Parameters
ps_operation
Returns
uint32_t otz_decode_uint32 ( otz_operation_t ps_operation)

Decode a unsigned 32-bit integer value from message.

This function decodes a single item of type uint32_t from the current offset in the structured message returned by the service.

Parameters
ps_operation
Returns
otz_return_t otz_device_close ( otz_device_t ps_device)

Close the device connection.

This function closes a connection with a device, freeing any associated resources.

Parameters
ps_device
Returns
otz_return_t otz_device_get_timelimit ( otz_device_t ps_device,
uint32_t  ui_timeout,
otz_timelimit_t ps_timelimit 
)

Calling this function generates a device-local absolute time limit in the structure pointed to by ps_time_limit from a timeout value ui_timeout. The absolute time limit is equal to the current time plus the specified timeout.

Get local time limit.

Parameters
ps_device
ui_timeout
ps_timelimit
Returns
otz_return_t otz_device_open ( void const *  pk_device_name,
void const *  pk_init,
otz_device_t ps_device 
)

This function opens a connection with the device in the underlying operating environment that represents the secure environment. When the client no longer requires the device it must call otz_device_close to close the connection and free any associated resources. This function accepts a pointer to a otz_device_t structure assumed to be in the OTZ_STATE_UNDEFINED state. On success this function must set the device structure *ps_device to the state OTZ_STATE_OPEN with a session count of zero. On failure, the device is set to the state OTZ_STATE_INVALID. It is possible to create multiple concurrent device connections from a single client. The number of devices that can be supported globally within the entire system, or locally within a single client, is implementation-defined.

Open the device.

Parameters
pk_device_name
pk_init
ps_device
Returns
void otz_encode_array ( otz_operation_t ps_operation,
void const *  pk_array,
uint32_t  length,
int  param_type 
)

Encode binary array to the encoded message.

Calling this function appends a binary array pointed to by array and of length length bytes to the end ofthe encoded message. The implementation must guarantee that when decoding the array in the service the base pointer is eight byte aligned to enable any basic C data structure to be exchanged using this method.

Parameters
ps_operation
pk_array
length
param_type
void* otz_encode_array_space ( otz_operation_t ps_operation,
uint32_t  length,
int  param_type 
)

Encode empty binary array to the encoded message.

Calling this function appends an empty binary array of length "length" bytes to the end of the encoded message and returns the pointer to this array to the client. This allows an implementation with fewer copies, as the encoder buffer can be filled directly by the client without needing a copy from an intermediate buffer into the real encoder buffer.

Parameters
ps_operation
length
param_type
Returns
void otz_encode_memory_reference ( otz_operation_t ps_operation,
otz_shared_mem_t ps_shared_mem,
uint32_t  offset,
uint32_t  length,
uint32_t  flags,
int  param_type 
)

Appends a reference of previously allocated shared block to the encoded buffer.

Calling this function appends a reference to a range of a previously created shared memory block.

Memory references are used to provide a synchronization token protocol which informs the service when it can read from or write to a portion of the shared memory block. A memory reference is associated with a specific operation and is valid only during the execution of that operation.

Parameters
ps_operation
ps_shared_mem
offset
length
flags
param_type
void otz_encode_uint32 ( otz_operation_t ps_operation,
void const *  data,
int  param_type 
)

Encode unsigned 32-bit integer.

Calling this function appends the value of the passed uint32_t, pk_data, to the end of the encoded message.

Parameters
ps_operation
data
param_type
void otz_free_temp_shared_mem ( otz_operation_t ps_operation)

Frees the Temporary shared Memory.

Parameters
ps_operation
void otz_operation_cancel ( otz_operation_t ps_operation)

This function Cancels the operation.

Parameters
ps_operation
otz_return_t otz_operation_perform ( otz_operation_t ps_operation,
otz_return_t pui_service_return 
)

Performs the previously prepared operation.

This function performs a previously prepared operation – issuing it to the secure environment. There are three kinds of operations that can be issued: opening a client session, invoking a service command, and closing a client session. Each type of operation is prepared with its respective function, which returns the operation structure to be used: otz_operation_prepare_open prepares an open session operation. otz_operation_prepare_invoke prepares an invoke service command operation. otz_operation_prepare_close prepares a close session operation.

Parameters
ps_operation
pui_service_return
Returns
otz_return_t otz_operation_prepare_close ( otz_session_t ps_session,
otz_operation_t ps_operation 
)

Prepare the operation for close session.

This function is responsible for locally preparing an operation that can be used to close a session between the client and a service.

Parameters
ps_session
ps_operation
Returns
otz_return_t otz_operation_prepare_invoke ( otz_session_t ps_session,
uint32_t  ui_command,
otz_timelimit_t const *  pks_timelimit,
otz_operation_t ps_operation 
)

This function is responsible for locally preparing an operation that can be used to issue a command to a service with which the client has already created a session.

Prepare operation for service request.

Parameters
ps_session
ui_command
pks_timelimit
ps_operation
Returns
otz_return_t otz_operation_prepare_open ( otz_device_t ps_device,
int  pks_service,
otz_login_t const *  pks_login,
otz_timelimit_t const *  pks_timelimit,
otz_session_t ps_session,
otz_operation_t ps_operation 
)

This function is responsible for locally preparing an operation that can be used to connect with the service defined by the UUID pointed to by pks_service, using the timeout pointed to by pks_time_limit and the login credentials specified in pks_login.

Prepare open operation.

Parameters
ps_device
pks_service
pks_login
pks_timelimit
ps_session
ps_operation
Returns
void otz_operation_release ( otz_operation_t ps_operation)

Release operation.

This function releases an operation, freeing any associated resources.

Parameters
ps_operation
otz_return_t otz_shared_memory_allocate ( otz_session_t ps_session,
otz_shared_mem_t ps_shared_mem 
)

This function allocates a block of memory, defined by the structure pointed to by ps_shared_mem, which is shared between the client and the service it is connected to.

Parameters
ps_session
ps_shared_mem
Returns
otz_return_t otz_shared_memory_register ( otz_session_t ps_session,
otz_shared_mem_t ps_shared_mem 
)
Parameters
ps_session
ps_shared_mem
Returns
void otz_shared_memory_release ( otz_shared_mem_t ps_shared_mem)

This function allocates a block of memory, defined by the structure pointed to by ps_shared_mem, which is shared between the client and the service it is connected to. This function marks a block of shared memory associated with a session as no longer shared.

Parameters
ps_shared_mem