commit 4c9dd8ca58633e4f9d63a2d6d994dfd961558389
parent 099a177fe14688f31d5fb7eb5d1683aa14e6929a
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Tue, 11 Nov 2025 15:47:56 +0100
update documentation for mailbox
Diffstat:
| M | core/api-mailbox.rst | | | 252 | ++++++++++++++++++++++++++++++++++++++----------------------------------------- |
1 file changed, 121 insertions(+), 131 deletions(-)
diff --git a/core/api-mailbox.rst b/core/api-mailbox.rst
@@ -28,8 +28,8 @@ 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.
+Mailboxes must be registered along with their public key information.
+Registration may incur costs depending on the mailbox service provider used.
The API specified here follows the :ref:`general conventions <http-common>`
for all details not specified in the individual requests.
@@ -82,16 +82,121 @@ Configuration information
delivery_period: RelativeTime;
// How much is the cost of a single
- // registration period of a mailbox
+ // registration (update) of a mailbox
+ // May be 0 for a free update/registration.
+ registration_update_fee: Amount
+
+ // How much is the cost of a single
+ // registration period (30 days) of a mailbox
// May be 0 for a free registration.
- registration_amount: Amount
+ monthly_fee: Amount
+
+ }
+
+---------------------------------
+Mailbox registration and metadata
+---------------------------------
+
+.. http:get:: /info/$H_MAILBOX
+
+ Endpoint that returns mailbox metadata including signing and encryption keys for ``$H_MAILBOX``.
+
+ **Response**
+
+ :http:statuscode:`200 Ok`:
+ Info is returned in a `MailboxMetadata` response,
+ :http:statuscode:`404 Not Found`:
+ This mailbox is not registered.
+ :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:**
+
+ .. _MailboxMetadata:
+ .. ts:def:: MailboxMetadata
+
+ interface MailboxMetadata {
+
+ // The mailbox signing key.
+ // Note that ``$H_MAILBOX == H(singingKey)``.
+ // Note also how this key cannot be updated
+ // as it identifies the mailbox.
+ // Base32 crockford-encoded.
+ signingKey: string;
- // How long is a registration period
- // a mailbox
- registration_period: RelativeTime
+ // Type of key.
+ // Currently only
+ // EdDSA keys are supported.
+ signingKeyType: "EdDSA";
+
+ // The mailbox encryption key.
+ // This is a HPKE public key
+ // Currently, only the X25519 format
+ // for use in a X25519-DHKEM (RFC 9180)
+ // is supported.
+ // Base32 crockford-encoded.
+ encryptionKey: string;
+
+ // Type of key.
+ // Currently only
+ // X25519 keys are supported.
+ encryptionKeyType: "X25519";
+
+ // Expiration of this mailbox.
+ // Unix epoch (seconds)
+ expiration: Timestamp;
}
+
+.. http:post:: /register
+
+ Requests the registration or update of a mailbox.
+ May be used to update encryption keys.
+ May incur cost.
+ The mailbox identity is given through the keys field
+ in the ``MailboxMetadata`` field.
+
+ **Request**
+
+ The body of the request must be a ``MailboxRegistrationRequest``.
+
+ **Details:**
+
+ .. _MailboxRegistrationRequest:
+ .. ts:def:: MailboxRegistrationRequest
+
+ interface MailboxRegistrationRequest {
+
+ // Keys to add/update for the mailbox.
+ mailbox_metadata: MailboxMetadata;
+
+ // Signature by the mailbox's signing key affirming
+ // the update of keys, of purpose
+ // ``TALER_SIGNATURE_MAILBOX_REGISTER``.
+ // The signature is created over the SHA-512 hash
+ // of (encryptionKeyType||encryptionKey||expiration)
+ // Base32 crockford-encoded.
+ // The signature system is defined through the
+ // signingKeyType in the keys field.
+ signature: string;
+
+ }
+
+ **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.
+ :http:statuscode:`402 Payment Required`
+ Client needs to make a Taler payment before proceeding. See
+ standard Taler payment procedure.
+
----------------
Sending messages
----------------
@@ -166,10 +271,6 @@ Receiving messages
immediately with the messages in the mailbox, and not
wait for additional messages to arrive.
- The header ``Mailbox-Order-Id`` may be provided if the client recently
- paid for this message.
-
-
**Response**
:http:statuscode:`200 Ok`:
@@ -193,15 +294,21 @@ Receiving messages
This allows the caller to select a range of messages starting
from the first message received in the last GET call
to delete.
- FIXME: do not use delete body somehow.
**Request**
- The body of the request must be a `MessageDeletionRequest`_.
The header ``Match-If`` must be set to the ID of the first message
to delete.
+ The ``ETag`` value is retrieved when receiving messages via a GET
+ request.
For example, a ``Match-If`` header value of 2 and a count field of
- 5 will delete messages from ID 2 to 7 (given a valid signature).
+ 5 will delete messages from ID 2 to N such that up to 5 messages are
+ deleted.
+ The ``Taler-Mailbox-Delete-Signature`` header must be set with a
+ Base32-Crockfor encoded signature over four 32 bit values in
+ network byte order: ``NBO(16)||NBO(TALER_SIGNATURE_MAILBOX_DELETE_MESSAGES)||NBO(Etag)||NBO(count)``
+ where ``TALER_SIGNATURE_MAILBOX_DELETE_MESSAGES`` is a signature purpose value registered in
+ GANA.
**Details:**
@@ -214,9 +321,6 @@ Receiving messages
// of the latest GET response).
count: Integer;
- // SHA-512 hash over all messages to delete.
- checksum: HashCode;
-
// Signature by the mailbox's private key affirming
// the deletion of the messages, of purpuse
// ``TALER_SIGNATURE_MAILBOX_DELETE_MESSAGES``.
@@ -237,118 +341,4 @@ Receiving messages
than the number of messages currently in the mailbox.
This response comes with a standard `ErrorDetail` response.
--------------
-Key directory
--------------
-
-.. http:get:: /$H_MAILBOX/info
-
- Endpoint that returns mailbox metadata including signing and encryption keys for ``$H_MAILBOX``.
-
- **Response**
-
- :http:statuscode:`200 Ok`:
- Keys are returned in a `MailboxInfo` response,
- :http:statuscode:`404 Not Found`:
- This mailbox is not registered.
- :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:**
-
- .. _MailboxInfo:
- .. ts:def:: MailboxInfo
-
- interface MailboxInfo {
-
- // Keys to of the mailbox.
- keys: MailboxMessageKeys;
-
- // Expiration of this mailbox.
- // Unix epoch (seconds)
- expiration: Timestamp;
-
- }
-
-
- .. _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.
- // Base32 crockford-encoded.
- signingKey: string;
-
- // Type of key.
- // Currently only
- // EdDSA keys are supported.
- signingKeyType: "EdDSA";
-
- // The mailbox encryption key.
- // This is a HPKE public key
- // Currently, only the X25519 format
- // for use in a X25519-DHKEM (RFC 9180)
- // is supported.
- // Base32 crockford-encoded.
- encryptionKey: string;
-
- // Type of key.
- // Currently only
- // X25519 keys are supported.
- encryptionKeyType: "X25519";
-
- }
-
-
-.. http:post:: /register
-
- Requests the registration or update of a mailbox.
- May be used to update encryption keys.
- May incur cost.
- The mailbox identity is given through the keys field
- in the ``MailboxMessageKeys`` field.
-
- **Request**
-
- The body of the request must be a ``MailboxRegistrationRequest``.
-
- **Details:**
-
- .. _MailboxRegistrationRequest:
- .. ts:def:: MailboxRegistrationRequest
-
- interface MailboxRegistrationRequest {
-
- // Keys to add/update for the mailbox.
- keys: MailboxMessageKeys;
-
- // Signature by the mailbox's signing key affirming
- // the update of keys, of purpose
- // ``TALER_SIGNATURE_MAILBOX_REGISTER``.
- // The signature is created over the SHA-512 hash
- // of (encryptionKeyType||encryptionKey||expiration)
- // Base32 crockford-encoded.
- // The signature system is defined through the
- // signingKeyType in the keys field.
- signature: string;
-
- }
-
- **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.
- :http:statuscode:`402 Payment Required`
- Client needs to make a Taler payment before proceeding. See
- standard Taler payment procedure.
