summaryrefslogtreecommitdiff
path: root/impl-mint.rst
blob: ed6d627d7da954314356ca3226be6a0f552d792d (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
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
===================================
The Mint Reference Implementation
===================================

----------------------
The Configuration File
----------------------

The section `[mint]` contains various global options for the mint:

* `master_public_key`: Must specify the mint's master public key.
* `wireformat`: The wireformat supported by the mint (i.e. "SEPA")
* `currency`: The currency supported by the mint (i.e. "EUR")


^^^^^^^^^^^^^^^^^^^^^^
Key Management Options
^^^^^^^^^^^^^^^^^^^^^^

The command line tool `taler-mint-keyup` updates the signing key and list of denominations offered by the mint.  This process requires the mint's master key, and should be done offline in order to protect the master key.  For this, `taler-mint-keyup` uses additional configuration options.

The section `[mint_keys]` containts the following entries:

* `signkey_duration`: How long should one signing key be used?
* `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.


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:

* `value`: How much is the coin worth, the format is CURRENCY:VALUE.FRACTION.  For example, a 10 cent piece is "EUR:0.10".
* `duration_withdraw`: How long can a coin of this type be withdrawn?  This limits the losses incured by the mint when a denomination key is compromised.
* `duration_overlap`: What is the overlap of the withdrawal timespan for this coin type?
* `duration_spend`: How long is a coin of the given type valid?  Smaller values result in lower storage costs for the mint.
* `fee_withdraw`: What does it cost to withdraw this coin? Specified using the same format as `value`.
* `fee_deposit`: What does it cost to deposit this coin? Specified using the same format as `value`.
* `fee_refresh`: What does it cost to refresh this coin? Specified using the same format as `value`.
* `rsa_keysize`: How many bits should the RSA modulus (product of the two primes) have for this type of coin.


------------------
Reserve management
------------------

Incoming transactions to the mint's provider result in the creation or update of reserves, identified by their withdrawal key.

The command line tool `taler-mint-reservemod` allows create and add money to reserves in the mint's database.


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

  .. note::

     This documentation is outdated (no bug number yet either).


.. sourcecode:: postgres

  CREATE TABLE purses (
    -- The customer's withdraw public key for the purse.
    withdraw_pub     BYTEA PRIMARY KEY,

    -- Purse balance (value part).
    balance_value    INT4 NOT NULL,

    -- Purse balance (fractional part).
    balance_fraction INT4 NOT NULL,

    -- Purse balance (fractional).
    balance_currency VARCHAR(4),

    -- Expiration time stamp for the purse.
    expiration       INT8,

    -- The blinding key (public part) for the purse, can be NULL
    -- if funds are insufficient or the mint has not
    -- generated it yet.
    blinding_pub        BYTEA,

    -- The blinding key (private part).
    blinding_priv       BYTEA,

    -- Key that was used to create the last signature on the
    -- purse status
    status_sign_pub     BYTEA,

    -- Cached status signature
    status_sig          BYTEA
  );


.. sourcecode:: postgres

  CREATE TABLE collectable_blindcoins (
    -- The public part of the blinding key.
    -- Note that this is not a foreign key,
    -- as the blinding key is removed from the purse
    -- table once a coin has been requested with it.
    -- Furthermore, the private part is not required
    -- anymore.
    blind_pub bytea   PRIMARY KEY,

    -- The coin blank provided by the customer.
    blind_blank_coin  BYTEA,

    -- Signature over the minting request by the customer.
    customer_sig      BYTEA,

    -- The signed blind blank coin.
    blind_signed_coin BYTEA,

    -- The denomination public key used to sign the
    -- blind signed coin.
    denom_pub         BYTEA,

    -- The purse that requested the minting of this
    -- coin.
    withdraw_pub      BYTEA REFERENCES purses(withdraw_pub)
  );


The table `coins` stores information about coins known to the mint.

.. sourcecode:: postgres

  CREATE TABLE coins (
    denom_pub BYTEA NOT NULL,
    denom_sig BYTEA NOT NULL,
    coin_pub BYTEA NOT NULL,

    -- melting session, or NULL if not melted
    melt_session BYTEA,

    -- remaining value of the coin
    balance_currency int4,
    balance_value int4,
    balance_fraction int4,

    -- lock id, not NULL if not locked
    lock int
  );

The following tables are used for refreshing.

.. sourcecode:: postgres

  CREATE TABLE refresh_sessions (
    session_pub BYTEA,
    order_sig BYTEA,
    index_reveal INT2,
  );

  CREATE TABLE refresh_melt (
    session_pub BYTEA REFERENCES refresh_sessions (session_pub),
    session_sig BYTEA,
    denom_pub BYTEA,
    denom_sig BYTEA,
    coin_pub BYTEA,
    coin_sig BYTEA,
  );

  -- create links to old coins
  CREATE TABLE refresh_link_commits (
    session_pub BYTEA,
    session_sig BYTEA,
    coin_pub BYTEA,
    transfer_pub BYTEA,
    link_secret_enc BYTEA,
    link_secret_hash BYTEA,
    idx INTEGER
  );

  CREATE TABLE refresh_order (
    -- EdDSA public key of the melting session
    session_pub BYTEA REFERENCES refresh_sessions (session_pub),
    -- denomination key for the newly ordered coin
    denom_pub BYTEA,
    -- signature from session key over coin order
    session_sig BYTEA,
  );

  CREATE TABLE refresh_coin_commits (
    session_pub BYTEA,
    idx INTEGER,
    coin_link_enc BYTEA,
    -- The blinding key (public part) for the purse, can be NULL
    -- if funds are insufficient or the mint has not
    -- generated it yet.
    blinding_pub        BYTEA,

    -- The blinding key (private part).
    blinding_priv       BYTEA,
    -- The coin blank provided by the customer.
    blind_blank_coin  BYTEA,
    -- encrypted stuff
    coin_link_enc BYTEA,
  );


------------------
Key Storage Format
------------------

The mint's key directory contains the two subdirectories `signkeys` and `coinkeys`.

The directory `signkeys` contains signkey files, where the name is the start date of the respective key.

The `coinkeys` directory additionaly contains a subdirectory for each coin type alias.  These contain coinkey files, where the name is again the start timestamp of the respective key.