├── LICENSE ├── README.md └── docs ├── 0001-open-online-config-v1.md └── 0002-open-online-config-v1-shadowsocks.md /LICENSE: -------------------------------------------------------------------------------- 1 | Creative Commons Legal Code 2 | 3 | CC0 1.0 Universal 4 | 5 | CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE 6 | LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN 7 | ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS 8 | INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES 9 | REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS 10 | PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM 11 | THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED 12 | HEREUNDER. 13 | 14 | Statement of Purpose 15 | 16 | The laws of most jurisdictions throughout the world automatically confer 17 | exclusive Copyright and Related Rights (defined below) upon the creator 18 | and subsequent owner(s) (each and all, an "owner") of an original work of 19 | authorship and/or a database (each, a "Work"). 20 | 21 | Certain owners wish to permanently relinquish those rights to a Work for 22 | the purpose of contributing to a commons of creative, cultural and 23 | scientific works ("Commons") that the public can reliably and without fear 24 | of later claims of infringement build upon, modify, incorporate in other 25 | works, reuse and redistribute as freely as possible in any form whatsoever 26 | and for any purposes, including without limitation commercial purposes. 27 | These owners may contribute to the Commons to promote the ideal of a free 28 | culture and the further production of creative, cultural and scientific 29 | works, or to gain reputation or greater distribution for their Work in 30 | part through the use and efforts of others. 31 | 32 | For these and/or other purposes and motivations, and without any 33 | expectation of additional consideration or compensation, the person 34 | associating CC0 with a Work (the "Affirmer"), to the extent that he or she 35 | is an owner of Copyright and Related Rights in the Work, voluntarily 36 | elects to apply CC0 to the Work and publicly distribute the Work under its 37 | terms, with knowledge of his or her Copyright and Related Rights in the 38 | Work and the meaning and intended legal effect of CC0 on those rights. 39 | 40 | 1. Copyright and Related Rights. A Work made available under CC0 may be 41 | protected by copyright and related or neighboring rights ("Copyright and 42 | Related Rights"). Copyright and Related Rights include, but are not 43 | limited to, the following: 44 | 45 | i. the right to reproduce, adapt, distribute, perform, display, 46 | communicate, and translate a Work; 47 | ii. moral rights retained by the original author(s) and/or performer(s); 48 | iii. publicity and privacy rights pertaining to a person's image or 49 | likeness depicted in a Work; 50 | iv. rights protecting against unfair competition in regards to a Work, 51 | subject to the limitations in paragraph 4(a), below; 52 | v. rights protecting the extraction, dissemination, use and reuse of data 53 | in a Work; 54 | vi. database rights (such as those arising under Directive 96/9/EC of the 55 | European Parliament and of the Council of 11 March 1996 on the legal 56 | protection of databases, and under any national implementation 57 | thereof, including any amended or successor version of such 58 | directive); and 59 | vii. other similar, equivalent or corresponding rights throughout the 60 | world based on applicable law or treaty, and any national 61 | implementations thereof. 62 | 63 | 2. Waiver. To the greatest extent permitted by, but not in contravention 64 | of, applicable law, Affirmer hereby overtly, fully, permanently, 65 | irrevocably and unconditionally waives, abandons, and surrenders all of 66 | Affirmer's Copyright and Related Rights and associated claims and causes 67 | of action, whether now known or unknown (including existing as well as 68 | future claims and causes of action), in the Work (i) in all territories 69 | worldwide, (ii) for the maximum duration provided by applicable law or 70 | treaty (including future time extensions), (iii) in any current or future 71 | medium and for any number of copies, and (iv) for any purpose whatsoever, 72 | including without limitation commercial, advertising or promotional 73 | purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each 74 | member of the public at large and to the detriment of Affirmer's heirs and 75 | successors, fully intending that such Waiver shall not be subject to 76 | revocation, rescission, cancellation, termination, or any other legal or 77 | equitable action to disrupt the quiet enjoyment of the Work by the public 78 | as contemplated by Affirmer's express Statement of Purpose. 79 | 80 | 3. Public License Fallback. Should any part of the Waiver for any reason 81 | be judged legally invalid or ineffective under applicable law, then the 82 | Waiver shall be preserved to the maximum extent permitted taking into 83 | account Affirmer's express Statement of Purpose. In addition, to the 84 | extent the Waiver is so judged Affirmer hereby grants to each affected 85 | person a royalty-free, non transferable, non sublicensable, non exclusive, 86 | irrevocable and unconditional license to exercise Affirmer's Copyright and 87 | Related Rights in the Work (i) in all territories worldwide, (ii) for the 88 | maximum duration provided by applicable law or treaty (including future 89 | time extensions), (iii) in any current or future medium and for any number 90 | of copies, and (iv) for any purpose whatsoever, including without 91 | limitation commercial, advertising or promotional purposes (the 92 | "License"). The License shall be deemed effective as of the date CC0 was 93 | applied by Affirmer to the Work. Should any part of the License for any 94 | reason be judged legally invalid or ineffective under applicable law, such 95 | partial invalidity or ineffectiveness shall not invalidate the remainder 96 | of the License, and in such case Affirmer hereby affirms that he or she 97 | will not (i) exercise any of his or her remaining Copyright and Related 98 | Rights in the Work or (ii) assert any associated claims and causes of 99 | action with respect to the Work, in either case contrary to Affirmer's 100 | express Statement of Purpose. 101 | 102 | 4. Limitations and Disclaimers. 103 | 104 | a. No trademark or patent rights held by Affirmer are waived, abandoned, 105 | surrendered, licensed or otherwise affected by this document. 106 | b. Affirmer offers the Work as-is and makes no representations or 107 | warranties of any kind concerning the Work, express, implied, 108 | statutory or otherwise, including without limitation warranties of 109 | title, merchantability, fitness for a particular purpose, non 110 | infringement, or the absence of latent or other defects, accuracy, or 111 | the present or absence of errors, whether or not discoverable, all to 112 | the greatest extent permissible under applicable law. 113 | c. Affirmer disclaims responsibility for clearing rights of other persons 114 | that may apply to the Work or any use thereof, including without 115 | limitation any person's Copyright and Related Rights in the Work. 116 | Further, Affirmer disclaims responsibility for obtaining any necessary 117 | consents, permissions or other rights required for any use of the 118 | Work. 119 | d. Affirmer understands and acknowledges that Creative Commons is not a 120 | party to this document and has no duty or obligation with respect to 121 | this CC0 or use of the Work. 122 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Open Online Config 2 | 3 | Open Online Config manages and maintains open protocols for the distribution of censorship circumvention services. 4 | 5 | ## Protocols 6 | 7 | 0. [README](README.md) (2021-06-27) 8 | 1. [Open Online Config Version 1](docs/0001-open-online-config-v1.md) (2021-08-20) 9 | 2. [Open Online Config Version 1: Shadowsocks](docs/0002-open-online-config-v1-shadowsocks.md) (2021-08-20) 10 | 11 | ## How to Propose New Protocols 12 | 13 | Open a PR to add your proposed standard document to the repository. 14 | 15 | For general-purpose distribution protocols, it's recommended to use a version number. For example, if the latest standardized version is Open Online Config Version 1 (OOCv1), then you may propose a version 2. 16 | -------------------------------------------------------------------------------- /docs/0001-open-online-config-v1.md: -------------------------------------------------------------------------------- 1 | # Open Online Config 1: An HTTPS-based Application Protocol for Configuration Delivery of Censorship Circumvention Services 2 | 3 | ## 0. Abstract 4 | 5 | This document defines version 1 of the Open Online Config protocol. Open Online Config 1 (OOCv1) provides a simple and elegant solution for service providers and application developers to deliver censorship circumvention service configurations to users. Open Online Config 1 enables unified support for different transport protocols with a registration and standardization process. 6 | 7 | ## 1. Overview 8 | 9 | Open Online Config 1 is an HTTPS-based application protocol for the distribution of censorship circumvention services. The protocol aims to provide a centralized model for the sharing of distributed censorship circumvention services in communities. 10 | 11 | An Open Online Config 1 server exposes a web API for clients to retrieve configurations. A series of requirements for the web API are specified in this document to ensure the secure transport of sensitive information. The API response is based on the minimal JSON format defined in this document. Extension standards add additional fields to support different transport protocols. 12 | 13 | ### 1.1. Document Structure 14 | 15 | This document describes the Open Online Config protocol version 1 and is structured as follows: 16 | 17 | - Section 2 describes transport and delivery details. 18 | - Section 3 defines the API specification, including request and response format. 19 | - Section 4 defines how transport protocols are registered and standardized. 20 | 21 | ### 1.2. Terms and Definitions 22 | 23 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119](https://www.rfc-editor.org/info/rfc2119) [RFC8174](https://www.rfc-editor.org/info/rfc8174) when, and only when, they appear in all capitals, as shown here. 24 | 25 | Commonly used terms in this document are described below. 26 | 27 | - OOCv1: An acronym for the Open Online Config protocol version 1 defined by this document. 28 | - Client: The endpoint that retrieves configuration for use. 29 | - Server: The endpoint that accepts OOCv1 requests and sends configuration. 30 | - Node: A participating server that acts as a transit for Internet traffic. 31 | 32 | ## 2. Transport and Delivery 33 | 34 | Clients communicate with servers by making API transactions. 35 | 36 | ### 2.1 Transport 37 | 38 | The web API MUST use HTTPS as the underlying transport. The minimum TLS version SHOULD be 1.3 to disallow week encryption and protect against TLS downgrade attacks. [HSTS (HTTP Strict Transport Security)](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security) SHOULD be deployed on the web server. Optimally, submit the domain name to the [HSTS preload list](https://hstspreload.org/). This prevents browsers from sending the initial request via an unsecured plain HTTP connection if the user enters the domain in the address bar without the protocol prefix. 39 | 40 | Certificates from a publicly-trusted CA SHOULD be used. Self-signed certificates MAY be used, in which case an accompanying certificate SHA-256 checksum must be provided for verification. 41 | 42 | Clients MUST NOT omit certificate issues or TLS errors to protect against TLS MITM attacks. Clients MAY support importing from or exporting as JSON files as a temporary way of exchanging configuration in case of need. 43 | 44 | Servers MUST respond with the correct format, content type and the UTF-8 charater set. 45 | 46 | ### 2.2 Delivery 47 | 48 | To access a web API, the following information is needed: 49 | 50 | - Base URL: The base URL for API transactions. The protocol scheme MUST be HTTPS. The URL MUST NOT contain a trailing slash. For example, `https://example.com`, `https://1.1.1.1:853` and `https://[2001:db8::1]:8443` are valid base URLs. `http://example.com` and `https://example.com/` are invalid because they do not meet the protocol scheme and trailing slash requirements. 51 | - Secret: Path to the API endpoint. This is required to conceal the presence of the API. The secret MAY contain zero or more forward slashes (/) to allow flexible path hierarchy. But it's recommended to put non-secret part of the path in the base URL. 52 | - User ID: A distinctive string that represents the user. A UUID or a random secret string MAY be used. 53 | - Certificate SHA-256 Fingerprint: Optional. Pin the server certificate by verifying the certificate fingerprint. Required only when using a self-signed certificate. The hash value MUST be a hexadecimal string with lowercase letters. For example, `0ae384bfd4dde9d13e50c5857c05a442c93f8e01445ee4b34540d22bd1e37f1b`. 54 | 55 | An __API token__ MAY be used to convey the API access information in a single string. 56 | 57 | ``` json 58 | { 59 | "version": 1, 60 | "baseUrl": "https://example.com", 61 | "secret": "8c1da4d8-8684-4a2c-9abb-57b9d5fa7e52", 62 | "userId": "a117460e-41df-4dbd-b2df-4bd0c16efd2f", 63 | "certSha256": "0ae384bfd4dde9d13e50c5857c05a442c93f8e01445ee4b34540d22bd1e37f1b" 64 | } 65 | ``` 66 | 67 | The `version` field MUST match the version of the Open Online Config protocol. 68 | 69 | The `certSha256` field is required when using a self-signed certificate. With a publicly-trusted certificate, this field SHOULD be omitted. 70 | 71 | The JSON string MAY be minified to fit in one line. 72 | 73 | ## 3. API Specification 74 | 75 | A `GET` method is required for basic configuration delivery. Implementations MAY implement additional methods. 76 | 77 | Request: 78 | 79 | ``` http 80 | GET //ooc/v1/ 81 | ``` 82 | 83 | Response JSON: 84 | 85 | ``` json 86 | { 87 | "username": "nobody", 88 | "bytesUsed": 274877906944, 89 | "bytesRemaining": 824633720832, 90 | "expiryDate": 1625356800, 91 | "protocols": [ "shadowsocks", "vmess", "trojan-go" ] 92 | } 93 | ``` 94 | 95 | Required fields: 96 | 97 | - `protocols`: Protocols utilized by this configuration. Only registered protocols are allowed. See Section 4 for details about protocol registration. 98 | 99 | Clients MUST check the `protocols` field against supported protocols. If not all protocols used by the configuration are supported, a warning message MUST be displayed. 100 | 101 | Optional fields: 102 | 103 | - `username`: Username. 104 | - `bytesUsed`: The amount of data used by the user in bytes. MUST be greater than or equal to 0. An unsigned 64-bit integer MAY be used. Omit this field if no data usage metrics are available. 105 | - `bytesRemaining`: The amount of data remaining to be used by the user in bytes. MUST be greater than or equal to 0. An unsigned 64-bit integer MAY be used. MUST be accompanied by `bytesUsed`. Omit this field if no data limit is in place. 106 | - `expiryDate`: 64-bit Unix Epoch timestamp in seconds. The configuration is valid until this date. Clients MUST pull for updates and reload before this date. If the credentials are updated, the servers MUST stop accepting new connections with expired credentials. Existing connections with expired credentials MUST be maintained. 107 | 108 | Custom fields MAY be used to convey additional optional information. They MUST follow the `camelCase` naming convention, and MUST NOT have the same name as any registered protocol object name. The delivered config MUST NOT rely on any custom fields to function. 109 | 110 | ## 4. Protocol Registration 111 | 112 | A transport protocol MUST be registered and approved to become part of the standard. 113 | 114 | 1. Prerequisites: A person MUST be actively involved in the design and/or implementation of the protocol to qualify for registration. If the protocol is managed by an organization or a company, anyone approved by the entity to represent them is eligible. 115 | 2. Registration: Open a pull request in this repository to add the standard document. The standard document MUST be written in English. The proposed changes MUST NOT cause conflicts or compatibility issues with existing configurations. 116 | 4. Approval: Once the proposed changes are approved and merged, the registered protocol will officially become part of the standard of Open Online Config 1, and is referred to as `OOCv1:`. For example, a registered `shadowsocks` protocol would be referred to as `OOCv1:shadowsocks`. 117 | -------------------------------------------------------------------------------- /docs/0002-open-online-config-v1-shadowsocks.md: -------------------------------------------------------------------------------- 1 | # Open Online Config 1: Shadowsocks 2 | 3 | ## 1. Overview 4 | 5 | Shadowsocks is a simple stateless proxy protocol that uses symmetric key ciphers to encrypt network traffic. 6 | 7 | This document defines the JSON document format for Shadowsocks AEAD configurations in Open Online Config 1, with support for plugins. 8 | 9 | ## 2. API Specification 10 | 11 | Request: 12 | 13 | ``` http 14 | GET //ooc/v1/ 15 | ``` 16 | 17 | Response JSON: 18 | 19 | ``` json 20 | { 21 | "protocols": [ "shadowsocks" ], 22 | "shadowsocks": [ 23 | { 24 | "id": "27b8a625-4f4b-4428-9f0f-8a2317db7c79", 25 | "name": "ServerName", 26 | "address": "example.com", 27 | "port": 8388, 28 | "method": "chacha20-ietf-poly1305", 29 | "password": "example", 30 | "pluginName": "plugin-name", 31 | "pluginVersion": "1.0", 32 | "pluginOptions": "whatever", 33 | "pluginArguments": "-vvvvvv" 34 | } 35 | ] 36 | } 37 | ``` 38 | 39 | The protocol name is `shadowsocks`. Shadowsocks servers are placed in an array named `shadowsocks`. Only Shadowsocks AEAD servers are allowed. Custom fields are allowed but MUST NOT be related to the protocol itself. 40 | 41 | Required fields: 42 | 43 | - `id`: UUID of the server. Used by clients to distinguish and persist servers when reloading. 44 | - `name`: Server name. 45 | - `address`: Server address. Do not enclose IPv6 addresses in brackets. Examples: `example.com`, `1.1.1.1`, `2001:db8::1`. 46 | - `port`: Server port number. 47 | - `method`: AEAD encryption method. Valid values: `aes-128-gcm`, `aes-256-gcm`, `chacha20-ietf-poly1305`. 48 | - `password`: Password. Not the derived key. 49 | 50 | Optional plugin fields: 51 | 52 | - `pluginName`: Plugin name. Required when using a plugin. 53 | - `pluginVersion`: Required version of the plugin. Optional when using a plugin. 54 | - `pluginOptions`: Value of environment variable `SS_PLUGIN_OPTIONS`. Optional when using a plugin. 55 | - `pluginArguments`: Plugin executable startup arguments. Optional when using a plugin. 56 | 57 | Implementations MUST follow [SIP003](https://shadowsocks.org/en/wiki/Plugin.html), with the addition of `pluginArguments` field to allow more flexible configurations. 58 | 59 | Plugin support at both sides is optional. But clients without plugin support MUST be able to recognize servers with plugins and reject them. 60 | 61 | Client implementations with plugin support MUST maintain a user-configurable list of locally installed plugins with their name, version, and binary path on it. When connecting to a plugin-enabled server, the client resolves the plugin from the list by matching plugin name and version. 62 | 63 | If a server doesn't use a plugin, all plugin fields MUST be omitted. 64 | --------------------------------------------------------------------------------