path: root/pages/docs/design/bonafide.text

@title = 'Bonafide'
@summary = 'Secure user registration, authentication, and provider discovery.'
@toc = true

h1. Introduction

Bonafide is a protocol that allows a user agent to communicate with a service provider. It includes the following capabilities:

* Discover basic information about a provider.
* Register a new account with a provider.
* Discover information about all the services offered by a provider.
* Authenticate with a provider.
* Destroy a user account.

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

*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.

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]]):

<pre>
{
  "api_uri": "https://api.demo.bitmask.net:4430",
  "api_version": "1",
  "ca_cert_fingerprint": "SHA256: 0f17c033115f6b76ff67871872303ff65034efe7dd1b910062ca323eb4da5c7e",
  "ca_cert_uri": "https://demo.bitmask.net/ca.crt",
  "default_language": "en",
  "description": {
    "en": "A demonstration provider."
  },
  "domain": "demo.bitmask.net",
  "enrollment_policy": "open",
  "languages": [
    "en"
  ],
  "name": {
    "en": "Bitmask"
  },
  "services": [
    "openvpn"
  ]
}
</pre>

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

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:

bc.. {
  "services":{
    "soledad":"/1/configs/soledad-service.json",
    "eip":"/1/configs/eip-service.json",
    "smtp":"/1/configs/smtp-service.json"
  }
}

h3. GET API_BASE/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. Provider Keys

h3. GET $ca_cert_uri

e.g. [[https://demo.bitmask.net/ca.crt]]

The value for @ca_cert_uri@ is contained in @provider.json@.

This request returns the file @ca.crt@, the provider's self-signed CA certificate.

If @ca_cert_uri@ specifies an HTTPS connection, the client must allow TLS connections even if the authenticity of the server certificate cannot be established. This is the only request where the authenticity of the TLS certificate can (and should) be ignored. Instead, after this file is downloaded, it's fingerprint MUST be checked against the value @ca_cert_fingerprint@ in @provider.json@.

h1. REST API

h2. Version

The API_BASE for the webapp API is constructed from 'api_uri' and 'api_version' from provider.json.

For example, given this in provider.json:

<pre>
{
  "api_uri": "https://api.bitmask.net:4430",
  "api_version": "1",
}
</pre>

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.

h2. Session

h3. Handshake

Starts authentication process (values A and B are part of the two step SRP authentication process).

<table class="table table-bordered table-striped">
<thead>
  <tr>
    <th colspan="2">POST API_BASE/sessions(.json)</th>
  </tr>
</thead>
<tr>
  <td>Query params:</td>
  <td>@{"A": "12…345", "login": "swq055"}@</td>
</tr>
<tr>
  <td>Response:</td>
  <td>200 @{"B": "17…651", "salt": "A13CDE"}@</td>
</tr>
</table>

If the query_params leave out the @A@, then no @B@ will be included and only the salt for the given login send out:

<table class="table table-bordered table-striped">
<thead>
  <tr>
    <th colspan="2">POST API_BASE/sessions(.json)</th>
  </tr>
</thead>
<tr>
  <td>Query params:</td>
  <td>@{"login": "swq055"}@</td>
</tr>
<tr>
  <td>Response:</td>
  <td>200 @{"salt": "A13CDE"}@</td>
</tr>
</table>

h3. Authenticate

Finishes authentication handshake, after which the user is successfully authenticated (assuming no errors). This needs to be run after the Handshake.

<table class="table table-bordered table-striped">
<thead>
  <tr>
    <th colspan="2">PUT API_BASE/sessions/:login(.json)</th>
  </tr>
</thead>
<tr>
  <td>Query params:</td>
  <td>@{"client_auth": "123…45", "A": "12…345"}@</td>
</tr>
<tr>
  <td>Response:</td>
  <td>200 @{"M2": "A123BC", "id": "234863", "token": "Aenfw893-zh"}@</td>
</tr>
<tr>
  <td>Error Response:</td>
  <td>500 @{"field":"password","error":"wrong password"}@</td>
</tr>
</table>

Variables:

* *A*: same as A param from the first Handshake request (POST).
* *client_auth*: SRP authentication value M, calculated by client.
* *M2*: Server response for SRP.
* *id*: User id for updating user record
* *token*: Unique identifier used to authenticate the user (until the session expires).

h3. Token Authentication

Tokens returned by the authentication request are used to authenticate further requests to the API and stored as a Hash in the couch database. Soledad directly queries the couch database to ensure the authentication of a user. It compares a hash of the token to the one stored in the database. Hashing prevents timing attacks.

h3. Logout

Destroy the current session and invalidate the token. Requires authentication.

<table class="table table-bordered table-striped">
<thead>
  <tr>
    <th colspan="2">DELETE API_BASE/logout(.json)</th>
  </tr>
</thead>
<tr>
  <td>Query params:</td>
  <td>@{"login": "swq055"}@</td>
</tr>
<tr>
  <td>Response:</td>
  <td>204 NO CONTENT</td>
</tr>
</table>

h2. User Certificates

h3. Get a VPN client certificate

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_BASE/cert</th>
  </tr>
</thead>
<tr>
  <td>Response:</td>
  <td>200 @PEM ENCODED CERT@</td>
</tr>
</table>

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. 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_BASE/smtp_cert</th>
  </tr>
</thead>
<tr>
  <td>Response:</td>
  <td>200 @PEM ENCODED CERT@</td>
</tr>
</table>

The response also includes the corresponding private key, PEM encoded.

h2. Users

h3. Signup

Create a new user.

<table class="table table-bordered table-striped">
<thead>
  <tr>
    <th colspan="2">POST API_BASE/users(.json)</th>
  </tr>
</thead>
<tr>
  <td>Query params:</td>
  <td>@{"user[password_salt]": "5A...21", "user[password_verifier]": "12...45", "user[login]": "that_s_me"}@</td>
</tr>
<tr>
  <td>Response:</td>
  <td>200 @{"password_salt":"5A...21","login":"that_s_me"}@</td>
</tr>
</table>

h3. Update user record

Update information about the user. Requires Authentication.

<table class="table table-bordered table-striped">
<thead>
  <tr>
    <th colspan="2">PUT API_BASE/users/:uid(.json)</th>
  </tr>
</thead>
<tr>
  <td>Query params:</td>
  <td>@{"user[param1]": "value1", "user[param2]": "value2" }@</td>
</tr>
<tr>
  <td>Response:</td>
  <td>204 @NO CONTENT@</td>
</tr>
</table>

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.