commit c4368446d4d2e30aba1a202adcc88f427036fb87
parent ade16c67bab3257b594051923431cc2b953aaa69
Author: Christian Grothoff <christian@grothoff.org>
Date: Thu, 21 Jan 2016 09:00:47 +0100
resolving merge
Diffstat:
12 files changed, 1996 insertions(+), 916 deletions(-)
diff --git a/Makefile b/Makefile
@@ -49,8 +49,11 @@ help:
clean:
rm -rf $(BUILDDIR)/*
+# The html-linked builder does not support caching, so we
+# remove all cached state first.
html:
- $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ rm -rf $(BUILDDIR)/*
+ $(SPHINXBUILD) -b html-linked $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
diff --git a/api-common.rst b/api-common.rst
@@ -0,0 +1,476 @@
+.. _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 mint,
+ 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 mint 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 mint 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 {
+ // Description of the error, i.e. "missing parameter", "commitment violation", ...
+ // The other arguments are specific to the error value reported here.
+ error: 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.
+
+
+
+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:
+
+Public Keys
+^^^^^^^^^^^
+
+EdDSA and ECDHE public keys are always points on Curve25519 and represented
+using the standard 256 bits Ed25519 compact format, converted to Crockford
+Base32_.
+
+.. _signature:
+
+Signatures
+^^^^^^^^^^
+
+The specific signature scheme in use, like RSA blind signatures or EdDSA,
+depends on the context. RSA blind signatures are only used for coins and
+always simply base32_ encoded.
+
+EdDSA signatures are transmitted as 64-byte base32_ binary-encoded objects with
+just the R and S values (base32_ binary-only). These signed objects always
+contain a purpose number unique to the context in which the signature is used,
+but frequently the actual binary-object must be reconstructed locally from
+information available only in context, such as recent messages or account
+detals. These objects are described in detail in :ref:`Signatures`.
+
+
+.. _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 (10e-6)
+ // of the base currency value. For example, a fraction
+ // of 500,000 would correspond to 50 cents.
+ fraction: number;
+ }
+
+
+--------------
+Binary Formats
+--------------
+
+ .. note::
+
+ This section largely corresponds to the definitions in taler_signatures.h.
+ You may also want to refer to this code, as it offers additional details
+ on each of the members of the structs.
+
+ .. 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.
+
+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_AmountNBO {
+ uint64_t value;
+ uint32_t fraction;
+ 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"
+(distant future, eternity).
+
+.. sourcecode:: c
+
+ struct GNUNET_TIME_AbsoluteNBO {
+ uint64_t timestamp_us;
+ };
+
+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];
+ };
+
+ struct TALER_ReservePublicKeyP {
+ uint8_t eddsa_pub[32];
+ };
+
+ struct TALER_ReservePrivateKeyP {
+ uint8_t eddsa_priv[32];
+ };
+
+ struct TALER_ReserveSignatureP {
+ uint8_t eddsa_signature[64];
+ };
+
+ 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];
+ };
+
+ struct TALER_MintPublicKeyP {
+ uint8_t eddsa_pub[32];
+ };
+
+ struct TALER_MintPrivateKeyP {
+ uint8_t eddsa_priv[32];
+ };
+
+ struct TALER_MintSignatureP {
+ 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];
+ };
+
+ union TALER_CoinSpendPublicKeyP {
+ uint8_t eddsa_pub[32];
+ uint8_t ecdhe_pub[32];
+ };
+
+ 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)];
+ };
+
+ struct TALER_LinkSecretP {
+ uint8_t key[sizeof (struct GNUNET_HashCode)];
+ };
+
+ struct TALER_EncryptedLinkSecretP {
+ uint8_t enc[sizeof (struct TALER_LinkSecretP)];
+ };
+
+.. _Signatures:
+
+Signatures
+^^^^^^^^^^
+
+Please note that any RSA signature is processed by a function called
+`GNUNET_CRYPTO_rsa_signature_encode (..)` **before** being sent over the
+network, so the receiving party must run `GNUNET_CRYPTO_rsa_signature_decode
+(..)` before verifying it. See their implementation in `src/util/crypto_rsa.c`,
+in GNUNET's code base. Finally, they are defined in
+`gnunet/gnunet_crypto_lib.h`.
+
+EdDSA signatures are always made on the hash of a block of the same generic
+format, the `struct SignedData` given below. In our notation, the type of a
+field can depend on the value of another field. For the following message, the
+length of the `payload` array must match the value of the `size` field:
+
+.. sourcecode:: c
+
+ struct SignedData {
+ uint32_t size;
+ uint32_t purpose;
+ uint8_t payload[size - sizeof (struct SignedData)];
+ };
+
+The `purpose` field in `struct SignedData` 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. The various `purpose` constants are
+defined in `taler_signatures.h`. The `size` field prevents padding attacks.
+
+In the subsequent messages, we use the following notation for signed data
+described in `FIELDS` with the given purpose.
+
+.. sourcecode:: c
+
+ signed (purpose = SOME_CONSTANT) {
+ FIELDS
+ } msg;
+
+The `size` field of the corresponding `struct SignedData` is determined by the
+size of `FIELDS`.
+
+.. sourcecode:: c
+
+ struct TALER_WithdrawRequestPS {
+ signed (purpose = TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW) {
+ 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;
+ }
+ };
+
+ struct TALER_DepositRequestPS {
+ signed (purpose = TALER_SIGNATURE_WALLET_COIN_DEPOSIT) {
+ 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;
+ }
+ };
+
+ struct TALER_DepositConfirmationPS {
+ signed (purpose = TALER_SIGNATURE_MINT_CONFIRM_DEPOSIT) {
+ 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;
+ }
+ };
+
+ struct TALER_RefreshMeltCoinAffirmationPS {
+ signed (purpose = TALER_SIGNATURE_WALLET_COIN_MELT) {
+ struct GNUNET_HashCode session_hash;
+ struct TALER_AmountNBO amount_with_fee;
+ struct TALER_AmountNBO melt_fee;
+ union TALER_CoinSpendPublicKeyP coin_pub;
+ }
+ };
+
+ struct TALER_RefreshMeltConfirmationPS {
+ signed (purpose = TALER_SIGNATURE_MINT_CONFIRM_MELT) {
+ struct GNUNET_HashCode session_hash;
+ uint16_t noreveal_index;
+ }
+ };
+
+ struct TALER_MintSigningKeyValidityPS {
+ signed (purpose = TALER_SIGNATURE_MASTER_SIGNING_KEY_VALIDITY) {
+ struct TALER_MasterPublicKeyP master_public_key;
+ struct GNUNET_TIME_AbsoluteNBO start;
+ struct GNUNET_TIME_AbsoluteNBO expire;
+ struct GNUNET_TIME_AbsoluteNBO end;
+ struct TALER_MintPublicKeyP signkey_pub;
+ }
+ };
+
+ struct TALER_MintKeySetPS {
+ signed (purpose=TALER_SIGNATURE_MINT_KEY_SET) {
+ struct GNUNET_TIME_AbsoluteNBO list_issue_date;
+ struct GNUNET_HashCode hc;
+ }
+ };
+
+ struct TALER_DenominationKeyValidityPS {
+ signed (purpose = TALER_SIGNATURE_MASTER_DENOMINATION_KEY_VALIDITY) {
+ 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;
+ }
+ };
+
+ struct TALER_MasterWireSepaDetailsPS {
+ signed (purpose = TALER_SIGNATURE_MASTER_SEPA_DETAILS) {
+ struct GNUNET_HashCode h_sepa_details;
+ }
+ };
+
+ struct TALER_MintWireSupportMethodsPS {
+ signed (purpose = TALER_SIGNATURE_MINT_WIRE_TYPES) {
+ struct GNUNET_HashCode h_wire_types;
+ }
+ };
+
+ struct TALER_DepositTrackPS {
+ signed (purpose = TALER_SIGNATURE_MERCHANT_DEPOSIT_WTID) {
+ struct GNUNET_HashCode h_contract;
+ struct GNUNET_HashCode h_wire;
+ uint64_t transaction_id;
+ struct TALER_MerchantPublicKeyP merchant;
+ struct TALER_CoinSpendPublicKeyP coin_pub;
+ }
+ };
diff --git a/api-merchant.rst b/api-merchant.rst
@@ -18,26 +18,6 @@ provided in the HTTP "Date:" header for this purpose, but the customer
is expected to check that the time of his machine is approximately
correct.
-
-------------------------------
-Frontend-Backend communication
-------------------------------
-
-To create a contract, the `frontend` needs to generate the body of a
-`contract` in JSON format. This `proposition` is then signed by the
-`backend` and then sent to the wallet. If the customer approves
-the `proposition`, the wallet signs the body of the `contract`
-using coins in the form of a `deposit permission`. This signature
-using the coins signifies both agreement of the customer and
-represents payment at the same time. The `frontend` passes the
-`deposit permission` to the `backend` which immediately verifies it
-with the mint and signals the `frontend` the success or failure of
-the payment process. If the payment is successful, the `frontend` is
-responsible for generating the fullfillment page.
-
-The contract format is specified in the `contract`_ section.
-
-
---------
Encodings
---------
@@ -46,28 +26,43 @@ Data such as dates, binary blobs, and other useful formats, are encoded as descr
.. _contract:
-Contract
-^^^^^^^^
+Offer and Contract
+^^^^^^^^^^^^^^^^^^
+
+An `offer` is a wrapper around a contract with some additional information
+that is legally non-binding:
-A `contract` is a JSON object having the following structure, which is returned as a
-successful response to the following two calls:
+ .. _tsref-type-Offer:
+ .. code-block:: tsref
+ :name: offer
-.. note::
+ interface Offer {
+ // The actual contract
+ contract: Contract;
- This section holds just a central definition for the `contract`, so refer to each component's
- section for its detailed REST interaction.
+ // The hash of the contract, provided as a convenience.
+ // All components that do not fully trust the
+ // merchant must verify this field.
+ H_contract: HashCode;
-.. http:get:: /taler/contract
+ // Signature over the contract made by the merchant.
+ // Must confirm to the `Signature specification`_ below.
+ sig: EddsaSignature;
- Issued by the wallet when the customer wants to see the contract for a certain purchase
+ // URL where the customer's wallet
+ // must send the payment for the contract.
+ // May be relative to the URL of the page that
+ // delivered the contract.
+ pay_url: string;
-.. http:post:: /contract
+ // URL to the `execution page`_.
+ exec_url: string;
+ }
- Issued by the frontend to the backend when it wants to augment its `proposition` with all the
- cryptographic information. For the sake of precision, the frontend encloses the following JSON inside a `contract`
- field to the actual JSON sent to the backend.
+The contract must have the following structure:
- .. code-block:: ts
+ .. _tsref-type-Contract:
+ .. code-block:: tsref
interface Contract {
// Total price for the transaction.
@@ -81,7 +76,7 @@ successful response to the following two calls:
// 53-bit number chosen by the merchant to uniquely identify the contract.
transaction_id: number;
- // List of products that are part of the purchase (see below)
+ // List of products that are part of the purchase (see `below)
products: Product[];
// Time when this contract was generated
@@ -109,19 +104,17 @@ successful response to the following two calls:
// Mints that the merchant accepts even if it does not accept any auditors that audit them.
mints: Mint[];
- // object locations: maps labels for locations to detailed geographical location data
- // (details for the format of locations are specified below).
- // The label strings must not contain a colon (`:`)
- // These locations can then be references by their respective labels throughout the contract.
- locations;
+ // Map from label to a `Location`_.
+ // The label strings must not contain a colon (`:`).
+ locations: { [label: string]: Location>;
}
-
The wallet must select a mint that either the mechant accepts directly by listing it in the mints arry, or for which the merchant accepts an auditor that audits that mint by listing it in the auditors array.
The `product` object describes the product being purchased from the merchant. It has the following structure:
- .. code-block:: ts
+ .. _tsref-type-Product:
+ .. code-block:: tsref
interface Product {
// Human-readable product description.
@@ -149,8 +142,7 @@ successful response to the following two calls:
delivery_location: string;
}
- The `merchant` object:
-
+ .. _tsref-type-Merchant:
.. code-block:: ts
interface Merchant {
@@ -166,25 +158,21 @@ successful response to the following two calls:
}
- The `location` object:
-
+ .. _Location:
+ .. _tsref-type-Location:
.. code-block:: ts
interface Location {
- country: string;
- city: string;
- state: string;
- region: string;
- province: string;
- zip_code: string;
- street: string;
- street_number: string;
+ country?: string;
+ city?: string;
+ state?: string;
+ region?: string;
+ province?: string;
+ zip_code?: string;
+ street?: string;
+ street_number?: string;
}
- Depending on the country, some fields may be missing
-
- The `auditor` object:
-
.. code-block:: ts
interface Auditor {
@@ -197,10 +185,6 @@ successful response to the following two calls:
url: string;
}
-
- The `mint` object:
-
-
.. code-block:: ts
interface Mint {
@@ -210,22 +194,23 @@ successful response to the following two calls:
// master public key of the mint
master_pub: EddsaPublicKey;
}
+
+.. _`Signature specification`:
When the contract is signed by the merchant or the wallet, the
signature is made over the hash of the JSON text, as the contract may
be confidential between merchant and customer and should not be
exposed to the mint. The hashcode is generated by hashing the
encoding of the contract's JSON obtained by using the flags
-`JSON_COMPACT | JSON_PRESERVE_ORDER`, as described in the `libjansson
+``JSON_COMPACT | JSON_PRESERVE_ORDER``, as described in the `libjansson
documentation
<https://jansson.readthedocs.org/en/2.7/apiref.html?highlight=json_dumps#c.json_dumps>`_.
The following structure is a container for the signature. The purpose
-should be set to `TALER_SIGNATURE_MERCHANT_CONTRACT`.
+should be set to ``TALER_SIGNATURE_MERCHANT_CONTRACT``.
.. _contract-blob:
-
-.. sourcecode:: c
+.. code-block:: c
struct MERCHANT_Contract
{
@@ -233,102 +218,14 @@ should be set to `TALER_SIGNATURE_MERCHANT_CONTRACT`.
struct GNUNET_HashCode h_contract;
}
----------------
-Wallet-Frontend
----------------
-
-.. _message-passing-ref:
-
-
-When the user chooses to pay, the page needs to inform the extension
-that it should execute the payment process. This is done by sending
-a
-
- .. js:data:: taler-contract
-
-event to the extension. The following example code fetches the
-contract from the merchant website and passes it to the extension
-when the button is clicked:
-
-.. sourcecode:: javascript
-
- function deliver_contract_to_wallet(jsonContract){
- var cevent = new CustomEvent('taler-contract', { detail: jsonContract });
- document.body.dispatchEvent(cevent);
- };
-
- function taler_pay(form){
- var contract_req = new XMLHttpRequest();
- // request contract from merchant website, i.e.:
- contract_req.open("GET", "/taler/contract", true);
- contract_req.onload = function (ev){
- if (contract_req.readyState == 4){ // HTTP request is done
- if (contract_req.status == 200){ // HTTP 200 OK
- deliver_contract_to_wallet(contract_req.responseText);
- }else{
- alert("Merchant failed to generate contract: " + contract_req.status);
- }
- }
- };
- contract_req.onerror = function (ev){
- // HTTP request failed, we didn't even get a status code...
- alert(contract_req.statusText);
- };
- contract_req.send(null); // run the GET request
- };
-
-.. sourcecode:: html
-
- <input type="button" onclick="taler_pay(this.form)" value="Ok">
-
-
-In this example, the function `taler_pay` is attached to the
-'checkout' button. This function issues the required POST and passes
-the contract to the wallet in the the function
-`deliver_contract_to_wallet` if the contract was received correctly
-(i.e. HTTP response code was 200 OK).
-
----------------
-The RESTful API
----------------
-
-The merchant's frontend must provide the JavaScript logic with the
-ability to fetch the JSON contract. In the example above, the
-JavaScript expected the contract at `/taler/contract` and the payment
-to go to '/taler/pay'. However, it is possible to deliver the
-contract from any URL and post the deposit permission to any URL,
-as long as the client-side logic knows how to fetch it and pass it to
-the extension. For example, the contract could already be embedded in
-the webpage or be at a contract-specific URL to avoid relying on
-cookies to identify the shopping session.
-
-
-.. http:get:: /taler/contract
-
- Triggers the contract generation. Note that the URL may differ between
- merchants.
-
- **Success Response**
-
- :status 200 OK: The request was successful.
- :resheader Content-Type: application/json
- :>json base32 contract: a :ref:`JSON contract <contract>` for this deal deprived of `pay_url` and `exec_url`
- :>json base32 sig: the signature of the binary described in :ref:`blob <contract-blob>`.
- :>json string pay_url: relative URL where the wallet should issue the payment
- :>json string exec_url: FIXME
- :>json base32 H_contract: the base32 encoding of the field `h_contract` of the contract's :ref:`blob <contract-blob>`
-
- **Failure Response**
-
- In most cases, the response will just be the forwarded response that the `frontend` got from the `backend`.
-
- :status 400 Bad Request: Request not understood.
- :status 500 Internal Server Error: In most cases, some error occurred while the backend was generating the contract. For example, it failed to store it into its database.
-
+---------------------
+The Merchant HTTP API
+---------------------
-.. _deposit-permission:
+In the following requests, ``$``-variables refer to the variables in the
+merchant's offer.
-.. http:post:: /taler/pay
+.. http:post:: $pay_url
Send the deposit permission to the merchant. Note that the URL may differ between
merchants.
@@ -359,3 +256,15 @@ cookies to identify the shopping session.
The error codes and data sent to the wallet are a mere copy of those gotten from the mint when attempting to pay. The section about :ref:`deposit <deposit>` explains them in detail.
+.. http:post:: $exec_url
+
+ Returns a cooperative merchant page (called the execution page) that will
+ send the ``taler-execute-payment`` to the wallet and react to failure or
+ success of the actual payment.
+
+ The wallet will inject an ``XMLHttpRequest`` request to the merchant's
+ ``$pay_url`` in the context of the execution page. This mechanism is
+ necessary since the request to ``$pay_url`` must be made from the merchant's
+ origin domain in order to preserve information (e.g. cookies).
+
+
diff --git a/api-mint.rst b/api-mint.rst
@@ -2,150 +2,184 @@
The Mint RESTful JSON API
=========================
--------
-General
--------
-
-.. _encodings-ref:
-
-++++++++++++++++
-Common encodings
-++++++++++++++++
-
-This section describes how certain types of values are represented throughout the API.
-
- .. _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.
-
- * **Large numbers**: Large numbers such as RSA blinding factors and 256 bit keys, are transmitted as other binary data in Crockford Base32 encoding.
+The API specified here follows the :ref:`general conventions <http-common>`
+for all details not specified in the individual requests.
- .. _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:
-
- * **Public key**: EdDSA and ECDHE public keys are always points on Curve25519 and represented using the standard 256 bits Ed25519 compact format, converted to Crockford Base32_.
-
- .. _Signature:
-
- * **Signatures**: The specific signature scheme in use, like RSA blind signatures or EdDSA, depends on the context. RSA blind signatures are only used for coins and always simply base32_ encoded.
-
-EdDSA signatures are transmitted as 64-byte base32_ binary-encoded objects with just the R and S values (base32_ binary-only).
-These signed objects always contain a purpose number unique to the context in which the signature is used, but frequently the actual binary-object must be reconstructed locally from information available only in context, such as recent messages or account detals.
-These objects are described in detail in :ref:`Signatures`.
-
- .. _Amount:
+-------------------
+Obtaining Mint Keys
+-------------------
- * **Amounts**: Amounts of currency are expressed as a JSON object with the following fields:
+This API is used by wallets and merchants to obtain global information about
+the mint, such as online signing keys, available denominations and the fee
+structure. This is typically the first call any mint client makes, as it
+returns information required to process all of the other interactions with the
+mint. The returned information is secured by (1) signature(s) from the mint,
+especially the long-term offline signing key of the mint, which clients should
+cache; (2) signature(s) from auditors, and the auditor keys should be
+hard-coded into the wallet as they are the trust anchors for Taler; (3)
+possibly by using HTTPS.
- * `currency`: 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.
- * `value`: 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.
- * `fraction`: unsigned 32 bit fractional value to be added to `value` representing an additional currency fraction, in units of one millionth (10\ :superscript:`-6`) of the base currency value. For example, a fraction of 500,000 would correspond to 50 cents.
+.. http:get:: /keys
-++++++++++++++
-General errors
-++++++++++++++
+ Get a list of all denomination keys offered by the bank,
+ as well as the bank's current online signing key.
-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.
+ **Response:**
+
+ :status 200 OK:
+ The mint responds with a `MintKeysResponse`_ object. This request should
+ virtually always be successful.
+
+ **Details:**
+
+ .. _MintKeysResponse:
+ .. code-block:: tsref
+
+ interface MintKeysResponse {
+ // EdDSA master public key of the mint, used to sign entries in `denoms` and `signkeys`
+ master_public_key: EddsaPublicKey;
+
+ // Denomination offered by this mint.
+ denoms: Denom[];
+
+ // The date when the denomination keys were last updated.
+ list_issue_date: string;
+
+ // Auditors of the mint.
+ auditors: Auditor[];
+
+ // The mint's signing keys.
+ signkeys: SignKey[];
+
+ // compact EdDSA signature_ (binary-only) over the SHA-512 hash of the
+ // concatenation of all SHA-512 hashes of the RSA denomination public keys
+ // in `denoms` in the same order as they were in `denoms`. Note that for
+ // hashing, the binary format of the RSA public keys is used, and not their
+ // base32_ encoding. Wallets cannot do much with this signature by itself;
+ // it is only useful when multiple clients need to establish that the mint
+ // is sabotaging end-user anonymity by giving disjoint denomination keys to
+ // different users. If a mint were to do this, this signature allows the
+ // clients to demonstrate to the public that the mint is dishonest.
+ eddsa_sig: string;
+
+ // Public EdDSA key of the mint that was used to generate the signature.
+ // Should match one of the mint's signing keys from /keys. It is given
+ // explicitly as the client might otherwise be confused by clock skew as to
+ // which signing key was used.
+ eddsa_pub: string;
+ }
-.. http:any:: /*
+ .. _tsref-type-Denom:
+ .. code-block:: tsref
- **Error Response: Internal error**
+ interface Denom {
+ // How much are coins of this denomination worth?
+ value: Amount;
- When encountering an internal error, the mint may respond to any request with an internal server error.
+ // When does the denomination key become valid?
+ stamp_start: Timestamp;
- :status 500 Internal server error: This always indicates some serious internal operational error of the mint, 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 mint 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 mint responds with a JSON object containing the following fields:
+ // When is it no longer possible to withdraw fresh coins
+ // of this denomination?
+ stamp_expire_withdraw: Timestamp;
- :resheader Content-Type: application/json
- :>json error: a string with the value "internal error"
- :>json hint: a string with problem-specific human-readable diagnostic text and typically useful for the mint operator
+ // When is it no longer possible to deposit coins
+ // of this denomination?
+ stamp_expire_withdraw: Timestamp;
+ // Timestamp indicating by when legal disputes relating to these coins must
+ // be settled, as the mint will afterwards destroy its evidence relating to
+ // transactions involving this coin.
+ stamp_expire_legal: Timestamp;
- **Error Response: Bad Request**
+ // Public (RSA) key for the denomination in base32 encoding.
+ denom_pub: string;
- When the client issues a malformed request with missing parameters or where the parameters fail to comply with the specification, the mint generates this type of response. The error should be shown to the user, while the other details are mostly intended as optional diagnostics for developers.
+ // Fee charged by the mint for withdrawing a coin of this denomination
+ fee_withdraw: Amount;
- :status 400 Bad Request: One of the arguments to the request is missing or malformed.
- :resheader Content-Type: application/json
- :>json string error: description of the error, i.e. missing parameter, malformed parameter, commitment violation, etc. The other arguments are specific to the error value reported here.
- :>json string parameter: name of the parameter that was bogus (if applicable)
- :>json string path: path to the argument that was bogus (if applicable)
- :>json string offset: offset of the argument that was bogus (if applicable)
- :>json string index: index of the argument that was bogus (if applicable)
- :>json string object: name of the component of the object that was bogus (if applicable)
- :>json string currency: currency that was problematic (if applicable)
- :>json string type_expected: expected type (if applicable)
- :>json string type_actual: type that was provided instead (if applicable)
+ // Fee charged by the mint for depositing a coin of this denomination
+ fee_deposit: Amount;
+ // Fee charged by the mint for refreshing a coin of this denomination
+ fee_refresh: Amount;
+ // Signature with purpose
+ // `TALER_SIGNATURE_MASTER_DENOMINATION_KEY_VALIDITY` over the expiration
+ // dates, value and the key, created with the mint's master key.
+ master_sig: EddsaSignature;
+ }
--------------------
-Obtaining Mint Keys
--------------------
+ Fees for any of the operations can be zero, but the fields must still be
+ present. The currency of the `fee_deposit` and `fee_refresh` must match the
+ currency of the `value`. Theoretically, the `fee_withdraw` could be in a
+ different currency, but this is not currently supported by the
+ implementation.
-This API is used by wallets and merchants to obtain global information about the mint, such as online signing keys, available denominations and the fee structure.
-This is typically the first call any mint client makes, as it returns information required to process all of the other interactions with the mint. The returned
-information is secured by (1) signature(s) from the mint, especially the long-term offline signing key of the mint, which clients should cache; (2) signature(s)
-from auditors, and the auditor keys should be hard-coded into the wallet as they are the trust anchors for Taler; (3) possibly by using HTTPS.
+ A signing key in the `signkeys` list is a JSON object with the following fields:
+ .. _tsref-type-SignKey:
+ .. code-block:: tsref
-.. http:get:: /keys
+ interface SignKey {
+ // The actual mint's EdDSA signing public key.
+ key: EddsaPublicKey;
- Get a list of all denomination keys offered by the bank,
- as well as the bank's current online signing key.
+ // Initial validity date for the signing key.
+ stamp_start: Timestamp;
- **Success Response: OK**
-
- :status 200 OK: This request should virtually always be successful.
- :resheader Content-Type: application/json
- :>json base32 master_public_key: EdDSA master public key of the mint, used to sign entries in `denoms` and `signkeys`
- :>json list denoms: A JSON list of denomination descriptions. Described below in detail.
- :>json date list_issue_date: The date when the denomination keys were last updated.
- :>json list auditors: A JSON list of the auditors of the mint. Described below in detail.
- :>json list signkeys: A JSON list of the mint's signing keys. Described below in detail.
- :>json base32 eddsa_sig: compact EdDSA signature_ (binary-only) over the SHA-512 hash of the concatenation of all SHA-512 hashes of the RSA denomination public keys in `denoms` in the same order as they were in `denoms`. Note that for hashing, the binary format of the RSA public keys is used, and not their base32_ encoding. Wallets cannot do much with this signature by itself; it is only useful when multiple clients need to establish that the mint is sabotaging end-user anonymity by giving disjoint denomination keys to different users. If a mint were to do this, this signature allows the clients to demonstrate to the public that the mint is dishonest.
- :>json base32 eddsa_pub: public EdDSA key of the mint that was used to generate the signature. Should match one of the mint's signing keys from /keys. It is given explicitly as the client might otherwise be confused by clock skew as to which signing key was used.
-
- A denomination description in the `denoms` list is a JSON object with the following fields:
-
- :>jsonarr object value: Amount_ of the denomination. A JSON object specifying an amount_.
- :>jsonarr date stamp_start: timestamp_ indicating when the denomination key becomes valid.
- :>jsonarr date stamp_expire_withdraw: timestamp_ indicating when the denomination key can no longer be used to withdraw fresh coins.
- :>jsonarr date stamp_expire_deposit: timestamp_ indicating when coins of this denomination become invalid for depositing.
- :>jsonarr date stamp_expire_legal: timestamp_ indicating by when legal disputes relating to these coins must be settled, as the mint will afterwards destroy its evidence relating to transactions involving this coin.
- :>jsonarr base32 denom_pub: Public (RSA) key for the denomination in base32_ encoding.
- :>jsonarr object fee_withdraw: Fee charged by the mint for withdrawing a coin of this type, encoded as a JSON object specifying an amount_.
- :>jsonarr object fee_deposit: Fee charged by the mint for depositing a coin of this type, encoded as a JSON object specifying an amount_.
- :>jsonarr object fee_refresh: Fee charged by the mint for melting a coin of this type during a refresh operation, encoded as a JSON object specifying an amount_. Note that the total refreshing charges will be the sum of the refresh fees for all of the melted coins and the sum of the withdraw fees for all "new" coins.
- :>jsonarr base32 master_sig: Signature_ (binary-only) with purpose `TALER_SIGNATURE_MASTER_DENOMINATION_KEY_VALIDITY` over the expiration dates, value and the key, created with the mint's master key.
-
- Fees for any of the operations can be zero, but the fields must still be present. The currency of the `fee_deposit` and `fee_refresh` must match the currency of the `value`. Theoretically, the `fee_withdraw` could be in a different currency, but this is not currently supported by the implementation.
+ // Date when the mint will stop using the signing key, allowed to overlap
+ // slightly with the next signing key's validity to allow for clock skew.
+ stamp_expire: Timestamp;
- A signing key in the `signkeys` list is a JSON object with the following fields:
+ // Date when all signatures made by the signing key expire and should
+ // henceforth no longer be considered valid in legal disputes.
+ stamp_end: Timestamp;
- :>jsonarr base32 key: The actual mint's EdDSA signing public key.
- :>jsonarr date stamp_start: Initial validity date for the signing key.
- :>jsonarr date stamp_expire: Date when the mint will stop using the signing key, allowed to overlap slightly with the next signing key's validity to allow for clock skew.
- :>jsonarr date stamp_end: Date when all signatures made by the signing key expire and should henceforth no longer be considered valid in legal disputes.
- :>jsonarr date stamp_expire: Expiration date for the signing key.
- :>jsonarr base32 master_sig: A signature_ (binary-only) with purpose `TALER_SIGNATURE_MASTER_SIGNING_KEY_VALIDITY` over the `key` and `stamp_expire` by the mint master key.
+ // Signature over `key` and `stamp_expire` by the mint master key.
+ // Must have purpose TALER_SIGNATURE_MASTER_SIGNING_KEY_VALIDITY.
+ master_sig: EddsaSignature;
+ }
An entry in the `auditors` list is a JSON object with the following fields:
- :>jsonarr base32 auditor_pub: The auditor's EdDSA signing public key.
- :>jsonarr array denomination_keys: An array of denomination keys the auditor affirms with its signature. Note that the message only includes the hash of the public key, while the signature is actually over the expanded information including expiration times and fees. The exact format is described below.
+ .. _tsref-type-Auditor:
+ .. code-block:: tsref
+
+ interface Auditor {
+ // The auditor's EdDSA signing public key.
+ auditor_pub: EddsaPublicKey;
- An entry in the `denomination_keys` list is a JSON object with the following field:
+ // An array of denomination keys the auditor affirms with its signature.
+ // Note that the message only includes the hash of the public key, while the
+ // signature is actually over the expanded information including expiration
+ // times and fees. The exact format is described below.
+ denomination_keys: DenominationKey[];
+ }
- :>jsonarr base32 denom_pub_h: hash of the public RSA key used to sign coins of the respective denomination. Note that the auditor's signature covers more than just the hash, but this other information is already provided in `denoms` and thus not repeated here.
- :>jsonarr base32 auditor_sig: A signature_ (binary-only) with purpose `TALER_SIGNATURE_AUDITOR_MINT_KEYS` over the mint's public key and the denomination key information. To verify the signature, the `denom_pub_h` must be resolved with the information from `denoms`.
+ .. _tsref-type-DenominationKey:
+ .. code-block:: tsref
+
+ interface DenominationKey {
+ // hash of the public RSA key used to sign coins of the respective
+ // denomination. Note that the auditor's signature covers more than just
+ // the hash, but this other information is already provided in `denoms` and
+ // thus not repeated here.
+ denom_pub_h: HashCode;
+
+ // A signature_ (binary-only) with purpose
+ // `TALER_SIGNATURE_AUDITOR_MINT_KEYS` over the mint's public key and the
+ // denomination key information. To verify the signature, the `denom_pub_h`
+ // must be resolved with the information from `denoms`
+ auditor_sig: EddsaSignature;
+ }
- The same auditor may appear multiple times in the array for different subsets of denomination keys, and the same denomination key hash may be listed multiple times for the same or different auditors. The wallet or merchant just should check that the denomination keys they use are in the set for at least one of the auditors that they accept.
+ The same auditor may appear multiple times in the array for different subsets
+ of denomination keys, and the same denomination key hash may be listed
+ multiple times for the same or different auditors. The wallet or merchant
+ just should check that the denomination keys they use are in the set for at
+ least one of the auditors that they accept.
.. note::
@@ -160,13 +194,34 @@ Obtaining wire-transfer information
Returns a list of payment methods supported by the mint. The idea is that wallets may use this information to instruct users on how to perform wire transfers to top up their wallets.
- **Success response: OK**
+ **Response:**
+
+ :status 200: The mint responds with a `WireResponse`_ object. This request should virtually always be successful.
+
+ **Details:**
+
+ .. _WireResponse:
+ .. _tsref-type-WireResponse:
+ .. code-block:: tsref
+
+ interface WireResponse {
+ // Names of supported methods (i.e. "sepa" or "test").
+ // Payment method METHOD is available under /wire/METHOD.
+ methods: string[];
+
+ // the EdDSA signature_ (binary-only) with purpose
+ // `TALER_SIGNATURE_MINT_PAYMENT_METHODS` signing over the hash over the
+ // 0-terminated strings representing the payment methods in the same order
+ // as given in methods.
+ sig: EddsaSignature;
+
+ // public EdDSA key of the mint that was used to generate the signature.
+ // Should match one of the mint's signing keys from /keys. It is given
+ // explicitly as the client might otherwise be confused by clock skew as to
+ // which signing key was used.
+ pub: EddsaPublicKey;
+ }
- :status 200: This request should virtually always be successful.
- :resheader Content-Type: application/json
- :>json array methods: a JSON array of strings with supported payment methods, i.e. "sepa". Further information about the respective payment method is then available under /wire/METHOD, i.e. /wire/sepa if the payment method was "sepa".
- :>json base32 sig: the EdDSA signature_ (binary-only) with purpose `TALER_SIGNATURE_MINT_PAYMENT_METHODS` signing over the hash over the 0-terminated strings representing the payment methods in the same order as given in methods.
- :>json base32 pub: public EdDSA key of the mint that was used to generate the signature. Should match one of the mint's signing keys from /keys. It is given explicitly as the client might otherwise be confused by clock skew as to which signing key was used.
.. http:get:: /wire/test
@@ -175,30 +230,40 @@ Obtaining wire-transfer information
in "test" mode, this request provides a redirect to an address where
the user can initiate a fake wire transfer for testing.
- **Success Response: OK**
-
:status 302: Redirect to the webpage where fake wire transfers can be made.
+ :status 501: This wire transfer method is not supported by this mint.
+
+.. http:get:: /wire/sepa
- **Failure Response: Not implemented**
+ Provides instructions for how to transfer funds to the mint using the SEPA
+ transfers. Always signed using the mint's long-term offline master public
+ key.
+ :status 200: The mint responds with a `WireSepaResponse`_ object. This request should virtually always be successful.
:status 501: This wire transfer method is not supported by this mint.
+
-.. http:get:: /wire/sepa
+ **Details:**
- Provides instructions for how to transfer funds to the mint using the SEPA transfers. Always signed using the mint's long-term offline master public key.
+ .. _WireSepaResponse:
+ .. _tsref-type-WireSepaResponse:
+ .. code-block:: tsref
- **Success Response: OK**
+ interface WireSepaResponse {
+ // Legal name of the mint operator who is receiving the funds
+ receiver_name: string;
- :status 200: This request should virtually always be successful.
- :resheader Content-Type: application/json
- :>json string receiver_name: Legal name of the mint operator who is receiving the funds
- :>json string iban: IBAN account number for the mint
- :>json string bic: BIC of the bank of the mint
- :>json base32 sig: the EdDSA signature_ (binary-only) with purpose `TALER_SIGNATURE_MINT_PAYMENT_METHOD_SEPA` signing over the hash over the 0-terminated strings representing the receiver's name, IBAN and the BIC.
+ // IBAN account number for the mint
+ iban: string;
- **Failure Response: Not implemented**
+ // BIC of the bank of the mint
+ bic: string;
- :status 501: This wire transfer method is not supported by this mint.
+ // the EdDSA signature_ (binary-only) with purpose
+ // `TALER_SIGNATURE_MINT_PAYMENT_METHOD_SEPA` signing over the hash over the
+ // 0-terminated strings representing the receiver's name, IBAN and the BIC.
+ sig: EddsaSignature;
+ }
------------------
@@ -207,7 +272,12 @@ Withdrawal
This API is used by the wallet to obtain digital coins.
-When transfering money to the mint such as via SEPA transfers, the mint creates a *reserve*, which keeps the money from the customer. The customer must specify an EdDSA reserve public key as part of the transfer, and can then withdraw digital coins using the corresponding private key. All incoming and outgoing transactions are recorded under the corresponding public key by the mint.
+When transfering money to the mint such as via SEPA transfers, the mint creates
+a *reserve*, which keeps the money from the customer. The customer must
+specify an EdDSA reserve public key as part of the transfer, and can then
+withdraw digital coins using the corresponding private key. All incoming and
+outgoing transactions are recorded under the corresponding public key by the
+mint.
.. note::
@@ -218,276 +288,614 @@ When transfering money to the mint such as via SEPA transfers, the mint creates
Request information about a reserve.
+ .. note::
+ The client currently does not have to demonstrate knowledge of the private
+ key of the reserve to make this request, which makes the reserve's public
+ key privliged information known only to the client, their bank, and the
+ mint. In future, we might wish to revisit this decision to improve
+ security, such as by having the client EdDSA-sign an ECDHE key to be used
+ to derive a symmetric key to encrypt the response. This would be useful if
+ for example HTTPS were not used for communication with the mint.
+
+ **Request:**
+
:query reserve_pub: EdDSA reserve public key identifying the reserve.
- .. note::
- The client currently does not have to demonstrate knowledge of the private key of the reserve to make this request, which makes the reserve's public key privliged information known only to the client, their bank, and the mint. In future, we might wish to revisit this decision to improve security, such as by having the client EdDSA-sign an ECDHE key to be used to derive a symmetric key to encrypt the response. This would be useful if for example HTTPS were not used for communication with the mint.
+ **Response:**
- **Success Response: OK**
+ :status 200 OK:
+ The mint responds with a `ReserveStatus`_ object; the reserve was known to the mint,
+ :status 404 Not Found: The withdrawal key does not belong to a reserve known to the mint.
- :status 200 OK: The reserve was known to the mint, details about it follow in the body.
- :resheader Content-Type: application/json
- :>json object balance: Total amount_ left in this reserve, an amount_ expressed as a JSON object.
- :>json object history: JSON list with the history of transactions involving the reserve.
+ **Details:**
- Objects in the transaction history have the following format:
+ .. _ReserveStatus:
+ .. code-block:: tsref
- :>jsonarr string type: either the string "WITHDRAW" or the string "DEPOSIT"
- :>jsonarr object amount: the amount_ that was withdrawn or deposited
- :>jsonarr object wire: a JSON object with the wiring details needed by the banking system in use, present in case the `type` was "DEPOSIT"
- :>jsonarr string details: base32_ binary encoding of the transaction data as a `TALER_WithdrawRequestPS` struct described in :ref:`Signatures`, only present if the `type` was "WITHDRAW". Its `purpose` should match our `type`, `amount_with_fee`, should match our `amount`, and its `size` should be consistent.
- :>jsonarr object signature: the EdDSA signature_ (binary-only) made with purpose `TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW` over the transaction's details, again only present if the `type` was "WITHDRAW".
+ interface ReserveStatus {
+ // Balance left in the reserve.
+ balance: Amount;
- **Error Response: Unknown reserve**
+ // Transaction history for this reserve
+ history: TransactionHistoryItem[];
+ }
- :status 404 Not Found: The withdrawal key does not belong to a reserve known to the mint.
- :resheader Content-Type: application/json
- :>json string error: the value is always "Reserve not found"
- :>json string parameter: the value is always "withdraw_pub"
+ Objects in the transaction history have the following format:
+ .. _tsref-type-TransactionHistoryItem:
+ .. code-block:: tsref
-.. http:post:: /reserve/withdraw
+ interface TransactionHistoryItem {
+ // Either "WITHDRAW" or "DEPOSIT"
+ type: string;
+
+ // The amount that was withdrawn or deposited.
+ amount: Amount;
+
+ // Wiring details, only present if type is "DEPOSIT".
+ wire?: any;
- Withdraw a coin of the specified denomination. Note that the client should commit all of the request details, including the private key of the coin and the blinding factor, to disk *before* issuing this request, so that it can recover the information if necessary in case of transient failures, like power outage, network outage, etc.
+ // binary encoding of the transaction data as a `TALER_WithdrawRequestPS`
+ // struct described in :ref:`Signatures`, only present if the `type` was
+ // "WITHDRAW". Its `purpose` should match our `type`, `amount_with_fee`,
+ // should match our `amount`, and its `size` should be consistent.
+ string?: details;
- :reqheader Content-Type: application/json
- :<json base32 denom_pub: denomination public key (RSA), specifying the type of coin the client would like the mint to create.
- :<json base32 coin_ev: coin's blinded public key, should be (blindly) signed by the mint's denomination private key
- :<json base32 reserve_pub: public (EdDSA) key of the reserve from which the coin should be withdrawn. The total amount deducted will be the coin's value plus the withdrawal fee as specified with the denomination information.
- :<json object reserve_sig: EdDSA signature_ (binary-only) of purpose `TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW` created with the reserves's private key
+ // Signature over the transaction details.
+ // Purpose: TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW
+ signature?: EddsaSignature;
+ }
- **Success Response: OK**:
- :status 200 OK: The request was succesful. Note that repeating exactly the same request will again yield the same response, so if the network goes down during the transaction or before the client can commit the coin signature_ to disk, the coin is not lost.
- :resheader Content-Type: application/json
- :>json base32 ev_sig: The RSA signature_ over the `coin_ev`, affirms the coin's validity after unblinding.
+.. http:post:: /reserve/withdraw
- **Error Response: Insufficient funds**:
+ Withdraw a coin of the specified denomination. Note that the client should
+ commit all of the request details, including the private key of the coin and
+ the blinding factor, to disk *before* issuing this request, so that it can
+ recover the information if necessary in case of transient failures, like
+ power outage, network outage, etc.
- :status 402 Payment Required: The balance of the reserve is not sufficient to withdraw a coin of the indicated denomination.
- :resheader Content-Type: application/json
- :>json string error: the value is "Insufficient funds"
- :>json object balance: a JSON object with the current amount_ left in the reserve
- :>json array history: a JSON list with the history of the reserve's activity, in the same format as returned by /reserve/status.
+ **Request:** The request body must be a `WithdrawRequest`_ object.
- **Error Response: Invalid signature**:
+ **Response:**
+ :status 200 OK:
+ The request was succesful, and the response is a `WithdrawResponse`. Note that repeating exactly the same request
+ will again yield the same response, so if the network goes down during the
+ transaction or before the client can commit the coin signature to disk, the
+ coin is not lost.
:status 401 Unauthorized: The signature is invalid.
- :resheader Content-Type: application/json
- :>json string error: the value is "invalid signature"
- :>json string paramter: the value is "reserve_sig"
+ :status 404 Not Found:
+ The denomination key or the reserve are not known to the mint. If the
+ denomination key is unknown, this suggests a bug in the wallet as the
+ wallet should have used current denomination keys from /keys. If the
+ reserve is unknown, the wallet should not report a hard error yet, but
+ instead simply wait for up to a day, as the wire transaction might simply
+ not yet have completed and might be known to the mint in the near future.
+ In this case, the wallet should repeat the exact same request later again
+ using exactly the same blinded coin.
+ :status 402 Payment Required:
+ The balance of the reserve is not sufficient to withdraw a coin of the indicated denomination.
+ The response is `WithdrawError`_ object.
+
+
+ **Details:**
+
+ .. _WithdrawRequest:
+ .. code-block:: tsref
+
+ interface WithdrawRequest {
+ // Denomination public key (RSA), specifying the type of coin the client
+ // would like the mint to create.
+ denom_pub: RsaPublicKey;
+
+ // coin's blinded public key, should be (blindly) signed by the mint's
+ // denomination private key
+ coin_ev: CoinEnvelope;
+
+ // public (EdDSA) key of the reserve from which the coin should be
+ // withdrawn. The total amount deducted will be the coin's value plus the
+ // withdrawal fee as specified with the denomination information.
+ reserve_pub: EddsaPublicKey;
+
+ // Signature (binary-only) of purpose
+ // `TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW` created with the reserves's
+ // private key
+ reserve_sig: EddsaSignature;
+ }
+
+
+ .. _WithdrawResponse:
+ .. code-block:: tsref
+
+ interface WithdrawResponse {
+ // The blinded RSA signature over the `coin_ev`, affirms the coin's
+ // validity after unblinding.
+ ev_sig: BlindedRsaSignature;
+ }
+
+ .. _WithdrawError:
+ .. code-block:: tsref
- **Error Response: Unknown key**:
+ interface WithdrawError {
+ // Constant "Insufficient funds"
+ error: string;
- :status 404 Not Found: The denomination key or the reserve are not known to the mint. If the denomination key is unknown, this suggests a bug in the wallet as the wallet should have used current denomination keys from /keys. If the reserve is unknown, the wallet should not report a hard error yet, but instead simply wait for up to a day, as the wire transaction might simply not yet have completed and might be known to the mint in the near future. In this case, the wallet should repeat the exact same request later again using exactly the same blinded coin.
- :resheader Content-Type: application/json
- :>json string error: "unknown entity referenced"
- :>json string parameter: either "denom_pub" or "reserve_pub"
+ // Amount left in the reserve
+ balance: Amount;
+
+ // History of the reserve's activity, in the same format as returned by /reserve/status.
+ history: TransactionHistoryItem[]
+ }
--------------------
Deposit
--------------------
-Deposit operations are requested by a merchant during a transaction. For the deposit operation, the merchant has to obtain the deposit permission for a coin from their customer who owns the coin. When depositing a coin, the merchant is credited an amount specified in the deposit permission, possibly a fraction of the total coin's value, minus the deposit fee as specified by the coin's denomination.
+Deposit operations are requested by a merchant during a transaction. For the
+deposit operation, the merchant has to obtain the deposit permission for a coin
+from their customer who owns the coin. When depositing a coin, the merchant is
+credited an amount specified in the deposit permission, possibly a fraction of
+the total coin's value, minus the deposit fee as specified by the coin's
+denomination.
.. _deposit:
.. http:POST:: /deposit
- Deposit the given coin and ask the mint to transfer the given amount to the merchants bank account. This API is used by the merchant to redeem the digital coins. The request should contain a JSON object with the following fields:
+ Deposit the given coin and ask the mint to transfer the given :ref:`amount`
+ to the merchants bank account. This API is used by the merchant to redeem
+ the digital coins. The request should contain a JSON object with the
+ following fields:
+
+ **Request:** The request body must be a `DepositRequest`_ object.
+
+ **Response:**
- :reqheader Content-Type: application/json
- :<json object f: the amount_ to be deposited, can be a fraction of the coin's total value
- :<json object `wire`: the merchant's account details. This must be a JSON object whose format must correspond to one of the supported wire transfer formats of the mint. See :ref:`wireformats`
- :<json base32 H_wire: SHA-512 hash of the merchant's payment details from `wire`. Although strictly speaking redundant, this helps detect inconsistencies.
- :<json base32 H_contract: SHA-512 hash of the contact of the merchant with the customer. Further details are never disclosed to the mint.
- :<json base32 coin_pub: coin's public key, both ECDHE and EdDSA.
- :<json base32 denom_pub: denomination RSA key with which the coin is signed
- :<json base32 ub_sig: mint's unblinded RSA signature_ of the coin
- :<json date timestamp: timestamp when the contract was finalized, must match approximately the current time of the mint
- :<json date edate: indicative time by which the mint undertakes to transfer the funds to the merchant, in case of successful payment.
- :<json int transaction_id: 64-bit transaction id for the transaction between merchant and customer
- :<json base32 merchant_pub: the EdDSA public key of the merchant, so that the client can identify the merchant for refund requests.
- :<json date refund_deadline: date until which the merchant can issue a refund to the customer via the mint, possibly zero if refunds are not allowed.
- :<json base32 coin_sig: the EdDSA signature_ (binary-only) made with purpose `TALER_SIGNATURE_WALLET_COIN_DEPOSIT` made by the customer with the coin's private key.
+ :status 200:
+ The operation succeeded, the mint confirms that no double-spending took place.
+ :status 401 Unauthorized:
+ One of the signatures is invalid.
+ :status 403:
+ The deposit operation has failed because the coin has insufficient
+ residual value; the request should not be repeated again with this coin.
+ In this case, the response is a `DepositDoubleSpendError`_.
+ :status 404:
+ Either the denomination key is not recognized (expired or invalid) or
+ the wire type is not recognized.
- The deposit operation succeeds if the coin is valid for making a deposit and has enough residual value that has not already been deposited or melted.
+ **Details:**
- **Success response: OK**
+ .. _DepositRequest:
+ .. code-block:: tsref
- :status 200: the operation succeeded, the mint confirms that no double-spending took place.
- :resheader Content-Type: application/json
- :>json string status: the string constant `DEPOSIT_OK`
- :>json base32 sig: the EdDSA signature_ (binary-only) with purpose `TALER_SIGNATURE_MINT_CONFIRM_DEPOSIT` using a current signing key of the mint affirming the successful deposit and that the mint will transfer the funds after the refund deadline, or as soon as possible if the refund deadline is zero.
- :>json base32 pub: public EdDSA key of the mint that was used to generate the signature. Should match one of the mint's signing keys from /keys. It is given explicitly as the client might otherwise be confused by clock skew as to which signing key was used.
+ interface DepositRequest {
+ // Amount to be deposited, can be a fraction of the
+ // coin's total value.
+ f: Amount;
- **Failure response: Double spending**
+ // The merchant's account details. This must be a JSON object whose format
+ // must correspond to one of the supported wire transfer formats of the mint.
+ // See `wireformats`_.
+ wire: WireFormat;
- :status 403: the deposit operation has failed because the coin has insufficient residual value; the request should not be repeated again with this coin.
- :resheader Content-Type: application/json
- :>json string error: the string "insufficient funds"
- :>json object history: a JSON array with the transaction history for the coin
+ // SHA-512 hash of the merchant's payment details from `wire`. Although
+ // strictly speaking redundant, this helps detect inconsistencies.
+ H_wire: HashCode;
- The transaction history contains entries of the following format:
+ // SHA-512 hash of the contact of the merchant with the customer. Further
+ // details are never disclosed to the mint.
+ H_contract: HashCode;
- :>jsonarr string type: either "deposit" or "melt"
- :>jsonarr object amount: the total amount_ of the coin's value absorbed by this transaction
- :>jsonarr string details: base32_ binary encoding of the transaction data as a `TALER_DepositRequestPS` or `TALER_RefreshMeltCoinAffirmationPS` struct described in :ref:`Signatures`. Its `purpose` should match our `type`, `amount_with_fee`, should match our `amount`, and its `size` should be consistent.
- :>jsonarr object signature: the EdDSA signature_ (binary-only) made with purpose `TALER_SIGNATURE_WALLET_COIN_DEPOSIT` or `TALER_SIGNATURE_WALLET_COIN_MELT` over the transaction's details.
+ // coin's public key, both ECDHE and EdDSA.
+ coin_pub: CoinPublicKey;
- **Error Response: Invalid signature**:
+ // denomination RSA key with which the coin is signed
+ denom_pub: RsaPublicKey;
- :status 401 Unauthorized: One of the signatures is invalid.
- :resheader Content-Type: application/json
- :>json string error: the value is "invalid signature"
- :>json string paramter: the value is "coin_sig" or "ub_sig", depending on which signature was deemed invalid by the mint
+ // mint's unblinded RSA `signature`_ of the coin
+ ub_sig: RsaSignature;
- **Failure response: Unknown denomination key**
+ // timestamp when the contract was finalized, must match approximately the
+ // current time of the mint
+ timestamp: Timestamp;
- :status 404: the mint does not recognize the denomination key as belonging to the mint, or it has expired
- :resheader Content-Type: application/json
- :>json string error: the value is "unknown entity referenced"
- :>json string paramter: the value is "denom_pub"
+ // indicative time by which the mint undertakes to transfer the funds to
+ // the merchant, in case of successful payment.
+ edate: Timestamp;
- **Failure response: Unsupported or invalid wire format**
+ // 64-bit transaction id for the transaction between merchant and customer
+ transaction_id: number;
- :status 404: the mint does not recognize the wire format (unknown type or format check fails)
- :resheader Content-Type: application/json
- :>json string error: the value is "unknown entity referenced"
- :>json string paramter: the value is "wire"
+ // EdDSA public key of the merchant, so that the client can identify the
+ // merchant for refund requests.
+ merchant_pub: EddsaPublicKey;
+ // date until which the merchant can issue a refund to the customer via the
+ // mint, possibly zero if refunds are not allowed.
+ refund_deadline: Timestamp;
+ // The EdDSA signature (binary-only) made with purpose
+ // `TALER_SIGNATURE_WALLET_COIN_DEPOSIT` made by the customer with the coin's
+ // private key.
+ coin_sig: EddsaSignature;
+ }
+
+ The deposit operation succeeds if the coin is valid for making a deposit and
+ has enough residual value that has not already been deposited or melted.
+
+
+ .. code-block:: tsref
+
+ interface DepositSuccess {
+ // The string constant "DEPOSIT_OK"
+ status: string;
+
+ // the EdDSA :ref:`signature` (binary-only) with purpose
+ // `TALER_SIGNATURE_MINT_CONFIRM_DEPOSIT` using a current signing key of the
+ // mint affirming the successful deposit and that the mint will transfer the
+ // funds after the refund deadline, or as soon as possible if the refund
+ // deadline is zero.
+ sig: EddsaSignature;
+
+ // public EdDSA key of the mint that was used to generate the signature.
+ // Should match one of the mint's signing keys from /keys. It is given
+ // explicitly as the client might otherwise be confused by clock skew as to
+ // which signing key was used.
+ pub: EddsaPublicKey;
+ }
+
+ .. _DepositDoubleSpendError:
+ .. code-block:: tsref
+
+ interface DepositDoubleSpendError {
+ // The string constant "insufficient funds"
+ string error;
+
+ // Transaction history for the coin that is
+ // being double-spended
+ history: CoinSpendHistoryItem[];
+ }
+
+ .. code-block:: tsref
+
+ interface CoinSpendHistoryItem {
+ // Either "deposit" or "melt"
+ type: string;
+
+ // The total amount of the coin's value absorbed by this transaction
+ amount: Amount;
+
+ // base32 binary encoding of the transaction data as a
+ // `TALER_DepositRequestPS` or `TALER_RefreshMeltCoinAffirmationPS`
+ // struct described in :ref:`Signatures`. Its `purpose` should match our
+ // `type`, `amount_with_fee`, should match our `amount`, and its `size`
+ // should be consistent.
+ details: string;
+
+ // the EdDSA :ref:`signature` (binary-only) made with purpose
+ // `TALER_SIGNATURE_WALLET_COIN_DEPOSIT` or
+ // `TALER_SIGNATURE_WALLET_COIN_MELT` over the transaction's details.
+ signature: EddsaSignature;
+ }
------------------
Refreshing
------------------
-Refreshing creates `n` new coins from `m` old coins, where the sum of denominations of the new coins must be smaller than the sum of the old coins' denominations plus melting (refresh) and withdrawal fees charged by the mint. The refreshing API can be used by wallets to melt partially spent coins, making transactions with the freshly minted coins unlinkabe to previous transactions by anyone except the wallet itself.
+Refreshing creates `n` new coins from `m` old coins, where the sum of
+denominations of the new coins must be smaller than the sum of the old coins'
+denominations plus melting (refresh) and withdrawal fees charged by the mint.
+The refreshing API can be used by wallets to melt partially spent coins, making
+transactions with the freshly minted coins unlinkabe to previous transactions
+by anyone except the wallet itself.
-However, the new coins are linkable from the private keys of all old coins using the /refresh/link request. While /refresh/link must be implemented by the mint to achieve taxability, wallets do not really ever need that part of the API during normal operation.
+However, the new coins are linkable from the private keys of all old coins
+using the /refresh/link request. While /refresh/link must be implemented by
+the mint to achieve taxability, wallets do not really ever need that part of
+the API during normal operation.
.. _refresh:
.. http:post:: /refresh/melt
- "Melts" coins. Invalidates the coins and prepares for minting of fresh coins. Taler uses a global parameter `kappa` for the cut-and-choose component of the protocol, for which this request is the commitment. Thus, various arguments are given `kappa`-times in this step. At present `kappa` is always 3.
+ "Melts" coins. Invalidates the coins and prepares for minting of fresh
+ coins. Taler uses a global parameter `kappa` for the cut-and-choose
+ component of the protocol, for which this request is the commitment. Thus,
+ various arguments are given `kappa`-times in this step. At present `kappa`
+ is always 3.
+
+
+ :status 401 Unauthorized:
+ One of the signatures is invalid.
+ :status 200 OK:
+ The request was succesful. The response body is `MeltResponse`_ in this case.
+ :status 403 Forbidden:
+ The operation is not allowed as at least one of the coins has insufficient funds. The response
+ is `MeltForbiddenResponse`_ in this case.
+ :status 404:
+ the mint does not recognize the denomination key as belonging to the mint,
+ or it has expired
+
+ **Details:**
+
+
+ .. code-block:: tsref
+
+ interface MeltRequest {
+ // Array of `n` new denominations to order.
+ new_denoms: RsaPublicKey[];
+
+ // List of `m` coins to melt.
+ melt_coins: MeltCoin[];
+
+ // For each of the `n` new coins, `kappa` transfer keys.
+ // coin_evs[j][k] is the k-th blank (of kappa) for the k-th new coin (of n).
+ coin_evs: CoinBlank[][]
+
+ // For each of the `m` old coins, `kappa` transfer public keys (2D-array
+ // of ephemeral ECDHE keys)
+ transfer_pubs: EddsaPublicKey[][];
+
+ // For each of the `m` old coins, `kappa` link encryptions with an
+ // ECDHE-encrypted SHA-512 hash code. The ECDHE encryption is done using
+ // the private key of the respective old coin and the corresponding transfer
+ // public key. Note that the SHA-512 hash code must be the same across all
+ // coins, but different across all of the `kappa` dimensions. Given the
+ // private key of a single old coin, it is thus possible to decrypt the
+ // respective `secret_encs` and obtain the SHA-512 hash that was used to
+ // symetrically encrypt the `link_encs` of all of the new coins.
+ secret_encs: string[][];
+
+ // For each of the `n` new coins, `kappa` symmetrically encrypted tuples
+ // consisting of the EdDSA/ECDHE-private key of the new coin and the
+ // corresponding blinding factor, encrypted using the corresponding SHA-512
+ // hash that is encrypted in `secret_encs`.
+ link_encs: string[][];
+ }
+
+ For details about the HKDF used to derive the symmetric encryption keys from
+ ECDHE and the symmetric encryption (AES+Twofish) used, please refer to the
+ implementation in `libtalerutil`. The `melt_coins` field is a list of JSON
+ objects with the following fields:
+
- The request body must contain a JSON object with the following fields:
+ .. _tsref-type-MeltCoin:
+ .. code-block:: tsref
- :<json array new_denoms: List of `n` new denominations to order. Each entry must be a base32_ encoded RSA public key corresponding to the coin to be minted.
- :<json array melt_coins: List of `m` coins to melt.
- :<json array coin_evs: For each of the `n` new coins, `kappa` coin blanks (2D array)
- :<json array transfer_pubs: For each of the `m` old coins, `kappa` transfer public keys (2D-array of ephemeral ECDHE keys)
- :<json array secret_encs: For each of the `m` old coins, `kappa` link encryptions with an ECDHE-encrypted SHA-512 hash code. The ECDHE encryption is done using the private key of the respective old coin and the corresponding transfer public key. Note that the SHA-512 hash code must be the same across all coins, but different across all of the `kappa` dimensions. Given the private key of a single old coin, it is thus possible to decrypt the respective `secret_encs` and obtain the SHA-512 hash that was used to symetrically encrypt the `link_encs` of all of the new coins.
- :<json array link_encs: For each of the `n` new coins, `kappa` symmetricly encrypted tuples consisting of the EdDSA/ECDHE-private key of the new coin and the corresponding blinding factor, encrypted using the corresponding SHA-512 hash that is encrypted in `secret_encs`.
+ interface MeltCoin {
+ // Coin public key, uniquely identifies the coin
+ coin_pub: string;
- For details about the HKDF used to derive the symmetric encryption keys from ECDHE and the symmetric encryption (AES+Twofish) used, please refer to the implementation in `libtalerutil`. The `melt_coins` field is a list of JSON objects with the following fields:
+ // The denomination public key allows the mint to determine total coin value.
+ denom_pub: RsaPublicKey;
- :<jsonarr string coin_pub: Coin public key (uniquely identifies the coin)
- :<jsonarr string denom_pub: Denomination public key (allows the mint to determine total coin value)
- :<jsonarr string denom_sig: Signature_ over the coin public key by the denomination
- :<jsonarr string confirm_sig: Signature_ by the coin over the session public key
- key
- :<jsonarr object value_with_fee: Amount_ of the value of the coin that should be melted as part of this refresh operation, including melting fee.
+ // Signature over the coin public key by the denomination.
+ denom_sig: RsaSignature;
- Errors such as failing to do proper arithmetic when it comes to calculating the total of the coin values and fees are simply reported as bad requests. This includes issues such as melting the same coin twice in the same session, which is simply not allowed. However, theoretically it is possible to melt a coin twice, as long as the `value_with_fee` of the two melting operations is not larger than the total remaining value of the coin before the melting operations. Nevertheless, this is not really useful.
+ // Signature by the coin over the session public key
+ confirm_sig: EddsaSignature;
- **Success Response: OK**
+ // Amount of the value of the coin that should be melted as part of
+ // this refresh operation, including melting fee.
+ value_with_fee: Amount;
- :status 200 OK: The request was succesful. The response body contains a JSON object with the following fields:
- :resheader Content-Type: application/json
- :>json int noreveal_index: Which of the `kappa` indices does the client not have to reveal.
- :>json base32 mint_sig: binary-only Signature_ for purpose `TALER_SIGNATURE_MINT_CONFIRM_MELT` whereby the mint affirms the successful melt and confirming the `noreveal_index`
- :>json base32 mint_pub: public EdDSA key of the mint that was used to generate the signature. Should match one of the mint's signing keys from /keys. Again given explicitly as the client might otherwise be confused by clock skew as to which signing key was used.
+ Errors such as failing to do proper arithmetic when it comes to calculating
+ the total of the coin values and fees are simply reported as bad requests.
+ This includes issues such as melting the same coin twice in the same session,
+ which is simply not allowed. However, theoretically it is possible to melt a
+ coin twice, as long as the `value_with_fee` of the two melting operations is
+ not larger than the total remaining value of the coin before the melting
+ operations. Nevertheless, this is not really useful.
- **Error Response: Invalid signature**:
- :status 401 Unauthorized: One of the signatures is invalid.
- :resheader Content-Type: application/json
- :>json string error: the value is "invalid signature"
- :>json string paramter: the value is "confirm_sig" or "denom_sig", depending on which signature was deemed invalid by the mint
+ .. _tsref-type-MeltResponse:
+ .. _MeltResponse:
+ .. code-block:: tsref
- **Error Response: Precondition failed**:
+ interface MeltResponse {
+ // Which of the `kappa` indices does the client not have to reveal.
+ noreveal_index: number;
+
+ // binary-only Signature_ for purpose `TALER_SIGNATURE_MINT_CONFIRM_MELT`
+ // whereby the mint affirms the successful melt and confirming the
+ // `noreveal_index`
+ mint_sig: EddsaSignature;
+
+ // public EdDSA key of the mint that was used to generate the signature.
+ // Should match one of the mint's signing keys from /keys. Again given
+ // explicitly as the client might otherwise be confused by clock skew as to
+ // which signing key was used.
+ mint_pub: EddsaPublicKey;
+ }
- :status 403 Forbidden: The operation is not allowed as at least one of the coins has insufficient funds.
- :resheader Content-Type: application/json
- :>json string error: the value is "insufficient funds"
- :>json base32 coin_pub: public key of a melted coin that had insufficient funds
- :>json amount original_value: original total value of the coin
- :>json amount residual_value: remaining value of the coin
- :>json amount requested_value: amount of the coin's value that was to be melted
- :>json array history: the transaction list of the respective coin that failed to have sufficient funds left. The format is the same as for insufficient fund reports during /deposit. Note that only the transaction history for one bogus coin is given, even if multiple coins would have failed the check.
- **Failure response: Unknown denomination key**
+ .. _tsref-type-MeltForbiddenResponse:
+ .. _MeltForbiddenResponse:
+ .. code-block:: tsref
+
+ interface MeltForbiddenResponse {
+ // Always "insufficient funds"
+ error: string;
+
+ // public key of a melted coin that had insufficient funds
+ coin_pub: EddsaPublicKey;
+
+ // original total value of the coin
+ original_value: Amount;
+
+ // remaining value of the coin
+ residual_value: Amount;
+
+ // amount of the coin's value that was to be melted
+ requested_value: Amount;
+
+ // The transaction list of the respective coin that failed to have sufficient funds left.
+ // Note that only the transaction history for one bogus coin is given,
+ // even if multiple coins would have failed the check.
+ history: CoinSpendHistoryItem[];
+ }
- :status 404: the mint does not recognize the denomination key as belonging to the mint, or it has expired
- :resheader Content-Type: application/json
- :>json string error: the value is "unknown entity referenced"
- :>json string paramter: the value is "denom_pub"
.. http:post:: /refresh/reveal
- Reveal previously commited values to the mint, except for the values corresponding to the `noreveal_index` returned by the /mint/melt step. Request body contains a JSON object with the following fields:
+ Reveal previously commited values to the mint, except for the values
+ corresponding to the `noreveal_index` returned by the /mint/melt step.
+ Request body contains a JSON object with the following fields:
+
+
+ :status 200 OK:
+ The transfer private keys matched the commitment and the original request was well-formed.
+ The response body is a `RevealResponse`_
+ :status 409 Conflict:
+ There is a problem between the original commitment and the revealed private
+ keys. The returned information is proof of the missmatch, and therefore
+ rather verbose, as it includes most of the original /refresh/melt request,
+ but of course expected to be primarily used for diagnostics.
+ The response body is a `RevealConflictResponse`_.
+
+
+
+ .. code-block:: tsref
+
+ interface RevealRequest {
+ // Hash over most of the arguments to the /mint/melt step. Used to
+ // identify the corresponding melt operation. For details on which elements
+ // must be hashed in which order, please consult the source code of the mint
+ // reference implementation.
+ session_hash: HashCode;
+
+ // 2D array of `kappa - 1` times number of melted coins ECDHE transfer
+ // private keys. The mint will use those to decrypt the transfer secrets,
+ // check that they match across all coins, and then decrypt the private keys
+ // of the coins to be generated and check all this against the commitments.
+ transfer_privs: EddsaPrivateKey[][];
+ }
+
+
+ .. _RevealResponse:
+ .. code-block:: tsref
+
+ interface RevealResponse {
+ // List of the mint's blinded RSA signatures on the new coins. Each
+ // element in the array is another JSON object which contains the signature
+ // in the "ev_sig" field.
+ ev_sigs: BlindedRsaSignature[];
+ }
+
+
+ .. _RevealConflictResponse:
+ .. code-block:: tsref
+
+ interface RevealConflictResponse {
+ // Constant "commitment violation"
+ error: string;
+
+ // offset of in the array of `kappa` commitments where the error was detected
+ offset: number;
+
+ // index of in the with respect to the melted coin where the error was detected
+ index: number;
+
+ // name of the entity that failed the check (i.e. "transfer key")
+ object: string;
+
+ // Information about each melted coin
+ oldcoin_infos: OldCoinInfo[];
+
+ // array with RSA denomination public keys of the coins the original
+ // refresh request asked to be minted
+ newcoins_infos: RsaPublicKey[];
+
+ // 2D array with `kappa` entries in the first dimension and the same
+ // length as the `oldcoin_infos` in the 2nd dimension containing as elements
+ // objects with the linkage information
+ link_infos: LinkInfo[][];
+
+ // 2D array with `kappa` entries in the first dimension and the same
+ // length as `newcoin_infos` in the 2nd dimension containing as elements
+ // objects with the commitment information
+ commit_infos: CommitInfo[][];
+ }
- :<json base32 session_hash: Hash over most of the arguments to the /mint/melt step. Used to identify the corresponding melt operation. For details on which elements must be hashed in which order, please consult the mint code itself.
- :<json array transfer_privs: 2D array of `kappa - 1` times number of melted coins ECDHE transfer private keys. The mint will use those to decrypt the transfer secrets, check that they match across all coins, and then decrypt the private keys of the coins to be generated and check all this against the commitments.
- **Success Response: OK**
+ .. _tsref-type-LinkInfo:
+ .. code-block:: tsref
- :status 200 OK: The transfer private keys matched the commitment and the original request was well-formed. The mint responds with a JSON of the following type:
- :resheader Content-Type: application/json
- :>json array ev_sigs: List of the mint's blinded RSA signatures on the new coins. Each element in the array is another JSON object which contains the signature in the "ev_sig" field.
+ interface LinkInfo {
+ // the transfer ECDHE public key
+ transfer_pub: EddsaPublicKey;
- **Failure Response: Conflict**
+ // the encrypted shared secret
+ shared_secret_enc: string;
+ }
- :status 409 Conflict: There is a problem between the original commitment and the revealed private keys. The returned information is proof of the missmatch, and therefore rather verbose, as it includes most of the original /refresh/melt request, but of course expected to be primarily used for diagnostics.
- :resheader Content-Type: application/json
- :>json string error: the value is "commitment violation"
- :>json int offset: offset of in the array of `kappa` commitments where the error was detected
- :>json int index: index of in the with respect to the melted coin where the error was detected
- :>json string object: name of the entity that failed the check (i.e. "transfer key")
- :>json array oldcoin_infos: array with information for each melted coin
- :>json array newcoin_infos: array with RSA denomination public keys of the coins the original refresh request asked to be minted
- :>json array link_infos: 2D array with `kappa` entries in the first dimension and the same length as the `oldcoin_infos` in the 2nd dimension containing as elements objects with the linkage information
- :>json array commit_infos: 2D array with `kappa` entries in the first dimension and the same length as `newcoin_infos` in the 2nd dimension containing as elements objects with the commitment information
+ .. _tsref-type-CommitInfo:
+ .. code-block:: tsref
- The linkage information from `link_infos` consists of:
+ interface CommitInfo {
+ coin_ev: BlindedRsaSignature;
- :>jsonarr base32 transfer_pub: the transfer ECDHE public key
- :>jsonarr base32 shared_secret_enc: the encrypted shared secret
+ // the encrypted private key of the coin
+ coin_priv_env: string;
- The commit information from `commit_infos` consists of:
+ // the encrypted blinding key
+ blinding_key_enc: string;
+ }
- :>jsonarr base32 coin_ev: the coin envelope (information to sign blindly)
- :>jsonarr base32 coin_priv_enc: the encrypted private key of the coin
- :>jsonarr base32 blinding_key_enc: the encrypted blinding key
.. http:get:: /refresh/link
Link the old public key of a melted coin to the coin(s) that were minted during the refresh operation.
+ **Request:**
+
:query coin_pub: melted coin's public key
- **Success Response**
+ **Response:**
+
+ :status 200 OK:
+ All commitments were revealed successfully. The mint returns an array,
+ typically consisting of only one element, in which each each element contains
+ information about a melting session that the coin was used in.
+ :status 404 Not Found:
+ The mint has no linkage data for the given public key, as the coin has not
+ yet been involved in a refresh operation.
- :status 200 OK: All commitments were revealed successfully. The mint returns an array, typically consisting of only one element, in which each each element contains information about a melting session that the coin was used in.
+ **Details:**
- :>jsonarr base32 transfer_pub: transfer ECDHE public key corresponding to the `coin_pub`, used to decrypt the `secret_enc` in combination with the private key of `coin_pub`.
- :>jsonarr base32 secret_enc: ECDHE-encrypted link secret that, once decrypted, can be used to decrypt/unblind the `new_coins`.
- :>jsonarr array new_coins: array with (encrypted/blinded) information for each of the coins minted in the refresh operation.
+ .. _tsref-type-LinkResponse:
+ .. code-block:: tsref
+
+ interface LinkResponse {
+ // transfer ECDHE public key corresponding to the `coin_pub`, used to
+ // decrypt the `secret_enc` in combination with the private key of
+ // `coin_pub`.
+ transfer_pub: EcdhePublicKey;
+
+ // ECDHE-encrypted link secret that, once decrypted, can be used to
+ // decrypt/unblind the `new_coins`.
+ secret_enc: Base32;
+
+ // array with (encrypted/blinded) information for each of the coins
+ // minted in the refresh operation.
+ new_coins: NewCoinInfo[];
+ }
- The `new_coins` array contains the following fields for each element:
+ .. _tsref-type-NewCoinInfo:
+ .. code-block:: tsref
+
+ interface NewCoinInfo {
+ // Encrypted private key and blinding factor information of the fresh coin
+ link_enc: Base32;
- :>jsonarr base32 link_enc: Encrypted private key and blinding factor information of the fresh coin
- :>jsonarr base32 denom_pub: RSA public key of the minted coin.
- :>jsonarr base32 ev_sig: Mint's blinded signature over the minted coin.
+ // RSA public key of the minted coin.
+ denom_pub: RsaPublicKey;
- **Error Response: Unknown key**:
+ // Mint's blinded signature over the minted coin.
+ ev_sig: BlindedRsaSignature;
+ }
- :status 404 Not Found: The mint has no linkage data for the given public key, as the coin has not yet been involved in a refresh operation.
- :resheader Content-Type: application/json
- :>json string error: "unknown entity referenced"
- :>json string parameter: will be "coin_pub"
@@ -530,80 +938,140 @@ typically also view the balance.)
Provides deposits associated with a given wire transfer.
+ **Request:**
+
:query wtid: wire transfer identifier identifying the wire transfer (a base32-encoded value)
- **Success Response: OK**
+ **Response:**
- :status 200 OK: The wire transfer is known to the mint, details about it follow in the body.
- :resheader Content-Type: application/json
- :>json object total: Total amount_ transferred.
- :>json base32 H_wire: hash of the wire details (identical for all deposits)
- :>json base32 merchant_pub: public key of the merchant (identical for all deposits)
- :>json object deposits: JSON array with **deposit details**.
+ :status 200 OK:
+ The wire transfer is known to the mint, details about it follow in the body.
+ The body of the response is a `WireDepositsResponse`_.
+ :status 404 Not Found:
+ The wire transfer identifier is unknown to the mint.
- Objects in the `deposits` array have the following format:
+ .. _WireDepositsResponse:
+ .. code-block:: tsref
- :>jsonarr object deposit_value: the total amount_ the original deposit was worth
- :>jsonarr object deposit_fee: applicable fees for the deposit
- :>jsonarr base32 H_contract: SHA-512 hash of the contact of the merchant with the customer.
- :>jsonarr int transaction_id: 64-bit transaction id for the transaction between merchant and customer
- :>jsonarr base32 coin_pub: coin's public key, both ECDHE and EdDSA.
+ interface WireDepositsResponse {
+ // Total amount transferred
+ total: Amount;
- .. note::
+ // hash of the wire details (identical for all deposits)
+ H_wire: HashCode;
- We might want to add a signature of the mint over the response in the future. That way, a merchant has proof should a mint ever try to change the story here. (#4135)
+ // public key of the merchant (identical for all deposits)
+ merchant_pub: EddsaPublicKey;
+
+ deposits: DepositDetail[];
+ }
+
+
+ .. _tsref-type-DepositDetail:
+ .. code-block:: tsref
+ interface DepositDetail {
+ // The total amount the original deposit was worth.
+ deposit_value: Amount;
- **Error Response: Unknown wire transfer identifier**
+ // applicable fees for the deposit
+ deposit_fee: Amount;
- :status 404 Not Found: The wire transfer identifier is unknown to the mint.
- :resheader Content-Type: application/json
- :>json string error: the value is always "Wire transfer identifier not found"
- :>json string parameter: the value is always "wtid"
+ // SHA-512 hash of the contact of the merchant with the customer.
+ H_contract: HashCode;
+
+ // 64-bit transaction id for the transaction between merchant and
+ // customer
+ transaction_id: number;
+
+ // coin's public key, both ECDHE and EdDSA.
+ coin_pub: CoinPublicKey;
+ }
+ .. note::
+
+ We might want to add a signature of the mint over the response in the future. That way, a merchant has proof should a mint ever try to change the story here. (#4135)
.. http:post:: /deposit/wtid
Provide the wire transfer identifier associated with an (existing) deposit operation.
- :reqheader Content-Type: application/json
- :<json base32 H_wire: SHA-512 hash of the merchant's payment details.
- :<json base32 H_contract: SHA-512 hash of the contact of the merchant with the customer.
- :<json base32 coin_pub: coin's public key, both ECDHE and EdDSA.
- :<json int transaction_id: 64-bit transaction id for the transaction between merchant and customer
- :<json base32 merchant_pub: the EdDSA public key of the merchant, so that the client can identify the merchant for refund requests.
- :<json base32 merchant_sig: the EdDSA signature of the merchant made with purpose `TALER_SIGNATURE_MERCHANT_DEPOSIT_WTID` , affirming that it is really the merchant who requires obtaining the wire transfer identifier.
+ **Request:** The request body most be a `WtidRequest`_ JSON object.
- **Success Response: OK**
+ **Response:**
- :status 200 OK: The deposit has been executed by the mint and we have a wire transfer identifier.
- :resheader Content-Type: application/json
- :>json base32 wtid: wire transfer identifier of the deposit.
- :>json date execution_time: when was the wire transfer given to the bank.
- :>json base32 mint_sig: binary-only Signature_ for purpose `TALER_SIGNATURE_MINT_CONFIRM_WIRE` whereby the mint affirms the successful wire transfer.
- :>json base32 mint_pub: public EdDSA key of the mint that was used to generate the signature. Should match one of the mint's signing keys from /keys. Again given explicitly as the client might otherwise be confused by clock skew as to which signing key was used.
+ :status 200 OK:
+ The deposit has been executed by the mint and we have a wire transfer identifier.
+ The response body is a `WtidResponse`_ object.
+ :status 202 Accepted:
+ The deposit request has been accepted for processing, but was not yet
+ executed. Hence the mint does not yet have a wire transfer identifier. The
+ merchant should come back later and ask again.
+ The response body is a `WtidAcceptedResponse`_.
+ :status 401 Unauthorized: The signature is invalid.
+ :status 404 Not Found: The deposit operation is unknown to the mint
- **Error Response: Wire transfer not yet executed**
+ **Details:**
- :status 202 Accepted: The deposit request has been accepted for processing, but was not yet executed. Hence the mint does not yet have a wire transfer identifier. The merchant should come back later and ask again.
- :resheader Content-Type: application/json
- :>json date execution_time: time by which the mint currently thinks the deposit will be executed.
+ .. _tsref-type-WtidRequest:
+ .. _WtidRequest:
+ .. code-block:: tsref
- **Error Response: Invalid signature**:
+ interface WtidRequest {
+ // SHA-512 hash of the merchant's payment details.
+ H_wire: HashCode;
- :status 401 Unauthorized: The signature is invalid.
- :resheader Content-Type: application/json
- :>json string error: the value is "invalid signature"
- :>json string paramter: the value is "merchant_sig"
+ // SHA-512 hash of the contact of the merchant with the customer.
+ H_contract: HashCode;
- **Error Response: Unknown wire transfer identifier**
+ // coin's public key, both ECDHE and EdDSA.
+ coin_pub: CoinPublicKey;
- :status 404 Not Found: The deposit operation is unknown to the mint
- :resheader Content-Type: application/json
- :>json string error: the value is always "Deposit unknown"
+ // 64-bit transaction id for the transaction between merchant and customer
+ transaction_id: number;
+ // the EdDSA public key of the merchant, so that the client can identify
+ // the merchant for refund requests.
+ merchant_pub: EddsaPublicKey;
+
+ // the EdDSA signature of the merchant made with purpose
+ // `TALER_SIGNATURE_MERCHANT_DEPOSIT_WTID` , affirming that it is really the
+ // merchant who requires obtaining the wire transfer identifier.
+ merchant_sig: EddsaSignature;
+ }
+ .. _tsref-type-WtidResponse:
+ .. _WtidResponse:
+ .. code-block:: tsref
+
+ interface WtidResponse {
+ // wire transfer identifier of the deposit.
+ wtid: Base32;
+
+ // when was the wire transfer given to the bank.
+ execution_time: Timestamp;
+
+ // binary-only Signature_ for purpose `TALER_SIGNATURE_MINT_CONFIRM_WIRE`
+ // whereby the mint affirms the successful wire transfer.
+ mint_sig: EddsaSignature;
+
+ // public EdDSA key of the mint that was used to generate the signature.
+ // Should match one of the mint's signing keys from /keys. Again given
+ // explicitly as the client might otherwise be confused by clock skew as to
+ // which signing key was used.
+ mint_pub: EddsaPublicKey;
+ }
+
+ .. _tsref-type-WtidAcceptedResponse:
+ .. _WtidAcceptedResponse:
+ .. code-block:: tsref
+
+ interface WtidAcceptedResponse {
+ // time by which the mint currently thinks the deposit will be executed.
+ execution_time: Timestamp;
+ }
+
-------
@@ -612,17 +1080,28 @@ Refunds
.. note::
- Refunds are currently not implemented (#3641), this documentation is thus rather preliminary and subject to change.
+ Refunds are currently not implemented (#3641), this documentation is thus
+ rather preliminary and subject to change.
.. _refund:
.. http:POST:: /refund
- Undo deposit of the given coin, restoring its value. The request
- should contain a JSON object with the following fields:
+ Undo deposit of the given coin, restoring its value.
- :>json obj retract_perm: If the coin was claimed as a refund, this field should contain the retract permission obtained from the merchant, otherwise it should not be present. For details about the object type, see :ref:`Merchant API:retract<retract>`.
- :>json string retract_value: Value returned due to the retraction.
+ **Request:**
+ .. code-block:: tsref
+
+ interface RefundRequest {
+ // If the coin was claimed as a refund, this field should contain the
+ // retract permission obtained from the merchant, otherwise it should not be
+ // present.
+ // TODO: document what the type
+ retract_perm: any;
+
+ // Value returned due to the retraction.
+ retract_value: string;
+ }
------------------------------
@@ -631,7 +1110,9 @@ Administrative API: Key update
.. note::
- This is not yet implemented (no bug number yet, as we are not sure we will implement this; for now, adding new files to the directory and sending a signal to the mint process seems to work fine).
+ This is not yet implemented (no bug number yet, as we are not sure we will
+ implement this; for now, adding new files to the directory and sending a
+ signal to the mint process seems to work fine).
New denomination and signing keys can be uploaded to the mint via the
HTTP interface. It is, of course, only possible to upload keys signed
@@ -643,15 +1124,34 @@ interception.
Upload a new denomination key.
- :>json object denom_info: Public part of the denomination key
- :>json base32 denom_priv: Private RSA key
+ **Request:**
+
+ .. code-block:: tsref
+
+ {
+ // Public part of the denomination key
+ denom_info: any:
+
+ // Private RSA key
+ denom_priv: RsaPrivateKey;
+ }
+
.. http:POST:: /admin/add/sign_key
Upload a new signing key.
- :>json object sign_info: Public part of the signing key
- :>json base32 sign_priv: Private EdDSA key
+ **Request:**
+
+ .. code-block:: tsref
+
+ {
+ // Public part of the signing key
+ sign_info: any;
+
+ // Private EdDSA key
+ sign_priv: EddsaPrivateKey;
+ }
.. _add-incoming:
@@ -663,63 +1163,84 @@ Administrative API: Bank transactions
Notify mint of an incoming transaction to fill a reserve.
- :>json base32 reserve_pub: Reserve public key
- :>json object amount: Amount transferred to the reserve
- :>json date execution_date: When was the transaction executed
- :>json object wire: Wire details
+ **Request:**
- **Success response**
+ .. code-block:: tsref
- :status 200: the operation succeeded
+ {
+ // Reserve public key
+ reserve_pub: EddsaPublicKey;
- The mint responds with a JSON object containing the following fields:
+ // Amount transferred to the reserve
+ amount: Amount;
- :>json string status: The string constant `NEW` or `DUP` to indicate
- whether the transaction was truly added to the DB
- or whether it already existed in the DB
+ // When was the transaction executed
+ execution_date: Timestamp;
+
+ // Wire details
+ wire: any;
+ }
- **Failure response**
+ **Response:**
- :status 403: the client is not permitted to add incoming transactions. The request may be disallowed by the configuration in general or restricted to certain IP addresses (i.e. loopback-only).
+ :status 200:
+ The operation succeeded. The body is an `AddIncomingResponse`_ object.
+ :status 403:
+ the client is not permitted to add incoming transactions. The request may
+ be disallowed by the configuration in general or restricted to certain IP
+ addresses (i.e. loopback-only).
- The mint responds with a JSON object containing the following fields:
- :>json string error: the error message, such as `permission denied`
- :>json string hint: hint as to why permission was denied
+ .. _AddIncomingResponse:
+ .. code-block:: tsref
+ interface AddIncomingResponse {
+ // The string constant `NEW` or `DUP` to indicate whether the transaction
+ // was truly added to the DB or whether it already existed in the DB
+ status: string;
+ }
.. http:POST:: /admin/add/outgoing
- Notify mint about the completion of an outgoing transaction satisfying a /deposit request. In the future, this will allow merchants to obtain details about the /deposit requests they send to the mint.
+ Notify mint about the completion of an outgoing transaction satisfying a
+ /deposit request. In the future, this will allow merchants to obtain details
+ about the /deposit requests they send to the mint.
.. note::
This is not yet implemented (no bug number yet either).
- :>json base32 coin_pub: Coin public key
- :>json object amount: Amount transferred to the merchant
- :>json string transaction: Transaction identifier in the wire details
- :>json base32 wire: Wire transaction details, as originally specified by the merchant
+ **Request:**
+ .. code-block:: tsref
- **Success response**
+ {
+ coin_pub: CoinPublicKey;
- :status 200: the operation succeeded
+ // Amount transferred to the merchant
+ amount: Amount;
- The mint responds with a JSON object containing the following fields:
+ // Transaction identifier in the wire details
+ transaction: number;
- :>json string status: The string constant `NEW` or `DUP` to indicate
- whether the transaction was truly added to the DB
- or whether it already existed in the DB
+ // Wire transaction details, as originally specified by the merchant
+ wire: any;
+ }
- **Failure response**
+ **Response**
+ :status 200: The request was successful.
:status 403: the client is not permitted to add outgoing transactions
- The mint responds with a JSON object containing the following fields:
+ If the request was successful, the response has the following format:
- :>json string error: the error message (`permission denied`)
- :>json string hint: hint as to why permission was denied
+ .. code-block:: tsref
+
+ {
+ // The string constant `NEW` or `DUP` to indicate whether the transaction
+ // was truly added to the DB or whether it already existed in the DB
+ status: string;
+ }
------------
The Test API
@@ -732,357 +1253,201 @@ binary-compatible with the implementation of the mint.
.. http:POST:: /test/base32
- Test hashing and Crockford base32_ encoding.
-
- :reqheader Content-Type: application/json
- :<json base32 input: some base32_-encoded value
- :status 200: the operation succeeded
- :resheader Content-Type: application/json
- :>json base32 output: the base32_-encoded hash of the input value
-
-.. http:POST:: /test/encrypt
-
- Test symmetric encryption.
+ Test hashing and Crockford :ref:`base32` encoding.
- :reqheader Content-Type: application/json
- :<json base32 input: some base32_-encoded value
- :<json base32 key_hash: some base32_-encoded hash that is used to derive the symmetric key and initialization vector for the encryption using the HKDF with "skey" and "iv" as the salt.
- :status 200: the operation succeeded
- :resheader Content-Type: application/json
- :>json base32 output: the encrypted value
+ **Request:**
-.. http:POST:: /test/hkdf
+ .. code-block:: tsref
- Test Hash Key Deriviation Function.
+ {
+ // some base32-encoded value
+ input: Base32;
+ }
- :reqheader Content-Type: application/json
- :<json base32 input: some base32_-encoded value
- :status 200: the operation succeeded
- :resheader Content-Type: application/json
- :>json base32 output: the HKDF of the input using "salty" as salt
+ **Response:**
-.. http:POST:: /test/ecdhe
+ .. code-block:: tsref
- Test ECDHE.
+ {
+ // the base32_-encoded hash of the input value
+ output: Base32;
+ }
- :reqheader Content-Type: application/json
- :<json base32 ecdhe_pub: ECDHE public key
- :<json base32 ecdhe_priv: ECDHE private key
- :status 200: the operation succeeded
- :resheader Content-Type: application/json
- :>json base32 ecdh_hash: ECDH result from the two keys
+.. http:POST:: /test/encrypt
-.. http:POST:: /test/eddsa
+ Test symmetric encryption.
- Test EdDSA.
+ **Request:**
- :reqheader Content-Type: application/json
- :<json base32 eddsa_pub: EdDSA public key
- :<json base32 eddsa_sig: EdDSA signature using purpose TALER_SIGNATURE_CLIENT_TEST_EDDSA. Note: the signed payload must be empty, we sign just the purpose here.
- :status 200: the signature was valid
- :resheader Content-Type: application/json
- :>json base32 eddsa_pub: Another EdDSA public key
- :>json base32 eddsa_sig: EdDSA signature using purpose TALER_SIGNATURE_MINT_TEST_EDDSA
+ .. code-block:: tsref
-.. http:GET:: /test/rsa/get
+ {
+ // Some `base32`_-encoded value
+ input: Base32;
- Obtain the RSA public key used for signing in /test/rsa/sign.
-
- :status 200: operation was successful
- :resheader Content-Type: application/json
- :>json base32 rsa_pub: The RSA public key the client should use when blinding a value for the /test/rsa/sign API.
+ // some `base32`_-encoded hash that is used to derive the symmetric key and
+ // initialization vector for the encryption using the HKDF with "skey" and
+ // "iv" as the salt.
+ key_hash: Base32;
+ }
-.. http:POST:: /test/rsa/sign
+ **Response:**
- Test RSA blind signatures.
- :reqheader Content-Type: application/json
- :<json base32 blind_ev: Blinded value to sign.
- :status 200: operation was successful
- :resheader Content-Type: application/json
- :>json base32 rsa_blind_sig: Blind RSA signature over the `blind_ev` using the private key corresponding to the RSA public key returned by /test/rsa/get.
+ .. code-block:: tsref
+ {
+ // the encrypted value
+ output: Base32;
+ }
-.. http:POST:: /test/transfer
+.. http:POST:: /test/hkdf
- Test Transfer decryption.
+ Test Hash Key Deriviation Function.
- :reqheader Content-Type: application/json
- :<json base32 secret_enc: Encrypted transfer secret
- :<json base32 trans_priv: Private transfer key
- :<json base32 coin_pub: Public key of a coin
- :status 200: the operation succeeded
- :resheader Content-Type: application/json
- :>json base32 secret: Decrypted transfer secret
+ **Request:**
-===========================
-Binary Blob Specification
-===========================
+ .. code-block:: tsref
- .. note::
+ {
+ // Some `base32`_-encoded value
+ input: Base32;
+ }
- This section largely corresponds to the definitions in taler_signatures.h. You may also want to refer to this code, as it offers additional details on each of the members of the structs.
+ **Response:**
- .. 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.
+ .. code-block:: tsref
-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).
+ {
+ // the HKDF of the input using "salty" as salt
+ output: Base32;
+ }
-------------------------
-Amounts
-------------------------
+.. http:POST:: /test/ecdhe
-Amounts of currency are always expressed in terms of a base value, a fractional value and the denomination of the currency:
+ Test ECDHE.
-.. sourcecode:: c
+ **Request:**
- struct TALER_AmountNBO {
- uint64_t value;
- uint32_t fraction;
- uint8_t currency_code[12];
- };
+ .. code-block:: tsref
+ {
+ ecdhe_pub: EcdhePublicKey;
+ ecdhe_priv: EcdhePrivateKey;
+ }
-------------------------
-Time
-------------------------
+ **Response:**
-In signed messages, time is represented using 64-bit big-endian values, denoting microseconds since the UNIX Epoch. `UINT64_MAX` represents "never" (distant future, eternity).
+ .. code-block:: tsref
-.. sourcecode:: c
+ {
+ // ECDH result from the two keys
+ ecdhe_hash: HashCode;
+ }
- struct GNUNET_TIME_AbsoluteNBO {
- uint64_t timestamp_us;
- };
-------------------------
-Cryptographic primitives
-------------------------
+.. http:POST:: /test/eddsa
-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).
+ Test EdDSA.
-.. sourcecode:: c
+ **Request:**
- struct GNUNET_HashCode {
- uint8_t hash[64];
- };
+ .. code-block:: tsref
- struct TALER_ReservePublicKeyP {
- uint8_t eddsa_pub[32];
- };
+ {
+ eddsa_pub: EddsaPublicKey;
- struct TALER_ReservePrivateKeyP {
- uint8_t eddsa_priv[32];
- };
+ // EdDSA signature using purpose TALER_SIGNATURE_CLIENT_TEST_EDDSA. Note:
+ // the signed payload must be empty, we sign just the purpose here.
+ eddsa_sig: EddsaSignature;
+ }
- struct TALER_ReserveSignatureP {
- uint8_t eddsa_signature[64];
- };
+ **Response:**
- struct TALER_MerchantPublicKeyP {
- uint8_t eddsa_pub[32];
- };
+ :status 200: the signature was valid
+ :status 401 Unauthorized: the signature was invalid
- struct TALER_MerchantPrivateKeyP {
- uint8_t eddsa_priv[32];
- };
+ The mint responds with another valid signature, which gives the
+ client the opportunity to test its signature verification implementation.
- struct TALER_TransferPublicKeyP {
- uint8_t ecdhe_pub[32];
- };
+ .. code-block:: tsref
- struct TALER_TransferPrivateKeyP {
- uint8_t ecdhe_priv[32];
- };
+ {
+ // Another EdDSA public key
+ eddsa_pub: EddsaPublicKey;
- struct TALER_MintPublicKeyP {
- uint8_t eddsa_pub[32];
- };
+ // EdDSA signature using purpose TALER_SIGNATURE_MINT_TEST_EDDSA
+ eddsa_sig: EddsaSignature;
+ }
- struct TALER_MintPrivateKeyP {
- uint8_t eddsa_priv[32];
- };
- struct TALER_MintSignatureP {
- uint8_t eddsa_signature[64];
- };
+.. http:GET:: /test/rsa/get
- struct TALER_MasterPublicKeyP {
- uint8_t eddsa_pub[32];
- };
+ Obtain the RSA public key used for signing in /test/rsa/sign.
- struct TALER_MasterPrivateKeyP {
- uint8_t eddsa_priv[32];
- };
+ **Response:**
- struct TALER_MasterSignatureP {
- uint8_t eddsa_signature[64];
- };
+ .. code-block:: tsref
- union TALER_CoinSpendPublicKeyP {
- uint8_t eddsa_pub[32];
- uint8_t ecdhe_pub[32];
- };
+ {
+ // The RSA public key the client should use when blinding a value for the /test/rsa/sign API.
+ rsa_pub: RsaPublicKey;
+ }
- union TALER_CoinSpendPrivateKeyP {
- uint8_t eddsa_priv[32];
- uint8_t ecdhe_priv[32];
- };
+.. http:POST:: /test/rsa/sign
- struct TALER_CoinSpendSignatureP {
- uint8_t eddsa_signature[64];
- };
+ Test RSA blind signatures.
- struct TALER_TransferSecretP {
- uint8_t key[sizeof (struct GNUNET_HashCode)];
- };
+ **Request:**
- struct TALER_LinkSecretP {
- uint8_t key[sizeof (struct GNUNET_HashCode)];
- };
+ .. code-block:: tsref
- struct TALER_EncryptedLinkSecretP {
- uint8_t enc[sizeof (struct TALER_LinkSecretP)];
- };
+ {
+ // Blinded value to sign.
+ blind_ev: BlindedRsaSignature;
+ }
-.. _Signatures:
+ **Response:**
-------------------------
-Signatures
-------------------------
-Please note that any RSA signature is processed by a function called `GNUNET_CRYPTO_rsa_signature_encode (..)` **before** being sent over the network, so the receiving party must run `GNUNET_CRYPTO_rsa_signature_decode (..)` before verifying it. See their implementation in `src/util/crypto_rsa.c`, in GNUNET's code base. Finally, they are defined in `gnunet/gnunet_crypto_lib.h`.
+ .. code-block:: tsref
-EdDSA signatures are always made on the hash of a block of the same generic format, the `struct SignedData` given below. In our notation, the type of a field can depend on the value of another field. For the following message, the length of the `payload` array must match the value of the `size` field:
+ {
+ // Blind RSA signature over the `blind_ev` using the private key
+ // corresponding to the RSA public key returned by /test/rsa/get.
+ rsa_blind_sig: BlindedRsaSignature;
+ }
-.. sourcecode:: c
+.. http:POST:: /test/transfer
- struct SignedData {
- uint32_t size;
- uint32_t purpose;
- uint8_t payload[size - sizeof (struct SignedData)];
- };
+ Test Transfer decryption.
-The `purpose` field in `struct SignedData` 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. The various `purpose` constants are defined in `taler_signatures.h`. The `size` field prevents padding attacks.
+ **Request:**
-In the subsequent messages, we use the following notation for signed data described in `FIELDS` with the given purpose.
+ .. code-block:: tsref
-.. sourcecode:: c
+ {
+ // Encrypted transfer secret
+ secret_enc: string;
- signed (purpose = SOME_CONSTANT) {
- FIELDS
- } msg;
+ // Private transfer key
+ trans_priv: string;
-The `size` field of the corresponding `struct SignedData` is determined by the size of `FIELDS`.
+ // Coin public ket
+ coin_pub: string;
+ }
-.. sourcecode:: c
+ **Response:**
- struct TALER_WithdrawRequestPS {
- signed (purpose = TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW) {
- 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;
- }
- };
-
- struct TALER_DepositRequestPS {
- signed (purpose = TALER_SIGNATURE_WALLET_COIN_DEPOSIT) {
- 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;
- }
- };
-
- struct TALER_DepositConfirmationPS {
- signed (purpose = TALER_SIGNATURE_MINT_CONFIRM_DEPOSIT) {
- 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;
- }
- };
-
- struct TALER_RefreshMeltCoinAffirmationPS {
- signed (purpose = TALER_SIGNATURE_WALLET_COIN_MELT) {
- struct GNUNET_HashCode session_hash;
- struct TALER_AmountNBO amount_with_fee;
- struct TALER_AmountNBO melt_fee;
- union TALER_CoinSpendPublicKeyP coin_pub;
- }
- };
+ :status 200: the operation succeeded
- struct TALER_RefreshMeltConfirmationPS {
- signed (purpose = TALER_SIGNATURE_MINT_CONFIRM_MELT) {
- struct GNUNET_HashCode session_hash;
- uint16_t noreveal_index;
- }
- };
-
- struct TALER_MintSigningKeyValidityPS {
- signed (purpose = TALER_SIGNATURE_MASTER_SIGNING_KEY_VALIDITY) {
- struct TALER_MasterPublicKeyP master_public_key;
- struct GNUNET_TIME_AbsoluteNBO start;
- struct GNUNET_TIME_AbsoluteNBO expire;
- struct GNUNET_TIME_AbsoluteNBO end;
- struct TALER_MintPublicKeyP signkey_pub;
- }
- };
+ .. code-block:: tsref
- struct TALER_MintKeySetPS {
- signed (purpose=TALER_SIGNATURE_MINT_KEY_SET) {
- struct GNUNET_TIME_AbsoluteNBO list_issue_date;
- struct GNUNET_HashCode hc;
- }
- };
-
- struct TALER_DenominationKeyValidityPS {
- signed (purpose = TALER_SIGNATURE_MASTER_DENOMINATION_KEY_VALIDITY) {
- 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;
+ {
+ // Decrypted transfer secret
+ secret: string;
}
- };
- struct TALER_MasterWireSepaDetailsPS {
- signed (purpose = TALER_SIGNATURE_MASTER_SEPA_DETAILS) {
- struct GNUNET_HashCode h_sepa_details;
- }
- };
- struct TALER_MintWireSupportMethodsPS {
- signed (purpose = TALER_SIGNATURE_MINT_WIRE_TYPES) {
- struct GNUNET_HashCode h_wire_types;
- }
- };
-
- struct TALER_DepositTrackPS {
- signed (purpose = TALER_SIGNATURE_MERCHANT_DEPOSIT_WTID) {
- struct GNUNET_HashCode h_contract;
- struct GNUNET_HashCode h_wire;
- uint64_t transaction_id;
- struct TALER_MerchantPublicKeyP merchant;
- struct TALER_CoinSpendPublicKeyP coin_pub;
- }
- };
diff --git a/conf.py b/conf.py
@@ -23,12 +23,15 @@ import os
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
+needs_sphinx = '1.3'
+
+sys.path.append(os.path.abspath('exts'))
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
+ 'tsref',
'sphinx.ext.todo',
'sphinx.ext.pngmath',
'sphinxcontrib.httpdomain'
@@ -48,7 +51,7 @@ master_doc = 'index'
# General information about the project.
project = u'Taler'
-copyright = u'2014, 2015 Florian Dold, Benedikt Muller, Sree Harsha Totakura, Christian Grothoff, Marcello Stanisci (GPLv3+ or GFDL 1.3+)'
+copyright = u'2014, 2015, 2016 Florian Dold, Benedikt Muller, Sree Harsha Totakura, Christian Grothoff, Marcello Stanisci (GPLv3+ or GFDL 1.3+)'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
diff --git a/dev-merchant.rst b/dev-merchant.rst
@@ -1,74 +0,0 @@
-=================================
-Merchant Reference Implementation
-=================================
-
------------------------
-Architectural Overview
------------------------
-
-The merchant reference implementationis divided into two independent
-compontents, the `frontend` and the `backend`.
-
-The `frontend` is the existing shopping portal of the merchant.
-The architecture tries to minimize the amount of modifications necessary
-to the `frontend` as well as the trust that needs to be placed into the
-`frontend` logic. Taler requires the frontend to facilitate two
-JSON-based interactions between the wallet and the `backend`, and
-one of those is trivial.
-
-The `backend` is a standalone C application intended to implement all
-the cryptographic routines required to interact with the Taler wallet
-and a Taler mint.
-
-
-------------------------------
-The Merchant Backend HTTP API
-------------------------------
-
-The following API are made available by the merchant's `backend` to the merchant's `frontend`.
-
-.. http:post:: /contract
-
- Ask the backend to add some missing (mostly related to cryptography) information to the contract.
-
- :reqheader Content-Type: application/json
-
- The `proposition` that is to be sent from the frontend is a `contract` object without the fields
-
- * `merchant_pub`
- * `mints`
- * `H_wire`
-
- The `backend` then completes this information based on its configuration.
-
- **Success Response**
-
- :status 200 OK: The backend has successfully created the contract.
- :resheader Content-Type: application/json
-
- The `frontend` should pass this response verbatim to the wallet.
-
- **Failure Responses: Bad contract**
-
- :status 400 Bad Request: Request not understood. The JSON was invalid. Possibly due to some error in formatting the JSON by the `frontend`.
-
-.. http:post:: /pay
-
- Asks the `backend` to execute the transaction with the mint and deposit the coins.
-
- :reqheader Content-Type: application/json
-
- The `frontend` passes the :ref:`deposit permission <deposit-permission>` received from the wallet, by adding the fields `max_fee`, `amount` (see :ref:`contract`) and optionally adding a field named `edate`, indicating a deadline by which he would expect to receive the bank transfer for this deal
-
- **Success Response: OK**
-
- :status 200 OK: The mint accepted all of the coins. The `frontend` should now fullfill the contract. This response has no meaningful body, the frontend needs to generate the fullfillment page.
-
- **Failure Responses: Bad mint**
-
- :status 400 Precondition failed: The given mint is not acceptable for this merchant, as it is not in the list of accepted mints and not audited by an approved auditor.
-
-
- **Failure Responses: Mint trouble**
-
- The `backend` will return verbatim the error codes received from the mint's :ref:`deposit <deposit>` API. If the wallet made a mistake, like by double-spending for example, the `frontend` should pass the reply verbatim to the browser/wallet. This should be the expected case, as the `frontend` cannot really make mistakes; the only reasonable exception is if the `backend` is unavailable, in which case the customer might appreciate some reassurance that the merchant is working on getting his systems back online.
diff --git a/dev-wallet-wx.rst b/dev-wallet-wx.rst
@@ -91,4 +91,16 @@ IndexedDB Query Abstractions
The *wxwallet* uses a fluent-style API for queries on IndexedDB.
-TODO: say more
+TODO: say more about this
+
+
+-------
+Testing
+-------
+
+Test cases for the wallet are written in TypeScript and
+run with `mochajs <http://mochajs.org/>`_ and the `better-assert <https://github.com/tj/better-assert>`_ assertion
+library.
+
+Run the default test suite with ``XXX``.
+
diff --git a/exts/tsref.py b/exts/tsref.py
@@ -0,0 +1,236 @@
+# Copyright (C) 2016 Florian Dold
+#
+# This program 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 3 of the License, or
+# (at your option) any later version.
+#
+# This program 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 General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+"""
+This extension adds a new lexer "tsref" for TypeScript, which
+allows reST-style links inside comments (`LinkName`_),
+and semi-automatically adds links to the definition of types.
+
+For type TYPE, a reference to tsref-type-TYPE is added.
+
+Known bugs and limitations:
+ - The way the extension works right now interferes wiht
+ Sphinx's caching, the build directory should be cleared
+ before every build.
+"""
+
+
+from pygments.util import get_bool_opt
+from pygments.token import Name, Comment, Token, _TokenType
+from pygments.filter import Filter
+from sphinx.highlighting import PygmentsBridge
+from sphinx.builders.html import StandaloneHTMLBuilder
+from sphinx.pygments_styles import SphinxStyle
+from pygments.formatters import HtmlFormatter
+from docutils import nodes
+from docutils.nodes import make_id
+import re
+
+
+_escape_html_table = {
+ ord('&'): u'&',
+ ord('<'): u'<',
+ ord('>'): u'>',
+ ord('"'): u'"',
+ ord("'"): u''',
+}
+
+
+class LinkingHtmlFormatter(HtmlFormatter):
+ def __init__(self, **kwargs):
+ super(LinkingHtmlFormatter, self).__init__(**kwargs)
+ self._builder = kwargs['_builder']
+
+ def _fmt(self, value, tok):
+ cls = self._get_css_class(tok)
+ href = tok_getprop(tok, "href")
+ caption = tok_getprop(tok, "caption")
+ content = caption if caption is not None else value
+ if href:
+ value = '<a style="color:inherit;text-decoration:underline" href="%s">%s</a>' % (href, content)
+ if cls is None or cls == "":
+ return value
+ return '<span class="%s">%s</span>' % (cls, value)
+
+ def _format_lines(self, tokensource):
+ """
+ Just format the tokens, without any wrapping tags.
+ Yield individual lines.
+ """
+ lsep = self.lineseparator
+ escape_table = _escape_html_table
+
+ line = ''
+ for ttype, value in tokensource:
+ link = get_annotation(ttype, "link")
+
+ parts = value.translate(escape_table).split('\n')
+
+ if len(parts) == 0:
+ # empty token, usually should not happen
+ pass
+ elif len(parts) == 1:
+ # no newline before or after token
+ line += self._fmt(parts[0], ttype)
+ else:
+ line += self._fmt(parts[0], ttype)
+ yield 1, line + lsep
+ for part in parts[1:-1]:
+ yield 1, self._fmt(part, ttype) + lsep
+ line = self._fmt(parts[-1], ttype)
+
+ if line:
+ yield 1, line + lsep
+
+
+class MyPygmentsBridge(PygmentsBridge):
+ def __init__(self, builder, trim_doctest_flags):
+ self.dest = "html"
+ self.trim_doctest_flags = trim_doctest_flags
+ self.formatter_args = {'style': SphinxStyle, '_builder': builder}
+ self.formatter = LinkingHtmlFormatter
+
+
+class MyHtmlBuilder(StandaloneHTMLBuilder):
+ name = "html-linked"
+ def init_highlighter(self):
+ if self.config.pygments_style is not None:
+ style = self.config.pygments_style
+ elif self.theme:
+ style = self.theme.get_confstr('theme', 'pygments_style', 'none')
+ else:
+ style = 'sphinx'
+ self.highlighter = MyPygmentsBridge(self, self.config.trim_doctest_flags)
+
+ def write_doc(self, docname, doctree):
+ self._current_docname = docname
+ super(MyHtmlBuilder, self).write_doc(docname, doctree)
+
+
+def get_annotation(tok, key):
+ if not hasattr(tok, "kv"):
+ return None
+ return tok.kv.get(key)
+
+
+def copy_token(tok):
+ new_tok = _TokenType(tok)
+ # This part is very fragile against API changes ...
+ new_tok.subtypes = set(tok.subtypes)
+ new_tok.parent = tok.parent
+ return new_tok
+
+
+def tok_setprop(tok, key, value):
+ tokid = id(tok)
+ e = token_props.get(tokid)
+ if e is None:
+ e = token_props[tokid] = (tok, {})
+ _, kv = e
+ kv[key] = value
+
+
+def tok_getprop(tok, key):
+ tokid = id(tok)
+ e = token_props.get(tokid)
+ if e is None:
+ return None
+ _, kv = e
+ return kv.get(key)
+
+
+link_reg = re.compile(r"`([^`<]+)\s*(?:<([^>]+)>)?\s*`_")
+
+# Map from token id to props.
+# Properties can't be added to tokens
+# since they derive from Python's tuple.
+token_props = {}
+
+# Mapping from element IDs to document
+# name where the ID occurs.
+id_to_doc = {}
+
+
+class LinkFilter(Filter):
+ def __init__(self, app, **options):
+ self.app = app
+ Filter.__init__(self, **options)
+
+ def filter(self, lexer, stream):
+ for ttype, value in stream:
+ if ttype in Token.Keyword.Type:
+ defname = make_id('tsref-type-' + value);
+ t = copy_token(ttype)
+ if defname in id_to_doc:
+ docname = id_to_doc[defname]
+ href = self.app.builder.get_target_uri(docname) + "#" + defname
+ tok_setprop(t, "href", href)
+
+ yield t, value
+ elif ttype in Token.Comment:
+ last = 0
+ for m in re.finditer(link_reg, value):
+ pre = value[last:m.start()]
+ if pre:
+ yield ttype, pre
+ t = copy_token(ttype)
+ x1, x2 = m.groups()
+ if x2 is None:
+ caption = x1.strip()
+ id = make_id(x1)
+ else:
+ caption = x1.strip()
+ id = make_id(x2)
+ if id in id_to_doc:
+ docname = id_to_doc[id]
+ href = self.app.builder.get_target_uri(docname) + "#" + id
+ tok_setprop(t, "href", href)
+ tok_setprop(t, "caption", caption)
+ else:
+ self.app.builder.warn("unresolved link target in comment: " + id)
+ yield t, m.group(1)
+ last = m.end()
+ post = value[last:]
+ if post:
+ yield ttype, post
+ else:
+ yield ttype, value
+
+
+
+def remember_targets(app, doctree):
+ docname = app.env.docname
+ for node in doctree.traverse():
+ if not isinstance(node, nodes.Element):
+ continue
+ ids = node.get("ids")
+ if ids:
+ for id in ids:
+ id_to_doc[id] = docname
+
+
+def setup(app):
+ from sphinx.highlighting import lexers
+ from pygments.lexers import TypeScriptLexer
+ from pygments.token import Name
+ from pygments.filters import NameHighlightFilter
+ lexer = TypeScriptLexer()
+ lexer.add_filter(LinkFilter(app))
+ app.add_lexer('tsref', lexer)
+ app.add_builder(MyHtmlBuilder)
+ app.connect("doctree-read", remember_targets)
+
+
+
diff --git a/impl-merchant.rst b/impl-merchant.rst
@@ -0,0 +1,106 @@
+=================================
+Merchant Reference Implementation
+=================================
+
+-----------------------
+Architectural Overview
+-----------------------
+
+The merchant reference implementationis divided into two independent
+compontents, the `frontend` and the `backend`.
+
+The `frontend` is the existing shopping portal of the merchant.
+The architecture tries to minimize the amount of modifications necessary
+to the `frontend` as well as the trust that needs to be placed into the
+`frontend` logic. Taler requires the frontend to facilitate two
+JSON-based interactions between the wallet and the `backend`, and
+one of those is trivial.
+
+The `backend` is a standalone C application intended to implement all
+the cryptographic routines required to interact with the Taler wallet
+and a Taler mint.
+
+
+
+------------------------------
+The Frontent HTTP API
+------------------------------
+
+.. http:get:: /taler/contract
+
+ Triggers the contract generation. Note that the URL may differ between
+ merchants.
+
+ **Request:**
+
+ The request depends entirely on the merchant implementation.
+
+ **Response**
+
+ :status 200 OK: The request was successful. The body contains an :ref:`offer <offer>`.
+ :status 400 Bad Request: Request not understood.
+ :status 500 Internal Server Error:
+ In most cases, some error occurred while the backend was generating the
+ contract. For example, it failed to store it into its database.
+
+
+------------------------------
+The Merchant Backend HTTP API
+------------------------------
+
+The following API are made available by the merchant's `backend` to the merchant's `frontend`.
+
+.. http:post:: /contract
+
+ Ask the backend to add some missing (mostly related to cryptography) information to the contract.
+
+ **Request:**
+
+ The `proposition` that is to be sent from the frontend is a `contract` object without the fields
+
+ * `merchant_pub`
+ * `mints`
+ * `H_wire`
+
+ The `backend` then completes this information based on its configuration.
+
+ **Response**
+
+ :status 200 OK:
+ The backend has successfully created the contract.
+ :status 400 Bad Request:
+ Request not understood. The JSON was invalid. Possibly due to some error in
+ formatting the JSON by the `frontend`.
+
+ On success, the `frontend` should pass this response verbatim to the wallet.
+
+
+.. http:post:: /pay
+
+ Asks the `backend` to execute the transaction with the mint and deposit the coins.
+
+ **Request:**
+
+ The `frontend` passes the :ref:`deposit permission <deposit-permission>`
+ received from the wallet, by adding the fields `max_fee`, `amount` (see
+ :ref:`contract`) and optionally adding a field named `edate`, indicating a
+ deadline by which he would expect to receive the bank transfer for this deal
+
+ **Response:**
+
+ :status 200 OK:
+ The mint accepted all of the coins. The `frontend` should now fullfill the
+ contract. This response has no meaningful body, the frontend needs to
+ generate the fullfillment page.
+ :status 400 Precondition failed:
+ The given mint is not acceptable for this merchant, as it is not in the
+ list of accepted mints and not audited by an approved auditor.
+
+
+ The `backend` will return verbatim the error codes received from the mint's
+ :ref:`deposit <deposit>` API. If the wallet made a mistake, like by
+ double-spending for example, the `frontend` should pass the reply verbatim to
+ the browser/wallet. This should be the expected case, as the `frontend`
+ cannot really make mistakes; the only reasonable exception is if the
+ `backend` is unavailable, in which case the customer might appreciate some
+ reassurance that the merchant is working on getting his systems back online.
diff --git a/impl-mint.rst b/impl-mint.rst
@@ -35,7 +35,7 @@ The section `[mint_keys]` containts the following entries:
* `lookahead_sign`: For how far into the future should keys be issued? This determines the frequency
of offline signing with the master key.
* `lookahead_provide`: How far into the future should the mint provide keys? This determines the attack
-window on keys.
+ window on keys.
Sections specifying denomination (coin) information start with "coin\_". By convention, the name continues with "$CURRENCY_[$SUBUNIT]_$VALUE", i.e. "[coin_eur_ct_10] for a 10 cent piece. However, only the "coin\_" prefix is mandatory. Each "coin\_"-section must then have the following options:
diff --git a/index.rst b/index.rst
@@ -32,6 +32,7 @@ It focuses on how to install, configure and run the required software.
:maxdepth: 2
impl-mint
+ impl-merchant
------------------------
@@ -61,6 +62,7 @@ interfaces between the core components of Taler.
.. toctree::
:maxdepth: 2
+ api-common
api-mint
api-merchant
@@ -78,7 +80,6 @@ core components of the Taler reference implementation.
:maxdepth: 2
dev-wallet-wx
- dev-merchant
------------------
@@ -86,9 +87,10 @@ Indices and tables
------------------
.. toctree::
- :maxdepth: 1
+ :hidden:
glossary
+* :doc:`glossary`
* :ref:`search`
diff --git a/integration-merchant.rst b/integration-merchant.rst
@@ -2,7 +2,49 @@
Interaction with merchant websites
==================================
-This section defines the protocol between the wallet
-and the merchant page.
+-------------
+Purchase Flow
+-------------
+The purchase flow consists of the following steps:
+1. UA visits merchant's checkout page
+2. The merchant's checkout page notifies the wallet
+ of the contract (``taler-deliver-contract``).
+3. The user reviews the contract inside the wallet
+4. The wallet directs the UA to the payment execution page
+5. The execution page must send the event ``taler-execute-payment`` with
+ the contract hash of the payment to be executed.
+6. The wallet executes the payment in the domain context of the
+ execution page and emits the ``taler-payment-result`` event
+ on the execution page.
+7. The execution page reacts to the payment result (which
+ is either successful or unsuccessful) by showing
+ an appropriate response to the user.
+
+----------------
+Event Reference
+----------------
+
+.. topic:: ``taler-deliver-contract``
+
+ The event takes an :ref:`offer <offer>` as event detail.
+
+.. topic:: ``taler-execute-payment``
+
+ The event takes `H_contract` of a :ref:`Contract <tsref-type-Contract>` as event detail.
+
+.. topic:: ``taler-payment-result``
+
+ The event takes the following object as event detail:
+
+ .. code-block:: tsref
+
+ {
+ // was the payment successful?
+ success: boolean;
+
+ // human-readable indication of what went wrong
+ hint: string;
+ }
+
