SIP008 Online Configuration Delivery

Overview

This specification defines a standard JSON document format for online configuration sharing and delivery, along with guidelines and security considerations for the secure transport of server configurations.

JSON Document Format

An example of a standard SIP008 JSON document:

{
    "version": 1,
    "servers": [
        {
            // Server UUID to distinguish between servers when updating.
            "id": "27b8a625-4f4b-4428-9f0f-8a2317db7c79",
            "remarks": "Name of the server",
            "server": "example.com",
            "server_port": 8388,
            "password": "example",
            "method": "chacha20-ietf-poly1305",
            "plugin": "xxx",
            "plugin_opts": "xxxxx"
        },
        // Another server
        {
            "id": "7842c068-c667-41f2-8f7d-04feece3cb67",
            "remarks": "Name of the server",
            "server": "example.com",
            "server_port": 8388,
            "password": "example",
            "method": "chacha20-ietf-poly1305",
            "plugin": "xxx",
            "plugin_opts": "xxxxx"
        }
    ],
    // The above fields are mandatory.
    // Optional fields for data usage:
    "bytes_used": 274877906944,
    "bytes_remaining": 824633720832
    // You may add other custom fields in the root object.
}

• All fields listed above, unless specified otherwise, are mandatory. You may define and include your own custom fields, but they are not guaranteed to be supported by all clients. Follow the naming convention of snake_case when naming your custom fields.
• The root object must contain a version field and it's set to 1 for this version of the standard.
• Each object within the servers array must represent a valid Shadowsocks server. Custom fields are allowed.
• The id field is a randomly-generated UUID used as the server UUID. With the server UUID, clients can distinguish between different servers, so client-specific miscellaneous information of the servers can be preserved when updating from an online configuration source.
• If a server does not use a plugin, the plugin and plugin_opts should be empty or excluded from the server object.
• To report data usage metrics to the client, the service provider must use the optional bytes_used and bytes_remaining fields. Custom fields must not be defined for the same purpose of the data usage optional fields. Clients without data usage support may ignore the data usage fields. Clients with data usage support must only use the data usage fields as the data source.
• The bytes_used field represents data used by the user in bytes.
• The bytes_remaining field represents data remaining to be used by the user in bytes. If no data limit is in place, the field must be omitted. If a data limit is enforced, the bytes_used field must also be included. In other words, this field must not be specified without the bytes_used field.

Transport and Delivery

• Delivery of an SIP008 JSON document must use HTTPS as the transport protocol. Clients must not ignore certificate issues or TLS handshake errors to protect against TLS MITM attacks. The web server should be configured to only use modern TLS versions to avoid week encryption and protect against TLS downgrade attacks. Plain HTTP can only be used for debugging purposes. Clients may display a warning message or reject it when a plain HTTP link is used.
• A delivery URL should employ basic protections against crawling. Common practices include using secrets in URL path and/or query.
• The response from the web service must be a standard JSON document. The response header must contain Content-Type: application/json; charset=utf-8. A response with an incorrect content type or in other charater sets can cause undefined behaviors in the client, and is not allowed by the standard.
• The JSON document should avoid escaping as mush as possible to maximize human readability. It doesn't need to be HTML safe, as the HTTP response content type is required in the previous rule.
• Clients may support importing from or exporting as JSON files, so users can exchange an SIP008 JSON document via their own transport channels.