tourze/tls-record

TLS Record

0.0.1 2025-05-19 06:41 UTC

Requires

• php: ^8.1
• ext-hash: *
• ext-sockets: *
• tourze/tls-common: 0.0.*
• tourze/tls-crypto: 0.0.*

Requires (Dev)

• maglnet/composer-require-checker: ^4
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^10.0

MIT

README

English | 中文

TLS-Record package implements the Record Layer of the TLS protocol, which is one of the core components of TLS.

The Record Layer is responsible for fragmenting data into manageable blocks, applying encryption and integrity protection to these blocks, and then encapsulating them into a consistent format for transmission.

Table of Contents

• Features
• Installation
• Quick Start
• Basic Usage
  • Creating a Record Layer Instance
  • Sending Records
  • Receiving Records
  • Switching to Encrypted Mode
  • Setting Maximum Fragment Length
• Custom Transport Layer
• Requirements
• Dependencies
• Architecture
• API Reference
  • RecordLayer Interface
• Contributing
• Security
• License

Features

• Complete implementation of the TLS Record Layer protocol
• Support for TLS 1.0, 1.1, 1.2, and 1.3
• Record fragmentation and reassembly
• Encryption and MAC protection
• Buffer management and optimization
• Defense against common TLS attacks (padding oracle, replay attacks)
• Pluggable transport layer interface
• Version-specific adapters for protocol differences

Installation

composer require tourze/tls-record

Quick Start

<?php

use Tourze\TLSCommon\Protocol\TLSVersion;
use Tourze\TLSCommon\Protocol\ContentType;
use Tourze\TLSRecord\RecordFactory;
use Tourze\TLSRecord\Transport\SocketTransport;

// Create transport layer
$transport = new SocketTransport('example.com', 443);

// Create record layer (TLS 1.2)
$recordLayer = RecordFactory::create($transport, TLSVersion::TLS_1_2->value);

// Send a handshake message
$handshakeData = 'your handshake data';
$recordLayer->sendRecord(ContentType::HANDSHAKE, $handshakeData);

// Receive a record
$record = $recordLayer->receiveRecord();
echo "Received: " . bin2hex($record->getData()) . "\n";

Basic Usage

Creating a Record Layer Instance

use Tourze\TLSCommon\Version;
use Tourze\TLSRecord\RecordFactory;
use Tourze\TLSRecord\Transport\SocketTransport;

// Create transport layer
$transport = new SocketTransport('example.com', 443);

// Create record layer
$recordLayer = RecordFactory::create($transport, Version::TLS_1_2);

Sending Records

use Tourze\TLSCommon\Protocol\ContentType;

// Send handshake message
$recordLayer->sendRecord(ContentType::HANDSHAKE, $handshakeData);

// Send application data
$recordLayer->sendRecord(ContentType::APPLICATION_DATA, $applicationData);

Receiving Records

// Receive record
$record = $recordLayer->receiveRecord();

// Check record type
if ($record->getContentType() === ContentType::HANDSHAKE) {
    // Process handshake message
    $handshakeData = $record->getData();
} elseif ($record->getContentType() === ContentType::APPLICATION_DATA) {
    // Process application data
    $applicationData = $record->getData();
}

Switching to Encrypted Mode

use Tourze\TLSRecord\CipherState;

// Create cipher state
$cipherState = new CipherState(
    'TLS_AES_128_GCM_SHA256', // Cipher suite
    $key,                     // Encryption key
    $iv,                      // Initialization vector
    $macKey,                  // MAC key
    Version::TLS_1_2          // TLS version
);

// Switch to encrypted mode
$recordLayer->changeWriteCipherSpec($cipherState);
$recordLayer->changeReadCipherSpec($cipherState);

Setting Maximum Fragment Length

// Set maximum fragment length
$recordLayer->setMaxFragmentLength(8192);

Custom Transport Layer

You can create custom transport layers by implementing the Transport interface:

use Tourze\TLSRecord\Transport\Transport;

class CustomTransport implements Transport
{
    // Implement interface methods
    public function send(string $data): int
    {
        // Custom send implementation
    }
    
    public function receive(int $length): string
    {
        // Custom receive implementation
    }
    
    public function hasDataAvailable(int $timeout = 0): bool
    {
        // Custom check implementation
    }
    
    public function close(): void
    {
        // Custom close implementation
    }
}

Requirements

• PHP 8.1 or higher
• ext-hash extension
• ext-sockets extension

Dependencies

• tourze/tls-common - Common TLS protocol definitions
• tourze/tls-crypto-hash - Cryptographic hash functions
• tourze/tls-crypto-symmetric - Symmetric encryption support

Architecture

The package consists of several key components:

• RecordLayer: Main interface for sending and receiving TLS records
• RecordFactory: Factory for creating record layer instances
• CipherState: Manages encryption/decryption state
• Transport Layer: Abstraction for network communication
• Version Adapters: Handle protocol differences between TLS versions
• Security Components: Protection against various attacks

API Reference

RecordLayer Interface

// Send a record
public function sendRecord(int $contentType, string $data): void

// Receive a record
public function receiveRecord(): RecordData

// Change cipher specifications
public function changeWriteCipherSpec(CipherState $cipherState): void
public function changeReadCipherSpec(CipherState $cipherState): void

// Set maximum fragment length
public function setMaxFragmentLength(int $length): void

Contributing

Please see CONTRIBUTING.md for details.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

License

The MIT License (MIT). Please see License File for more information.