-
Notifications
You must be signed in to change notification settings - Fork 178
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
13933a7
commit 37bd5fe
Showing
5 changed files
with
171 additions
and
4 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,139 @@ | ||
= Configure HSTS | ||
:description: 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. | ||
:page-topic-type: reference | ||
|
||
[abstract] | ||
{description} | ||
|
||
== 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 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] | ||
== 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. | ||
|
||
=== See Also | ||
|
||
[#see-also] | ||
== See Also | ||
|
||
For more information on managing on-the-wire security-settings with the REST API, see xref:rest-api/rest-setting-security.adoc[Configure On-the-Wire Security]. | ||
|
||
A conceptual overview of on-the-wire security is provided in xref:learn:security/on-the-wire-security.adoc[On-the-Wire Security]. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters