summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2019-12-20 20:04:00 +0100
committerChristian Grothoff <christian@grothoff.org>2019-12-20 20:04:00 +0100
commit934a6a18301e81c4fd1b3a8cda2dc13dca4741cc (patch)
treed5753592cdb9c58045e8d9475a05c9223dfa9aea
parent5f8c067ab79831d9c13c4155e8739f632cee320f (diff)
downloaddocs-934a6a18301e81c4fd1b3a8cda2dc13dca4741cc.tar.gz
docs-934a6a18301e81c4fd1b3a8cda2dc13dca4741cc.tar.bz2
docs-934a6a18301e81c4fd1b3a8cda2dc13dca4741cc.zip
updating prebuild documentation
-rw-r--r--texinfo/taler-bank-figures/exchange-db.pngbin564934 -> 313125 bytes
-rw-r--r--texinfo/taler-bank.texi6
-rw-r--r--texinfo/taler-exchange-figures/exchange-db.pngbin564934 -> 313125 bytes
-rw-r--r--texinfo/taler-exchange.texi148
-rw-r--r--texinfo/taler-merchant-api-tutorial-figures/exchange-db.pngbin564934 -> 313125 bytes
-rw-r--r--texinfo/taler-merchant-api-tutorial.texi4
-rw-r--r--texinfo/taler-merchant-figures/exchange-db.pngbin564934 -> 313125 bytes
-rw-r--r--texinfo/taler-merchant.texi16
8 files changed, 134 insertions, 40 deletions
diff --git a/texinfo/taler-bank-figures/exchange-db.png b/texinfo/taler-bank-figures/exchange-db.png
index 421e5941..b088da04 100644
--- a/texinfo/taler-bank-figures/exchange-db.png
+++ b/texinfo/taler-bank-figures/exchange-db.png
Binary files differ
diff --git a/texinfo/taler-bank.texi b/texinfo/taler-bank.texi
index 78293b57..075df81e 100644
--- a/texinfo/taler-bank.texi
+++ b/texinfo/taler-bank.texi
@@ -21,7 +21,7 @@
@copying
@quotation
-GNU Taler 0.6.0pre1, Sep 18, 2019
+GNU Taler 0.6.0pre1, Dec 20, 2019
GNU Taler team
@@ -191,7 +191,7 @@ transmit to the exchange when transmitting the funds.
@item @code{confirm-reserve}
-To secure the operation, the (demo) bank then shows a "CAPTCHA page"
+To secure the operation, the (demo) bank then shows a “CAPTCHA page”
– a real bank would instead show some PIN entry dialog or similar
security method – where the customer can finally prove she their
identity and thereby confirm the withdraw operation to the bank.
@@ -237,7 +237,7 @@ API, providing those arguments it got along the @code{X-Taler-Callback-Url}
URL. (In the future, the exchange will poll for this information.)
However, the bank will define two additional values for this API:
@code{execution_date} (a operation’s timestamp), and @code{transfer_details}
-(just a "seed" to make unique the operation). See
+(just a “seed” to make unique the operation). See
@indicateurl{https://docs.taler.net/api/api-exchange.html#administrative-api-bank-transactions}.
The polling mechanism is possbile thanks to the @code{/history} API
diff --git a/texinfo/taler-exchange-figures/exchange-db.png b/texinfo/taler-exchange-figures/exchange-db.png
index 421e5941..b088da04 100644
--- a/texinfo/taler-exchange-figures/exchange-db.png
+++ b/texinfo/taler-exchange-figures/exchange-db.png
Binary files differ
diff --git a/texinfo/taler-exchange.texi b/texinfo/taler-exchange.texi
index e6c95a4a..7e2fa5fb 100644
--- a/texinfo/taler-exchange.texi
+++ b/texinfo/taler-exchange.texi
@@ -21,7 +21,7 @@
@copying
@quotation
-GNU Taler 0.6.0pre1, Sep 18, 2019
+GNU Taler 0.6.0pre1, Dec 20, 2019
GNU Taler team
@@ -76,6 +76,7 @@ Configuration
* Database::
* Coins (denomination keys): Coins denomination keys.
* Keys duration::
+* Terms of Service::
Bank account
@@ -83,6 +84,10 @@ Bank account
* Wire plugin “ebics”::
* Wire fee structure::
+Terms of Service
+
+* Example::
+
Deployment
* Keys generation::
@@ -382,6 +387,7 @@ of some of the options.
* Database::
* Coins (denomination keys): Coins denomination keys.
* Keys duration::
+* Terms of Service::
@end menu
@@ -390,7 +396,6 @@ of some of the options.
@section Configuration format
-configuration
In Taler realm, any component obeys to the same pattern to get
configuration values. According to this pattern, once the component has
been installed, the installation deploys default values in
@@ -774,7 +779,7 @@ CONFIG = postgres:///talerdemo
Sections specifying denomination (coin) information start with @code{coin_}.
-By convention, the name continues with "$CURRENCY_[$SUBUNIT]_$VALUE",
+By convention, the name continues with “$CURRENCY_[$SUBUNIT]_$VALUE”,
i.e. @code{[coin_eur_ct_10]} for a 10 cent piece. However, only the @code{coin_}
prefix is mandatory. Each @code{coin_}-section must then have the following
options:
@@ -784,7 +789,7 @@ options:
@item
value: How much is the coin worth, the format is
-CURRENCY:VALUE.FRACTION. For example, a 10 cent piece is "EUR:0.10".
+CURRENCY:VALUE.FRACTION. For example, a 10 cent piece is “EUR:0.10”.
@item
duration_withdraw: How long can a coin of this type be withdrawn?
@@ -816,7 +821,7 @@ rsa_keysize: How many bits should the RSA modulus (product of the two
primes) have for this type of coin.
@end itemize
-@node Keys duration,,Coins denomination keys,Configuration
+@node Keys duration,Terms of Service,Coins denomination keys,Configuration
@anchor{taler-exchange-manual id11}@anchor{1e}@anchor{taler-exchange-manual keys-duration}@anchor{1f}
@section Keys duration
@@ -860,11 +865,100 @@ Note that if SIGNKEY_DURATION is bigger than LOOKAHEAD_SIGN,
which is sufficient to cover all the gap.
@end itemize
+@node Terms of Service,,Keys duration,Configuration
+@anchor{taler-exchange-manual terms-of-service}@anchor{20}
+@section Terms of Service
+
+
+The exchange has an endpoint “/terms” to return the terms of service
+(in legal language) of the exchange operator. The wallet will show
+those terms of service to the user when the user is first withdrawing
+coins. Terms of service are optional for experimental deployments,
+if none are configured, the exchange will return a simple statement
+saying that there are no terms of service available.
+
+To configure the terms of service response, there are two options
+in the [exchange] section:
+
+
+@itemize -
+
+@item
+TERMS_ETAG: The current “Etag” to return for the terms of service.
+This value must be changed whenever the terms of service are
+updated. A common value to use would be a version number.
+Note that if you change the TERMS_ETAG, you MUST also provide
+the respective files in TERMS_DIR (see below).
+
+@item
+TERMS_DIR: The directory that contains the terms of service.
+The files in the directory must be readable to the exchange
+process.
+@end itemize
+
+The TERMS_DIR directory structure must follow a particular layout.
+First, inside of TERMS_DIR, there should be sub-directories using
+two-letter language codes like “en”, “de”, or “jp”. Each of these
+directories would then hold translations of the current terms of
+service into the respective language. Empty directories are
+permitted in case translations are not available.
+
+Then, inside each language directory, files with the name of the
+value set as the TERMS_ETAG must be provided. The extension of
+each of the files should be typical for the respective mime type.
+The set of supported mime types is currently hard-coded in the
+exchange, and includes HTML, PDF and TXT files. If other files are
+present, the exchange may show a warning on startup.
+
+@menu
+* Example::
+
+@end menu
+
+@node Example,,,Terms of Service
+@anchor{taler-exchange-manual example}@anchor{21}
+@subsection Example
+
+
+A sample file structure for a TERMS_ETAG of “v1” would be:
+
+
+@itemize -
+
+@item
+TERMS_DIR/en/v1.txt
+
+@item
+TERMS_DIR/en/v1.html
+
+@item
+TERMS_DIR/en/v1.pdf
+
+@item
+TERMS_DIR/de/v1.txt
+
+@item
+TERMS_DIR/de/v1.html
+
+@item
+TERMS_DIR/de/v1.pdf
+
+@item
+TERMS_DIR/fr/v1.pdf
+@end itemize
+
+If the user requests an HTML with language preferences “fr” followed by “en”,
+the exchange would return “TERMS_DIR/en/v1.html” lacking an HTML version in
+French.
+
@node Deployment,Diagnostics,Configuration,Top
-@anchor{taler-exchange-manual deployment}@anchor{20}@anchor{taler-exchange-manual id12}@anchor{21}
+@anchor{taler-exchange-manual deployment}@anchor{22}@anchor{taler-exchange-manual id12}@anchor{23}
@chapter Deployment
+This chapter describes how to deploy the exchange once it has been
+properly configured.
+
@menu
* Keys generation::
* Database upgrades::
@@ -872,13 +966,13 @@ which is sufficient to cover all the gap.
@end menu
@node Keys generation,Database upgrades,,Deployment
-@anchor{taler-exchange-manual id13}@anchor{22}@anchor{taler-exchange-manual keys-generation}@anchor{23}
+@anchor{taler-exchange-manual id13}@anchor{24}@anchor{taler-exchange-manual keys-generation}@anchor{25}
@section Keys generation
Once the configuration is properly set up, all the keys can be generated
by the tool @code{taler-exchange-keyup}. The following command generates
-denomkeys and signkeys, plus the "blob" that is to be signed by the
+denomkeys and signkeys, plus the “blob” that is to be signed by the
auditor.
@example
@@ -920,7 +1014,7 @@ option @code{[exchange]/master_public_key}.
@code{OUTPUT_FILE} must then be copied into the directory specified by the
option @code{AUDITOR_BASE_DIR} under the section @code{[exchangedb]}. Assuming
@code{AUDITOR_BASE_DIR = $@{HOME@}/.local/share/taler/auditors}, the
-following command will "add" the auditor identified by @code{AUDITOR_URL}
+following command will “add” the auditor identified by @code{AUDITOR_URL}
to the exchange.
@example
@@ -932,7 +1026,7 @@ response must contain an entry in the @code{auditors} array mentioning the
auditor’s URL.
@node Database upgrades,,Keys generation,Deployment
-@anchor{taler-exchange-manual database-upgrades}@anchor{24}@anchor{taler-exchange-manual id14}@anchor{25}
+@anchor{taler-exchange-manual database-upgrades}@anchor{26}@anchor{taler-exchange-manual id14}@anchor{27}
@section Database upgrades
@@ -951,7 +1045,7 @@ exchange can then not detect double-spending. Hence this operation must
not be performed in a production system.
@node Diagnostics,,Deployment,Top
-@anchor{taler-exchange-manual diagnostics}@anchor{26}@anchor{taler-exchange-manual id15}@anchor{27}
+@anchor{taler-exchange-manual diagnostics}@anchor{28}@anchor{taler-exchange-manual id15}@anchor{29}
@chapter Diagnostics
@@ -970,7 +1064,7 @@ diagnostics.
@end menu
@node Reserve management,Database Scheme,,Diagnostics
-@anchor{taler-exchange-manual id16}@anchor{28}@anchor{taler-exchange-manual reserve-management}@anchor{29}
+@anchor{taler-exchange-manual id16}@anchor{2a}@anchor{taler-exchange-manual reserve-management}@anchor{2b}
@section Reserve management
@@ -980,7 +1074,7 @@ tool taler-exchange-reservemod allows create and add money to reserves
in the exchange’s database.
@node Database Scheme,Signing key storage,Reserve management,Diagnostics
-@anchor{taler-exchange-manual database-scheme}@anchor{2a}@anchor{taler-exchange-manual id17}@anchor{2b}
+@anchor{taler-exchange-manual database-scheme}@anchor{2c}@anchor{taler-exchange-manual id17}@anchor{2d}
@section Database Scheme
@@ -996,13 +1090,13 @@ The database scheme used by the exchange look as follows:
@image{taler-exchange-figures/exchange-db,,,,png}
@node Signing key storage,Denomination key storage,Database Scheme,Diagnostics
-@anchor{taler-exchange-manual id18}@anchor{2c}@anchor{taler-exchange-manual signing-key-storage}@anchor{2d}
+@anchor{taler-exchange-manual id18}@anchor{2e}@anchor{taler-exchange-manual signing-key-storage}@anchor{2f}
@section Signing key storage
The private online signing keys of the exchange are stored in a
-subdirectory "signkeys/" of the "KEYDIR" which is an option in the
-"[exchange]" section of the configuration file. The filename is the
+subdirectory “signkeys/” of the “KEYDIR” which is an option in the
+“[exchange]” section of the configuration file. The filename is the
starting time at which the signing key can be used in microseconds since
the Epoch. The file format is defined by the struct
TALER_EXCHANGEDB_PrivateSigningKeyInformationP:
@@ -1015,19 +1109,19 @@ struct TALER_EXCHANGEDB_PrivateSigningKeyInformationP @{
@end example
@node Denomination key storage,Auditor signature storage,Signing key storage,Diagnostics
-@anchor{taler-exchange-manual denomination-key-storage}@anchor{2e}@anchor{taler-exchange-manual id19}@anchor{2f}
+@anchor{taler-exchange-manual denomination-key-storage}@anchor{30}@anchor{taler-exchange-manual id19}@anchor{31}
@section Denomination key storage
The private denomination keys of the exchange are store in a
-subdirectory "denomkeys/" of the "KEYDIR" which is an option in the
-"[exchange]" section of the configuration file. "denomkeys/" contains
+subdirectory “denomkeys/” of the “KEYDIR” which is an option in the
+“[exchange]” section of the configuration file. “denomkeys/” contains
further subdirectories, one per denomination. The specific name of the
-subdirectory under "denomkeys/" is ignored by the exchange. However, the
-name is important for the "taler-exchange-keyup" tool that generates the
+subdirectory under “denomkeys/” is ignored by the exchange. However, the
+name is important for the “taler-exchange-keyup” tool that generates the
keys. The tool combines a human-readable encoding of the denomination
-(i.e. for EUR:1.50 the prefix would be "EUR_1_5-", or for EUR:0.01 the
-name would be "EUR_0_01-") with a postfix that is a truncated
+(i.e. for EUR:1.50 the prefix would be “EUR_1_5-“, or for EUR:0.01 the
+name would be “EUR_0_01-“) with a postfix that is a truncated
Crockford32 encoded hash of the various attributes of the denomination
key (relative validity periods, fee structure and key size). Thus, if
any attributes of a coin change, the name of the subdirectory will also
@@ -1057,7 +1151,7 @@ GNUNET_CRYPTO_rsa_private_key_decode().
@end menu
@node Revocations,,,Denomination key storage
-@anchor{taler-exchange-manual id20}@anchor{30}@anchor{taler-exchange-manual revocations}@anchor{31}
+@anchor{taler-exchange-manual id20}@anchor{32}@anchor{taler-exchange-manual revocations}@anchor{33}
@subsection Revocations
@@ -1089,13 +1183,13 @@ under highly unusual (“emergency”) conditions and not under normal
conditions.
@node Auditor signature storage,,Denomination key storage,Diagnostics
-@anchor{taler-exchange-manual auditor-signature-storage}@anchor{32}@anchor{taler-exchange-manual id21}@anchor{33}
+@anchor{taler-exchange-manual auditor-signature-storage}@anchor{34}@anchor{taler-exchange-manual id21}@anchor{35}
@section Auditor signature storage
Signatures from auditors are stored in the directory specified in the
-exchange configuration section "exchangedb" under the option
-"AUDITOR_BASE_DIR". The exchange does not care about the specific names
+exchange configuration section “exchangedb” under the option
+“AUDITOR_BASE_DIR”. The exchange does not care about the specific names
of the files in this directory.
Each file must contain a header with the public key information of the
diff --git a/texinfo/taler-merchant-api-tutorial-figures/exchange-db.png b/texinfo/taler-merchant-api-tutorial-figures/exchange-db.png
index 421e5941..b088da04 100644
--- a/texinfo/taler-merchant-api-tutorial-figures/exchange-db.png
+++ b/texinfo/taler-merchant-api-tutorial-figures/exchange-db.png
Binary files differ
diff --git a/texinfo/taler-merchant-api-tutorial.texi b/texinfo/taler-merchant-api-tutorial.texi
index b49eeefe..b5db7024 100644
--- a/texinfo/taler-merchant-api-tutorial.texi
+++ b/texinfo/taler-merchant-api-tutorial.texi
@@ -21,7 +21,7 @@
@copying
@quotation
-GNU Taler 0.6.0pre1, Sep 18, 2019
+GNU Taler 0.6.0pre1, Dec 20, 2019
GNU Taler team
@@ -936,10 +936,10 @@ and they is also allowed to have additional fields. Contract
renderers must render at least the fields listed above, and should
render fields that they do not understand as a key-value list.
@end table
-@anchor{taler-merchant-api-tutorial The-Taler-Order-Format}@w{ }
@anchor{d}@w{ }
@anchor{b}@w{ }
@anchor{taler-merchant-api-tutorial Session_002dBound-Payments}@w{ }
+@anchor{taler-merchant-api-tutorial The-Taler-Order-Format}@w{ }
@c %**end of body
@bye
diff --git a/texinfo/taler-merchant-figures/exchange-db.png b/texinfo/taler-merchant-figures/exchange-db.png
index 421e5941..b088da04 100644
--- a/texinfo/taler-merchant-figures/exchange-db.png
+++ b/texinfo/taler-merchant-figures/exchange-db.png
Binary files differ
diff --git a/texinfo/taler-merchant.texi b/texinfo/taler-merchant.texi
index f1334973..7a484371 100644
--- a/texinfo/taler-merchant.texi
+++ b/texinfo/taler-merchant.texi
@@ -21,7 +21,7 @@
@copying
@quotation
-GNU Taler 0.6.0pre1, Sep 18, 2019
+GNU Taler 0.6.0pre1, Dec 20, 2019
GNU Taler team
@@ -621,7 +621,7 @@ The option
@end example
specifies which DBMS is to be used. However, currently only the value
-"postgres" is supported. This is also the default.
+“postgres” is supported. This is also the default.
In addition to selecting the DBMS software, the backend requires
DBMS-specific options to access the database.
@@ -703,7 +703,7 @@ instance
The backend allows the user to run multiple instances of shops with
distinct business entities against a single backend. Each instance
uses its own bank accounts and key for signing contracts. It is
-mandatory to configure a "default" instance.
+mandatory to configure a “default” instance.
@itemize -
@@ -856,7 +856,7 @@ Given the above configuration, the backend will use a database named
The backend will deposit the coins it receives to the exchange at
@indicateurl{https://exchange.demo.taler.net/}, which has the master key
-"CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00".
+“CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00”.
Please note that @code{doc/config.sh} will walk you through all
configuration steps, showing how to invoke @code{taler-config} for each of
@@ -955,7 +955,7 @@ Please NOTE that the generator contains @emph{hardcoded} values, as for
deposit fees of the coins it uses. In order to work against the used
exchange, those values MUST match the ones used by the exchange.
-The following example shows how the generator "sets" a deposit fee of
+The following example shows how the generator “sets” a deposit fee of
EUR:0.01 for the 5 EURO coin.
@example
@@ -1304,7 +1304,7 @@ be able to find the bank details in a human-readable format on the main
page of the exchange.
Make your wire transfer and (optionally) check at
-“@indicateurl{https://exchange:443/reserve/status/reserve_pub=QPE24X}...” whether your
+“@indicateurl{https://exchange:443/reserve/status/reserve_pub=QPE24X}…” whether your
transfer has arrived at the exchange.
Once the funds have arrived, you can start to use the reserve for
@@ -1448,14 +1448,14 @@ options:
@item
@code{--tracks-number=TN} Instructs the tool to perform @emph{TN} tracking
operations. Note that the @strong{total} amount of operations will be two
-times @emph{TN}, since "one" tracking operation accounts for
+times @emph{TN}, since “one” tracking operation accounts for
@code{/track/transaction} and @code{/track/transfer}. This command should
only be used to see if the operation ends without problems, as no
actual measurement of performance is provided (despite of the
’benchmark’ work used in the tool’s name).
@end itemize
-@anchor{17}@w{ }
@anchor{taler-merchant-manual Using-taler_002dconfig}@w{ }
+@anchor{17}@w{ }
@c %**end of body
@bye