Merge branch 'master' of git+ssh://git.taler.net/docs

1 files changed, 43 insertions, 43 deletions

diff --git a/anastasis.rst b/anastasis.rst
index 2fc9bee2..78a7b166 100644
--- a/anastasis.rst
+++ b/anastasis.rst
@@ -51,7 +51,7 @@ A **recovery document** includes all of the information a user needs to
 recover access to their core secret.  It specifies a set of **escrow
 methods**, which specify how the user should convince the Anastasis server
 that they are "real".  Escrow methods can for example include SMS-based
-verification, Video-identification or a security question.  For each escrow
+verification, video identification or a security question.  For each escrow
 method, the Anastasis server is provided with **truth**, that is data the
 Anastasis operator may learn during the recovery process to authenticate the
 user.  Examples for truth would be a phone number (for SMS), a picture of the
@@ -136,9 +136,9 @@ information as the **identifier**.
 This identifier will be first hashed with Argon2, to provide a **kdf_id**
 which will be used to derive other keys later. The Hash must also include the
 respective **server_salt**. This also ensures that the **kdf_id** is different
-on each server. The use of Argon2 and the respective server_salt is intended
-to make it difficult to brute-force **kdf_id** values and help protect user's
-privacy. Also this ensures that the kdf_ids on every server differs. However,
+on each server. The use of Argon2 and the respective **server_salt** is intended
+to make it difficult to brute-force **kdf_id** values and help protect the user's
+privacy. Also this ensures that the **kdf_id**\ s on every server differs. However,
 we do not assume that the **identifier** or the **kdf_id** cannot be
 determined by an adversary performing a targeted attack, as a user's
 **identifier** is likely to always be known to state actors and may
@@ -151,7 +151,7 @@ likely also be available to other actors.
 
 **identifier**: The secret defined from the user beforehand.
 
-**server_salt**: The salt from the Server
+**server_salt**: The salt from the Server.
 
 **keysize**: The desired output size of the KDF, here 32 bytes.
 
@@ -162,7 +162,7 @@ Verification
 For users to authorize "policy" operations we need an EdDSA key pair.  As we
 cannot assure that the corresponding private key is truly secret, such policy
 operations must never be destructive: Should an adversary learn the private
-key, they could access (and with the kdf_id decrypt) the user's policy (but
+key, they could access (and with the **kdf_id** decrypt) the user's policy (but
 not the core secret), or upload a new version of the
 **encrypted recovery document** (but not delete an existing version).
 
@@ -175,7 +175,7 @@ HKDF to ensure that the result differs from other cases where we hash
 
 ::
 
-    ver_secret:= HKDF(kdf_id, "ver", keysize)
+    ver_secret := HKDF(kdf_id, "ver", keysize)
     eddsa_priv := eddsa_d_to_a(ver_secret)
     eddsa_pub := get_EdDSA_Pub(eddsa_priv)
 
@@ -186,7 +186,7 @@ HKDF to ensure that the result differs from other cases where we hash
 
 **key_size**: Size of the output, here 32 bytes.
 
-**ver_secret**: Derived key from the kdf_id, serves as intermediate step for the generation of the private key
+**ver_secret**: Derived key from the kdf_id, serves as intermediate step for the generation of the private key.
 
 **eddsa_d_to_a()**: Function which converts the ver_key to a valid EdDSA private key. Specifically, assuming the value eddsa_priv is in a 32-byte array "digest", the function clears and sets certain bits as follows:
 
@@ -214,11 +214,11 @@ key material using an HKDF over a nonce and the kdf_id.
 
 **HKDF()**: The HKDF-function uses two phases: First we use HMAC-SHA512 for the extraction phase, then HMAC-SHA256 is used for expansion phase.
 
-**kdf_id**: Hashed identifier
+**kdf_id**: Hashed identifier.
 
-**keysize**: Size of the AES symmetric key, here 32 bytes
+**keysize**: Size of the AES symmetric key, here 32 bytes.
 
-**ivsize**: Size of the AES GCM IV, here 12 bytes
+**ivsize**: Size of the AES GCM IV, here 12 bytes.
 
 **prekey**: Original key material.
 
@@ -227,7 +227,7 @@ avoid key reuse. So, we have to use different nonces to get different keys and i
 
 **key**: Symmetric key which is later used to encrypt the documents with AES256-GCM.
 
-**iv**: IV which will be used for AES-GCM
+**iv**: IV which will be used for AES-GCM.
 
 
 ---------
@@ -267,7 +267,7 @@ Nonce must contain the string "ERD".
 Here, **i** must be a positive number used to iterate over the various **key shares** used for the various **escrow methods**
 at the various providers.
 
-**nonce_i**: Nonce which is used to generate *key_i* and *iv_i* which are used for the encryption of the *key share*. **i** must be
+**nonce_i**: Nonce which is used to generate *key_i* and *iv_i* which are used for the encryption of the **key share**. **i** must be
 the same number as specified above for *encrypted_key_share_i*. Nonce must contain the string "EKS" plus the according *i*.
 
 Signatures
@@ -282,7 +282,7 @@ algorithm is equivalent for **Anastasis-Policy-Signature**.
     (anastasis-account-signature) = eddsa_sign(h_body, eddsa_priv)
     ver_res = eddsa_verifiy(h_body, anastasis-account-signature, eddsa_pub)
 
-**anastasis-account-signature**: Signature over the SHA-512 hash of the body using the purpose code TALER_SIGNATURE_ANASTASIS_POLICY_UPLOAD (1400) (see GNUnet EdDSA signature API for the use of purpose)
+**anastasis-account-signature**: Signature over the SHA-512 hash of the body using the purpose code ``TALER_SIGNATURE_ANASTASIS_POLICY_UPLOAD`` (1400) (see GNUnet EdDSA signature API for the use of purpose).
 
 **h_body**: The hashed body.
 
@@ -296,7 +296,7 @@ When requesting policy downloads, the client must also provide a signature:
     (anastasis-account-signature) = eddsa_sign(version, eddsa_priv)
     ver_res = eddsa_verifiy(version, anastasis-account-signature, eddsa_pub)
 
-**anastasis-account-signature**: Signature over the SHA-512 hash of the body using the purpose code TALER_SIGNATURE_ANASTASIS_POLICY_DOWNLOAD (1401) (see GNUnet EdDSA signature API for the use of purpose)
+**anastasis-account-signature**: Signature over the SHA-512 hash of the body using the purpose code ``TALER_SIGNATURE_ANASTASIS_POLICY_DOWNLOAD`` (1401) (see GNUnet EdDSA signature API for the use of purpose).
 
 **version**: The version requested as a 64-bit integer, 2^64-1 for the "latest version".
 
@@ -309,7 +309,7 @@ Availability Considerations
 
 Anastasis considers two main threats against availability. First, the
 Anastasis server operators must be protected against denial-of-service attacks
-where an adversary attempts to exhaust operator's resources.  The API protects
+where an adversary attempts to exhaust the operator's resources.  The API protects
 against these attacks by allowing operators to set fees for all
 operations. Furthermore, all data stored comes with an expiration logic, so an
 attacker cannot force servers to store data indefinitely.
@@ -448,10 +448,10 @@ Manage policy
 This API is used by the Anastasis client to deposit or request encrypted
 recovery documents with the escrow provider.  Generally, a client will deposit
 the same encrypted recovery document with each escrow provider, but provide
-different truth to each escrow provider.
+a different truth to each escrow provider.
 
-Operations by the client are identified and authorized by $ACCOUNT_PUB, which
-should be kept secret from third parties. $ACCOUNT_PUB should be an account
+Operations by the client are identified and authorized by ``$ACCOUNT_PUB``, which
+should be kept secret from third parties. ``$ACCOUNT_PUB`` should be an account
 public key using the Crockford base32-encoding.
 
 In the following, UUID is always defined and used according to `RFC 4122`_.
@@ -501,18 +501,18 @@ In the following, UUID is always defined and used according to `RFC 4122`_.
 
   *Etag*: Set by the server to the Base32-encoded SHA512 hash of the body. Used for caching and to prevent redundancies. The server MUST send the Etag if the status code is 200 OK.
 
-  *If-None-Match*: If this is not the very first request of the client, this contains the Etag-value which the client has reveived before from the server.
+  *If-None-Match*: If this is not the very first request of the client, this contains the Etag-value which the client has received before from the server.
   The client SHOULD send this header with every request (except for the first request) to avoid unnecessary downloads.
 
-  *Anastasis-Account-Signature*: The client must provide Base-32 encoded EdDSA signature over hash of body with $ACCOUNT_PRIV, affirming desire to download the requested encrypted recovery document.  The purpose used MUST be TALER_SIGNATURE_ANASTASIS_POLICY_DOWNLOAD (1401).
+  *Anastasis-Account-Signature*: The client must provide Base-32 encoded EdDSA signature over hash of body with ``$ACCOUNT_PRIV``, affirming desire to download the requested encrypted recovery document.  The purpose used MUST be ``TALER_SIGNATURE_ANASTASIS_POLICY_DOWNLOAD`` (1401).
 
 .. http:post:: /policy/$ACCOUNT_PUB
 
   Upload a new version of the customer's encrypted recovery document.
   While the document's structure is described in JSON below, the upload
-  should just be the bytestream of the raw data (i.e. 32 bytes nonce followed
-  by 16 bytes tag followed by the encrypted document).
-  If request has been seen before, the server should do nothing, and otherwise store the new version.
+  should just be the bytestream of the raw data (i.e. 32-byte nonce followed
+  by 16-byte tag followed by the encrypted document).
+  If the request has been seen before, the server should do nothing, and otherwise store the new version.
   The body must begin with a nonce, an AES-GCM tag and continue with the ciphertext.  The format
   is the same as specified for the response of the GET method. The
   Anastasis server cannot fully validate the format, but MAY impose
@@ -534,18 +534,18 @@ In the following, UUID is always defined and used according to `RFC 4122`_.
      case.
 
   *If-Match*: Unless the client expects to upload the first encrypted recovery document to this account, the client
-    SHOULD provide an Etag matching the latest version already known to the server.  If this
-    header is present, the server MUST refuse the upload if the latest known version prior to
-    this upload does not match the given Etag.
+  SHOULD provide an Etag matching the latest version already known to the server.  If this
+  header is present, the server MUST refuse the upload if the latest known version prior to
+  this upload does not match the given Etag.
 
   *If-None-Match*: This header MUST be present and set to the SHA512 hash (Etag) of the body by the client.
-    The client SHOULD also set the "Expect: 100-Continue" header and wait for "100 continue"
-    before uploading the body.  The server MUST
-    use the Etag to check whether it already knows the encrypted recovery document that is about to be uploaded.
-    The server MUST refuse the upload with a "304" status code if the Etag matches
-    the latest version already known to the server.
+  The client SHOULD also set the "Expect: 100-Continue" header and wait for "100 continue"
+  before uploading the body.  The server MUST
+  use the Etag to check whether it already knows the encrypted recovery document that is about to be uploaded.
+  The server MUST refuse the upload with a "304" status code if the Etag matches
+  the latest version already known to the server.
 
-  *Anastasis-Policy-Signature*: The client must provide Base-32 encoded EdDSA signature over hash of body with $ACCOUNT_PRIV, affirming desire to upload an encrypted recovery document.
+  *Anastasis-Policy-Signature*: The client must provide Base-32 encoded EdDSA signature over hash of body with ``$ACCOUNT_PRIV``, affirming desire to upload an encrypted recovery document.
 
   *Payment-Identifier*: Base-32 encoded 32-byte payment identifier that was included in a previous payment (see 402 status code). Used to allow the server to check that the client paid for the upload (to protect the server against DoS attacks) and that the client knows a real secret of financial value (as the **kdf_id** might be known to an attacker). If this header is missing in the client's request (or the associated payment has exceeded the upload limit), the server must return a 402 response.  When making payments, the server must include a fresh, randomly-generated payment-identifier in the payment request.
 
@@ -553,12 +553,12 @@ In the following, UUID is always defined and used according to `RFC 4122`_.
 
   :http:statuscode:`204 No content`:
     The encrypted recovery document was accepted and stored.  "Anastasis-Version" and "Anastasis-UUID" headers
-    incidate what version and UUID was assigned to this encrypted recovery document upload by the server.
+    indicate what version and UUID was assigned to this encrypted recovery document upload by the server.
   :http:statuscode:`304 Not modified`:
     The same encrypted recovery document was previously accepted and stored.  "Anastasis-Version" header
-    incidates what version was previously assigned to this encrypted recovery document.
+    indicates what version was previously assigned to this encrypted recovery document.
   :http:statuscode:`400 Bad request`:
-    The $ACCOUNT_PUB is not an EdDSA public key or mandatory headers are missing.
+    The ``$ACCOUNT_PUB`` is not an EdDSA public key or mandatory headers are missing.
     The response body MUST elaborate on the error using a Taler error code in the typical JSON encoding.
   :http:statuscode:`402 Payment required`:
     The account's balance is too low for the specified operation.
@@ -673,7 +673,7 @@ the escrow provider.
 An **escrow method** specifies an Anastasis provider and how the user should
 authorize themself.  The **truth** API allows the user to provide the
 (encrypted) key share to the respective escrow provider, as well as auxiliary
-data required for such an respective escrow method.
+data required for such a respective escrow method.
 
 An Anastasis-server may store truth for free for a certain time period, or
 charge per truth operation using GNU Taler.
@@ -736,10 +736,10 @@ charge per truth operation using GNU Taler.
 
 .. http:get:: /truth/$UUID[?response=$RESPONSE]
 
-  Get the stored encrypted key share. If $RESPONSE is specified by the client, the server checks
-  if $RESPONSE matches the expected response specified before within the TruthUploadRequest_ (see encrypted_truth).
+  Get the stored encrypted key share. If ``$RESPONSE`` is specified by the client, the server checks
+  if ``$RESPONSE`` matches the expected response specified before within the TruthUploadRequest_ (see encrypted_truth).
   Also, the user has to provide the correct *truth_encryption_key* with every get request (see below).
-  When $RESPONSE is correct, the server responses with the encrypted key share.
+  When ``$RESPONSE`` is correct, the server responses with the encrypted key share.
   The encrypted key share is returned simply as a byte array and not in JSON format.
 
   **Response**:
@@ -766,7 +766,7 @@ charge per truth operation using GNU Taler.
     Server is out of Service.
 
   *Truth-Decryption-Key*: Key used to encrypt the **truth** (see encrypted_truth within TruthUploadRequest_) and which has to provided by the user. The key is stored with
-  the according EscrowMethod_. The server needs this key to get the info out of TruthUploadRequest_ needed to verify the $RESPONSE.
+  the according EscrowMethod_. The server needs this key to get the info out of TruthUploadRequest_ needed to verify the ``$RESPONSE``.
 
   **Details:**
 
@@ -2616,7 +2616,7 @@ SMS (sms)
 ^^^^^^^^^
 
 Sends an SMS with a code to the users phone.
-The user must send this code back with his request (see $RESPONSE under 'Managing truth').
+The user must send this code back with his request (see ``$RESPONSE`` under `Managing truth`_).
 If the transmitted code is correct, the server responses with the requested encrypted key share.
 FIXME: details!
 
@@ -2624,7 +2624,7 @@ FIXME: details!
 Email verification (email)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 Sends an email with a code to the users mail address.
-The user must send this code back with his request (see $RESPONSE under 'Managing truth').
+The user must send this code back with his request (see ``$RESPONSE`` under `Managing truth`_).
 If the transmitted code is correct, the server responses with the requested encrypted key share.
 FIXME: details!