Document opt-out behavior for #13

Author: dvershinin

.idea/dictionaries/danila.xml

@@ -32,6 +32,22 @@ In general, the module features sending security HTTP headers in a way that bett
 For instance, `Strict-Transport-Security` header should *not* be sent for plain HTTP requests.
 The module follows this recommendation.
 
+## Important note on `Strict-Transport-Security`
+
+The module adds several security headers, including `Strinct-Transport-Security`.
+Note that `preload` is sent in the value of this header, by default.
+This means Chrome may and will include your websites to its preload list of domains which are HTTPS only.
+
+It is *usually* what you want anyway, but bear in mind that in some edge cases you want to access
+a subdomain via plan unencrypted connection.
+
+If you absolutely sure that all your domains and subdomains used with the module will ever primarily operate
+on HTTPs, proceed without any extra step.
+
+If you are *not sure* if you have or will have a need to access your websites or any of its subdomains over
+plain insecure HTTP protocol, ensure `security_headers_hsts_preload off;` in your config before you ever
+start NGINX with the module to avoid having your domain preloaded by Chrome.
+
 ## Key Features
 
 *   Plug-n-Play: the default set of security headers can be enabled with `security_headers on;` in your NGINX configuration

README.md

@@ -31,6 +31,7 @@
 typedef struct {
     ngx_flag_t                 enable;
     ngx_flag_t                 hide_server_tokens;
+    ngx_flag_t                 hsts_preload;
 
     ngx_uint_t                 xss;
     ngx_uint_t                 fo;
@@ -116,6 +117,13 @@ static ngx_command_t  ngx_http_security_headers_commands[] = {
       offsetof(ngx_http_security_headers_loc_conf_t, hide_server_tokens ),
       NULL },
 
+    { ngx_string( "security_headers_hsts_preload" ),
+      NGX_HTTP_MAIN_CONF|NGX_HTTP_SRV_CONF|NGX_HTTP_LOC_CONF|NGX_CONF_FLAG,
+      ngx_conf_set_flag_slot,
+      NGX_HTTP_LOC_CONF_OFFSET,
+      offsetof(ngx_http_security_headers_loc_conf_t, hsts_preload ),
+      NULL },
+
     { ngx_string("security_headers_xss"),
       NGX_HTTP_MAIN_CONF|NGX_HTTP_SRV_CONF|NGX_HTTP_LOC_CONF|NGX_CONF_TAKE1,
       ngx_conf_set_enum_slot,
@@ -264,7 +272,11 @@ ngx_http_security_headers_filter(ngx_http_request_t *r)
     if (r->schema.len == 5 && ngx_strncmp(r->schema.data, "https", 5) == 0)
     {
         ngx_str_set(&key, "Strict-Transport-Security");
-        ngx_str_set(&val, "max-age=63072000; includeSubDomains; preload");
+        if (1 == slcf->hsts_preload) {
+            ngx_str_set(&val, "max-age=63072000; includeSubDomains");
+        } else {
+            ngx_str_set(&val, "max-age=63072000; includeSubDomains; preload");
+        }
         ngx_set_headers_out_by_search(r, &key, &val);
     }
 #endif
@@ -330,6 +342,7 @@ ngx_http_security_headers_create_loc_conf(ngx_conf_t *cf)
     conf->rp  =    NGX_CONF_UNSET_UINT;
     conf->enable = NGX_CONF_UNSET;
     conf->hide_server_tokens = NGX_CONF_UNSET_UINT;
+    conf->hsts_preload = NGX_CONF_UNSET_UINT;
 
     return conf;
 }
@@ -342,9 +355,9 @@ ngx_http_security_headers_merge_loc_conf(ngx_conf_t *cf, void *parent,
     ngx_http_security_headers_loc_conf_t *prev = parent;
     ngx_http_security_headers_loc_conf_t *conf = child;
 
-    ngx_conf_merge_value( conf->enable, prev->enable, 0 );
-    ngx_conf_merge_value(conf->hide_server_tokens,
-                         prev->hide_server_tokens, 0 );
+    ngx_conf_merge_value(conf->enable, prev->enable, 0);
+    ngx_conf_merge_value(conf->hide_server_tokens, prev->hide_server_tokens, 0);
+    ngx_conf_merge_value(conf->hsts_preload, prev->hsts_preload, 1);
 
     if (ngx_http_merge_types(cf, &conf->text_types_keys, &conf->text_types,
                              &prev->text_types_keys, &prev->text_types,