README

English | 中文

This package provides comprehensive TLS extension naming and handling functionality for PHP applications, implementing various TLS extensions according to RFC specifications.

Features

Full implementation of 20+ common TLS extensions
Type-safe extension handling with PHP 8.2+ enums
Easy-to-use factory methods for creating extensions
Encoding and decoding support for binary TLS data
Support for both TLS 1.2 and TLS 1.3 extensions
Comprehensive test coverage with 128 test cases

Installation

composer require tourze/tls-extension-naming

Supported Extensions

Server Name Indication (SNI) - RFC 6066
Application-Layer Protocol Negotiation (ALPN) - RFC 7301
Supported Versions - RFC 8446 (TLS 1.3)
Signature Algorithms - RFC 8446
Key Share - RFC 8446 (TLS 1.3)
Supported Groups - RFC 8446
Pre-Shared Key - RFC 8446 (TLS 1.3)
Early Data - RFC 8446 (TLS 1.3)
Extended Master Secret - RFC 7627
Session Ticket - RFC 5077
And many more...

Quick Start

Using the Extension Factory

use Tourze\TLSExtensionNaming\ExtensionFactory;

// Create a Server Name extension
$sniExtension = ExtensionFactory::createServerName('example.com');

// Create an ALPN extension
$alpnExtension = ExtensionFactory::createALPN(['h2', 'http/1.1']);

// Create a Supported Versions extension
$versionsExtension = ExtensionFactory::createSupportedVersions([
    0x0304, // TLS 1.3
    0x0303  // TLS 1.2
]);

// Create a Signature Algorithms extension
$sigAlgsExtension = ExtensionFactory::createSignatureAlgorithms([
    0x0804, // rsa_pss_rsae_sha256
    0x0401  // rsa_pkcs1_sha256
]);

// Create a Key Share extension
$keyShareExtension = ExtensionFactory::createKeyShare([
    ['group' => 0x001d, 'key_exchange' => 'public_key_data_here']
]);

Working with Extensions Directly

use Tourze\TLSExtensionNaming\Extension\ServerNameExtension;
use Tourze\TLSExtensionNaming\Extension\ALPNExtension;

// Server Name Extension
$sni = new ServerNameExtension();
$sni->addServerName('example.com')
    ->addServerName('www.example.com');

// Encode to binary
$encoded = $sni->encode();

// Decode from binary
$decoded = ServerNameExtension::decode($encoded);

// ALPN Extension
$alpn = new ALPNExtension();
$alpn->addProtocol(ALPNExtension::PROTOCOL_HTTP_2)
     ->addProtocol(ALPNExtension::PROTOCOL_HTTP_1_1);

Extension Types Enum

use Tourze\TLSExtensionNaming\Extension\ExtensionType;

// Access extension type values
$sniType = ExtensionType::SERVER_NAME->value; // 0x0000
$alpnType = ExtensionType::ALPN->value;       // 0x0010
$keyShareType = ExtensionType::KEY_SHARE->value; // 0x0033

// Get extension label
echo ExtensionType::SERVER_NAME->getLabel(); // "服务器名称指示"

// Get all registered extension types
$registeredTypes = ExtensionFactory::getRegisteredTypes();

Advanced Usage

Custom Extensions

You can register custom extension types:

use Tourze\TLSExtensionNaming\ExtensionFactory;
use Tourze\TLSExtensionNaming\Extension\AbstractExtension;

class MyCustomExtension extends AbstractExtension {
    public function getType(): int {
        return 0x9999;
    }
    
    public function encode(): string {
        // Implementation
    }
    
    public static function decode(string $data): static {
        // Implementation
    }
}

// Register the custom extension
ExtensionFactory::registerExtension(0x9999, MyCustomExtension::class);

Error Handling

use Tourze\TLSExtensionNaming\Exception\UnknownExtensionTypeException;
use Tourze\TLSExtensionNaming\Exception\ExtensionEncodingException;

try {
    $extension = ExtensionFactory::create(0x9999, $data);
} catch (UnknownExtensionTypeException $e) {
    echo "Unknown extension type: " . $e->getMessage();
} catch (ExtensionEncodingException $e) {
    echo "Encoding error: " . $e->getMessage();
}

Requirements

PHP 8.2 or higher
Composer

Testing

vendor/bin/phpunit

Contributing

Please see CONTRIBUTING.md for details.

License

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

tourze / tls-extension-naming

Maintainers

Details