C API for BALTECH SDK
BRP Communication Library

Macros

#define BRP_ERR_AR_NOMESSAGE   BRP_ERR_STATUS(0x0500, 0x01)
 
#define BRP_ERR_AR_DISABLED   BRP_ERR_STATUS(0x0500, 0x10)
 
#define BRP_CMD_SYS_GETINFO_FWS_LEN   41
 maximum length of firmwarestring (see brp_exec_Sys_GetInfo()) More...
 
#define BRP_INFINITE   0xFFFFFFFF
 is used if brp_time shall be infinite. More...
 
#define BRP_TIME_SUBTRACT(time, delta)
 
#define BRP_FRAME_INVALID_SIZE   ((size_t) -1)
 
#define BRP_LOG_DIR_PREFIX   "brp-logs-"
 
#define BRP_PROTID_BRP   1
 identificator for BRP protocols (see brp_protocol.h) More...
 
#define BRP_PROTID_TCPIP   2
 identificator for TCP/IP protocol (see tcpip_protocol.h) More...
 
#define BRP_PROTID_PKI   3
 
#define BRP_PROTID_COMPOSITE   4
 identificator for composed protocols (see composite_protocol.h) More...
 
#define BRP_PROTID_DUMMY   5
 internal identificator for unused protocol layers in composed protocols (see composite_protocol.h). More...
 
#define BRP_PROTID_USB_HID   6
 identificator for USB HID protocols (see usb_hid_protocol.h) More...
 
#define BRP_PROTID_RS232   7
 identificator for RS232/Virtual Comport protocols (see usb_hid_protocol.h) More...
 
#define BRP_PROTID_SECURE_CHANNEL   8
 identificator for RS232 protocol (see rs232_protocol.h) More...
 
#define BRP_PROTID_MONITOR   9
 identificator for transparent BRP monitor protocol. More...
 
#define BRP_PROTID_CUSTOM(ndx)   (0x80+(ndx))
 identificator for custom protocols (=not implemented by this library) More...
 
#define BRP_LAYERID_ANONYMOUS   0
 unnamed protocol layer More...
 
#define BRP_LAYERID_IO   1
 lowest protocol layer that forwards More...
 
#define BRP_LAYERID_BRP   3
 data to OS drivers More...
 
#define BRP_LAYERID_MONITOR   5
 monitoring layer More...
 
#define BRP_LAYERID_CRYPTO   4
 encryption layer More...
 
#define BRP_LAYERID_PLAIN_MONITOR   6
 monitoring layer for dencrypted cmds More...
 
#define BRP_AES_KEY_SIZE   16
 
#define BRP_AES_BLOCK_SIZE   16
 
#define BRP_MAX_SECURITY_LEVEL   3
 
#define BRP_DEFAULT_TCP_PORT   2939
 If a TCP/IP connection is created without specifying a portnr, this default value is used as portnr. More...
 
#define BRP_DEFAULT_TCPIP_ROUNDTRIP_TIMEOUT   1500
 This is the default time that will be assumed as worst case for a single roundtrip. More...
 

Typedefs

typedef unsigned char * brp_buf
 represents a pointer to a protocol data buffer. More...
 
typedef unsigned long brp_time
 absolute/relative timeout/delay in ms. More...
 
typedef unsigned int brp_errcode
 This type is used library-wide for passing error codes in the return value of functions. More...
 
typedef struct brp_mempool_object_t * brp_mempool
 mempool handle. More...
 
typedef struct brp_protocol_t * brp_protocol
 This is a generic handle of a protocol. More...
 
typedef int brp_layer_id
 identifies the layer of a composite protocol stack (see brp_create() or brp_create_composite(). More...
 
typedef unsigned char brp_sec_key[BRP_AES_KEY_SIZE]
 A AES128 key, that is required for crypto operations. More...
 
typedef unsigned char brp_sec_iv[BRP_AES_BLOCK_SIZE]
 A AES IV. More...
 

Functions

BRP_LIB brp_errcode brp_decode_base64_obj (char *obj_name, brp_frame encoded_frm, brp_frame decoded_frm)
 This function decodes any BASE64-encoded frame and stores the decoded data in "decoded_frm". More...
 
BRP_LIB brp_protocol brp_create_brp (void)
 Creates a new BRP protocol. More...
 
BRP_LIB brp_errcode brp_exec_cmd (brp_protocol protocol, int cmd_code, brp_buf param_buf, size_t param_len, brp_buf resp_buf, size_t max_resp_len, size_t *resp_len, brp_time cmd_timeout)
 Runs a command on the BRP device connected via the assigned protocol. More...
 
BRP_LIB brp_errcode brp_send_cmd (brp_protocol protocol, int cmd_code, brp_buf param_buf, size_t param_len, brp_time cmd_timeout, int mode)
 Sends a command frame via a BRP protocol. More...
 
BRP_LIB brp_errcode brp_recv_cmd (brp_protocol protocol, brp_buf resp_buf, size_t max_resp_len, size_t *resp_len, brp_time timeout)
 Returns the response of a command runned on the BRP device connected via base_protocol. More...
 
BRP_LIB brp_errcode brp_break_cmd (brp_protocol protocol)
 Stops a command that was run with brp_send_cmd() with the mode parameter set to in BRP_MODE_CONTINUOUS or BRP_MODE_REPEAT. More...
 
BRP_LIB brp_errcode brp_exec_Sys_GetInfo (brp_protocol protocol, char *fws)
 Retrieves the firmware string. More...
 
BRP_LIB brp_errcode brp_exec_AR_GetMessage (brp_protocol protocol, int *msg_type, char *msg, size_t max_msg_len, size_t *msg_len)
 Returns the last message read by device. More...
 
BRP_LIB brp_errcode brp_exec_Sys_CfgSetValue (brp_protocol protocol, int key, int value, brp_buf data, size_t data_len)
 Modifies the devices (permanent) configuration. More...
 
BRP_LIB brp_errcode brp_exec_Sys_CfgGetValue (brp_protocol protocol, int key, int value, brp_buf data, size_t max_data_len, size_t *data_len)
 Retrieves a configuration value from the device. More...
 
BRP_LIB brp_protocol brp_create_composite (void)
 Creates an empty composite protocol. More...
 
BRP_LIB brp_protocol brp_create (void)
 This is equivalent to the following call: More...
 
BRP_LIB brp_errcode brp_add_layer (brp_protocol composite_protocol, brp_layer_id layer_id)
 Adds a protocol layer without assigning a protocol to it. More...
 
BRP_LIB brp_errcode brp_set_layer (brp_protocol composite_protocol, brp_layer_id layer_id, brp_protocol layer_protocol)
 Adds/replaces a protocol layer to a composite protocol. More...
 
BRP_LIB brp_protocol brp_get_layer (brp_protocol composite_protocol, brp_layer_id layer_id)
 Retrieves a protocol layer from a composite protocol. More...
 
BRP_LIB brp_protocol brp_detach_layer (brp_protocol composite_protocol, brp_layer_id layer_id)
 Removes a protocol from a composite protocol stack without destroying. More...
 
BRP_LIB brp_errcode brp_set_io (brp_protocol protocol, brp_protocol io_protocol)
 Assigns an I/O protocol to a composite protocol (protocol stack). More...
 
BRP_LIB brp_errcode brp_set_crypto (brp_protocol composite_protocol, brp_protocol crypto_protocol)
 Assigns a crypto protocol to a composite protocol (protocol stack). More...
 
BRP_LIB brp_errcode brp_suppress_monitoring (brp_protocol protocol)
 Disables the monitoring feature of this library. More...
 
BRP_LIB brp_errcode brp_set_monitor (brp_protocol protocol, int mode)
 When communicating encrypted (see brp_set_crypto()) the monitoring feature of this library logs the plaintext data. More...
 
BRP_LIB void brp_mempool_free (brp_mempool *mempool)
 Releases the memory of a brp_mempool. More...
 
BRP_LIB brp_protocol brp_create_monitor (void)
 Creates a new Monitor protocol layer. More...
 
BRP_LIB void brp_annotation_start (brp_protocol protocol)
 Marks the beginning of a related block of log entries. More...
 
BRP_LIB void brp_annotation_end (brp_protocol protocol, bool success, char *comment)
 Marks the end of a related block of log entries and adds some kind of comment to it. More...
 
BRP_LIB char * brp_map_errcode (brp_errcode errcode)
 Retrieve name of errorcode. More...
 
BRP_LIB char * brp_map_errcode_to_desc (brp_errcode errcode)
 Retrieve textual description of errorcode in english. More...
 
BRP_LIB char * brp_map_errcode_to_docurl (brp_errcode errcode)
 Retrieve URL of the documentation describing the passed errcode. More...
 
BRP_LIB char * brp_map_cmdcode (unsigned cmd_code)
 Retrieve the name of a (16bit) cmdcode as C string. More...
 
BRP_LIB char * brp_map_cmdcode_to_docurl (unsigned cmd_code)
 Retrieve URL of the documentation describing the passed cmdcode. More...
 
BRP_LIB brp_protocol brp_create_pki (int security_level, brp_buf host_cert_chain, size_t host_cert_chain_len, brp_buf dev_ca_cert_chain, size_t dev_ca_cert_chain_len, brp_buf private_key, size_t private_key_len, brp_time session_timeout)
 Creates a new PKI protocol layer. More...
 
BRP_LIB brp_errcode brp_append_host_certs (brp_protocol protocol, brp_buf host_cert_chain, size_t host_cert_chain_len)
 Adds certificate(s) to the host certificate chain. More...
 
BRP_LIB brp_errcode brp_append_dev_ca_certs (brp_protocol protocol, brp_buf dev_ca_cert_chain, size_t dev_ca_cert_chain_len)
 Adds certificate(s) to the devices CA certificate chain. More...
 
BRP_LIB brp_errcode brp_pki_save_session (brp_protocol protocol, brp_buf persistent_buf, size_t peristent_buf_size, size_t *persistent_buf_actlen)
 This command stores the current PKI session state in a persistent storage for being continued later using brp_pki_restore_session(). More...
 
BRP_LIB size_t brp_pki_get_session_buf_size (brp_protocol protocol)
 Returns the size of the buffer required to store the session state using brp_pki_save_session(). More...
 
BRP_LIB brp_errcode brp_pki_restore_session (brp_protocol protocol, brp_buf persistent_buf, size_t persistent_buf_size)
 This command reloads the current PKI session that was stored by brp_pki_save_session(). More...
 
BRP_LIB brp_errcode brp_pki_get_dev_cert (brp_protocol protocol, brp_buf dev_cert_buf, size_t dev_cert_buf_size, size_t *dev_cert_len)
 This command retrieves the certificate of the device which it created a PKI connection to. More...
 
BRP_LIB brp_errcode brp_open (brp_protocol protocol)
 Set up a connection via this protocol. More...
 
BRP_LIB brp_errcode brp_close (brp_protocol protocol)
 Closes protocol. More...
 
BRP_LIB brp_errcode brp_flush (brp_protocol)
 Deletes all data that is waiting in input buffers for being read via brp_recv_frame() (or brp_recv_fix_frame() / brp_frecv_any_frame()). More...
 
BRP_LIB brp_errcode brp_get_io_id (brp_protocol protocol, char **intf_name, brp_frame instance_id)
 Retrieves the instance name of the I/O-protocol of this protocol stack. More...
 
BRP_LIB brp_errcode brp_destroy (brp_protocol)
 Closes a protocol if opened and frees all allocated resources thereafter. More...
 
BRP_LIB brp_protocol brp_create_rs232 (char *dev_name, unsigned baudrate, char parity)
 Creates a protocol object for RS232/CDC interfaces from the device name. More...
 
BRP_LIB brp_protocol brp_create_secure_channel (int security_level, brp_sec_key key, int sec_mode)
 Creates a new secured channel that allows you to establish an authenticated and encrypted connection over an insecure BRP channel. More...
 
BRP_LIB brp_errcode brp_mutual_authenticate (brp_protocol protocol, int security_level, brp_sec_key key, int *req_auth_modes, brp_sec_key session_key)
 Does a mutual authentication and generates a session key. More...
 
BRP_LIB brp_errcode brp_secured_send_frm (brp_protocol protocol, int security_level, int sec_mode, brp_sec_key key, brp_sec_iv iv, int cmd_code, brp_buf param_buf, size_t param_len, brp_time cmd_timeout, int mode)
 Sends an encrypted command. More...
 
BRP_LIB brp_errcode brp_secured_recv_frm (brp_protocol protocol, int sec_mode, brp_sec_key key, brp_sec_iv iv, int cmd_code, brp_frame resp_frm, brp_time timeout)
 Sends an encrypted command. More...
 
BRP_LIB brp_protocol brp_create_tcpip (char *ipaddr)
 Creates a TCP/IP protocol from an IP address. More...
 
BRP_LIB brp_protocol brp_create_tcpip_by_socket (int socket)
 Creates a TCP/IP protocol from an OS-level socket that was created by the user of the BRP library. More...
 
BRP_LIB char * brp_get_tcpip_ipaddr (brp_protocol protocol)
 Retrieves the ipaddr set in brp_create_tcpip(). More...
 
BRP_LIB brp_errcode brp_set_tcpip_roundtrip_timeout (brp_protocol protocol, brp_time timeout)
 If the value of BRP_DEFAULT_TCPIP_ROUNDTRIP_TIMEOUT is not appropriate it can be finetuned for specific protocol instances via this function. More...
 
BRP_LIB brp_time brp_get_tcpip_roundtrip_timeout (brp_protocol protocol)
 Retrieves the value of the roundtrip timeout set by the last brp_set_tcpip_roundtrip_timeout(). More...
 
BRP_LIB brp_protocol brp_create_usb_hid (long long snr)
 Creates an (USB) HID protocol object from the connected baltech device with serialnumber 'snr'. More...
 
BRP_LIB char * brp_get_version (void)
 Returns the version of the BRP Communication Libary. More...
 

BRP_MODE_XXX

Specifies the run mode / frame format of BRP protocol.

#define BRP_MODE_STD   0x00
 Standard mode. More...
 
#define BRP_MODE_NONE   BRP_MODE_STD
 legacy define More...
 
#define BRP_MODE_CONTINUOUS   0x01
 Continous mode. More...
 
#define BRP_MODE_REPEAT   0x02
 Repeat mode. More...
 
#define BRP_MODE_BREAK   0x03
 Stop continuous / repeat mode. More...
 

BRP_MONITOR_XXX

Specifies the mode of monitoring

#define BRP_MONITOR_DISABLED   0
 avoid that BRP traffic could leak More...
 
#define BRP_MONITOR_ENABLED   1
 (required when sensitive data is transferred) More...
 
#define BRP_MONITOR_PLAINTEXT   2
 encrypted sessions will show only encryted data More...
 

BRP_MASK_XXX

Defines bitmasks for :brp_errcode. If a errcode is and'ed with one of the bitmasks the corresponding part of the error can be extracted.

#define BRP_ERRMASK_GROUP   0xFFFF0000
 
#define BRP_ERRMASK_CODE   0x0000FFFF
 

BRP_ERRGRP_XXX

#define BRP_ERRGRP_DEVICE   0x00010000u
 A command failed to execute due to a error on the device side which is not host communication related (card error, ...) More...
 
#define BRP_ERRGRP_COMM_UNSUPPORTED   0x00800000u
 A command cannot be executed as the device does not support the requested feature. More...
 
#define BRP_ERRGRP_COMM_ACCESSDENIED   0x01000000u
 A command cannot be executed as the device does not allow access this features in the current operations mode. More...
 
#define BRP_ERRGRP_COMM_TIMEOUT   0x02000000u
 A the device or host exceeded the allowed time for sending a frame. More...
 
#define BRP_ERRGRP_COMM_FRAMEFORMAT   0x04000000u
 The device or host send a frame that does not correspond the expected frame. More...
 
#define BRP_ERRGRP_COMM_UNDEFINED   0x08000000u
 any device <-> host communication problem which is not categoriezed by one of the BRP_ERRGRP_COMM_* macros More...
 
#define BRP_ERRGRP_COMMUNICATION   0x0F800000u
 Any kind of device <-> host communication problem. More...
 
#define BRP_ERRGRP_LIB_INVALIDCALL   0x10000000u
 The libraries API was used in an invalid manner. More...
 
#define BRP_ERRGRP_LIB_NONRECOVERABLE   0x20000000u
 A fatal error occured, which the library cannot recover from. More...
 
#define BRP_ERRGRP_LIB_OS   0x40000000u
 A error in the operating system layer (i.e. More...
 
#define BRP_ERRGRP_LIB_UNDEFINED   0x80000000u
 any library specific error which is not one of the BRP_ERRGRP_LIB_* macros. More...
 
#define BRP_ERRGRP_LIBRARY   0xF0000000u
 Any error which occured in the library. More...
 

BRP_ERR_XXX

A list of standard error codes that required all over this library.

#define BRP_OK   0x00000000u
 If a function of return type :brp_errcode runs properly, it returns this value. More...
 
#define BRP_ERR_INTERNAL   (0x0001u | BRP_ERRGRP_LIB_NONRECOVERABLE)
 This error must not be returned if the library operatares correctly. More...
 
#define BRP_ERR_CMD_TIMEOUT   (0x0002u | BRP_ERRGRP_COMM_TIMEOUT)
 A BRP command that was send by brp_send_frame() exceeded the specified timeout (see also brp_send_cmd() / brp_exec_cmd()). More...
 
#define BRP_ERR_FRAMEFORMAT   (0x0003u | BRP_ERRGRP_COMM_FRAMEFORMAT)
 The frame returned from the reader does not match the format expected by the BRP protocol. More...
 
#define BRP_ERR_INVALID_API_CALL   (0x0004u | BRP_ERRGRP_LIB_INVALIDCALL)
 Returned if the a parameter contains an invalid value. More...
 
#define BRP_ERR_OUT_OF_MEMORY   (0x0005u | BRP_ERRGRP_LIB_NONRECOVERABLE)
 The heap has not enough memory to allocate a buffer that is required for the wanted operation. More...
 
#define BRP_ERR_NOT_IMPLEMENTED   (0x0006u | BRP_ERRGRP_LIB_INVALIDCALL)
 The requested feature is not implemented yet. More...
 
#define BRP_ERR_BUSY   (0x0007u | BRP_ERRGRP_LIB_INVALIDCALL)
 The Library is not ready to send/receive data. More...
 
#define BRP_ERR_CLOSED   (0x0008u | BRP_ERRGRP_LIB_INVALIDCALL)
 The protocol/device is not opened. More...
 
#define BRP_ERR_BUFFER_OVERFLOW   (0x0009u | BRP_ERRGRP_COMM_FRAMEFORMAT)
 A Command's response is bigger than the buffer provided for the response. More...
 
#define BRP_ERR_OPEN_IO   (0x000Au | BRP_ERRGRP_LIB_OS)
 Failed to open the I/O connection. More...
 
#define BRP_ERR_WRITE_IO   (0x000Bu | BRP_ERRGRP_LIB_OS)
 Failed to send data via IO connection. More...
 
#define BRP_ERR_WAIT_IO   (0x000Cu | BRP_ERRGRP_LIB_OS)
 Failed to wait for data via IO connection. More...
 
#define BRP_ERR_READ_IO   (0x000Du | BRP_ERRGRP_LIB_OS)
 Failed to wait for data via IO connection. More...
 
#define BRP_ERR_CLOSE_IO   (0x000Eu | BRP_ERRGRP_LIB_OS)
 Failed to open the I/O connection. More...
 
#define BRP_ERR_PAYLOAD_FORMAT   (0x000Fu | BRP_ERRGRP_COMM_FRAMEFORMAT)
 The payload of a frame has invalid format. More...
 
#define BRP_ERR_CRYPTO_FORMAT   (0x0010u | BRP_ERRGRP_COMM_FRAMEFORMAT)
 The payload of a encrypted/PKI command or a PKI certificate had invalid format/response. More...
 
#define BRP_ERR_PKI_FORMAT   BRP_ERR_CRYPTO_FORMAT
 
#define BRP_ERR_DEV_CERT_FORMAT   (0x0011u | BRP_ERRGRP_COMM_FRAMEFORMAT)
 The devices PKI end-Certificate had invalid format. More...
 
#define BRP_ERR_HOST_CERT_FORMAT   (0x00012u | BRP_ERRGRP_COMM_FRAMEFORMAT)
 The hosts PKI Certificate or the devices CA certificates (which are stored on the host!) had invalid format. More...
 
#define BRP_ERR_PKI_OPERATION_FAILED   (0x0013u | BRP_ERRGRP_LIB_NONRECOVERABLE)
 A PKI operation cannot be executed. More...
 
#define BRP_ERR_DEV_CERT_INVALID_SIGNATURE   (0x0014u | BRP_ERRGRP_COMM_ACCESSDENIED)
 The ECC certificate of the device is invalid. More...
 
#define BRP_ERR_HOST_CERT_INVALID_SIGNATURE   (0x0015u | BRP_ERRGRP_COMM_ACCESSDENIED)
 The ECC certificate of the host is invalid or the devices CA certificates (which are stored on the host!) have invalid signature. More...
 
#define BRP_ERR_SEC_LEVEL_NOT_SUPPORTED   (0x0016u | BRP_ERRGRP_COMM_ACCESSDENIED)
 The given securitylevel is not supported. More...
 
#define BRP_ERR_SEQ_CTR_NOT_IN_SYNC   (0x0017u | BRP_ERRGRP_COMM_ACCESSDENIED)
 The sequence counter is not in sync any more. More...
 
#define BRP_ERR_INVALID_HMAC   (0x0018u | BRP_ERRGRP_COMM_ACCESSDENIED)
 The HMAC is invalid. More...
 
#define BRP_ERR_CRYPTO_RECV_DEV   (0x0019u | BRP_ERRGRP_COMM_ACCESSDENIED)
 device failed to decrypt PKI command successfully More...
 
#define BRP_ERR_UNSUPPORTED_COMMAND   (0x0020u | BRP_ERRGRP_COMM_UNSUPPORTED)
 The specified BRP command is not supported by the connected device. More...
 
#define BRP_ERR_COMMAND_DENIED   (0x0021u |BRP_ERRGRP_COMM_ACCESSDENIED)
 The BRP command is not allowed to be executed from the current security level. More...
 
#define BRP_ERR_UNEXPECTED_FRAME   (0x0022u | BRP_ERRGRP_COMM_FRAMEFORMAT)
 The received frame is a valid BRP frame but not expected in this protocol state. More...
 
#define BRP_ERR_TIMEOUT   (0x0023u | BRP_ERRGRP_COMM_TIMEOUT)
 The response to a brp_recv_frame() / brp_recv_any_frame() is not returned within the specified timeout. More...
 
#define BRP_ERR_CALLED_INVALID_FRAME   (0x0024u | BRP_ERRGRP_LIB_INVALIDCALL)
 Returned if the a frame passed to a function to be transferred to the device has invalid format. More...
 
#define BRP_ERR_EXISTING_LAYER   (0x0025u | BRP_ERRGRP_LIB_INVALIDCALL)
 The layer is tried to be added to a composite protocol (see brp_add_layer() / brp_set_layer()) although already added earliert. More...
 
#define BRP_ERR_GEN_RANDOM_DATA   (0x0026u | BRP_ERRGRP_LIB_OS)
 The OS failed to generate a random number. More...
 
#define BRP_ERR_INVALID_KEY   (0x0027u | BRP_ERRGRP_COMM_ACCESSDENIED)
 The readers KEY does not match the key of the host. More...
 
#define BRP_ERR_STATUS(cmd_code, statuscode)
 Error codes that happen on the reader side are encoded by this macro. More...
 

BRP_SECMODE_ Security Modes

BRP_SECMODE_* specifies the level of security that shall be applied when establishing a secure channel.

Internally this bitmask is translated to the authmode bitmask.

Security Modes

#define BRP_SECMODE_STD   0
 This is the recommended setting as it provides ideal security. More...
 
#define BRP_SECMODE_PLAIN   1
 Same as BRP_SECMODE_STD, except that encryption is disabled. More...
 
#define BRP_SECMODE_STATELESS   2
 Allows secured communication without session handling. More...
 

Detailed Description