From 27da1e18bd406c21642831433ac9e54b0ef21f4e Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 3 Jul 2022 11:55:57 +0200 Subject: add mailbox api spec --- core/api-exchange.rst | 6 +- core/api-mailbox.rst | 253 ++++++++++++++++++++++++++++++++++++++++++++++++++ core/index.rst | 1 + 3 files changed, 257 insertions(+), 3 deletions(-) create mode 100644 core/api-mailbox.rst (limited to 'core') diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 1223086d..85d8e3a7 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -2537,7 +2537,7 @@ denomination. // `coin's private key `. coin_sig: EddsaSignature; } - + The deposit operation succeeds if the coin is valid for making a deposit and has enough residual value that has not already been deposited or melted. @@ -2572,7 +2572,7 @@ denomination. } .. ts:def:: DepositConfirmationSignature - + interface DepositConfirmationSignature { // The EdDSA signature of `TALER_DepositConfirmationPS` using a current // `signing key of the exchange ` affirming the successful @@ -2581,7 +2581,7 @@ denomination. exchange_sig: EddsaSignature; } - + ---------- Refreshing ---------- diff --git a/core/api-mailbox.rst b/core/api-mailbox.rst new file mode 100644 index 00000000..25c9cd87 --- /dev/null +++ b/core/api-mailbox.rst @@ -0,0 +1,253 @@ +.. + 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 + + @author Christian Grothoff + + +======================= +The Mailbox RESTful API +======================= + +This is a proposed API 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. + +The API specified here follows the :ref:`general conventions ` +for all details not specified in the individual requests. +The `glossary `_ +defines all specific terms used in this section. + +-------------------- +Terms of service API +-------------------- + +These APIs allow wallets to obtain the terms of service +and the privacy policy of the Mailbox. + +.. http:get:: /terms + + Get the terms of service of the Mailbox. + The Mailbox will consider the "Accept" and "Accept-Language" and + "Accept-Encoding" headers when generating a response. Specifically, + it will try to find a response with an acceptable mime-type, then + pick the version in the most preferred language of the user, and + finally apply compression if that is allowed by the client and + deemed beneficial. + + The Mailbox will set an "Etag", and subsequent requests of the + same client should provide the tag in an "If-None-Match" header + to detect if the terms of service have changed. If not, a + "204 Not Modified" response will be returned. + + If the "Etag" is missing, the client should not cache the response and + instead prompt the user again at the next opportunity. This is usually only + the case if the terms of service were not configured correctly. + + +.. http:get:: /privacy + + Get the privacy policy of the Mailbox. + The Mailbox will consider the "Accept" and "Accept-Language" and + "Accept-Encoding" headers when generating a response. Specifically, + it will try to find a response with an acceptable mime-type, then + pick the version in the most preferred language of the user, and + finally apply compression if that is allowed by the client and + deemed beneficial. + + The Mailbox will set an "Etag", and subsequent requests of the + same client should provide the tag in an "If-None-Match" header + to detect if the privacy policy has changed. If not, a + "204 Not Modified" response will be returned. + + If the "Etag" is missing, the client should not cache the response and + instead prompt the user again at the next opportunity. This is usually only + the case if the privacy policy was not configured correctly. + + +------------------------- +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; + + // How long will the service store a message + // before giving up on delivery? + delivery_period: Duration; + + } + +---------------- +Sending messages +---------------- + +.. http:post:: /$H_MAILBOX + + Puts a message into ``$H_MAILBOX``. + ``$H_MAILBOX`` is the SHA512 of an EdDSA public key. + + **Request** + + The body of the request must be an `IdentityMessage`. + + **Response** + + :http:statuscode:`204 No Content` + Message was stored and will be delivered. + :http:statuscode:`402 Payment Required` + Client needs to make a Taler payment before proceeding. See + standard Taler payment procedure. + :http:statuscode:`403 Forbidden` + The specified ``order_id`` does not permit sending + of this message. Possible reaons 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`_. + + **Details:** + + .. _IdentityMessage: + .. ts:def:: IdentityMessage { + // Public DH key used to encrypt the body. Must be fresh + // and only used once (ephemeral). + ephemeral_key: EcdhePublicKey; + + // Encrypted message. Must be exactly 256-32 bytes long. + body: string; + + // Order ID, if the client recently paid for this message. + order_id?: string; + } + + .. _MailboxRateLimitedResponse: + .. ts:def:: MailboxRateLimitedResponse + + interface MailboxRateLimitedResponse { + + // Taler error code, TALER_EC_MAILBOX_DELIVERY_RATE_LIMITED. + code: number; + + // 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. + + **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!). + + **Request** + + The body of the request must be a ``MessageDeletionRequest``. + + **Details:** + + .. _MessageDeletionRequest: + .. ts:def:: MessageDeletionRequest { + + // Number of messages to delete. (Starting from the beginning + // of the latest GET response). + count: Integer; + + // SHA-512 hash over all messages to delete. + checksum: Hash; + + // Signature by the mailbox's private key affirming + // the deletion of the messages, of purpuse + // ``TALER_SIGNATURE_WALLET_MAILBOX_DELETE_MESSAGES``. + wallet_sig: EddsaSignature; + + } + + **Response** + + :http:statuscode:`204 No Content`: + Deletion complete. + :http:statuscode:`403 Forbidden`: + The ``wallet_sig`` 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. diff --git a/core/index.rst b/core/index.rst index b54e48e3..f44bc247 100644 --- a/core/index.rst +++ b/core/index.rst @@ -36,6 +36,7 @@ interfaces between the core components of Taler. api-auditor api-sync api-taldir + api-mailbox api-wire api-bank-merchant api-bank-integration -- cgit v1.2.3