Creating key pairs

This page explains how to generate public/private key pairs using OpenSSL command-line tools.

Device authentication

ClearBlade IoT Core uses public key (or asymmetric) authentication:

The device uses a private key to sign a JSON Web Token (JWT). The token is passed to ClearBlade IoT Core as proof of the device's identity.
The service uses the device’s public key (uploaded before the JWT is sent) to verify the device's identity.

ClearBlade IoT Core supports the RSA and elliptic curve algorithms. For details on key formats, see Public key format.

Generating an RSA key

You can generate a 2048-bit RSA key pair with these commands:

openssl genpkey -algorithm RSA -out rsa_private.pem -pkeyopt rsa_keygen_bits:2048
openssl rsa -in rsa_private.pem -pubout -out rsa_public.pem

These commands create this public/private key pair:

rsa_private.pem: The private key that must be securely stored on the device and used to sign the authentication JWT.
rsa_public.pem: The public key that must be stored in ClearBlade IoT Core and used to verify the authentication JWT’s signature.

Generating an RSA key with a self-signed X.509 certificate

The certificate must meet specific requirements if you validate keys against registry-level certificates. One of these requirements is that the certificate uses the X.509 standard.

To generate a 2048-bit RSA private key and a self-signed X.509 certificate with an SHA-256 signature, run this command:

openssl req -x509 -nodes -newkey rsa:2048 -keyout rsa_private.pem -out rsa_cert.pem -subj "/CN=unused"

You can replace the -subj argument with an actual certificate subject and use that certificate. Alternatively, you can omit -subj and supply the certificate information when prompted (ClearBlade IoT Core does not verify the subject).

By default, X.509 certificates expire 30 days after creation. Add the -days <n> flag at creation time to set the number of days until the certificate expires. If you try to create or update a device with an expired certificate or try to connect a device to a registry and the certificate has expired, ClearBlade IoT Core returns an error.

Generating elliptic curve keys

You can use these commands to generate a P-256 elliptic curve key pair:

openssl ecparam -genkey -name prime256v1 -noout -out ec_private.pem
openssl ec -in ec_private.pem -pubout -out ec_public.pem

These commands create this public/private key pair:

ec_private.pem: The private key that must be securely stored on the device and used to sign the authentication JWT.
ec_public.pem: The public key that must be stored in ClearBlade IoT Core and used to verify the authentication JWT’s signature.

Generating an ES256 key with a self-signed X.509 certificate

If you're validating keys against registry-level certificates, the certificate must meet specific requirements. One of these requirements is that the certificate uses the X.509 standard.

Run this command to generate an ES256 key with a self-signed X.509 certificate:

openssl req -x509 -new -key ec_private.pem -out ec_cert.pem -subj "/CN=unused"

You can replace the -subj argument with an actual certificate subject and use that certificate. Alternatively, you can omit -subj and supply the certificate information when prompted (ClearBlade IoT Core does not verify the subject).

By default, X.509 certificates expire 30 days after creation. Add the -days <n> flag at creation time to set the number of days until the certificate expires. If you try to create or update a device with an expired certificate or try to connect a device to a registry and the certificate has expired, ClearBlade IoT Core returns an error.

Converting keys to PKCS #8 for Java

In Java, you must convert private keys to the PKCS #8 format. To convert RSA and elliptic curve keys from PEM format to PKCS #8 format, run these commands:

RSA

openssl pkcs8 -topk8 -inform PEM -outform DER -in rsa_private.pem -nocrypt > rsa_private_pkcs8

Elliptic curve

openssl pkcs8 -topk8 -inform PEM -outform DER -in ec_private.pem -nocrypt > ec_private_pkcs8

Managing keys

Review the device security recommendations and consider implementing key rotation.

You can also use registry-level certificates to verify key credentials.

Generate a signed RS256_X509 device certificate and private key

1. Generate the private key and certificate request. Change the number of days the certificate should be valid as per your requirements:
openssl req -newkey rsa:2048 -nodes -days 365000 -keyout client-key.pem -out client-rsa-req.pem

You will be shown this prompt to enter a common name:
Common Name (e.g., server FQDN or YOUR name) []:
Ensure the common name is different from the CA certificate one.

2. Generate the X509 device certificate:
openssl x509 -req -days 365000 -set_serial 01 -in client-rsa-req.pem -out client-rsa-cert.pem -CA ca-cert.pem -CAkey ca-key.pem

3. Verify the signed X509 device certificate:
openssl verify -CAfile ca-cert.pem ca-cert.pem client-rsa-cert.pem

Generate a signed ES256_X509 device certificate and private key

1. Generate a private key:
openssl ecparam -genkey -name prime256v1 -out client-ec-key.pem

2. Generate the certificate request:
openssl req -new -key client-ec-key.pem -out client-ec-cert-req.pem