api-taldir.rst (9475B)
1 .. 2 This file is part of GNU TALER. 3 Copyright (C) 2022 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 2.1, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 16 @author Christian Grothoff 17 @author Martin Schanzenbach 18 19 .. _api-taldir: 20 21 ===================== 22 Directory RESTful API 23 ===================== 24 25 This is the API for the Taler Directory (TalDir) service which allows Taler wallets to 26 securely associate an inbox service (URL and public key) with the alias of a 27 wallet's user. Wallets can also lookup the 28 inbox of other users. This will enable wallets to make wallet-to-wallet 29 payments to distant wallets where the target user is only identified by their 30 alias. Examples for aliases include E-mail and phone numbers but also 31 social handles. 32 The service in principle allows registration of any valid URI as inbox 33 service. 34 For Taler, the URI is a link to a :ref:`mailbox <api-mailbox>`. 35 36 The API specified here follows the :ref:`general conventions <http-common>` 37 for all details not specified in the individual requests. 38 The `glossary <https://docs.taler.net/taler-developer-manual.html#developer-glossary>`_ 39 defines all specific terms used in this section. 40 41 42 43 --------------- 44 Version History 45 --------------- 46 47 The current protocol version is **v0**. 48 49 * Nothing depends on the mailbox API at this point. 50 51 **Version history:** 52 53 * ``v0``: Initial version. 54 55 **Upcoming versions:** 56 57 * None anticipated. 58 59 **Ideas for future version:** 60 61 * ``vXXX``: marker for features not yet targeted for release 62 63 64 65 .. include:: tos.rst 66 67 68 ------------------------- 69 Configuration information 70 ------------------------- 71 72 .. http:get:: /config 73 74 Return the protocol version and currency supported by this service. 75 76 **Response:** 77 78 :http:statuscode:`200 OK`: 79 The body is a `VersionResponse`. 80 81 .. ts:def:: VersionResponse 82 83 interface VersionResponse { 84 // libtool-style representation of the Merchant protocol version, see 85 // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning 86 // The format is "current:revision:age". 87 version: string; 88 89 // Name of the protocol. 90 name: "taler-directory"; 91 92 // Supported alias types 93 alias_types: TaldirAliasType[]; 94 95 // fee for one month of registration 96 monthly_fee: Amount; 97 98 } 99 100 .. ts:def:: TaldirAliasType 101 102 interface TaldirAliasType { 103 // Name of the alias type, e.g. "email" or "sms". 104 name: string; 105 106 // per challenge fee 107 challenge_fee: Amount; 108 109 } 110 111 ------------------ 112 Alias registration 113 ------------------ 114 115 .. http:post:: /register/$ALIASTYPE 116 117 Endpoint to register, extend or modify the registration for an alias in 118 the directory. 119 Here, $ALIASTYPE is the type of alias to register, e.g. "email", or "phone". 120 Supported alias types are listed in the VersionResponse. 121 Note that duration should be given as a multiple of a month in microseconds. 122 If the duration is not a multiple of a month it will be rounded to the 123 nearest multiple. Halfway values will be rounded away from zero. 124 The cost calculation and resulting registration validity will be adjusted 125 automatically. 126 In order to only modify the data, the duration may be set to 0. 127 When the call is made with unmodified data and a duration of 0, the 128 endpoint will return how long this registration is currently paid for. 129 In order to delete the mapping, the target URI may be set to the empty string. 130 When the call is made with the empty string, and upon re-validation, the mapping 131 will be deleted. 132 133 **Request** 134 135 .. ts:def:: IdentityMessage 136 137 interface IdentityMessage { 138 // Alias, in $ALIASTYPE-specific format 139 alias: string; 140 141 // Target URI to associate with this alias. 142 target_uri: string; 143 144 // For how long should the registration last/be extended. 145 duration: RelativeTime; 146 147 } 148 149 **Response** 150 151 :http:statuscode:`200 Ok` 152 Registration already exists for this alias for the specified duration. 153 Returns for how long this registration is paid for. 154 The response format is given by `AlreadyPaidResponse`_. 155 :http:statuscode:`202 Accepted` 156 Registration was initiated, the client should check for receiving 157 a challenge at the alias where registration was attempted. 158 :http:statuscode:`402 Payment Required` 159 Client needs to make a Taler payment before proceeding. See 160 standard Taler payment procedure. 161 :http:statuscode:`404 Not found` 162 The TalDir service does not support the specified alias type. 163 This response comes with a standard `ErrorDetail` response. 164 :http:statuscode:`429 Too Many Requests`: 165 The client exceeded the number of allowed attempts for initiating 166 a challenge for this alias in the given timeframe. 167 The response format is given by `RateLimitedResponse`_. 168 169 .. _RateLimitedResponse: 170 .. ts:def:: RateLimitedResponse 171 172 interface RateLimitedResponse { 173 174 // Taler error code, TALER_EC_TALDIR_REGISTER_RATE_LIMITED. 175 code: Integer; 176 177 // At what frequency are new registrations allowed. 178 request_frequency: RelativeTime; 179 180 // The human readable error message. 181 hint: string; 182 183 } 184 185 .. _AlreadyPaidResponse: 186 .. ts:def:: AlreadyPaidResponse 187 188 interface AlreadyPaidResponse { 189 190 // The remaining duration for which this registration is still paid for 191 valid_for: RelativeTime; 192 193 } 194 195 196 .. http:get:: /register/$H_ALIAS/$PINTAN?alias=$ALIAS 197 198 Endpoint that generates an HTML Web site with a link for completing the 199 registration. Useful to open the registration challenge in a browser (say if 200 it was received on a different device than where the wallet is running). 201 Does NOT complete the registration, as some providers automatically click on 202 all links in messages. Yes, we do not like them doing so either, but ``GET`` 203 is a "safe" method according to the HTTP standard, so technically this is 204 allowed. 205 206 Opening the link will allow the user to do the POST call to this endpoint. 207 If the Taler wallet can somehow intercept the URL (say for SMS, if it has the right 208 permissions) it can skip this request and directly do the POST, as all of 209 the required new information is already encoded in the URL. 210 211 Note that the wallet must be involved before the POST is made, as the 212 ``target_uri`` from the registration must be hashed with the ``$PINTAN`` 213 to protect the user against phishing. Otherwise, someone else might attempt 214 a concurrent registration of a different public key, and the user might 215 accidentally authorize the registration of the public key of a different 216 wallet. 217 ``$H_ALIAS`` is the SHA-512 hash of a prefix-free encoding of the 218 alias to be registered in Crockford Base32 encoding, specifically: 219 ``SHA-512(len($ALIASTYPE)+len($ALIAS)||$ALIASTYPE||$ALIAS)`` 220 The service verifies that ``$ALIAS`` is, in fact, the preimage of ``$H_ALIAS`` 221 and ``$ALIAS`` as well as the ``inbox_uri`` are displayed to the user 222 for verification. 223 224 .. http:post:: /$H_ALIAS 225 226 This request is the last step of a registration, proving to the TalDir that 227 the user of the wallet is indeed able to receive messages for the specified 228 alias. 229 ``$H_ALIAS`` is the SHA-512 hash of a prefix-free encoding of the 230 alias to be registered in Crockford Base32 encoding. 231 232 **Request** 233 234 .. ts:def:: IdentityConfirmation 235 236 interface IdentityConfirmation { 237 // The solution is the SHA-512 hash of the challenge ($PINTAN) value 238 // chosen by TalDir concatenated with the ``inbox_uri`` (both strings 239 // are hashed excluding the 0-terminator). 240 // The hash is provided as string in Crockford base32 encoding. 241 solution: HashCode; 242 243 } 244 245 **Response** 246 247 :http:statuscode:`204 No Content`: 248 Registration complete. 249 :http:statuscode:`403 Forbidden`: 250 The ``solution`` is invalid. Retrying immediately is allowed. 251 :http:statuscode:`404 Not found`: 252 The alias is unknown (original registration attempt may have expired). 253 :http:statuscode:`429 Too Many Requests`: 254 The client exceeded the number of allowed attempts for solving 255 a challenge for this alias in the given timeframe. 256 257 ------------ 258 Alias lookup 259 ------------ 260 261 .. http:get:: /$H_ALIAS 262 263 Lookup the target URI associated with 264 an alias in the TalDir. Here, 265 ``$H_ALIAS`` is the SHA-512 hash of a prefix-free encoding of the 266 alias to be registered in Crockford base32 encoding. 267 268 **Response** 269 270 Standard HTTP cache control headers are used to specify how long the 271 registration is still expected to be valid. 272 273 :http:statuscode:`200 Ok`: 274 Registration information returned, of type `MailboxDetailResponse` 275 :http:statuscode:`404 Not found`: 276 The alias is unknown (original registration may have expired). 277 278 .. _MailboxDetailResponse: 279 .. ts:def:: MailboxDetailResponse 280 281 interface MailboxDetailResponse { 282 283 // Target URI to associate with this alias. 284 target_uri: string; 285 286 287 }