SSL provides certificate and trust management in addition to providing secure and encrypted communication. An SSL enabled server is required to provide a certificate to the connected clients thus the server cannot operate without an installed certificate. The client however, can function without a certificate. Using client certificates are therefore optional at the SSL level, however your design may have a requirement on using client certificates when client authentication is needed.
Certificate management is a complex component that is generally required by all applications using the SSL protocol. We provide an online certificate management tutorial for those that are new to certificate management.
The Certificate Management for IoT tutorial shows how to use our certificate management tool for setting up a certificate authority and signing certificates by using this tool. The tutorial is tailored for devices using SharkSSL as a client.
Introduction to SSL Certificates and Private Key
SSL certificates are encoded in the binary format specified in the X.509 ITU-T standard, which is a well established telecom standard for storing structured binary data. The binary X.509 data is sometimes stored as raw binary data and sometimes encoded using Base64 encoding. Several X.509 encoding formats exists. SharkSSL can handle the following formats: .PEM, .DER, and .P7B.
Typically, a certificate's private key and public certificate are stored as two .PEM encoded files. Root certificates (CAs) are typically stored in the container format .P7B, which can store multiple CAs. The root certificates are used by SharkSSL when certifying (authenticating) the peer side.
Introduction to Certificate Authority Certificates
A CA certificate can be used by SharkSSL during the initial SSL handshake. The CA is then used as a trusted third party and SharkSSL uses the CA for certifying the peer's certificate. Certifying the peer side is optional in SharkSSL, however, if used, the peer side must provide a certificate signed by a trusted CA as part of the SSL handshake.
The CA certificate(s) must be stored in the device, either on a file system or integrated into the firmware. In many cases, only one CA certificate is required in the device. The same CA can be used to sign all certificates the device must verify. The Certificate Management Example Programs shows how to store and use multiple CAs.
Certificate Management with SharkSSL
SharkSSL uses its own binary format for storing certificates, a format optimized for speed and size thus making it ideal for small microcontrollers. SharkSSL includes high level functions that converts standard .PEM, .DER, and .P7B formats into its internal format. The high level functions are included in the SharkSSL source by default, but we recommend that you disable this code in microcontroller based applications. You can control the inclusion/exclusion of these functions by tuning the SharkSSL_cfg.h configuration file. In particular, the macro SHARKSSL_ENABLE_PEM_API and SHARKSSL_ENABLE_CERTSTORE_API either excludes or includes the certificate management functions.
We provide a number of command line programs that can convert standard certificates into the optimized SharkSSL format. You use these command line tools when you exclude the high level certificate functions from the SharkSSL code base.
Using the High Level SharkSSL Certificate APIs
The high level SharkSSL certificate APIs enable you to load and convert certificates to the internal format used by SharkSSL. The converted certificates are stored in RAM memory (it is for this reason we recommend that you do not include the high level APIs when using SharkSSL in a microcontroller). The APIs are divided into loading SharkSSL certificates and for loading CA root certificates.
SharkSSL Certificate
A SharkSSL certificate is a combination of the certificate (the public part) and the certificate key (the private part). The following figure shows how the SharkSslParseCert tool converts these two components into one SharkSSL certificate.
A SharkSSL certificate is loaded and converted to the internal format by calling function sharkssl_PEM. The resulting SharkSSL certificate can then be used as the SharkSslCert argument when calling the SharkSsl_addCertificate function. The high level sharkssl_PEM certificate function performs the same conversion as the command line tool SharkSslParseCert.
CA Certificate
CA certificates are optional and can be used by SharkSSL to authenticate the peer side. You instruct SharkSSL to load one or multiple CA certificates as follows:
- Call SharkSslCertStore_constructor
- For each certificate, call SharkSslCertStore_add
- Finish by calling SharkSslCertStore_assemble
Function SharkSslCertStore_assemble converts and stores all CA certificates as a SharkSslCAList object. This object can then be used as an argument when calling SharkSsl_setCAList. The SharkSslCertStore functions perform the same conversion as the command line tool SharkSSLParseCAList.
SharkSSL Certificate Command Line Tools
The SharkSSL certificate command line tools convert X.509 certificates from various formats to the proprietary SharkSSL formats. The tools are used when the high level SharkSSL certificate APIs are excluded from SharkSSL at compile time. The tools are also integrated in the certificate management tool.
The tools can create one of the following:
- A binary file
- A C header file, where the binary data is provided in a C array.
Creating a C array is the most convenient method since the header file includes data that can be fed directly into the API function. You use a binary file if you do want to separate the certificate(s) from the firmware image. The binary file can for example be stored in a separate section in flash memory and the pointer to the start of this section can be fed to the API function.
SharkSslParseCert
A SharkSSL certificate is a combination of the certificate (the public part) and the certificate key (the private part). The following figure shows how the SharkSslParseCert tool converts these two components into one SharkSSL certificate.
Usage:
SharkSSLParseCert MyCertFile.cert MyPrivateKey.key [-p passkey] [-b MyBinFile.bin] MyCertFile.cert : a certificate file, in PEM format and this certificate must have been signed with either RSA or ECDSA. The certificate's public key must be of type RSA or ECDH. MyPrivateKey.key: private key file, in PEM format; must match the public key in MyCertFile.cert and can be encrypted using 3DES, AES-128 or AES-256 passkey: mandatory only when the private key is encrypted, this is the encryption key (an ASCII string)
If the -b flag is not specified, the output goes to "stdout", thus it must be redirected to a file using the > operator. The -b flag can optionally be used instead of creating a header file. The binary certificate is then written to the filename following the -b flag.
Example:
SharkSSLParseCert MyCertFile.cert MyPrivateKey.key > MyCert.h
The SharkSSL certificate in MyCert.h can then be used as input when calling the SharkSsl_addCertificate function.
SharkSSLParseCAList
CA certificates are optional and can be used by SharkSSL to verify the peer side. The SharkSSLParseCAList converts one or multiple CAs into one SharkSslCAList object.
Usage:
SharkSSLParseCAList [-b MyCAList.bin] cert1.pem cert2.der certlist.p7b
If the -b flag is not specified, the output goes to "stdout", thus it must be redirected to a file using the > operator. The -b flag can optionally be used instead of creating a header file. The binary certificate is then written to the filename following the -b flag.
A sequence of parameter can be specified, each one being the name of a certificate in .PEM or .DER format, or a set of certificates in .P7B format
Example: SharkSSLParseCAList OneCert.pem ManyCerts.p7b >MyCaList.h
The CA list in MyCaList.h can then be used as input when calling the SharkSsl_setCAList function.
SharkSslParseKey
Usage:
SharkSslParseKey \<privkey file\> [-p \<passkey\>] [-b \<binary output file\>]
SharkSslParseKey \<pubkey file\> [-b \<binary output file\>]
SharkSSLParsePSKTable
Usage: SharkSSLParsePSKTable.exe <PSK file> [-b <binary output file>]