kych.conf.5.rst (12040B)
1 kych.conf(5) 2 ############ 3 4 .. only:: html 5 6 Name 7 ==== 8 9 **kych.conf** - configuration file of the KyCH OAuth 2.0 gateway 10 11 12 Description 13 =========== 14 15 kych-oauth2-gateway(1) and kych-client-management(1) read their configuration 16 from a file in the GNU Taler configuration format, the same one every other 17 GNU Taler component reads. It holds one ``[kych-oauth2-gateway]`` section with 18 the settings of the service itself, and any number of ``[client_*]`` sections 19 describing OAuth 2.0 clients. 20 21 Both tools take the file from the **-c** option. Without it, they read the 22 first of 23 24 * ``$XDG_CONFIG_HOME/kych.conf`` 25 * ``$HOME/.config/kych.conf`` 26 * ``/etc/kych.conf`` 27 * ``/etc/kych/kych.conf`` 28 29 that exists; the Debian package installs the last of these. Before any of 30 them, every file in ``$PREFIX/share/kych/config.d/`` is read, so that 31 package-supplied defaults can be overridden rather than edited. Later 32 settings win over earlier ones. 33 34 The file contains the database credentials and the client secrets, and should 35 not be world-readable. 36 37 Nothing is re-read at run time; restart the service after editing. 38 39 40 Syntax 41 ------ 42 43 Comments are introduced by ``#`` or ``%`` and **must stand on a line of their 44 own**; ``;`` is not a comment character. The parser has no notion of a 45 trailing comment, and the two places where one might be written fail 46 differently: 47 48 * after a value, as in ``PORT = 8080 # the port``, the ``#`` and everything 49 after it become part of the value, which then fails to parse as a number; 50 51 * after a section header, as in ``[client_x] # the exchange``, the line is no 52 longer recognised as a section header at all and the file is rejected with 53 ``Expected section header, option assignment or directive``. 54 55 Section names are case-insensitive, and so are option names. Values are 56 trimmed of surrounding whitespace; a value wrapped in double quotes keeps 57 whatever whitespace is inside them, with the quotes removed. 58 59 Several options take a list. The braces are conventional but optional, and 60 items are separated by commas, by whitespace, or by both, so ``{ES256, ES384}``, 61 ``ES256, ES384`` and ``ES256 ES384`` are the same list. An option that is 62 present but names no item at all is an error. 63 64 Options that name a *path* - currently only ``UNIXPATH`` - expand ``$VAR`` and 65 ``${VAR}`` from the ``[paths]`` section and from the environment, and 66 ``${VAR:-default}`` supplies a fallback. ``$PREFIX``, ``$BINDIR``, 67 ``$LIBEXECDIR``, ``$DOCDIR``, ``$ICONDIR``, ``$LOCALEDIR``, ``$LIBDIR`` and 68 ``$DATADIR`` are predefined, derived from where ``kych-oauth2-gateway`` was 69 found on ``$PATH``. 70 71 72 Including other files 73 --------------------- 74 75 A directive on a line of its own pulls in another file, relative to the 76 directory of the file the directive appears in. A directive ends the current 77 section, so an option written after one needs its section header repeated. 78 79 @inline@ FILE 80 Include the whole of ``FILE`` at this point. 81 82 @inline-matching@ GLOB 83 Include every file matching ``GLOB``, in glob order. 84 85 @inline-secret@ SECTION FILE 86 Include only ``[SECTION]`` from ``FILE``, and merge it into the section of 87 that name. This is how the database password and the client secrets are 88 kept out of the main configuration file: the main file stays readable to 89 whoever needs to inspect it, and only the small included file has to be 90 restricted. A missing file is a warning rather than an error, on the theory 91 that a component which does not need the secret should still start. 92 93 For example, in ``/etc/kych/kych.conf``:: 94 95 @inline-secret@ kych-oauth2-gateway secrets/database.conf 96 97 with ``/etc/kych/secrets/database.conf`` holding:: 98 99 [kych-oauth2-gateway] 100 DATABASE = postgres://kych:SECRET@db.example.com/kych 101 102 103 GLOBAL OPTIONS 104 -------------- 105 106 The following options are from the ``[kych-oauth2-gateway]`` section. 107 108 109 Server Binding 110 ^^^^^^^^^^^^^^ 111 112 SERVE 113 How the server obtains its listening socket. Required. One of: 114 115 ``unix`` 116 Bind a Unix domain socket at ``UNIXPATH``. 117 118 ``tcp`` 119 Bind a TCP socket at ``BIND_TO`` and ``PORT``. 120 121 ``systemd`` 122 Take an already-bound socket from the service manager, as passed in 123 ``$LISTEN_FDS``. Either kind of socket is accepted, and nothing else in 124 this section is read. Starting the daemon this way without an activated 125 socket fails with ``Missing systemd activated socket``. 126 127 In every case the server speaks plain HTTP and does not terminate TLS; put 128 a reverse proxy in front of it. 129 130 BIND_TO 131 IP address to bind the TCP server to, e.g. ``127.0.0.1`` or ``::``. 132 Required when ``SERVE = tcp``. Do not bind an address reachable from 133 outside the host. 134 135 PORT 136 TCP port number to listen on, e.g. ``8080``. 137 Required when ``SERVE = tcp``. 138 139 UNIXPATH 140 Path to the Unix domain socket file, e.g. ``/run/kych/kych.sock``. 141 Required when ``SERVE = unix``. The server creates the socket itself and 142 unlinks a leftover socket of a previous run at startup. The directory must 143 already exist. 144 145 UNIXPATH_MODE 146 File permissions for the Unix domain socket, in octal. 147 Required when ``SERVE = unix``. The socket's group is the group the server 148 runs as, so ``660`` plus a shared group is the usual way to restrict it to 149 the reverse proxy. 150 151 152 Database 153 ^^^^^^^^ 154 155 DATABASE 156 PostgreSQL connection string for the database. Required. 157 158 Both the URI form, ``postgres://user:secret@localhost/kych``, and a URI 159 naming a Unix socket directory, ``postgres:///kych?host=/var/run/postgresql``, 160 are understood. Anything the string leaves out is taken from the usual 161 ``PGHOST``, ``PGPORT``, ``PGUSER``, ``PGPASSWORD``, ``PGDATABASE`` and 162 ``PGSSLMODE`` environment variables, or, for the user name, from the 163 account the process runs as - which is what makes peer authentication work 164 without a password in the file. The ``~/.pgpass`` file is *not* consulted 165 for a connection string in URI form. 166 167 The schema is not created automatically; it must be loaded from the SQL 168 shipped with the software before the first start. 169 170 171 Cryptographic Parameters 172 ^^^^^^^^^^^^^^^^^^^^^^^^ 173 174 All three sizes are counts of random bytes, before base64url encoding. The 175 recommended value is 32 in each case, and lowering it directly weakens the 176 unguessability that the corresponding secret relies on. 177 178 NONCE_BYTES 179 Number of random bytes to generate for the nonce created by ``/setup``, 180 which forms the secret part of the authorization URL given to the user. 181 Required. Recommended value: ``32``. 182 183 TOKEN_BYTES 184 Number of random bytes to generate for the OAuth 2.0 access token issued by 185 ``/token``. Required. Recommended value: ``32``. 186 187 AUTH_CODE_BYTES 188 Number of random bytes to generate for the OAuth 2.0 authorization code. 189 Required. Recommended value: ``32``. 190 191 AUTH_CODE_TTL_MINUTES 192 Validity period for authorization codes in minutes. 193 Default: ``10``. 194 The code is single-use in any case. 195 196 197 Verifiable Credential Configuration 198 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 199 200 These options define the verifiable credential type that KyCH will request 201 from the Swiyu Verifier. They are also published to clients on the 202 ``/config`` endpoint, and must match what the issuer actually issues. 203 204 VC_TYPE 205 The type identifier of the verifiable credential, matched against the 206 ``vct`` claim of the presented SD-JWT. 207 Required. Example: ``betaid-sdjwt``. 208 209 VC_FORMAT 210 The format of the verifiable credential. 211 Required. Example: ``vc+sd-jwt``. 212 213 VC_ALGORITHMS 214 List of acceptable cryptographic algorithms for the credential and for the 215 key binding JWT. 216 Required, and must not be empty. Example: ``{ES256}`` or ``{ES256, ES384}``. 217 218 VC_CLAIMS 219 The complete set of claim names that exist in the verifiable credential 220 type. This defines which claims are valid and can be requested by clients 221 via the ``scope`` parameter. The gateway validates that all requested 222 claims are in this set. Required, and must not be empty. 223 Example: ``{family_name, given_name, birth_date, age_over_18}``. 224 225 226 Scope Restrictions 227 ^^^^^^^^^^^^^^^^^^ 228 229 ALLOWED_SCOPES 230 Optional policy restriction on which claims clients may request. If set, 231 only the listed claims can be requested, even if more claims are defined 232 in ``VC_CLAIMS``. If not set, clients may request any claim from 233 ``VC_CLAIMS``. 234 Use this to limit what data clients can access without changing the 235 credential configuration. 236 Example: ``{family_name, age_over_18}``. 237 238 This is the operator's lever for data minimisation, and it is worth 239 setting: without it, a client is trusted to ask only for what it needs. 240 241 242 CLIENT SECTIONS 243 --------------- 244 245 Each OAuth2 client is configured in a separate section with a name starting 246 with ``client_``, for example ``[client_merchant]`` or ``[client_exchange]``; 247 the rest of the name is arbitrary. 248 249 .. note:: 250 251 These sections are **not read by the running gateway**, which resolves 252 clients from the database. They are the input to 253 254 .. code-block:: shell 255 256 $ kych-client-management -c /etc/kych/kych.conf sync 257 258 which creates or updates the corresponding database rows; see 259 kych-client-management(1). Until that command has been run, a newly 260 described client does not exist, and requests on its behalf are rejected 261 as unauthorized. 262 263 CLIENT_ID 264 Unique identifier for this OAuth2 client, used at ``/setup`` and at 265 ``/token``. 266 Required. 267 268 CLIENT_SECRET 269 Secret key for client authentication, stored bcrypt-hashed in the database. 270 Required. 271 272 It is read only when the client is first created. Changing it here and 273 running **sync** again does *not* rotate the stored secret; delete the 274 client and synchronize again for that. 275 276 VERIFIER_URL 277 Base URL of the Swiyu Verifier service that this client will use. 278 Required. Example: ``https://verifier.swiyu.admin.ch``. 279 280 VERIFIER_MANAGEMENT_API_PATH 281 Path to the verifier's management API endpoint. 282 Default: ``/management/api/verifications``. 283 284 REDIRECT_URI 285 OAuth2 callback URL where the authorization response will be sent. 286 Required, and must not be empty. Must match the redirect URI registered 287 with the client application. Several may be given as one comma-separated 288 value; the *redirect_uri* of an authorization request must match one of 289 them exactly, and the same value must be repeated on the token request. 290 Example: ``https://merchant.example.com/kyc/callback``. 291 292 ACCEPTED_ISSUER_DIDS 293 List of trusted issuer DIDs for verifiable credentials. 294 Example: ``{did:tdw:issuer1, did:tdw:issuer2}``. 295 296 .. note:: 297 298 Formally optional - the configuration parses without it - but in 299 practice required: ``/authorize`` fails with 300 ``accepted_issuer_dids_not_configured`` for a client that has no issuer 301 DIDs, so no verification can be started. 302 303 304 EXAMPLE CONFIGURATION 305 ===================== 306 307 :: 308 309 [kych-oauth2-gateway] 310 # Where to listen: unix, tcp or systemd 311 SERVE = unix 312 UNIXPATH = /run/kych/kych.sock 313 UNIXPATH_MODE = 660 314 315 # For SERVE = tcp instead 316 #BIND_TO = 127.0.0.1 317 #PORT = 8080 318 319 # Database connection 320 DATABASE = postgres:///kych?host=/var/run/postgresql 321 322 # Cryptographic parameters 323 NONCE_BYTES = 32 324 TOKEN_BYTES = 32 325 AUTH_CODE_BYTES = 32 326 AUTH_CODE_TTL_MINUTES = 10 327 328 # Optional scope restriction 329 #ALLOWED_SCOPES = {family_name, given_name, birth_date} 330 331 # Verifiable Credential configuration 332 VC_TYPE = betaid-sdjwt 333 VC_FORMAT = vc+sd-jwt 334 VC_ALGORITHMS = {ES256} 335 VC_CLAIMS = {family_name, given_name, birth_date, nationality} 336 337 # Client configuration, with the secrets kept in a separate file 338 @inline-secret@ client_merchant secrets/merchant.conf 339 340 [client_merchant] 341 CLIENT_ID = merchant_prod_01 342 VERIFIER_URL = https://verifier.swiyu.admin.ch 343 VERIFIER_MANAGEMENT_API_PATH = /management/api/verifications 344 REDIRECT_URI = https://merchant.example.com/kyc/callback 345 ACCEPTED_ISSUER_DIDS = {did:tdw:trusted_issuer} 346 347 348 SEE ALSO 349 ======== 350 351 kych-oauth2-gateway(1), kych-client-management(1). 352 353 354 BUGS 355 ==== 356 357 Report bugs by using https://bugs.taler.net/ or by sending electronic 358 mail to <taler@gnu.org>.