diff options
author | Christian Grothoff <christian@grothoff.org> | 2017-04-08 19:54:12 +0200 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2017-04-08 19:54:12 +0200 |
commit | 47d03e227af8ef3b81cb7ee1ff991e99208e0e3e (patch) | |
tree | 4871d84d415f916d7659f333c67a8cd31e2ff438 | |
parent | 2948254d49a550b454899c74a8a61c30b644532a (diff) | |
download | exchange-47d03e227af8ef3b81cb7ee1ff991e99208e0e3e.tar.xz |
document denomination key revocation file format
-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 |