taler-docs

api-taldir.rst (9183B)

---

 ..
   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
 
 .. _api-taldir:
 
 =====================
 Directory RESTful API
 =====================
 
 This is the API for the Taler Directory (TalDir) service which allows Taler wallets to
 securely associate an inbox service (URL and public key) with the alias of a
 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
 alias. Examples for aliases include E-mail and phone numbers but also
 social handles.
 The service in principle allows registration of any valid URI as inbox
 service.
 For Taler, the URI is a link to a :ref:`mailbox <api-mailbox>`.
 
 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/taler-developer-manual.html#developer-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 alias types
       alias_types: TaldirAliasType[];
 
       // fee for one month of registration
       monthly_fee: Amount;
 
     }
 
   .. ts:def:: TaldirAliasType
 
     interface TaldirAliasType {
       // Name of the alias type, e.g. "email" or "sms".
       name: string;
 
       // per challenge fee
       challenge_fee: Amount;
 
     }
 
 ------------------
 Alias registration
 ------------------
 
 .. http:post:: /register/$ALIASTYPE
 
   Endpoint to register, extend or modify the registration for an alias in
   the directory.
   Here, $ALIASTYPE is the type of alias to register, e.g. "email", or "phone".
   Supported alias types 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.
   In order to delete the mapping, the target URI may be set to the empty string.
   When the call is made with the empty string, and upon re-validation, the mapping
   will be deleted.
 
   **Request**
 
   .. ts:def:: IdentityMessage
 
     interface IdentityMessage {
       // Alias, in $ALIASTYPE-specific format
       alias: string;
 
       // Target URI to associate with this alias.
       target_uri: string;
 
       // For how long should the registration last/be extended.
       duration: RelativeTime;
 
     }
 
   **Response**
 
   :http:statuscode:`200 Ok`
      Registration already exists for this alias 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 alias 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 alias type.
      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 alias 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: Integer;
 
       // 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_ALIAS/$PINTAN?alias=$ALIAS
 
   Endpoint that generates an HTML Web site with a 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 allow the user to do the POST call to this endpoint.
   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
   ``target_uri`` 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.
   ``$H_ALIAS`` is the SHA-512 hash of a prefix-free encoding of the
   alias to be registered in Crockford Base32 encoding, specifically:
   ``SHA-512(len($ALIASTYPE)+len($ALIAS)||$ALIASTYPE||$ALIAS)``
   The service verifies that ``$ALIAS`` is, in fact, the preimage of ``$H_ALIAS``
   and ``$ALIAS`` as well as the ``inbox_uri`` are displayed to the user
   for verification.
 
 .. http:post:: /$H_ALIAS
 
   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 for the specified
   alias.
   ``$H_ALIAS`` is the SHA-512 hash of a prefix-free encoding of the
   alias 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 concatenated with the ``inbox_uri`` (both strings
       // are hashed excluding the 0-terminator).
       // 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 alias 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 alias in the given timeframe.
 
 ------------
 Alias lookup
 ------------
 
 .. http:get:: /$H_ALIAS
 
   Lookup the target URI associated with
   an alias in the TalDir. Here,
   ``$H_ALIAS`` is the SHA-512 hash of a prefix-free encoding of the
   alias to be registered 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 alias is unknown (original registration may have expired).
 
   .. _MailboxDetailResponse:
   .. ts:def:: MailboxDetailResponse
 
     interface MailboxDetailResponse {
 
       // Target URI to associate with this alias.
       target_uri: string;
 
 
     }