Add Shadowsocks over WebSocket (SS over WSS) Support

[lunarthegrey]

Feature Request: Add Shadowsocks over WebSocket (SS over WSS) Support

Fork where changes were made: https://github.com/unredacted/outline-server

Summary

Add support for tunneling Shadowsocks traffic over WebSocket connections to enhance censorship resistance and improve connectivity in restrictive network environments.

Motivation

Current Limitations

The current Outline Server implementation only supports direct Shadowsocks connections, which can be problematic in several scenarios:

1. Deep Packet Inspection (DPI): Modern censorship systems can detect and block Shadowsocks traffic patterns
2. Corporate Firewalls: Many enterprise networks only allow HTTP/HTTPS traffic through proxies
3. Network Restrictions: Some networks block non-standard ports or protocols
4. Protocol Fingerprinting: Direct Shadowsocks connections have identifiable characteristics

Proposed Solution

I've implemented a complete solution that adds WebSocket transport support while maintaining backward compatibility. The implementation allows servers to support both traditional Shadowsocks connections and WebSocket-tunneled connections simultaneously.

Key Features

1. Flexible Configuration: Each access key can optionally enable WebSocket transport
2. Dual Protocol Support: Separate paths for TCP and UDP over WebSocket
3. Dynamic Client Configuration: Automatically generates appropriate client configs
4. Backward Compatible: Servers without WebSocket keys continue using the legacy format
5. Mixed Mode Operation: Supports both WebSocket and traditional clients simultaneously

API Changes

New WebSocket configuration options for access keys:

{
  "name": "User with WebSocket",
  "websocket": {
    "enabled": true,
    "tcpPath": "/tcp",
    "udpPath": "/udp", 
    "domain": "example.com",
    "tls": true
  }
}

Configuration Format

The implementation automatically generates the appropriate outline-ss-server configuration:

When WebSocket keys exist:

web:
  servers:
    - id: outline-ws-server
      listen:
        - '127.0.0.1:8080'
services:
  - listeners:
      - type: tcp
        address: '[::]:443'
      - type: udp
        address: '[::]:443'
    keys:
      - id: '0'
        cipher: chacha20-ietf-poly1305
        secret: <secret>
  - listeners:
      - type: websocket-stream
        web_server: outline-ws-server
        path: /tcp
      - type: websocket-packet
        web_server: outline-ws-server
        path: /udp
    keys:
      - id: '1'
        cipher: chacha20-ietf-poly1305
        secret: <secret>

Client Configuration

WebSocket-enabled keys return dynamic YAML configuration:

transport:
  $type: tcpudp
  tcp:
    $type: shadowsocks
    endpoint:
      $type: websocket
      url: 'wss://example.com/tcp'
    cipher: chacha20-ietf-poly1305
    secret: <secret>
  udp:
    $type: shadowsocks
    endpoint:
      $type: websocket
      url: 'wss://example.com/udp'
    cipher: chacha20-ietf-poly1305
    secret: <secret>

Implementation Details

Components Modified

1. API Schema (api.yml): Added WebSocketConfig schema
2. Data Model (access_key.ts): Extended interfaces for WebSocket support
3. Manager Service (manager_service.ts): Added validation and dynamic config generation
4. Access Key Repository (server_access_key.ts): Stores WebSocket configuration
5. Shadowsocks Server (outline_shadowsocks_server.ts): Generates WebSocket-aware configs
6. Dependencies: Updated to outline-ss-server v1.9.2 with WebSocket support

Reverse Proxy Setup

The WebSocket server runs on a separate port (8080) and requires reverse proxy configuration with nginx example below:

location /tcp {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

location /udp {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

This can also be fronted by using something like Cloudflare Tunnel.

Testing

The implementation has been thoroughly tested with:

• Creating WebSocket-enabled access keys via API
• Generating proper server configurations for mixed environments
• Client connections using dynamic access key configurations
• Simultaneous traditional and WebSocket client connections
• Multi-platform Docker image builds (amd64/arm64)

Future Enhancements

1. Configurable WebSocket Port: Currently hardcoded to 8080
2. Custom Headers: Support for additional WebSocket headers
3. Path Randomization: Generate random paths for enhanced security

Contribution

I have a working implementation in my fork that I'm ready to contribute. The code:

• Maintains backward compatibility
• Follows existing code patterns and conventions
• Includes proper error handling and validation
• Has been tested in production environments

Would the team be interested in reviewing a pull request for this feature? I'm happy to make any adjustments to align with the project's goals and standards.

References

• [outline-ss-server v1.9.2](https://github.com/Jigsaw-Code/outline-ss-server/releases/tag/v1.9.2) - Includes WebSocket support
• [WebSocket Protocol RFC 6455](https://datatracker.ietf.org/doc/html/rfc6455)

[jyyi1]

Hi @lunarthegrey , is this what you are looking for: https://developers.google.com/outline/docs/guides/service-providers/websockets ?

[lunarthegrey]

Hi @jyyi1 - yes. My fork adds support for that into outline-server's shadowbox, rather than having to directly configure it on each server manually.

Currently it's not possible to create SS over WSS keys directly via the shadowbox API. This is very limiting for us which is why I forked, as the API is one of the best ways to programmatically create new access keys. Due to the fork, and added support in https://github.com/unredacted/freesocks-control-plane our service is able to create SS over WSS enabled access keys.

If you want, I can show you a demo of it working live on our service (in beta currently), just drop a message through to us: https://unredacted.org/contact/

[jyyi1]

Thanks @lunarthegrey for the explanation. @fortuna, please feel free to weigh in with your ideas.

[ohnorobo]

Here's the change diff for those looking. @lunarthegrey let me know if that's incorrect. I know you didn't officially make a PR yet, so sorry if I'm exposing it before you intended, but I think it's helpful for us to be able to look at the changes. Thank so much for your work on this!

[lunarthegrey]

No worries, thanks for posting that. I am looking for feedback on changes as well before I make a PR.

Testing with the fork is going well so far, I haven't run into any major issues and I've had maybe 50+ people test new access keys generated from the forked outline-server.

[lunarthegrey]

Here's an example curl of what you can do with the API in the fork to create an SS over WSS access key.

curl -X POST "https://server.domain.com/RANDOM_STRING/access-keys" \
    -H "Content-Type: application/json" \
    -k \
    -d '{
      "name": "WSS User 1",
      "websocket": {
        "enabled": true,
        "tcpPath": "/tcp",
        "udpPath": "/udp",
        "domain": "cdn-front.domain.com",
        "tls": true
      }
    }'

The JSON response looks like this:

{"id":"165","name":"WSS User 1","password":"RANDOM","port":443,"method":"chacha20-ietf-poly1305","accessUrl":"ss://RANDOM@cdn-front.domain.com:443/?outline=1","websocket":{"enabled":true,"tcpPath":"/tcp","udpPath":"/udp","domain":"cdn-front.domain.com","tls":true}}

[fortuna]

We need an API with a model aligned with the backend, which we designed to allow for expansion.

Instead of a method to "set the websocket", I'd rather see a method to add/remove a listener.
It's a generalization of the existing "port for new keys". Instead, we can have "listeners for new keys".
By default it starts with tcp and udp, and you can add websocket stream and packet.
(BTE, it will be cool to allow for tcp and udp ports to be different)

The reason why we have the API be "for new keys" is because the keys are static, and you can't change them after you distribute to users.

We will need a web server, so we probably need an API to create one. Though we can consider reusing the webserver that hosts the API. Better to keep separate, especially if we want to serve dynamic keys later. The API & dynamic keys should be on an address different from the proxy service, so they don't all get blocked together.

To use the webserver, we need TLS certificate provisioning. I believe there are libraries for that in Go, or we could call Caddy, which has an API. There's no need for nginx in that case. This would benefit the API as well, which currently runs with a self-signed certificate. I'd prioritize TLS certificate provisioning before anything else.

[lunarthegrey]

Thanks for the feedback. I'm going to think about this for a while and propose some changes to my fork.

[lunarthegrey]

Just want to report that I'm currently working on moving to the proposed listener model. I'm still testing different situations and making sure it works properly. Additionally, I'm thinking the best way to handle these WS keys would be to have a reverse proxy running alongside shadowbox (for example Caddy), then adding a feature to the shadowbox API to control Caddy via its admin API.

Right now, I'm just using Cloudflare Tunnels that proxy to localhost on the default port (8080) which works fine, but it would be ideal to have a better integrated method as well.

I think the API would be good to have in shadowbox, but I'm not sure if that's sort of the same line of thinking you were having too @fortuna. Let me know what you think.

[fortuna]

We already have https://github.com/Jigsaw-Code/outline-ss-server/tree/master/outlinecaddy. Have you seen that?
You can change the config via Caddy's config API.

Deploying a separate Caddy should work too, but the integrated approach may be better