Security Stack: TLS, Argon2id & Password Hashing

Security isn’t a feature you add at the end—it’s the foundation you build upon. This article explores the production-ready security implementation from the email-server project, covering automatic TLS management, OWASP-recommended password hashing with Argon2id, and the security considerations that go into protecting user credentials.

TLS/ACME Integration: Automatic Certificate Management

Let’s Encrypt with autocert

The TLS manager provides seamless integration with Let’s Encrypt using Go’s autocert package:

// @filename: handlers.go
// internal/security/tls.go
func NewTLSManager(cfg *config.Config) (*TLSManager, error) {
  manager := &TLSManager{config: cfg}

  if cfg.TLS.AutoTLS {
    // Use Let's Encrypt with autocert
    manager.certManager = &autocert.Manager{
      Prompt:     autocert.AcceptTOS,
      HostPolicy: autocert.HostWhitelist(cfg.Server.Hostname),
      Cache:      autocert.DirCache(cfg.TLS.CacheDir),
      Email:      cfg.TLS.Email,
    }

    manager.tlsConfig = manager.certManager.TLSConfig()
  } else if cfg.TLS.CertFile != "" && cfg.TLS.KeyFile != "" {
    // Use provided certificates
    cert, err := tls.LoadX509KeyPair(cfg.TLS.CertFile, cfg.TLS.KeyFile)
    if err != nil {
      return nil, fmt.Errorf("failed to load TLS certificate: %w", err)
    }

    manager.tlsConfig = &tls.Config{
      Certificates: []tls.Certificate{cert},
      MinVersion:   tls.VersionTLS12,
    }
  }

  // Set secure defaults if TLS is configured
  if manager.tlsConfig != nil {
    // Use TLS 1.2 as minimum for email client compatibility (Apple Mail, Outlook, etc.)
    // TLS 1.3 is preferred but many email clients still require TLS 1.2 support
    // The cipher suites below ensure TLS 1.2 connections use only secure algorithms
    manager.tlsConfig.MinVersion = tls.VersionTLS12

    // Secure cipher suites for TLS 1.2 connections
    // TLS 1.3 uses its own fixed cipher suites (these are ignored for 1.3)
    // All suites use ECDHE for forward secrecy and AEAD ciphers (GCM/ChaCha20)
    manager.tlsConfig.CipherSuites = []uint16{
      tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
      tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
      tls.TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,
      tls.TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,
      tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
      tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
    }
  }

  return manager, nil
}

Key Features

1. Automatic certificate renewal: Let’s Encrypt certificates are valid for 90 days, but autocert handles renewal automatically before expiration
2. Flexible configuration: Supports both automatic ACME certificates and custom certificate/key pairs
3. HTTP-01 challenges: Built-in challenge handling for domain validation
4. Persistent caching: Certificates cached to disk to survive restarts

TLS Configuration Best Practices

The implementation follows several security best practices:

• Minimum TLS 1.2: TLS 1.0/1.1 are deprecated and insecure
• Secure cipher suites only: Only ECDHE with AEAD ciphers for forward secrecy
• No weak algorithms: Excludes CBC mode ciphers vulnerable to BEAST/POODLE
• AES-256 and ChaCha20: Strong encryption with hardware acceleration support

Argon2id: OWASP-Recommended Password Hashing

Implementation Details

Argon2id combines the best properties of Argon2i (resistant to side-channel attacks) and Argon2d (resistant to GPU attacks), making it ideal for password hashing:

// @filename: handlers.go
// internal/auth/password.go
package auth


  "crypto/rand"
  "crypto/subtle"
  "encoding/base64"
  "fmt"
  "strings"

  "golang.org/x/crypto/argon2"
)

// Argon2id parameters (OWASP recommended)
const (
  argon2Time    = 3         // Number of iterations
  argon2Memory  = 64 * 1024 // 64 MB
  argon2Threads = 4         // Parallelism
  argon2KeyLen  = 32        // Output key length
  argon2SaltLen = 16        // Salt length
)

// HashPassword creates an argon2id hash of the password
func HashPassword(password string) (string, error) {
  // Generate random salt
  salt := make([]byte, argon2SaltLen)
  if _, err := rand.Read(salt); err != nil {
    return "", fmt.Errorf("failed to generate salt: %w", err)
  }

  // Hash password with argon2id
  hash := argon2.IDKey([]byte(password), salt, argon2Time, argon2Memory, argon2Threads, argon2KeyLen)

  // Encode as "$argon2id$v=19$m=65536,t=3,p=4$<salt>$<hash>"
  b64Salt := base64.RawStdEncoding.EncodeToString(salt)
  b64Hash := base64.RawStdEncoding.EncodeToString(hash)

  encoded := fmt.Sprintf("$argon2id$v=%d$m=%d,t=%d,p=%d$%s$%s",
    argon2.Version, argon2Memory, argon2Time, argon2Threads,
    b64Salt, b64Hash,
  )

  return encoded, nil
}

// VerifyPassword checks if a password matches the hash
func VerifyPassword(password, encoded string) bool {
  // Parse the encoded hash
  params, salt, hash, err := parseArgon2Hash(encoded)
  if err != nil {
    return false
  }

  // Compute hash with same parameters
  computedHash := argon2.IDKey(
    []byte(password), salt,
    params.time, params.memory, params.threads, params.keyLen,
  )

  // Constant-time comparison
  return subtle.ConstantTimeCompare(hash, computedHash) == 1
}

OWASP-Recommended Parameters

Why Argon2id over bcrypt/scrypt?

Performance Comparison

Benchmark results on a 4-core system (email-server performance tests):

Argon2id provides the best resistance to GPU attacks due to its memory-hard nature, making brute force attacks significantly more expensive.

Password Hash Flow: Registration, Authentication, Verification

Registration Flow

// @filename: query.sql
// internal/auth/auth.go
func (a *Authenticator) CreateUser(ctx context.Context, username, password string, domainID int64) (*User, error) {
  // Validate username format
  if err := ValidateUsername(username); err != nil {
    return nil, err
  }

  // Validate password strength
  if err := ValidatePassword(password); err != nil {
    return nil, err
  }

  // Normalize username to lowercase for consistency
  username = strings.ToLower(strings.TrimSpace(username))

  // Begin transaction for atomicity
  tx, err := a.db.BeginTx(ctx, nil)
  if err != nil {
    return nil, fmt.Errorf("failed to begin transaction: %w", err)
  }
  defer tx.Rollback() // Safe to call even after commit

  // Verify domain exists and get domain name (within transaction)
  var domainName string
  err = tx.QueryRowContext(ctx, "SELECT name FROM domains WHERE id = ? AND is_active = TRUE", domainID).Scan(&domainName)
  if err != nil {
    if errors.Is(err, sql.ErrNoRows) {
      return nil, ErrDomainNotFound
    }
    return nil, fmt.Errorf("failed to query domain id %d: %w", domainID, err)
  }

  // Hash password
  passwordHash, err := HashPassword(password)
  if err != nil {
    return nil, fmt.Errorf("failed to hash password: %w", err)
  }

  // Insert user
  result, err := tx.ExecContext(ctx, `
    INSERT INTO users (domain_id, username, password_hash, is_active, created_at, updated_at)
    VALUES (?, ?, ?, TRUE, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
  `, domainID, username, passwordHash)
  if err != nil {
    return nil, fmt.Errorf("failed to create user %s@%s: %w", username, domainName, err)
  }

  id, err := result.LastInsertId()
  if err != nil {
    return nil, fmt.Errorf("failed to get last insert id: %w", err)
  }

  // Commit transaction
  if err := tx.Commit(); err != nil {
    return nil, fmt.Errorf("failed to commit transaction: %w", err)
  }

  return &User{
    ID:       id,
    DomainID: domainID,
    Username: username,
    Domain:   domainName,
    Email:    fmt.Sprintf("%s@%s", username, domainName),
    IsActive: true,
  }, nil
}

Authentication Flow

// @filename: main.go
// internal/auth/auth.go
func (a *Authenticator) Authenticate(ctx context.Context, email, password string) (*User, error) {
  // Normalize email for lockout tracking
  normalizedEmail := strings.ToLower(strings.TrimSpace(email))

  // Check if account is locked FIRST (before any other processing)
  // Return generic error to prevent username enumeration via timing
  if a.isAccountLocked(normalizedEmail) {
    // Do a dummy hash comparison to prevent timing attack
    _ = VerifyPassword(password, "$argon2id$v=19$m=65536,t=3,p=4$dummysalt$dummyhash")
    return nil, ErrInvalidCredentials // Return generic error instead of ErrAccountLocked
  }

  // Basic email parsing (no password validation yet to avoid timing attacks)
  username, domain, err := parseEmail(email)
  if err != nil {
    a.recordFailedAttempt(normalizedEmail)
    return nil, ErrInvalidCredentials // Don't leak validation details
  }

  // Look up user
  user, passwordHash, err := a.lookupUserWithPassword(ctx, username, domain)
  if err != nil {
    a.recordFailedAttempt(normalizedEmail)
    if errors.Is(err, ErrUserNotFound) {
      // Do a dummy hash comparison to prevent timing attack
      _ = VerifyPassword(password, "$argon2id$v=19$m=65536,t=3,p=4$dummysalt$dummyhash")
      return nil, ErrInvalidCredentials
    }
    return nil, fmt.Errorf("authentication lookup failed: %w", err)
  }

  // Check if account is disabled - return generic error to prevent enumeration
  if !user.IsActive {
    // Do a dummy hash comparison to prevent timing attack
    _ = VerifyPassword(password, "$argon2id$v=19$m=65536,t=3,p=4$dummysalt$dummyhash")
    return nil, ErrInvalidCredentials // Return generic error instead of ErrUserDisabled
  }

  // Now validate password length (do this before expensive hash verification)
  if err := ValidatePassword(password); err != nil {
    a.recordFailedAttempt(normalizedEmail)
    return nil, ErrInvalidCredentials // Don't leak validation details
  }

  // Verify password hash (constant-time comparison)
  if !VerifyPassword(password, passwordHash) {
    a.recordFailedAttempt(normalizedEmail)
    return nil, ErrInvalidCredentials
  }

  // Clear lockout on successful login
  a.clearLockout(normalizedEmail)

  return user, nil
}

Account Lockout Mechanism

The implementation includes robust account lockout to prevent brute force attacks:

// @filename: main.go
const (
  maxAttempts     = 10           // Max failed attempts before lockout
  lockoutWindow   = time.Hour    // Time window for counting attempts
  lockoutDuration = 30 * time.Minute // How long to lock account
)

func (a *Authenticator) isAccountLocked(email string) bool {
  a.lockoutMu.RLock()
  defer a.lockoutMu.RUnlock()

  lockout, exists := a.lockouts[email]
  if !exists {
    return false
  }
  return time.Now().Before(lockout.lockedUntil)
}

func (a *Authenticator) recordFailedAttempt(email string) bool {
  a.lockoutMu.Lock()
  defer a.lockoutMu.Unlock()

  now := time.Now()
  lockout, exists := a.lockouts[email]

  if !exists {
    a.lockouts[email] = &accountLockout{
      failedAttempts: 1,
      firstFailure:   now,
    }
    return false
  }

  // Reset if window expired
  if now.After(lockout.firstFailure.Add(a.lockoutWindow)) {
    lockout.failedAttempts = 1
    lockout.firstFailure = now
    lockout.lockedUntil = time.Time{}
    return false
  }

  lockout.failedAttempts++

  // Lock if max attempts reached
  if lockout.failedAttempts >= a.maxAttempts {
    lockout.lockedUntil = now.Add(a.lockoutDuration)
    return true
  }

  return false
}

Constant-Time Comparison: Preventing Timing Attacks

The Attack Vector

Timing attacks exploit the fact that string comparison operations take different amounts of time based on how many characters match before the first mismatch. An attacker can iteratively guess passwords and measure response times to deduce correct characters.

Implementation Using subtle.ConstantTimeCompare

// @filename: handlers.go
// internal/auth/password.go
func VerifyPassword(password, encoded string) bool {
  // Parse the encoded hash
  params, salt, hash, err := parseArgon2Hash(encoded)
  if err != nil {
    return false
  }

  // Compute hash with same parameters
  computedHash := argon2.IDKey(
    []byte(password), salt,
    params.time, params.memory, params.threads, params.keyLen,
  )

  // Constant-time comparison
  return subtle.ConstantTimeCompare(hash, computedHash) == 1
}

Timing-Consistent Error Handling

The authentication flow uses dummy hash comparisons to prevent timing attacks:

// @filename: main.go
// internal/auth/auth.go
if a.isAccountLocked(normalizedEmail) {
  // Do a dummy hash comparison to prevent timing attack
  _ = VerifyPassword(password, "$argon2id$v=19$m=65536,t=3,p=4$dummysalt$dummyhash")
  return nil, ErrInvalidCredentials
}

user, passwordHash, err := a.lookupUserWithPassword(ctx, username, domain)
if err != nil {
  a.recordFailedAttempt(normalizedEmail)
  if errors.Is(err, ErrUserNotFound) {
    // Do a dummy hash comparison to prevent timing attack
    _ = VerifyPassword(password, "$argon2id$v=19$m=65536,t=3,p=4$dummysalt$dummyhash")
    return nil, ErrInvalidCredentials
  }
  return nil, fmt.Errorf("authentication lookup failed: %w", err)
}

This ensures that failed authentication attempts take roughly the same amount of time regardless of whether the user exists, is locked, or has an incorrect password.

TLS Certificate Verification: Configurable Enforcement

Configuration Options

The delivery engine provides configurable TLS enforcement for outbound SMTP delivery:

// @filename: handlers.go
// internal/smtp/delivery/delivery.go
type Config struct {
  // RequireTLS requires TLS for outbound delivery.
  RequireTLS bool
  // VerifyTLS verifies TLS certificates.
  VerifyTLS bool
}

// Default configuration
func DefaultConfig() Config {
  return Config{
    RequireTLS: false,
    VerifyTLS:  true,
  }
}

TLS Handshake with Verification

// @filename: main.go
// internal/smtp/delivery/delivery.go
func (e *Engine) deliverToHostWithTLS(ctx context.Context, addr, hostname string, msg *queue.Message, data []byte, tryTLS bool) error {
  // ... connection setup ...

  // Try STARTTLS if enabled and this is our first attempt
  if tryTLS {
    if ok, _ := client.Extension("STARTTLS"); ok {
      tlsConfig := &tls.Config{
        ServerName:         hostname,
        InsecureSkipVerify: !e.config.VerifyTLS,
        MinVersion:         tls.VersionTLS12,
      }
      if err := client.StartTLS(tlsConfig); err != nil {
        if e.config.RequireTLS {
          return fmt.Errorf("STARTTLS required but failed: %w", err)
        }

        // SECURITY WARNING: TLS downgrade attack possible here
        // Consider setting RequireTLS=true in production for sensitive mail.
        e.logger.WarnContext(ctx, "SECURITY: STARTTLS failed, falling back to plaintext - potential downgrade attack",
          "error", err,
          "hostname", hostname,
          "recommendation", "set RequireTLS=true for secure delivery",
        )

        // Close current connection and retry without TLS
        client.Close()
        return e.deliverToHostWithTLS(ctx, addr, hostname, msg, data, false)
      }
    } else if e.config.RequireTLS {
      return fmt.Errorf("STARTTLS required but not supported by server")
    }
  }

  // ... delivery logic ...
}

Security Trade-offs

TLS Fallback Strategy: Handling Misconfigured Servers

Graceful Degradation

When encountering misconfigured servers (expired certificates, mismatched hostnames, etc.), the delivery engine implements a fallback strategy:

1. First attempt: Try TLS with verification enabled
2. On failure: Log security warning and retry without verification if RequireTLS=false
3. On persistent failure: Fall back to plaintext delivery if RequireTLS=false

Configuration Recommendations

# Production settings for sensitive mail
delivery:
  require_tls: true
  verify_tls: true

# Production settings for general delivery
delivery:
  require_tls: false
  verify_tls: true

# Development/testing only (never use in production)
delivery:
  require_tls: false
  verify_tls: false

Monitoring TLS Failures

The delivery engine logs security warnings for TLS failures:

// @filename: main.go
e.logger.WarnContext(ctx, "SECURITY: STARTTLS failed, falling back to plaintext - potential downgrade attack",
  "error", err,
  "hostname", hostname,
  "recommendation", "set RequireTLS=true for secure delivery",
)

These warnings should be monitored in production to identify:

• Domains with misconfigured TLS
• Potential man-in-the-middle attacks
• Certificate expiration issues

Certificate Monitoring: Health Checks and Renewal Tracking

Built-in Health Checks

The TLS manager exposes health check endpoints:

// @filename: main.go
// internal/security/tls.go
func (m *TLSManager) HasTLS() bool {
  return m.tlsConfig != nil
}

Certificate Verification

The setup wizard includes TLS certificate validation:

// @filename: handlers.go
// internal/setup/doctor.go
func checkTLSCertificates(cfg *config.Config) CheckResult {
  certFile := cfg.TLS.CertFile
  keyFile := cfg.TLS.KeyFile

  if certFile == "" || keyFile == "" {
    return CheckResult{
      Name:    "TLS Certificates",
      Status:  StatusWarning,
      Message: "TLS not configured",
      Help:    "Configure tls.cert_file and tls.key_file",
    }
  }

  // Load and validate certificate
  cert, err := tls.LoadX509KeyPair(certFile, keyFile)
  if err != nil {
    return CheckResult{
      Name:    "TLS Certificates",
      Status:  StatusError,
      Message: fmt.Sprintf("Failed to load certificate: %v", err),
      Help:    "Ensure cert and key files are valid and accessible",
    }
  }

  // Check expiration
  if cert.Leaf.NotAfter.Before(time.Now().Add(30 * 24 * time.Hour)) {
    return CheckResult{
      Name:    "TLS Certificates",
      Status:  StatusWarning,
      Message: fmt.Sprintf("Certificate expires soon: %v", cert.Leaf.NotAfter),
      Help:    "Renew certificate or use AutoTLS with Let's Encrypt",
    }
  }

  return CheckResult{
    Name:    "TLS Certificates",
    Status:  StatusOK,
    Message: "Certificate valid until " + cert.Leaf.NotAfter.Format(time.RFC3339),
  }
}

Automatic Renewal with Let’s Encrypt

The autocert.Manager handles automatic certificate renewal:

// @filename: main.go
manager.certManager = &autocert.Manager{
  Prompt:     autocert.AcceptTOS,
  HostPolicy: autocert.HostWhitelist(cfg.Server.Hostname),
  Cache:      autocert.DirCache(cfg.TLS.CacheDir),
  Email:      cfg.TLS.Email,
}

Renewal timeline:

• Certificates renewed ~30 days before expiration
• Background goroutine checks renewal status
• Failed renewals are retried with exponential backoff
• Caching prevents unnecessary ACME challenges

Monitoring Certificate Status

Use the health endpoints to monitor certificate status:

# @filename: script.sh
# Check overall health
curl http://localhost:8080/health

# Detailed health check includes certificate information
curl http://localhost:8080/health/detailed

Security Best Practices for Password Storage

Never Store Plaintext Passwords

Always use a memory-hard password hashing algorithm like Argon2id. Plaintext storage is a complete security failure.

Use Unique Salts Per Password

The implementation generates a unique 16-byte salt for each password:

// @filename: main.go
salt := make([]byte, argon2SaltLen)
if _, err := rand.Read(salt); err != nil {
  return "", fmt.Errorf("failed to generate salt: %w", err}

Salts prevent:

• Rainbow table attacks
• Identical passwords hashing to the same value
• Attackers from pre-computing hash tables

Use Constant-Time Comparisons

Always use constant-time comparison when verifying passwords:

return subtle.ConstantTimeCompare(hash, computedHash) == 1

Implement Account Lockout

Rate limiting and account lockout prevent brute force attacks:

• 10 failed attempts within 1 hour triggers 30-minute lockout
• Dummy comparisons prevent timing-based enumeration
• Lockouts automatically expire

Validate Passwords

Following NIST SP 800-63B recommendations:

• Minimum 8 characters
• No arbitrary complexity requirements
• No rotation requirements (NIST explicitly discourages this)

Never Log Passwords

The implementation never logs passwords or password hashes. Log entries only contain:

• Authentication success/failure
• Timestamps
• Remote addresses
• Protocol information

Use Secure Random Number Generation

Cryptographically secure random number generation is essential for salts:

// @filename: main.go
salt := make([]byte, argon2SaltLen)
if _, err := rand.Read(salt); err != nil {
  return "", fmt.Errorf("failed to generate salt: %w", err)
}

Performance Impact of Argon2id

Hashing Performance

On a typical 4-core system:

Comparison with Other Algorithms

Key insight: While bcrypt takes longer to hash, its low memory requirements make GPU attacks much cheaper. Argon2id’s memory-hard nature provides superior protection at a reasonable performance cost.

Impact on User Experience

With OWASP-recommended parameters:

• Login delay: ~100ms (imperceptible to users)
• Registration delay: ~100ms (one-time cost)
• Authentication throughput: ~10 logins/second/core

For high-traffic applications, consider:

• Offloading authentication to separate service
• Using connection pooling for database lookups
• Implementing session caching to reduce repeated authentication

Conclusion

Security is not about choosing between security and usability—it’s about implementing both thoughtfully. The email-server project demonstrates production-ready security practices:

TLS Implementation:

• Automatic certificate management with Let’s Encrypt
• Secure cipher suite configuration
• Configurable certificate verification
• Graceful fallback for misconfigured servers

Password Security:

• OWASP-recommended Argon2id parameters
• Constant-time comparisons
• Account lockout mechanisms
• Timing-attack prevention

Monitoring and Observability:

• Health checks for certificate status
• Detailed logging of security events
• Built-in diagnostics and validation tools

These practices provide a strong security foundation while maintaining usability. The key is to:

1. Use standard, well-vetted libraries
2. Follow OWASP and industry best practices
3. Monitor and log security events
4. Design for graceful degradation
5. Test security assumptions with automated tools

By implementing these practices, you can build systems that protect user credentials without sacrificing performance or user experience.

Further Reading

• OWASP Password Storage Cheat Sheet
• Argon2 RFC
• Let’s Encrypt Integration Guide
• NIST SP 800-63B
• Go crypto/subtle documentation