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
- To create an encrypted session, run brp_create_pki()call_made.
- Pass it to brp_set_crypto()call_made to assign a crypto protocol object to your protocol stack.
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.
|The security level hardcoded in the application|
Certificate chain of the host in ASN.1 DER format
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.
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.
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
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:
- Before closing an active TCP connection, run
brp_pki_save_session()call_made to save the
session state including the session key.
To first calculate the required buffer size, run brp_pki_get_session_buf_size()call_made. Then reserve the buffer and pass it to
- Store the session state, e.g. in a database.
Once a new TCP connection has been established, run the following sequence:
Try it out with our app note
The app note
appnotes\tcp_server in the SDK gives you a working examples of the
(learn more about app notes).