DOC-9245: Configure HSTS

modules/ROOT/nav.adoc

@@ -720,6 +720,8 @@ include::cli:partial$cbcli/nav.adoc[]
    **** xref:rest-api:rest-authorization.adoc[Authorization API]
     ***** xref:rest-api:rbac.adoc[Role-Based Access Control (RBAC)]
    **** xref:rest-api:rest-setting-security.adoc[Configure On-the-Wire Security]
+   **** xref:rest-api:rest-setting-hsts.adoc[Configure HSTS]
+   **** xref:rest-api:rest-setting-security.adoc[Manage Encryption Settings]
    **** xref:rest-api:rest-secret-mgmt.adoc[Secret Management API]
 * xref:xdcr-reference:xdcr-reference-intro.adoc[XDCR Reference]
  ** xref:xdcr-reference:xdcr-advanced-settings.adoc[Advanced Settings]

modules/learn/pages/security/on-the-wire-security.adoc

@@ -32,6 +32,8 @@ This includes establishing the server's minimum TLS version; determining whether
 These values can be configured either _globally_ (for the whole cluster), or on a _per service_ basis.
 Details are provided immediately below.
 
+* _Setting 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. 
+
 [#tls-and-cipher-suites]
 == TLS and Cipher-Suites
 
@@ -136,6 +138,11 @@ For information, see https://tools.ietf.org/html/rfc7540#section-9.2.2[Section 9
 
 Also, for information on cipher-suites prohibited by HTTP/2, see https://tools.ietf.org/html/rfc7540#appendix-A[Appendix A^] of the same document.
 
+== Establishing an HTTP Secure Transport Header
+
+Setting an HTTP Secure Transport Header (HSTS) informs 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.
+
 == Configuring On-the-Wire Security-Parameters
 
 The parameters provided by Couchbase Server for on-the-wire security can be configured by means of either the CLI or the REST API.

modules/manage/pages/manage-security/manage-tls.adoc

@@ -15,6 +15,8 @@ The interfaces provided by Couchbase Server for configuring on-the-wire security
 
 * Configuring TLS and Cipher-Suites.
 
+* Setting an _HTTP Secure Transport Header_ (HSTS).
+
 * Enforcing TLS across the cluster.
 
 These areas are described in detail in xref:learn:security/on-the-wire-security.adoc[On-the-Wire Security], which should be read before the examples provided below are attempted.
@@ -42,7 +44,7 @@ The argument must be a list of cipher suites, each of which appears as a member
 +
 Note that Couchbase Server only accepts _IETF RFC_ names, for cipher-suites: _OpenSSL_ names cannot be used.
 
-A further four, on-the-wire security settings are provided for global configuration only — thus, these _cannot_ be set per service:
+Additional on-the-wire security settings are provided for global configuration only — thus, these _cannot_ be set per service:
 
 * `disableUIOverHttp`.
 Whether access to Couchbase Web Console should be disabled over http.
@@ -71,6 +73,16 @@ Note, however, that after `strict` has been specified, communication that occurs
 Applying `strict` as the `clusterEncryptionLevel` has a number of significant consequences, which should be fully understood before proceeding.
 See xref:rest-api:rest-setting-security.adoc#enforcing-tls[Enforcing TLS].
 
+* `Strict-Transport-Security`.
+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. 
+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.
+
 [#manage-on-the-wire-security-with-the-cli]
 == Manage On-the-Wire Security, with the CLI
 
@@ -251,6 +263,7 @@ For information, see xref:learn:security/on-the-wire-security.adoc#establishing-
 
 As described above, the CLI can also be used to establish global settings for
 `disableUIOverHttp`, `disableUIOverHttps`, `disableWWWAuthenticate`, and `clusterEncryptionLevel`.
+It can also be used to establish HSTS; by means of the `hsts-max-age`, `hsts-preload-enabled`, and `hsts-include-sub-domains-enabled` parameters.
 For information, see the reference page for the xref:cli:cbcli/couchbase-cli-setting-security.adoc[setting-security] command.
 
 [#manage-on-the-wire-security-with-the-rest-api]
@@ -311,10 +324,12 @@ If successful, the call gives `200 OK`, and returns an empty array.
 [#establish-other-global-settings-with-the-rest-api]
 === Establish Other Global Settings, with the REST API
 
-As described above, the REST API can also be used to establish global settings for
+As described above, the REST API, using the `/settings/security` URI, can also be used to establish global settings for
 `disableUIOverHttp`, `disableUIOverHttps`, `disableWWWAuthenticate`, and `clusterEncryptionLevel`.
 For information, see xref:rest-api:rest-setting-security.adoc[Configure On-the-Wire Security].
 
+For information on setting an HTTP Secure Transport Header with the REST API, see xref:rest-api:rest-setting-hsts.adoc[Configure HSTS].
+
 [#configure-on-the-wire-security-per-service-with-the-rest-api]
 === Configure On-the-Wire Security Per Service, with the REST API
 
@@ -364,6 +379,6 @@ The current `cipherSuites` list for the service is thus shown to have been appro
 
 == See Also
 
-For more information on the REST API, see xref:rest-api:rest-setting-security.adoc[Configure On-the-Wire Security].
+For more information on the REST API, see xref:rest-api:rest-setting-security.adoc[Configure On-the-Wire Security] and xref:rest-api:rest-setting-hsts.adoc[Configure HSTS].
 For more information on the CLI, see the reference page for the xref:cli:cbcli/couchbase-cli-setting-security.adoc[setting-security] command.
 A conceptual overview of on-the-wire security is provided in xref:learn:security/on-the-wire-security.adoc[On-the-Wire Security].

modules/rest-api/pages/rest-setting-hsts.adoc

@@ -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].

modules/rest-api/pages/rest-setting-security.adoc

@@ -5,7 +5,7 @@
 [abstract]
 {description}
 
-== HTTP method and URI
+== HTTP Method and URI
 
 ----
 GET /settings/security/[service-name]
@@ -20,6 +20,8 @@ This includes the encryption _level_, for node-to-node encryption within the clu
 UI disablement over insecure connections; TLS minimum version; and a list of accepted cipher suites.
 Additionally, secure communication by means of TLS can be _enforced_ across the cluster.
 
+Note that information on setting an HTTP Secure Transport Header with the REST API is provided in xref:rest-api:rest-setting-hsts.adoc[Configure HSTS].
+
 [#curl-syntax]
 == Curl Syntax
 
@@ -279,4 +281,6 @@ The returned output shows that the new settings have been successfully establish
 
 For more information on managing on-the-wire security-settings with the CLI, see the reference page for the xref:cli:cbcli/couchbase-cli-setting-security.adoc[setting-security] command.
 
+Information on setting an HTTP Secure Transport Header with the REST API is provided in xref:rest-api:rest-setting-hsts.adoc[Configure HSTS].
+
 A conceptual overview of on-the-wire security is provided in xref:learn:security/on-the-wire-security.adoc[On-the-Wire Security].