Serving the Console over HTTPS

TLS Certificates

Common Name vs Subject Alternative Name

TLS certificates contain metadata, including zero to one Common Name field and zero or more Subject Alternative Name extension fields. Google Chrome 58+ and Capsule8 Sensor 4.6.0+ require the domain or IP serving the certificate to be in the certificate's list of Subject Alternative Names.

That means Capsule8 Sensor 4.6.0 and later will reject a CN-only Console certificate.

Symptoms of this issue are:

• Google Chrome 58+ failing to connect to a HTTPS Console URL with the error NET::ERR_CERT_COMMON_NAME_INVALID
• Capsule8 Sensor 4.6.0+ logs the error x509: certificate relies on legacy Common Name

Populating the Subject Alternative Names on a self-signed certificate is out of scope of this document because different users have different tools and certificate needs; we suggest searching subject alternative name <toolname> example as a starting point.

Configuring Console

If you have custom TLS certificates and would like the Console to handle SSL termination, make the certificate and key files available to the Console and specify their locations in the configuration.

console:
  #...
  https_enabled: true
  tls_cert_path: /path/to/cert
  tls_key_path: /path/to/key

Disabling TLS

Disable TLS to serve Console content over HTTP instead of HTTPS. This may be useful when initially installing the Console or when terminating SSL in a load balancer or reverse proxy.

console:
  #...
  https_enabled: false

TLS version

By default, Console 4.7.0 and later require minimum TLS version 1.2. Previous versions of Console required minimum TLS version 1.1. Users may manually configure minimum TLS versions of 1.0, 1.1, 1.2, and 1.3:

console:
  #...
  https_enabled: true
  tls_version: 1.3

HTTP Strict Transport Security (HSTS)

HSTS is a policy that enables web sites to declare themselves accessible only via secure connections and/or for users to be able to direct their user agent(s) to interact with given sites only over secure connections. The policy is declared via the Strict-Transport-Security HTTP response header field.

When your site is accessed over HTTPS with no certificate errors, the browser knows your site is HTTPS capable and will honor the Strict-Transport-Security header.

By default HSTS is disabled. Once enabled the browser should remember that the Console is only to be accessed using HTTPS for the next 2 years.

console:
  #...
  strict_transport_security_header: true

Cross Site Request Forgery (CSRF) prevention

What is it?

Cross-Site Request Forgery (CSRF) is a type of attack that occurs when a malicious web site, email, blog, instant message, or program causes a user's web browser to perform an unwanted action on a trusted site when the user is authenticated. A CSRF attack works because browser requests automatically include all cookies including session cookies. Therefore, if the user is authenticated to the site, the site cannot distinguish between legitimate requests and forged requests.

The impact of a successful CSRF attack is limited to the capabilities exposed by the vulnerable application and privileges of the user. For example, this attack could result in creating a new user or changing a password with the user's credentials. In effect, CSRF attacks are used by an attacker to make a target system perform a function via the victim's browser, without the victim's knowledge, at least until the unauthorized transaction has been committed.

How Console prevents it

In order to defend CSRF Console implements the "Double Submit Cookie" technique. In this technique, Console sends a random value in both a cookie and as a request header, with the server verifying if the cookie value and header value match. When a user access the Console a (cryptographically strong) pseudorandom value is generated and set as a cookie on the user's machine separate from the session identifier. Then the Console requires that every transaction request include a token (calculated with this  pseudorandom value) as a header. If both of them pass validation at server side, the server accepts it as legitimate request and if they don't, it would reject the request.

Because subdomains can write cookies to the parent domains and because cookies can be set for the domain over plain HTTP connections this technique works as long as you are sure that your subdomains are fully secured and only accept HTTPS connections.