GroveStreams Help Center
GS MQTT Certificates (Beta)



Overview

X.509 certificates are used by GroveStreams to authenticate client and device connections. Client certificates must be registered within a GroveStreams organization before a client can communicate with the GroveStreams MQTT servers. A client device certificate can only be registered within one GroveStreams organization. A client certificate authority (CA) can be registered in one or more organizations.

We recommend that each device or client be given a unique certificate. Devices and clients should also support rotation and replacement of certificates to help ensure smooth operation as certificates expire or become compromised.

Certificate Policies Certificate Certificate Operations
Rolling Backup/Restore GroveStreams Public Certificate


Certificate management can be done within Observation Studio: Choose Toolbar - Admin - Security MQTT Message Broker Certificates
GroveStreams - MQTT Certificate Menu

GroveStreams - MQTT Certificates


Certificate Policies

Every certificate is required to have a policy. A policy determines which MQTT topic actions are allowed for a certificate. A single policy can be used by many certificates. Certificate management can be done within Observation Studio: Choose Toolbar - Admin - Security MQTT Message Broker Certificates and then right click on Client Certificate Policies.

  • Name: The name of the policy.
  • ID: Used by API calls. It must be unique within the organization.
  • Permission Sets: A collection of topics and actions allowed for the collection of topics.
  • Topics: A collection of topics. Wildcards # and * are allowed.
  • Topic Actions:
    • PUBLISH: The ability to publish.
    • PUBLISH_RETAIN_MESSAGE: The ability to publish while retaining the message.
    • SUBSCRIBE: The ability to subscribe.
See the GroveStreams Raspberry Pi - MQTT Tutorial Extras for an example of creating a Policy.

Certificate

A GroveStreams certificate represents an imported X.509 certificate along with metadata.

Where to get an X.509 Certificate
There are many ways to obtain X.509 certificates for your IoT devices. These include purchasing certificates or generating your own self-signed certificates using tools such as OpenSSL or keytool.

Generating certificates is ideal for prototyping and testing as it is quick and affordable, but this is not recommended for production systems as it provides few guarantees around security.

There are many commercial certificate vendors. Do a search to find one: Certificate Search

The problem is finding one that is affordable for thousands of devices. Let us know if you find an affordable vendor for buying thousands of device certificates or one affordable signing certificate from a root certificate authority (that allows you to sign your own generated device certificates).

See the Certificates in Production (the .sh scripts) and Rolling X.509 expired certificates for more information around X.509 certificates.

Importing an X.509 Certificate
Right-click on a certificate folder and select New to import a public key X.509 certificate or bundle. Each public certificate in the trust chain, even the root, needs to be imported. Certificates are identified internally by their distinguished name (DN). The certificate DN must be unique across all organizations for device certificates. CA certificates can be used across organizations.

  • Status: ACTIVE or INACTIVE. Any status of INACTIVE within a certificate chain will block MQTT calls using a certificate below within the chain.
  • Name: The name of the certificate. Defaults to the X.509 certificate distinguished name.
  • CA indicator: Indicates whether the a certificate is a certificate authority (CA). The import process will try to determine if the certificate is a CA. Sometimes it gets it wrong and this setting allows it to be changed.
  • Policy: The policy used by the certificate while processing MQTT calls.
  • Run as user for HTTP API Calls (optional): MQTT HTTP API calls will run under this selected user's access security settings.
  • Component Registration - Template: A component will be created based on the selected template if the component does not exist on the initial call.
  • Component Registration- Initial Folder: The folder to place a new component into. The folder will be created if it does not exist during the registration process.
  • Pin to Host Address: Pinning associates a host with this certificate. The IP address of the host must match the pinned IP address for all calls. The IP address will be automatically set during the first call if it is blank here. Clear the pinned IP address and save the certificate to automatically reset pinning.
  • Pin to Component: Pinning will associate a component with this certificate. The component can be selected manually here or automatically assigned during its creation during a device feed publish. Components pinned to a certificate will participate in certificate operations such as rolling certificates. Clear the selected component and save the certificate to automatically have the next component that uses the certificate pinned.
  • Certificate Details: The X.509 certificate details.
See the GroveStreams Raspberry Pi - MQTT Tutorial Extras for an example of creating a certificate and importing it.

Certificate Operations

A certificate operation allows for batch processing of certificates under a selected folder. Processing can be started by right-clicking on an operation and selecting Execute Certificate Operation Now or by setting up a schedule.

Operation results can be sent by email. Operation exceptions will be reported as System Notifications.

Operation Types
  • Report Expiring: Iterates over all certificates under the selected folder and will email a list of all expiring certificates.
  • Roll Expiring: Iterates over all certificates under the selected folder and will publish an MQTT topic {orgUid}/manage/cert/roll/cid/{componentId} to each component/device pinned to the certificate if the certificate is expiring. It is the responsibility of the device to do the actual rolling. An email may be sent with a list of all processed certificates.
  • Roll all Certificates: Iterates over all certificates under the selected folder and will publish an MQTT topic {orgUid}/manage/cert/roll/cid/{componentId} to each component/device pinned to the certificate. It is the responsibility of the device to do the actual rolling. An email may be sent with a list of all processed certificates.
  • Update Truststore: Notifies each device to update its truststore with a new GroveStreams public certificate. Iterates over all certificates under the selected folder and will publish an MQTT topic {orgUid}/manage/cert/update_truststore/cid/{componentId} to each component/device pinned to the certificate. The entity of the publish will be a UTF8 String version of the GroveStreams publish certificate.
  • Take Action: Execute an action defined under Tools - Even Action Packages (left side of Observation Studio). Add an MQTT Publish action, or any other action to the action package. The Action Package Action Client Certificate will be substituted with the current certificate being processed during the operation. Action message variables such as, [component.id], are supported. [component.id] will be substituted with the ID of the current certificates' pinned component's ID. Action Package - MQTT Publish Action editor:
    GroveStreams - MQTT Action Package


Scheduling and EMail
Operations may be scheduled and results emailed.

GroveStreams - MQTT Certificate Operation Schedule

See the Rasperry Pi Tutorial Extras for certificate operation examples.


Rolling

You'll need to roll certificates during the life cycle of your IoT solution. This is mainly due to security breaches and certificates expiring. Highly sensitive data solutions may require daily rotations while others may roll every couple of years.

GroveStreams Certificate Operations are designed for detecting expiring certificates and optionally rolling them.

See the Rolling X.509 expired certificates for detailed information on rolling.

Backup/Restore

Certificates, Policies, and Operations are included as part of the organization backup and restore process.

GroveStreams Public Certificate

MQTT clients that are Subscribing will need the GroveStreams Public certificate on the device. It can be downloaded by Right-Clicking any folder within the Admin - Security - MQTT Certificates window and selecting Download GroveStreams public certificate.

See the Rasperry Pi Tutorial code for using the GroveStreams public certificate within a local truststore.
See Updating the Pi's GroveStreams public certificate remotely for and example of rolling the GS public certificate.