taler-docs

commit bec63dd3c67ae6b6a658811061014240033bbda8
parent 2898af2abf088209361c92fd91e806e05bf612a9
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date:   Wed,  5 Nov 2025 09:47:16 +0100

update mailbox API with key directory

Diffstat:
M
core/api-mailbox.rst
 | 
101
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--

1 file changed, 99 insertions(+), 2 deletions(-)
diff --git a/core/api-mailbox.rst b/core/api-mailbox.rst
@@ -25,6 +25,12 @@ This is the API documentation for the GNU Taler Mailbox service which allows Tal
 wallets to securely send push and pull payment requests to other wallets
 without having to interact with the respective messaging service.
 
+Clients (wallets) are expected to generate mailbox keys that uniquely identify
+a mailbox as well as encryption keys that can be used to encrypt messages for
+the mailbox (e.g. `HPKE <https://www.rfc-editor.org/rfc/rfc9180.html>`.
+Mailbox signing keys are usable implicity, but encryption keys must be generated
+and put into the key directory.
+
 The API specified here follows the :ref:`general conventions <http-common>`
 for all details not specified in the individual requests.
 The `glossary <https://docs.taler.net/taler-developer-manual.html#developer-glossary>`_
@@ -193,7 +199,7 @@ Receiving messages
       // Signature by the mailbox's private key affirming
       // the deletion of the messages, of purpuse
       // ``TALER_SIGNATURE_WALLET_MAILBOX_DELETE_MESSAGES``.
-      wallet_sig: EddsaSignature;
+      signature: EddsaSignature;
 
     }
 
@@ -202,10 +208,101 @@ Receiving messages
   :http:statuscode:`204 No Content`:
      Deletion complete.
   :http:statuscode:`403 Forbidden`:
-     The ``wallet_sig`` is invalid.
+     The ``signature`` is invalid.
      This response comes with a standard `ErrorDetail` response.
   :http:statuscode:`404 Not found`:
      The checksum does not match the messages currently at the
      head of the mailbox, or ``count`` is larger
      than the number of messages currently in the mailbox.
      This response comes with a standard `ErrorDetail` response.
+
+-------------
+Key directory
+-------------
+
+.. http:get:: /keys/$H_MAILBOX
+
+  Endpoint that returns signing and encryption keys for ``$H_MAILBOX``.
+
+  **Response**
+
+  :http:statuscode:`200 Ok`:
+    Keys are returned in a `MailboxMessageKeys` response,
+  :http:statuscode:`204 No Content`:
+    The mailbox has no keys configured.
+  :http:statuscode:`429 Too Many Requests`:
+    The system is currently experiencing a too high request
+    load and is unable to accept the message for delivery.
+    The response format is given by `MailboxRateLimitedResponse`_.
+
+
+  **Details:**
+
+  .. _MailboxMessageKeys:
+  .. ts:def:: MailboxMessageKeys
+
+    interface MailboxMessageKeys {
+
+      // The mailbox signing key.
+      // Note that ``$H_MAILBOX == H(singingKey)``.
+      // Note also how this key cannot be updated
+      // as it identifies the mailbox.
+      signingKey: EddsaKey;
+
+      // Type of key.
+      // Optional, as currently only
+      // EdDSA keys are supported.
+      signingKeyType?: "EdDSA";
+
+      // The mailbox encryption key.
+      // This is an HPKE public key
+      // in the X25519 format for use
+      // in a X25519-DHKEM (RFC 9180).
+      // Base32 crockford-encoded.
+      encryptionKey: string;
+
+      // Type of key.
+      // Optional, as currently only
+      // X25519 keys are supported.
+      encryptionKeyType?: "X25519";
+
+      // Expiration of this mapping.
+      expiration: Timestamp;
+
+    }
+
+
+.. http:post:: /keys
+
+  Requests the update of the encryption key for the mailbox.
+
+  **Request**
+
+  The body of the request must be a ``KeyUpdateRequest``.
+
+  **Details:**
+
+  .. _KeyUpdateRequest:
+  .. ts:def:: KeyUpdateRequest
+
+    interface KeyUpdateRequest {
+
+      // Keys to add/update for a mailbox.
+      keys: MailboxMessageKeys;
+
+      // Signature by the mailbox's signing key affirming
+      // the update of keys, of purpuse
+      // ``TALER_SIGNATURE_WALLET_MAILBOX_UPDATE_KEYS``.
+      // The signature is created over the SHA-512 hash
+      // of (encryptionKeyType||encryptionKey||expiration)
+      signature: EddsaSignature;
+
+    }
+
+  **Response**
+
+  :http:statuscode:`204 No Content`:
+     Update/creation complete.
+  :http:statuscode:`403 Forbidden`:
+     The ``signature`` is invalid.
+     This response comes with a standard `ErrorDetail` response.