[GNUnet-SVN] [taler-exchange] branch master updated: document denomination key revocation file format

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository exchange.

The following commit(s) were added to refs/heads/master by this push:
     new 47d03e2  document denomination key revocation file format
47d03e2 is described below

commit 47d03e227af8ef3b81cb7ee1ff991e99208e0e3e
Author: Christian Grothoff <address@hidden>
AuthorDate: Sat Apr 8 19:54:12 2017 +0200

    document denomination key revocation file format
---
 doc/taler-exchange.texi | 38 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/doc/taler-exchange.texi b/doc/taler-exchange.texi
index 350174f..8aa88c6 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()}.
 
address@hidden
+* Revocations::
address@hidden menu
+
address@hidden Revocations
address@hidden Revocations
+
address@hidden payback
address@hidden 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
address@hidden 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
address@hidden  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
address@hidden 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

-- 
To stop receiving notification emails like this one, please contact
address@hidden