-
Notifications
You must be signed in to change notification settings - Fork 535
SIP008 Online Configuration Delivery
Max Lv edited this page Nov 12, 2020
·
4 revisions
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.
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 to1
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
andplugin_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
andbytes_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, thebytes_used
field must also be included. In other words, this field must not be specified without thebytes_used
field.
- 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.