Skip to main content

setuptls.py

Use setuptls.py to complete all setup steps to active TLS secure communications

This tutorial will guide you through using the setuptls.py program to create certificates and configure your server to activate TLS communications. This program can be found in the faircom/tools/certman/ directory.

This program is meant to be run on a FairCom server. If it is run from the faircom/tools/certman/ directory, it uses that installation of the FairCom server. If you wish to configure a different installation, pass that directory as the only command-line argument to this program.

This program is meant to be run on a new server, but can be run on any server with the following considerations:

  • It will change the settings of the SUBSYSTEM COMM_PROTOCOL SSL block in ctsrvr.cfg.

  • It will change the settings in the tls block of the HTTPS, MQTTS, and MQTTWSS listeners in services.json.

  • Depending on the answers provided, insecure ports/listeners may be disabled and MQTT may be configured to disallow anonymous connections.

  • Newly created certificates will be copied to the server directory under the target installation.

Note that ctsrvr.cfg and services.json are the only files changed by this program.  Prior to those changes, the original files are backed up with a prepended timestamp.

This program will create five new files after a successful run:

  • ca.key

  • ca.crt (in two locations)

  • <server name>Server.pem (in two locations)

It will not overwrite any existing key files or certificate files.

When the program asks "Do you want to also allow unencrypted connections (like HTTP and MQTT): ", if the user responds with "no" the following things will happen.

  • HTTP on port 8080 will be disabled

  • MQTT on port 1883 will be disabled

  • MQTTWS on port 9001 will be disabled

  • MQTT authentication methods will be restricted to "password" and "clientCertificate"

Walkthrough

C:\FairCom\EdgeV13\tools\certman>python setuptls.py

Welcome to FairCom's TLS Configurator
setuptls.py prompts you to create CA and server certificates if necessary.
  It then configures a FairCom server on the same computer to use those
  certificates to provide secure TLS communications.
Program started from 'C:\FairCom\EdgeV13\tools\certman'.
Configuring the installation located at 'C:\FairCom\EdgeV13'.
Using 'C:\FairCom\EdgeV13\config' as the config directory.
First you will be asked for general information.
Enter your company's name: FairCom

Enter the name of a directory where certificates will be stored
  Certificates will be stored in directories in this location.
  Ensure this directory is secure (not shared), and is backed up properly.
Directory [Certificates]:
Do you want to also allow unencrypted connections (like HTTP and MQTT): no
Enter a two-letter country code where your company is located: US
Enter a state/province where your company is located: Utah
Enter a city where your company is located: Sandy
Enter a department within your organization: IT
Enter an email address to associate with this certificate: adam.howell@faircom.com

Now you will be asked for information related to the Certificate Authority being configured.

Enter the number of years when the CA certificate will expire.
  Default expiration is 10 years.
  When a CA certificate expires, it and all certificates that use it must be
  replaced on operating systems, servers, and client software.
Years [10]:

Now you will be asked for information related to the server being configured.

Enter the number of months when the certificate will expire.
  When a certificate expires, communications using that certificate stop working.
  Recommended expiration is 13 months to give time to renew each year.
  NOTE: When a CA certificate expires, the CA certificate must be replaced
        by a new CA certificate everywhere it is used,
        including operating systems, browsers, and other software.
Months [96]:
Enter the Common Name of the server
  (this will be used as part of the filename) [AdamH-LT-2021]:
Enter a filename that contains IP addresses and DNS names,
  or press ENTER to be prompted for this information:
Enter one IP address or DNS name and press ENTER to enter another.
  Pressing ENTER on an empty line will terminate entry.
  Enter a new IP address or DNS name: adamh-lt-2021
  Enter a new IP address or DNS name: localhost
  Enter a new IP address or DNS name: 127.0.0.1
  Enter a new IP address or DNS name: ::1
  Enter a new IP address or DNS name:
Done collecting IP addresses and DNS names.

Now the server will be configured to use the certificates just created.
Server configuration complete.

Newly created files:
  C:/FairCom/EdgeV13/tools/certman/Certificates/Expires_On_2034-10-05/ca.crt
  C:/FairCom/EdgeV13/tools/certman/Certificates/_ca_key/ca.key
  C:/FairCom/EdgeV13/server/ca.crt
  C:/FairCom/EdgeV13/tools/certman/Certificates/Expires_On_2032-10-05/AdamH-LT-2021Server.pem
  C:/FairCom/EdgeV13/server/AdamH-LT-2021Server.pem
Modified files and their backup:
  C:/FairCom/EdgeV13/config/ctsrvr.cfg
    Backed up to: C:/FairCom/EdgeV13/config/2024-10-08_22-36-07-ctsrvr.cfg
  C:/FairCom/EdgeV13/config/services.json
    Backed up to: C:/FairCom/EdgeV13/config/2024-10-08_22-36-07-services.json

The CA certificate will now be imported into your OS trust store.
All configuration has been completed.

C:\FairCom\EdgeV13\tools\certman>

Note

This program can be rerun by deleting the output folder and the CertificateSettings.json file.

If the FairCom directory cannot be detected, the program will exit.

This program operates by calling three other programs: createcacert.py, createservercert.py, and importcert.py.