security

func APIKeyAuth ¶ added in v0.0.6

func APIKeyAuth() echo.MiddlewareFunc

APIKeyAuth creates an Echo middleware for API key authentication. This middleware validates incoming requests against an API key stored in the API_KEY environment variable. The /health endpoint is exempted from authentication to allow health checks.

The middleware expects the API key in the X-API-Key request header.

Returns:

• echo.MiddlewareFunc: Configured middleware function

Example:

e := echo.New()
api := e.Group("/api")
api.Use(APIKeyAuth())
api.GET("/protected", handler) // This endpoint requires X-API-Key header

e.GET("/health", healthHandler) // This endpoint is public

// Set API key in environment
os.Setenv("API_KEY", "my-secret-key")
defer os.Unsetenv("API_KEY")

e := echo.New()

// Public endpoint
e.GET("/health", func(c echo.Context) error {
	return c.String(http.StatusOK, "OK")
})

// Protected API group
api := e.Group("/api")
api.Use(security.APIKeyAuth())

// This endpoint requires X-API-Key header
api.GET("/protected", func(c echo.Context) error {
	return c.JSON(http.StatusOK, map[string]string{
		"message": "Access granted",
	})
})

// Start server
// Clients must send: X-API-Key: my-secret-key
e.Start(":8080")

func CertsCheckHost ¶

func CertsCheckHost(host string, warnYears, warnMonths, warnDays *int) (result hostResult)

CertsCheckHost checks the TLS certificates of a host for expiration and security issues. This function connects to the host, examines its certificate chain, and checks for:

• Certificates expiring within the warning period
• Use of deprecated signature algorithms

Parameters:

• host: The host:port to check (e.g., "example.com:443")
• warnYears: Number of years before expiration to start warning
• warnMonths: Number of months before expiration to start warning
• warnDays: Number of days before expiration to start warning

Returns:

• hostResult: A struct containing the host information, any errors found, and the common name from the certificate

The function:

1. Establishes a TLS connection to the host
2. Examines each certificate in the verified chains
3. Checks expiration dates against the warning thresholds
4. Validates signature algorithms against known deprecated algorithms
5. Returns any issues found

func DecryptFile ¶

func DecryptFile(pass, inputPath, outputPath string) error

DecryptFile decrypts a ciphertext file to a plaintext file using AES-256-GCM.

The decryption key is derived from the provided password using SHA-256. The ciphertext file must contain a prepended nonce (generated during encryption). The function verifies authenticity and integrity during decryption.

Parameters:

• pass: Password used to derive the decryption key.
• inputPath: Path to the ciphertext file to decrypt.
• outputPath: Path to write the decrypted plaintext file.

Returns an error if reading, decryption, authentication, or writing fails.

func EncryptFile ¶

func EncryptFile(pass, inputPath, outputPath string) error

EncryptFile encrypts a plaintext file to a ciphertext file using AES-256-GCM.

The encryption key is derived from the provided password using SHA-256, producing a 32-byte key for AES-256. A random nonce is generated and prepended to the ciphertext. The resulting data is written to outputPath.

Parameters:

• pass: Password used to derive the encryption key.
• inputPath: Path to the plaintext file to encrypt.
• outputPath: Path to write the resulting ciphertext file.

Returns an error if reading, encryption, or writing fails.

func ExtractScopesFromXSUAA ¶ added in v0.0.12

func ExtractScopesFromXSUAA(claims map[string]interface{}) []string

ExtractScopesFromXSUAA extracts scopes from XSUAA token claims. XSUAA tokens store scopes in the "scope" claim as an array of strings.

Parameters:

• claims: The token claims map

Returns:

• []string: List of scopes, or nil if not found

Example:

claims, _ := VerifyXSUAAToken(token, xsuaaURL)
scopes := ExtractScopesFromXSUAA(claims)
for _, scope := range scopes {
    fmt.Println("Scope:", scope)
}

func HandleWithClientCredentials ¶ added in v0.0.6

func HandleWithClientCredentials(c echo.Context) error

HandleWithClientCredentials is an Echo HTTP handler that forwards requests to a backend service using XSUAA client credentials authentication. This demonstrates how to use client credentials tokens to authenticate service-to-service API calls.

The handler:

1. Constructs a target URL with query parameters
2. Adds the XSUAA bearer token to the Authorization header
3. Forwards the request to the backend service
4. Returns the backend response to the client

Query Parameters:

• product_group: Product category identifier
• publication_id: Publication identifier for the X-Publication-Id header
• filter_columns: Comma-separated list of columns to filter

Returns:

• error: Any error encountered during request processing

Example usage in Echo router:

e := echo.New()
e.GET("/api/response", HandleWithClientCredentials)

func HasXSUAAScope ¶ added in v0.0.12

func HasXSUAAScope(claims map[string]interface{}, scope string) bool

HasXSUAAScope checks if the claims contain a specific scope. Scopes in XSUAA typically have the format "appname.scopename".

Parameters:

• claims: The token claims map
• scope: The scope to check for

Returns:

• bool: true if the scope is present, false otherwise

Example:

claims, _ := VerifyXSUAAToken(token, xsuaaURL)
if HasXSUAAScope(claims, "myapp.read") {
    fmt.Println("User has read permission")
}

func HashPassword ¶ added in v0.0.12

func HashPassword(password string) (string, error)

HashPassword creates a bcrypt hash of the provided password. Uses the default cost factor (10) which provides good security for most use cases.

Bcrypt is a password hashing function designed to be slow and computationally expensive, making it resistant to brute-force attacks. Each hash includes a random salt automatically.

Parameters:

• password: The plaintext password to hash

Returns:

• string: The bcrypt hash string (includes algorithm, cost, salt, and hash)
• error: Any error encountered during hashing

Example:

hash, err := HashPassword("mySecurePassword123")
if err != nil {
    log.Fatalf("Failed to hash password: %v", err)
}
// Store hash in database: $2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy

func HashPasswordWithCost ¶ added in v0.0.12

func HashPasswordWithCost(password string, cost int) (string, error)

HashPasswordWithCost creates a bcrypt hash of the provided password with a custom cost factor. Use this when you need fine-grained control over the hashing cost.

Cost factor recommendations:

• 10: Default, suitable for most applications
• 12: Higher security, slower hashing (~250ms)
• 14: Very high security, much slower (~1 second)
• 4-9: Faster but less secure (not recommended for production)

Parameters:

• password: The plaintext password to hash
• cost: The bcrypt cost factor (must be between bcrypt.MinCost and bcrypt.MaxCost)

Returns:

• string: The bcrypt hash string
• error: Any error encountered during hashing

Example:

// Use higher cost for admin passwords
hash, err := HashPasswordWithCost("adminPassword", 12)
if err != nil {
    log.Fatalf("Failed to hash password: %v", err)
}

func InfisicalSecrets ¶

func InfisicalSecrets(host, client_id, client_secret, project_id, environment, format string) string

InfisicalSecrets retrieves secrets from an Infisical project environment.

It authenticates using the provided client ID and secret, fetches secrets for the given project and environment, and returns them formatted as either environment variable declarations or `.netrc` entries.

Parameters:

• host: The Infisical host domain (e.g. "app.infisical.com").
• client_id: The Infisical client ID for authentication.
• client_secret: The Infisical client secret for authentication.
• project_id: The project identifier from which to fetch secrets.
• environment: The target environment name (e.g. "dev", "prod").
• format: Output format, either "env" (default) or "netrc".

Returns:

A string containing either key=value pairs (one per line) or `.netrc`
formatted credentials if format == "netrc".

Behavior:

• On authentication or retrieval failure, the program logs the error using eve.Logger and exits with status code 1.
• If format == "netrc", it looks for secrets with keys "MACHINE", "LOGIN", and "PASSWORD" to construct the .netrc entry.

Example Output (env format):

MACHINE=github.com
LOGIN=myuser
PASSWORD=mytoken

Example Output (netrc format):

machine github.com
login myuser
password mytoken

func NeedsRehash ¶ added in v0.0.12

func NeedsRehash(hash string, cost int) (bool, error)

NeedsRehash checks if a password hash needs to be regenerated with a different cost factor. This is useful when you increase the cost factor in your application and want to upgrade old hashes during user login.

Parameters:

• hash: The bcrypt hash to check
• cost: The desired cost factor

Returns:

• bool: true if the hash needs to be regenerated with the new cost
• error: Any error encountered while parsing the hash

Example:

const CurrentCost = 12

// During login after successful password verification
needsRehash, err := NeedsRehash(storedHash, CurrentCost)
if err == nil && needsRehash {
    newHash, _ := HashPasswordWithCost(password, CurrentCost)
    // Update hash in database
}

func SetGlobalXSUAAToken ¶ added in v0.0.6

func SetGlobalXSUAAToken(token *TokenResponse)

SetGlobalXSUAAToken sets the global XSUAA token for use in handlers. This is typically called during application initialization after obtaining the token via GetXSUAAToken.

Parameters:

• token: The token response to cache globally

Example:

token, err := GetXSUAAToken(tokenURL, clientID, clientSecret)
if err != nil {
    log.Fatal(err)
}
SetGlobalXSUAAToken(token)

package main

import (
	"fmt"

	"eve.evalgo.org/security"
)

func main() {
	// Obtain token
	token := &security.TokenResponse{
		AccessToken: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
		TokenType:   "bearer",
		ExpiresIn:   3600,
	}

	// Cache token globally
	security.SetGlobalXSUAAToken(token)

	// Later, retrieve the token
	cachedToken := security.GetGlobalXSUAAToken()
	if cachedToken != nil {
		fmt.Printf("Token expires in: %d seconds\n", cachedToken.ExpiresIn)
	}
}

Output:

Token expires in: 3600 seconds

func VerifyPassword ¶ added in v0.0.12

func VerifyPassword(hash, password string) error

VerifyPassword compares a plaintext password with a bcrypt hash. Returns nil if the password matches the hash, or an error if they don't match or if verification fails.

This function is constant-time to prevent timing attacks.

Parameters:

• hash: The bcrypt hash to verify against
• password: The plaintext password to check

Returns:

• error: nil if password matches, bcrypt.ErrMismatchedHashAndPassword if mismatch, or other error if verification fails

Example:

// During login
err := VerifyPassword(storedHash, userProvidedPassword)
if err != nil {
    if err == bcrypt.ErrMismatchedHashAndPassword {
        log.Println("Invalid password")
    } else {
        log.Printf("Verification error: %v", err)
    }
    return
}
log.Println("Password correct, user authenticated")

func VerifyXSUAAToken ¶ added in v0.0.12

func VerifyXSUAAToken(token, xsuaaURL string) (map[string]interface{}, error)

VerifyXSUAAToken verifies an XSUAA JWT token using the provider's public key. This performs cryptographic validation of the token signature using JWK (JSON Web Key).

The function:

1. Fetches the JWK Set from the XSUAA provider's token_keys endpoint
2. Verifies the token signature using the appropriate public key
3. Validates standard claims (expiration, issuer, etc.)

Parameters:

• token: The raw JWT token string to verify
• xsuaaURL: The XSUAA service base URL (e.g., from credentials.URL)

Returns:

• map[string]interface{}: The validated token claims
• error: Any error during verification

Example:

creds, _ := GetXSUAACredentials()
claims, err := VerifyXSUAAToken(tokenString, creds.URL)
if err != nil {
    log.Printf("Invalid token: %v", err)
    return
}
fmt.Printf("User: %s\n", claims["user_name"])

func VerifyXSUAATokenWithKey ¶ added in v0.0.12

func VerifyXSUAATokenWithKey(token, publicKey string) (map[string]interface{}, error)

VerifyXSUAATokenWithKey verifies an XSUAA JWT token using a provided public key. Use this when you have the public key directly (e.g., from XSUAA_VERIFICATION_KEY env var).

The public key can be:

• PEM-encoded RSA public key
• PEM-encoded ECDSA public key
• Base64-encoded public key

Parameters:

• token: The raw JWT token string to verify
• publicKey: The public key in PEM or base64 format

Returns:

• map[string]interface{}: The validated token claims
• error: Any error during verification

Example:

publicKey := os.Getenv("XSUAA_VERIFICATION_KEY")
claims, err := VerifyXSUAATokenWithKey(tokenString, publicKey)
if err != nil {
    log.Printf("Invalid token: %v", err)
    return
}
fmt.Printf("Scopes: %v\n", claims["scope"])

func ZitiCreateCSR ¶

func ZitiCreateCSR(privateFilePath, csrFilePath string) error

ZitiCreateCSR generates a Certificate Signing Request (CSR) and private key for Ziti. This function creates an ECDSA key pair and generates a CSR for a Ziti edge router.

Parameters:

• privateFilePath: Path to save the generated private key
• csrFilePath: Path to save the generated CSR

The function:

1. Generates an ECDSA key pair using P-256 curve
2. Saves the private key to a PEM file
3. Creates a CSR template with appropriate subject information
4. Generates the CSR using the private key
5. Saves the CSR to a PEM file

The generated CSR will have:

• Common Name: "ziti-edge-router"
• Organization: "OpenZiti"
• Signature Algorithm: ECDSA with SHA-256