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"}
See Also
For more information on managing on-the-wire security-settings with the REST API, see Configure On-the-Wire Security.
A conceptual overview of on-the-wire security is provided in On-the-Wire Security.