Configure HSTS

reference

Establish an HTTP Secure Transport Header (HSTS); so as to inform the Web-Console browser never to load a site using HTTP; and instead, to automatically convert all access-requests from HTTP to HTTPS.

HTTP Method and URI

GET /settings/security/responseHeaders

POST /settings/security/responseHeaders

DELETE /settings/security/responseHeaders

Description

Establishes an HTTP Secure Transport Header (HSTS); so as to inform the Web-Console browser never to load a site using HTTP; and instead, to automatically convert all access-requests from HTTP to HTTPS. Only the Strict-Transport-Security header is supported.

Three sub-settings must be established, which are:

The duration of HTTPS-enforcement for this browser.
Whether the site’s subdomains are to be covered by the setting.
Whether the preload directive should be set; so that the policy is enforced before any communication takes place.

Curl Syntax

curl -X GET -u <administrator>:<password>
  http://<ip-address-or-domain-name>:8091/settings/security/responseHeaders

curl -X POST -u <administrator>:<password>
  http://<ip-address-or-domain-name>:8091/settings/security/responseHeaders
  -d <transport-security-specification>

  curl -X DELETE -u <administrator>:<password>
    http://<ip-address-or-domain-name>:8091/settings/security/responseHeaders

The transport-security-specification specified with POST must be JSON object that takes the following form:

{
  Strict-Transport-Security: max-age=<integer>;[includeSubDomains];[preload]
}

The value specified for the Strict-Transport-Security key is a valid HSTS header, which will be used by the browser. The integer specified for max-age determines the number of seconds for which HTTPS is mandated for this browser. The optional includeSubDomains keyword, if specified, determines that all the subdomains for this site are to be covered by the specification. The optional preload keyword, if specified, determines that the specification is to be preloaded, to ensure that it becomes active even before any subsequent communication is attempted.

Responses

The GET method, if successful, gives 200 OK. If a setting has been made, an object containing the valid header is returned. If no setting has been made, an empty array is returned.

The POST method, if successful, gives 200 OK, and returns an empty array.

The DELETE method, if successful, also gives 200 OK, and returns an empty array.

For both methods, an incorrect URI gives 404 Object Not Found, with a Not found error message. Use of improper credentials gives 401 Unauthorized. An improper port number returns an error message such as Failed to connect to localhost port 8094: Connection refused.

For the POST method, incorrectly specified parameters fail with 400 Bad Request, and return an object such as the following: {"errors":["responseHeaders - Invalid format. Expecting a json."]}.

Examples

The methods and the URI can be used as shown below.

Establish HSTS

The following call establishes a Strict-Transport-Security heading for the browser:

curl -v -X POST localhost:8091/settings/security/responseHeaders \
-u Administrator:password \
-d '{"Strict-Transport-Security":"max-age=31536000;includeSubDomains;preload"}'

This establishes that only HTTPS connections are accepted by this browser, and that this covers all subdomains for this site: it also specifies that this security constraint should be preloaded, so that it will be enforced even before any subsequent connection is attempted. The integer that is the value of max-age specifies the number of seconds during which the constraint should be maintained: this constitutes one year.

The following, alternative call establishes a different header:

curl -v -X POST localhost:8091/settings/security/responseHeaders \
-u Administrator:password \
-d '{"Strict-Transport-Security":"max-age=31536000"}'

This again specifies that only HTTPS connections are accepted for the next year. However, the setting does not cover subdomains, and will not be preloaded.

Get the Current HSTS Setting

The following call returns the current HSTS setting, if one has indeed been established:

curl -v -GET localhost:8091/settings/security/responseHeaders \
-u Administrator:password

If no setting has been established, an empty array is returned. Otherwise, an object containing the setting is returned. For example:

{"Strict-Transport-Security":"max-age=31536000"}

Delete the Current HSTS Setting

The following call deletes the current HSTS setting, if one exists.

curl -v -X DELETE localhost:8091/settings/security/responseHeaders \
-u Administrator:password

The call always returns an empty array.