feat: Integration with Cumulocity CA

[didier-wenzek]

A planned PKI feature of Cumulocity IoT will allow a tenant to act as a Certificate Authority (CA) for its fleet of connected devices. Once enabled, this feature:

• let the devices request their own certificate directly from their tenant
• the legitimacy of these certificate requests being controlled with security tokens
• which have been pre-registered on the tenant by an administrator during a registration step.

To leverage this feature, thin-edge must be extended along the following lines.

Device Registration

Security tokens are used to prove the legitimacy of certificate requests issued by the devices.

• The tenant and the device must agree on a device common name (CN) and an associated security token.
• A tenant administrator has to register this (CN, token) pair on the tenant and to give the same pair to the device.
• Then the device can request for a certificate for that CN using the token for authentication.

Technically, thin-edge could provide a command combining these steps. However,

• this might be confusing as this combines two different levels of authentication, for the device and for the tenant user
• this is not flexible as this imposes a workflow where all the registration data are coming from the device.

Hence:

• Thin-edge will only provide a command to request a certificate, being given a device id and a security token.
• Users will have to implement their own workflow to generate device identifiers and tokens, to pre-register the devices on their tenant, and finally to trigger on the thin-edge device the certificate creation.
• To support users implementing their own workflow, c8y-tedge will be extended with a sub-command to register a device (CN, token) pair and trigger the certificate request on behalf of the device.

Certificate Creation

A new tedge cert download c8y cli sub-command is introduced, designed along similar lines as for tedge cert upload c8y.

$ tedge cert download c8y --help
Request and download the device certificate from Cumulocity

- generate a private key and Signing Certificate Request (CSR) for the device
- upload this CSR on Cumulocity, using the provided device identifier and security token
- loop till the device is registered by an administrator and the CSR accepted 
- store the certificate created by Cumulocity

Usage: tedge cert download c8y [OPTIONS] --device-id <ID> --token <TOKEN>

Options:
      --device-id <ID>

          The device identifier to be used as the common name for the certificate

      --token <TOKEN>

          The security token assigned to this device when registered to Cumulocity

      --config-dir <CONFIG_DIR>

          Use the following settings from the config:

          - c8y.http  HTTP Endpoint for the Cumulocity tenant, with optional port.
          - device.key_path  Path where the device's private key is stored.
          - device.cert_path  Path where the device's certificate is stored.
          - device.csr_path  Path where the device's certificate signing request is stored. 

          [env: TEDGE_CONFIG_DIR, default: /etc/tedge]

  -h, --help
          Print help (see a summary with '-h')

Certificate Renewal

As long as a device is actually connected to Cumulocity with a valid certificate, the device can renew its certificate using the tedge cert renew c8y command.

$ tedge cert renew c8y --help
Renew the device certificate from Cumulocity

- keep the device identifier (CN) unchanged
- keep the current private key unchanged
- generate a new Signing Certificate Request (CSR) for the device
- upload this CSR on Cumulocity, using JWT to authenticate
- store the updated certificate without erasing the current certificate

Usage: tedge cert renew c8y [OPTIONS]

Options:
      --config-dir <CONFIG_DIR>

          Use the following settings from the config:

          - c8y.http  HTTP Endpoint for the Cumulocity tenant, with optional port.
          - device.key_path  Path where the device's private key is stored.
          - device.cert_path  Path where the device's certificate is stored.
          - device.csr_path  Path where the device's certificate signing request is stored. 

          [env: TEDGE_CONFIG_DIR, default: /etc/tedge]

  -h, --help
          Print help (see a summary with '-h')

Note that a certificate renewal should not erase the current certificate that is still in use.

Several points need to be clarified:

• Should the bridge be restarted when a new certificate is available?
• Should tedge reconnect c8y be triggered?
• How to organize certificate swapping between new and current?
• What if the connection fails with the new certificate?
• Can the mapper itself trigger a certificate renewal?

Some helpers have to be added:

• The tedge cert show command will be extended with an --expire-in to display the number of days after which the certificate will expire.
• The tedge config has to be extended with:
  • a path for the certificate backup,
  • a requested valid duration for the certificates,
  • a trigger for certificate renewal,

[reubenmiller]

Looks good. It isn't explicitly mentioned in the example, but it would be good to support setting the the cli's flags (e.g. --device-id and --token) from environment variables as well (useful for automating the container use-case)