swiyu-verifier.1.rst (6688B)
1 swiyu-verifier(1) 2 ################# 3 4 .. only:: html 5 6 Name 7 ==== 8 9 **swiyu-verifier** - SWIYU Generic Verifier service 10 11 12 Synopsis 13 ======== 14 15 **swiyu-verifier** 16 [*--PROPERTY=VALUE* ...] 17 18 19 Description 20 =========== 21 22 **swiyu-verifier** runs the SWIYU Generic Verifier, the Spring Boot service 23 that performs OpenID4VP credential verification against the Swiss SWIYU trust 24 infrastructure. kych-oauth2-gateway(1) creates verifications on its management 25 API and is told the result through a webhook; the user's wallet talks to its 26 OID4VP API. 27 28 This program is a thin wrapper around ``java -jar 29 /usr/share/swiyu-verifier/swiyu-verifier.jar``. It exists because three things 30 have to be settled before the JVM starts: 31 32 * **Which Java.** The jar is built for Java 25, which the verifier moved to in 33 its 5.0.0 release, so the system default ``java`` is not necessarily the 34 right one. ``$JAVA_HOME`` wins if it is set and holds a runtime; otherwise 35 an ``/usr/lib/jvm/java-25-openjdk-*`` is preferred over the default. 36 37 * **The configuration under /etc.** ``/etc/swiyu-verifier/application.yml`` is 38 added to the configuration compiled into the jar, overriding it. 39 40 * **The trust store.** If ``/var/lib/swiyu-verifier/cacerts`` exists -- the 41 package's ``postinst`` builds it from the system Java trust store plus the 42 Swiss Government Root CA VI, which is not publicly trusted -- it is used 43 instead of the JVM default. 44 45 Any arguments are passed on to the application, so Spring Boot's 46 ``--property=value`` form works; see **Examples**. 47 48 The service is normally not run from a terminal but through 49 ``swiyu-verifier.service``, which is where the environment comes from. 50 51 52 Configuration 53 ============= 54 55 The verifier is configured through environment variables, which 56 ``swiyu-verifier.service`` reads from 57 58 ``/etc/swiyu-verifier/swiyu-verifier.env`` 59 The package's defaults, and the reference for what can be set: the identity 60 of the verifier (``EXTERNAL_URL``, ``VERIFIER_DID``, 61 ``DID_VERIFICATION_METHOD``), where it listens (``SERVER_ADDRESS``, 62 ``SERVER_PORT``), its database (``POSTGRES_JDBC``, ``POSTGRES_USER``), where 63 to report results (``WEBHOOK_CALLBACK_URI``) and which trust registry to 64 use. It is commented throughout; the full list of properties is upstream's, 65 at https://github.com/swiyu-admin-ch/swiyu-verifier. 66 67 ``/etc/swiyu-verifier/local.env`` 68 Where the operator's own settings belong. Read after the file above, and 69 therefore overriding it, and not owned by the package -- so an upgrade that 70 changes the shipped defaults has no conffile question to ask. Not shipped; 71 create it. 72 73 ``/etc/swiyu-verifier/secrets/db.env`` 74 ``POSTGRES_PASSWORD``, written by swiyu-verifier-dbconfig(1). 75 76 The signing key is not among them, because a PEM document has newlines in it 77 and an environment file cannot express those -- an escaped ``\n`` reaches the 78 JVM as two characters, which fails with ``No PEM key found``. It is a YAML 79 file instead, imported by ``application.yml`` through 80 ``spring.config.import``: 81 82 ``/etc/swiyu-verifier/secrets/signing-key.yml`` 83 ``application.signing_key``, the private key whose public half is published 84 in the verifier's DID document, as a block scalar. Mode 0640, 85 root:swiyu-verifier. Copy 86 ``/usr/share/swiyu-verifier/signing-key.yml.example`` to it. For a key in an 87 HSM, leave it out and set ``SIGNING_KEY_MANAGEMENT_METHOD`` and the 88 ``HSM_*`` variables in the environment file instead -- those are 89 single-line values. 90 91 Two further files are read by the service itself: 92 93 ``/etc/swiyu-verifier/application.yml`` 94 Spring Boot configuration for the few settings that have no environment 95 variable, and for pinning those that must not change with an upstream 96 default -- ``spring.jpa.hibernate.ddl-auto`` above all, which must stay 97 ``validate``. 98 99 ``/etc/swiyu-verifier/client_metadata.json`` 100 The OpenID4VP client metadata: the name and logo the wallet shows the user 101 when it asks for consent, and the credential formats and algorithms this 102 verifier accepts. ``${client-id}`` in it is replaced with ``VERIFIER_DID`` 103 at runtime. 104 105 106 Database 107 ======== 108 109 The service owns its schema and migrates it with Flyway on every start, so 110 upgrading this package is a restart and nothing more. The database and the 111 role it connects as are created once by swiyu-verifier-dbconfig(1). 112 113 The connection goes over TCP to localhost rather than the PostgreSQL socket, 114 because the JDBC driver cannot use ``peer`` authentication; that is why there 115 is a generated password at all. 116 117 118 Endpoints 119 ========= 120 121 ``/oid4vp/api/`` 122 The OpenID4VP interface the wallet talks to. It must be reachable from the 123 internet over HTTPS with a certificate from a publicly trusted CA -- the 124 SWIYU wallet accepts nothing else -- which is the reverse proxy's job, as 125 this service speaks plain HTTP. 126 127 ``/management/api/verifications`` 128 Creates a verification and retrieves its result. **Must not be reachable 129 from outside the host**: anybody who can reach it can create verifications 130 in this verifier's name. KyCH is its only intended user. 131 132 ``/actuator/health``, ``/actuator/prometheus`` 133 Health and metrics. ``/actuator/env`` echoes part of the configuration and 134 is therefore not exposed by the shipped ``application.yml``. 135 136 ``/swagger-ui.html`` 137 Interactive API documentation for the above. 138 139 140 Files 141 ===== 142 143 ``/usr/share/swiyu-verifier/swiyu-verifier.jar`` 144 The application. 145 146 ``/usr/share/swiyu-verifier/certs/root_ca_vi.crt`` 147 Swiss Government Root CA VI, as shipped by upstream. 148 149 ``/var/lib/swiyu-verifier/cacerts`` 150 The service's Java trust store, built by the package's ``postinst`` and 151 removed on purge. 152 153 154 Examples 155 ======== 156 157 Follow a verification through the logs: 158 159 .. code-block:: shell 160 161 $ sudo journalctl -u swiyu-verifier -f 162 163 Check that the service considers itself healthy, which includes resolving its 164 own DID in the identifier registry: 165 166 .. code-block:: shell 167 168 $ curl -s http://127.0.0.1:8080/actuator/health | python3 -m json.tool 169 170 Run it by hand on another port, as the service user, to try a configuration 171 change out: 172 173 .. code-block:: shell 174 175 $ sudo -u swiyu-verifier swiyu-verifier --server.port=8081 176 177 178 See Also 179 ======== 180 181 swiyu-verifier-dbconfig(1), kych-oauth2-gateway(1), kych.conf(5). 182 183 The operator manual at https://docs.taler.net/taler-swiyu-verifier-manual.html 184 covers onboarding to the SWIYU trust infrastructure, which has to happen 185 before this service can verify anything. 186 187 188 Bugs 189 ==== 190 191 Report bugs in the packaging by using https://bugs.taler.net/ or by sending 192 electronic mail to <taler@gnu.org>. Bugs in the verifier itself belong to its 193 upstream at https://github.com/swiyu-admin-ch/swiyu-verifier/issues.