diff options
Diffstat (limited to 'pages/docs/design')
| -rw-r--r-- | pages/docs/design/bonafide.text | 99 |
1 files changed, 72 insertions, 27 deletions
diff --git a/pages/docs/design/bonafide.text b/pages/docs/design/bonafide.text index 27f5588..69f15b5 100644 --- a/pages/docs/design/bonafide.text +++ b/pages/docs/design/bonafide.text @@ -14,19 +14,34 @@ Bonafide is a protocol that allows a user agent to communicate with a service pr Bonafide user SRP (Secure Remote Password) for password-based authentication. +h1. Definitions + +*DOMAIN* is the primary domain of the provider. This specified by the user when they enter what provider they want to sign up with. + +*API_BASE* is the root URL of all the API calls. This is constructed from @api_uri/api_version@, where @api_url@ and @api_version@ are values found in the @provider.json@ file. + +*ca.crt* is used to denote the provider's self-signed Certificate Authority certificate used to sign all the provider's server certificates, except for DOMAIN which uses a commercial Certificate Authority. + +*ca_cert_uri* is the special URL that specifies where to download the provider's CA certificate (@ca.crt@). The value for @ca_cert_uri@ is found in @provider.json@. + h1. Configuration Files +*Send If-Modified-Since header*: All HTTP requests for configuration JSON files should set a correct "If-Modified-Since" header. In reply, the server may send a "304 Not Modified" response if the client has the most up to date version. + h2. JSON files -h3. GET /provider.json +*Character encoding*: JSON files are always in UTF8. When loaded in the browser, they are not displayed in UTF8, so non-ascii characters look off, but the files are correct. + +h3. GET DOMAIN/provider.json The @provider.json@ file includes basic information about a provider. The URL for provider.json is always the same for all providers (`http://DOMAIN/provider.json`). This is the basic 'bootstrap' file that informs the user agent what URLs to use for the other actions. -JSON files are always in UTF8. When loaded in the browser, they are not displayed in UTF8, so non-ascii characters look off, but the files are correct. +This request MUST be made no more than ONCE. All subsequent requests to update @provider.json@ must be made to @GET API_BASE/provider.json@. -Here is an example `provider.json` (from https://demo.bitmask.net/provider.json): +Here is an example @provider.json@ (from [[https://demo.bitmask.net/provider.json]]): -bc.. { +<pre> +{ "api_uri": "https://api.demo.bitmask.net:4430", "api_version": "1", "ca_cert_fingerprint": "SHA256: 0f17c033115f6b76ff67871872303ff65034efe7dd1b910062ca323eb4da5c7e", @@ -47,13 +62,15 @@ bc.. { "openvpn" ] } +</pre> -p. In this document, `API_BASE` consists of `api_uri/api_version` -TODO: define a schema for this file. +h3. GET API_BASE/provider.json + +Used for checking for updates to @provider.json@ after the initial bootstrap @provider.json@ has been loaded from @GET DOMAIN/provider.json@. h3. GET API_BASE/configs.json -For each supported service code, `configs.json` lists the available configuration file. The service codes are listed in "services" in `provider.json`. A provider can use whatever service codes they want, but the user agent will only respond to the ones that it understands. +A request to @configs.json@ lists the available configuration files. The available service codes are listed in "services" in @provider.json@. A provider can use whatever service codes they want, but the user agent will only respond to the ones that it understands. For example: @@ -67,18 +84,21 @@ bc.. { h3. GET API_BASE/config/eip-service.json -e.g. https://api.bitmask.net:4430/1/config/eip-service.json +e.g. [[https://api.bitmask.net:4430/1/config/eip-service.json]] This file defines the "encrypted internet proxy" capabilities and gateways. The actual URL that should be used to fetch this is specified in the response from @/1/configs.json@. -h2. Keys +h2. Provider Keys + +h3. GET ca_cert_uri -h3. GET /ca.crt +e.g. [[https://demo.bitmask.net/ca.crt]] -e.g. https://bitmask.net/ca.crt +The value for @ca_cert_uri@ is contained in @provider.json@. -This is the CA certificate for the provider. It is used to validate servers when not using the web browser. In particular, for OpenVPN. The URL for this is the same for all providers. The fingerprint for this CA cert should be distributed with the client whenever possible. +This request returns the file @ca.crt@, the provider's self-signed CA certificate. *Every* TLS connection with the provider API is validated using this CA certificate. The one exception is when the client is downloading @ca_cert_uri@ for the first time AND when @ca_cert_uri@ specifies an API URL. +After this file is downloaded, it's fingerprint MUST be checked against the value @ca_cert_fingerprint@ in @provider.json@. h1. REST API @@ -88,14 +108,14 @@ The API_BASE for the webapp API is constructed from 'api_uri' and 'api_version' For example, given this in provider.json: -<code> +<pre> { "api_uri": "https://api.bitmask.net:4430", "api_version": "1", } -</code> +</pre> -The API_BASE would be https://api.bitmask.net:4430/1 +The API_BASE would be [[https://api.bitmask.net:4430/1]] The API_VERSION will increment if breaking changes to the api are made. The API might be enhanced without incrementing the version. For Version 1 this may include sending additional data in json responses. @@ -108,7 +128,7 @@ Starts authentication process (values A and B are part of the two step SRP authe <table class="table table-bordered table-striped"> <thead> <tr> - <th colspan="2">POST API / sessions(.json)</th> + <th colspan="2">POST API_BASE/sessions(.json)</th> </tr> </thead> <tr> @@ -126,7 +146,7 @@ If the query_params leave out the @A@, then no @B@ will be included and only the <table class="table table-bordered table-striped"> <thead> <tr> - <th colspan="2">POST API / sessions(.json)</th> + <th colspan="2">POST API_BASE/sessions(.json)</th> </tr> </thead> <tr> @@ -146,7 +166,7 @@ Finishes authentication handshake, after which the user is successfully authenti <table class="table table-bordered table-striped"> <thead> <tr> - <th colspan="2">PUT API / sessions/:login(.json)</th> + <th colspan="2">PUT API_BASE/sessions/:login(.json)</th> </tr> </thead> <tr> @@ -182,7 +202,7 @@ Destroy the current session and invalidate the token. Requires authentication. <table class="table table-bordered table-striped"> <thead> <tr> - <th colspan="2">DELETE API / logout(.json)</th> + <th colspan="2">DELETE API_BASE/logout(.json)</th> </tr> </thead> <tr> @@ -195,16 +215,16 @@ Destroy the current session and invalidate the token. Requires authentication. </tr> </table> -h2. Certificates +h2. User Certificates h3. Get a VPN client certificate -The client certificate will be a "free" cert unless client is authenticated. +The client certificate will be a "free" cert unless client is authenticated. This certificate includes no identifying information that associates it with the user. Depending on the service level of the user, the certificate may have a common name that indicates that the certificate is valid for rate limited or unlimited bandwidth. <table class="table table-bordered table-striped"> <thead> <tr> - <th colspan="2">POST API / cert</th> + <th colspan="2">POST API_BASE/cert</th> </tr> </thead> <tr> @@ -217,12 +237,12 @@ The response also includes the corresponding private key. h3. Get a SMTP client certificate -The client certificate will include the user's email address and the fingerprint will be stored with the users identity and the date it was created. Authentication is required. +The client certificate will include the user's email address and the fingerprint will be stored with the users identity and the date it was created. This is so that a provider can shut down a user's account if it is sending large amounts of Spam. Authentication is required. <table class="table table-bordered table-striped"> <thead> <tr> - <th colspan="2">POST API / smtp_cert</th> + <th colspan="2">POST API_BASE/smtp_cert</th> </tr> </thead> <tr> @@ -231,7 +251,7 @@ The client certificate will include the user's email address and the fingerprint </tr> </table> -The response also includes the corresponding private key. +The response also includes the corresponding private key, PEM encoded. h2. Users @@ -242,7 +262,7 @@ Create a new user. <table class="table table-bordered table-striped"> <thead> <tr> - <th colspan="2">POST API / users(.json)</th> + <th colspan="2">POST API_BASE/users(.json)</th> </tr> </thead> <tr> @@ -262,7 +282,7 @@ Update information about the user. Requires Authentication. <table class="table table-bordered table-striped"> <thead> <tr> - <th colspan="2">PUT API /users/:uid(.json)</th> + <th colspan="2">PUT API_BASE/users/:uid(.json)</th> </tr> </thead> <tr> @@ -280,3 +300,28 @@ Possible parameters to update: * @login@ (requires @password_verifier@) * @password_verifier@ combined with @salt@ * @public_key@ + +h1. Rules + +*One-time bootstrap*: The file @DOMAIN/provider.json@ should be requested at most ONCE. If a provider.json file already exists in the code base (a "pre-seeded" provider), then this bootstrap request MUST NOT be made, ever. + +*Updating provider.json*: The client should check for updates to @provider.json@ on a regular basis, but no more than once per day. This regular update check MUST be performed using the @api_uri@ contained in the current @provider.json@, but never using the @DOMAIN/provider.json@ URL that is used only for the one-time bootstrap. + +*Updating ca.crt*: The stored self-signed CA certificate ca.crt MUST be redownloaded when, and ONLY when, the fingerprint value @ca_cert_fingerprint@ in @provider.json@ changes. + +*Updating service configs*: All service configs should be checked for updates on a regular basis, but no more than once per day. + +*TLS Certificate Validation*: There are two types of TLS connections for Bonafide: + +# DOMAIN connections: These connections must be over TLS and the server's TLS certificate must be validated using an established Certificate Authority. The primary example is the one-time bootstrap request to @DOMAIN/provider.json@. It is also possible that the @ca_cert_uri@ may include DOMAIN. +# API connections: These connections, to @api_uri@ value specified in @provider.json@, MUST use TLS and the server's TLS certificate MUST be validated ONLY using the provider's CA certificate, @ca.crt@. The one exception is if the @ca_cert_uri@ points to an @api_uri@ address. In this one case, there might be no way to authenticate the server's TLS certificate and the connection should proceed without any validation (the client must still check the fingerprint on the subsequently downloaded CA certificate). + +h1. TODO + +Changes that should be made for future versions: + +* Get rid of DOMAIN/provider.json. Instead, replace it with a more minimal DOMAIN/bootstrap.json that includes just the API url, CA url, and CA cert fingerprint. Why? it makes it easier to have a minimal bootstrap.json file for when you need to manually put this file in place on your webserver. The full provider.json can be loaded from the API. +* Actually, lets change the name of provider.json to something else. It is confusing, since there is a different provider.json that the sysadmins edit. We could call the bonafide one 'provider-information.json' or something. +* There should be support for multiple CA certificates. +* Unify the file format for specifying servers. Currently, different service configs use different formats. +* Add JSON schema.
\ No newline at end of file |