[GNUnet-SVN] [taler-anastasis] branch master updated: api work

[gnunet]

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

grothoff pushed a commit to branch master
in repository anastasis.

The following commit(s) were added to refs/heads/master by this push:
     new 1e9cbbf  api work
1e9cbbf is described below

commit 1e9cbbf406b081f095ddcde1cddb6c3b338ee112
Author: Christian Grothoff <address@hidden>
AuthorDate: Fri Aug 2 14:17:52 2019 +0200

    api work
---
 src/api/api-anastasis.rst | 337 +++++++++++++++-------------------------------
 1 file changed, 110 insertions(+), 227 deletions(-)

diff --git a/src/api/api-anastasis.rst b/src/api/api-anastasis.rst
index d284733..7f98d47 100644
--- a/src/api/api-anastasis.rst
+++ b/src/api/api-anastasis.rst
@@ -24,9 +24,9 @@ for all details not specified in the individual requests.
 
 .. _registration:
 
----------------------------
-Register to Escrow Provider
----------------------------
+-------------
+Manage policy
+-------------
 
 This API is used by Anastasis clients to obtain global information about
 the escrow provider, such as online signing keys and the fee
@@ -37,302 +37,185 @@ especially the long-term offline signing key of the 
escrow provider, which clien
 cache; (2) possibly by using HTTPS.
 
 
-.. http:get:: /escrow/registration
+.. http:get:: /policy/$ACCOUNT_PUB[?version=$NUMBER]
 
-  Get the providers's current online signing key.
-
-  **Request:** The request body must be a `RegistrationRequest`_ object.
-
-  :query last_issue_date: optional argument specifying the maximum value of 
any of the "stamp_start" members of the denomination keys of a "/register" 
response that is already known to the client. Allows the exchange to only 
return keys that have changed since that timestamp.  The given value must be an 
unsigned 64-bit integer representing seconds after 1970.  If the timestamp does 
not exactly match the "stamp_start" of one of the denomination keys, all keys 
are returned.
-
-  **Response:**
+  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.
 
   :status 200 OK:
-    The escrow provider responds with a `EscrowInitResponse`_ object. This 
request should
-    virtually always be successful.
+    The escrow provider responds with a `EncryptedPolicyDocument`_ object. 
This request should
+    virtually always be successful, if the account exists.
 
+    X-Anastatis-Version: $NUMBER --- return actual version number in header;
+    (if not specified in request, return latest).
+    
   **Details:**
 
-  .. _EscrowInitResponse:
+  .. _EncryptedPolicyDocument:
   .. code-block:: tsref
 
     interface EscrowInitResponse {
-      // EdDSA master public key of the escrow provider
-      master_public_key: EddsaPublicKey;
+      // ECDHE public key used to encrypt the payload
+      ephemeral_pub: EddsaPublicKey;
 
-      // Relative duration until inactive reserves are closed; not signed, 
expressed as
-      // a string in relative time in microseconds, i.e. "/Delay(1000)/" for 1 
second.
-      reserve_closing_delay: RelativeTime;
+      // Authentication tag
+      aeas_gcm_tag: byte[32];
 
-      // The escrow provider's signing key.
-      signkey: SignKey;
-  
-      // The  hashed and salted identification (e.g. AHV number) of the client.
-      clientId_J: HashedClientId;
+      // Variable-size encrypted policy document. After decryption,
+      // this contains a gzip compressed JSON-encoded `PolicyDocument`_.
+      body: byte[]
 
-      // Some metadata of the client/customer
-      customer: Customer;
-
-      // The type of contract (free or paid abonnement etc.)
-      contractType: String;
     }
 
-  .. note::
-
-      Hash Algorithm for clientId_J must be different from the one used for 
the clientId_I used for the key provider!
-
-.. _policy:
-
----------------------------------
-Send policy to escrow provider
----------------------------------
-
-This API is used by Anastasis clients to send a defined policy for masterkey 
recovery to the escrow provider.
-
-
-.. http:post:: /escrow/policy
+   .. _PolicyDocument:
+   .. code-block:: tsref
 
-  Send a defined policy for masterkey recovery.
-
-  **Request:** The request body must be a `SignedPolicy`_ object.
+    interface EscrowInitResponse {
+      // List of escrow providers and selected authentication method
+      methods: EscrowMethod[];
 
-  **Response:**
+      // List of possible decryption policies
+      policy: DecryptionPolicy[];
 
-  :status 200 OK:
-    The key provider responds with a `PolicyStatus`_ object. This request 
should
-    virtually always be successful.
+      // Account identifier at backup provider, AES-encrypted with
+      // (symmetric) master_key, i.e.
+      // https://sync.taler.net/ + private key
+      backup_account: byte[];
 
-  **Details:**
-
-  .. _PolicyStatus:
-  .. code-block:: tsref
-       
-    interface PolicyStatus {
-      // Message
-      message: String; 
     }
 
----------------------------------
-Get policies from escrow provider
----------------------------------
-
-This API is used by Anastasis clients to get the policies to recovery the 
masterkey.
-
-
-.. http:get:: /escrow/policy
-
-  Get the policies for masterkey recovery.
-
-  **Request:** The request body must be a `PolicyRequest`_ object.
-
-  **Response:**
-
-  :status 200 OK:
-    The key provider responds with a `Policies`_ object. This request should
-    virtually always be successful.
-
-  **Details:**
-
-  .. _Policies:
-  .. code-block:: tsref
-       
-    interface Policies {
-      // Policies
-      policies: Policy[] 
+    interface EscrowMethod {
+      provider_url : string;
+      escrow_method: string;
+      uuid: uuid;
+      salt: byte[32];
     }
 
-.. _masterkey:
-
----------------------------------
-Send masterkey to escrow provider
----------------------------------
-
-This API is used by Anastasis clients to send the encrypted masterkey to the 
escrow provider.
-
-
-.. http:post:: /escrow/masterkey
+    interface DecryptionPolicy {
+      salt: byte[32];
+      // Master key, AES-encrypted with key derived from
+      // salt and secrets revealed by the following list of
+      // escrow methods identified by UUID.
+      master_key: byte[32];
+      uuid: uuid[];
+    }
 
-  Send the masterkey to the escrow provider.
 
-  **Request:** The request body must be a `MasterkeyBackup`_ object.
+.. http:post:: /policy/$ACCOUNT_PUB
 
-  **Response:**
+   Body as in GET.
+   Plus:
+   X-Anastasis-Policy-Signature: $ACCOUNT_SIG (over hash of body with 
$ACCOUNT_PRIV).
+   If request seen before, ignore.
+   Otherwise, store new version.
+   
 
-  :status 200 OK:
-    The key provider responds with a `MasterkeyStatus`_ object. This request 
should
-    virtually always be successful.
-
-  **Details:**
-
-  .. _MasterkeyStatus:
-  .. code-block:: tsref
-       
-    interface MasterkeyStatus {
-      // Message
-      message: String;      
-    }
+.. _escrow:
 
 ---------------------------------
-Obtain masterkey from escrow provider
+Manage key share for escrow
 ---------------------------------
 
-This API is used by Anastasis clients to obtain the encrypted masterkey from 
the escrow provider.
+This API is used by Anastasis clients to share a key share with the
+escrow provider.
 
 
-.. http:get:: /escrow/masterkey
+.. http:post:: /escrow/$ACCOUNT_PUB/$UUID
 
-  Obtain the masterkey from the escrow provider.
+  Send key share to escrow provider.
 
-  **Request:** The request body must be a `MasterkeyRequest`_ object.
+  **Request:** The request body must be a `KeyShare`_ object.
 
   **Response:**
 
   :status 200 OK:
-    The key provider responds with a `MasterkeyResponse`_ object. This request 
should
-    virtually always be successful.
+    Key share stored successfully.
+
+    FIXME: define error conditions (not supported key share method,
+    payment required, out of service...)
 
   **Details:**
 
-  .. _MasterkeyResponse:
+  .. _KeyShare:
   .. code-block:: tsref
        
-    interface MasterkeyResponse {
-      // Encrypted masterkey
-      masterkey: Masterkey;
-    }
-
-.. _backup:
-
----------------------------------
-Send backup file to escrow provider
----------------------------------
-
-This API is used by Anastasis clients to send an encrypted backup (wallet 
etc.) to the escrow provider.
+    interface KeyShare {
+      // Key share method, i.e. "security question", "SMS", "e-mail", ...
+      method: String;
 
-.. http:post:: /escrow/backup
+      // the explicit key to reveal, if method is one of SMS, e-mail, ...
+      key? : byte[];
 
-  Send the backup file to the escrow provider.
+      // ground truth, i.e. challenge question,
+      // phone number, e-mail address, picture, fingerprint, ...
+      truth? : byte[];
 
-  **Request:** The request body must be a `FileBackup`_ object.
-
-  **Response:**
-
-  :status 200 OK:
-    The key provider responds with a `BackupStatus`_ object. This request 
should
-    virtually always be successful.
-
-  **Details:**
+      // mime type of truth, i.e. text/ascii, image/jpeg, etc.
+      truth_mime: string;
 
-  .. _BackupStatus:
-  .. code-block:: tsref
-       
-    interface BackupStatus {
-      // Message
-      message: String;  
+      // signature over method, uuid, and hash of truth / truth-mime and/or 
key.
+      account_sig: EdDSA-Signature;
+      
     }
 
----------------------------------
-Obtain backup file from escrow provider
----------------------------------
+    
 
-This API is used by Anastasis clients to obtain encrypted backup file (wallet 
etc.) from the escrow provider.
 
+.. http:get:: /escrow/$ACCOUNT_PUB/$UUID
 
-.. http:get:: /escrow/backup
+  Request masterkey recovery.
 
-  Obtain the backup file from the escrow provider.
-
-  **Request:** The request body must be a `FileBackupRequest`_ object.
+  **Request:** The request body must be a `EscrowRecoveryRequest`_ object.
 
   **Response:**
 
   :status 200 OK:
-    The key provider responds with a `FileBackupResponse`_ object. This 
request should
-    virtually always be successful.
-
-  **Details:**
-
-  .. _FileBackupResponse:
-  .. code-block:: tsref
-       
-    interface FileBackupResponse {
-      // Encrypted and signed backup file
-      backup: FileBackup;
-    }
-
-
-.. _depositkey:
-
----------------------------------
-Deposit a key with a Key Provider
----------------------------------
-
-This API is used by Anastasis clients to deposit a key with a key provider in 
accordance with a pre-defined policy.
+    The key provider responds with a `Recovery`_ object. 
 
+  :status 3xx :
+    The key provider responds with a `EscrowChallenge`_ object. 
 
-.. http:post:: /keydepo/depositkey
+  :status 304:
+    Empty body, the escrow provider will respond out-of-band (i.e. SMS)
 
-  Get the key providers's current online signing key and a specific index for 
the key deposited.
+  :status 302 Redirect:
+    Escrow provider redirects for authentication (i.e. video 
identification/WebRTC).
 
-  **Request:** The request body must be a `KeyDepositRequest`_ object.
+  :status 402 :
+    Pay.
 
-  **Response:**
-
-  :status 200 OK:
-    The key provider responds with a `KeyDepositResponse`_ object. This 
request should
-    virtually always be successful.
+  :status 404:
 
   **Details:**
 
-  .. _KeyDepositResponse:
+  .. _EscrowRecoveryRequest:
   .. code-block:: tsref
        
-    interface KeyDepositResponse {
-      // EdDSA master public key of the key provider
-      master_public_key: EddsaPublicKey;
+    interface EscrowRecoveryRequest {
+      // Escrow recovery nonce
+      nonce: byte[32];
 
-      // Relative duration until inactive reserves are closed; not signed, 
expressed as
-      // a string in relative time in microseconds, i.e. "/Delay(1000)/" for 1 
second.
-      reserve_closing_delay: RelativeTime;
+      // signature over nonce, uuid.
+      account_sig: EdDSA-Signature;
 
-      // The key provider's signing key.
-      signkey: SignKey;
-
-      // The index of the key deposited
-      indexkey: Integer;       
+      // Authentication token (i.e. as received via SMS/E-mail)
+      token? : string;
     }
 
-.. _obtainkey:
-
----------------------------------
-Obtain a key from a Key Provider
----------------------------------
-
-This API is used by Anastasis clients to deposit a key with a key provider in 
accordance with a pre-defined policy.
-
-
-.. http:get:: /keydepo/obtainkey
-
-  Get the key providers's current online signing key and a specific index for 
the key deposited.
-
-  **Request:** The request body must be a `KeyObtainRequest`_ object.
-
-  **Response:**
-
-  :status 200 OK:
-    The key provider responds with a `KeyObtainResponse`_ object. This request 
should
-    virtually always be successful.
-
-  **Details:**
-
-  .. _KeyObtainResponse:
+      .. _Recovery:
   .. code-block:: tsref
        
-    interface KeyObtainResponse {
-      // The index of the key obtained
-      index: Integer;
-
-      // The requested key
-      key: HashedKey;  
+    interface Recovery {
+      // Escrow recovery nonce
+      key: byte[32];
     }
 
+   .. _EscrowChallenge:
+   .. code-block:: tsref
+       
+    interface EscrowChallenge {
+      truth: byte[];
+      truth_mime: string;
+    }

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