Introduction

Concurrent programming in Java requires careful management of shared resources. The Java platform provides multiple synchronization mechanisms to prevent data races and ensure thread safety. This blog post explores the nuances of intrinsic locks, ReentrantLock, ReadWriteLock, Semaphore, and other synchronization primitives, helping you choose the right tool for your specific use case.

Table of Contents

1. Intrinsic Locks (synchronized)
2. ReentrantLock
3. ReadWriteLock
4. ReentrantReadWriteLock
5. Semaphore
6. StampedLock
7. CountDownLatch
8. CyclicBarrier
9. Phaser
10. Comparison Table
11. Best Practices

Intrinsic Locks {#intrinsic-locks}

Overview

Intrinsic locks (also called monitor locks) are the synchronization mechanism built into the Java language itself. Every object in Java has an associated lock that is automatically managed by the JVM.

Usage

public class Counter {
    private int count = 0;

    // Synchronize on the instance
    public synchronized void increment() {
        count++;
    }

    // Synchronize on a specific object
    public void incrementSafe() {
        synchronized(this) {
            count++;
        }
    }
}

Characteristics

• Automatic Release: Locks are automatically released when exiting a synchronized block
• Reentrancy: The same thread can acquire the same lock multiple times
• No Timeout: Cannot timeout waiting for a lock
• Simple: Easy to use and understand
• JVM Optimizations: Subject to optimization (biased locking, lock coarsening)

Advantages

✅ Simple and straightforward syntax
✅ Automatically released (no risk of forgetting to unlock)
✅ Reentrant by default
✅ Efficient for uncontended locks

Disadvantages

❌ Cannot check if lock is available without attempting to acquire it
❌ No timeout support
❌ Must use nested synchronized blocks for multiple locks (deadlock risk)
❌ Less flexible than explicit locks

Example

public class BankAccount {
    private double balance = 0;

    public synchronized void deposit(double amount) {
        balance += amount;
    }

    public synchronized void withdraw(double amount) {
        balance -= amount;
    }

    public synchronized double getBalance() {
        return balance;
    }
}

ReentrantLock {#reentrantlock}

Overview

ReentrantLock is an explicit implementation of the Lock interface that provides similar functionality to intrinsic locks but with additional features and flexibility.

Usage

import java.util.concurrent.locks.ReentrantLock;
import java.util.concurrent.locks.Lock;

public class Counter {
    private int count = 0;
    private final Lock lock = new ReentrantLock();

    public void increment() {
        lock.lock();
        try {
            count++;
        } finally {
            lock.unlock();
        }
    }
}

Characteristics

• Explicit Control: Manual lock and unlock
• Reentrancy: Same thread can acquire multiple times
• Fairness: Optional fair queuing policy (FIFO)
• Timeout Support: Can timeout waiting for lock
• Interruptible: Can be interrupted while waiting
• Try Lock: Can attempt non-blocking lock acquisition

Advantages

✅ Supports timeout with tryLock(long, TimeUnit)
✅ Interruptible via lockInterruptibly()
✅ Can check lock status with tryLock()
✅ Fair scheduling option available
✅ Works with Conditions for advanced synchronization

Disadvantages

❌ Manual unlock required (easy to forget)
❌ More verbose than synchronized
❌ Slightly higher overhead than intrinsic locks

Example

import java.util.concurrent.TimeUnit;
import java.util.concurrent.locks.ReentrantLock;

public class TimedLockExample {
    private final ReentrantLock lock = new ReentrantLock();
    private int value = 0;

    public void updateValue(int newValue) throws InterruptedException {
        if (lock.tryLock(5, TimeUnit.SECONDS)) {
            try {
                value = newValue;
                System.out.println("Value updated to: " + newValue);
            } finally {
                lock.unlock();
            }
        } else {
            System.out.println("Could not acquire lock within timeout");
        }
    }

    public void interruptibleUpdate(int newValue) throws InterruptedException {
        lock.lockInterruptibly();
        try {
            value = newValue;
        } finally {
            lock.unlock();
        }
    }
}

ReadWriteLock {#readwritelock}

Overview

ReadWriteLock maintains a pair of locks: one for read access and one for write access. Multiple threads can hold the read lock simultaneously, but only one thread can hold the write lock.

Characteristics

• Concurrent Reads: Multiple threads can read simultaneously
• Exclusive Writes: Only one thread can write, and no reads happen during writes
• Improved Throughput: Better performance when reads greatly outnumber writes
• Read-Write Lock Semantics: Readers don't block each other

Usage

import java.util.concurrent.locks.ReadWriteLock;
import java.util.concurrent.locks.ReentrantReadWriteLock;

public class DataCache {
    private String data = "";
    private final ReadWriteLock rwLock = new ReentrantReadWriteLock();

    public String getData() {
        rwLock.readLock().lock();
        try {
            return data;
        } finally {
            rwLock.readLock().unlock();
        }
    }

    public void setData(String newData) {
        rwLock.writeLock().lock();
        try {
            data = newData;
        } finally {
            rwLock.writeLock().unlock();
        }
    }
}

Advantages

✅ Excellent for read-heavy workloads
✅ Multiple concurrent readers
✅ Exclusive write access
✅ Prevents writer starvation

Disadvantages

❌ More overhead than simple locks
❌ Not beneficial when reads and writes are balanced
❌ More complex to understand and use

ReentrantReadWriteLock {#reentrantreadwritelock}

Overview

ReentrantReadWriteLock is the standard implementation of ReadWriteLock in Java. It provides reentrancy for both read and write locks with optional fairness.

Example

import java.util.concurrent.locks.ReentrantReadWriteLock;

public class CachedData {
    private String value = "";
    private final ReentrantReadWriteLock lock = new ReentrantReadWriteLock();

    public String getValue() {
        lock.readLock().lock();
        try {
            return value;
        } finally {
            lock.readLock().unlock();
        }
    }

    public void setValue(String newValue) {
        lock.writeLock().lock();
        try {
            value = newValue;
        } finally {
            lock.writeLock().unlock();
        }
    }

    // Downgrade write lock to read lock
    public void processData() {
        lock.writeLock().lock();
        try {
            // Perform write operation
            value = "processed";

            // Acquire read lock before releasing write lock (downgrade)
            lock.readLock().lock();
        } finally {
            lock.writeLock().unlock();
        }

        try {
            // Now we only hold the read lock
            System.out.println("Current value: " + value);
        } finally {
            lock.readLock().unlock();
        }
    }
}

Semaphore {#semaphore}

Overview

A Semaphore maintains a set of permits. Threads call acquire() to wait for a permit and release() to release one. When no permits are available, acquire() blocks the thread.

Characteristics

• Permit-Based: Controls access through a pool of permits
• Resource Pooling: Useful for limiting concurrent access to a resource pool
• Counting Semaphore: Maintains a count of permits
• Binary Semaphore: Acts as a lock when permit count = 1
• Non-Reentrant: By default, doesn't allow the same thread to acquire twice

Usage

import java.util.concurrent.Semaphore;

public class ConnectionPool {
    private final Semaphore semaphore = new Semaphore(5); // 5 connections available

    public void executeTask() throws InterruptedException {
        semaphore.acquire(); // Wait for a permit
        try {
            System.out.println("Executing task with connection");
            // Simulate work
            Thread.sleep(1000);
        } finally {
            semaphore.release(); // Release the permit
        }
    }
}

Advantages

✅ Excellent for resource pooling
✅ Simple counting mechanism
✅ Can be used as a binary lock (Mutex)
✅ Supports timeout with tryAcquire(long, TimeUnit)

Disadvantages

❌ Not reentrant (unless you track permits manually)
❌ Less intuitive than locks for mutual exclusion
❌ No condition variables

Binary Semaphore (Mutex)

import java.util.concurrent.Semaphore;

public class MutexExample {
    private final Semaphore mutex = new Semaphore(1); // Binary semaphore
    private int counter = 0;

    public void incrementCounter() throws InterruptedException {
        mutex.acquire();
        try {
            counter++;
        } finally {
            mutex.release();
        }
    }
}

StampedLock {#stampedlock}

Overview

StampedLock is a high-performance lock introduced in Java 8 that provides three modes: write lock, read lock, and optimistic read. The optimistic read mode doesn't acquire a lock at all but checks a "stamp" to detect conflicts.

Characteristics

• Optimistic Reading: Can read without acquiring a lock
• Stamp-Based Validation: Uses stamps to detect write conflicts
• High Performance: Designed for low-contention scenarios
• Three Modes: Optimistic read, pessimistic read, write
• Non-Reentrant: Cannot be reacquired by the same thread

Usage

import java.util.concurrent.locks.StampedLock;

public class OptimizedData {
    private int value = 0;
    private final StampedLock lock = new StampedLock();

    // Optimistic read - fast path
    public int readOptimistic() {
        long stamp = lock.tryOptimisticRead();
        int result = value;

        if (!lock.validate(stamp)) {
            // Conflict detected, fall back to pessimistic read
            stamp = lock.readLock();
            try {
                result = value;
            } finally {
                lock.unlockRead(stamp);
            }
        }
        return result;
    }

    // Pessimistic read
    public int readPessimistic() {
        long stamp = lock.readLock();
        try {
            return value;
        } finally {
            lock.unlockRead(stamp);
        }
    }

    // Write lock
    public void write(int newValue) {
        long stamp = lock.writeLock();
        try {
            value = newValue;
        } finally {
            lock.unlockWrite(stamp);
        }
    }
}

Advantages

✅ Excellent performance for read-heavy, low-contention scenarios
✅ Optimistic read avoids blocking
✅ Lower overhead than ReentrantReadWriteLock

Disadvantages

❌ Not reentrant
❌ More complex API
❌ Should only be used when you understand the implications
❌ Optimistic reads can fail (need validation logic)

CountDownLatch {#countdownlatch}

Overview

CountDownLatch is a synchronization aid that allows one or more threads to wait until a set of operations being performed in other threads completes.

Characteristics

• One-Time Use: Cannot be reset once count reaches zero
• Countdown Mechanism: Count decrements with each countDown() call
• Blocking Wait: await() blocks until count reaches zero
• Simple Coordination: Good for one-off synchronization

Usage

import java.util.concurrent.CountDownLatch;

public class ParallelProcessing {
    public static void main(String[] args) throws InterruptedException {
        int numWorkers = 3;
        CountDownLatch latch = new CountDownLatch(numWorkers);

        for (int i = 0; i < numWorkers; i++) {
            new Thread(() -> {
                System.out.println(Thread.currentThread().getName() + " is working");
                try {
                    Thread.sleep(2000);
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();
                }
                System.out.println(Thread.currentThread().getName() + " finished");
                latch.countDown();
            }).start();
        }

        latch.await(); // Wait for all workers to finish
        System.out.println("All workers completed!");
    }
}

Advantages

✅ Simple and intuitive for one-off synchronization
✅ Lightweight and efficient
✅ Supports timeout with await(long, TimeUnit)

Disadvantages

❌ Cannot be reused (count cannot be reset)
❌ Only useful for one-time events
❌ Not suitable for repeating synchronization

CyclicBarrier {#cyclicbarrier}

Overview

CyclicBarrier allows a fixed number of parties to wait for each other at a barrier point. Unlike CountDownLatch, it can be reused.

Characteristics

• Reusable: Can be used multiple times (cyclic)
• Mutual Waiting: All threads wait for each other
• Barrier Action: Optional action executed when all parties arrive
• Fixed Number of Parties: Number of threads must be known upfront

Usage

import java.util.concurrent.CyclicBarrier;

public class BarrierExample {
    public static void main(String[] args) {
        int numThreads = 3;
        CyclicBarrier barrier = new CyclicBarrier(numThreads, () -> {
            System.out.println("All threads have reached the barrier!");
        });

        for (int i = 0; i < numThreads; i++) {
            new Thread(() -> {
                try {
                    System.out.println(Thread.currentThread().getName() + " is working");
                    Thread.sleep((long)(Math.random() * 3000));
                    System.out.println(Thread.currentThread().getName() + " reached barrier");
                    barrier.await(); // Wait for others
                    System.out.println(Thread.currentThread().getName() + " passed barrier");
                } catch (Exception e) {
                    e.printStackTrace();
                }
            }).start();
        }
    }
}

Advantages

✅ Reusable (cyclic)
✅ Symmetric - all threads wait for each other
✅ Optional barrier action supports coordinated tasks
✅ Good for iterative synchronization

Disadvantages

❌ All threads must wait (no timeout)
❌ Breaking the barrier (exception) may cause issues
❌ Less flexible than Phaser

Phaser {#phaser}

Overview

Phaser is a more flexible version of CyclicBarrier and CountDownLatch combined. It supports dynamic party registration and can be reused across multiple phases.

Characteristics

• Flexible Parties: Can dynamically register/deregister threads
• Multiple Phases: Can synchronize through multiple phases
• Phased Execution: Better control over multi-phase synchronization
• Timeout Support: Can timeout waiting for a phase to complete
• Terminal Phase: Can handle completion elegantly

Usage

import java.util.concurrent.Phaser;

public class PhaserExample {
    public static void main(String[] args) {
        Phaser phaser = new Phaser(1); // Register the main thread

        for (int i = 0; i < 3; i++) {
            phaser.register(); // Register each worker
            new Thread(() -> {
                for (int phase = 0; phase < 3; phase++) {
                    System.out.println(Thread.currentThread().getName() + 
                        " working on phase " + phase);
                    try {
                        Thread.sleep((long)(Math.random() * 2000));
                    } catch (InterruptedException e) {
                        Thread.currentThread().interrupt();
                    }
                    System.out.println(Thread.currentThread().getName() + 
                        " finished phase " + phase);
                    phaser.arriveAndAwaitAdvance(); // Move to next phase
                }
            }).start();
        }

        phaser.arriveAndAwaitAdvance(); // Advance from phase 0
        System.out.println("Phase 0 complete!");

        phaser.arriveAndAwaitAdvance(); // Advance from phase 1
        System.out.println("Phase 1 complete!");

        phaser.arriveAndAwaitAdvance(); // Advance from phase 2
        System.out.println("Phase 2 complete!");
    }
}

Advantages

✅ Dynamic party registration
✅ Multiple phases support
✅ Timeout support with awaitAdvanceInterruptibly()
✅ Elegant handling of completion
✅ Most flexible synchronization primitive

Disadvantages

❌ More complex API
❌ Slight overhead compared to simpler mechanisms
❌ Requires careful understanding of phase advancement

Comparison Table {#comparison-table}

Best Practices {#best-practices}

1. Choose the Right Tool

• Simple mutual exclusion: Use synchronized for simplicity
• Advanced locking needs: Use ReentrantLock for flexibility
• Read-heavy workloads: Use ReadWriteLock or StampedLock
• Resource pooling: Use Semaphore
• One-time coordination: Use CountDownLatch
• Iterative synchronization: Use CyclicBarrier
• Multi-phase synchronization: Use Phaser

2. Always Release Locks

Lock lock = new ReentrantLock();
lock.lock();
try {
    // Critical section
} finally {
    lock.unlock(); // Always execute in finally
}

3. Avoid Deadlocks

// ❌ BAD: Risk of deadlock with nested locks
lock1.lock();
lock2.lock();

// ✅ GOOD: Consistent lock ordering
if (lock1.getId() < lock2.getId()) {
    lock1.lock();
    lock2.lock();
} else {
    lock2.lock();
    lock1.lock();
}

4. Use Try-Finally or Try-With-Resources

// ✅ GOOD: Modern approach with try-with-resources (if available)
try (Locker locked = new Locker(lock)) {
    // Critical section
}

// ✅ GOOD: Traditional try-finally
lock.lock();
try {
    // Critical section
} finally {
    lock.unlock();
}

5. Consider High-Level Abstractions

// ❌ Low-level: Manual synchronization
// ✅ High-level: Collections.synchronizedList or ConcurrentHashMap
List<String> list = Collections.synchronizedList(new ArrayList<>());

6. Profile Before Optimizing

StampedLock and other advanced locks introduce complexity. Profile your application to ensure the performance gains justify the complexity.

// ❌ Premature optimization
private final StampedLock lock = new StampedLock(); // Might be overkill

// ✅ Thoughtful choice based on workload analysis
private final ReentrantReadWriteLock lock = new ReentrantReadWriteLock(); // Suitable for the workload

7. Document Lock Ordering

/**
 * Locks must be acquired in this order to prevent deadlocks:
 * 1. accountLock
 * 2. transactionLock
 */
public void transfer(Account from, Account to, double amount) {
    // Lock in documented order
}

8. Use java.util.concurrent Collections

// ✅ Preferred: Concurrent collections handle synchronization internally
Map<String, Integer> map = new ConcurrentHashMap<>();
List<String> list = new CopyOnWriteArrayList<>();
Queue<String> queue = new ConcurrentLinkedQueue<>();

Summary

Java provides multiple synchronization mechanisms, each suited for different scenarios:

• synchronized (Intrinsic Locks): Simple, built-in, suitable for basic synchronization
• ReentrantLock: Flexible, feature-rich alternative to synchronized with timeout and interruptibility
• ReadWriteLock: Optimized for read-heavy workloads with concurrent readers
• Semaphore: Perfect for resource pooling and limiting concurrent access
• StampedLock: High-performance option for low-contention scenarios with optimistic reads
• CountDownLatch: Simple one-time synchronization for waiting on completion
• CyclicBarrier: For reusable barrier points where threads wait for each other
• Phaser: Most flexible for multi-phase, dynamic synchronization scenarios

The key is understanding your workload and choosing the appropriate primitive that provides the necessary functionality with minimal complexity. In most cases, simple solutions like synchronized or the concurrent collections are sufficient and preferable.

Interactive Demos

This blog post comes with comprehensive, runnable demonstrations of each synchronization mechanism. Each demo includes:

• Real-world scenarios (bank accounts, caches, connection pools, pipelines, game rounds)
• Best practices with detailed comments
• Multiple example classes per synchronization type
• Performance comparisons where applicable
• Exception handling and timeout patterns

Demo Files

1. IntrinsicLockDemo - Bank accounts, thread-safe counters, and caches
2. ReentrantLockDemo - Timeout support, producer-consumer queues, and fair scheduling
3. ReadWriteLockDemo - Concurrent readers with performance comparison
4. SemaphoreDemo - Connection pooling, rate limiting, and thread pool control
5. StampedLockDemo - Optimistic reads with pessimistic fallback
6. CountDownLatchDemo - Parallel task execution and pipeline coordination
7. CyclicBarrierDemo - Iterative processing and game round synchronization
8. PhaserDemo - Multi-phase execution and dynamic party management

Running the Demos

Run the interactive launcher:

java info.mnafshin.locks_in_java.demos.DemoLauncher

Or run individual demos:

java info.mnafshin.locks_in_java.demos.IntrinsicLockDemo
java info.mnafshin.locks_in_java.demos.ReentrantLockDemo
java info.mnafshin.locks_in_java.demos.SemaphoreDemo
# ... etc

See DEMOS_README.md for detailed documentation and usage instructions for each demo.

Further Reading

• Java Concurrency in Practice (Book)
• Java API Documentation: java.util.concurrent package
• Oracle Java Tutorials on Concurrency

Get the Code

The source code for this project is available on GitHub: https://github.com/mnafshin/locks-in-java.git

Understanding SSL/TLS handshakes is crucial for debugging secure connections in Java applications. In this guide, I'll walk you through a real-world example of capturing and analyzing an SSL/TLS handshake using Java's built-in debugging capabilities.

This article covers:

• How to enable SSL/TLS debugging in Java
• Real handshake flow with detailed timing
• Complete working example with HttpURLConnection
• Step-by-step breakdown of the TLS 1.2 handshake

Enabling SSL/TLS Debug Output

To capture SSL/TLS debugging information, simply set this system property before establishing any connections:

System.setProperty("javax.net.debug", "all");

This enables comprehensive logging of:

• Cipher suite negotiation
• Certificate validation
• Handshake messages
• Raw bytes sent/received
• Session information

Real-World TLS 1.2 Handshake Flow

When you connect to an HTTPS endpoint (in our example: https://httpbin.org/get), the following handshake occurs:

ASCII Diagram: Complete TLS 1.2 Handshake

CLIENT (Java App)                           SERVER (httpbin.org)
════════════════════════════════════════════════════════════════

        ┌─────────────────────────────────┐
        │  1. ClientHello                 │
        │  (22:20:06.819 CET)             │
        │  - Ciphers, Extensions          │
        │  - Random value                 │
        └────────────────────┬────────────┘
                             │
                             │ [Raw write]
                             │ TLS 1.2 record
                             ├──────────────────────────────────>
                                                                │
                                           ┌────────────────────┘
                                           │
                                           ▼
                            ┌──────────────────────────────────┐
                            │  2. ServerHello                  │
                            │  (22:20:06.924 CET)              │
                            │  - Selected cipher suite:        │
                            │    TLS_ECDHE_RSA_WITH_AES_128... │
                            │  - Server random                 │
                            │  - Session ID                    │
                            └────────────────┬──────────────────┘
                                             │
                                             │ [Raw read]
        ┌────────────────────────────────────┤
        │                                     │
        ▼                                     ▼
┌──────────────────────────────┐  ┌──────────────────────────────────┐
│  3. Server Certificate       │  │  4. ServerKeyExchange (ECDH)     │
│  (22:20:06.930 CET)          │  │  (22:20:06.950 CET)              │
│  - Certificate chain:        │  │  - ECDH parameters               │
│    └─ httpbin.org            │  │  - Server's ECDH public key      │
│    └─ Amazon RSA 2048 M      │  │  - Signature                     │
│    └─ Root CA                │  │                                  │
└──────────────────────────────┘  └──────────────────────────────────┘
        │                                    │
        └────────────────────┬───────────────┘
                             │
                             ▼
                    ┌──────────────────────┐
                    │  5. ServerHelloDone  │
                    │  (22:20:06.951 CET)  │
                    └────────┬─────────────┘
                             │
                             │ [Raw read]
        ┌────────────────────┘
        │
        ▼
┌───────────────────────────────────────────┐
│  6. ClientKeyExchange (ECDHE)             │
│  (22:20:06.951 CET)                       │
│  - Client's ECDH public key               │
│  - Compute shared secret (PreMasterKey)   │
└────────────────┬────────────────────────────┐
                 │                            │
                 │ [Raw write]                │
                 │ TLS 1.2 handshake         │
                 ├───────────────────────────────────────────────>
                 │                            │
                 ▼                            │
┌────────────────────────────────────────┐   │
│  7. ChangeCipherSpec (Client)          │   │
│  (22:20:06.952 CET)                    │   │
│  - Switch to encrypted traffic         │   │
└────────────────┬─────────────────────────┐ │
                 │                          │ │
                 │ [Raw write]              │ │
                 │ TLS 1.2 change spec      │ │
                 ├──────────────────────────────>
                 │                          │ │
                 ▼                          │ │
┌────────────────────────────────────────┐   │
│  8. Finished (Client)                  │   │
│  (22:20:06.954 CET)                    │   │
│  - MAC of all handshake messages       │   │
│  - Encrypted with session key          │   │
└────────────────┬─────────────────────────┐ │
                 │                          │ │
                 │ [Raw write]              │ │
                 │ TLS 1.2 handshake       │ │
                 ├──────────────────────────────>
                 │                          │ │
                 │                          │ │
                 │                   ┌──────┘ │
                 │                   │        │
                 │                   ▼        ▼
                 │        ┌──────────────────────────────┐
                 │        │  9. NewSessionTicket         │
                 │        │  (22:20:07.056 CET)          │
                 │        │  - For session resumption    │
                 │        └────────┬─────────────────────┘
                 │                 │
                 │                 │ [Raw read]
        ┌────────┴─────────────────┤
        │                          │
        ▼                          ▼
┌──────────────────────┐  ┌────────────────────────────┐
│  10. ChangeCipherSpec│  │  11. Server Finished       │
│  (Server)            │  │  (22:20:07.056 CET)       │
│  (22:20:07.056 CET)  │  │  - MAC of all handshake   │
└──────────────────────┘  │  - Encrypted with key     │
                          └────────┬──────────────────┘
                                   │
                                   │ [Raw read]
                    ┌──────────────┘
                    │
                    ▼
        ┌───────────────────────────────┐
        │  ✓ HANDSHAKE COMPLETE        │
        │  (22:20:07.057 CET)          │
        │                              │
        │  Secure Channel Established  │
        │  - Ready for application     │
        │  - All data encrypted/MAC'd  │
        └───────────────────────────────┘

Handshake Timing & Summary

Negotiated Security Parameters

• Protocol Version: TLS 1.2
• Cipher Suite: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (0xC02F)
• Key Exchange: ECDHE (Elliptic Curve Diffie-Hellman Ephemeral)
• Encryption: AES-128-GCM
• Hash Algorithm: SHA256
• Server Certificate: httpbin.org (issued by Amazon RSA 2048 M)

Negotiated Extensions

• ✓ renegotiation_info - Controls renegotiation
• ✓ server_name - SNI (Server Name Indication)
• ✓ ec_point_formats - Supported EC point formats (uncompressed)
• ✓ extended_master_secret - Enhanced security
• ✓ session_ticket - Session resumption capability

Handshake Phase Breakdown

Phase 1: Key Exchange & Authentication

The client and server exchange their capabilities and parameters:

1. ClientHello → Client offers supported ciphers, TLS versions, and extensions
2. ServerHello → Server selects cipher, version, and confirms capabilities
3. Certificate → Server proves identity with certificate chain
4. ServerKeyExchange → Server sends ECDH parameters for key agreement
5. ServerHelloDone → Marks end of server's initial messages

Phase 2: Key Derivation

Both sides generate the shared secret:

6. ClientKeyExchange → Client sends ECDH public key
   • Both sides compute: PreMasterSecret = ECDH(client_key, server_key)
   • Both derive: MasterSecret = PRF(PreMasterSecret, "master secret", client_random || server_random)
   • Both generate session encryption/decryption keys

Phase 3: Cipher Activation & Verification

Both sides verify the handshake and activate encryption:

7. ChangeCipherSpec (Client) → "Start encrypting from now on"
8. Finished (Client) → Encrypted MAC of all handshake messages
9. NewSessionTicket (Server) → Optional ticket for future session resumption
10. ChangeCipherSpec (Server) → "Start encrypting from now on"
11. Finished (Server) → Encrypted MAC of all handshake messages

Phase 4: Secure Communication

Application data is now encrypted using the derived session keys.

Complete Working Example

Here's the complete Java code that produces the above handshake:

App.java - Main Application

/*
 * This source file was generated by the Gradle 'init' task
 */
package ssl.debug;

import ssl.debug.adapter.BasicHttpsClient;

public class App {

    BasicHttpsClient basicHttpsClient = new BasicHttpsClient();

    public String getGreeting() throws Exception {
        return basicHttpsClient.get("https://httpbin.org/get");
    }

    public String getSslInfo() throws Exception {
        return basicHttpsClient.getSSLInfo("https://httpbin.org/get");
    }

    public static void main(String[] args) throws Exception {
        System.setProperty("javax.net.debug", "all");
        App app = new App();
        System.out.println(app.getGreeting());
        System.out.println(app.getSslInfo());
    }
}

BasicHttpsClient.java - HTTPS Client Library

package ssl.debug.adapter;

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URI;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.Map;

/**
 * A simple HTTPS client for making secure HTTP requests.
 * Useful for demonstrating SSL/TLS handshake and debugging.
 */
public class BasicHttpsClient {

    private String userAgent = "Mozilla/5.0 (Java SSL Debug)";
    private int connectionTimeout = 10000; // 10 seconds
    private int readTimeout = 10000; // 10 seconds

    /**
     * Performs a GET request to the specified URL
     * 
     * @param urlString The HTTPS URL to connect to
     * @return The response body as a string
     * @throws Exception if connection fails
     */
    public String get(String urlString) throws Exception {
        return get(urlString, null);
    }

    /**
     * Performs a GET request with custom headers
     * 
     * @param urlString The HTTPS URL to connect to
     * @param headers Custom headers to send (can be null)
     * @return The response body as a string
     * @throws Exception if connection fails
     */
    public String get(String urlString, Map<String, String> headers) throws Exception {
        HttpURLConnection connection = null;
        try {
            URL url = new URI(urlString).toURL();
            connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("GET");
            connection.setConnectTimeout(connectionTimeout);
            connection.setReadTimeout(readTimeout);
            connection.setRequestProperty("User-Agent", userAgent);

            // Add custom headers if provided
            if (headers != null) {
                headers.forEach(connection::setRequestProperty);
            }

            int responseCode = connection.getResponseCode();
            String responseBody = readResponse(connection);

            System.out.println("Status Code: " + responseCode);
            System.out.println("Response Headers:");
            printHeaders(connection.getHeaderFields());

            return responseBody;

        } finally {
            if (connection != null) {
                connection.disconnect();
            }
        }
    }

    /**
     * Gets SSL/TLS information from the connection
     * 
     * @param urlString The HTTPS URL to connect to
     * @return SSL information as a formatted string
     * @throws Exception if connection fails
     */
    public String getSSLInfo(String urlString) throws Exception {
        HttpURLConnection connection = null;
        try {
            URL url = new URI(urlString).toURL();
            connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("HEAD");
            connection.setConnectTimeout(connectionTimeout);
            connection.setReadTimeout(readTimeout);

            // Trigger connection to perform SSL handshake
            connection.getResponseCode();

            StringBuilder info = new StringBuilder();
            info.append("=== SSL/TLS Information ===\n");
            info.append("URL: ").append(urlString).append("\n");
            info.append("Status Code: ").append(connection.getResponseCode()).append("\n");
            info.append("Content Type: ").append(connection.getContentType()).append("\n");

            // Get cipher suite if available (only on HTTPS)
            if (connection instanceof javax.net.ssl.HttpsURLConnection httpsConnection) {
                httpsConnection.connect();
                info.append("Cipher Suite: ").append(httpsConnection.getCipherSuite()).append("\n");
                var sslSession = httpsConnection.getSSLSession();
                if (sslSession.isPresent()) {
                    info.append("Protocol: ").append(sslSession.get().getProtocol()).append("\n");
                }
            }

            return info.toString();

        } finally {
            if (connection != null) {
                connection.disconnect();
            }
        }
    }

    /**
     * Reads the response body from the connection
     */
    private String readResponse(HttpURLConnection connection) throws Exception {
        StringBuilder response = new StringBuilder();
        try (BufferedReader reader = new BufferedReader(
                new InputStreamReader(connection.getInputStream(), StandardCharsets.UTF_8))) {
            String line;
            while ((line = reader.readLine()) != null) {
                response.append(line).append("\n");
            }
        }
        return response.toString();
    }

    /**
     * Prints response headers
     */
    private void printHeaders(Map<String, List<String>> headers) {
        headers.forEach((key, values) -> {
            if (key != null) { // null key is the status line
                values.forEach(value -> System.out.println("  " + key + ": " + value));
            }
        });
    }

    /**
     * Sets the connection timeout
     */
    public void setConnectionTimeout(int timeout) {
        this.connectionTimeout = timeout;
    }

    /**
     * Sets the read timeout
     */
    public void setReadTimeout(int timeout) {
        this.readTimeout = timeout;
    }

    /**
     * Sets the User-Agent header
     */
    public void setUserAgent(String userAgent) {
        this.userAgent = userAgent;
    }
}

How to Run the Example

Prerequisites

• Java 21+ (or JDK 17+ minimum)
• Gradle 8.x

Steps

1. Clone or download the project:

   cd ssl-debug
   

2. Build the project:

   ./gradlew build
   

3. Run with SSL debugging enabled:

   ./gradlew run
   

4. Capture output to file:

   ./gradlew run > all.log 2>&1
   

The application will:

• Enable javax.net.debug=all
• Make a GET request to https://httpbin.org/get
• Log all TLS handshake messages
• Display SSL/TLS information (cipher suite, protocol version, etc.)

Key Insights from the Handshake

Certificate Chain Validation

The SSL/TLS debug output shows the server provided three certificates:

1. End-Entity Certificate: httpbin.org (issued by Amazon RSA 2048 M CA)
2. Intermediate CA: Amazon RSA 2048 M
3. Root CA: Amazon Root CA (trusted in system trust store)

The JVM validates this chain by:

• Loading 152 trusted CA certificates from cacerts
• Verifying each certificate's signature against its issuer
• Checking validity dates
• Confirming key usage extensions

Cipher Suite Selection

The server chose TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 because it's:

• Secure: Modern encryption standard
• Forward-Secure: Uses ephemeral ECDH keys (PFS)
• Authenticated: RSA signature verification
• Authenticated Encryption: AES-GCM prevents tampering

Key Exchange Details

• Algorithm: ECDHE (Elliptic Curve Diffie-Hellman Ephemeral)
• Benefits:
  • Perfect Forward Secrecy (PFS) - past sessions are safe even if long-term keys are compromised
  • Faster than traditional DHE
  • Smaller key sizes with equivalent security

Common SSL/TLS Debugging Scenarios

Debug Level Options

// Full debug (as shown in this guide)
System.setProperty("javax.net.debug", "all");

// Specific areas only
System.setProperty("javax.net.debug", "ssl");           // SSL records
System.setProperty("javax.net.debug", "ssl:handshake"); // Handshake only
System.setProperty("javax.net.debug", "ssl:trustmanager"); // Certificate validation
System.setProperty("javax.net.debug", "ssl:record");    // Record layer details

Troubleshooting Common Issues

Issue: PKIX path building failed

• Cause: Certificate not in trust store
• Solution: Import certificate or use custom TrustManager

Issue: Unsupported or unrecognized SSL message

• Cause: Connecting to non-HTTPS endpoint
• Solution: Verify URL starts with https://

Issue: Excessive network latency

• Cause: Certificate revocation checks (OCSP, CRL)
• Solution: Disable revocation checks if acceptable for your use case

Conclusion

Understanding TLS/TLS handshakes is essential for:

• Debugging: Identifying connection issues quickly
• Security: Understanding what's being negotiated
• Performance: Analyzing handshake overhead
• Compliance: Verifying secure cipher suites are used

The javax.net.debug system property provides deep visibility into Java's SSL/TLS layer, making it invaluable for developers working with secure connections.

Remember: The SSL/TLS logs contain sensitive handshake information. Only enable debugging in development environments, never in production without careful security considerations.

Resources

• Java JSSE Documentation
• RFC 5246 - TLS 1.2
• OWASP Transport Layer Protection
• httpbin.org - HTTP Request/Response Service

Get the Code

The source code for this project is available on GitHub:

📚 github.com/mnafshin/ssl-debug

Feel free to fork, clone, and experiment with the examples to deepen your understanding of SSL/TLS handshakes!