swagger.json (15851B)
1 { 2 "components": { 3 "schemas": { 4 "mailbox.MailboxMetadata": { 5 "description": "Keys to add/update for a mailbox.", 6 "properties": { 7 "encryption_key": { 8 "description": "The mailbox encryption key.\nThis is an HPKE public key\nin the X25519 format for use\nin a X25519-DHKEM (RFC 9180).\nBase32 crockford-encoded.", 9 "type": "string" 10 }, 11 "encryption_key_type": { 12 "description": "Type of key.\nOptional, as currently only\nX25519 keys are supported.", 13 "type": "string" 14 }, 15 "expiration": { 16 "$ref": "#/components/schemas/mailbox.Timestamp" 17 }, 18 "info": { 19 "description": "Info field (e.g for Keyoxide claim proof)", 20 "type": "string" 21 }, 22 "signing_key": { 23 "description": "The mailbox signing key.\nNote that $H_MAILBOX == H(singingKey).\nNote also how this key cannot be updated\nas it identifies the mailbox.", 24 "type": "string" 25 }, 26 "signing_key_type": { 27 "description": "Type of key.\nOptional, as currently only\nEdDSA keys are supported.", 28 "type": "string" 29 } 30 }, 31 "type": "object" 32 }, 33 "mailbox.MailboxRegistrationRequest": { 34 "properties": { 35 "mailbox_metadata": { 36 "$ref": "#/components/schemas/mailbox.MailboxMetadata" 37 }, 38 "signature": { 39 "description": "Signature by the mailbox's signing key affirming\nthe update of keys, of purpose\nTALER_SIGNATURE_WALLET_MAILBOX_KEYS_UPDATE.\nThe signature is created over the SHA-512 hash\nof (encryptionKeyType||encryptionKey||expiration)", 40 "type": "string" 41 } 42 }, 43 "type": "object" 44 }, 45 "mailbox.RelativeTime": { 46 "description": "How long will the service store a message\nbefore giving up", 47 "properties": { 48 "d_us": { 49 "type": "integer" 50 } 51 }, 52 "type": "object" 53 }, 54 "mailbox.Timestamp": { 55 "description": "Expiration of this mapping (UNIX Epoch seconds).", 56 "properties": { 57 "t_s": { 58 "type": "integer" 59 } 60 }, 61 "type": "object" 62 }, 63 "mailbox.VersionResponse": { 64 "properties": { 65 "delivery_period": { 66 "$ref": "#/components/schemas/mailbox.RelativeTime" 67 }, 68 "free_message_quota": { 69 "description": "How many messages can be send and\nare stored by the service for free.\nAfter the quota is reached, the\nregular message_fee applies.\nMay be 0 for no free quota.", 70 "type": "string" 71 }, 72 "message_body_bytes": { 73 "description": "Fixed size of message bodies", 74 "type": "integer" 75 }, 76 "message_fee": { 77 "description": "How much is the cost to send a single\nmessage to a mailbox.\nMay be 0 for free message sending.", 78 "type": "string" 79 }, 80 "message_response_limit": { 81 "description": "How many messages will a single response\ncontain at maximum.", 82 "type": "integer" 83 }, 84 "monthly_fee": { 85 "description": "How much is the cost of a single\nregistration period (30 days) of a mailbox\nMay be 0 for a free registration.", 86 "type": "string" 87 }, 88 "name": { 89 "description": "Name of the protocol.", 90 "type": "string" 91 }, 92 "registration_update_fee": { 93 "description": "How much is the cost of a single\nregistration (update) of a mailbox\nMay be 0 for a free update/registration.", 94 "type": "string" 95 }, 96 "version": { 97 "description": "libtool-style representation of the Mailbox protocol version, see\nhttps://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning\nThe format is \"current:revision:age\".", 98 "type": "string" 99 } 100 }, 101 "type": "object" 102 } 103 } 104 }, 105 "info": { 106 "contact": { 107 "url": "https://taler.net" 108 }, 109 "description": "The Taler Mailbox service provides encrypted message delivery to wallets identified by their public key.", 110 "license": { 111 "name": "AGPL-3.0-or-later", 112 "url": "https://www.gnu.org/licenses/agpl-3.0.html" 113 }, 114 "title": "Taler Mailbox API", 115 "version": "" 116 }, 117 "externalDocs": { 118 "description": "", 119 "url": "" 120 }, 121 "paths": { 122 "/config": { 123 "get": { 124 "description": "Returns service metadata including fees, message size limits, and delivery period.", 125 "responses": { 126 "200": { 127 "content": { 128 "application/json": { 129 "schema": { 130 "$ref": "#/components/schemas/mailbox.VersionResponse" 131 } 132 } 133 }, 134 "description": "OK" 135 } 136 }, 137 "summary": "Get service configuration", 138 "tags": [ 139 "config" 140 ] 141 } 142 }, 143 "/info/{h_mailbox}": { 144 "get": { 145 "description": "Returns the signing and encryption key metadata for the given mailbox.", 146 "parameters": [ 147 { 148 "description": "SHA-512 hash of the mailbox signing key (Crockford base32)", 149 "in": "path", 150 "name": "h_mailbox", 151 "required": true, 152 "schema": { 153 "type": "string" 154 } 155 } 156 ], 157 "responses": { 158 "200": { 159 "content": { 160 "application/json": { 161 "schema": { 162 "$ref": "#/components/schemas/mailbox.MailboxMetadata" 163 } 164 } 165 }, 166 "description": "OK" 167 }, 168 "404": { 169 "description": "Mailbox not found or expired" 170 } 171 }, 172 "summary": "Get mailbox info", 173 "tags": [ 174 "mailbox" 175 ] 176 } 177 }, 178 "/register": { 179 "post": { 180 "description": "Registers a new mailbox or updates the keys/expiration of an existing one.\nA valid EdDSA signature over the key material must be provided.", 181 "requestBody": { 182 "content": { 183 "application/json": { 184 "schema": { 185 "oneOf": [ 186 { 187 "type": "object" 188 }, 189 { 190 "$ref": "#/components/schemas/mailbox.MailboxRegistrationRequest", 191 "summary": "body", 192 "description": "Registration request" 193 } 194 ] 195 } 196 } 197 }, 198 "description": "Registration request", 199 "required": true 200 }, 201 "responses": { 202 "204": { 203 "description": "Registration confirmed" 204 }, 205 "304": { 206 "description": "Nothing changed" 207 }, 208 "400": { 209 "description": "Invalid request body or signature" 210 }, 211 "402": { 212 "description": "Payment required" 213 }, 214 "500": { 215 "description": "Internal Server Error" 216 } 217 }, 218 "summary": "Register or update mailbox", 219 "tags": [ 220 "mailbox" 221 ] 222 } 223 }, 224 "/{h_mailbox}": { 225 "get": { 226 "description": "Returns up to MessageResponseLimit encrypted message bodies for the given mailbox.\nThe ETag response header contains the serial number of the first message.", 227 "parameters": [ 228 { 229 "description": "SHA-512 hash of the mailbox signing key (Crockford base32)", 230 "in": "path", 231 "name": "h_mailbox", 232 "required": true, 233 "schema": { 234 "type": "string" 235 } 236 } 237 ], 238 "responses": { 239 "200": { 240 "content": { 241 "application/octet-stream": { 242 "schema": { 243 "format": "binary", 244 "type": "string" 245 } 246 } 247 }, 248 "description": "One or more message bodies concatenated" 249 }, 250 "204": { 251 "description": "No messages available" 252 }, 253 "404": { 254 "description": "Mailbox not found" 255 } 256 }, 257 "summary": "Retrieve messages", 258 "tags": [ 259 "mailbox" 260 ] 261 }, 262 "post": { 263 "description": "Stores an encrypted message body for the given mailbox. The body must be\nexactly MessageBodyBytes in size.", 264 "parameters": [ 265 { 266 "description": "SHA-512 hash of the mailbox signing key (Crockford base32)", 267 "in": "path", 268 "name": "h_mailbox", 269 "required": true, 270 "schema": { 271 "type": "string" 272 } 273 } 274 ], 275 "requestBody": { 276 "content": { 277 "application/octet-stream": { 278 "schema": { 279 "format": "binary", 280 "type": "string" 281 } 282 }, 283 "text/plain": { 284 "schema": { 285 "title": "body", 286 "type": "string" 287 } 288 } 289 }, 290 "description": "Encrypted message body (fixed size)", 291 "required": true 292 }, 293 "responses": { 294 "204": { 295 "description": "Message stored" 296 }, 297 "304": { 298 "description": "Identical message already stored" 299 }, 300 "400": { 301 "description": "Missing or wrong-size body" 302 }, 303 "402": { 304 "description": "Payment required (free quota exceeded)" 305 }, 306 "500": { 307 "description": "Internal Server Error" 308 } 309 }, 310 "summary": "Send a message", 311 "tags": [ 312 "mailbox" 313 ] 314 } 315 }, 316 "/{mailbox}": { 317 "delete": { 318 "description": "Deletes one or more messages starting from the serial given in the If-Match header.\nRequires a valid EdDSA signature in the Taler-Mailbox-Delete-Signature header.", 319 "parameters": [ 320 { 321 "description": "Crockford base32-encoded EdDSA public key of the mailbox", 322 "in": "path", 323 "name": "mailbox", 324 "required": true, 325 "schema": { 326 "type": "string" 327 } 328 }, 329 { 330 "description": "Number of messages to delete (default: 1)", 331 "in": "query", 332 "name": "count", 333 "schema": { 334 "type": "integer" 335 } 336 }, 337 { 338 "description": "Serial number of the first message to delete", 339 "in": "header", 340 "name": "If-Match", 341 "required": true, 342 "schema": { 343 "type": "string" 344 } 345 }, 346 { 347 "description": "EdDSA signature authorising the deletion", 348 "in": "header", 349 "name": "Taler-Mailbox-Delete-Signature", 350 "required": true, 351 "schema": { 352 "type": "string" 353 } 354 } 355 ], 356 "responses": { 357 "204": { 358 "description": "Messages deleted" 359 }, 360 "400": { 361 "description": "Missing or malformed headers/parameters" 362 }, 363 "403": { 364 "description": "Signature invalid" 365 }, 366 "404": { 367 "description": "Message with given serial not found" 368 }, 369 "500": { 370 "description": "Internal Server Error" 371 } 372 }, 373 "summary": "Delete messages", 374 "tags": [ 375 "mailbox" 376 ] 377 } 378 } 379 }, 380 "openapi": "3.1.0", 381 "servers": [ 382 { 383 "url": "/" 384 } 385 ] 386 }