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 general conventions for all details not specified in the individual requests. The glossary defines all specific terms used in this section.
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.
When returning a full response (not a “304 Not Modified”), the server should also include a “Acceptable-Languages” header which includes a space-separated list of the languages in which the terms of service are available in. Clients can use this to generate a language switcher for users that may not have expressed a proper language preference.
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.
GET /config¶Return the protocol version and currency supported by this service.
Response:
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: Method[];
// fee for one month of registration
monthly_fee: Amount;
}
interface Method {
// Name of the method, e.g. "email" or "sms".
name: string;
// per challenge fee
challenge_fee: Amount;
}
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
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
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¶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.
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 (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
solution is invalid. Retrying immediately is allowed.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.
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;
}