HTTPS and TLS Explained: How Secure Connections Actually Work

// io.thecodeforge: TLS 1.3 vs TLS 1.2 Handshake Comparison
// Annotated step by step — each arrow shows direction and content

// ============================================================
// TLS 1.3 — 1 RTT (1 round trip before application data flows)
// ============================================================

Client                                              Server
  |
  |--- ClientHello --------------------------------->|
  |    [Max TLS version: 1.3]                        |
  |    [Supported cipher suites]                     |
  |    [Client's ephemeral DH key share]             |
  |    [Supported signature algorithms]              |
  |                                                  |
  |<-- ServerHello + Certificate + Finished ---------|  <- All in ONE flight
  |    [Chosen TLS version: 1.3]                     |
  |    [Chosen cipher: AES-256-GCM-SHA384]           |
  |    [Server's ephemeral DH key share]             |
  |    [Certificate chain (leaf + intermediates)]    |
  |    [CertificateVerify: proof of private key]     |
  |    [Finished: encrypted with derived keys]       |
  |                                                  |
  // Both sides now independently compute shared secret:
  // shared_secret = DH(client_private, server_public)
  //               = DH(server_private, client_public)
  // The secret NEVER crosses the wire.
  |
  |--- Finished (encrypted) ------------------------>|
  |
  |=== Application Data (encrypted with AES) ======>|
  //
  // Total: 1 RTT. On a 100ms link: 100ms before data flows.


// ============================================================
// TLS 1.2 — 2 RTT (2 round trips before application data flows)
// ============================================================

Client                                              Server
  |
  |--- ClientHello --------------------------------->|  // RTT 1 begins
  |    [Max TLS version: 1.2]                        |
  |    [Supported cipher suites]                     |
  |    [Random value]                                |
  |                                                  |
  |<-- ServerHello + Certificate + ServerHelloDone --|  // RTT 1 ends
  |    [Chosen cipher suite]                         |
  |    [Server certificate]                          |
  |    [Server random value]                         |
  |                                                  |
  // Client verifies certificate, THEN begins key exchange
  |
  |--- ClientKeyExchange + ChangeCipherSpec -------->|  // RTT 2 begins
  |    [Encrypted pre-master secret or DH value]     |
  |--- Finished ------------------------------------->|
  |                                                  |
  |<-- ChangeCipherSpec + Finished ------------------|  // RTT 2 ends
  |
  |=== Application Data (encrypted) ===============>|
  //
  // Total: 2 RTT. On a 100ms link: 200ms before data flows.
  // On a 200ms link (cross-region): 400ms — measurable latency penalty.

#!/bin/bash
# io.thecodeforge: Certificate Health & Expiry Audit Script
# Run this after every certificate renewal and server migration
# to verify the certificate is valid, the chain is complete,
# and the expiry date is what you expect.

TARGET_DOMAIN="${1:-thecodeforge.io}"
TARGET_PORT="${2:-443}"
WARN_DAYS=30  # Alert threshold: warn if expiry within this many days

echo "=== TLS Certificate Audit: ${TARGET_DOMAIN}:${TARGET_PORT} ==="
echo

# Step 1: Verify the server is reachable and TLS handshakes succeed
if ! echo | openssl s_client -connect "${TARGET_DOMAIN}:${TARGET_PORT}" \
    -servername "${TARGET_DOMAIN}" </dev/null 2>/dev/null | \
    grep -q 'Verify return code: 0'; then
  echo "ERROR: TLS verification failed — certificate may be invalid, expired, or chain incomplete"
  # Show the actual verification error for diagnosis
  echo | openssl s_client -connect "${TARGET_DOMAIN}:${TARGET_PORT}" \
    -servername "${TARGET_DOMAIN}" 2>&1 | grep 'Verify return code'
  exit 1
fi

# Step 2: Extract and display primary certificate fields
echo "--- Certificate Identity ---"
echo | openssl s_client \
  -connect "${TARGET_DOMAIN}:${TARGET_PORT}" \
  -servername "${TARGET_DOMAIN}" \
  </dev/null 2>/dev/null \
  | openssl x509 -noout -text \
  | grep -A2 -E 'Issuer:|Subject:|Not Before|Not After|DNS:'

# Step 3: Count certificates in the chain
# Should be at least 2: leaf + at least one intermediate
# If only 1, non-browser clients will fail to verify the chain
CHAIN_COUNT=$(echo | openssl s_client \
  -connect "${TARGET_DOMAIN}:${TARGET_PORT}" \
  -showcerts \
  </dev/null 2>/dev/null \
  | grep -c 'BEGIN CERTIFICATE')

echo
echo "--- Chain Depth ---"
echo "Certificates in chain: ${CHAIN_COUNT}"
if [ "${CHAIN_COUNT}" -lt 2 ]; then
  echo "WARNING: Incomplete chain — non-browser clients (curl, Go, Java, mobile) will fail"
  echo "Fix: use fullchain.pem instead of cert.pem in ssl_certificate directive"
else
  echo "OK: Full chain served"
fi

# Step 4: Calculate days remaining until expiry
EXPIRY_DATE=$(echo | openssl s_client \
  -connect "${TARGET_DOMAIN}:${TARGET_PORT}" \
  -servername "${TARGET_DOMAIN}" \
  </dev/null 2>/dev/null \
  | openssl x509 -noout -enddate \
  | cut -d= -f2)

# Handle both GNU date (Linux) and BSD date (macOS)
EXPIRY_EPOCH=$(date -d "${EXPIRY_DATE}" +%s 2>/dev/null || \
               date -j -f "%b %d %T %Y %Z" "${EXPIRY_DATE}" +%s)
NOW_EPOCH=$(date +%s)
DAYS_LEFT=$(( (EXPIRY_EPOCH - NOW_EPOCH) / 86400 ))

echo
echo "--- Expiry Status ---"
echo "Certificate expires: ${EXPIRY_DATE}"
echo "Days remaining: ${DAYS_LEFT}"

if [ "${DAYS_LEFT}" -lt 0 ]; then
  echo "CRITICAL: Certificate has EXPIRED — all clients are failing right now"
  exit 2
elif [ "${DAYS_LEFT}" -lt 7 ]; then
  echo "CRITICAL: Certificate expires in ${DAYS_LEFT} days — renew immediately"
  exit 2
elif [ "${DAYS_LEFT}" -lt ${WARN_DAYS} ]; then
  echo "WARNING: Certificate expires in ${DAYS_LEFT} days — schedule renewal"
  exit 1
else
  echo "OK: Certificate is healthy"
fi

# io.thecodeforge: Diffie-Hellman Key Exchange — Conceptual Implementation
#
# This demonstrates the mathematical principle behind DH key exchange.
# Real TLS uses ECDHE with 256-bit+ elliptic curve parameters — the small
# numbers here are for readability only. Never use this code for actual
# cryptography.
#
# The key insight: both parties compute the SAME shared secret
# using ONLY values that were transmitted publicly.
# An observer who captured the entire exchange still cannot derive the secret.

# Agreed public parameters — both sides know these, anyone watching knows these
PRIME = 23      # p: a large prime in real implementations
GENERATOR = 5   # g: a primitive root modulo p

print(f"Public parameters: prime={PRIME}, generator={GENERATOR}")
print()

# Browser generates a private key (random, never shared)
browser_private = 6
browser_public = pow(GENERATOR, browser_private, PRIME)  # g^a mod p
print(f"Browser private key (never transmitted): {browser_private}")
print(f"Browser public key (sent in ClientHello): {browser_public}")
print()

# Server generates its own private key (random, never shared)
server_private = 15
server_public = pow(GENERATOR, server_private, PRIME)    # g^b mod p
print(f"Server private key (never transmitted): {server_private}")
print(f"Server public key (sent in ServerHello): {server_public}")
print()

# Each side computes the shared secret using the OTHER side's public key
# and their OWN private key
browser_shared = pow(server_public, browser_private, PRIME)  # (g^b)^a mod p
server_shared  = pow(browser_public, server_private, PRIME)  # (g^a)^b mod p

print(f"Browser computes shared secret: {browser_shared}")
print(f"Server computes shared secret:  {server_shared}")
print(f"Shared secrets match: {browser_shared == server_shared}")
print()

# What an attacker sees from the wire:
print("What a network observer captured:")
print(f"  Public parameters: prime={PRIME}, generator={GENERATOR}")
print(f"  Browser's public value: {browser_public}")
print(f"  Server's public value: {server_public}")
print(f"  Attacker can see both public values — but CANNOT compute {browser_shared}")
print(f"  To do so requires solving the discrete logarithm problem.")
print()
print("This shared secret becomes the seed for deriving AES session keys.")
print("All subsequent application data is encrypted with those symmetric keys.")

package io.thecodeforge.security;

import org.apache.hc.client5.http.impl.classic.CloseableHttpClient;
import org.apache.hc.client5.http.impl.classic.HttpClients;
import org.apache.hc.client5.http.impl.io.PoolingHttpClientConnectionManagerBuilder;
import org.apache.hc.client5.http.ssl.SSLConnectionSocketFactoryBuilder;
import org.apache.hc.core5.ssl.SSLContexts;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.client.HttpComponentsClientHttpRequestFactory;
import org.springframework.web.client.RestTemplate;

import javax.net.ssl.SSLContext;
import java.io.File;
import java.security.KeyStore;
import java.security.KeyManagementException;
import java.security.KeyStoreException;
import java.security.NoSuchAlgorithmException;

/**
 * io.thecodeforge: RestTemplate configured with a custom SSL context.
 *
 * Use this when:
 * - Calling internal services that use a private/internal CA
 * - Configuring mTLS (both client and server present certificates)
 * - The default JVM trust store does not include the target server's CA
 *
 * NEVER deploy TrustAllStrategy to production.
 * It disables certificate verification entirely — any MITM can intercept
 * traffic and the client will not detect it. Use a specific trust store.
 */
@Configuration
public class SslClientConfig {

    @Value("${tls.truststore.path}")
    private String trustStorePath;

    @Value("${tls.truststore.password}")
    private char[] trustStorePassword;

    /**
     * Production-safe RestTemplate bean with custom trust store.
     *
     * Loads the specified PKCS12 or JKS trust store containing only
     * the internal CA certificate(s). The JVM will reject connections
     * to any server whose certificate is not signed by a CA in this store.
     *
     * For mTLS: also call .loadKeyMaterial() on the SSLContextBuilder
     * to configure the client's own certificate and private key.
     */
    @Bean
    public RestTemplate forgeRestTemplate()
            throws Exception {

        // Load the specific trust store — production version
        // Replace this with .loadTrustMaterial(null, new TrustAllStrategy())
        // ONLY for local development and never commit to main
        KeyStore trustStore = KeyStore.getInstance("PKCS12");
        try (var is = new java.io.FileInputStream(trustStorePath)) {
            trustStore.load(is, trustStorePassword);
        }

        SSLContext sslContext = SSLContexts.custom()
                .loadTrustMaterial(trustStore, null)  // null = no additional trust condition
                .build();

        // For mTLS, add client certificate loading:
        // .loadKeyMaterial(keyStore, keyPassword)
        // The server will verify this certificate against its own trust store

        CloseableHttpClient httpClient = HttpClients.custom()
                .setConnectionManager(
                    PoolingHttpClientConnectionManagerBuilder.create()
                        .setSSLSocketFactory(
                            SSLConnectionSocketFactoryBuilder.create()
                                .setSslContext(sslContext)
                                // Enforce hostname verification — never disable this
                                // NoopHostnameVerifier would accept any hostname,
                                // re-introducing MITM vulnerability
                                .build()
                        )
                        .build()
                )
                .build();

        HttpComponentsClientHttpRequestFactory factory =
            new HttpComponentsClientHttpRequestFactory(httpClient);

        // Set reasonable timeouts — unset timeouts cause thread pool exhaustion
        // on slow TLS peers
        factory.setConnectTimeout(5000);    // 5s connection timeout
        factory.setReadTimeout(30000);      // 30s read timeout

        return new RestTemplate(factory);
    }
}

# io.thecodeforge: Hardened Nginx TLS Configuration
# Target: A+ rating on SSL Labs, TLS 1.2/1.3 only, PFS mandatory
#
# Before using this config:
# 1. Replace thecodeforge.io with your actual domain
# 2. Verify /etc/letsencrypt/live/thecodeforge.io/ exists with valid certs
# 3. Generate DH parameters: openssl dhparam -out /etc/nginx/dhparam.pem 2048
# 4. Test config: nginx -t before reloading

# Redirect all HTTP traffic to HTTPS
# This ensures no plaintext connections reach the application
server {
    listen 80;
    listen [::]:80;
    server_name thecodeforge.io www.thecodeforge.io;

    # Return 301 (permanent redirect) to HTTPS
    # Use 301 (not 302) so browsers cache the redirect
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name thecodeforge.io www.thecodeforge.io;

    # Certificate configuration
    # ssl_certificate MUST use fullchain.pem — includes leaf + intermediates
    # cert.pem (leaf only) breaks non-browser clients
    ssl_certificate     /etc/letsencrypt/live/thecodeforge.io/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/thecodeforge.io/privkey.pem;

    # Protocol restriction: TLS 1.2 minimum, TLS 1.3 preferred
    # TLS 1.0 and 1.1 are deprecated by RFC 8996 — disable them
    ssl_protocols TLSv1.2 TLSv1.3;

    # Cipher suite selection for TLS 1.2
    # All ECDHE (forward secrecy) + GCM (authenticated encryption)
    # No CBC (BEAST/POODLE/Lucky13 vulnerable), no RC4 (broken), no 3DES (Sweet32)
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers on;

    # TLS 1.3 cipher suites are configured separately in OpenSSL
    # and are all AEAD — no additional configuration needed

    # DH parameters for TLS 1.2 DHE cipher suites
    # Generate with: openssl dhparam -out /etc/nginx/dhparam.pem 2048
    ssl_dhparam /etc/nginx/dhparam.pem;

    # Session resumption: reduces handshake overhead for returning clients
    # Rotate ssl_session_ticket_key periodically for forward secrecy
    ssl_session_timeout 1d;
    ssl_session_cache shared:ForgeSSL:10m;  # ~40,000 sessions
    ssl_session_tickets off;  # Tickets have forward secrecy implications

    # OCSP Stapling: server pre-fetches revocation status from CA
    # Eliminates client round trip to CA's OCSP responder
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_trusted_certificate /etc/letsencrypt/live/thecodeforge.io/chain.pem;
    resolver 8.8.8.8 8.8.4.4 valid=300s;
    resolver_timeout 5s;

    # ---- Security Headers ----

    # HSTS: tell browsers to always use HTTPS for this domain
    # max-age=31536000 = 1 year
    # includeSubDomains: applies to all subdomains
    # preload: eligible for browser built-in HSTS list (submit at hstspreload.org)
    # WARNING: preload is permanent — only add when you control the domain long-term
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;

    # Prevent browsers from rendering this site in a frame (clickjacking)
    add_header X-Frame-Options DENY always;

    # Prevent MIME-type sniffing on script/style responses
    add_header X-Content-Type-Options nosniff always;

    # Basic CSP — restrict script sources to same origin
    # Tighten further based on your application's actual script sources
    add_header Content-Security-Policy "default-src 'self'; script-src 'self'; object-src 'none'" always;

    # Referrer Policy: limit URL leakage in cross-origin requests
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # Upstream application — plaintext inside the private Docker network
    location / {
        proxy_pass http://app_backend:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# io.thecodeforge: Production TLS Termination Proxy
# Pattern: Nginx Alpine as TLS edge proxy
# Certificates mounted as volumes — never baked into the image
#
# Usage:
#   docker build -t thecodeforge/tls-proxy:latest .
#   docker run -d \
#     -p 80:80 -p 443:443 \
#     -v /etc/letsencrypt:/etc/letsencrypt:ro \
#     -v /etc/nginx/dhparam.pem:/etc/nginx/dhparam.pem:ro \
#     --network app_network \
#     thecodeforge/tls-proxy:latest

FROM nginx:1.27-alpine

# Alpine base: ~40MB vs ~180MB for nginx:stable (Debian)
# Smaller attack surface: no package manager, fewer utilities available
# to an attacker who achieves code execution

# Remove default config — prevents Nginx from starting with insecure defaults
# if our config fails to load for any reason
RUN rm /etc/nginx/conf.d/default.conf

# Copy hardened TLS configuration
COPY secure_nginx_tls.conf /etc/nginx/conf.d/thecodeforge.conf

# Validate config at build time — fail the build if config has syntax errors
# This catches missing directives before the image is pushed
RUN nginx -t

# Create certificate mount point
# Actual certs are mounted as a read-only volume at runtime
# Never COPY certs into the image — they expire and cannot be renewed
# without rebuilding the image
RUN mkdir -p /etc/letsencrypt

# Expose only the ports this proxy uses
EXPOSE 80 443

# exec form: nginx is PID 1 and receives SIGTERM directly for graceful shutdown
# shell form (/bin/sh -c) would make sh PID 1, which may not forward signals
CMD ["nginx", "-g", "daemon off;"]