1.9. 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 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 service in principle allows registration of any valid URI as inbox service. For Taler, the URI is a link a mailbox.

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.

1.9.1. Terms of service API

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.

The “Etag” is generated from the first 256 bits of the SHA-512 hash over the terms and encoded in Crockford base-32. However, this behavior is not normative and clients MUST NOT rely on it.

A “Taler-Terms-Version” header is generated to indicate the legal version of the terms. This header will change whenever something legally changed in the terms of service and the user must review and accept the terms of service again. If the “Taler-Terms-Version” is identical to one that the user has already accepted, there is no need for the user to review the terms again.

When returning a full response (not a “304 Not Modified”), the server should also include a “Avail-Languages” header which includes a comma-separated list of the languages in which the terms of service are available in (see availability hints specification). Clients can use this to generate a language switcher for users that may not have expressed a proper language preference.

Response:

200 OK:

The body is the terms of service in the requested encoding and language.

501 Not Implemented:

The exchange lacks a valid terms of service configuration. A human-readable error message is returned. Wallets should not require the human to accept any terms of service (and do not need to show this message).

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.

Response:

200 OK:

The body is the privacy policy in the requested encoding and language.

501 Not Implemented:

The exchange lacks a valid terms of service configuration. A human-readable error message is returned. Wallets should not require the human to accept any terms of service (and do not need to show this message).

1.9.2. Configuration information

GET /config

Return the protocol version and currency supported by this service.

Response:

200 OK:

The body is a 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;

}

interface TaldirMethod {
  // Name of the method, e.g. "email" or "sms".
  name: string;

  // per challenge fee
  challenge_fee: Amount;

}

1.9.3. Address registration

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. 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

interface IdentityMessage {
  // Address, in $METHOD-specific format
  address: string;

  // Target URI to associate with this address.
  target_uri: string;

  // For how long should the registration last/be extended.
  duration: RelativeTime;

}

Response

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.

202 Accepted

Registration was initiated, the client should check for receiving a challenge at the address where registration was attempted.

402 Payment Required

Client needs to make a Taler payment before proceeding. See standard Taler payment procedure.

404 Not found

The TalDir service does not support the specified method. This response comes with a standard ErrorDetail response.

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.

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;

}

interface AlreadyPaidResponse {

  // The remaining duration for which this registration is still paid for
  valid_for: RelativeTime;

}

GET /register/$H_ADDRESS/$PINTAN?address=$ADDRESS

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_ADDRESS is the SHA-512 hash of the address to be registered in Crockford base32 encoding. The service verifies that $ADDRESS is, in fact, the preimage of $H_ADDRESS and $ADDRESS as well as the inbox_uri are displayed to the user for verification.

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

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

204 No Content:

Registration complete.

403 Forbidden:

The solution is invalid. Retrying immediately is allowed.

404 Not found:

The address is unknown (original registration attempt may have expired).

429 Too Many Requests:

The client exceeded the number of allowed attempts for solving a challenge for this address in the given timeframe.

1.9.4. Address lookup

GET /$H_ADDRESS

Lookup the target URI associated with an address in the TalDir. Here, $H_ADDRESS is the SHA-512 hash of a 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.

200 Ok:

Registration information returned, of type MailboxDetailResponse

404 Not found:

The address is unknown (original registration may have expired).

interface MailboxDetailResponse {

  // Target URI to associate with this address.
  target_uri: string;


}