README (4976B)
1 KYCH 2 ==== 3 4 KYCH is an OAuth2-based identity verification system that integrates with 5 the Swiss SWIYU trust infrastructure. It enables services like GNU Taler 6 exchanges to verify user identity through SD-JWT Verifiable Credentials, 7 supporting privacy-preserving selective disclosure. 8 9 For integration with GNU Taler, see documentation/taler-docs/. 10 11 12 Architecture 13 ------------ 14 15 The system consists of two main components working together: 16 17 +------------------+ +-------------------+ +---------------+ 18 | Service | | KYCH OAuth2 | | SWIYU | 19 | (e.g. Taler | <---> | Gateway | <---> | Verifier | 20 | Exchange) | | (Rust) | | (Java) | 21 +------------------+ +-------------------+ +---------------+ 22 ^ 23 | 24 v 25 +------------------+ 26 | SWIYU Wallet | 27 | (User's mobile) | 28 +------------------+ 29 30 1. KYCH OAuth2 Gateway (kych_oauth2_gateway/) 31 A Rust service implementing OAuth2 authorization code flow with 32 OpenID4VP (OID4VP) credential verification. 33 34 2. SWIYU Verifier (swiyu-verifier/) 35 The upstream SWIYU Generic Verifier, maintained by the Swiss 36 Confederation, as a git submodule pinned to a release tag, plus the 37 scripts and configuration for running it. Both components are packaged 38 for Debian from this tree, as "kych" and "swiyu-verifier". 39 40 The full interaction flow between a Taler exchange, the gateway, and the 41 verifier is documented in: 42 documentation/sequence_diagrams/swiyu_taler_sequence_diagram.txt 43 44 45 Components 46 ---------- 47 48 kych_oauth2_gateway/ Rust OAuth2 gateway service 49 swiyu-verifier/ The verifier: upstream submodule and setup scripts 50 taler-config/ Vendored GNU Taler configuration parser 51 debian/ Packaging for both components 52 documentation/ Technical specifications and sequence diagrams 53 54 55 Technology Stack 56 ---------------- 57 58 Gateway: Rust (Axum, Tokio, SQLx) 59 Verifier: Java 25, Spring Boot 4 (Java 21 up to verifier 4.2.0) 60 Database: PostgreSQL 61 Credentials: SD-JWT Verifiable Credentials (dc+sd-jwt) 62 Protocols: OAuth 2.0, OpenID4VP, DCQL 63 64 65 Standards 66 --------- 67 68 SD-JWT VC https://datatracker.ietf.org/doc/draft-ietf-oauth-sd-jwt-vc/ 69 OpenID4VP https://openid.net/specs/openid-4-verifiable-presentations-1_0.html 70 GNU Taler https://docs.taler.net/ 71 SWIYU Swiss e-ID Trust Infrastructure 72 73 74 Building 75 -------- 76 77 The tree builds with the usual sequence. ./bootstrap is only needed in a git 78 checkout -- a source tarball is ready to configure as unpacked: 79 80 ./bootstrap # fetch the verifier submodule 81 ./configure --prefix=$HOME/target # default prefix: /usr/local 82 make 83 make check 84 make install 85 86 ./configure reports the toolchain it found and writes .config.mk; "make help" 87 lists every target. A plain "make" without ./configure also works and uses 88 whatever cargo is on $PATH. 89 90 Two parts of the build are optional, and ./configure says so rather than 91 failing late: 92 93 * python3-sphinx renders the man pages from 94 documentation/taler-docs/manpages. Without it they are simply not built; 95 a source tarball ships them pre-built, so building from a tarball never 96 needs sphinx. 97 98 * The SWIYU verifier needs maven and a JDK 25, and its submodule checked 99 out. It is built when all three are present and skipped otherwise; pass 100 --enable-verifier to turn a missing one into a configure error, or 101 --disable-verifier to leave it out deliberately. 102 103 "make dist" writes kych-<version>.tar.gz: the tree as of HEAD, plus the 104 verifier submodule, the pre-built man pages and a .version file, so that a 105 build from it needs neither git nor sphinx. "make distcheck" unpacks that 106 tarball and runs the whole sequence above inside it. 107 108 Note that "make check" runs the unit tests always, but the two integration 109 suites in kych_oauth2_gateway/tests/ skip themselves unless DATABASE_URL names 110 a reachable PostgreSQL. They write to the live schema, so point them at a 111 throwaway database: 112 113 DATABASE_URL=postgres:///kych_test make check 114 115 116 Getting Started 117 --------------- 118 119 0. Fetch the verifier source: git submodule update --init 120 1. Set up the SWIYU Verifier - see swiyu-verifier/README 121 2. Configure and run the OAuth2 Gateway - see kych_oauth2_gateway/README 122 3. Review the technical documentation in documentation/ 123 124 For a deployment rather than a development setup, build the Debian packages 125 (debian/README.source) and follow debian/kych.README.Debian and 126 debian/swiyu-verifier.README.Debian. 127 128 Note that the gateway needs a verifier of release 3.0.0 or newer: it sends a 129 DCQL query, which replaced the DIF Presentation Exchange format that earlier 130 verifier releases used.