Verifying device credentials

Cloud IoT Core offers per-device public/private key authentication using JSON Web Tokens (JWTs). For additional security, Cloud IoT Core can verify device public key certificates against registry-level CA certificates.

Registry-level CA certificates are an optional feature for additional security; you are not required to use them.

A verified certificate attests that a public/private key pair belongs to a legitimate device. This can be especially useful when the device manufacturer creates public and private keys, stores the private key on the device, and has the public key signed by the CA.

Generating CA certificates

Cloud IoT Core can verify device public key certificates against self-signed CA certificates and CA certificates generated by a trusted third party. Both kinds of CA certificates are used the same way, but each is generated differently.

Self-signed CA certificates Third-party CA certificates
Device private key owners can generate the certificates A trusted third party must generate the certificates
Device private key owners create and own the CA private keys that sign the certificates A third party creates and owns the CA private keys that sign the certificates
Free to generate Third parties bill to generate certificates and establish a chain of trust with the CA

Self-signed CA certificates

To generate a self-signed CA certificate (and corresponding CA private key), complete the following steps:

  1. Create a CA private key. The CA private key will be uniquely associated with the CA certificate. You can generate a 2048-bit RSA private key with the following command:
    openssl genpkey -algorithm RSA -out ca_private.pem -pkeyopt rsa_keygen_bits:2048
    
  2. Generate the self-signed CA certificate. The following command generates an RS256 certificate that meets the CA certificate requirements:
    openssl req -x509 -new -nodes -key ca_private.pem -sha256 -out ca_cert.pem -subj "/CN=unused"
    

See Generating an RSA key with a self-signed X.509 certificate or Generating an ES256 key with a self-signed X.509 certificate for more examples.

Third-party CA certificates

To get a CA certificate from a trusted third party, submit a CSR to the CA. The CA then sends you a CA certificate with the corresponding device public key certificate, signed by the CA private key. To get third-party CA certificates:

  1. Create a device private key. You can generate a 2048-bit RSA private key with the following command:
    openssl genpkey -algorithm RSA -out rsa_private.pem -pkeyopt rsa_keygen_bits:2048
    
  2. Create a CSR from the device private key. The CSR keeps the private key secret. The following command generates a CSR with a SHA-256 signature:
    openssl req -new -sha256 -key rsa_private.pem -out rsa_cert.csr -subj "/CN=unused"
    
  3. Send the CSR to a CA and apply for a certificate. Each CA has a different application process. For instance, you may need to register an account with the CA and upload the CSR to an online portal.

CA certificate requirements

All registry-level CA certificates must meet the following requirements:

  • The CA certificate must be in the X.509v3 (RFC 5280) format, encoded in base64, and wrapped in -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.
  • The CA certificate must be a .pem file encrypted with a supported algorithm:
    • RSA with at least 2048 bits
    • NIST P-256
  • The CA certificate must be valid. If you try to add a device to a registry and the registry's certificate has expired, Cloud IoT Core returns an error.

Adding CA certificates to a registry

Once you have CA certificates, add them to a registry. Cloud IoT Core verifies CA certificates at the registry level, so all CA certificates must be associated with a registry. A certificate can be added to multiple registries. You can add CA certificates with the Google Cloud Platform Console, the API, or gcloud.

Console

  1. Go to the Registries page in GCP Console.

    Go to the Registries page

  2. At the top of the page, click Create Registry.

  3. Click Add CA certificate to type/paste a certificate or upload a certificate .pem file. You can add only one certificate when first creating the registry, but you can add more certificates later (up to 10).

The Device registry details page includes a Certificates tab that shows the existing certificates and allows you to add more.

gcloud

To add or manage CA certificates, run one of the gcloud iot registries credentials commands.

To add a new certificate to a registry, run the gcloud iot registries credentials create command:

gcloud iot registries credentials create \
    --path=PATH_TO_CERTIFICATE \
    --project=PROJECT_ID \
    --registry=REGISTRY_ID \
    --region=REGION

API

The DeviceRegistry resource includes fields for defining CA certificates at the registry level:

Effect on existing devices

When you add or remove certificates, existing devices in the registry (whether connected or not) are not affected. If a device's associated registry-level certificates are revoked, deleted, or modified, the device can't use the same public key certificates it used when the registry-level certificates were in force, but it can still connect to Cloud IoT Core with its private key.

Generating public key certificates

Cloud IoT Core verifies device public key certificates signed by CA private keys.

To generate a signed public key certificate:

  • If the registry is configured with a self-signed CA certificate, sign a public key with the CA private key.
    1. Create a device private key. This key is different than the CA certificate and CA private key. You can generate a 2048-bit RSA private key with the following command:
      openssl genpkey -algorithm RSA -out rsa_private.pem -pkeyopt rsa_keygen_bits:2048
      
    2. Create a CSR from the device private key. The following command generates a CSR with a SHA-256 signature:
      openssl req -new -sha256 -key rsa_private.pem -out rsa_cert.csr -subj "/CN=unused-device"
      
    3. Create a public key and sign it with the CA private key. The following command generates a signed RS256 certificate that meets the public key certificate requirements:
      openssl x509 -req -in rsa_cert.csr -CA ca_cert.pem -CAkey ca_private.pem \
          -CAcreateserial -sha256 -out rsa_cert.pem
      
  • If a registry is configured with a third-party CA certificate, the CA certificate contains a device public key certificate signed by the CA private key. You can extract an RSA device public key certificate from an RSA CA certificate with the following command:
    openssl rsa -in ca_cert.pem -pubout -out rsa_cert.pem
    

Public key certificate requirements

Device public key certificates must meet the following requirements (in addition to the standard Cloud IoT Core requirements for device credentials) in order to verify them against registry-level CA certificates:

  • The CA certificate must be in the X.509v3 (RFC 5280) format, encoded in base64, and wrapped in -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.
  • The device public key certificate must be signed by a specific CA certificate at the registry level; intermediary CAs are not supported.
    • The device public key certificate must not be identical to the registry-level certificate.
  • No raw public keys.
  • Supported JWT algorithms:
  • The device public key certificate must be valid. If you try to create or update a device with an expired certificate, Cloud IoT Core returns an error.

These requirements are enforced when you create or update the device. If a registry does not have any CA certificates defined for it, all device public keys are unconditionally accepted.

Verifying public key certificates

Cloud IoT Core verifies device public key certificates against registry-level CA certificates when you create a device or modify its public keys. You can create a device using the GCP Console, API, or gcloud. You can add, remove, and edit public keys with the GCP Console or API.

Console

  1. Go to the Registries page in GCP Console.

    Go to the Registries page

  2. Click the ID of the registry for the device.

  3. In the registry menu on the left, click Devices.

  4. Click Create a device.

    To modify a device's public keys, click the device's ID on the Devices page, and then click Edit device at the top of the page.

  5. Enter a Device ID that briefly describes the device or otherwise helps you identify it. (This field can't be edited later.) For information on device naming and size requirements, see Permitted characters and size requirements.

  6. For Device communication, select Allow or Block. This option allows you to block communication when needed, such as when a device is not functioning properly. In most cases, you'll want to allow communication when first creating the device.

  7. For Public key format, select RS256_X509 or ES256_X509. Paste the device public key certificate in the Public key value field. You can also set an expiration date for the key.

    To add a key to an existing device, click Add public key on the Device details page.

    To remove a key from an existing device:

    1. Check the box next to the key on the Device details page.
    2. Click Delete to remove the key.

    To edit a key, click the Edit icon next to the key on the Device details page.

  8. Select the Input method you want to use to enter the device public key certificate.

    • Manual: Copy and paste the device public key certificate into the Public key value field
    • Upload: In the Public key value field, click Browse to select a file on your computer
  9. Use the Key and Value fields to add optional device metadata, such as a serial number. For information on metadata key-value naming and size requirements, see Permitted characters and size requirements.

  10. Select a Stackdriver Logging level to determine which device events are sent to Stackdriver Logging.

  11. Click Create to create the device.

gcloud

To create a device, run the gcloud iot devices create command.

To create a device with RS256 credentials that meet the device certificate requirements, run the following command:

gcloud iot devices create DEVICE_ID \
    --project=PROJECT_ID \
    --region=REGION \
    --registry=REGISTRY_ID \
    --public-key path=rsa_cert.pem,type=rsa-x509-pem

To create a device with ES256 credentials that meet the device certificate requirements, run the following command:

gcloud iot devices create DEVICE_ID \
    --project=PROJECT_ID \
    --region=REGION \
    --registry=REGISTRY_ID \
    --public-key path=ec_cert.pem,type=es256-x509-pem

API

Use the following methods to create devices or modify public keys:

Public keys are specified in the credentials field of the Device resource in the Cloud IoT Core API. See DeviceCredential in the Device resource for more information.

Because one or more registry-level certificates are present, the Device resource must meet the device certificate requirements.

  • The Device.credentials[i].public_key.key field must be set to the contents of the device public key certificate (including the header and the footer).
  • The Device.credentials[i].public_key.format field must be set to RSA_X509_PEM or ES256_X509_PEM.
Bu sayfayı yararlı buldunuz mu? Lütfen görüşünüzü bildirin:

Şunun hakkında geri bildirim gönderin...

Cloud IoT Core Documentation