kych.conf.5.rst (13618B)
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 Two details of that syntax are worth knowing, because getting them wrong 168 produces a connection to somewhere else rather than an error: 169 170 * A ``host=`` *parameter* whose value begins with ``/`` selects a Unix 171 socket directory, not a host name. Written as the authority instead it 172 has to be percent-encoded: 173 ``postgres://%2Fvar%2Frun%2Fpostgresql/kych``. 174 175 * The port is read from the authority part only; ``?port=`` is ignored. A 176 server on another port is therefore 177 ``postgres://localhost:5433/kych?host=/var/run/postgresql`` -- the 178 ``localhost`` there is a placeholder that the socket parameter overrides. 179 180 With neither given, the socket directory is found by looking for 181 ``.s.PGSQL.5432`` in ``/var/run/postgresql`` and then ``/tmp``, falling back 182 to a TCP connection to ``localhost``. 183 184 The schema is created by kych-dbconfig(1) and kept up to date by 185 kych-dbinit(1); see those pages. The daemon itself never creates or migrates 186 it. 187 188 SQL_DIR 189 Directory holding ``versioning.sql`` and the ``oauth2gw-000N.sql`` patch 190 files. Read by kych-dbinit(1) only; the daemon ignores it. 191 Optional, and defaults to ``$DATADIR/sql``, which resolves to 192 ``/usr/share/kych/sql`` for an installation under ``/usr``. In a source tree 193 the patches are in ``oauth2_gatewaydb/``, which kych-dbinit's ``--sql-dir`` 194 can also name directly. 195 196 197 Cryptographic Parameters 198 ^^^^^^^^^^^^^^^^^^^^^^^^ 199 200 All three sizes are counts of random bytes, before base64url encoding. The 201 recommended value is 32 in each case, and lowering it directly weakens the 202 unguessability that the corresponding secret relies on. 203 204 NONCE_BYTES 205 Number of random bytes to generate for the nonce created by ``/setup``, 206 which forms the secret part of the authorization URL given to the user. 207 Required. Recommended value: ``32``. 208 209 TOKEN_BYTES 210 Number of random bytes to generate for the OAuth 2.0 access token issued by 211 ``/token``. Required. Recommended value: ``32``. 212 213 AUTH_CODE_BYTES 214 Number of random bytes to generate for the OAuth 2.0 authorization code. 215 Required. Recommended value: ``32``. 216 217 AUTH_CODE_TTL_MINUTES 218 Validity period for authorization codes in minutes. 219 Default: ``10``. 220 The code is single-use in any case. 221 222 223 Verifiable Credential Configuration 224 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 225 226 These options define the verifiable credential type that KyCH will request 227 from the Swiyu Verifier. They are also published to clients on the 228 ``/config`` endpoint, and must match what the issuer actually issues. 229 230 VC_TYPE 231 The type identifier of the verifiable credential, matched against the 232 ``vct`` claim of the presented SD-JWT. 233 Required. Example: ``betaid-sdjwt``. 234 235 VC_FORMAT 236 The format of the verifiable credential, sent as the ``format`` of the DCQL 237 credential query. ``dc+sd-jwt`` is the canonical SD-JWT VC media type; the 238 verifier also still accepts the older ``vc+sd-jwt``. 239 Required. Example: ``dc+sd-jwt``. 240 241 VC_ALGORITHMS 242 List of acceptable cryptographic algorithms for the credential and for the 243 key binding JWT. DCQL has no place for them in the credential query, so 244 they are no longer sent to the verifier and only appear on the ``/config`` 245 endpoint, where clients read them. 246 Required, and must not be empty. Example: ``{ES256}`` or ``{ES256, ES384}``. 247 248 VC_CLAIMS 249 The complete set of claim names that exist in the verifiable credential 250 type. This defines which claims are valid and can be requested by clients 251 via the ``scope`` parameter. The gateway validates that all requested 252 claims are in this set. Required, and must not be empty. 253 Example: ``{family_name, given_name, birth_date, age_over_18}``. 254 255 256 Scope Restrictions 257 ^^^^^^^^^^^^^^^^^^ 258 259 ALLOWED_SCOPES 260 Optional policy restriction on which claims clients may request. If set, 261 only the listed claims can be requested, even if more claims are defined 262 in ``VC_CLAIMS``. If not set, clients may request any claim from 263 ``VC_CLAIMS``. 264 Use this to limit what data clients can access without changing the 265 credential configuration. 266 Example: ``{family_name, age_over_18}``. 267 268 This is the operator's lever for data minimisation, and it is worth 269 setting: without it, a client is trusted to ask only for what it needs. 270 271 272 CLIENT SECTIONS 273 --------------- 274 275 Each OAuth2 client is configured in a separate section with a name starting 276 with ``client_``, for example ``[client_merchant]`` or ``[client_exchange]``; 277 the rest of the name is arbitrary. 278 279 .. note:: 280 281 These sections are **not read by the running gateway**, which resolves 282 clients from the database. They are the input to 283 284 .. code-block:: shell 285 286 $ kych-client-management -c /etc/kych/kych.conf sync 287 288 which creates or updates the corresponding database rows; see 289 kych-client-management(1). Until that command has been run, a newly 290 described client does not exist, and requests on its behalf are rejected 291 as unauthorized. 292 293 CLIENT_ID 294 Unique identifier for this OAuth2 client, used at ``/setup`` and at 295 ``/token``. 296 Required. 297 298 CLIENT_SECRET 299 Secret key for client authentication, stored bcrypt-hashed in the database. 300 Required. 301 302 It is read only when the client is first created. Changing it here and 303 running **sync** again does *not* rotate the stored secret; delete the 304 client and synchronize again for that. 305 306 VERIFIER_URL 307 Base URL of the Swiyu Verifier service that this client will use. 308 Required. Example: ``https://verifier.swiyu.admin.ch``. 309 310 VERIFIER_MANAGEMENT_API_PATH 311 Path to the verifier's management API endpoint. 312 Default: ``/management/api/verifications``. 313 314 REDIRECT_URI 315 OAuth2 callback URL where the authorization response will be sent. 316 Required, and must not be empty. Must match the redirect URI registered 317 with the client application. Several may be given as one comma-separated 318 value; the *redirect_uri* of an authorization request must match one of 319 them exactly, and the same value must be repeated on the token request. 320 Example: ``https://merchant.example.com/kyc/callback``. 321 322 ACCEPTED_ISSUER_DIDS 323 List of trusted issuer DIDs for verifiable credentials. 324 Example: ``{did:tdw:issuer1, did:tdw:issuer2}``. 325 326 .. note:: 327 328 Formally optional - the configuration parses without it - but in 329 practice required: ``/authorize`` fails with 330 ``accepted_issuer_dids_not_configured`` for a client that has no issuer 331 DIDs, so no verification can be started. 332 333 334 EXAMPLE CONFIGURATION 335 ===================== 336 337 :: 338 339 [kych-oauth2-gateway] 340 # Where to listen: unix, tcp or systemd 341 SERVE = unix 342 UNIXPATH = /run/kych/kych.sock 343 UNIXPATH_MODE = 660 344 345 # For SERVE = tcp instead 346 #BIND_TO = 127.0.0.1 347 #PORT = 8080 348 349 # Database connection 350 DATABASE = postgres:///kych?host=/var/run/postgresql 351 352 # Cryptographic parameters 353 NONCE_BYTES = 32 354 TOKEN_BYTES = 32 355 AUTH_CODE_BYTES = 32 356 AUTH_CODE_TTL_MINUTES = 10 357 358 # Optional scope restriction 359 #ALLOWED_SCOPES = {family_name, given_name, birth_date} 360 361 # Verifiable Credential configuration 362 VC_TYPE = betaid-sdjwt 363 VC_FORMAT = dc+sd-jwt 364 VC_ALGORITHMS = {ES256} 365 VC_CLAIMS = {family_name, given_name, birth_date, nationality} 366 367 # Client configuration, with the secrets kept in a separate file 368 @inline-secret@ client_merchant secrets/merchant.conf 369 370 [client_merchant] 371 CLIENT_ID = merchant_prod_01 372 VERIFIER_URL = https://verifier.swiyu.admin.ch 373 VERIFIER_MANAGEMENT_API_PATH = /management/api/verifications 374 REDIRECT_URI = https://merchant.example.com/kyc/callback 375 ACCEPTED_ISSUER_DIDS = {did:tdw:trusted_issuer} 376 377 378 SEE ALSO 379 ======== 380 381 kych-oauth2-gateway(1), kych-client-management(1). 382 383 384 BUGS 385 ==== 386 387 Report bugs by using https://bugs.taler.net/ or by sending electronic 388 mail to <taler@gnu.org>.