README

English | 中文

A comprehensive PHP library for handling TLS handshake protocol messages. This package provides complete implementation of TLS handshake message structures with serialization, deserialization, and validation capabilities.

Table of Contents

• Features
• Installation
• Requirements
• Supported Message Types
• Quick Start
  • Creating a ClientHello Message
  • Working with Certificates
  • Message Validation
  • Version Compatibility
• Architecture
  • Message Interface
  • Message Types
  • Exception Handling
• Testing
• Development
  • Code Quality
• Contributing
• License
• Security
• Related Packages

Features

• 🔒 Complete TLS Message Support: Implements all major TLS handshake message types
• 📦 Serialization/Deserialization: Efficient binary data encoding and decoding
• ✅ Message Validation: Built-in integrity and format validation
• 🔄 Version Compatibility: Support for multiple TLS versions with compatibility handling
• 🧪 Well Tested: Comprehensive test suite with 100+ test cases
• 🚀 High Performance: Optimized for production use

Installation

composer require tourze/tls-handshake-messages

Requirements

• PHP 8.1 or higher
• tourze/enum-extra: ^0.1
• tourze/tls-common: ^0.0

Supported Message Types

• ClientHello: Client handshake initialization
• ServerHello: Server handshake response
• Certificate: Certificate chain messages
• CertificateRequest: Certificate request from server
• CertificateVerify: Certificate verification messages
• ClientKeyExchange: Client key exchange messages
• ServerKeyExchange: Server key exchange messages
• Finished: Handshake completion messages
• NewSessionTicket: Session ticket messages
• EncryptedExtensions: TLS 1.3 encrypted extensions
• HelloRequest: Server hello request messages
• ServerHelloDone: Server hello done messages

Quick Start

Creating a ClientHello Message

use Tourze\TLSHandshakeMessages\Message\ClientHelloMessage;

// Create a new ClientHello message
$clientHello = new ClientHelloMessage();
$clientHello->setVersion(0x0303); // TLS 1.2
$clientHello->setRandom(random_bytes(32));
$clientHello->setSessionId('');
$clientHello->setCipherSuites([0x1301, 0x1302]); // TLS 1.3 cipher suites
$clientHello->setCompressionMethods([0x00]);

// Add extensions
$clientHello->addExtension(0, hex2bin('00000e7777772e676f6f676c652e636f6d')); // server_name

// Serialize to binary
$binaryData = $clientHello->encode();

// Deserialize from binary
$decodedMessage = ClientHelloMessage::decode($binaryData);

Working with Certificates

use Tourze\TLSHandshakeMessages\Message\CertificateMessage;

// Create certificate message with chain
$certificate = new CertificateMessage();
$certificate->setCertificateChain([
    $serverCertificate,
    $intermediateCertificate,
    $rootCertificate
]);

// Or add certificates one by one
$certificate->addCertificate($serverCertificate);
$certificate->addCertificate($intermediateCertificate);

// Validate certificate message
if ($certificate->isValid()) {
    // Process certificate chain
    $chain = $certificate->getCertificateChain();
}

Message Validation

// All messages implement validation
if ($message->isValid()) {
    // Message is properly formatted
    $length = $message->getLength();
    $type = $message->getType();
}

Version Compatibility

use Tourze\TLSHandshakeMessages\Protocol\MessageCompatibilityHandler;

// Adapt message to different TLS versions
$tls12Message = MessageCompatibilityHandler::adaptMessageToVersion(
    $originalMessage,
    MessageCompatibilityHandler::TLS_VERSION_1_2
);

// Check compatibility
if (MessageCompatibilityHandler::isMessageCompatibleWithVersion($message, MessageCompatibilityHandler::TLS_VERSION_1_3)) {
    // Message is compatible with TLS 1.3
}

Architecture

Message Interface

All messages implement HandshakeMessageInterface which provides:

• getType(): Get message type
• encode(): Serialize to binary
• decode(): Deserialize from binary
• getLength(): Get message length
• isValid(): Validate message format

Message Types

Message types are defined in HandshakeMessageType enum:

use Tourze\TLSHandshakeMessages\Protocol\HandshakeMessageType;

$type = HandshakeMessageType::CLIENT_HELLO;

Exception Handling

The package uses InvalidMessageException for handling malformed messages:

use Tourze\TLSHandshakeMessages\Exception\InvalidMessageException;

try {
    $message = ClientHelloMessage::decode($invalidData);
} catch (InvalidMessageException $e) {
    // Handle invalid message format
}

Testing

Run the test suite:

vendor/bin/phpunit packages/tls-handshake-messages/tests

Development

Code Quality

# Run PHPStan analysis
vendor/bin/phpstan analyse packages/tls-handshake-messages

# Run tests
vendor/bin/phpunit packages/tls-handshake-messages/tests

Contributing

1. Fork the repository
2. Create a feature branch
3. Write tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

MIT License. See LICENSE file for details.

Security

This package is designed for defensive security applications. If you discover any security issues, please report them responsibly.

Related Packages

• tourze/tls-common - Common TLS utilities
• tourze/enum-extra - Enhanced enum functionality