[taler-anastasis] branch master updated: rest

[gnunet]

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

ds-meister pushed a commit to branch master
in repository anastasis.

The following commit(s) were added to refs/heads/master by this push:
     new e312538  rest
e312538 is described below

commit e312538fd54a74aa50d55c33d26fabe806a093eb
Author: Dominik Meister <dominiksamuel.meister@students.bfh.ch>
AuthorDate: Thu Jun 11 11:16:26 2020 +0200

    rest
---
 doc/thesis/rest_api_documentation.tex | 54 ++++++++++++++++++-----------------
 1 file changed, 28 insertions(+), 26 deletions(-)

diff --git a/doc/thesis/rest_api_documentation.tex 
b/doc/thesis/rest_api_documentation.tex
index a2218b9..3cd5eac 100644
--- a/doc/thesis/rest_api_documentation.tex
+++ b/doc/thesis/rest_api_documentation.tex
@@ -94,14 +94,12 @@ This API is used by the Anastasis client to deposit or 
request encrypted recover
 \\
 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. \\
-\\
 \textbf{GET /policy/\$ACCOUNT\_PUB[?version=\$NUMBER]} \\
 \\
 Get the customer’s encrypted recovery document. If “version” is not specified, 
the server returns the latest available version. If “version” is specified, 
returns the policy with the respective “version”. The response must begin with 
the nonce and an AES-GCM tag and continue with the ciphertext. Once decrypted, 
the plaintext is expected to contain:
 \begin{itemize}
 \item the escrow policy
-\item the separately encrypted master public key
+\item the separately encrypted master key
 \end{itemize}
 
 \textbf{Status Codes: } \\
@@ -130,7 +128,7 @@ Upload a new version of the customer’s encrypted recovery 
document. While the
  \\
 \textbf{Status Codes: } \\
 \begin{itemize}
-\item 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.
+\item 204 No Content – The encrypted recovery document was accepted and 
stored. “Anastasis-Version” indicate what version was assigned to this 
encrypted recovery document upload by the server.
 \item 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.
 \item 400 Bad request – 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.
 \item 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 MAY provide alternative means for payment.
@@ -139,8 +137,8 @@ Upload a new version of the customer’s encrypted recovery 
document. While the
 \item 413 Request Entity Too Large – The upload is too large or too small. The 
response body may elaborate on the error.
 \end{itemize}
 \textit{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. \\
-\textit{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.
-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.\\
+\textit{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.\\
+\textit{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.\\
 \textit{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 40 [...]
  \\
 \begin{lstlisting}
@@ -189,8 +187,8 @@ interface EscrowMethod {
   // Name of the escrow method (e.g. security question, SMS etc.)
   escrow_method: string;
 
-  // UUID of the escrow method (see /truth/ API below).
-  uuid: string;
+  // truth_seed of the escrow method (see /truth/ API below).
+  truth_seed: [32]; //bytearray
 
   // Key used to encrypt the Truth this EscrowMethod is related to.
   // Client has to provide this key to the server when using /truth/
@@ -221,11 +219,11 @@ interface DecryptionPolicy {
 
   // Master key, AES-encrypted with key derived from
   // salt and keyshares revealed by the following list of
-  // escrow methods identified by UUID.
+  // escrow methods identified by the truth_seeds.
   encrypted_master_key: [32]; //bytearray
 
-  // List of escrow methods identified by their uuid.
-  uuid: string[];
+  // List of escrow methods identified by their truth_seed.
+  truth_seeds: []; //array of truth_seed
 
 }
 \end{lstlisting}
@@ -235,18 +233,20 @@ This API is used by the Anastasis client to deposit truth 
or request a (encrypte
 \newline
 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. \\
 \newline
+Operations by the client are identified and authorized by \$TRUTH\_PUB, which 
should be kept secret from third parties. \$TRUTH\_PUB should be a public key 
using the Crockford base32-encoding.\\
+\newline
 An Anastasis-server may store truth for free for a certain time period, or 
charge per truth operation using GNU Taler. \\
 \newline
-\textbf{POST /truth/\$UUID}
+\textbf{POST /truth/\$TRUTH\_PUB}
 \newline
 Upload a TruthUploadRequest-Object according to the policy the client created 
before (see RecoveryDocument). If request has been seen before, the server 
should do nothing, and otherwise store the new object. \\
 \newline
 \textbf{Status Codes: } \\
 \begin{itemize}
 \item 204 No content – Truth stored successfully.
-\item 304 Not modified – The same truth was previously accepted and stored 
under this UUID. The Anastasis server must still update the expiration time for 
the truth when returning this response code.
+\item 304 Not modified – The same truth was previously accepted and stored 
under this \$TRUTH\_PUB. The Anastasis server must still update the expiration 
time for the truth when returning this response code.
 \item 402 Payment Required – This server requires payment to store truth per 
item. See the Taler payment protocol specification for how to pay. The response 
body MAY provide alternative means for payment.
-\item 409 Conflict – The server already has some truth stored under this UUID. 
The client should check that it is generating UUIDs with enough entropy.
+\item 409 Conflict – The server already has some truth stored under this 
TRUTH\_PUB. The client should check that it is generating \$TRUTH\_PUB with 
enough entropy.
 \item 412 Precondition Failed – The selected authentication method is not 
supported on this provider.
 \end{itemize}
 \textbf{Details:}
@@ -264,8 +264,8 @@ interface TruthUploadRequest {
   // encrypted_truth.
   nonce: [32]; //bytearray
 
-  // Authentication tag of encrypted_truth
-  aes_gcm_tag: [16]; //bytearray
+  // Signature over the key_share signed with TRUTH\_PRIV.
+  key_share_signature: EddsaSignature;
 
   // Variable-size truth. After decryption,
   // this contains the ground truth, i.e. H(challenge answer),
@@ -274,13 +274,16 @@ interface TruthUploadRequest {
   //
   // The nonce of the HKDF for this encryption must include the
   // string "ECT".
-  encrypted_truth: [80]; //bytearray
-
+  encrypted_authentication_data: []; //bytearray
+  
+    // Signature over the key_share signed with TRUTH\_PRIV.
+  authentication_data_signature: EddsaSignature;
+  
   // mime type of truth, i.e. text/ascii, image/jpeg, etc.
   truth_mime: string;
 }
 \end{lstlisting}
-\textbf{GET /truth/\$UUID[?response=\$RESPONSE]} \\
+\textbf{GET /truth/\$TRUTH\_PUB[?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). 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. 
The encrypted key share is returned simply as a byte array and not in JSON 
format. \\
 
@@ -290,12 +293,14 @@ Get the stored encrypted key share. If \$RESPONSE is 
specified by the client, th
 \item 202 Accepted – The escrow provider will respond out-of-band (i.e. SMS). 
The body may contain human-readable instructions on next steps.
 \item 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.
 \item 402 Payment Required – The service requires payment for access to truth. 
See the Taler payment protocol specification for how to pay. The response body 
MAY provide alternative means for payment.
-\item 403 Forbidden – The server requires a valid “response” to the challenge 
associated with the UUID.
-\item 404 Not Found – The server does not know any truth under the given UUID.
+\item 403 Forbidden – The server requires a valid “response” to the challenge 
associated with the \$TRUTH\_PUB.
+\item 404 Not Found – The server does not know any truth under the given 
TRUTH\_PUB.
 \item 503 Service Unavailable – Server is out of Service.
 \end{itemize}
 
-\textbf{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.
+\textbf{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.\\
+\textbf{authentication\_data\_signature:} The client must provide Base-32 
encoded EdDSA signature over the hash of the encrypted\_authentication\_data 
with \$TRUTH\_PRIV.\\
+\textbf{key\_share\_signature:} The client must provide Base-32 encoded EdDSA 
signature over hash of the encrypted\_key\_key\_share with \$TRUTH\_PRIV.
  \\
 \textbf{Details:}
 \begin{lstlisting}
@@ -303,9 +308,6 @@ interface EncryptedKeyShare {
   // Nonce used to compute the decryption (iv,key) pair.
   nonce_i: [32]; //bytearray
 
-  // Authentication tag
-  aes_gcm_tag_i: [16]; //bytearray
-
   // Encrypted key-share in base32 encoding.
   // After decryption, this yields a KeyShare.  Note that
   // the KeyShare MUST be encoded as a fixed-size binary
@@ -325,7 +327,7 @@ interface KeyShare {
   // and KDF to derive the key to decrypt the master key.
   key_share: [32]; //bytearray
 
-  // Signature over method, uuid, and key_share.
+  // Signature over the key_share signed with TRUTH\_PRIV.
   account_sig: EddsaSignature;
 }
 \end{lstlisting}

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.