diff options
Diffstat (limited to 'core/api-taldir.rst')
| -rw-r--r-- | core/api-taldir.rst | 258 |
1 files changed, 258 insertions, 0 deletions
diff --git a/core/api-taldir.rst b/core/api-taldir.rst new file mode 100644 index 00000000..4da9bb02 --- /dev/null +++ b/core/api-taldir.rst @@ -0,0 +1,258 @@ +.. + 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 + @author Martin Schanzenbach + + +====================== +The TalDir RESTful API +====================== + +This is a proposed API for the TalDir service which allows Taler wallets to +securely associate an inbox service (URL and public key) with the address of a +messaging service used by the wallet's user. Wallets can also lookup the +inbox of other users. This will enable wallets to make wallet-to-wallet +payments to distant wallets where the target user is only identified by their +address in a messaging service. Examples for messaging services include E-mail +and SMS. + +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/glossary.html#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`. + + .. 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-directory"; + + // Supported registration methods + methods: TaldirMethod[]; + + // fee for one month of registration + monthly_fee: Amount; + + } + + .. ts:def:: TaldirMethod + + interface TaldirMethod { + // Name of the method, e.g. "email" or "sms". + name: string; + + // per challenge fee + challenge_fee: Amount; + + } + +-------------------- +Address registration +-------------------- + +.. http:post:: /register/$METHOD + + Endpoint to register, extend or modify the registration for an address in + the directory. + Here, $METHOD is the type of address to register, e.g. "email", or "phone". + Supported methods are listed in the VersionResponse. + Note that duration should be given as a multiple of a month in microseconds. + If the duration is not a multiple of a month it will be rounded to the + nearest multiple. Halfway values will be rounded away from zero. + The cost calculation and resulting registration validity will be adjusted + automatically. + In order to only modify the data, the duration may be set to 0. + When the call is made with unmodified data and a duration of 0, the + endpoint will return how long this registration is currently paid for. + + **Request** + + .. ts:def:: IdentityMessage + + interface IdentityMessage { + // Address, in $METHOD-specific format + address: string; + + // Public key of the user to register. As string in Crockfor base32 encoding. + public_key: EddsaPublicKey; + + // (HTTPS) endpoint URL for the inbox service. + inbox_url: string; + + // For how long should the registration last/be extended. + duration: RelativeTime; + + } + + **Response** + + :http:statuscode:`200 Ok` + Registration already exists for this address for the specified duration. + Returns for how long this registration is paid for. + The response format is given by `AlreadyPaidResponse`_. + :http:statuscode:`202 Accepted` + Registration was initiated, the client should check for receiving + a challenge at the address where registration was attempted. + :http:statuscode:`402 Payment Required` + Client needs to make a Taler payment before proceeding. See + standard Taler payment procedure. + :http:statuscode:`404 Not found` + The TalDir service does not support the specified method. + This response comes with a standard `ErrorDetail` response. + :http:statuscode:`429 Too Many Requests`: + The client exceeded the number of allowed attempts for initiating + a challenge for this address in the given timeframe. + The response format is given by `RateLimitedResponse`_. + + .. _RateLimitedResponse: + .. ts:def:: RateLimitedResponse + + interface RateLimitedResponse { + + // Taler error code, TALER_EC_TALDIR_REGISTER_RATE_LIMITED. + code: number; + + // At what frequency are new registrations allowed. + request_frequency: RelativeTime; + + // The human readable error message. + hint: string; + + } + + .. _AlreadyPaidResponse: + .. ts:def:: AlreadyPaidResponse + + interface AlreadyPaidResponse { + + // The remaining duration for which this registration is still paid for + valid_for: RelativeTime; + + } + + +.. http:get:: /register/$H_ADDRESS/$PINTAN + + Endpoint that generates an HTML Web site with a QR code and + ``taler://taldir/$H_ADDRESS/$PINTAN-wallet`` link for completing the + registration. Useful to open the registration challenge in a browser (say if + it was received on a different device than where the wallet is running). + Does NOT complete the registration, as some providers automatically click on + all links in messages. Yes, we do not like them doing so either, but ``GET`` + is a "safe" method according to the HTTP standard, so technically this is + allowed. + + Opening the link will lead the **wallet** to do the POST call below. If the + Taler wallet can somehow intercept the URL (say for SMS, if it has the right + permissions) it can skip this request and directly do the POST, as all of + the required new information is already encoded in the URL. + + Note that the wallet must be involved before the POST is made, as the + wallet's public key from the registration must be hashed with the ``$PINTAN`` + to protect the user against phishing. Otherwise, someone else might attempt + a concurrent registration of a different public key, and the user might + accidentally authorize the registration of the public key of a different + wallet. + +.. http:post:: /$H_ADDRESS + + This request is the last step of a registration, proving to the TalDir that + the user of the wallet is indeed able to receive messages at the specified + address. ``$H_ADDRESS`` is the SHA-512 hash of the address to be registered in + Crockford base32 encoding. + + **Request** + + .. ts:def:: IdentityConfirmation + + interface IdentityConfirmation { + // The solution is the SHA-512 hash of the challenge ($PINTAN) value + // chosen by TalDir (encoded as string just as given in the URL, but + // excluding the 0-termination) concatenated with the binary 32-byte + // value representing the wallet's EdDSA public key. + // The hash is provided as string in Crockford base32 encoding. + solution: HashCode; + + } + + **Response** + + :http:statuscode:`204 No Content`: + Registration complete. + :http:statuscode:`403 Forbidden`: + The ``solution`` is invalid. Retrying immediately is allowed. + :http:statuscode:`404 Not found`: + The address is unknown (original registration attempt may have expired). + :http:statuscode:`429 Too Many Requests`: + The client exceeded the number of allowed attempts for solving + a challenge for this address in the given timeframe. + +-------------- +Address lookup +-------------- + +.. http:get:: /$H_ADDRESS + + Lookup the public key (and mailbox service base URL) associated with + an address in the TalDir. Here, ``$H_ADDRESS`` is the SHA-512 hash of + a (presumably) registered address in Crockford base32 encoding. + + **Response** + + Standard HTTP cache control headers are used to specify how long the + registration is still expected to be valid. + + :http:statuscode:`200 Ok`: + Registration information returned, of type `MailboxDetailResponse` + :http:statuscode:`404 Not found`: + The address is unknown (original registration may have expired). + + .. _MailboxDetailResponse: + .. ts:def:: MailboxDetailResponse + + interface MailboxDetailResponse { + + // Registered public key of the user. As string in Crockford base32 encoding. + public_key: EddsaPublicKey; + + // (HTTPS) endpoint URL for the inbox service. + inbox_url: string; + + } |