README

English | 中文

A pure PHP implementation of the Shadowsocks protocol, including encryption, decryption, and protocol handling for both client and server operations.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Basic Usage
  • Creating a Shadowsocks Configuration
  • Encrypting and Decrypting Data
  • Using AEAD Ciphers
  • Protocol Layers
  • Working with URIs
• Advanced Usage
  • auth_chain Protocol
  • Buffer Management
  • Action Handling
• Supported Encryption Methods
  • Stream Ciphers
  • AEAD Ciphers
• Testing
• Contributing
• Security
• License
• References

Features

• Full Protocol Support

  • Stream ciphers (AES-CFB, RC4, ChaCha20)
  • AEAD ciphers (AES-GCM, ChaCha20-Poly1305)
  • auth_aes128_md5 and auth_chain protocols
  • TCP and UDP support

• Configuration Management

  • Standard URI format (ss://method:password@hostname:port#tag)
  • Base64 encoded URI format
  • SIP002 URI format with plugin support
  • SIP008 online configuration delivery
  • JSON configuration files

• Modular Architecture

  • Pluggable cipher implementations
  • Layer-based protocol handling
  • Action-based request/response processing
  • Buffer management for streaming data

Installation

composer require tourze/shadowsocks-php

Requirements

• PHP 8.1 or higher
• OpenSSL extension
• Sodium extension (optional, for ChaCha20-Poly1305)

Quick Start

Here's a simple example to get you started with Shadowsocks PHP:

<?php
require_once 'vendor/autoload.php';

use Shadowsocks\Config\ClientConfig;
use Shadowsocks\Cipher\Encipher;
use Shadowsocks\Cipher\Decipher;

// 1. Create a configuration
$config = new ClientConfig(
    'your-server.com',  // Server address
    8388,               // Server port  
    1080,               // Local port
    'your-password',    // Password
    'aes-256-gcm'       // Encryption method
);

// 2. Quick encryption/decryption
$password = 'your-password';
$key = hash('sha256', $password, true);
$iv = random_bytes(16);

$encipher = new Encipher('aes-256-cfb', $key, $iv);
$encrypted = $encipher->update('Hello World');

$decipher = new Decipher('aes-256-cfb', $key, $iv);
$decrypted = $decipher->update($encrypted);

echo "Original: Hello World\n";
echo "Encrypted: " . base64_encode($encrypted) . "\n";
echo "Decrypted: " . $decrypted . "\n";

Basic Usage

Creating a Shadowsocks Configuration

use Shadowsocks\Config\ClientConfig;

$config = new ClientConfig(
    '192.168.1.100',  // Server address
    8388,             // Server port  
    1080,             // Local port
    'mypassword',     // Password
    'aes-256-gcm'     // Encryption method
);

Encrypting and Decrypting Data

use Shadowsocks\Cipher\Encipher;
use Shadowsocks\Cipher\Decipher;

// Encryption
$key = hash('sha256', 'password', true);
$iv = random_bytes(16);
$encipher = new Encipher('aes-256-cfb', $key, $iv);
$encrypted = $encipher->update('Hello World');

// Decryption  
$decipher = new Decipher('aes-256-cfb', $key, $iv);
$decrypted = $decipher->update($encrypted);

Using AEAD Ciphers

use Shadowsocks\Cipher\AEADEncipher;
use Shadowsocks\Cipher\AEADDecipher;

$salt = random_bytes(32);

// AEAD Encryption
$encipher = new AEADEncipher('aes-256-gcm', 'password', $salt);
$encrypted = $encipher->update('Hello World');

// AEAD Decryption
$decipher = new AEADDecipher('aes-256-gcm', 'password', $salt);
$decrypted = $decipher->update($encrypted);

Protocol Layers

use Shadowsocks\Layer\StreamLayer;
use Shadowsocks\Config\ServerConfig;

// Create a stream layer for protocol handling
$config = new ServerConfig(8388, 'password', 'aes-256-gcm');
$layer = new StreamLayer($config);

// Process incoming data
$actions = $layer->decrypt($encryptedData);
foreach ($actions as $action) {
    if ($action instanceof \Shadowsocks\Action\Streaming) {
        // Handle streaming data
        $data = $action->getData();
    }
}

Working with URIs

use Shadowsocks\Config\SIP002;

// Parse Shadowsocks URI
$sip002 = SIP002::fromUri('ss://YWVzLTI1Ni1nY206cGFzc3dvcmQ@192.168.1.100:8388#MyServer');
$config = $sip002->getConfig();

// Generate URI from config
$config = new ClientConfig('192.168.1.100', 8388, 1080, 'password', 'aes-256-gcm');
$sip002 = new SIP002($config);
$uri = $sip002->toUri();

Advanced Usage

auth_chain Protocol

use Shadowsocks\Layer\AuthChainLayer;
use Shadowsocks\Config\ServerConfig;

$config = new ServerConfig(8388, 'password', 'none');
$config->setProtocol('auth_chain_a');
$config->setProtocolParam('1234:user_password');

$layer = new AuthChainLayer($config);

Buffer Management

use Shadowsocks\Buffer;

$buffer = new Buffer();
$buffer->push('Hello ');
$buffer->push('World');

$data = $buffer->pop(5);  // Returns 'Hello'
$remaining = $buffer->popAll(); // Returns ' World'

Action Handling

use Shadowsocks\Action\SendBack;
use Shadowsocks\Action\Streaming;
use Shadowsocks\Action\CloseConnection;

// Different actions for different scenarios
$sendBack = new SendBack($responseData);
$streaming = new Streaming($forwardData);
$close = CloseConnection::instance();

Supported Encryption Methods

Stream Ciphers

• aes-128-cfb
• aes-192-cfb
• aes-256-cfb
• aes-128-ctr
• aes-192-ctr
• aes-256-ctr
• chacha20
• chacha20-ietf
• rc4
• rc4-md5

AEAD Ciphers

• aes-128-gcm
• aes-192-gcm
• aes-256-gcm
• chacha20-poly1305
• chacha20-ietf-poly1305
• xchacha20-ietf-poly1305

Testing

# Run all tests
./vendor/bin/phpunit packages/shadowsocks-php/tests

# Run specific test categories
./vendor/bin/phpunit packages/shadowsocks-php/tests/Layer
./vendor/bin/phpunit packages/shadowsocks-php/tests/Cipher
./vendor/bin/phpunit packages/shadowsocks-php/tests/Config

# Run tests with coverage
./vendor/bin/phpunit packages/shadowsocks-php/tests --coverage-text

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email security@tourze.com instead of using the issue tracker.

License

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

References

• Shadowsocks Protocol
• AEAD Ciphers
• SIP002 URI Scheme
• SIP008 Online Configuration