security

gokit/security

TLS configuration, secure header policies, and test helpers for secure transport across gokit modules.

Overview

The security package provides:

• TLSConfig for TLS 1.2+ transport policy, CA bundles, and mTLS
• HeadersConfig for secure-by-default HTTP response headers

Configuration fields are tagged for YAML and mapstructure, so they integrate directly with gokit's config loading.

The locked transport policy is explicit:

• minimum supported floor: TLS 1.2
• default negotiation outcome: TLS 1.3 whenever both peers support it
• explicit floors below TLS 1.2 are rejected during validation
• secure headers default-on: HSTS, CSP, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy

The companion tlstest sub-package generates self-signed certificates for integration tests — no external tools or fixtures required.

Installation

go get github.com/kbukum/gokit

security is part of the core module — no separate go get needed.

Quick Start

package main

import (
	"crypto/tls"
	"fmt"

	"github.com/kbukum/gokit/security"
)

func main() {
	cfg := security.TLSConfig{
		CAFile:     "/etc/certs/ca.pem",
		CertFile:   "/etc/certs/client.pem",
		KeyFile:    "/etc/certs/client-key.pem",
		ServerName: "api.example.com",
		MinVersion: tls.VersionTLS13,
	}

	if err := cfg.Validate(); err != nil {
		panic(err)
	}

	tlsConfig, err := cfg.Build()
	if err != nil {
		panic(err)
	}

	fmt.Println(tlsConfig != nil) // true
}

API Reference

TLSConfig

HeadersConfig

Methods

Advanced Usage

Mutual TLS (mTLS)

cfg := security.TLSConfig{
	CAFile:   "/etc/certs/ca.pem",
	CertFile: "/etc/certs/client.pem",
	KeyFile:  "/etc/certs/client-key.pem",
}

tlsCfg, _ := cfg.Build()
// tlsCfg.Certificates contains the client cert
// tlsCfg.RootCAs contains the CA for server verification

Embedding in Service Config

tls:
  ca_file: /etc/certs/ca.pem
  cert_file: /etc/certs/client.pem
  key_file: /etc/certs/client-key.pem
  server_name: api.example.com
  min_version: 772  # tls.VersionTLS13

type KafkaConfig struct {
	Brokers []string          `yaml:"brokers"`
	TLS     security.TLSConfig `yaml:"tls"`
}

Testing with tlstest

The tlstest package generates ephemeral self-signed certificates for tests.

import "github.com/kbukum/gokit/security/tlstest"

func TestMTLS(t *testing.T) {
	certs := tlstest.GenerateTLSCerts(t)

	// Use generated file paths
	cfg := security.TLSConfig{
		CAFile:   certs.CAFile,
		CertFile: certs.CertFile,
		KeyFile:  certs.KeyFile,
	}

	tlsCfg, err := cfg.Build()
	require.NoError(t, err)
	require.NotNil(t, tlsCfg)

	// Or use the pre-built objects directly
	_ = certs.ServerTLS  // tls.Certificate
	_ = certs.CertPool   // *x509.CertPool
}

GenerateTLSCerts creates an ECDSA P-256 CA and server certificate valid for localhost, 127.0.0.1, and ::1. Files are written to t.TempDir() and cleaned up automatically.

Use WriteInvalidPEM(t, "bad.pem") to generate invalid certificate files for error-path testing.

Testing

cd security
go test -race ./...

Contributing

Please refer to the root CONTRIBUTING.md for guidelines.