Establish a PKI-encrypted connection

To establish a PKI-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 encrypted session

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

brp_set_crypto(dev,brp_create_pki());

brp_create_pki() passes the host's public key to the reader, including the certificates needed by the reader to verify the host's public key. 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
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 encrypted connection.
Tips
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
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 Ethernet server mode
  • 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 run your host application in Ethernet server mode 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 encrypted 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:

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).