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 wallets to obtain the terms of service and the privacy policy of the TalDir.
GET /terms¶Get the terms of service of the TalDir. The TalDir 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 TalDir 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 “204 Not Modified” response will be returned.
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.
GET /privacy¶Get the privacy policy of the TalDir. The TalDir 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 TalDir 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 privacy policy has changed. If not, a “204 Not Modified” response will be returned.
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 privacy policy was not configured correctly.
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;
}