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 general conventions for all details not specified in the individual requests. The glossary defines all specific terms used in this section.
These APIs allow clients to obtain the terms of service and the privacy policy of a service.
GET /terms¶Get the terms of service of the service. The endpoint 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 endpoint 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 “304 Not Modified” response will be returned. Note that the “304 Not Modified” will also be returned if the client changed the “Accept-Language” or “Accept-Encoding” header. Thus, if the client would like to download the resource in a different language or format, the “If-None-Match” header must be omitted.
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.
When returning a full response (not a “304 Not Modified”), the server should also include a “Acceptable-Languages” header which includes a space-separated list of the languages in which the terms of service are available in. Clients can use this to generate a language switcher for users that may not have expressed a proper language preference.
GET /privacy¶Get the privacy policy of the service. Behaves the same way as The “/terms” endpoint, except that it returns the privacy policy instead of the terms of service.
GET /config¶Return the protocol version and currency supported by this service.
Response:
Details:
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: RelativeTime;
}
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
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.Details:
interface 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;
}
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;
}
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:
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
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:
interface 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: HashCode;
// 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
wallet_sig is invalid.
This response comes with a standard ErrorDetail response.count is larger
than the number of messages currently in the mailbox.
This response comes with a standard ErrorDetail response.