LetsEncrypt

About the "LetsEncrypt" sample

The "LetsEncrypt" sample is a server extension that generates a TLS certificate for the hmi server with Let's Encrypt.

Let's Encrypt

Let's Encrypt provides an API to generate TLS certificates for a given domain. The client has to complete a challenge on the device, on which the HMI-Server runs, to ensure the control over it. The certificate can be generated with two different APIs. To test Let's Encrypt and the server extension it's possible to use the Staging Environment (https://letsencrypt.org/docs/staging-environment/).

Requirements

The HMI server must be reachable about a public domain and the endpoints http://0.0.0.0:80 and https://0.0.0.0:443 must be configured.

Example requests

1. Add the public domain of the device you want to generate a certificate for.

   Request:

   {
       "requestType": "ReadWrite",
       "commands": [
           {
               "symbol": "LetsEncrypt.Config::data::domain",
               "writeValue": "example.com"
           }
       ]
   }

   Response:

   {
       "requestType": "ReadWrite",
       "commands": [
           {
               "symbol": "LetsEncrypt.Config::data::domain",
               "readValue": "example.com"
           }
       ]
   }

2. Add email address to Let's Encrypt to get notified if certificate expires.

   Request:

   {
       "requestType": "ReadWrite",
       "commands": [
           {
               "symbol": "LetsEncrypt.Config::data::contacts",
               "writeValue": [
                   "[email protected]"
               ]
           }
       ]
   }

   Response:

   {
       "requestType": "ReadWrite",
       "commands": [
           {
               "symbol": "LetsEncrypt.Config::data::contacts",
               "readValue": [
                   "[email protected]"
               ]
           }
       ]
   }

3. Set staging environment as current api.

   Request:

   {
       "requestType": "ReadWrite",
       "commands": [
           {
               "symbol": "LetsEncrypt.Config::data::api",
               "writeValue": 1
           }
       ]
   }

   Response:

   {
       "requestType": "ReadWrite",
       "commands": [
           {
               "symbol": "LetsEncrypt.Config::data::api",
               "readValue": 1
           }
       ]
   }

4. Set acme-v02 as current api.

   Request:

   {
       "requestType": "ReadWrite",
       "commands": [
           {
               "symbol": "LetsEncrypt.Config::data::api",
               "writeValue": 0
           }
       ]
   }

   Response:

   {
       "requestType": "ReadWrite",
       "commands": [
           {
               "symbol": "LetsEncrypt.Config::data::api",
               "readValue": 0
           }
       ]
   }

5. Set certificate information.

   Request:

   {
       "requestType": "ReadWrite",
       "commands": [
           {
               "symbol": "LetsEncrypt.Config::data::certificateInformation",
               "writeValue": {
                   "countryName": "country",
                   "state": "state",
                   "locality": "locality",
                   "organization": "organization",
                   "organizationUnit": "organizationUnit"
               }
           }
       ]
   }

   Response:

   {
       "requestType": "ReadWrite",
       "commands": [
           {
               "symbol": "LetsEncrypt.Config::data::certificateInformation",
               "readValue": {
                   "countryName": "country",
                   "state": "state",
                   "locality": "locality",
                   "organization": "organization",
                   "organizationUnit": "organizationUnit"
               }
           }
       ]
   }

6. Start certificate generation.

   Request:

   {
       "requestType": "ReadWrite",
       "commands": [
           {
               "symbol": "LetsEncrypt.Config::generateCertificate",
               "writeValue": true
           }
       ]
   }

   Response:

   {
       "requestType": "ReadWrite",
       "commands": [
           {
               "symbol": "LetsEncrypt.Config::generateCertificate",
               "readValue": true
           }
       ]
   }

7. Define interval of certificate generation.

   Request:

   {
       "requestType": "ReadWrite",
       "commands": [
           {
               "symbol": "LetsEncrypt.Config::interval",
               "writeValue": "P30D"
           }
       ]
   }

   Response:

   {
       "requestType": "ReadWrite",
       "commands": [
           {
               "symbol": "LetsEncrypt.Config::interval",
               "readValue": "P30D"
           }
       ]
   }

8. Define interval of certificate generation if staging environment is used.

   Request:

   {
       "requestType": "ReadWrite",
       "commands": [
           {
               "symbol": "LetsEncrypt.Config::intervalStaging",
               "writeValue": "P30D"
           }
       ]
   }

   Response:

   {
       "requestType": "ReadWrite",
       "commands": [
           {
               "symbol": "LetsEncrypt.Config::intervalStaging",
               "readValue": "P30D"
           }
       ]
   }

State information returned by LetsEncrypt extension

1. Example response of LetsEncrypt.Diagnostics

   {
       "symbol": "LetsEncrypt.Diagnostics",
       "readValue": {
           "currentCertificate": {
               "valid": true,
               "validTo": "2022-06-11T16:24:42Z",
               "validFrom": "2022-03-13T16:24:43Z"
           },
           "nextCertificateGeneration": "2022-03-15T16:24:43Z"
       }
   }