Still on splitting

1 files changed, 0 insertions, 705 deletions

diff --git a/api-common.rst b/api-common.rst
deleted file mode 100644
index 411f7df5..00000000
--- a/api-common.rst
+++ /dev/null
@@ -1,705 +0,0 @@
-..
-  This file is part of GNU TALER.
-  Copyright (C) 2014, 2015, 2016 GNUnet e.V. and INRIA
-  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
-  Foundation; either version 2.1, or (at your option) any later version.
-  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
-  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
-  A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
-  You should have received a copy of the GNU Lesser General Public License along with
-  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
-
-  @author Christian Grothoff
-  @author Marcello Stanisci
-
-.. _http-common:
-
-=================================
-Common Taler HTTP API Conventions
-=================================
-
-
--------------------------
-HTTP Request and Response
--------------------------
-
-Certain response formats are common for all requests. They are documented here
-instead of with each individual request.  Furthermore, we note that clients may
-theoretically fail to receive any response.  In this case, the client should
-verify that the Internet connection is working properly, and then proceed to
-handle the error as if an internal error (500) had been returned.
-
-.. http:any:: /*
-
-
-  **Request:**
-
-  Unless specified otherwise, HTTP requests that carry a message body must
-  have the content type `application/json`.
-
-  :reqheader Content-Type: application/json
-
-  **Response:**
-
-  :resheader Content-Type: application/json
-  :status 200: The request was successful.
-  :status 500 Internal server error:
-    This always indicates some serious internal operational error of the exchange,
-    such as a program bug, database problems, etc., and must not be used for
-    client-side problems.  When facing an internal server error, clients should
-    retry their request after some delay.  We recommended initially trying after
-    1s, twice more at randomized times within 1 minute, then the user should be
-    informed and another three retries should be scheduled within the next 24h.
-    If the error persists, a report should ultimately be made to the auditor,
-    although the auditor API for this is not yet specified.  However, as internal
-    server errors are always reported to the exchange operator, a good operator
-    should naturally be able to address them in a timely fashion, especially
-    within 24h.  When generating an internal server error, the exchange responds with
-    a JSON object containing the following fields:
-  :status 400 Bad Request: One of the arguments to the request is missing or malformed.
-
-  Unless specified otherwise, all error status codes (4xx and 5xx) have a message
-  body with an `ErrorDetail`_ JSON object.
-
-  **Details:**
-
-  .. _ErrorDetail:
-  .. _tsref-type-ErrorDetail:
-  .. code-block:: tsref
-
-    interface ErrorDetail {
-
-      // Numeric `error code <error-codes>`_ unique to the condition.
-      code: number;
-
-      // Human-readable description of the error, i.e. "missing parameter", "commitment violation", ...
-      // The other arguments are specific to the error value reported here.
-      error: string;
-
-      // Hint about error nature
-      hint?: string;
-
-      // Name of the parameter that was bogus (if applicable)
-      parameter?: string;
-
-      // Path to the argument that was bogus (if applicable)
-      path?: string;
-
-      // Offset of the argument that was bogus (if applicable)
-      offset?: string;
-
-      // Index of the argument that was bogus (if applicable)
-      index?: string;
-
-      // Name of the object that was bogus (if applicable)
-      object?: string;
-
-      // Name of the currency thant was problematic (if applicable)
-      currency?: string;
-
-      // Expected type (if applicable).
-      type_expected?: string;
-
-      // Type that was provided instead (if applicable).
-      type_actual?: string;
-    }
-
-
-.. _encodings-ref:
-
-----------------
-Common encodings
-----------------
-
-This section describes how certain types of values are represented throughout the API.
-
-.. _base32:
-.. _tsref-type-Base32:
-
-Binary Data
-^^^^^^^^^^^
-
-Binary data is generally encoded using Crockford's variant of Base32
-(http://www.crockford.com/wrmg/base32.html), except that "U" is not excluded
-but also decodes to "V" to make OCR easy.  We will still simply use the JSON
-type "base32" and the term "Crockford Base32" in the text to refer to the
-resulting encoding.
-
-.. _tsref-type-HashCode:
-
-Hash codes
-^^^^^^^^^^
-Hashcodes are strings representing base32 encoding of the respective hashed
-data. See `base32`_.
-
-Large numbers
-^^^^^^^^^^^^^
-
-Large numbers such as RSA blinding factors and 256 bit  keys, are transmitted
-as other binary data in Crockford Base32 encoding.
-
-
-.. _tsref-type-Timestamp:
-
-Timestamps
-^^^^^^^^^^
-
-Timestamps are represented in JSON as a string literal `"\\/Date(x)\\/"`,
-where `x` is the decimal representation of the number of seconds past the
-Unix Epoch (January 1, 1970).  The escaped slash (`\\/`) is interpreted in
-JSON simply as a normal slash, but distinguishes the timestamp from a normal
-string literal.  We use the type "date" in the documentation below.
-Additionally, the special strings "\\/never\\/" and "\\/forever\\/" are
-recognized to represent the end of time.
-
-
-.. _public\ key:
-
-Keys
-^^^^
-
-.. _`tsref-type-EddsaPublicKey`:
-.. _`tsref-type-EcdhePublicKey`:
-.. _`tsref-type-EcdhePrivateKey`:
-.. _`tsref-type-EddsaPrivateKey`:
-.. _`tsref-type-CoinPublicKey`:
-
-.. code-block:: tsref
-
-   // EdDSA and ECDHE public keys always point on Curve25519
-   // and represented  using the standard 256 bits Ed25519 compact format,
-   // converted to Crockford `Base32`_.
-   type EddsaPublicKey = string;
-   type EddsaPrivateKey = string;
-
-.. _`tsref-type-RsaPublicKey`:
-
-.. code-block:: tsref
-
-   // RSA public key converted to Crockford `Base32`_.
-   type RsaPublicKey = string;
-
-.. _blinded-coin:
-
-Blinded coin
-^^^^^^^^^^^^
-
-.. _`tsref-type-CoinEnvelope`:
-
-.. code-block:: tsref
-
-  // Blinded coin's `public EdDSA key <eddsa-coin-pub>`_, `base32`_ encoded
-  type CoinEnvelope = string;
-
-.. _signature:
-
-Signatures
-^^^^^^^^^^
-
-.. _`tsref-type-EddsaSignature`:
-
-.. code-block:: tsref
-  
-  // EdDSA signatures are transmitted as 64-bytes `base32`_
-  // binary-encoded objects with just the R and S values (base32_ binary-only)
-  type EddsaSignature = string;
-
-
-.. _`tsref-type-RsaSignature`:
-
-.. code-block:: tsref
-  
-  // `base32`_ encoded RSA signature
-  type RsaSignature = string;
-
-.. _`tsref-type-BlindedRsaSignature`:
-
-.. code-block:: tsref
-  
-  // `base32`_ encoded RSA blinded signature
-  type BlindedRsaSignature = string;
-
-.. _amount:
-
-Amounts
-^^^^^^^
-
-Amounts of currency are expressed as a JSON object with the following fields:
-
-.. _`tsref-type-Amount`:
-
-.. code-block:: tsref
-
-  interface Amount {
-    // name of the currency using either a three-character ISO 4217 currency
-    // code, or a regional currency identifier starting with a "*" followed by
-    // at most 10 characters.  ISO 4217 exponents in the name are not supported,
-    // although the "fraction" is corresponds to an ISO 4217 exponent of 6.
-    currency: string;
-
-    // unsigned 32 bit value in the currency, note that "1" here would
-    // correspond to 1 EUR or 1 USD, depending on `currency`, not 1 cent.
-    value: number;
-
-    // unsigned 32 bit fractional value to be added to `value` representing
-    // an additional currency fraction, in units of one millionth (1e-6)
-    // of the base currency value.  For example, a fraction
-    // of 500,000 would correspond to 50 cents.
-    fraction: number;
-  }
-
-
---------------
-Binary Formats
---------------
-
-  .. note::
-
-     Due to the way of handling `big` numbers by some platforms (such as
-     `JavaScript`, for example), wherever the following specification mentions
-     a 64-bit value, the actual implementations are strongly advised to rely on
-     arithmetic up to 53 bits.
-
-  .. note::
-     
-     Taler uses `libgnunetutil` for interfacing itself with the operating system,
-     doing crypto work, and other "low level" actions, therefore it is strongly
-     connected with the `GNUnet project <https://gnunet.org>`_.
-
-This section specifies the binary representation of messages used in Taler's
-protocols. The message formats are given in a C-style pseudocode notation.
-Padding is always specified explicitly, and numeric values are in network byte
-order (big endian).
-
-Amounts
-^^^^^^^
-
-Amounts of currency are always expressed in terms of a base value, a fractional
-value and the denomination of the currency:
-
-.. sourcecode:: c
-
-  struct TALER_Amount {
-    uint64_t value;
-    uint32_t fraction;
-    uint8_t currency_code[12]; // i.e. "EUR" or "USD"
-  };
-  struct TALER_AmountNBO {
-    uint64_t value;            // in network byte order
-    uint32_t fraction;         // in network byte order
-    uint8_t currency_code[12];
-  };
-
-
-Time
-^^^^
-
-In signed messages, time is represented using 64-bit big-endian values,
-denoting microseconds since the UNIX Epoch.  `UINT64_MAX` represents "never".
-
-.. sourcecode:: c
-
-  struct GNUNET_TIME_Absolute {
-    uint64_t timestamp_us;
-  };
-  struct GNUNET_TIME_AbsoluteNBO {
-    uint64_t abs_value_us__;       // in network byte order
-  };
-
-Cryptographic primitives
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-All elliptic curve operations are on Curve25519.  Public and private keys are
-thus 32 bytes, and signatures 64 bytes.  For hashing, including HKDFs, Taler
-uses 512-bit hash codes (64 bytes).
-
-.. sourcecode:: c
-
-   struct GNUNET_HashCode {
-     uint8_t hash[64];      // usually SHA-512
-   };
-
-.. _reserve-pub:
-.. sourcecode:: c
-
-   struct TALER_ReservePublicKeyP {
-     uint8_t eddsa_pub[32];
-   };
-
-.. _reserve-priv:
-.. sourcecode:: c
-
-   struct TALER_ReservePrivateKeyP {
-     uint8_t eddsa_priv[32];
-   };
-
-   struct TALER_ReserveSignatureP {
-     uint8_t eddsa_signature[64];
-   };
-
-.. _merchant-pub:
-.. sourcecode:: c
-
-   struct TALER_MerchantPublicKeyP {
-     uint8_t eddsa_pub[32];
-   };
-
-   struct TALER_MerchantPrivateKeyP {
-     uint8_t eddsa_priv[32];
-   };
-
-   struct TALER_TransferPublicKeyP {
-     uint8_t ecdhe_pub[32];
-   };
-
-   struct TALER_TransferPrivateKeyP {
-     uint8_t ecdhe_priv[32];
-   };
-
-.. _sign-key-pub:
-.. sourcecode:: c
-
-   struct TALER_ExchangePublicKeyP {
-     uint8_t eddsa_pub[32];
-   };
-
-.. _sign-key-priv:
-.. sourcecode:: c
-
-   struct TALER_ExchangePrivateKeyP {
-     uint8_t eddsa_priv[32];
-   };
-
-.. _eddsa-sig:
-.. sourcecode:: c
-
-   struct TALER_ExchangeSignatureP {
-     uint8_t eddsa_signature[64];
-   };
-
-   struct TALER_MasterPublicKeyP {
-     uint8_t eddsa_pub[32];
-   };
-
-   struct TALER_MasterPrivateKeyP {
-     uint8_t eddsa_priv[32];
-   };
-
-   struct TALER_MasterSignatureP {
-     uint8_t eddsa_signature[64];
-   };
-
-.. _eddsa-coin-pub:
-.. sourcecode:: c
-
-   union TALER_CoinSpendPublicKeyP {
-     uint8_t eddsa_pub[32];
-     uint8_t ecdhe_pub[32];
-   };
-
-.. _coin-priv:
-.. sourcecode:: c
-
-   union TALER_CoinSpendPrivateKeyP {
-     uint8_t eddsa_priv[32];
-     uint8_t ecdhe_priv[32];
-   };
-
-   struct TALER_CoinSpendSignatureP {
-     uint8_t eddsa_signature[64];
-   };
-
-   struct TALER_TransferSecretP {
-     uint8_t key[sizeof (struct GNUNET_HashCode)];
-   };
-     uint8_t key[sizeof (struct GNUNET_HashCode)];
-   };
-
-   struct TALER_EncryptedLinkSecretP {
-     uint8_t enc[sizeof (struct TALER_LinkSecretP)];
-   };
-
-.. _Signatures:
-
-Signatures
-^^^^^^^^^^
-Any piece of signed data, complies to the abstract data structure given below.
-
-.. sourcecode:: c
-
-  struct Data {
-    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
-    type1_t payload1;
-    type2_t payload2;
-    ...
-  };
-
-  /*From gnunet_crypto_lib.h*/
-  struct GNUNET_CRYPTO_EccSignaturePurpose {
-    /**
-     * This field is used to express the context in
-     * which the signature is made, ensuring that a
-     * signature cannot be lifted from one part of the protocol
-     * to another. See `src/include/taler_signatures.h` within the
-     * exchange's codebase (git://taler.net/exchange)
-     */
-    uint32_t purpose;
-    /**
-     * This field equals the number of bytes being signed,
-     * namely 'sizeof (struct Data)'
-     */
-    uint32_t size;
-  };
-
-
-The following list contains all the data structure that can be signed in
-Taler. Their definition is typically found in `src/include/taler_signatures.h`,
-within the :ref:`exchange's codebase <exchange-repo>`.
-
-.. _TALER_WithdrawRequestPS:
-.. sourcecode:: c
-
-  struct TALER_WithdrawRequestPS {
-    /**
-     * purpose.purpose = TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW
-     */
-    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
-    struct TALER_ReservePublicKeyP reserve_pub;
-    struct TALER_AmountNBO amount_with_fee;
-    struct TALER_AmountNBO withdraw_fee;
-    struct GNUNET_HashCode h_denomination_pub;
-    struct GNUNET_HashCode h_coin_envelope;
-  };
-
-.. _TALER_DepositRequestPS:
-.. sourcecode:: c
-
-  struct TALER_DepositRequestPS {
-    /**
-     * purpose.purpose = TALER_SIGNATURE_WALLET_COIN_DEPOSIT
-     */
-    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
-    struct GNUNET_HashCode h_contract;
-    struct GNUNET_HashCode h_wire;
-    struct GNUNET_TIME_AbsoluteNBO timestamp;
-    struct GNUNET_TIME_AbsoluteNBO refund_deadline;
-    uint64_t transaction_id;
-    struct TALER_AmountNBO amount_with_fee;
-    struct TALER_AmountNBO deposit_fee;
-    struct TALER_MerchantPublicKeyP merchant;
-    union TALER_CoinSpendPublicKeyP coin_pub;
-  };
-
-.. _TALER_DepositConfirmationPS:
-.. sourcecode:: c
-
-  struct TALER_DepositConfirmationPS {
-    /**
-     * purpose.purpose = TALER_SIGNATURE_WALLET_CONFIRM_DEPOSIT
-     */
-    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
-    struct GNUNET_HashCode h_contract;
-    struct GNUNET_HashCode h_wire;
-    uint64_t transaction_id GNUNET_PACKED;
-    struct GNUNET_TIME_AbsoluteNBO timestamp;
-    struct GNUNET_TIME_AbsoluteNBO refund_deadline;
-    struct TALER_AmountNBO amount_without_fee;
-    union TALER_CoinSpendPublicKeyP coin_pub;
-    struct TALER_MerchantPublicKeyP merchant;
-  };
-
-.. _TALER_RefreshMeltCoinAffirmationPS:
-.. sourcecode:: c
-
-  struct TALER_RefreshMeltCoinAffirmationPS {
-    /**
-     * purpose.purpose = TALER_SIGNATURE_WALLET_COIN_MELT
-     */
-    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
-    struct GNUNET_HashCode session_hash;
-    struct TALER_AmountNBO amount_with_fee;
-    struct TALER_AmountNBO melt_fee;
-    union TALER_CoinSpendPublicKeyP coin_pub;
-  };
-
-.. _TALER_RefreshMeltConfirmationPS:
-.. sourcecode:: c
-
-  struct TALER_RefreshMeltConfirmationPS {
-    /**
-     * purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_MELT
-     */
-    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
-    struct GNUNET_HashCode session_hash;
-    uint16_t noreveal_index;
-  };
-
-  struct TALER_ExchangeSigningKeyValidityPS {
-    /**
-     * purpose.purpose = TALER_SIGNATURE_MASTER_SIGNING_KEY_VALIDITY
-     */
-    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
-    struct TALER_MasterPublicKeyP master_public_key;
-    struct GNUNET_TIME_AbsoluteNBO start;
-    struct GNUNET_TIME_AbsoluteNBO expire;
-    struct GNUNET_TIME_AbsoluteNBO end;
-    struct TALER_ExchangePublicKeyP signkey_pub;
-  };
-
-  struct TALER_ExchangeKeySetPS {
-      /**
-       * purpose.purpose = TALER_SIGNATURE_EXCHANGE_KEY_SET
-       */
-      struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
-      struct GNUNET_TIME_AbsoluteNBO list_issue_date;
-      struct GNUNET_HashCode hc;
-  };
-
-.. _TALER_DenominationKeyValidityPS:
-.. sourcecode:: c
-
-  struct TALER_DenominationKeyValidityPS {
-    /**
-     * purpose.purpose = TALER_SIGNATURE_MASTER_DENOMINATION_KEY_VALIDITY
-     */
-    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
-    struct TALER_MasterPublicKeyP master;
-    struct GNUNET_TIME_AbsoluteNBO start;
-    struct GNUNET_TIME_AbsoluteNBO expire_withdraw;
-    struct GNUNET_TIME_AbsoluteNBO expire_spend;
-    struct GNUNET_TIME_AbsoluteNBO expire_legal;
-    struct TALER_AmountNBO value;
-    struct TALER_AmountNBO fee_withdraw;
-    struct TALER_AmountNBO fee_deposit;
-    struct TALER_AmountNBO fee_refresh;
-    struct GNUNET_HashCode denom_hash;
-  };
-
-.. _TALER_MasterWireDetailsPS:
-.. sourcecode:: c
-
-  struct TALER_MasterWireDetailsPS {
-    /**
-     * purpose.purpose = TALER_SIGNATURE_MASTER_SEPA_DETAILS || TALER_SIGNATURE_MASTER_TEST_DETAILS
-     */
-    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
-    struct GNUNET_HashCode h_sepa_details;
-  };
-
-  struct TALER_DepositTrackPS {
-    /**
-     * purpose.purpose = TALER_SIGNATURE_MASTER_SEPA_DETAILS || TALER_SIGNATURE_MASTER_TEST_DETAILS
-     */
-    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
-    struct GNUNET_HashCode h_contract;
-    struct GNUNET_HashCode h_wire;
-    uint64_t transaction_id;
-    struct TALER_MerchantPublicKeyP merchant;
-    struct TALER_CoinSpendPublicKeyP coin_pub;
-  };
-
-  /**
-   * Format internally used for packing the detailed information
-   * to generate the signature for /track/transfer signatures.
-   */
-  struct TALER_WireDepositDetailP {
-    struct GNUNET_HashCode h_contract;
-    struct GNUNET_TIME_AbsoluteNBO execution_time;
-    uint64_t transaction_id GNUNET_PACKED;
-    struct TALER_CoinSpendPublicKeyP coin_pub;
-    struct TALER_AmountNBO deposit_value;
-    struct TALER_AmountNBO deposit_fee;
-  };
-
-
-  struct TALER_WireDepositDataPS {
-    /**
-     * purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE_DEPOSIT 
-     */
-    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
-    struct TALER_AmountNBO total;
-    struct TALER_MerchantPublicKeyP merchant_pub;
-    struct GNUNET_HashCode h_wire;
-    struct GNUNET_HashCode h_details;
-  };
-
-.. _TALER_ExchangeKeyValidityPS:
-.. sourcecode:: c
-
-  struct TALER_ExchangeKeyValidityPS {
-    /**
-     * purpose.purpose = TALER_SIGNATURE_AUDITOR_EXCHANGE_KEYS
-     */
-    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
-    struct GNUNET_HashCode auditor_url_hash;
-    struct TALER_MasterPublicKeyP master;
-    struct GNUNET_TIME_AbsoluteNBO start;
-    struct GNUNET_TIME_AbsoluteNBO expire_withdraw;
-    struct GNUNET_TIME_AbsoluteNBO expire_spend;
-    struct GNUNET_TIME_AbsoluteNBO expire_legal;
-    struct TALER_AmountNBO value;
-    struct TALER_AmountNBO fee_withdraw;
-    struct TALER_AmountNBO fee_deposit;
-    struct TALER_AmountNBO fee_refresh;
-    struct GNUNET_HashCode denom_hash;
-  };
-
-
-.. _TALER_PaymentResponsePS:
-.. sourcecode:: c
-
-  struct PaymentResponsePS {
-    /**
-     * purpose.purpose = TALER_SIGNATURE_MERCHANT_PAYMENT_OK
-     */
-    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
-    struct GNUNET_HashCode h_contract;
-  };
-
-
-.. _TALER_ContractPS:
-.. sourcecode:: c
-
-  struct TALER_ContractPS {
-    /**
-     * purpose.purpose = TALER_SIGNATURE_MERCHANT_CONTRACT
-     */
-    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
-    uint64_t transaction_id;
-    struct TALER_AmountNBO total_amount;
-    struct TALER_AmountNBO max_fee;
-    struct GNUNET_HashCode h_contract;
-    struct TALER_MerchantPublicKeyP merchant_pub;
-  };
-
-  struct TALER_ConfirmWirePS {
-    /**
-     * purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE
-     */
-    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
-    struct GNUNET_HashCode h_wire;
-    struct GNUNET_HashCode h_contract;
-    struct TALER_WireTransferIdentifierRawP wtid;
-    struct TALER_CoinSpendPublicKeyP coin_pub;
-    uint64_t transaction_id;
-    struct GNUNET_TIME_AbsoluteNBO execution_time;
-    struct TALER_AmountNBO coin_contribution;
-  };
-
-.. _TALER_RefundRequestPS:
-.. sourcecode:: c
-
-  struct TALER_RefundRequestPS {
-    /**
-      *  purpose.purpose = TALER_SIGNATURE_MERCHANT_REFUND
-      */
-    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
-    struct GNUNET_HashCode h_contract GNUNET_PACKED;
-    uint64_t transaction_id GNUNET_PACKED;
-    struct TALER_CoinSpendPublicKeyP coin_pub;
-    struct TALER_MerchantPublicKeyP merchant;
-    uint64_t rtransaction_id GNUNET_PACKED;
-    struct TALER_AmountNBO refund_amount;
-    struct TALER_AmountNBO refund_fee;
-  };