certs

README

certs service

Objective

Manage certificates for authentication of hub services, IoT devices and inter-domain hub services.

This manages the Hub certificates, including a Hub self-signed CA, Hub server certificate and hub service client certificates. The certificates are intended for machine-to-machine authentication of hub services and IoT devices. Users are authenticated using tokens and outside the scope of this plugin.

Summary

This Hub CLI manages authentication certificates for use by services, IoT devices and end-users on the local network:

• create the Hub CA certificate for generating signed certificates
• create the Hub server certificate for use by Hub services (currently a single server certificate for all Hub services)
• create client certificates for use by Hub services (currently a single client certificate for all Hub services)
• create IoT device client certificates for use by IoT client authentication as used by the idprov provisioning service

Limitations: Certificate revocation is not currently supported. If the private key of the CA, server or Hub service certificate is compromised then the recommended action is to delete all keys including the CA private key and regenerate the certificates. This requires importing the new CA certificate in the browser and re-authenticating all IoT devices.

Iot device certificates have a default validity of 30 days and should be renewed by the IoT device with the provisioning service before expiry.

Hub CA Certificate

The WoST Hub utilizes a self-signed CA certificate. The Hub CA is an organization certificate and not a domain certificate, intended only for use on the local network (domain is local).

A self-signed CA certificate is generated on first startup. The CA certificate/key is used to sign all generated server and client certificates. The CA certificate must be distributed to clients so they can validate the server and client certificates.

It is recommended to import the CA certificate in the browser to avoid unnecessary warnings. This certificate has a default 10 year validity period.

The idprov protocol exports the CA certificate to IoT devices when the device is provisioned. No action is needed for WoST compatible IoT devices.

Hub Server Certificate

Hub Services use a CA signed server certificate to identify themselves to clients.

A new Hub server TLS certificate is generated on startup. Hub services that offer API access use this certificate to identify themselves for incoming TLS connections. Currently, all services use the same server certificate from the application 'certs' folder.

Hub Client Certificate

Hub services and IoT devices authenticate using client certificates that are signed by the Hub CA.

Hub services use this client certificate to authenticate themselves with other Hub services, such as the directory and the Hub message bus. Currently, all services use the same client certificate which has full authorization. This client certificate is regenerated on each restart. This implies that Hub services are fully trusted.

IoT Device Client Certificate

IoT devices that register themselves with the Hub to publish 'Things' receive a client certificate upon registration. This certificate is unique to the device and signed by the CA. See also the 'idprov' service that implements the idprov protocol for issuing these certificates.

By default device certificates have a validity period of 30 days, before which they must be renewed with the idprov service.

IoT Device certificates authenticate the IoT device and authorize it to publish the Thing Description documents of the things it represents, and allow subscription to messages to update the Thing configuration and status. The certificate includes the device ID and type to identify it as an IoT Device.

Certificate Bundle Generation

This module generates the following certificate bundle and stores then in the Hub 'certs' folder.

1. The CA certificate and private key is generated on first startup, as a self-signed certificate. The CA certficate is shared with every client and server and is used to verify authenticity of all other certificates. The CA key is only used to generate the certificates listed here. Intermediary certificates are not used by WoST Hub services.
2. The hub server certificate and key are regenerated on each startup. This certificate is used by hub services such as the provisioning server (idprov), directory server (thingdir), and mosquitto message bus server. The keys of this certificate is used to generate and validate access and refresh tokens.
3. The plugin client certificate and key are regenerated on each startup. This client certificate is used by hub services to authenticate access other hub services, like for example the message bus.
4. IoT Device client certificates are generated by the IDProv provisioning server using the device provided public key. These certificates are only issued to IoT devices that publish Thing information and used by IoT devices to identify themselves.

A commandline utility can generate custom certificates for special users such as administrators. All services accept certificates signed by the CA.

Client Authentication Using Certificates

Authentication through client certificates is handled by the TLS protocol itself. A valid client certificate as generated by this service is required in order to make a connection. The certificate CN contains the user or service name, the OU is used to indicate the role in the organization:

• Hub plugins use the hub client certificate to access other Hub services. The Hub plugin certificate contains 'plugin' as the OU which is used to authorize full access.
• IoT devices have the device-ID as the CN and 'iotdevice' as the OU. IoT devices are publishers of things and have access to all Things of which they are the publisher.
• The administrator certificate has their user loginID as the CN and 'admin' as the OU.
• Other clients have their loginID as the CN and 'client' as the OU.

Properly signed certificates are accepted as valid authentication without the need of additional credentials.

Build and Installation

Build & Install (tentative)

Run 'make all' to build and 'make install' to install as a user.

See hub's README.md for more details on system installation.

Usage

... todo examples ...