swiyu-verifier.README.Debian (7797B)
1 swiyu-verifier for Debian 2 ========================= 3 4 This package builds and installs the SWIYU Generic Verifier, the service 5 maintained by the Swiss Confederation that performs the actual OpenID4VP 6 credential verification. It is a separate upstream from KyCH 7 (https://github.com/swiyu-admin-ch/swiyu-verifier), pinned to a release tag 8 in the swiyu-verifier/upstream submodule of the KyCH source package. 9 10 The service is installed disabled and cannot work until it has an identity of 11 its own in the SWIYU trust infrastructure. There is no way around that step: 12 a verifier signs its authorization requests with a key that wallets check 13 against its DID document in the Base Registry. 14 15 1. Onboard 16 ---------- 17 18 Follow the official cookbook, 19 20 https://swiyu-admin-ch.github.io/cookbooks/onboarding-generic-verifier/ 21 22 which walks through the Swiss Confederacy ePortal account, the business 23 partner registration, the API keys, the DID space, generating the key pair 24 and uploading the DID log. The operator manual at 25 https://docs.taler.net/taler-swiyu-verifier-manual.html summarises it. 26 27 You end up with three things: a DID, the identifier of the verification 28 method inside it, and the private key. 29 30 2. Create the database 31 ---------------------- 32 33 swiyu-verifier-dbconfig 34 35 That creates the role "swiyu_verifier" with a generated password, the 36 database of the same name owned by it, and writes the password to 37 /etc/swiyu-verifier/secrets/db.env (0640 root:swiyu-verifier). 38 39 The connection is over TCP to localhost, not the PostgreSQL socket, because 40 the JDBC driver cannot do peer authentication -- which is the only reason 41 there is a password at all. 42 43 The schema is not created here: the verifier runs its own Flyway migrations 44 on every start. That is also why an upgrade of this package needs nothing 45 but the restart it already does. 46 47 3. Configure 48 ------------ 49 50 /etc/swiyu-verifier/swiyu-verifier.env the package's defaults and 51 the reference for what can 52 be set -- do not edit 53 /etc/swiyu-verifier/local.env YOUR settings; read last, so 54 it overrides the above 55 /etc/swiyu-verifier/secrets/signing-key.yml the signing key 56 /etc/swiyu-verifier/secrets/db.env written by the step above 57 /etc/swiyu-verifier/application.yml Spring settings without an 58 environment variable 59 /etc/swiyu-verifier/client_metadata.json name and logo the wallet shows 60 61 Writing into local.env rather than the shipped file is not a matter of taste: 62 swiyu-verifier.env is a conffile, so an upgrade that changes it has to ask 63 what to do about your edits, and an unattended upgrade will then either stop 64 and wait or quietly pick one side. local.env belongs to nobody but you. 65 66 The environment file is commented throughout; what you must set -- in 67 local.env -- is 68 69 EXTERNAL_URL the public HTTPS URL of this verifier 70 VERIFIER_DID your DID 71 DID_VERIFICATION_METHOD the verification method in it 72 73 for example 74 75 cat > /etc/swiyu-verifier/local.env <<EOF 76 EXTERNAL_URL=https://verifier.example.com 77 VERIFIER_DID=did:tdw:QmExample:identifier-reg.trust-infra.swiyu.admin.ch:api:v1:did:0000 78 DID_VERIFICATION_METHOD=did:tdw:QmExample:identifier-reg.trust-infra.swiyu.admin.ch:api:v1:did:0000#auth-key-01 79 WEBHOOK_CALLBACK_URI=https://kych.example.com/notification 80 EOF 81 chmod 0640 /etc/swiyu-verifier/local.env 82 chown root:swiyu-verifier /etc/swiyu-verifier/local.env 83 84 The key goes in a file of its own, because a PEM document has newlines and 85 an environment file cannot carry those: 86 87 cp /usr/share/swiyu-verifier/signing-key.yml.example \ 88 /etc/swiyu-verifier/secrets/signing-key.yml 89 editor /etc/swiyu-verifier/secrets/signing-key.yml 90 systemd-tmpfiles --create swiyu-verifier.conf # re-applies 0640 root:swiyu-verifier 91 92 It is YAML, and the block scalar is what makes the key work: 93 94 application: 95 signing_key: | 96 -----BEGIN EC PRIVATE KEY----- 97 MHcC... 98 -----END EC PRIVATE KEY----- 99 100 For a key in an HSM, leave that out and set SIGNING_KEY_MANAGEMENT_METHOD and 101 the HSM_* variables in swiyu-verifier.env instead; see swiyu-verifier(1). 102 103 Two defaults deserve a decision rather than being left alone: 104 105 * SWIYU_TRUST_REGISTRY_API_URL points at the swiyu-int *sandbox*. Switch 106 it to production before serving real credentials. 107 * WEBHOOK_CALLBACK_URI is unset, so nothing is told about a finished 108 verification. With KyCH behind a reverse proxy on the same host this is 109 that proxy's /notification path. 110 111 4. Start it 112 ----------- 113 114 systemctl enable --now swiyu-verifier 115 systemctl status swiyu-verifier 116 curl -s http://127.0.0.1:8080/actuator/health 117 118 The health endpoint resolves your own DID in the identifier registry, so it 119 is the quickest check that onboarding actually worked. A JVM with a cold 120 Spring context and a Flyway migration to run takes a few seconds to answer. 121 122 If the service fails to start five times -- almost always a configuration 123 that cannot work, a missing signing key above all -- systemd stops trying. 124 After fixing the cause: 125 126 systemctl reset-failed swiyu-verifier 127 systemctl start swiyu-verifier 128 129 Reverse proxy 130 ------------- 131 132 The service listens on 127.0.0.1:8080 and speaks plain HTTP. Two parts of it 133 belong on different sides of the firewall: 134 135 /oid4vp/api/ must be reachable from the internet over HTTPS with a 136 publicly trusted certificate -- the SWIYU wallet 137 accepts nothing else 138 /management/api/ must NOT be reachable from outside the host; anybody 139 who can reach it can create verifications in your 140 verifier's name 141 /actuator/ likewise internal; /actuator/env echoes part of the 142 configuration 143 144 For nginx, that is 145 146 location /oid4vp/ { 147 proxy_pass http://127.0.0.1:8080; 148 proxy_set_header Host $host; 149 proxy_set_header X-Forwarded-Proto $scheme; 150 } 151 152 and nothing else proxied. EXTERNAL_URL must be the URL this location is 153 served at, because it is what the verifier puts into the QR code. 154 155 Working with KyCH 156 ----------------- 157 158 In /etc/kych/kych.conf, the client section points at this service's 159 management API: 160 161 VERIFIER_URL = http://localhost:8080 162 VERIFIER_MANAGEMENT_API_PATH = /management/api/verifications 163 164 then "kych-client-management -c /etc/kych/kych.conf sync". 165 166 Note that KyCH requires a verifier of release 3.0.0 or newer: it sends a DCQL 167 query, which replaced the DIF Presentation Exchange format that older 168 verifiers used. 169 170 Logs go to the journal: 171 172 journalctl -u swiyu-verifier -f 173 174 Removing the package 175 -------------------- 176 177 A purge removes the conffiles, as always -- which means the identity settings 178 in swiyu-verifier.env go with it. Two things do *not* go, because the package 179 does not own them: 180 181 * /etc/swiyu-verifier/secrets/signing-key.yml and .../db.env, which are 182 written by you and by swiyu-verifier-dbconfig. Delete them by hand if 183 the host is not to keep the key. 184 * the swiyu_verifier database. "swiyu-verifier-dbconfig -r" drops and 185 recreates it; dropping it for good is 186 "sudo -u postgres dropdb swiyu_verifier". 187 188 189 Upstream version 190 ---------------- 191 192 dpkg -s swiyu-verifier | grep ^Version 193 194 carries the KyCH version, not the verifier's. The verifier release that was 195 built is recorded in /usr/share/doc/swiyu-verifier/copyright and in the 196 submodule the package was built from; the running service reports it at 197 /actuator/info. 198 199 -- Taler Systems SA <deb@taler.net>