[taler-docs] 10/36: misc spec fixes

[gnunet]

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

grothoff pushed a commit to branch master
in repository docs.

commit b944ce40628194e9f77d769fab8c6004446c9e21
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sat May 15 13:29:53 2021 +0200

    misc spec fixes
---
 core/api-common.rst   | 148 ++++++++++++++++++++++++++++++++++++++++++++++++++
 core/api-exchange.rst | 101 ++++++++++++++++++++--------------
 2 files changed, 208 insertions(+), 41 deletions(-)

diff --git a/core/api-common.rst b/core/api-common.rst
index bcb0570..81b85ab 100644
--- a/core/api-common.rst
+++ b/core/api-common.rst
@@ -500,6 +500,13 @@ uses 512-bit hash codes (64 bytes).
      uint8_t hash[64];      // usually SHA-512
    };
 
+.. _TALER_EcdhEphemeralPublicKeyP:
+.. sourcecode:: c
+
+   struct TALER_EcdhEphemeralPublicKeyP {
+     uint8_t ecdh_pub[32];
+   };
+
 .. _reserve-pub:
 .. sourcecode:: c
 
@@ -760,6 +767,9 @@ within the
     struct TALER_ExchangePublicKeyP signkey_pub;
   };
 
+.. _TALER_ExchangeKeySetPS:
+.. sourcecode:: c
+
   struct TALER_ExchangeKeySetPS {
       /**
        * purpose.purpose = TALER_SIGNATURE_EXCHANGE_KEY_SET
@@ -1219,3 +1229,141 @@ within the
     struct GNUNET_HashCode h_items;
     struct TALER_WadId wad_id;
   };
+
+.. _TALER_WadPartnerSignaturePS:
+.. sourcecode:: c
+
+  struct TALER_WadPartnerSignaturePS {
+    /**
+     * purpose.purpose = TALER_SIGNATURE_MASTER_PARTNER_DETAILS
+     */
+    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+    struct GNUNET_HashCode h_partner_base_url;
+    struct TALER_MasterPublicKeyP master_public_key;
+    struct GNUNET_TIME_AbsoluteNBO start_date;
+    struct GNUNET_TIME_AbsoluteNBO end_date;
+    struct TALER_AmountNBO wad_fee;
+    struct GNUNET_TIME_RelativeNBO wad_frequency;
+  };
+
+
+.. _TALER_P2PFeesPS:
+.. sourcecode:: c
+
+  struct TALER_P2PFeesPS {
+    /**
+     * purpose.purpose = TALER_SIGNATURE_P2P_FEES
+     */
+    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+    struct GNUNET_TIME_AbsoluteNBO start_date;
+    struct GNUNET_TIME_AbsoluteNBO end_date;
+    struct TALER_AmountNBO kyc_fee;
+    struct TALER_AmountNBO purse_fee;
+    struct TALER_AmountNBO account_history_fee;
+    struct TALER_AmountNBO account_annual_fee;
+    struct GNUNET_TIME_RelativeNBO account_kyc_timeout;
+    struct GNUNET_TIME_RelativeNBO purse_timeout;
+    uint32_t purse_account_limit;
+  };
+
+
+.. _TALER_DenominationKeyAnnouncementPS:
+.. sourcecode:: c
+
+   struct TALER_DenominationKeyAnnouncementPS {
+     /**
+      * purpose.purpose = TALER_SIGNATURE_SM_DENOMINATION_KEY
+      */
+      struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+      struct GNUNET_HashCode h_denom_pub;
+      struct GNUNET_HashCode h_section_name;
+      struct GNUNET_TIME_AbsoluteNBO anchor_time;
+      struct GNUNET_TIME_RelativeNBO duration_withdraw;
+    };
+
+
+.. _TALER_SigningKeyAnnouncementPS:
+.. sourcecode:: c
+
+    struct TALER_SigningKeyAnnouncementPS {
+      /**
+       * purpose.purpose = TALER_SIGNATURE_SM_SIGNING_KEY .
+       */
+      struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+      struct TALER_ExchangePublicKeyP exchange_pub;
+      struct GNUNET_TIME_AbsoluteNBO anchor_time;
+      struct GNUNET_TIME_RelativeNBO duration;
+    };
+
+.. _TALER_MasterDenominationKeyRevocationPS:
+.. sourcecode:: c
+
+    struct TALER_MasterDenominationKeyRevocationPS {
+      /**
+       * purpose.purpose = TALER_SIGNATURE_MASTER_DENOMINATION_KEY_REVOKED.
+       */
+      struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+      struct GNUNET_HashCode h_denom_pub;
+    };
+
+
+.. _TALER_MasterSigningKeyRevocationPS:
+.. sourcecode:: c
+
+    struct TALER_MasterSigningKeyRevocationPS {
+      /**
+       * purpose.purpose = TALER_SIGNATURE_MASTER_SIGNING_KEY_REVOKED.
+       */
+      struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+      struct TALER_ExchangePublicKeyP exchange_pub;
+    };
+
+
+.. _TALER_MasterAddAuditorPS:
+.. sourcecode:: c
+
+    struct TALER_MasterAddAuditorPS {
+      /**
+       * purpose.purpose = TALER_SIGNATURE_MASTER_ADD_AUDITOR
+       */
+       struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+       struct GNUNET_TIME_AbsoluteNBO start_date;
+       struct TALER_AuditorPublicKeyP auditor_pub;
+       struct GNUNET_HashCode h_auditor_url;
+     };
+
+.. _TALER_MasterDelAuditorPS:
+.. sourcecode:: c
+
+    struct TALER_MasterDelAuditorPS {
+      /**
+       * purpose.purpose = TALER_SIGNATURE_MASTER_DEL_AUDITOR
+       */
+      struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+      struct GNUNET_TIME_AbsoluteNBO end_date;
+      struct TALER_AuditorPublicKeyP auditor_pub;
+    };
+
+.. _TALER_MasterAddWirePS:
+.. sourcecode:: c
+
+    struct TALER_MasterAddWirePS {
+      /**
+       * purpose.purpose = TALER_SIGNATURE_MASTER_ADD_WIRE.
+       */
+      struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+      struct GNUNET_TIME_AbsoluteNBO start_date;
+      struct GNUNET_HashCode h_wire GNUNET_PACKED;
+    };
+
+.. _TALER_MasterDelWirePS:
+.. sourcecode:: c
+
+    struct TALER_MasterDelWirePS {
+      /**
+       * purpose.purpose = TALER_SIGNATURE_MASTER_DEL_WIRE.
+       */
+      struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+      struct GNUNET_TIME_AbsoluteNBO end_date;
+      struct GNUNET_HashCode h_wire GNUNET_PACKED;
+    };
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 3f80d4d..44dfd2a 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -140,7 +140,7 @@ possibly by using HTTPS.
       // Fees relevant for wallet-to-wallet (or peer-to-peer) payments.
       // If no fees are provided for a given time range, then the
       // exchange simply does not support purses/p2p-payments at that time.
-      p2p_fees: P2Pfees[];
+      p2p_fees: P2PFees[];
 
       // The date when the denomination keys were last updated.
       list_issue_date: Timestamp;
@@ -160,6 +160,7 @@ possibly by using HTTPS.
       // is sabotaging end-user anonymity by giving disjoint denomination keys 
to
       // different users.  If an exchange were to do this, this signature 
allows the
       // clients to demonstrate to the public that the exchange is dishonest.
+      // Signature of `TALER_ExchangeKeySetPS`
       eddsa_sig: EddsaSignature;
 
       // Public EdDSA key of the exchange that was used to generate the 
signature.
@@ -197,10 +198,9 @@ possibly by using HTTPS.
       // regulatory reasons.)
       account_annual_fee: Amount;
 
-      // How long will the exchange preserve the account
-      // history? After an account was deleted/closed, the
-      // exchange will retain the account history for
-      // legal reasons until this time.
+      // How long will the exchange preserve the account history?
+      // After an account was deleted/closed, the exchange will
+      // retain the account history for legal reasons until this time.
       legal_history_retention: RelativeTime;
 
       // How long does the exchange promise to keep funds
@@ -217,13 +217,12 @@ possibly by using HTTPS.
       // Non-negative number of concurrent purses that any
       // account holder is allowed to create without having
       // to pay the purse_fee.
-      purse_account_limit: integer;
+      purse_account_limit: Integer;
 
-      // How long does an exchange keep a purse around
-      // after a purse has expired (or been successfully
-      // merged)?  A 'GET' request for a purse will
-      // succeed until the purse expiration time plus this
-      // value.
+      // How long does an exchange keep a purse around after a purse
+      // has expired (or been successfully merged)?  A 'GET' request
+      // for a purse will succeed until the purse expiration time
+      // plus this value.
       purse_timeout: RelativeTime;
 
       // Signature of `TALER_P2PFeesPS`.
@@ -308,6 +307,7 @@ possibly by using HTTPS.
       stamp_end: Timestamp;
 
       // Signature over ``key`` and ``stamp_expire`` by the exchange master 
key.
+      // Signature of `TALER_ExchangeSigningKeyValidityPS`.
       // Must have purpose ``TALER_SIGNATURE_MASTER_SIGNING_KEY_VALIDITY``.
       master_sig: EddsaSignature;
     }
@@ -453,7 +453,8 @@ possibly by using HTTPS.
       // How long is this partnership expected to last?
       end_date: Timestamp;
 
-      // Signature using the exchange's offline key
+      // Signature using the exchange's offline key over
+      // `TALER_WadPartnerSignaturePS`
       // with purpose ``TALER_SIGNATURE_MASTER_PARTNER_DETAILS``.
       master_sig: EddsaSignature;
     }
@@ -542,7 +543,10 @@ Management operations authorized by master key
       // Fee charged by the exchange for refunding a coin of this denomination.
       fee_refund: Amount;
 
-      // Signature over this denomination by the denomination security module.
+      // Signature by the denomination security module
+      // over `TALER_DenominationKeyAnnouncementPS`
+      // for this denomination with purpose
+      // ``TALER_SIGNATURE_SM_DENOMINATION_KEY``.
       denom_secmod_sig: EddsaSignature;
 
     }
@@ -564,7 +568,9 @@ Management operations authorized by master key
       // henceforth no longer be considered valid in legal disputes.
       stamp_end: Timestamp;
 
-      // Signature over this signing key by the signkey security module.
+      // Signature over `TALER_SigningKeyAnnouncementPS`
+      // for this signing key by the signkey security
+      // module using purpose ``TALER_SIGNATURE_SM_SIGNING_KEY``.
       signkey_secmod_sig: EddsaSignature;
     }
 
@@ -607,7 +613,8 @@ Management operations authorized by master key
       // Hash of the public (RSA) key of the denomination.
       h_denom_pub: HashCode;
 
-      // Signature of `TALER_DenominationKeyValidityPS`.
+      // Signature over `TALER_DenominationKeyValidityPS`.
+      // Must have purpose ``TALER_SIGNATURE_MASTER_DENOMINATION_KEY_VALIDITY``
       master_sig: EddsaSignature;
 
     }
@@ -618,7 +625,8 @@ Management operations authorized by master key
       // The actual exchange's EdDSA signing public key.
       key: EddsaPublicKey;
 
-      // Signature by the exchange master key.
+      // Signature by the exchange master key over
+      // `TALER_ExchangeSigningKeyValidityPS`.
       // Must have purpose ``TALER_SIGNATURE_MASTER_SIGNING_KEY_VALIDITY``.
       master_sig: EddsaSignature;
 
@@ -646,7 +654,8 @@ Management operations authorized by master key
 
     interface DenomRevocationSignature {
 
-      // Signature by the exchange master key.
+      // Signature by the exchange master key over a
+      // `TALER_MasterDenominationKeyRevocationPS`.
       // Must have purpose ``TALER_SIGNATURE_MASTER_DENOMINATION_KEY_REVOKED``.
       master_sig: EddsaSignature;
 
@@ -673,7 +682,8 @@ Management operations authorized by master key
 
     interface SignkeyRevocationSignature {
 
-      // Signature by the exchange master key.
+      // Signature by the exchange master key over a
+      // `TALER_MasterSigningKeyRevocationPS`.
       // Must have purpose ``TALER_SIGNATURE_MASTER_SIGN_KEY_REVOKED``.
       master_sig: EddsaSignature;
 
@@ -712,8 +722,9 @@ Management operations authorized by master key
       // The auditor's EdDSA signing public key.
       auditor_pub: EddsaPublicKey;
 
-      // Signature by the exchange master key.
-      // Must have purpose ``TALER_SIGNATURE_MASTER_AUDITOR_ADD``.
+      // Signature by the exchange master ke yover a
+      // `TALER_MasterAddAuditorPS`.
+      // Must have purpose ``TALER_SIGNATURE_MASTER_ADD_AUDITOR``.
       master_sig: EddsaSignature;
 
       // When does the auditor become active?
@@ -756,7 +767,8 @@ Management operations authorized by master key
 
     interface AuditorTeardownMessage {
 
-      // Signature by the exchange master key.
+      // Signature by the exchange master key over a
+      // `TALER_MasterDelAuditorPS`.
       // Must have purpose ``TALER_SIGNATURE_MASTER_AUDITOR_DEL``.
       master_sig: EddsaSignature;
 
@@ -849,7 +861,8 @@ Management operations authorized by master key
       // with purpose ``TALER_SIGNATURE_MASTER_WIRE_DETAILS``.
       master_sig_wire: EddsaSignature;
 
-      // Signature using the exchange's offline key
+      // Signature using the exchange's offline key over a
+      // `TALER_MasterAddWirePS`
       // with purpose ``TALER_SIGNATURE_MASTER_WIRE_ADD``.
       master_sig_add: EddsaSignature;
 
@@ -896,7 +909,8 @@ Management operations authorized by master key
       // ``payto://`` URL identifying the account and wire method
       payto_uri: string;
 
-      // Signature using the exchange's offline key
+      // Signature using the exchange's offline key over a
+      // `TALER_MasterDelWirePS`.
       // with purpose ``TALER_SIGNATURE_MASTER_WIRE_DEL``.
       master_sig_del: EddsaSignature;
 
@@ -1063,7 +1077,7 @@ exchange.
 
     }
 
- .. ts:def:: AccountSetupTransaction
+  .. ts:def:: AccountSetupTransaction
 
     interface AccountSetupTransaction {
       type: "SETUP";
@@ -1374,7 +1388,7 @@ exchange.
     The account is unknown to the exchange.
   :http:statuscode:`409 Conflict`:
     The account is still has digital cash in it, the associated
-    wire method is ``void'' and the *force* option was not provided.
+    wire method is ``void`` and the *force* option was not provided.
     This response comes with a standard `ErrorDetail` response.
 
   **Details:**
@@ -2477,7 +2491,7 @@ Wallet-to-wallet transfers
       purse_expiration: Timestamp;
 
       // Indicative time at which the exchange is answering the
-      // status request.  Used as part of `exchange_sig`.
+      // status request.  Used as part of 'exchange_sig'.
       status_timestamp: Timestamp;
 
       // Maximum deposit fees that can be charged under the contract.
@@ -2489,13 +2503,13 @@ Wallet-to-wallet transfers
       // EdDSA signature of the exchange affirming the purse status.
       exchange_sig: EddsaSignature;
 
-      // EdDSA public key exchange used for exchange_sig.
+      // EdDSA public key exchange used for 'exchange_sig'.
       exchange_pub: EddsaPublicKey;
 
       // AES-GCM Encrypted contract terms using encryption
       // key derived from DH of 'contract_pub' and the 'purse_pub'.
       // Optional, may be omitted if not desired by the client.
-      e_contract_terms?: byte[];
+      e_contract_terms?: string;
 
       // If a merge request was received, information about the
       // merge request. Omitted if the purse has not yet received
@@ -2583,23 +2597,27 @@ Wallet-to-wallet transfers
       deposits: PurseDeposit[];
     }
 
-  .. ts:def:: EncryptedContract {
+   .. ts:def:: EncryptedContract
+
+    interface EncryptedContract {
 
       // ECDH contract_public key used to encrypt the contract.
       // Optional as the contract terms may already be known
       // to the exchange or the other wallet from a different
       // interaction.
-      contract_pub: EcdhPublicKey;
+      contract_pub: TALER_EcdhEphemeralPublicKeyP;
 
       // AES-GCM Encrypted contract terms using encryption
-      // key derived from DH of 'contract_pub' and the 'purse_pub'.
+      // key derived from DH of ``contract_pub`` and the ``purse_pub``.
       // Optional as the contract terms may already be known
       // to the exchange or the other wallet from a different
       // interaction.
-      e_contract_terms: byte[];
-  }
+      e_contract_terms: string;
+    }
 
-  .. ts:def:: PurseDeposit {
+  .. ts:def:: PurseDeposit
+
+    interface PurseDeposit {
 
       // Public key of the coin being deposited into the purse.
       coin_pub: EddsaPublicKey;
@@ -2614,7 +2632,8 @@ Wallet-to-wallet transfers
       // Exchange's unblinded RSA signature of the coin.
       ub_sig: RsaSignature;
 
-      // Signature of `TALER_PurseDepositRequestPS`,
+      // Signature over `TALER_PurseDepositSignaturePS`
+      // of purpose ``TALER_SIGNATURE_PURSE_DEPOSIT``
       // made by the customer with the
       // `coin's private key <coin-priv>`.
       coin_sig: EddsaSignature;
@@ -2810,7 +2829,7 @@ Wallet-to-wallet transfers
 
       // The number of remaining purses that can still be opened
       // under the given account.
-      remaining_purses: integer;
+      remaining_purses: Integer;
 
     }
 
@@ -2835,7 +2854,7 @@ Wallet-to-wallet transfers
   :http:statuscode:`200 Ok`:
     The operation succeeded, the exchange confirms that the account
     can now be used.
-    The response will be an `AccountStatus` object.
+    The response will be an `AccountKycStatus` object.
   :http:statuscode:`202 Accepted`:
     The user should be redirected to the provided location to perform
     the required KYC checks to open the account. Afterwards, the
@@ -2890,7 +2909,7 @@ Wallet-to-wallet transfers
       exchange_pub: EddsaPublicKey;
     }
 
-   .. ts:def:: AccountKycRedirect
+  .. ts:def:: AccountKycRedirect
 
      interface AccountKycRedirect {
 
@@ -2946,13 +2965,13 @@ wallet-to-wallet payments.  Only another exchange 
should access this endpoint.
       items: WadItem[];
 
       // EdDSA signature of the exchange affirming the wad
-      // data is correct, must be of purpose
-      // TALER_SIGNATURE_WAD_DATA.
+      // data is correct, must be over `TALER_WadDataSignaturePS`
+      // and of purpose ``TALER_SIGNATURE_WAD_DATA``.
       exchange_sig: EddsaSignature;
 
       // public key used to create the signature.
       exchange_pub: EddsaPublicKey;
-  }
+     }
 
   Objects in the wad item list have the following format:
 

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