taler-www

2025-11.html.j2 (15011B)

---

 {% extends "common/news.j2" %}
 {% block body_content %}
 <h1>2025-10: Onboarding the Swiyu Trust Infrastructure as a Verifier</h1>
 
 <p>
 We are pleased to announce the availability of comprehensive documentation for integrating GNU Taler with the Swiyu trust infrastructure for digital identity verification. This integration will enable GNU Taler exchanges to perform Know Your Customer (KYC) processes using Switzerland's digital identity infrastructure, particularly relevant for regulatory compliance in Swiss financial services.
 </p>
 
 <p>
 This guide enables developers to onboard as credential verifiers in the Swiss digital identity ecosystem, enabling the verification of user identity attributes from Swiyu eID credentials.
 </p>
 
 <h2 id="about-swiyu">About Swiyu</h2>
 
 <p>
 <a href="https://swiyu-admin-ch.github.io/">Swiyu</a> is Switzerland's decentralized trust infrastructure for digital identity management. Swiyu is currently in public beta, allowing organizations to act as credential issuers or verifiers. The <a href="https://github.com/swiyu-admin-ch/swiyu-verifier">Generic Verifier</a> component enables registered third-party entities to request and verify identity attributes from Swiyu eID credentials.
 </p>
 
 <p>
 <strong>Important:</strong> Swiyu is in Public Beta and is provided on a best-effort basis. The system will continue to evolve over time.
 </p>
 
 <h2 id="architecture">System Architecture and Components</h2>
 
 <p>
 The Swiyu ecosystem consists of several key components that work together to enable secure digital identity verification:
 </p>
 
 <h3>Core Components</h3>
 
 <ul>
 <li><strong>Swiyu Base Registry:</strong> The foundational decentralized identifier (DID) registry that stores and manages DIDs for all participants in the ecosystem. This is where organizations register their identity and cryptographic keys.</li>
 <li><strong>Swiyu Wallet:</strong> Mobile application held by end users that stores their verifiable credentials (eID). The Swiyu wallet communicates with verifiers to present identity attributes upon request.</li>
 <li><strong>Issuers:</strong> Trusted entities (such as government agencies) that issue verifiable credentials to users' Swiyu wallets after identity verification.</li>
 <li><strong>Verifiers:</strong> Services operated by organizations that request and verify identity attributes from user Swiyu wallets.</li>
 <li><strong>DID Toolbox:</strong> A command-line tool for generating cryptographic keys and DID documents required for onboarding to the Base Registry.</li>
 </ul>
 
 <h3>How Components Interact</h3>
 
 <p>
 The verification flow works as follows:
 </p>
 
 <ol>
 <li>A <strong>Verifier Service</strong> creates a verification request specifying which identity attributes are needed (e.g., date of birth, name)</li>
 <li>The request is presented to the user's <strong>Swiyu wallet</strong> (typically via QR code)</li>
 <li>The <strong>Swiyu wallet</strong> displays which attributes are being requested and asks for user consent</li>
 <li>Upon consent, the <strong>Swiyu wallet</strong> presents the requested attributes from the user's credentials to the <strong>Verifier Service</strong></li>
 <li>The <strong>Verifier Service</strong> validates the credentials by checking signatures against the <strong>Base Registry</strong> and verifying the issuer is trusted</li>
 <li>The verified attributes are made available to the requesting business system (e.g., a Taler exchange's KYC module)</li>
 </ol>
 
 <p>
 All participants (issuers and verifiers) must register their DIDs in the <strong>Base Registry</strong> to participate in the trust infrastructure. The registry ensures that all cryptographic keys can be discovered and verified by other participants.
 </p>
 
 <h2 id="prerequisites">Prerequisites</h2>
 
 <p>Before deploying a <a href="https://github.com/swiyu-admin-ch/swiyu-verifier">generic verifier</a> in the beta, you must first onboard to the Swiyu Base Registry. Ensure you have:</p>
 
 <ul>
 <li>An AGOV or CH-Login account for accessing the ePortal</li>
 <li>Java Runtime Environment (JRE) 21 or higher installed</li>
 <li>Sufficient disk space (approximately 100 MB)</li>
 <li>Internet connection</li>
 <li>Operating system: Linux x64/AArch64, macOS (AArch64), or Windows (x64)</li>
 </ul>
 
 <h2 id="onboarding-process">Onboarding Process</h2>
 
 <p>The onboarding process consists of the following steps:</p>
 
 <ol>
 <li>Sign-in or sign-up to the Swiss Confederacy ePortal</li>
 <li>Register as Business Partner</li>
 <li>Get API keys from the self-service portal</li>
 <li>Allocate DID space on the Swiyu Base Registry</li>
 <li>Generate cryptographic keys and DID log using the Swiyu DID Toolbox</li>
 <li>Create and upload the DID log</li>
 <li>(Optional) Become a trusted participant</li>
 </ol>
 
 <p>
 The official Swiyu technical documentation offers detailed guides—cookbooks—that guide you through this process in a detailed manner. Follow <a href="https://swiyu-admin-ch.github.io/cookbooks/onboarding-generic-verifier/">this</a> cookbook to complete the necessary steps to onboard the Swiyu Base Registry before continuing.
 </p>
 
 <h2 id="configuring-the-swiyu-generic-verifier">Configuring the Swiyu Generic Verifier</h2>
 
 <p>
 With the Base Registry onboarding process complete, it is necessary to configure the <a href="https://github.com/swiyu-admin-ch/swiyu-verifier">Swiyu Generic Verifier</a> with the generated keys and DID obtained in the Base Registry Onboarding <a href="https://swiyu-admin-ch.github.io/cookbooks/onboarding-base-and-trust-registry/">cookbook</a>.
 </p>
 
 <h3>Locate the Configuration File</h3>
 
 <p>
 The Generic Verifier uses a YAML configuration file, located in <tt>/swiyu-verifier/verifier-application/src/main/resources/application.yml</tt>.
 </p>
 
 <h3>Understanding the Required Configuration Parameters</h3>
 
 <p>
 The configuration parameters are obtained from files generated during the Base Registry onboarding process. When you run the <a href="https://swiyu-admin-ch.github.io/cookbooks/onboarding-base-and-trust-registry/#quickstart--create-your-first-did">DID Toolbox</a> during onboarding, it creates a <tt>.didtoolbox</tt> directory containing the necessary files:
 </p>
 
 <ul>
 <li><strong>DID Log location:</strong> The DID log is generated by the DID Toolbox and saved as a JSONL (JSON Lines) file in the <tt>.didtoolbox</tt> directory. This file contains your DID and public key references in the format specified by the <a href="https://swiyu-admin-ch.github.io/cookbooks/onboarding-base-and-trust-registry/#quickstart--create-your-first-did">DID creation cookbook</a>.</li>
 <li><strong>Private keys location:</strong> Private keys are stored in separate PEM files within the <tt>.didtoolbox</tt> directory with names corresponding to their purpose (e.g., <tt>auth-key-01</tt>, <tt>agree-key-01</tt>, etc.).</li>
 </ul>
 
 <p>
 Extract the following parameters from these files for your Generic Verifier configuration:
 </p>
 
 <ul>
 <li><strong>client_id:</strong> Your DID identifier found in the <tt>value.id</tt> field of the DID log JSONL file. This is a unique identifier in the format <tt>did:tdw:&lt;hash&gt;:&lt;registry-domain&gt;:api:v1:did:&lt;uuid&gt;</tt></li>
 <li><strong>signing-key-verification-method:</strong> Your DID with the authentication key fragment appended. Found in the <tt>value.assertionMethod</tt> array in the DID log. The format is: <tt>&lt;your-did&gt;#auth-key-01</tt>. This specifies which key in your DID document is used for signing authorization requests.</li>
 <li><strong>signing-key:</strong> The private EC256 (Elliptic Curve P-256) authentication key from the file <tt>.didtoolbox/auth-key-01</tt>. This is a PEM-encoded private key used to sign requests sent to the Swiyu wallet. Copy the entire content including the <tt>-----BEGIN EC PRIVATE KEY-----</tt> and <tt>-----END EC PRIVATE KEY-----</tt> markers.</li>
 </ul>
 
 <h3>Example Configuration</h3>
 
 <p>
 Create your configuration profile by copying the template from the local deployment YAML in the repository (<tt>application-local.yml</tt>). After replacing with your specific values, the <tt>application.yaml</tt> configuration will look similar to this:
 </p>
 
 <pre><code>application:
   signing-key: |
     -----BEGIN EC PRIVATE KEY-----
     MHcCAQEEIABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstu
     oAoGCCqGSM49AwEHoUQDQgAE5cice+6ILYCD2gFEVFMLPt3HPf5n/Oef
     zOOoP+3SLDAlh/YkKQvF/1xv0uYuvy1t6wpDM7au1dMEg2L1I9wDxE==
     -----END EC PRIVATE KEY-----
   signing-key-verification-method: "did:tdw:
     Qmd9bwsodZ1GAz4h8D7Vy6qRio78voXifDrnXokSTsMVQK:
     identifier-reg.trust-infra.swiyu-int.admin.ch:api:v1:
     did:18fa7c77-9dd1-4e20-a147-fb1bec146085#auth-key-01"
   external-url: "https://yourdomain.com"
   client_id: "did:tdw:
     Qmd9bwsodZ1GAz4h8D7Vy6qRio78voXifDrnXokSTsMVQK:
     identifier-reg.trust-infra.swiyu-int.admin.ch:api:v1:
     did:18fa7c77-9dd1-4e20-a147-fb1bec146085"
   client_id_scheme: "did"
   client-metadata-file: "classpath:/client_metadata.json"
 </code></pre>
 
 <p>
 To make sure the Generic Verifier uses your configuration, specify your <tt>.yaml</tt> run profile when booting the server:
 </p>
 
 <pre><code>./mvnw spring-boot:run -pl verifier-application -Dspring-boot.run.profiles=application
 </code></pre>
 
 <p>Where 'application' is the name of your configuration <tt>.yaml</tt> file.</p>
 
 <h2 id="https-configuration">HTTPS/TLS Configuration</h2>
 
 <p>
 <strong>Important:</strong> The Swiyu wallet only accepts HTTPS connections. Ensure your verifier is accessible via HTTPS with a valid TLS/SSL certificate from a trusted Certificate Authority.
 </p>
 
 <h2 id="testing">Testing Your Verifier Setup</h2>
 
 <p>
 Once your verifier is configured and running, you should test the complete verification flow to ensure everything works correctly. This section guides you through obtaining a test wallet, getting test credentials, and performing a verification.
 </p>
 
 <h3>1. Get the Swiyu Wallet</h3>
 
 <p>
 Download the Swiyu BetaID wallet application for your mobile device (iOS or Android). Links can be found under 'Information for private individuals' <a href="https://www.eid.admin.ch/en/public-beta-e">here</a>.
 </p>
 
 <p>
 Install the app and complete the initial setup by setting your password and optionally setting a biometric login with your fingerprint. Since Swiyu is in public beta, you will need to obtain a BetaID credential directly:
 </p>
 
 <ol>
 <li>Follow the link displayed after the initial setup to the Beta-ID <a href="https://www.bcs.admin.ch/bcs-web/#/">website</a></li>
 <li>Request</a> a Beta-ID</a>
 <li>Choose a Beta-ID from a template (Helvetia or Marco), optionally upload a ID picture</li>
 <li>Click the 'Request the issuing of a Beta-ID' button and then the 'Add to wallet' button</li>
 <li>Once back in the Swiyu wallet app, click on 'Add' to add the Beta-ID to your wallet</li>
 </ol>
 Congratulations! Your unique Beta-ID is now on your wallet (and nowhere else!).
 
 <h3>2. Create a Verification Request</h3>
 
 <p>
 With your verifier service running, create a test verification request using the management API. The following example verification request can be performed using <tt>curl</tt> to verify if a user is over 18 years old:
 </p>
 
 <pre><code>curl -X POST https://your-verifier-domain.com/management/api/verifications \
   -H "Content-Type: application/json" \
   -d '{
     "jwt_secured_authorization_request": true,
     "response_mode": "direct_post",
     "response_type": "vp_token",
     "presentation_definition": {
       "id": "00000000-0000-0000-0000-000000000000",
       "name": "Over 18 Verification",
       "purpose": "Verify age is over 18",
       "input_descriptors": [
         {
           "id": "11111111-1111-1111-1111-111111111111",
           "format": {
             "vc+sd-jwt": {
               "sd-jwt_alg_values": ["ES256"],
               "kb-jwt_alg_values": ["ES256"]
             }
           },
           "constraints": {
             "fields": [
               {
                 "path": ["$.vct"],
                 "filter": {
                   "type": "string",
                   "const": "betaid-sdjwt"
                 }
               },
               {
                 "path": ["$.age_over_18"]
               }
             ]
           }
         }
       ]
     },
     "configuration_override": {}
   }'
 </code></pre>
 
 <p>
 This request asks the Swiyu wallet to provide proof that the user is over 18 years old from their BetaID credential.
 </p>
 
 <h3>3. Generate and Scan QR Code</h3>
 
 <p>
 The verification request response will contain a verification ID. You need to convert the request URL in the response to a QR code for the Swiyu wallet to scan. The request URL format is:
 </p>
 
 <pre><code>https://your-verifier-domain.com/oid4vp/api/request-object/&lt;verificationId&gt;</code></pre>
 
 <p>
 For example, if your verification ID is <tt>abc123def456</tt>, the URL would be:
 </p>
 
 <pre><code>https://your-verifier-domain.com/oid4vp/api/request-object/abc123def456</code></pre>
 
 <p>
 Convert this URL to a QR code using for example <a href="https://fukuchi.org/en/works/qrencode/">qrencode</a> (a CLI QR code generation tool available in most package managers):
 
 </p>
 
 <ol>
 <li>Install qrencode if not already available:
 <pre><code># macOS, requires homebrew
 brew install qrencode
 
 # Ubuntu/Debian
 sudo apt-get install qrencode</code></pre>
 </li>
 <li>Generate a QR code PNG from your the terminal:
 <pre><code>qrencode -o verification-qr.png "https://your-verifier-domain.com/oid4vp/api/request-object/abc123def456"</code></pre>
 </li>
 <li>Open your Swiyu wallet app and scan the generated QR code</li>
 </ol>
 
 <h3>4. Complete the Verification</h3>
 
 <p>
 After scanning the QR code:
 </p>
 
 <ol>
 <li>The Swiyu wallet will display which attributes are being requested</li>
 <li>Review the request and tap to approve sharing the requested attributes</li>
 <li>The Swiyu wallet sends the selected Beta-ID attributes to your verifier service</li>
 </ol>
 
 <h3>5. Check Verification Results</h3>
 
 <p>
 Query your verifier's management API to retrieve the verification results:
 </p>
 
 <pre><code>curl https://your-verifier-domain.com/management/api/verifications/&lt;verificationId&gt;
 </code></pre>
 
 <p>
 A successful verification will show a status indicating completion, along with the verified attributes that were presented by the Swiyu wallet.
 </p>
 
 <h3>Troubleshooting</h3>
 
 <p>Here are some common errors you might encounter during the configuration of the generic verifier and during QR code generation and scanning:</p>
 
 <ul>
 <li><strong>Swiyu wallet cannot connect:</strong> Ensure your verifier is accessible via HTTPS with a valid certificate</li>
 <li><strong>Verification fails:</strong>The format of the signing key in the .yaml configuration of your Verifier must be exactly as specified in the example configuration file and cannot contain literal <tt>\n</tt> escape sequences or extra quotation marks (<tt>"</tt>). The signing key field should use YAML's multiline string format with the pipe (<tt>|</tt>) operator.</li>
 </ul>
 
 {% endblock body_content %}