Secure

Secure is an HTTP middleware from Hertz that checks HTTP requests to quickly secure access requests. Secure middleware provides not only a default base configuration, but also a wide range of custom configuration options.

The implementation of the secure extension refers to the implementation of gin-contrib/secure.

Install

Download and install

go get github.com/hertz-contrib/secure

Import in your code

import "github.com/hertz-contrib/secure"

Example

package main

import (
    "context"
    
    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/hertz-contrib/secure"
)

func main() {
    h := server.Default()
    // use default config
    h.Use(secure.New())
    h.GET("/ping", func(ctx context.Context, c *app.RequestContext) {
        c.String(200, "pong")
    })
    h.Spin()
}

Config

Instructions

Most of the Secure configuration items are designed to simplify the user’s configuration of HTTP response headers, if you are confused about how to use HTTP headers, you can check it yourself in MDN Docs

New

Secure provides the New() function for integrating Secure into Hertz, which is configured by default as follows

ConfigurationDescriptionDefault Value
WithSSLRedirectIf WithSSLRedirect is set to true, only https requests will be allowedtrue
WithIsDevelopmentIf WithIsDevelopment is set to true, the entire security policy of the middleware application will be completely disabledfalse
WithSTSSecondWithSTSSecond is used to set the number of seconds for the max-age of Strict-Transport-Security315360000
WithFrameDenyWithFrameDeny is used to set the value in X-Frame-Options, true sets the value to DENYtrue
WithContentTypeNosniffIf WithContentTypeNosniff is set to true,
then add the nosniff value to the X-Content-Type-Options
true
WithBrowserXssFilterIf WithBrowserXssFilter is set to true,
then add the value 1; mode=block to the X-XSS-Protection header
true
WithContentSecurityPolicyWithContentSecurityPolicy is used to configure policies in Content-Security-Policy“default-src ‘self’”
WithIENoOpenWithIENoOpen is used to prevent Internet Explorer from executing download tasks in the website, the default setting is true, that is, to prevent downloadingtrue
WIthSSLProxyHeadersWIthSSLProxyHeaders is used to set the request headers map. If the request is insecure, the information in the request header is matched against the information in the request headers map. If it matches the corresponding value, the request is considered securemap[string]string{
“X-Forwarded-Proto”: “https”
}

Of course, in addition to these default configuration items, we have other configuration items that will be introduced later

WithAllowHosts

WithAllowHosts is used to set a whitelist of fully qualified domains that are allowed to be accessed, which defaults to an empty list by default, allowing any and all host names

Function signature:

func WithAllowedHosts(ss []string) Option

WithSSLTemporaryRedirect

When WithSSLTemporaryRedirect is set to true, a 302 status code (StatusFound) will be used on redirects. Otherwise, 301 (StatusMovedPermanently) is used

Function signature:

func WithSSLTemporaryRedirect(b bool) Option

WithSSLHost

WithSSLHost is used to set the host name to redirect http requests to https, default is "" which means use the same host name

Function signature:

func WithSSLHost(s string) Option

WithSTSIncludeSubdomains

WhenWithSTSIncludeSubdomains is set to true, will be appended to the Strict-Transport-Security header. Default is false.

Function signature:

func WithSTSIncludeSubdomains(b bool) Option

WithCustomFrameOptionsValue

Use WithCustomFrame-OptionsValue to fill in custom values in X-Frame-Options

Note: This setting will override the WithFrameDeny setting mentioned above

Function signature:

func WithCustomFrame-OptionsValue(s string) Option

WithReferrerPolicy

WithReferrerPolicy is used to set the policy in the Referrer-Policy, which regulates the access source information that should be included in the generated request

Function signature:

func WithReferrerPolicy(s string) Option

WithBadHostHandler

WithBadHostHandler is used to set the logic to handle the request when an error occurs, default return 403 (StatusForbidden) status code

Function signature:

func WithBadHostHandler(handler app.HandlerFunc) Option

Example:

package main

import (
	"context"
	"net/http"

	"github.com/cloudwego/hertz/pkg/app"
	"github.com/cloudwego/hertz/pkg/app/server"
    "github.com/cloudwego/hertz/pkg/common/utils"
    
    "github.com/hertz-contrib/secure"
)

func main() {
	h := server.New(server.WithHostPorts("127.0.0.1:8080"))
	h.Use(secure.New(
		secure.WithAllowedHosts([]string{"example.com"}),
		secure.WithSSLHost("example.com"),
		secure.WithBadHostHandler(func(ctx context.Context, c *app.RequestContext) {
			c.AbortWithStatusJSON(http.StatusForbidden, utils.H{
				"message": "this is a custom Bad Host Handler!",
			})
		}),
	))
	h.GET("/ping", func(ctx context.Context, c *app.RequestContext) {
		c.String(200, "pong")
	})
	h.Spin()
}

WithFeaturePolicy

WithFeaturePolicy is used to set the policy of Feature-Policy

Function signature:

func WithFeaturePolicy(s string) Option

WithDontRedirectIPV4Hostnames

When WithDontRedirectIPV4Hostnames is set to true, then requests for hostnames with IPV4 addresses will not be redirected. This is configured so that a health check like Loadbalancer’s setup succeeds.

Function signature:

func WithDontRedirectIPV4Hostnames(b bool) Option

Last modified December 2, 2022 : chore: add lark footer link (#460) (f41a884)