Reference14r1:Concept Let's Encrypt

From innovaphone wiki
Jump to navigation Jump to search


Certificates are automatically generated for innovaphone gateways and App Platforms.

Applies to

  • innovaphone gateways from version 14r1
  • innovaphone App Platform with version 14r1 apps (image version 110036 or higher)

How it works

  • Each configured innovaphone client requests a new certificate 30 days before it's current certificate expires.
  • Therefor an app websocket connection is opened to the Connector for Let's Encrypt App Service.
  • The client sends a certificate signing request to the Connector for Let's Encrypt App Service.
  • The Connector for Let's Encrypt App Service itself communitates via HTTPs and JWT with Let's Encrypt to request a new certificate.
  • Let's Encrypt triggers an HTTP challenge for every DNS entry where the token for the DNS entry is verified. (The Token is saved in the Let's Encrypt App Service)
  • After successfull HTTP challenges for every DNS name, the new certificate is send back to the client.
  • The certificate is installed X days before the old certificate expires, while X can be configured in the PBX Manager Plugin.

Flow without Reverse Proxy

Letsencrypt-flow.png

Flow with Reverse Proxy

Letsencrypt-flow-rp.png

Requirements

ACMEv2 compliant certification service

Our Connector for Let's Encrypt App Service uses the ACMEv2 protocol. So in general every ACMEv2 compliant service could be used.
Officially tested is Let's Encrypt itself with this URL: https://acme-v02.api.letsencrypt.org

Gateways and App Platform

  • Firmware from version 14r1 or later
  • innovaphone App Platform with App Platform Manager version 14r1 or higher and image version 110036 or higher
  • innovaphone App Connector for Let's Encrypt version 14r1 or higher
  • working DNS configuration

Reverse-Proxy

  • Port 80 must be available from WAN (external DNS should be correct for every DNS name, which gets a Let's Encrypt certificate) to the Reverse-Proxy, as the HTTP challenge uses this port to verify the token. (The ACMEv2 protocol doesn't allow another port!)
  • The Reverse-Proxy automatically forwards incoming requests to /.well-known/acme-challenge/ to the Connector for Let's Encrypt App before the local ruleset is checked. (This mechanism is already part of the firmware, so you do not need to create a custom rule on the RP) The App checks if the challenge can be verified.
    • If this is not possible, because the App doesn't know anything about this request, the Reverse-Proxy takes care about the request by its normal configured ruleset.
    • This means: if a 3rd-party device behind the Reverse-Proxy tries to generate a Let's Encrypt certificate by themselves (without the Connector for Let's Encrypt App) you have to create a rule for the Path "/.well-known/acme-challenge/" in your Reverse-proxy rules.
    • Conclusion: If you want to use the automatic forwarding you first have to configure Let's Encrypt on the Reverse-Proxy. Otherwise, devices behind Reverse-Proxy (mostly the PBX) can't obtain a certificate.
  • The App Platform must be able to communicate with the Let's Encrypt URLs.

Security Consideration

We do not recommend that a device can be reached directly from the Internet on port 80. Please use the reverse proxy variant described above.

Limitations

  • You can configure up to 100 DNS entries for a single device. More DNS entries are not supported by Let's Encrypt.
  • You cannot configure DNS entries with wildcards. Such wildcard entries require the so called DNS challenge mechanism which is not supported by our Connector for Let's Encrypt App Service.

Configuration

Connector for Let's Encrypt PBX Manager Plugin

Configure the PBX Manager Plugin of the Connector for Let's Encrypt App Service.

innovaphone Gateways

Configure the Let's Encrypt service on every gateway which shall get a Let's Encrypt certificate.

innovaphone App Platform

Configure Let's Encrypt in the settings of the App Platform Manager on every App Platform which shall get a Let's Encrypt certificate.

RP

If your gateways and/or App Platforms are behind an innovaphone reverse proxy, you must configure the Let's Encrypt service here too.
You must configure all DNS names which are used by the individual devices behind the RP.

The RP will request a certificate with multiple SAN entries while every individual device will request an own certificate with a single SAN entry (or still multiple if a single device shall have multiple DNS entries).

Devices certificate configuration

If you want to rollout the Let's Encrypt root certificates to your devices, configure the URL for Let's Encrypt root certificates in a certificates configuration (App Devices -> Domains -> your domain -> Device Configurations) which will then ensure that always the latest root certificates are available in the trust list of your devices.
You can find this URL in the PBX Manager Plugin.

Tracing and logging

Gateways

The following trace flags can be activated at Maintenance/Diagnostics/Tracing.

Let's Encrypt
communication between gateway and the Connector for Let's Encrypt App Service
processing of incoming id_tokens
HTTP Client
the HTTPS communication with the Connector for Let's Encrypt App Service

App Platform

Enable these trace flags for diagnostics:

App Platform Manager

App
requests of new certificates
AppWebsocket
communication with the Connector for Let's Encrypt App Service
Websocket Client
communication with the Connector for Let's Encrypt App Service

Connector for Let's Encrypt App Service

App
app logs
HttpClient
communication with Let's Encrypt itself
AppWebsocket
communication with the clients

Alarms and Events

  • an event is generated for every failed certificate creation by the Connector for Let's Encrypt App Service
  • an alarm is generated on the corresponding device as long as the certificate creation fails

Troubleshooting

Not working TLS connection between a reverse proxy/gateway and the app platform with the Connector for Let's Encrypt

If a gateway/reverse proxy cannot establish a TLS connection to the app platform where the Connector for Let's Encrypt is running, no new certificate can be created anymore.

As a workaround, you can temporarily switch to a non TLS connection under Services -> Let's Encrypt Let's Encrypt App URL by using ws instead of wss.
If all your systems have a valid TLS certificate again, don't forget to switch back to wss!

Known Issue

Geoblocking can prevent confirmation

To verify the correctness of DNS entries and HTTP Challenge, Let's Encrypt sends DNS/HTTP requests from multiple locations around the world. All of these requests must be successfully answered. If a request is not answered due to geoblocking, Let's Encrypt does not trust the issuer.

Related Articles