|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +This is a custom TLS 1.3 server implementation in Go that demonstrates the complete TLS 1.3 handshake protocol from scratch. The project implements all major handshake messages (ClientHello, ServerHello, EncryptedExtensions, Certificate, CertificateVerify, Finished) and serves HTTP responses over TLS 1.3. |
| 8 | + |
| 9 | +## Architecture |
| 10 | + |
| 11 | +- `main.go`: Entry point that starts the custom TLS 1.3 server via `tls13.Server()` |
| 12 | +- `tls13/` package: Core TLS 1.3 implementation |
| 13 | + - `tls1_3.go`: Core TLS 1.3 data structures, constants, and cryptographic operations |
| 14 | + - `handshake.go`: Main server loop and TLS record handling |
| 15 | + - `client_hello_handler.go`: ClientHello message processing and server response generation |
| 16 | + - `finished_handler.go`: Client Finished message verification |
| 17 | + - `application_data_handler.go`: HTTP request/response handling over TLS |
| 18 | + - `utilities.go`: HKDF key derivation and cryptographic utilities |
| 19 | + |
| 20 | +The implementation supports: |
| 21 | +- ECDHE key exchange (secp256r1, secp384r1, secp521r1, x25519) |
| 22 | +- ECDSA and Ed25519 certificate signatures |
| 23 | +- AES-128-GCM encryption |
| 24 | +- SHA-256 hashing |
| 25 | +- HTTP/1.1 over TLS 1.3 |
| 26 | + |
| 27 | +## Common Commands |
| 28 | + |
| 29 | +### Certificate Generation |
| 30 | +```bash |
| 31 | +make server-crt # Generate ECDSA certificate (default) |
| 32 | +make ed25519-crt # Generate Ed25519 certificate |
| 33 | +``` |
| 34 | + |
| 35 | +### Running the Server |
| 36 | +```bash |
| 37 | +make start # Start the TLS 1.3 server on port 443 |
| 38 | +``` |
| 39 | + |
| 40 | +### Testing |
| 41 | +```bash |
| 42 | +make test # Run all Go tests |
| 43 | +make handshake # Test with OpenSSL s_client (debugging) |
| 44 | +``` |
| 45 | + |
| 46 | +### Client Testing |
| 47 | +```bash |
| 48 | +# OpenSSL client |
| 49 | +openssl s_client -noservername -crlf -connect localhost:443 |
| 50 | + |
| 51 | +# curl |
| 52 | +curl -k https://localhost:443 |
| 53 | + |
| 54 | +# Browser: https://localhost (accept certificate warning) |
| 55 | +``` |
| 56 | + |
| 57 | +## Key Implementation Details |
| 58 | + |
| 59 | +- Custom TLS record parsing and generation in `handshake.go:handleMessage` |
| 60 | +- ECDH key exchange and shared secret derivation in `tls1_3.go:GenerateSecrets` |
| 61 | +- HKDF-based key derivation following TLS 1.3 specification in `utilities.go` |
| 62 | +- AES-GCM AEAD encryption/decryption with proper nonce calculation |
| 63 | +- Certificate verification and digital signature generation/verification |
| 64 | +- HTTP request parsing and response generation over established TLS connection |
| 65 | + |
| 66 | +The server expects `server.crt` and `server.key` files in the project root for TLS operation. |
0 commit comments