document auditor information we will provide in /keys

1 files changed, 13 insertions, 0 deletions

diff --git a/api-mint.rst b/api-mint.rst
index 5abaf2ee..2fcce10a 100644
--- a/api-mint.rst
+++ b/api-mint.rst
@@ -109,6 +109,7 @@ from auditors, and the auditor keys should be hard-coded into the wallet as they
   :>json base32 master_public_key: EdDSA master public key of the mint, used to sign entries in `denoms` and `signkeys`
   :>json list denoms: A JSON list of denomination descriptions.  Described below in detail.
   :>json date list_issue_date: The date when the denomination keys were last updated.
+  :>json list auditors: A JSON list of the auditors of the mint. Described below in detail.
   :>json list signkeys: A JSON list of the mint's signing keys.  Described below in detail.
   :>json base32 eddsa_sig: compact EdDSA signature_ (binary-only) over the SHA-512 hash of the concatenation of all SHA-512 hashes of the RSA denomination public keys in `denoms` (in the same order as they were in `denoms`).  Note that for hashing, the binary format of the RSA public keys is used, and not their base32_ encoding.  Wallets cannot do much with this signature by itself; it is only useful when multiple clients need to establish that the mint is cheating (with respect to end-user anonymity) by giving disjoint denomination keys to different users.  If a mint were to do this, this signature allows the clients to demonstrate to the public that the mint is dishonest.
   :>json base32 eddsa_pub: public EdDSA key of the mint that was used to generate the signature.  Should match one of the mint's signing keys from /keys. (Given explicitly as the client might otherwise be confused by clock skew as to which signing key was used.)
@@ -137,6 +138,18 @@ from auditors, and the auditor keys should be hard-coded into the wallet as they
   :>jsonarr date stamp_expire: Expiration date for the signing key.
   :>jsonarr base32 master_sig:  A signature_ (binary-only) with purpose `TALER_SIGNATURE_MASTER_SIGNING_KEY_VALIDITY` over the `key` and `stamp_expire` by the mint master key.
 
+  An entry in the `auditors` list is a JSON object with the following fields:
+
+  :>jsonarr base32 auditor_pub: The auditor's EdDSA signing public key.
+  :>jsonarr base32 auditor_sig: A signature_ (binary-only) with purpose `TALER_SIGNATURE_AUDITOR_MINT_KEYS` over the mint's public key and the denomination keys. To verify the signature, the information from `denomination_keys` must be combined with the information from `denoms`.
+  :>jsonarr array denomination_keys: An array of denomination keys the auditor affirms with its signature. Note that the message only includes the hash of the public key, while the signature is actually over the expanded information including expiration times and fees.  The exact format is described below.
+
+  An entry in the `denomination_keys` list is a JSON object with the following field:
+
+  :>jsonarr base32 denom_pub_h: hash of the public RSA key used to sign coins of the respective denomination.  Note that the auditor's signature covers more than just the hash, but this other information is already provided in `denoms` and thus not repeated here.
+
+  The same auditor may appear multiple times in the array (i.e. for different subsets of denomination keys) and the same denomination key hash may be listed multiple times for the same or different auditors.  The wallet or merchant just should check that the denomination keys they use are in the set for at least one of the auditors that they accept.
+
   .. note::
 
     Both the individual denominations *and* the denomination list is signed,