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