This page explains how to generate public/private key pairs using OpenSSL command-line tools.
Device authentication
Cloud 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 Cloud IoT Core as proof of the device's identity.
- The service uses the device public key (uploaded before the JWT is sent) to verify the device's identity.
Cloud 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 the following 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 the following 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 Cloud IoT Core and used to verify the signature of the authentication JWT.
Generating an RSA key with a self-signed X.509 certificate
If you're validating keys against registry-level certificates, the certificate must meet certain requirements. One of these requirements is that the certificate use the X.509 standard.
To generate a 2048-bit RSA private key and a self-signed X.509 certificate with a SHA-256 signature, run the following 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, or you can omit -subj and supply the certificate
information when prompted. (Cloud IoT Core does not verify the
subject.)
By default, X.509 certificates expire 30 days after creation. To set the number
of days until the certificate expires, add the -days <n> flag at creation
time. If you try to create or update a device with an expired certificate, or
try to connect a device to a registry and the registry's certificate has
expired, Cloud IoT Core returns an error.
Generating an Elliptic Curve keys
You can use the following 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 the following 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 Cloud IoT Core and used to verify the signature of the authentication JWT.
Generating an ES256 key with a self-signed X.509 certificate
If you're validating keys against registry-level certificates, the certificate must meet certain additional requirements not covered in this page. One of these requirements is that the certificate use the X.509 standard.
Run the following commands 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, or you can omit -subj and supply the certificate
information when prompted. (Cloud IoT Core does not verify the subject.)
By default, X.509 certificates expire 30 days after creation. To set the number
of days until the certificate expires, add the -days <n> flag at creation
time. If you try to create or update a device with an expired certificate, or
try to connect a device to a registry and the registry's certificate has
expired, Cloud IoT Core returns an error.
Converting keys to PKCS8 for Java
In Java, you need to convert private keys to the PKCS8 format. To convert RSA and Elliptic Curve keys from PEM format to PKCS8 format, run the following 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
Be sure to review the device security recommendations and consider implementing key rotation.
You can also use optional registry-level certificates to verify key credentials.