[GNUnet-SVN] [taler-anastasis] branch master updated: cleaning up API spec

[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 327da56  cleaning up API spec
327da56 is described below

commit 327da569d0501cbeebb8b411fb16abd4ba7212a4
Author: Christian Grothoff <address@hidden>
AuthorDate: Fri Aug 30 06:07:30 2019 +0200

    cleaning up API spec
---
 src/api/api-anastasis.rst | 413 +++++++++++++++++++++++++++++++---------------
 1 file changed, 284 insertions(+), 129 deletions(-)

diff --git a/src/api/api-anastasis.rst b/src/api/api-anastasis.rst
index 2d4ec23..b6a39a4 100644
--- a/src/api/api-anastasis.rst
+++ b/src/api/api-anastasis.rst
@@ -1,6 +1,6 @@
 ..
   This file is part of GNU TALER.
-  Copyright (C) 2014-2018 Taler Systems SA
+  Copyright (C) 2019 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU General Public License as published by the Free Software
@@ -20,24 +20,63 @@
 ==============================
 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 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.
+**Anastasis** is a service that allows the user to securely deposit a master
+secret with an open set of escrow providers and recover it if it is lost.  To
+uniquely identify users, an "unforgettable" **identifier** is used.  This
+identifier should be difficult to guess for anybody but the user, but is not
+expected to have sufficient entropy or secrecy to be cryptographically
+secure. Examples for such identifier would be a concatenation of the full name
+of the user and their social security or passport number(s).  For Swiss
+citizens, the AHV number could also be used.  Some key material, but not the
+master secret, is then derived from this **identifier** using different HKDFs.
+These HKDFs are salted using the respective escrow provider's **server salt**,
+which ensures that the accounts for the same user cannot be easily correlated
+across the various Anastasis servers.
+
+The Anastasis service uses an EdDSA **account key** to identify the account of
+the user.  The account private key is derived from the user's identifier using
+a computationally expensive cryptographic hash function H_1.  Using an
+expensive hash algorithm is supposed to make it difficult for an adversary to
+determine account keys by brute force without knowing the user's identifier.
+However, it is assumed that an adversary performing a targeted attack can
+compute the account key pair.
+
+The public account key is Crockford base32-encoded in the URI to identify the
+account, and used to sign requests.  These signatures are provided in base32
+encoding using the HTTP header "Anastasis-Account-Signature".
+
+A second ECDHE **encryption key** is also derived per account to encrypt
+information stored on the Anastasis server on behalf of the user.  The ECDHE
+private key is derived from the user's identifier via another computationally
+expensive cryptographic hash function H_2.  To encrypt some payload, another
+**ephemeral** ECDHE key is created (fresh for each encryption operation).  The
+ECDH of the encryption key and the ephemeral key is then given to an HKDF to
+derive a symmetric key and IV to encrypt the plaintext using AES-GCM as an
+AEAD, with the **account key** (in binary) being provided as associated data.
+The public ephemeral key and the GCM tag are then pre-pended to the resulting
+ciphertext and uploaded to the Anastasis server.  This is done whenever
+encrypted data is stored with the server.  The **salt** given to the HKDF is
+varied to indicate the context of the encryption operation (preventing the
+server from switching ciphertexts from the same account).  Below, we will
+specify the salt used for each encryption operation with the respective use of
+encryption in the protocol.
+
+The **core secret** of the user is encrypted using a symmetric **master key**.
+Recovering the master key requires the user to satisfy a particular
+**policy**.  Policies specify a set of **escrow methods**, each of
+which leads the user to a **key share**. Combining those key shares then
+ultimately allows the user to obtain a **policy key**, which can be used to
+decrypt the **master key**.  There can be many policies, satisfying any of
+these will allow the user to recover the master key.  A **recovery document**
+contains the encrypted core secret, a set of escrow methods and a set
+of policies.
+
+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 the respective authorization method.
 
-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.
 
 .. _salt:
 
@@ -47,7 +86,11 @@ Obtain salt
 
 .. http:get:: /salt
 
-  Obtain the salt used by the escrow provider.
+  Obtain the salt used by the escrow provider.  Different providers
+  will use different high-entropy salt values. The resulting
+  **provider salt** is then used in various operations to ensure
+  cryptographic operations differ by provider.  A provider must
+  never change its salt value.
 
 
   **Response:**
@@ -60,63 +103,117 @@ Obtain salt
 
     interface SaltResponse {
       // salt value, at least 128 bits of entropy
-      salt: string;
+      server_salt: string;
     }
 
 .. _escrow:
 
--------------------------
-Manage policy + key-share
--------------------------
+-------------
+Manage policy
+-------------
 
-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. 
+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.
 
+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.
 
-.. 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, the encrypted master public key and the encrypted key-share. 
+.. http:get:: /policy/$ACCOUNT_PUB[?version=$NUMBER]
+
+  Get the customer's policy and encrypted master key share data.  If "version"
+  is not specified, returns the latest available version.  If
+  "version" is specified, returns the policy with the respective
+  "version".  The response must begin with an ephemeral ECDHE public
+  key and continue with an AES-GCM tag and ciphertext.  Once decrypted, the
+  plaintext is expected to contain:
+  * the escrow policy
+  * the separately encrypted master public key
+  Note that the key shares required to decrypt the master public key are
+  not included, as for this the client needs to obtain authorization.
+  The policy does provide sufficient information for the client to determine
+  how to authorize requests for **truth**.
+
+  The client MAY provide an "If-not-modified-since" header with an Etag.
+  In that case, the server MUST additionally respond with an "304" status
+  code in case the resource matches the provided Etag.
 
   :status 200 OK:
     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 400 Bad request:
+    The $ACCOUNT_PUB is not an EdDSA public key.
   :status 402 Payment Required:
-    Payment Reequired.
+    The account's balance is too low for the specified operation.
+    See the Taler payment protocol specification for how to pay.
+  :status 403 Forbidden:
+    The required account signature was invalid.
   :status 404 Not Found:
     The requested resource was not found.
 
-  *X-Anastasis-Version*: $NUMBER --- return actual version number in header;
+  *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-UUID*: $UUID --- return actual uuid in header;
-  (if not specified in request, return EscrowChallenge_ according to specified 
version &NUMBER respectively the latest version).
-    
+  *Etag*: Etag, hash over the body for caching.
+
+  *Anastasis-Account-Signature*: Signature by the account's private key 
affirming the desire to download the policy.
+
+.. http:post:: /policy/$ACCOUNT_PUB
+
+  Upload a new version of the customer's policy and encrypted master key share 
data.
+  If request has been seen before, the server should do nothing, and otherwise 
store the new version.
+  The body must begin with an ephemeral ECDHE public
+  key and continue with an AES-GCM tag and ciphertext.  The format
+  is the same as specified for the response of the GET method. The
+  Anastasis server cannot validate the format, but MAY impose
+  minimum and maximum size limits.
+
+  :status 204 No Content:
+    The policy was accepted and stored.  "Anastasis-Version" and 
"Anastasis-UUID" headers
+    incidate what version and UUID was assigned to this policy upload by the 
server.
+  :status 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.
+  :status 400 Bad request:
+    The $ACCOUNT_PUB is not an EdDSA public key.  The response body may 
elaborate on the error.
+  :status 402 Payment Required:
+    The account's balance is too low for the specified operation.
+    See the Taler payment protocol specification for how to pay.
+    The response body SHOULD provide various means for payment.
+  :status 403 Forbidden:
+    The required account signature was invalid.  The response body may 
elaborate on the error.
+  :status 413 Payload Too Large:
+    The upload is too large *or* too small.  The response body may elaborate 
on the error.
+
+  *Anastasis-Version*: $NUMBER --- return actual version number as determined 
by the server.
+    Only generated if the status is 204 or 304.
+
+  *If-modified-since*: Must contain an Etag with the hash over the body (to 
avoid unnecessary re-uploads).
+
+  *Anastasis-Policy-Signature*: Base-32 encoded EdDSA sianture over hash of 
body with $ACCOUNT_PRIV, affirming desire to upload an encrypted recovery 
document.
+
   **Details:**
- 
+
   .. _EncryptedRecoveryDocument:
   .. code-block:: tsref
 
     interface EncryptedRecoveryDocument {
-      // ECDHE public key used to encrypt the gzip compressed JSON-encoded 
`RecoveryDocument`_.
-      ephemeral_pub: EddsaPublicKey;
+      // Binary ECDHE ephemeral public key used to encrypt the gzip compressed 
JSON-encoded `RecoveryDocument`_.
+      ephemeral_pub: EcdhePublicKey;
 
       // Authentication tag
-      aes_gcm_tag: byte[32];
+      aes_gcm_tag: byte[32?];
 
       // Variable-size encrypted recovery document. After decryption,
       // this contains a gzip compressed JSON-encoded `RecoveryDocument`_.
-      body: byte[]
+      // The salt of the HKDF for this encryption must include the
+      // string "EDR".
+      // FIXME: does it help including the server_salt here as well?
+      encrypted_compressed_recovery_document: byte[]
 
     }
 
@@ -124,45 +221,18 @@ EdDSA public key.
   .. 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
+      // Account identifier at backup provider, AES-encrypted with
+      // the (symmetric) master_key, i.e. an URL
+      // https://sync.taler.net/$BACKUP_ID and
+      // a private key to decrypt the backup.  Anastasis is oblivious
+      // to the details of how this is ultimately encoded.
+      backup_account: byte[];
 
-    interface PolicyDocument {
       // List of escrow providers and selected authentication method
       methods: EscrowMethod[];
 
       // List of possible decryption policies
-      policy: DecryptionPolicy[];
-
-      // Account identifier at backup provider, AES-encrypted with
-      // (symmetric) master_key, i.e.
-      // https://sync.taler.net/ + private key
-      backup_account: byte[];
-
-    }
-
-  .. _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];
+      policy: EscrowPolicy[];
 
     }
 
@@ -170,104 +240,189 @@ EdDSA public key.
   .. code-block:: tsref
 
     interface EscrowMethod {
-      // URL of the escrow provider
+      // URL of the escrow provider (including possibly this Anastasis server)
       provider_url : string;
 
       // Name of the escrow method (e.g. security question, SMS etc.)
       escrow_method: string;
 
-      // UUID of the escrow method
+      // UUID of the escrow method (see /truth/ API below).
       uuid: uuid;
 
-      salt: byte[32];
+      // Salt used to encrypt the truth on the Anastasis server.
+      truth_salt: byte[32];
+
+      // The challenge to give to the user (i.e. the security question
+      // if this is challenge-response).
+      // (Q: as string in base32 encoding?)
+      // (Q: what is the mime-type of this value?)
+      //
+      // For some methods, this value may be absent.
+      //
+      // The plaintext challenge is not revealed to the
+      // Anastasis server.
+      challenge: byte[];
 
     }
 
-  .. _DecryptionPolicy:
+  .. _EscrowPolicy:
   .. code-block:: tsref
 
     interface DecryptionPolicy {
-      salt: byte[32];
+      // Salt included to encrypt master key share when
+      // using this decryption policy.
+      policy_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];
+      encrypted_master_key: byte[32];
 
       // List of escrow methods identified by their uuid
       uuid: uuid[];
 
     }
 
-  .. _EscrowChallenge:
+
+.. _truth:
+
+--------------
+Managing truth
+--------------
+
+This API is used by the Anastasis client to deposit or request **truth** with
+the escrow provider.  As with the policy, the user may be identified and
+authorized by $ACCOUNT_PUB.  Note that authentification of the user is
+optional when uploading truth and depends on the server.  An Anastasis-server
+may agree to store truth for free for a certain time period, or charge per
+truth without associating the truth with an account.  Hence the "account"
+argument and signature may be optional.
+
+.. http:post:: /truth/$UUID[?account=$ACCOUNT_PUB]
+
+  :status 204 No content:
+    Truth stored successfully.
+  :status 304 Not modified:
+    The same truth was previously accepted and stored under this UUID.
+  :status 400 Bad request:
+    The $ACCOUNT_PUB is not an EdDSA public key.  The response body may 
elaborate on the error.
+  :status 402 Payment Required:
+    The account's balance is too low for the specified operation (or the server
+    requires payment to store truth per item).
+    See the Taler payment protocol specification for how to pay.
+    The response body SHOULD provide various means for payment.
+  :status 403 Forbidden:
+    The required account signature was invalid.  The response body may 
elaborate on the error.
+  :status 409 Conflict:
+    The server already has some truth stored under this UUID. The client 
should check that it
+    is generating UUIDs with enough entropy.
+  :status 412 Precondition Failed:
+    The selected authentication method is not supported on this provider.
+
+  *Anastasis-Account-Signature*: Client header with the signature by the 
account's private key affirming the desire to upload the truth; only present if 
"account" is specified in the URL.
+
+  **Details:**
+
+  .. _Truth:
   .. code-block:: tsref
 
-    interface EscrowChallenge {
-      // ground truth, i.e. challenge question,
+    interface Truth {
+      // Key share method, i.e. "security question", "SMS", "e-mail", ...
+      method: String;
+
+      // The explicit key material to reveal (Q: as string in base32 encoding?)
+      // Contains a KeyShare_, but in compact binary encoding.
+      //
+      // The salt of the HKDF for the encryption of this
+      // value must include the string "EKS".   Depending
+      // on the method, the HKDF may additionally include
+      // bits from the response (i.e. some hash over the
+      // answer to the security question)
+      encrypted_key_share: byte[];
+
+      // ECDHE public key used to encrypt the encrypted_key_share
+      key_share_ephemeral_pub: EddsaPublicKey;
+
+      // Authentication tag over the encrypted_key_share
+      key_share_aes_gcm_tag: byte[32];
+      
+      // ground truth, i.e. H(challenge answer),
       // phone number, e-mail address, picture, fingerprint, ...
+      // (Q: as string in base32 encoding?)
+      //
+      // The truth MUST NOT be revealed to the user, even
+      // after successful authentication (of course the user
+      // was originally aware when establishing the truth).
       truth: byte[];
 
       // mime type of truth, i.e. text/ascii, image/jpeg, etc.
       truth_mime: string;
-    
-    }
-
-
-.. http:post:: /escrow/$ACCOUNT_PUB
-
-   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.
-   
 
-.. _truth:
+    }
 
-----------------
-Upload the truth 
-----------------
 
-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:get:: /truth/$UUID[?response=$RESPONSE]
 
-.. http:post:: /truth/$ACCOUNT_PUB/$UUID
-    
   :status 200 OK:
-    Key share stored successfully.
-  :status 400 Bad Request:
-    Request wasn’t built properly.
+    EncryptedKeyShare_ is returned in body (in binary).
+  :status 202 Accepted:
+    The escrow provider will respond out-of-band (i.e. SMS).
+    The body may contain human-readable instructions on next steps.
+  :status 303 See Other:
+    The provider redirects for authentication (i.e. video 
identification/WebRTC).
+    If the client is not a browser, it should launch a browser at the URL
+    given in the "Location" header and allow the user to re-try the operation
+    after successful authorization.
   :status 402 Payment Required:
-    Payment Reequired.
+    The account's balance is too low for the specified operation (or the server
+    requires payment to store truth per item).
+    See the Taler payment protocol specification for how to pay.
+    The response body SHOULD provide various means for payment.
+  :status 403 Forbidden:
+    The server requires a valid "response" to the challenge associated with 
the UUID.
+  :status 404 Not Found:
+    The server does not know any truth under the given UUID.
   :status 412 Precondition Failed:
-    The selected authentication Method is not supported on this provider.
+    The escrow provider responds with an EscrowChallenge_ object containing
+    details on the challenge the user has to satisfy (see below).
   :status 503 Service Unavailable:
     Server is out of Service.
 
   **Details:**
 
-  .. _Truth:
+  .. _EncryptedKeyShare:
   .. code-block:: tsref
+    interface EncryptedKeyShare {
+      // ECDHE public key used to encrypt the gzip compressed JSON-encoded 
`KeyShare`_.
+      ephemeral_pub: EddsaPublicKey;
 
-    interface Truth {
-      // Key share method, i.e. "security question", "SMS", "e-mail", ...
-      method: String;
+      // Authentication tag
+      aes_gcm_tag: byte[32];
 
-      // 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[];
+      // Encrypted key-share in base32 encoding.
+      // After decryption, this yields a KeyShare_.  Note that
+      // the KeyShare_ MUST be encoded as a fixed-size binary
+      // block (instead of in JSON encoding).
+      //
+      // The salt of the HKDF for the encryption of this
+      // value must include the string "EKS".   Depending
+      // on the method, the HKDF may additionally include
+      // bits from the response (i.e. some hash over the
+      // answer to the security question)
+      encrypted_key_share: 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;
+  .. _KeyShare:
+    .. code-block:: tsref
+    interface KeyShare {
+      // Key material to concatenate with policy_salt and KDF to derive
+      // the key to decrypt the master key.
+      key_share: byte[32];
 
-      // signature over method, uuid, and hash of truth / truth-mime and/or 
key.
+      // Signature over method, uuid, and key_share.
       account_sig: EdDSA-Signature;
-      
+
     }
 
 

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