Zymkey can be used to assist in the TLS handshake process and Certificate Signing Request (CSR) generation for sessions that are configured as ECDSA NIST P-256.
Every Zymkey contains a unique ECDSA private key that is both generated and stored inside the onboard encryption engine. The key cannot be read, or exported. Each key is randomly generated using an onboard True Random Number Generator (TRNG - conforming to NIST SP800-22) plus additional entropy.
Simplified Use Case
In this example, it is assumed that the Zymkey has been bound to a host Raspberry Pi. Also, this example was performed against an Apache server based on Ubuntu. We offer an easily distributable docker image for the Apache setup as well as the baseline configuration steps.
Install the necessary software packages and bind Zymkey using the USB or I2C tutorials. The Zymkey should be visible and read as "bound" from the Zymbit console.
- Be sure docker is running on your host system. I am running Docker 1.12.3 on OSX. By default, your docker install should come equipped with docker-compose; which we utilize here for getting up and running quickly.
- Clone the
git clone https://github.com/zymbit/zymkey-apache-server.git
- From the
zymkey-apache-server directory run the command:
docker-compose run app
Certificate Authority Configuration
To create a CA specifically for zymkeys, run the
mk_ca.sh script using
docker exec zymkeyapacheserver_app_run_1 mk_ca.sh
You should have the following files in your
ca-chain.pem zk_ca.crt zk_ca.key
Generate Certificate Signing Request
Secure shell to your host pi and run the command:
openssl req -key nonzymkey.key -new -out zymkey.csr -engine zymkey_ssl -keyform e -subj "/C=US/ST=California/L=Santa Barbara/O=Zymbit/OU=Zymkey/CN=rpi.edge.zymbit.com"
nonzymkey.key is a dummy file and does not need to be created. It is merely a placeholder which prevents openssl from generating a default key.
-subj parameter allows the CSR to be formed in non-interactive mode. Replace the CSR information as needed.
Now send the CSR to your Server with the Certificate Authority (CA). I used
Generate Self-Signed Certificate on CA Server
To generate a certificate from the csr in the previous step, it is easiest to use the
sign_csr.sh utility provided. Since our server is running isolated within a docker container we will use
docker exec to run the utility.
docker exec zymkeyapacheserver_app_run_1 sign_csr.sh zymkey.csr zymkey.crt
openssl to generate a self-signed certificate on the Apache CA server. Now send/
scp the newly generated certificate back to the host pi.
Test TLS Connection
Secure shell back to your Raspberry Pi and run curl to request connection to your apache test server:
curl --insecure -H 'Host: zymkey-verify.zymbit.com.dev' https://:4430/ -k -tlsv1.2 --cert zymkey.crt --key nonzymkey.key --engine zymkey_ssl --key-typ ENG -v
The verbose output will show the successful TLS handshake and HTTPS connection using the Zymkey private key!