commit 2e27ed82871a2e67560d843112fbd71c13d248a5
parent fa1e3e5c51b09febec252b5a2d60cdd17f5500eb
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Mon, 10 Nov 2025 10:13:46 +0100
update dd70
Diffstat:
1 file changed, 18 insertions(+), 23 deletions(-)
diff --git a/design-documents/070-alias-directory-mailbox.rst b/design-documents/070-alias-directory-mailbox.rst
@@ -100,7 +100,7 @@ The registration procedure may succeed or fail.
Alice may retry on failure to register the same Alias.
Alice may also register other Aliases.
-.. _dd-13-us-alias-mgmt:
+.. _dd-70-us-alias-mgmt:
Alias Management
----------------
@@ -110,7 +110,7 @@ Alias Management
Alice opens ``Settings -> Aliases`` to manage her aliases.
The UI shows all registered aliases with expiration times.
The UI allows Alice to delete registrations (or disable auto-renewal) and renew a registration pre-emptively before it expires.
-Alice may use this screen to display a QR code of her mailbox URI, see also :ref:`Contacts Management <dd-13-us-contacts-mgmt>`.
+Alice may use this screen to display a QR code (an ``add-contact`` Taler URI) of her own contact, see also :ref:`Contacts Management <dd-70-us-contacts-mgmt>`.
This may require separation into two or three stories.
@@ -126,10 +126,10 @@ Once Bob has entered all necessary details, a payment request (:ref:`DD 13 <dd-1
created and the screen with QR code is shown.
This screen now also allows to send the request to a contact by using the contact list.
The *Request from Contact* screen brings up the contacts list to select a contact.
-Bob may also import a contact here ad-hoc, see :ref:`Contacts Management <dd-13-us-contacts-mgmt>`.
+(Optional): Bob may also import a contact here ad-hoc, see :ref:`Contacts Management <dd-70-us-contacts-mgmt>`.
Bob selects the contact and the request is sent to Alice.
- **Technical Note**: This will trigger the wallet to send the payment request to Alice's Mailbox URI through the :ref:`Mailbox API <api-mailbox>`. The message format is still TBD.
+ **Technical Note**: This will trigger the wallet to send the payment request to Alice's Mailbox URI through the :ref:`Mailbox API <api-mailbox>`.
The request may fail, for example if Alice's Mailbox is full.
@@ -150,21 +150,19 @@ The new payment request by Bob is received by the Wallet and it notifies Alice.
Alice interacts with the notification or manually browses to ``Settings->Mailbox``.
- **TODO**: Does this exist / make sense?
-
There, the wallet provides a screen with payment request overviews (e.g. list of messages
in the local mailbox).
Alice selects Bob's payment request either through the notification or from the list
of payment requests.
-Alice creates a P2P payment based on the metadata in the payment request.
-She may also decline to pay.
+The messages contain Taler URIs, so the application may simply offer to process the respective
+URI as is usually done.
**Note**: When are local messages deleted?
-.. _dd-13-us-contacts-mgmt:
+.. _dd-70-us-contacts-mgmt:
Contacts Management
------------------
+-------------------
Prerequisites: Alice has installed Taler Wallet
@@ -179,7 +177,7 @@ Alice selects the Alias type (e.g. GitHub or Email) and inputs a contacts Alias.
If no results were found, Alice cannot import this contact.
If found, Alice will be able to import this contact into the contact list.
-Alternatively, the contact can also be imported using a QR code, see :ref:`Alias Management <dd-13-us-alias-mgmt>`.
+Alternatively, the contact can also be imported using an ``add-contact`` Taler URI, see :ref:`Alias Management <dd-70 -us-alias-mgmt>`.
**Technical Note**: The wallet periodically performs lookups for contacts where their Taldir registrations have expired and refresh accordingly.
@@ -198,7 +196,7 @@ This screen now also allows to send the request to a contact by using the contac
Bob selects *Send to Contact*.
The *Send to Contact* screen brings up the contacts list to select a contact.
- **Note**: At this point, Bob may now also import a contact here ad-hoc, see :ref:`Contacts Management <dd-13-us-contacts-mgmt>`.
+ **Note**: At this point, Bob may now also import a contact here ad-hoc, see :ref:`Contacts Management <dd-70-us-contacts-mgmt>`.
Bob selects the contact and the payment offer is sent to Alice.
@@ -217,8 +215,7 @@ Bob may want to resend a payment request if it expired or if Alice lost the requ
**Technical Note**: This does not mean that the request can get lost in transit. It means that it is possible that Alice lost her phone and needed to setup her Wallet again.
-Bob opens ``Settings->Mailbox`` and selects a payment request he wants to send again.
-Bob can initiate to resend this payment request with a button.
+Bob opens the open payment request and selects the contact to send it to again.
**Technical Note**: This likely implies the creation of a new payment request, with the same detail of the already sent request. Sending the same request again is probably not a good idea. This, however, requires a new field to the contract terms (``idempotency_nonce``?) that we keep identical between both requests. That way, the receiving wallet can detect that it is a duplicate and act accordingly --- if already paid, ignore, if hard-rejected/banned ignore, and if merely expired show again.
@@ -227,11 +224,6 @@ Open Questions
==============
- - Payment Request Message unspecified. We should probabl use :ref:`DD 13 <dd-13>` but it seems outdated? Whatever is used for NFC/QR could be used in a message.
- - Requests should probably be encrypted (HPKE?)
- - For encryption, the registered Mailbox URI should/must include a hint what public to use for encryption. This should probably not be the EdDSA public key of the wallet because we should not reuse the signing key for the KEM in the HPKE.
- We may be able to use a query parameter to the mailbox URI (``$MAILBOX_SERVER/$H_ADDRESS#hpke_pk=Base32(pk)``) used in the Taldir registration.
-
Proposed Solution
=================
@@ -262,10 +254,13 @@ The first two bytes of the message are 16 bit unsigned integers
in network byte order that specify the message type.
The remaining bytes contain the encrypted message (including the MAC).
Messages are encrypted using HPKE (X25519 with ChaChaPoly1305 as AEAD).
-This means that the encrypted message payload also contains a 32 byte
-encapsulation as well as a 16 byte MAC.
-
-The plaintext payload of messages is defined as follows:
+Currently, there is only a single message type that carries a taler URI as payload.
+This type is identified by the bytes ``0x00 0x00``.
+This message type number is in network byte order prefixed before the HPKE ciphertext.
+The HPKE ciphertext starts with a 32 byte
+encapsulation followed by the encrypted URI.
+The encrypted URI is followed by a 16 byte MAC.
+The message type is part of the MAC (the additional data portion of the AEAD scheme).
Wire format MailboxMessage:
