[GNUnet-SVN] [taler-anastasis] 01/05: Combined PolicyDocument and KeyShare in EncryptedRecoveryDocument

[gnunet]

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

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

commit 742e9db57eba64ea9ea3837ae6d6bc260578398d
Author: Dennis Neufeld <address@hidden>
AuthorDate: Wed Aug 28 11:36:57 2019 +0200

    Combined PolicyDocument and KeyShare in EncryptedRecoveryDocument
---
 src/api/api-anastasis.rst | 183 ++++++++++++++--------------------------------
 1 file changed, 56 insertions(+), 127 deletions(-)

diff --git a/src/api/api-anastasis.rst b/src/api/api-anastasis.rst
index 48d2e5d..6ad765a 100644
--- a/src/api/api-anastasis.rst
+++ b/src/api/api-anastasis.rst
@@ -50,18 +50,18 @@ 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]
 
   Get the customer's policy and encrypted master key share data.  The
   response must begin with an ephemeral ECDHE public key and continue
@@ -69,7 +69,7 @@ EdDSA public key.
   policy and the encrypted master public key. 
 
   :status 200 OK:
-    The escrow provider responds with an `EncryptedPolicyDocument`_ object. 
This request should
+    The escrow provider responds with an `EncryptedRecoveryDocument`_ object. 
This request should
     virtually always be successful, if the account exists.
 
   X-Anastasis-Version: $NUMBER --- return actual version number in header;
@@ -77,22 +77,39 @@ EdDSA public key.
     
   **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 {
+      // ECDHE public key used to encrypt the gzip compressed JSON-encoded 
`KeyShare`_.
+      ephemeral_pub: EddsaPublicKey;
+
+      // Authentication tag
+      aes_gcm_tag: byte[32];
+      policy_doc: PolicyDocument;
+
+      // Variable-size encrypted key-share. After decryption,
+      // this contains a gzip compressed JSON-encoded `KeyShare`_.
+      enc_keyshare: byte[]; 
+      
+    }
+
   .. _PolicyDocument:
   .. code-block:: tsref
 
@@ -110,6 +127,28 @@ EdDSA public key.
 
     }
 
+  .. _KeyShare:
+  .. code-block:: tsref
+       
+    interface KeyShare {
+      // 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, ...
+      key? : byte[];
+
+      // 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;
+
+      // signature over method, uuid, and hash of truth / truth-mime and/or 
key.
+      account_sig: EdDSA-Signature;
+      
+    }
+
   .. _EscrowMethod:
   .. code-block:: tsref
 
@@ -144,7 +183,7 @@ EdDSA public key.
     }
 
 
-.. http:post:: /policy/$ACCOUNT_PUB
+.. http:post:: /escrow/$ACCOUNT_PUB
 
    Body as in GET.
    Plus:
@@ -153,119 +192,9 @@ EdDSA public key.
    Otherwise, store new version.
    
 
-.. _escrow:
-
----------------------------
-Manage key share for escrow
----------------------------
-
-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
-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:**
-
-  :status 200 OK:
-    Key share stored successfully.
-  :status 400 Bad Request:
-    Request wasn't built properly.
-  :status 402 Payment Required:
-    Payment Required.
-  :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:
-  .. code-block:: tsref
-       
-    interface KeyShare {
-      // 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, ...
-      key? : byte[];
-
-      // 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;
-
-      // signature over method, uuid, and hash of truth / truth-mime and/or 
key.
-      account_sig: EdDSA-Signature;
-      
-    }
-
-
-.. 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
-    
+.. _truth:
 
-  **Details:**
-
-  .. _EscrowRecoveryRequest:
-  .. code-block:: tsref
-       
-    interface EscrowRecoveryRequest {
-      // Escrow recovery nonce
-      nonce: byte[32];
+----------------
+Upload the truth 
+----------------
 
-      // 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.