README

English | 中文

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

Features
Requirements
Installation
Quick Start
Basic Usage
Advanced Usage
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.

tourze / shadowsocks-config-php

Maintainers

Details