summaryrefslogtreecommitdiff
path: root/dev-exchange.rst
blob: 91278ee79cf90527dccdca2adc2150c4d94eb866 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
..
  This file is part of GNU TALER.
  Copyright (C) 2014, 2015, 2016 INRIA

  TALER is free software; you can redistribute it and/or modify it under the
  terms of the GNU General Public License as published by the Free Software
  Foundation; either version 2.1, or (at your option) any later version.

  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License along with
  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>

  @author Christian Grothoff
  @author Marcello Stanisci

========
Exchange
========

.. _keys-duration:

-------------
Keys duration
-------------

`signkeys`. The option `lookahead_sign` is such that, being `t` the time when `taler-exchange-keyup`
is run, `taler-exchange-keyup` will generate `n` `signkeys`, where `t + (n * signkey_duration) = t +
lookahead_sign`. In other words, we generate a number of keys which is sufficient to cover a period of
`lookahead_sign`. As for the starting date, the first generated key will get a starting time of `t`,
and the `j`-th key will get a starting time of `x + signkey_duration`, where `x` is the starting time
of the `(j-1)`-th key.

`denom keys`. The option `lookahead_sign` is such that, being `t` the time when `taler-exchange-keyup`
is run, `taler-exchange-keyup` will generate `n` `denom keys` for each denomination, where
`t + (n * duration_withdraw) = t + lookahead_sign`. In other words, for each denomination, we generate a
number of keys which is sufficient to cover a period of `lookahead_sign`. As for the starting date, the
first generated key will get a starting time of `t`, and the `j`-th key will get a starting time of
`x + duration_withdraw`, where `x` is the starting time of the `(j-1)`-th key.



---------------
Database Scheme
---------------

The exchange database must be initialized using `taler-exchange-dbinit`.  This
tool creates the tables required by the Taler exchange to operate.  The
tool also allows you to reset the Taler exchange database, which is useful
for test cases but should never be used in production.  Finally,
`taler-exchange-dbinit` has a function to garbage collect a database,
allowing administrators to purge records that are no longer required.

The database scheme used by the exchange look as follows:

.. image:: exchange-db.png


-------------------
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
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`:

.. sourcecode:: c

  struct TALER_EXCHANGEDB_PrivateSigningKeyInformationP {
     struct TALER_ExchangePrivateKeyP signkey_priv;
     struct TALER_ExchangeSigningKeyValidityPS issue;
  };

------------------------
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
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 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 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 change, even if the
denomination remains the same.

Within this subdirectory, each file represents a particular
denomination key.  The filename is the starting time at which the
signing key can be used in microseconds since the Epoch.  The
format on disk begins with a
`struct TALER_EXCHANGEDB_DenominationKeyInformationP` giving
the attributes of the denomination key and the associated
signature with the exchange's long-term offline key:

.. sourcecode:: c

  struct TALER_EXCHANGEDB_DenominationKeyInformationP {
    struct TALER_MasterSignatureP signature;
    struct TALER_DenominationKeyValidityPS properties;
  };

This is then followed by the variable-size RSA private key in
libgcrypt's S-expression format, which can be decoded using
`GNUNET_CRYPTO_rsa_private_key_decode()`.

-------------------------
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 of the files in this directory.

Each file must contain a header with the public key information
of the auditor, the master public key of the exchange, and
the number of signed denomination keys:

.. sourcecode:: c

  struct AuditorFileHeaderP {
    struct TALER_AuditorPublicKeyP apub;
    struct TALER_MasterPublicKeyP mpub;
    uint32_t dki_len;
  };

This is then followed by `dki_len` signatures of the auditor of type
`struct TALER_AuditorSignatureP`, which are then followed by another
`dki_len` blocks of type `struct TALER_DenominationKeyValidityPS`.
The auditor's signatures must be signatures over the information of
the corresponding denomination key validity structures embedded in a
`struct TALER_ExchangeKeyValidityPS` structure using the
`TALER_SIGNATURE_AUDITOR_EXCHANGE_KEYS` purpose.