README.md (7438B)
1 # Taler Directory 2 3 This is the Taler Directory (TalDir) implementation. 4 The API can be found here: https://docs.taler.net/core/api-taldir.html 5 6 # Dependencies 7 8 - golang 9 10 # Build and Run 11 12 Compile and run: 13 14 ``` 15 $ ./bootstrap 16 $ ./configure --prefix=PREFIX 17 $ make && make install 18 (You may have to set your $PATH to include the go/bin folder accordingly) 19 $ cp config/taldir-example.conf taldir.conf 20 (Edit taldir.conf to fit your needs) 21 $ ./taler-directory-httpd -c taldir.conf 22 ``` 23 24 # Test 25 26 ``` 27 $ go test -v ./cmd/talidir-server 28 ``` 29 30 # Configuration 31 32 The configuration file of taldir is `taldir.conf`. 33 You may copy the example configuration `config/taldir-example.conf` to your 34 runtime directory and modify it according to your needs. 35 36 The following configuration variables exist: 37 38 For the `[taldir]` section: 39 40 - "production" (boolean): true for a production deployment. Causes verbose log messages to be inhibited. 41 - "db_backend" (string): "sqlite" for the SQLite database backend to be used. 42 - "validators" (array): An array of strings for the validators/identity types that can be used. Currently supported values: "email" 43 - "email_sender" (string): For email validations, what should the sender address be. 44 - "host" (string): For the validation link, which hostname should be used (useful if behind proxy). 45 - "bind_to" (string): Where to bind and listen (HTTP server). 46 - "salt" (string): The salt to use for identity key hashes in the database may alternatively be an environment variable `TALDIR_SALT`. 47 - "monthly_fee" (string): The monthly fee for a registration (Default: "KUDOS:1") 48 - "default_doc_filetype" (string): The default file type for the terms of service and privacy policy documents (Default: "text/markdown") 49 - "default_doc_lang" (string): The default language for the terms of service and privacy policy documents (Default: "en-US") 50 - "default_tos_path" (string): The path for the terms of service documents. Taldir will look for `<lang>.<extension>` depending on the requested file type ("Accept"-header) and locale ("Accept-Language"-header) (Default: "terms/") 51 - "default_pp_path" (string): See `default_tos_path` (Default: "privacy/") 52 - "challenge_bytes" (number): The number of bytes (entropy) of the generated challenge (Default: 16) 53 - "validation_initiation_max" (number): How many challenges can be requested to validate an address (Default: 3) 54 - "validation_timeframe" (string): The timeframe in which challenges can be requested up to `validation_initiation_max` times (Default: 10m) 55 - "solution_attempt_max" (number): How often can the solution be attempted for a challenge in the `solution_attempt_timeframe` (Default: 3) 56 - "solution_attempt_timeframe" (string): The timeframe in which the solution can be attempted `solution_attempt_max` times (Default: "1h") 57 - "merchant_baseurl_privat" (string): The base URL for the merchant API to use (Default: "http://merchant.taldir/instances/myInstance") 58 - "merchant_token" (string): The access token for the merchant API (Default: "superSecretToken") 59 - "validation_landing" (string): The location of the HTML template to use for the validation landing displaying a QR code. (Default: "templates/validation_landing.html" 60 - "validation_expiration" (string): The duration for which incomplete registration requests are kept. (Default: "24h") 61 62 For the `[taldir-pq]` section: 63 64 - "host" (string): The host of the Postgres database to use (Default: "localhost") 65 - "port" (number): The port of the Postres database to use (Default: 5432) 66 - "user" (string): The database user (Default: "taldir") 67 - "password" (string): The database user password (Default: "secret") 68 - "db_name" (string): The database name (Default: "taldir") 69 70 Examples and defaults for the configuration can be found in the `taldir.conf` file shipped with this software. 71 72 # Disseminators 73 74 Aliases will be disseminated through the REST API of the taler-directory service itself by default. 75 It is also possible to use other external disseminators. 76 At this point in time, only the GNU Name System (RFC 9498) is available as an additional 77 dissemiantion mechanism. 78 79 You can activate it through the configuration: 80 81 ``` 82 [taldir-disseminator-gns] 83 enabled = true 84 zone = "testtaldir" 85 expiration = "1d" 86 ``` 87 88 If `enabled` is set to `true`, the disseminator is enabled. 89 The GNS zone with the name configured under the `zone` key is where records 90 will be stored upon dissemination. 91 `expiration` is a relative expiration string (`1d` is one day, `15m` would be 15 minutes). 92 This defines the TTL of the records in GNS after which a re-resolution by resolvers 93 is required. 94 The default value of 1 day should be fine in most cases. 95 Note that this means that there will be up to 1 day of delay between the deletion or update of an 96 alias mapping and its removal/availability through GNS. 97 98 The GNS dissemination plugin requires a working GNUnet (https://www.gnunet.org) peer to be installed and started and the respective configured zone to exist. 99 100 Aliases will then be available for resolution in GNS using the `$H_ADDRESS` (see https://docs.taler.net/core/api-taldir.html#address-lookup) in GNS as TXT record: 101 102 ``` 103 104 $ gnunet-gns -u $H_ADDRESS.$ZONE 105 ``` 106 107 where `$ZONE` is either the zone public key of the configured dissemination zone or a human-readable mapping to it (See the documentation of GNS for details). 108 109 # Validators 110 111 Taldir validators are executable programs which are used to transfer a validation 112 code out of band to the client. 113 A Taldir validator is uniquely identified by a name. 114 In order to enable a validator, its `<name>` must be present in the `validators` field 115 in the `taldir` section in the Taldir configuration file. 116 Further, a `taldir-<name>` section must exists which contains the following 117 variables: 118 119 - "challenge_fee" (amount): The cost of a single challenge using this validation method. 120 - "command" (string): The program to use to trigger the out of band transfer of the validation code. 121 122 ## Validator command 123 124 The validator command is an executable program which takes exactly two arguments: 125 For example: 126 127 ``` 128 $ validator-test <address> <code> 129 ``` 130 131 The first argument of the validator command is the address in a validation method-specific format. 132 For example, the email validation expects an email address, the Twitter validator expects a Twitter handle, etc. 133 The second argument is the activation code generated by Taldir and which is expected to be transferred using the validation method to the user. 134 135 # Terms of Service and Privacy Policy 136 137 You may edit the document templates under `contrib/pp` and `contrib/tos` 138 to your needs. 139 You can build the documents using: 140 141 ``` 142 $ make update-tos 143 $ make update-pp 144 ``` 145 146 And configure/copy the built localized documents into your configured 147 paths, e.g.: 148 149 ``` 150 $ cp -r contrib/tos/en terms/ 151 $ cp -r contrib/pp/en terms/ 152 ``` 153 154 # Generate OpenAPI Spec 155 156 You can generate an openapi spec from code to `./swagger.json`: 157 158 ``` 159 $ go install github.com/swaggo/swag/v2/cmd/swag@latest 160 $ ./configure --prefix=PREFIX 161 $ make openapi 162 ``` 163 164 # Funding 165 166 This project is funded through [NGI TALER Fund](https://nlnet.nl/taler), a fund established by [NLnet](https://nlnet.nl) with financial support from the European Commission's [Next Generation Internet](https://ngi.eu) program. Learn more at the [NLnet project page](https://nlnet.nl/project/TALER-LookupService). 167 168 [<img src="https://nlnet.nl/logo/banner.png" alt="NLnet foundation logo" width="20%" />](https://nlnet.nl)