[GNUnet-SVN] [taler-anastasis] branch master updated (c7107be -> 25c293d)

[gnunet]

This is an automated email from the git hooks/post-receive script.

dennis-neufeld pushed a change to branch master
in repository anastasis.

    from c7107be  Corrected some terminology. Inserted possibility to obtain 
salt of the provider
     new 742e9db  Combined PolicyDocument and KeyShare in 
EncryptedRecoveryDocument
     new 08edc08  Added more general information about the keys to use.
     new 78284cb  Added Truth. Status Codes are missing yet.
     new 1e318bf  Added some states to the get request
     new 25c293d  Added EscrowChallenge and states to truth api.

The 5 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 src/api/api-anastasis.rst | 204 +++++++++++++++++++++++-----------------------
 1 file changed, 103 insertions(+), 101 deletions(-)

diff --git a/src/api/api-anastasis.rst b/src/api/api-anastasis.rst
index 48d2e5d..2d4ec23 100644
--- a/src/api/api-anastasis.rst
+++ b/src/api/api-anastasis.rst
@@ -20,9 +20,22 @@
 ==============================
 The Anastasis RESTful JSON API
 ==============================
+**Anastasis** is a service that allows the user to securely deposit a master 
password with an escrow provider 
+and recover it if it is lost. An "unforgettable" secret is used, e.g. the AHV 
number for Swiss citizens. 
+Necessary keys are derived from this "secret" using different HKDFs (see 
below).
 
-The API specified here follows the :ref:`general conventions <http-common>`
-for all details not specified in the individual requests.
+The service uses an EdDSA escrow key to identify the "account" of the user. 
The escrow key is Crockford 
+Base32-encoded in the URI to access the data and used to sign requests as well 
as to encrypt the contents. 
+These signatures are provided in detached form as HTTP headers.
+
+To make a possible attack more difficult, we use different expensive hash 
functions to generate different private keys: 
+
+* escrow key for the "account", signing and for deriving ECDHE public keys 
used to encrypt the payload: H_1
+* Key for deriving ECDHE public keys used to encrypt the key share: H_2
+
+The symmetric keys used for encryption must be generated as follows: First, an 
ECDHE public key is derived 
+from the corresponding private key. Using ECDH, the private key and the 
derived public key form the symmetric key to be used. 
+For symmetric encryption we use AES-GCM.
 
 For security reasons, we assume that the service is only accessed over TLS.
 
@@ -50,49 +63,81 @@ Obtain salt
       salt: string;
     }
 
-.. _policy:
+.. _escrow:
 
--------------
-Manage policy
--------------
+-------------------------
+Manage policy + key-share
+-------------------------
 
-This API is used by Anastasis clients to obtain or upload policies and the 
corresponding encrypted masterkey from/to the escrow provider.
+This API is used by the Anastasis client to deposit or request the 
policy/policies plus the desired key-share with the escrow provider.
 The client is identified and authorized by $ACCOUNT_PUB, which should be kept 
secret from third parties. $ACCOUNT_PUB should be an
 EdDSA public key. 
 
 
-.. http:get:: /policy/$ACCOUNT_PUB[?version=$NUMBER]
+.. http:get:: /escrow/$ACCOUNT_PUB[?version=$NUMBER&uuid=$UUID]
 
   Get the customer's policy and encrypted master key share data.  The
   response must begin with an ephemeral ECDHE public key and continue
   with an AES-GCM encrypted payload and tag containing the escrow
-  policy and the encrypted master public key. 
+  policy, the encrypted master public key and the encrypted key-share. 
 
   :status 200 OK:
-    The escrow provider responds with an `EncryptedPolicyDocument`_ object. 
This request should
-    virtually always be successful, if the account exists.
+    The escrow provider responds with an `EncryptedRecoveryDocument`_ object.
+  :status 302 Found:
+    The Provider redirects for authentication (i.e. video 
identification/WebRTC).
+  :status 303 See Other:
+    The escrow provider responds with an EscrowChallenge_ object.
+  :status 304 Not Modified:
+    Empty body, the escrow provider will respond out-of-band (i.e. SMS).
+  :status 402 Payment Required:
+    Payment Reequired.
+  :status 404 Not Found:
+    The requested resource was not found.
+
+  *X-Anastasis-Version*: $NUMBER --- return actual version number in header;
+  (if not specified in request, return EscrowChallenge_ according to specified 
&UUID or return
+  EscrowChallenge_ according to the latest version. If status 200 OK: Return 
EncryptedRecoveryDocument_ 
+  according to specified version respectively the latest the version).
 
-  X-Anastasis-Version: $NUMBER --- return actual version number in header;
-  (if not specified in request, return latest).
+  *X-Anastasis-UUID*: $UUID --- return actual uuid in header;
+  (if not specified in request, return EscrowChallenge_ according to specified 
version &NUMBER respectively the latest version).
     
   **Details:**
  
-  .. _EncryptedPolicyDocument:
+  .. _EncryptedRecoveryDocument:
   .. code-block:: tsref
 
-    interface EncryptedPolicyDocument {
-      // ECDHE public key used to encrypt the payload
+    interface EncryptedRecoveryDocument {
+      // ECDHE public key used to encrypt the gzip compressed JSON-encoded 
`RecoveryDocument`_.
       ephemeral_pub: EddsaPublicKey;
 
       // Authentication tag
       aes_gcm_tag: byte[32];
 
-      // Variable-size encrypted policy document. After decryption,
-      // this contains a gzip compressed JSON-encoded `PolicyDocument`_.
+      // Variable-size encrypted recovery document. After decryption,
+      // this contains a gzip compressed JSON-encoded `RecoveryDocument`_.
       body: byte[]
 
     }
 
+  .. _RecoveryDocument:
+  .. code-block:: tsref
+
+    interface RecoveryDocument {
+      policy_doc: PolicyDocument;
+      
+      // ECDHE public key used to encrypt the gzip compressed JSON-encoded 
`KeyShare`_.
+      ephemeral_pub: EddsaPublicKey;
+
+      // Authentication tag
+      aes_gcm_tag: byte[32];
+
+      // Variable-size encrypted key-share. After decryption,
+      // this contains a gzip compressed JSON-encoded `KeyShare`_.
+      enc_keyshare: byte[]; 
+
+    }
+
   .. _PolicyDocument:
   .. code-block:: tsref
 
@@ -110,6 +155,17 @@ EdDSA public key.
 
     }
 
+  .. _KeyShare:
+  .. code-block:: tsref
+       
+    interface KeyShare {
+      // the explicit key to reveal, if method is one of SMS, e-mail, ...
+      key-share : byte[];
+
+      salt: byte[32];
+
+    }
+
   .. _EscrowMethod:
   .. code-block:: tsref
 
@@ -143,8 +199,21 @@ EdDSA public key.
 
     }
 
+  .. _EscrowChallenge:
+  .. code-block:: tsref
+
+    interface EscrowChallenge {
+      // ground truth, i.e. challenge question,
+      // phone number, e-mail address, picture, fingerprint, ...
+      truth: byte[];
+
+      // mime type of truth, i.e. text/ascii, image/jpeg, etc.
+      truth_mime: string;
+    
+    }
+
 
-.. http:post:: /policy/$ACCOUNT_PUB
+.. http:post:: /escrow/$ACCOUNT_PUB
 
    Body as in GET.
    Plus:
@@ -153,47 +222,40 @@ EdDSA public key.
    Otherwise, store new version.
    
 
-.. _escrow:
+.. _truth:
 
----------------------------
-Manage key share for escrow
----------------------------
+----------------
+Upload the truth 
+----------------
 
-This API is used by Anastasis clients to share a key share with the
-key provider. The client is identified and authorized by $ACCOUNT_PUB, 
-which should be kept secret from third parties. $ACCOUNT_PUB should be an
+This API is used by the Anastasis client to deposit or request the truth with 
the escrow provider.
+The client is identified and authorized by $ACCOUNT_PUB, which should be kept 
secret from third parties. $ACCOUNT_PUB should be an
 EdDSA public key. 
 
-
-.. http:post:: /escrow/$ACCOUNT_PUB/$UUID
-
-  Send key share to escrow provider.
-
-  **Request:** The request body must be a `KeyShare`_ object.
-
-  **Response:**
-
+.. http:post:: /truth/$ACCOUNT_PUB/$UUID
+    
   :status 200 OK:
     Key share stored successfully.
   :status 400 Bad Request:
-    Request wasn't built properly.
+    Request wasn’t built properly.
   :status 402 Payment Required:
-    Payment Required.
+    Payment Reequired.
   :status 412 Precondition Failed:
     The selected authentication Method is not supported on this provider.
   :status 503 Service Unavailable:
     Server is out of Service.
-    
+
   **Details:**
 
-  .. _KeyShare:
+  .. _Truth:
   .. code-block:: tsref
-       
-    interface KeyShare {
+
+    interface Truth {
       // Key share method, i.e. "security question", "SMS", "e-mail", ...
       method: String;
 
       // the explicit key to reveal, if method is one of SMS, e-mail, ...
+      // If not defined, the provider provides a key himself, unless the 
method is a secure question.
       key? : byte[];
 
       // ground truth, i.e. challenge question,
@@ -209,63 +271,3 @@ EdDSA public key.
     }
 
 
-.. http:get:: /escrow/$ACCOUNT_PUB/$UUID
-
-  Request masterkey recovery.
-
-  **Request:** The request body must be a `EscrowRecoveryRequest`_ object.
-
-  **Response:**
-
-  :status 200 OK:
-    The key provider responds with a `Recovery`_ object.
-  :status 302 Found:
-    Key provider redirects for authentication (i.e. video 
identification/WebRTC). 
-  :status 303 See Other:
-    The key provider responds with a `EscrowChallenge`_ object.
-  :status 304 Not Modified:
-    Empty body, the key provider will respond out-of-band (i.e. SMS).
-  :status 402 Payment Required:
-    Payment Required 
-  :status 404 Not Found:
-    The requested Ressource was not found
-    
-
-  **Details:**
-
-  .. _EscrowRecoveryRequest:
-  .. code-block:: tsref
-       
-    interface EscrowRecoveryRequest {
-      // Escrow recovery nonce
-      nonce: byte[32];
-
-      // signature over nonce, uuid.
-      account_sig: EdDSA-Signature;
-
-      // Authentication token (i.e. as received via SMS/E-mail)
-      token? : string;
-
-    }
-
-  .. _Recovery:
-  .. code-block:: tsref
-       
-    interface Recovery {
-      // Escrow recovery key
-      key: byte[32];
-
-    }
-
-  .. _EscrowChallenge:
-  .. code-block:: tsref
-       
-    interface EscrowChallenge {
-      // ground truth, i.e. challenge question,
-      // phone number, e-mail address, picture, fingerprint, ... 
-      truth: byte[];
-
-      // mime type of truth, i.e. text/ascii, image/jpeg, etc.
-      truth_mime: string;
-
-    }

-- 
To stop receiving notification emails like this one, please contact
address@hidden.