secure

README

Secure (This is a community driven project)

Secure middleware for hertz framework.

This repo is forked from secure and adapted for hertz.

Install

go get github.com/hertz-contrib/secure

Custom example

User passed in custom configuration items

Function Signature

func New(opts ...Option) app.HandlerFunc

Sample Code

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(
		server.WithHostPorts("127.0.0.1:8080"),
	)
	h.Use(secure.New(
		secure.WithAllowedHosts([]string{"example.com", "ssl.example.com"}),
		secure.WithSSLHost("ssl.example.com"),
	))

	h.GET("/ping", func(c context.Context, ctx *app.RequestContext) {
		ctx.String(200, "pong")
	})
	h.Spin()
}

Default Configuration

    config:
	options{
	    sslRedirect:           true,
	    isDevelopment:         false,
	    stsSeconds:            315360000,
	    frameDeny:             true,
	    contentTypeNosniff:    true,
	    browserXssFilter:      true,
	    contentSecurityPolicy: "default-src 'self'",
	    ieNoOpen:              true,
	    sslProxyHeaders:       map[string]string{"X-Forwarded-Proto": "https"},
       },

Option

options	Parameters	value	Description
WithSSLRedirect	bool	true	If WithSSLRedirect is set to true, then only allow https requests
WithIsDevelopment	bool	false	When true, the whole security policy applied by the middleware is disabled completely.
WithSTSSecond	int64	315360000	Default is 315360000, which would NOT include the header.
WithSTSIncludeSubdomains	bool	false	If WithSTSIncludeSubdomains is set to true, the includeSubdomains will be appended to the Strict-Transport-Security header. Default is false.
WithFrameDeny	bool	false	If WithFrameDeny is set to true, adds the X-Frame-Options header with the value of DENY. Default is false
WithContentTypeNosniff	bool	false	If WithContentTypeNosniff is true, adds the X-Content-Type-Options header with the value nosniff. Default is false.
WithBrowserXssFilter	bool	false	If WithBrowserXssFilter is true, adds the X-XSS-Protection header with the value 1; mode=block. Default is false.
WithContentSecurityPolicy	[]string	""	WithContentSecurityPolicy allows the Content-Security-Policy header value to be set with a custom value. Default is "".
WithIENoOpen	bool	false	Prevent Internet Explorer from executing downloads in your site’s context
WithSSLProxyHeaders	map[string]string	"X-Forwarded-Proto": "https"	This is useful when your app is running behind a secure proxy that forwards requests to your app over http (such as on Heroku).
WithAllowedHosts	[]string	nil	WithAllowedHosts is a list of fully qualified domain names that are allowed.Default is empty list, which allows any and all host names.
WithSSLTemporaryRedirect	bool	false	If WithSSLTemporaryRedirect is true, the a 302 will be used while redirecting. Default is false (301).
WithSSLHost	string	""	WithSSLHost is the host name that is used to redirect http requests to https. Default is "", which indicates to use the same host.
WithCustomFrameOptionsValue	string	nil	WithCustomFrameOptionsValue allows the X-Frame-Options header value to be set with a custom value. This overrides the FrameDeny option.
WithReferrerPolicy	string	nil	HTTP header "Referrer-Policy" governs which referrer information, sent in the Referrer header, should be included with requests made.
WithBadHostHandler	app.HandlerFunc	nil	Handlers for when an error occurs (ie bad host).
WithFeaturePolicy	string	nil	Feature Policy is a new header that allows a site to control which features and APIs can be used in the browser.
WithDontRedirectIPV4Hostnames	bool	false	If WithDontRedirectIPV4Hostnames is true, requests to hostnames that are IPV4 addresses aren't redirected. This is to allow load balancer health checks to succeed.

License

This project is under Apache License. See the LICENSE file for the full license text.

Documentation

Index

• func New(opts ...Option) app.HandlerFunc
• type Option
  • func WithAllowedHosts(ss []string) Option
  • func WithBadHostHandler(handler app.HandlerFunc) Option
  • func WithBrowserXssFilter(b bool) Option
  • func WithContentSecurityPolicy(s string) Option
  • func WithContentTypeNosniff(b bool) Option
  • func WithCustomFrameOptionsValue(s string) Option
  • func WithDontRedirectIPV4Hostnames(b bool) Option
  • func WithFeaturePolicy(s string) Option
  • func WithFrameDeny(b bool) Option
  • func WithIENoOpen(b bool) Option
  • func WithIsDevelopment(b bool) Option
  • func WithReferrerPolicy(s string) Option
  • func WithSSLHost(s string) Option
  • func WithSSLProxyHeaders(m map[string]string) Option
  • func WithSSLRedirect(b bool) Option
  • func WithSSLTemporaryRedirect(b bool) Option
  • func WithSTSIncludeSubdomains(b bool) Option
  • func WithSTSSecond(sec int64) Option

Functions

func New

func New(opts ...Option) app.HandlerFunc

New creates an instance of the secure middleware using the specified configuration. router.Use(secure.N)

Types

type Option

type Option func(o *options)

func WithAllowedHosts

func WithAllowedHosts(ss []string) Option

WithAllowedHosts is a list of fully qualified domain names that are allowed. Default is empty list, which allows any and all host names.

func WithBadHostHandler

func WithBadHostHandler(handler app.HandlerFunc) Option

WithBadHostHandler use to when an error occurs (ie bad host).

func WithBrowserXssFilter

func WithBrowserXssFilter(b bool) Option

WithBrowserXssFilter when BrowserXssFilter is true, adds the X-XSS-Protection header with the value `1; mode=block`. Default is false.

func WithContentSecurityPolicy

func WithContentSecurityPolicy(s string) Option

WithContentSecurityPolicy allows the Content-Security-Policy header value to be set with a custom value. Default is "".

func WithContentTypeNosniff

func WithContentTypeNosniff(b bool) Option

WithContentTypeNosniff when ContentTypeNosniff is true, adds the X-Content-Type-Options header with the value `nosniff`. Default is false.

func WithCustomFrameOptionsValue

func WithCustomFrameOptionsValue(s string) Option

WithCustomFrameOptionsValue allows the X-Frame-Options header value to be set with a custom value. This overrides the FrameDeny option.

func WithDontRedirectIPV4Hostnames

func WithDontRedirectIPV4Hostnames(b bool) Option

WithDontRedirectIPV4Hostnames when DontRedirectIPV4Hostnames is true, requests to hostnames that are IPV4 addresses aren't redirected. This is to allow load balancer health checks to succeed.

func WithFeaturePolicy

func WithFeaturePolicy(s string) Option

WithFeaturePolicy is a new header that allows a site to control which features and APIs can be used in the browser.

func WithFrameDeny

func WithFrameDeny(b bool) Option

WithFrameDeny when FrameDeny is set to true, adds the X-Frame-Options header with the value of `DENY`. Default is false.

func WithIENoOpen

func WithIENoOpen(b bool) Option

WithIENoOpen prevents Internet Explorer from executing downloads in your site’s context

func WithIsDevelopment

func WithIsDevelopment(b bool) Option

WithIsDevelopment when true, the whole security policy applied by the middleware is disabled completely.

func WithReferrerPolicy

func WithReferrerPolicy(s string) Option

WithReferrerPolicy use to set HTTP header "Referrer-Policy" governs which referrer information, sent in the Referrer header,/should be included with requests made.

func WithSSLHost

func WithSSLHost(s string) Option

WithSSLHost is the host name that is used to redirect http requests to https. Default is "", which indicates to use the same host.

func WithSSLProxyHeaders

func WithSSLProxyHeaders(m map[string]string) Option

WithSSLProxyHeaders If the request is insecure, treat it as secure if any of the headers in this dict are set to their corresponding value This is useful when your app is running behind a secure proxy that forwards requests to your app over http (such as on Heroku).

func WithSSLRedirect

func WithSSLRedirect(b bool) Option

WithSSLRedirect when SSLRedirect is set to true, then only allow https requests. Default is false.

func WithSSLTemporaryRedirect

func WithSSLTemporaryRedirect(b bool) Option

WithSSLTemporaryRedirect when SSLTemporaryRedirect is true, the a 302 will be used while redirecting. Default is false (301).

func WithSTSIncludeSubdomains

func WithSTSIncludeSubdomains(b bool) Option

WithSTSIncludeSubdomains when STSIncludeSubdomains is set to true, the `includeSubdomains` will be appended to the Strict-Transport-Security header. Default is false.

func WithSTSSecond

func WithSTSSecond(sec int64) Option

WithSTSSecond is the max-age of the Strict-Transport-Security header. Default is 0, which would NOT include the header.