Exchange

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:

_images/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:

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:

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:

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.