api-mailbox.rst (12256B)
1 .. 2 This file is part of GNU TALER. 3 Copyright (C) 2022 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 2.1, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 16 @author Christian Grothoff 17 18 .. _api-mailbox: 19 20 =================== 21 Mailbox RESTful API 22 =================== 23 24 This is the API documentation for the GNU Taler Mailbox service which allows Taler 25 wallets to securely send push and pull payment requests to other wallets 26 without having to interact with the respective messaging service. 27 28 Clients (wallets) are expected to generate mailbox keys that uniquely identify 29 a mailbox as well as encryption keys that can be used to encrypt messages for 30 the mailbox (e.g. `HPKE <https://www.rfc-editor.org/rfc/rfc9180.html>`_. 31 Mailboxes must be registered along with their public key information. 32 Registration may incur costs depending on the mailbox service provider used. 33 34 The API specified here follows the :ref:`general conventions <http-common>` 35 for all details not specified in the individual requests. 36 The `glossary <https://docs.taler.net/taler-developer-manual.html#developer-glossary>`_ 37 defines all specific terms used in this section. 38 39 40 41 --------------- 42 Version History 43 --------------- 44 45 The current protocol version is **v0**. 46 47 * Nothing depends on the mailbox API at this point. 48 49 **Version history:** 50 51 * ``v0``: Initial version. 52 53 **Upcoming versions:** 54 55 * None anticipated. 56 57 **Ideas for future version:** 58 59 * ``vXXX``: marker for features not yet targeted for release 60 61 62 .. include:: tos.rst 63 64 ------------------------- 65 Configuration information 66 ------------------------- 67 68 .. http:get:: /config 69 70 Return the protocol version and currency supported by this service. 71 72 **Response:** 73 74 :http:statuscode:`200 OK`: 75 The body is a `VersionResponse`. 76 77 **Details:** 78 79 .. ts:def:: VersionResponse 80 81 interface VersionResponse { 82 // libtool-style representation of the Merchant protocol version, see 83 // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning 84 // The format is "current:revision:age". 85 version: string; 86 87 // Name of the protocol. 88 name: "taler-mailbox"; 89 90 // Fee per message. 91 message_fee: Amount; 92 93 // Fixed size of message body. 94 message_body_bytes: Integer; 95 96 // Maximum number of messages in a 97 // single response. 98 message_response_limit: Integer; 99 100 // How long will the service store a message 101 // before giving up on delivery? 102 delivery_period: RelativeTime; 103 104 // How much is the cost of a single 105 // registration (update) of a mailbox 106 // May be 0 for a free update/registration. 107 registration_update_fee: Amount 108 109 // How much is the cost of a single 110 // registration period (30 days) of a mailbox 111 // May be 0 for a free registration. 112 monthly_fee: Amount 113 114 // How much is the cost to send a single 115 // message to a mailbox. 116 // May be 0 for free message sending. 117 message_fee: Amount 118 119 // How many messages can be send and 120 // are stored by the service for free. 121 // After the quota is reached, the 122 // regular message_fee applies. 123 // May be 0 for no free quota. 124 free_message_quota: Integer 125 126 } 127 128 --------------------------------- 129 Mailbox registration and metadata 130 --------------------------------- 131 132 .. http:get:: /info/$H_MAILBOX 133 134 Endpoint that returns mailbox metadata including signing and encryption keys for ``$H_MAILBOX``. 135 136 **Response** 137 138 :http:statuscode:`200 Ok`: 139 Info is returned in a `MailboxMetadata` response, 140 :http:statuscode:`404 Not Found`: 141 This mailbox is not registered. 142 :http:statuscode:`429 Too Many Requests`: 143 The system is currently experiencing a too high request 144 load and is unable to accept the message for delivery. 145 The response format is given by `MailboxRateLimitedResponse`_. 146 147 148 **Details:** 149 150 .. _MailboxMetadata: 151 .. ts:def:: MailboxMetadata 152 153 interface MailboxMetadata { 154 155 // The mailbox signing key. 156 // Note that ``$H_MAILBOX == H(signing_key)``. 157 // Note also how this key cannot be updated 158 // as it identifies the mailbox. 159 // Base32 crockford-encoded. 160 signing_key: string; 161 162 // Type of key. 163 // Currently only 164 // EdDSA keys are supported. 165 signing_key_type: "EdDSA"; 166 167 // The mailbox encryption key. 168 // This is a HPKE public key 169 // Currently, only the X25519 format 170 // for use in a X25519-DHKEM (RFC 9180) 171 // is supported. 172 // Base32 crockford-encoded. 173 encryption_key: string; 174 175 // Type of key. 176 // Currently only 177 // X25519 keys are supported. 178 encryption_key_type: "X25519"; 179 180 // Expiration of this mailbox. 181 // Unix epoch (seconds) 182 expiration: Timestamp; 183 184 // Optional info string that can be 185 // chosen by the mailbox owner. 186 // This may contain a Keyoxide proof for the mailbox 187 // in order to link it to the owners profile 188 info?: string; 189 } 190 191 192 .. http:post:: /register 193 194 Requests the registration or update of a mailbox. 195 May be used to update encryption keys. 196 May incur cost. 197 The mailbox identity is given through the keys field 198 in the ``MailboxMetadata`` field. 199 200 **Request** 201 202 The body of the request must be a ``MailboxRegistrationRequest``. 203 204 **Details:** 205 206 .. _MailboxRegistrationRequest: 207 .. ts:def:: MailboxRegistrationRequest 208 209 interface MailboxRegistrationRequest { 210 211 // Keys to add/update for the mailbox. 212 mailbox_metadata: MailboxMetadata; 213 214 // Signature by the mailbox's signing key affirming 215 // the update of keys, of purpose 216 // ``TALER_SIGNATURE_MAILBOX_REGISTER``. 217 // The signature is created over the SHA-512 hash 218 // of (encryptionKeyType||encryptionKey||expiration) 219 // Base32 crockford-encoded. 220 // The signature system is defined through the 221 // signing_key_type in the keys field. 222 signature: string; 223 224 } 225 226 **Response** 227 228 :http:statuscode:`204 No Content`: 229 Update/creation complete. 230 :http:statuscode:`403 Forbidden`: 231 The ``signature`` is invalid. 232 This response comes with a standard `ErrorDetail` response. 233 :http:statuscode:`402 Payment Required` 234 Client needs to make a Taler payment before proceeding. See 235 standard Taler payment procedure. 236 237 ---------------- 238 Sending messages 239 ---------------- 240 241 .. http:post:: /$H_MAILBOX 242 243 Puts a message into ``$H_MAILBOX``. 244 ``$H_MAILBOX`` is the SHA512 of an EdDSA public key. 245 246 **Request** 247 248 The content of the request must be the message with a size of 249 exactly message_body_bytes (see `VersionResponse`). 250 251 **Response** 252 253 :http:statuscode:`204 No Content` 254 Message was stored and will be delivered. 255 :http:statuscode:`403 Forbidden` 256 The specified order ID in the ``Mailbox-Order-Id`` header does not 257 permit sending of this message. Possible reasons include the order 258 being for a different message, unpaid or 259 malformed. 260 This response comes with a standard `ErrorDetail` response. 261 :http:statuscode:`429 Too Many Requests`: 262 The system is currently experiencing a too high request 263 load and is unable to accept the message for delivery. 264 The response format is given by `MailboxRateLimitedResponse`_. 265 :http:statuscode:`402 Payment Required` 266 Client needs to make a Taler payment before proceeding. See 267 standard Taler payment procedure. 268 269 270 **Details:** 271 272 .. _MailboxRateLimitedResponse: 273 .. ts:def:: MailboxRateLimitedResponse 274 275 interface MailboxRateLimitedResponse { 276 277 // Taler error code, TALER_EC_MAILBOX_DELIVERY_RATE_LIMITED. 278 code: Integer; 279 280 // When the client should retry. 281 retry_delay: RelativeTime; 282 283 // The human readable error message. 284 hint: string; 285 286 } 287 288 ------------------ 289 Receiving messages 290 ------------------ 291 292 .. http:get:: /$H_MAILBOX 293 294 Endpoint that returns unread messages in ``$H_MAILBOX``. 295 The number of messages returned by the service can be limited. 296 If the request is simply repeated, the same messages will be 297 returned again (or possibly more if additional messages arrived 298 and the total number is below the service's current internal limit). 299 To receive additional messages, the client generally has to first 300 explicitly delete already downloaded messages from the mailbox. 301 If messages are returned, the ``ETag`` header will be set 302 containing the ID of the first message 303 for use in any potential delete requests that require the message ID. 304 305 **Request:** 306 307 :query timeout_ms=NUMBER: *Optional.* If specified, 308 the Mailbox service will wait up to ``NUMBER`` 309 milliseconds for the arrival of new messages 310 before sending the HTTP response. Note that if the 311 mailbox is non-empty, the service will always return 312 immediately with the messages in the mailbox, and not 313 wait for additional messages to arrive. 314 315 **Response** 316 317 :http:statuscode:`200 Ok`: 318 Messages are returned in binary format, 256 bytes per message, 319 starting with the ephemeral key and followed by 320 the encrypted body. Messages are not encapsulated in JSON! 321 :http:statuscode:`204 No Content`: 322 The mailbox is empty. 323 :http:statuscode:`429 Too Many Requests`: 324 The system is currently experiencing a too high request 325 load and is unable to accept the message for delivery. 326 The response format is given by `MailboxRateLimitedResponse`_. 327 328 .. http:delete:: /$ADDRESS 329 330 Requests the deletion of already received messages from the 331 mailbox. Here, ``$ADDRESS`` must be the EdDSA public key 332 of the mailbox (not the hash!). 333 The ``ETag`` header returned by a GET request for messages 334 returns the ID for the first message received. 335 This allows the caller to select a range of messages starting 336 from the first message received in the last GET call 337 to delete. 338 339 **Request** 340 341 The header ``Match-If`` must be set to the ID of the first message 342 to delete. 343 The ``ETag`` value is retrieved when receiving messages via a GET 344 request. 345 For example, a ``Match-If`` header value of 2 and a count field of 346 5 will delete messages from ID 2 to N such that up to 5 messages are 347 deleted. 348 The ``Taler-Mailbox-Delete-Signature`` header must be set with a 349 Base32-Crockfor encoded signature over four 32 bit values in 350 network byte order: ``NBO(16)||NBO(TALER_SIGNATURE_MAILBOX_DELETE_MESSAGES)||NBO(Etag)||NBO(count)`` 351 where ``TALER_SIGNATURE_MAILBOX_DELETE_MESSAGES`` is a signature purpose value registered in 352 GANA. 353 354 :query count=NUMBER: *Optional.* If specified, 355 the Mailbox service will delete up to ``NUMBER`` 356 of new messages starting from the ID provided 357 in ``Match-If``. 358 If the parameter is not provided, only a single 359 message will be deleted. 360 361 362 **Details:** 363 364 .. _MessageDeletionRequest: 365 .. ts:def:: MessageDeletionRequest 366 367 interface MessageDeletionRequest { 368 369 // Number of messages to delete. (Starting from the beginning 370 // of the latest GET response). 371 count: Integer; 372 373 // Signature by the mailbox's private key affirming 374 // the deletion of the messages, of purpuse 375 // ``TALER_SIGNATURE_MAILBOX_DELETE_MESSAGES``. 376 signature: string; 377 378 } 379 380 **Response** 381 382 :http:statuscode:`204 No Content`: 383 Deletion complete. 384 :http:statuscode:`403 Forbidden`: 385 The ``signature`` is invalid. 386 This response comes with a standard `ErrorDetail` response. 387 :http:statuscode:`404 Not found`: 388 The checksum does not match the messages currently at the 389 head of the mailbox, or ``count`` is larger 390 than the number of messages currently in the mailbox. 391 This response comes with a standard `ErrorDetail` response.