HTTPS Certificate

An HTTPS certificate is required to access the Web API and its built-in API documentation.

A self-signed certificate is automatically installed and used during installation (computer certificates). Alternatively, a Let’s Encrypt certificate can be used.

Use of Let’s Encrypt (ACME Protocol)

Let’s Encrypt allows you to manage certificates for a specified domain. Existing certificates are kept up to date by checking the expiration date and a new certificate is installed if none exists.

How to use Let’s Encrypt:

Install the Web API.
Configure your network (see Network Configuration).
Edit the Let's Encrypt section in the appsettings.json file (see Let’s Encrypt Configuration).
Restart the service.
Make sure the Let’s Encrypt certificate is installed.
Add the new certificate to be used to the appsettings.json file (see Use a Certificate).
Restart the service.
Access the Swagger website via the new domain name to make sure the certificate is used (see HTTPS REST API).

Network Configuration

To create and manage a TLS certificate for a domain, you must configure your network correctly. The IPv4 listener of the Let’s Encrypt module responds to port 13020. The service performs an HTTP-01 challenge to validate the certificate request.

The HTTP-01 challenge can only be performed on port 80. You must therefore configure port forwarding on your internet router / firewall from port 80 to the internal port 13020 of the Web API server.

The server must open port 13020 for this communication.

Let’s Encrypt Configuration

To activate the Let’s Encrypt module, you must configure the appsettings.json file.

Configure the LetsEncrypt section and set the active parameter to true. An example can look like this:

Copy

"LetsEncrypt": {
    "active": true,
    "staging": false,
    "user": "anybody.surname@company.com",
    "domain": "sample.dns.net",
    "chronSchedule": "0 0 * * * ?",
    "renewbeforeexpireddays": 30
  },

You can configure the following parameters in the LetsEncrypt section of the appsettings.json:

Setting	Description
active	To activate the Let’s Encrypt module (ACME module), set this parameter to `true`. To use the generated certificate, change the subject of `HttpsInlineCertStore` to the domain name after the certificate has been successfully generated.
staging	Let’s Encrypt provides a staging environment for testing purposes. If you set this parameter to `true`, the service communicates with this staging environment. Do not use this parameter to generate certificates. If you use the staging environment, an invalid certificate will be created but not installed. To request a valid certificate, set the parameter to `false`. Note that the number of certificates for a domain name is limited by Let’s Encrypt.
user	The e-mail address of the user requesting a certificate. The module either creates a new account or automatically uses the existing one. The e-mail address is used by the Let’s Encrypt service. For further information, see: https://letsencrypt.org/docs/expiration-emails/
domain	The certificate managed by the service is issued for the specified domain. It is also the subject of the certificate when it is installed and is used to identify the certificates in the update routine of the module.
chronSchedule	The service checks the validity of the certificate periodically. The `chronSchedule` parameter defines the time period in which the checks are performed. By default, a check is performed hourly. When the service is started, the certificate is checked once and created or updated if necessary.
renewbeforeexpireddays	The `renewbeforeexpireddays` parameter determines how many days before expiration the certificate is automatically renewed.

Use the staging environment of Let’s Encrypt to ensure that all other settings and the network configuration is correct. After that, you can safely deactivate the staging environment. For more information on using Let’s Encrypt, see the Web API log files (see Service Log Files).

Use a Certificate

To select a certificate, configure the HttpsInlineCertStore section in the appsettings.json file. The service loads the certificate once on its starts. To use the certificate, set the Subject parameter to the subject of the certificate. The default setting is to load the self-signed certificate.

First generate a certificate with Let’s Encrypt and then adjust the Subject for HttpsInlineCertStore. As long as no certificate is found, the Web API service will not start.

The Let’s Encrypt module creates a certificate for the domain name of your system. This domain is also the subject of the generated certificate.

Make sure that the Url parameter is not configured for a specific domain. Use https://*:13333 or https://0.0.0.0:13333 (port 13333 can be changed to any other port) to listen to any domain of the server. The service is accessible locally with localhost (127.0.0.1) or externally via the configured domain name.

Copy

 "HttpsInlineCertStore": {
    "Url": "https://*:13333",
    "Certificate": {
      "Subject": "sample.dns.net",
      "Store": "My",
      "Location": "LocalMachine"
    }
  },

Further Information

Local Port Forwarding

If you need a local port forwarding on the system on which the Web API is installed, use the following cmd command:

Copy

netsh interface portproxy add v4tov4 listenport=80 listenaddress=0.0.0.0 connectport=13020 connectaddress=127.0.0.1

DynDNS

You can use a DynDNS service to get a domain name for your dial-up connections. Most routers support multiple DnyDNS services. DuckDNS.org, for example, is a free and easy-to-use service that you can use for this.

Fritz Box Users

If you activate the MyFritz function of your Fritz!Box, the Fritz!Box has a built-in domain name. This gives you a domain name for your dial-up connection such as: 1234abcd.myfritz.net.

To be able to use this domain name, you must deactivate IPv6 in the internet connection. Otherwise, the port forwarding from port 80 to IPv4 will not work and will always redirect you to the login page of the Fritz Box.

Why Are HTTPS Certificates Important?

Creating an SSL certificate for an HTTPS connection helps ensure the security and privacy of your content and complies with the cyber security standards.

Complete Encryption of the Transmitted Data

An HTTPS connection with SSL certificate provides an additional level of security for your G-Core system and for the operator. The SSL certificate completely encrypts the data transmitted via the internet to protect sensitive information from interception and manipulation by third parties.

Secure Connection in Web Browsers

HTTPS connections are identified as insecure in almost all web browsers. The Firefox web browser even offers the extended security function "HTTPS-Only Mode". In future, HTTP connections will tend to no longer be permitted or access will become very difficult.

Personal Responsibility and Control of Your Content

By generating your own SSL certificates, you retain personal responsibility and control of your content. This ensure that your content is transmitted securely and according to your specific requirements.