taler-docs

api-mailbox.rst (11756B)

---

 ..
   This file is part of GNU TALER.
   Copyright (C) 2022 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU Affero General Public License as published by the Free Software
   Foundation; either version 2.1, or (at your option) any later version.
 
   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
 
   You should have received a copy of the GNU Affero General Public License along with
   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
 
   @author Christian Grothoff
 
 .. _api-mailbox:
 
 ===================
 Mailbox RESTful API
 ===================
 
 This is the API documentation for the GNU Taler Mailbox service which allows Taler
 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>`_.
 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.
 The `glossary <https://docs.taler.net/taler-developer-manual.html#developer-glossary>`_
 defines all specific terms used in this section.
 
 .. contents:: Table of Contents
   :local:
 
 .. include:: tos.rst
 
 -------------------------
 Configuration information
 -------------------------
 
 .. http:get:: /config
 
   Return the protocol version and currency supported by this service.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The body is a `VersionResponse`.
 
   **Details:**
 
   .. ts:def:: VersionResponse
 
     interface VersionResponse {
       // libtool-style representation of the Merchant protocol version, see
       // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
       // The format is "current:revision:age".
       version: string;
 
       // Name of the protocol.
       name: "taler-mailbox";
 
       // Fee per message.
       message_fee: Amount;
 
       // Fixed size of message body.
       message_body_bytes: Integer;
 
       // Maximum number of messages in a
       // single response.
       message_response_limit: Integer;
 
       // How long will the service store a message
       // before giving up on delivery?
       delivery_period: RelativeTime;
 
       // How much is the cost of a single
       // 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.
       monthly_fee: Amount
 
       // How much is the cost to send a single
       // message to a mailbox.
       // May be 0 for free message sending.
       message_fee: Amount
 
       // How many messages can be send and
       // are stored by the service for free.
       // After the quota is reached, the
       // regular message_fee applies.
       // May be 0 for no free quota.
       free_message_quota: Integer
 
     }
 
 ---------------------------------
 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(signing_key)``.
       // Note also how this key cannot be updated
       // as it identifies the mailbox.
       // Base32 crockford-encoded.
       signing_key: string;
 
       // Type of key.
       // Currently only
       // EdDSA keys are supported.
       signing_key_type: "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.
       encryption_key: string;
 
       // Type of key.
       // Currently only
       // X25519 keys are supported.
       encryption_key_type: "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
       // signing_key_type 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
 ----------------
 
 .. http:post:: /$H_MAILBOX
 
   Puts a message into ``$H_MAILBOX``.
   ``$H_MAILBOX`` is the SHA512 of an EdDSA public key.
 
   **Request**
 
   The content of the request must be the message with a size of
   exactly message_body_bytes (see `VersionResponse`).
 
   **Response**
 
   :http:statuscode:`204 No Content`
      Message was stored and will be delivered.
   :http:statuscode:`403 Forbidden`
      The specified order ID in the ``Mailbox-Order-Id`` header does not
      permit sending of this message. Possible reasons include the order
      being for a different message, unpaid or
      malformed.
      This response comes with a standard `ErrorDetail` response.
   :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`_.
   :http:statuscode:`402 Payment Required`
      Client needs to make a Taler payment before proceeding. See
      standard Taler payment procedure.
 
 
   **Details:**
 
   .. _MailboxRateLimitedResponse:
   .. ts:def:: MailboxRateLimitedResponse
 
     interface MailboxRateLimitedResponse {
 
       // Taler error code, TALER_EC_MAILBOX_DELIVERY_RATE_LIMITED.
       code: Integer;
 
       // When the client should retry.
       retry_delay: RelativeTime;
 
       // The human readable error message.
       hint: string;
 
     }
 
 ------------------
 Receiving messages
 ------------------
 
 .. http:get:: /$H_MAILBOX
 
   Endpoint that returns unread messages in ``$H_MAILBOX``.
   The number of messages returned by the service can be limited.
   If the request is simply repeated, the same messages will be
   returned again (or possibly more if additional messages arrived
   and the total number is below the service's current internal limit).
   To receive additional messages, the client generally has to first
   explicitly delete already downloaded messages from the mailbox.
   If messages are returned, the ``ETag`` header will be set
   containing the ID of the first message
   for use in any potential delete requests that require the message ID.
 
   **Request:**
 
   :query timeout_ms=NUMBER: *Optional.*  If specified,
     the Mailbox service will wait up to ``NUMBER``
     milliseconds for the arrival of new messages
     before sending the HTTP response.  Note that if the
     mailbox is non-empty, the service will always return
     immediately with the messages in the mailbox, and not
     wait for additional messages to arrive.
 
   **Response**
 
   :http:statuscode:`200 Ok`:
     Messages are returned in binary format, 256 bytes per message,
     starting with the ephemeral key and followed by
     the encrypted body. Messages are not encapsulated in JSON!
   :http:statuscode:`204 No Content`:
     The mailbox is empty.
   :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`_.
 
 .. http:delete:: /$ADDRESS
 
   Requests the deletion of already received messages from the
   mailbox. Here, ``$ADDRESS`` must be the EdDSA public key
   of the mailbox (not the hash!).
   The ``ETag`` header returned by a GET request for messages
   returns the ID for the first message received.
   This allows the caller to select a range of messages starting
   from the first message received in the last GET call
   to delete.
 
   **Request**
 
   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 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.
 
   :query count=NUMBER: *Optional.*  If specified,
     the Mailbox service will delete up to ``NUMBER``
     of new messages starting from the ID provided
     in ``Match-If``.
     If the parameter is not provided, only a single
     message will be deleted.
 
 
   **Details:**
 
   .. _MessageDeletionRequest:
   .. ts:def:: MessageDeletionRequest
 
     interface MessageDeletionRequest {
 
       // Number of messages to delete. (Starting from the beginning
       // of the latest GET response).
       count: Integer;
 
       // Signature by the mailbox's private key affirming
       // the deletion of the messages, of purpuse
       // ``TALER_SIGNATURE_MAILBOX_DELETE_MESSAGES``.
       signature: string;
 
     }
 
   **Response**
 
   :http:statuscode:`204 No Content`:
      Deletion complete.
   :http:statuscode:`403 Forbidden`:
      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.