Use configuration files safely

We all know that storing passwords in plaintext is generally a bad practice. The Xillio Link Redirector allows you to store your configuration files encrypted.

Currently, we support files that are encrypted by the OpenSSL standard, the industry standard for implementing encryption and other security features. To use encrypted configuration, follow the following steps:

Step 1.

First create and validate your plaintext configuration file and make sure that everything is working properly in the 'unsafe' mode.

config.yml

# Information on how the Xillio Link Redirector should act and be exposed towards the outside world
license:
  key: YOUR-KEY-HERE

logger:
  type: simple            # The type of logger to use. choose from `simple`, `json`, or `void` (default: simple)
  showStackTrace: false   # Print the stack trace to stdout (default: false)
  levels:                 # List of log-levels that should be shown. (default: all levels)
    - audit               # Possible values are ['trace', 'audit', 'http', 'debug', 'info', 'warn', 'error']
    - http
    - info
    - warn
    - error

proxy:
  port: 80                # The port to use for HTTP connections (default: 80)
  requestLogging: true    # Enable logging incoming request to the console (default: false)
  requestMonitoring: true # Enable measuring request data to a metric service (default: false)

  # (Optional) Options for SSL connections.
  # If `httpsPort` is defined, the `keyFile` and `certificateFile` also need to be specified.
  httpsPort: 443                            # The port to use for HTTPS connections (default: 443)
  keyFile: ./certs/localhost.key            # The path towards your certificate key file
  certificateFile: ./certs/localhost.cert   # The path towards your certificate file
  # caFile: ./certs/rootCA.cert             # (Optional) Override the root CA to use
  forceHttps: true                          # Redirect all incoming HTTP request towards the HTTPS ports (default: false)

  # (Optional) Additional configuration
  # timeout: 10000                  # Timeout for proxied request in milli seconds (default: 10000)
  # addForwardedForHeaders: false   # Add all headers of the incoming request to the proxied request (default: false)
  # acceptUntrustedProxyTLS: false  # Allow self-signed certificates for proxied requests (default: false)
  # logProxyRequests: false         # Log the proxied requests (default: false)
  # maxUrlLength: 256               # The maximum length of the URL (default: 256)

api:
  port: 8080              # The port to use for HTTP connections (default: 8080)
  requestLogging: true    # Enable logging of incoming request to stdout (default: false)
  requestMonitoring: true # Enable measuring of request data to a metric service (default: false)

  # (Optional) Options for SSL connections.
  # If `httpsPort` is defined, the `keyFile` and `certificateFile` also need to be specified.
  httpsPort: 8443                           # The port to use for HTTPS connections (default: 8443)
  keyFile: ./certs/localhost.key            # The path to your certificate key file
  certificateFile: ./certs/localhost.cert   # The path to your certificate file
  # caFile: ./certs/rootCA.cert             # (Optional) Override the root CA to use
  forceHttps: true                          # Redirect all incoming HTTP request towards the HTTPS ports (default: false)

  # basePath: /xlr/api                        # The base path for all api endpoints (default: /xlr/api)
  # maxUrlLength: 256                         # The maximum length of the URL (default: 256)

# Configuration on the database connection
database:
  type: postgres
  url: postgresql://postgres:example@db:5432/xlr

# (Optional) Configuration for the metrics service to use for request and performance metrics
metrics:
  type: influx
  url: http://:development@metrics:8086
  organization: xillio
  performanceMonitoring: true  # Enable measuring system performance to a metric service (default: false)

To validate that everything is working properly, execute the following command (assuming the [[Start a local instance]] guide is used)

link-redirector -c config.yml

Step 2.

Now that we validated the behavior of the Xillio Link Redirector we can start encrypting our configuration. For this guide we advice to make a copy of our configuration file, so we can easily retry some of the steps in case something went wrong.

On a linux machine, we can run

openssl enc -aes-256-cbc -pbkdf2 -a -in config.yml -out config.yml

You will be prompted a password that will be used to decrypt the configuration file later on. Remember this password well or use a Password manager to store it and keep it safely within your organizations knowledge base.

Now we can open the file and see only ciphertext.

Step 3.

With our encrypted configuration we can start the application again to validate that everything is still working.

link-redirector -c config.yml -p YOUR_PASSWORD