Establish a PKI-authenticated and encrypted connection

To establish a PKI-authenticated and encrypted connection, you need to add the following to your code.

Specify security level

Hardcode the application's security level. In most cases, only level 1 is configured. However, multiple security levels may be configured if the readers are accessed by multiple applications, and each application is given different permissions.

The number specified here must match the security level specified in BALTECH PKI Certificate Manager when creating the PKI project (If you created the PKI with openSSL instead, it must match the security level passed when storing the signed end entity certificate on the reader.)

#define SECURITY_LEVEL // can be 1, 2, or 3

Start an authenticated and encrypted session

In your protocol stack, run the following commands before connecting to the reader with brp_open():

• To start an authenticated and encrypted session, run brp_create_pki().
• Pass it to brp_set_crypto() to assign a crypto protocol object to your protocol stack.

brp_set_crypto(dev,brp_create_pki());

brp_create_pki() passes the host's public key to the reader, including the certificates needed for host authentication. Based on the host's private key and the reader's certificate chain, a session key is generated that encrypts all commands sent afterwards.

Parameter	Description
security_level	The security level hardcoded in the application
host_cert_chain	Certificate chain of the host in ASN.1 DER format Tips To convert Base64-encoded certificates (e.g. PEM, CRT) into DER format, use brp_decode_base64_obj() To pass certificates individually instead of passing them all in this command, set this parameter to NULL and run brp_append_dev_ca_certs afterwards.
dev_ca_cert_chain	Certificate chain of the reader in ASN.1 DER format Due to storage limitations on the reader, the reader certificate chain needs to be stored on the host. You need to pass it each time you establish an authenticated and encrypted connection. Tips To convert Base64-encoded certificates (e.g. PEM, CRT) into DER format, use brp_decode_base64_obj() To pass certificates individually instead of passing them all in this command, set this parameter to NULL and run brp_append_dev_ca_certs afterwards.
private_key	Private key of the host ASN.1 DER format; it is used by the SDK to establish the connection on behalf of the host application. Tip To convert Base64-encoded keys (e.g. PEM, CRT) into DER format, use brp_decode_base64_obj()
session_timeout	Defines how long the session (and thus the session key) is valid. Regular timeouts are an important security measure; however, starting a new session is very time-consuming. That's why the best practice is a timeout every 24 hours (i.e. 86400000 ms) during a timeslot with little activity, e.g. at night. Notes for host as server implementation After the timeout, readers open a new TCP connection to the host by sending the identification frame SessionKeyTimeout (0x0004). You then need to start a new session by running brp_create_pki() again. To improve performance when you have a large number of readers, save the session state to restore it for the next TCP connection as described below.

Save and restore the session state

When you implement your host application as a server and have a large number of readers, we recommend you maintain a TCP connection only as long as needed. This helps save computing power and bandwidth. However, it's very time consuming to start a new session for each new TCP connection. That's why we recommend you save the state of the crypto protocol object and restore it when starting the next session:

• Before closing an active TCP connection, run brp_pki_save_session() to save the session state including the session key.
  To first calculate the required buffer size, run brp_pki_get_session_buf_size(). Then reserve the buffer and pass it to brp_pki_save_session().
• Store the session state, e.g. in a database.

• Once a new TCP connection has been established, run the following sequence:

  • To start an authenticated and encrypted session, run brp_create_pki() and pass it to brp_set_crypto().

  • To restore the session state, run pki_restore_session().

  • Run brp_open() and follow the protocol stack lifecycle from there.

Try it out with our app note

The app note appnotes\tcp_server in the SDK gives you a working examples of the implementation
(learn more about app notes).