Improve Bonafide documentation

1 files changed, 16 insertions, 14 deletions

diff --git a/pages/docs/design/bonafide.text b/pages/docs/design/bonafide.text
index 693bba6..df43b57 100644
--- a/pages/docs/design/bonafide.text
+++ b/pages/docs/design/bonafide.text
@@ -12,15 +12,15 @@ Bonafide is a protocol that allows a user agent to communicate with a service pr
 * Authenticate with a provider.
 * Destroy a user account.
 
-Bonafide user SRP (Secure Remote Password) for password-based authentication.
+Bonafide uses 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.
+*DOMAIN* is the primary domain of the provider. This is specified by the user when they enter which 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.crt* is used to denote the provider's self-signed Certificate Authority certificate, which is used to sign all of 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@.
 
@@ -34,7 +34,7 @@ h2. JSON files
 
 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.
+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@.
 
@@ -104,7 +104,7 @@ h1. REST API
 
 h2. Version
 
-The API_BASE for the webapp API is constructed from 'api_uri' and 'api_version' from provider.json.
+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:
 
@@ -123,7 +123,7 @@ h2. Session
 
 h3. Handshake
 
-Starts authentication process (values A and B are part of the two step SRP authentication process).
+The handshake starts the authentication process between a client and a provider. In the following example, values A and B are part of the two-step SRP authentication process.
 
 <table class="table table-bordered table-striped">
 <thead>
@@ -141,7 +141,7 @@ Starts authentication process (values A and B are part of the two step SRP authe
 </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:
+If the query_params leaves out the @A@ parameter, then no @B@ parameter will be included in the response and only the salt for the given login will be sent in the reply.
 
 <table class="table table-bordered table-striped">
 <thead>
@@ -161,7 +161,7 @@ If the query_params leave out the @A@, then no @B@ will be included and only the
 
 h3. Authenticate
 
-Finishes authentication handshake, after which the user is successfully authenticated (assuming no errors). This needs to be run after the Handshake.
+Finishes the authentication handshake, after which the user will be successfully authenticated assuming there were no errors in the process. This needs to be run after the Handshake.
 
 <table class="table table-bordered table-striped">
 <thead>
@@ -193,7 +193,9 @@ Variables:
 
 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.
+Tokens returned by the authentication request are used to authenticate further requests to the API, and are stored as a hash in the Couch database.
+
+Soledad ([[https://leap.se/en/docs/design/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
 
@@ -219,7 +221,7 @@ 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.
+The client certificate will be a "free" certificate unless the requesting 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>
@@ -235,9 +237,9 @@ The client certificate will be a "free" cert unless client is authenticated. Thi
 
 The response also includes the corresponding private key.
 
-h3. Get a SMTP client certificate
+h3. Get an 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.
+The client certificate will include the user's email address and the fingerprint will be stored with the identity of the user as well as 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 in order to receive an SMTP client certificate.
 
 <table class="table table-bordered table-striped">
 <thead>
@@ -277,7 +279,7 @@ Create a new user.
 
 h3. Update user record
 
-Update information about the user. Requires Authentication.
+Update information about the user. Requires authentication.
 
 <table class="table table-bordered table-striped">
 <thead>
@@ -324,4 +326,4 @@ Changes that should be made for future versions:
 * 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
+* Add JSON schema.