security

Documentation

Overview

Package security includes encryption and decryption with AES-GCM, secure key generation, HMAC hashing, bcrypt-based password handling, and a preconfigured secure HTTP(S) server with liveness and readiness probes for robust application security.

Index

• Variables
• func Decrypt(ciphertext []byte, key [32]byte) (plaintext []byte, err error)
• func Encrypt(plaintext []byte, key [32]byte) (ciphertext []byte)
• func GenerateID() string
• func GenerateKey() [32]byte
• func GeneratePKCE() (codeVerifier, challenge string)
• func Getenv(key string) (out [32]byte)
• func Hash(tag string, data []byte) (sum []byte)
• func IsPasswordValid(ciphertext, plaintext []byte) bool
• func NewClient() *http.Client
• func NewClientWithTLS(certFile, keyFile, caFile string) *http.Client
• func NewIdentityProvider() *identityProvider
• func NewServer(mux *http.ServeMux) *http.Server
• func ParseDuration(key string, def time.Duration) time.Duration
• func ParseInt(key string, def int) int
• func Password(plaintext []byte) ([]byte, error)
• func TLSClientConfig(certFile, keyFile, caFile string) *tls.Config
• func WithAuth(sessions *ServerSessions, next http.HandlerFunc) http.HandlerFunc
• type ContextKey
• type IdentityTokenClaims
• type ServerSession
• type ServerSessions
  • func NewServeMux(ctx context.Context, efs embed.FS) (mux *http.ServeMux, serverSessions *ServerSessions)
  • func NewServerSessions() *ServerSessions
  • func (a *ServerSessions) Create(id string, data any) (s ServerSession)
  • func (a *ServerSessions) Delete(id string)
  • func (a *ServerSessions) Read(id string) (*ServerSession, bool)
  • func (a *ServerSessions) Update(s ServerSession)

Variables

var IdentityProvider = NewIdentityProvider()

IdentityProvider is a singleton instance of the identity provider.

Functions

func Decrypt

func Decrypt(ciphertext []byte, key [32]byte) (plaintext []byte, err error)

Decrypt takes an encrypted byte slice (ciphertext) and a 256-bit AES key, and decrypts the ciphertext using AES-GCM.

func Encrypt

func Encrypt(plaintext []byte, key [32]byte) (ciphertext []byte)

Encrypt takes an input byte slice (plaintext) and encrypts it using AES-GCM. It returns the encrypted data (ciphertext) and the key used for encryption.

func GenerateID

func GenerateID() string

GenerateID generates a unique ID using a secure random key.

func GenerateKey

func GenerateKey() [32]byte

GenerateKey generates a 256-bit (32-byte) random key for AES encryption. It uses a cryptographically secure random number generator.

func GeneratePKCE

func GeneratePKCE() (codeVerifier, challenge string)

GeneratePKCE generates a OAuth 2.0 PKCE challenge by using a random string.

func Getenv

func Getenv(key string) (out [32]byte)

Getenv retrieves an environment variable by the given key, interprets its value as a hexadecimal string, and decodes it into a 32-byte array. If the environment variable is not set, the value is not a valid hex string, or the decoded byte length is not 32, the function returns an empty array.

func Hash

func Hash(tag string, data []byte) (sum []byte)

Hash generates an HMAC hash using the SHA-512/256 algorithm.

func IsPasswordValid

func IsPasswordValid(ciphertext, plaintext []byte) bool

IsPasswordValid checks if a given plaintext password matches a hashed password.

func NewClient

func NewClient() *http.Client

NewClient creates and returns a new *http.Client with a default timeout of 5 seconds. The timeout can be adjusted by setting the CLIENT_TIMEOUT environment variable.

func NewClientWithTLS

func NewClientWithTLS(certFile, keyFile, caFile string) *http.Client

NewClientWithTLS creates and returns a new *http.Client with mutual TLS authentication.

func NewIdentityProvider

func NewIdentityProvider() *identityProvider

NewIdentityProvider creates a new identity provider.

func NewServer

func NewServer(mux *http.ServeMux) *http.Server

NewServer creates and returns a configured HTTP server. It uses the PORT environment variable or defaults to port 8080. The server has a default timeout of 5 seconds for read, write, and idle connections. The timeout can be adjusted by setting the SERVER_*_TIMEOUT environment variables.

func ParseDuration

func ParseDuration(key string, def time.Duration) time.Duration

ParseDuration parses the value of the environment variable with the given key as a duration. If the value is not set or cannot be parsed, the default duration is returned.

func ParseInt

func ParseInt(key string, def int) int

ParseInt parses the value of the environment variable with the given key as an integer. If the value is not set or cannot be parsed, the default integer is returned.

func Password

func Password(plaintext []byte) ([]byte, error)

Password hashes a plaintext password using bcrypt with a cost of 14.

func TLSClientConfig

func TLSClientConfig(certFile, keyFile, caFile string) *tls.Config

TLSClientConfig creates and returns a *tls.Config configured for mutual TLS authentication. It loads client specific certificates and adds server specific root CA certificates.

func WithAuth

func WithAuth(sessions *ServerSessions, next http.HandlerFunc) http.HandlerFunc

WithAuth adds authentication information to the context.

Types

type ContextKey

type ContextKey string

const (
	ContextSessionID ContextKey = "session_id"
	ContextEmail     ContextKey = "email"
	ContextIssuer    ContextKey = "issuer"
	ContextName      ContextKey = "name"
	ContextSubject   ContextKey = "subject"
	ContextVerified  ContextKey = "verified"
)

type IdentityTokenClaims

type IdentityTokenClaims struct {
	Email    string `json:"email"`
	Issuer   string `json:"iss"`
	Name     string `json:"name"`
	Subject  string `json:"sub"`
	Verified bool   `json:"email_verified"`
}

IdentityTokenClaims represents the claims of an identity token.

type ServerSession

type ServerSession struct {
	ID   string `json:"id"`
	Data any    `json:"value"`
}

ServerSession is a session for a user.

type ServerSessions

type ServerSessions struct {
	// contains filtered or unexported fields
}

ServerSessions is a thread-safe map of session IDs to sessions.

func NewServeMux

func NewServeMux(ctx context.Context, efs embed.FS) (mux *http.ServeMux, serverSessions *ServerSessions)

NewServeMux creates a new mux with the liveness check endpoint (/liveness) and the readiness check endpoint (/readiness). The mux is returned along with a new ServerSessions instance.

func NewServerSessions

func NewServerSessions() *ServerSessions

NewServerSessions creates a new serverSessions.

func (*ServerSessions) Create

func (a *ServerSessions) Create(id string, data any) (s ServerSession)

Create adds a new session to the serverSessions.

func (*ServerSessions) Delete

func (a *ServerSessions) Delete(id string)

Delete removes the session with the given sessionID.

func (*ServerSessions) Read

func (a *ServerSessions) Read(id string) (*ServerSession, bool)

Get returns the session for the given sessionID.

func (*ServerSessions) Update

func (a *ServerSessions) Update(s ServerSession)

Update adds a new session to the serverSessions.