diff options
| -rw-r--r-- | doc/taler-exchange.texi | 38 |
1 files changed, 37 insertions, 1 deletions
diff --git a/doc/taler-exchange.texi b/doc/taler-exchange.texi index 350174f03..8aa88c6af 100644 --- a/doc/taler-exchange.texi +++ b/doc/taler-exchange.texi @@ -1000,7 +1000,6 @@ struct TALER_EXCHANGEDB_PrivateSigningKeyInformationP @{ @node Denomination key storage @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 @@ -1035,6 +1034,43 @@ This is then followed by the variable-size RSA private key in libgcrypt's S-expression format, which can be decoded using @cite{GNUNET_CRYPTO_rsa_private_key_decode()}. +@menu +* Revocations:: +@end menu + +@node Revocations +@subsection Revocations + +@cindex payback +@cindex revocation +When an exchange goes out of business or detects that the private +key of a denomination key pair has been compromised, it may revoke +some or all of its denomination keys. At this point, the hashes +of the revoked keys must be returned as part of the @code{/keys} response +under ``payback''. Wallets detect this, and then return unspent +coins of the respective denomination key using the @code{/payback} +API. + +When a denomination key is revoked, a revocation file is placed +into the respective subdirectory of ``denomkeys/''. The file has the +same prefix as the file that stores the +@cite{struct TALER_EXCHANGEDB_DenominationKeyInformationP} information, +but is followed by the ``.rev'' suffix. It contains a 64-byte +EdDSA signature made with the master key of the exchange with purpose +@code{TALER_SIGNATURE_MASTER_DENOMINATION_KEY_REVOKED}. If such a file +is present, the exchange must check the signature and if it is valid +treat the respective denomination key as revoked. + +Revocation files can be generated using the +@code{taler-exchange-keyup} command-line tool using the @code{-r} +option. The Taler auditor will instruct operators to generate +revocations if it detects a key compromise (which is possible more +coins of a particular denomination were deposited than issued). + +It should be noted that denomination key revocations should only happen +under highly unusual (``emergency'') conditions and not under normal +conditions. + @node Auditor signature storage @section Auditor signature storage |