This document describes how to use the ZETA SDK, and how to build and run the provided test- and demo-clients.

The ZETA Client SDK is designed to be integrated into existing and new client applications that need to access a TI service based on the new Zerotrust (or ZETA) architecture.

The SDK aims to encapsulate the ZETA requirements and shield the application from it, while at the same time allowing the client to reuse existing functionality that may already be implemented, like the specific storage, configuration, or getting an SM(C)-B token. While implementations for those topics are provided, due to the modular nature and the configuration parameters when instantiating the ZETA SDK, client-specific implementations can be injected into the SDK.

The client is written in kotlin multiplatform, to provide a single implementation of the ZETA functionality, but providing examples on how the client can be integrated into a Java application and as a C++ library.

The following sections give an overview on the repository content, as well as how to build the different clients and how to use them.

[[TOC]]

The Zeta Client SDK is build with Kotlin Multiplatform (KMP) to target multiple platforms (iOS, Android and JVM), while reducing the duplicated code. By sharing core logic across platforms, minimizing the maintenance overhead and ensure consistent behaviour for all clients.

Folders for core SDK functionality and clients.

The different clients serve different purposes:

• The demo client is a pure kotlin client and running in a JVM, and features all the functions to access the test Fachdienst
• The proxy client is running in a container and works as an HTTP proxy, to be used in testing.
• The Java client is a Proof-of-concept and shows how to configure and use the client from a Java application, but only implements the hellozeta call of the test Fachdienst.
• The C++ client demonstrates how to integrate the SDK from a C++ application. It implements HTTP CRUD (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS) and WebSocket STOMP communication with a resource server.

The clients, how to build and how to use them are described in more detail below.

Here are the folders for the different modules:

The different modules contain, depending on the respective setup, platform-specific subfolders.

Here an example from the network module:

The different subfolders contain either commonly used code, which is at least the API of the module, or the platform specific implementations

If you want to include the SDK into your own kotlin projects, you can get it from a maven repository already.

To do this, add this dependency to your maven pom file:

<!-- https://mvnrepository.com/artifact/de.gematik.zeta/zeta-sdk-jvm -->
<dependency>
  <groupId>de.gematik.zeta</groupId>
  <artifactId>zeta-sdk</artifactId>
  <version>x.y.z</version>
</dependency>

Here is The Maven repository homepage.

If you want to include the SDK into your own Java projects, you can get it from a maven repository already.

To do this, add this dependency to your maven pom file:

<!-- https://mvnrepository.com/artifact/de.gematik.zeta/zeta-sdk-jvm -->
<dependency>
  <groupId>de.gematik.zeta</groupId>
  <artifactId>zeta-sdk-jvm</artifactId>
  <version>x.y.z</version>
</dependency>

Note that the artifactId has an additional -jvm compared to the kotlin version.

Here is The Maven repository homepage.

The build process for the C++ SDK creates a number of DLL files, that need to be linked to your C++ application. This highly depends on your own build process.

The C++ API is defined in a single generated header file:

• libzeta_sdk_api.h (Linux / macOS)
• zeta_sdk_api.h (Windows)

This header is automatically generated and enriched with the SDK type definitions during the SDK build process.

The next sections contain information about the clients.

All clients implement at least the "hellozeta" call to show how the integration of the kotlin code/library is done. The Java client is a proof-of-technology client that implements the hellozeta call and WebSocket STOMP communication. The C++ native client additionally implements full HTTP CRUD operations (GET, POST, PUT, DELETE, HEAD, OPTIONS).

The demo-client can use the functional interface of the Test Fachdienst (test resource server), and can thus create presciptions, show them, modify them, and delete them.

The testdriver is a proxy client that just forwards the HTTP(S) requests it receives to the given resource server, but using the PEP endpoint and the necessary ZETA and ASL protocols. In addition, it also provides the websockets interface. It can be run in a container, allowing for easy proxying of functional test clients through ZETA SDK and ZETA Guard to an actual resource server. A ready to use container image is provided.

The Java and C++ clients are proof-of-technology clients that only implement the "hellozeta" call, to show how the SDK can be integrated into clients with this technology. In addition, they use the websockets functionality to connect to the test resource server.

The build process is using the gradle tool. It can be customized using some values in the "gradle.properties" and the "local.properties" file.

Before building any client that depends on the SDK via Maven, publish it to the local Maven repository:

./gradlew publishJvmPublicationToMavenLocal

The gradle.properties file contains switches that enable or disable building some of the platforms. These can be used to improve the build speed.

de.gematik.zeta.sdk.build-logic.enableAndroid=true
de.gematik.zeta.sdk.build-logic.enableIOS=true
de.gematik.zeta.sdk.build-logic.enableNative=true

Here the "enableNative" switch enables the C++ build components.

In the local.properties file the location of the Android Sdk can be set, for example like so on a windows machine:

sdk.dir=C\:\\Users\\ABCDE\\AppData\\Local\\Android\\Sdk

All clients use the same set of configuration values, which are described here. These are either configured as environment variables, or in a configuration file.

Note that these items only concern the provided demo- and test-clients. In a real client (like a practice management system) these should be provided by the "surrounding" client application.

Here are the items you need to adapt:

Note that two sets of configuration variables for the SM(C)-B client authentication are provided, one for the SM-B certificate file, another for the SMC-B connector interface.

Only one set of these needs to be provided

The demo client shows the use of the SDK in a kotlin multiplatform environment. It implements the functionality that is exposed by the Test-Fachdienst.

• A PC with Windows, Linux, or Mac
• Installed Java Development Kit (JDK)
• git client to clone the source repo, or a copy of the source repo content
• Installed Android Software Development Kit (SDK) with configured ANDROID_HOME environment variable (optional)

Note: the SDK and the test client can be built without Android SDK.

The main configuration of the test client are the

• Endpoint of the Fachdienst
• SM-B file location, alias and password

Those are being provided using a configuration file or environment variables.

After creating the configuration file the test client can be started like so:

./gradlew :zeta-client:jvmRun -DmainClass="de.gematik.zeta.client.ZetaClientAppKt" --args='--ZETA_ENV_FILE=<Name-der-Parameter-Datei>

The parameter file contains the configuration parameters as described above:

ENVIRONMENTS=<resource_server_1_api_endpoint> <resource_server_2_api_endpoint> ...

SMB_KEYSTORE_FILE=<sm-b-keystore-file>.p12
SMB_KEYSTORE_ALIAS=<key-alias-im-keystore-file>
SMB_KEYSTORE_PASSWORD=<keystore-password>

POPP_TOKEN=eyJhbGciOiJ......
...

Note: the resource server URL is here named differently as 'ENVIRONMENTS', as there are multiple resource servers possible, not just a single 'FACHDIENST_URL'

The variable 'ENVIRONMENTS' thus contains multiple resource server endpoints, separate by a space. These can be selected in the UI of the demo client.

This step does not need an Android SDK.

./gradlew publishJvmPublicationToMavenLocal
./gradlew publishKotlinMultiplatformToMavenLocal

Hinweis: sollten Sie das ZETA SDK in ein eigenes Remote Repository submitten wollen, so müssen sie die folgende Konfiguration in der build-logic anpassen:

The full tests and setups need an Android SDK:

./gradlew build

./gradlew testAll

In this section we describe how you can create a container with a proxy client containing the SDK and exposing the SDK APIs and other test-related actions as HTTP endpoints. This proxy client is used in various test situations.

Here is an overview on how the proxy client sits between a test driver and the zeta guard. The purpose of the proxy client is to encapsulate the ZETA protocol and make testing of the zeta guard setup easier.

TODO: diagram how the proxy client sits between a test driver and the zeta guard

Requests to the Fachdienst enter the proxy client as normal HTTP requests, get forwarded to the ZETA guard using the ZETA and optionally ASL protocol, the ZETA guard validates them and forwards them to the Fachdienst backend. This facilitates end-to-end testing and testing whether the ZETA guard setup is correct.

The proxy client exposes a number of HTTP endpoints that allow on one side forwarding requests to the Fachdienst, but also control the client and extract information necessary for testing.

Note: in coming project milestones the paths may change or be extended to accomodate for multiple client instance running in parallel

Note that building the container image in an automated CI/CD process is preferred over these manual steps. The file .gitlab-ci.yml shows how this can be done.

In general the requisites are required for building the test driver as are for the demo client.

• A PC with Windows, Linux, or Mac
• Installed Java Development Kit (JDK)
• git client to clone the source repo, or a copy of the source repo content
• Installed Android Software Development Kit (SDK) with configured ANDROID_HOME environment variable (optional)

Also this tools is required to create the container image:

• Docker build Tool

The necessary libraries can be built with

./gradlew clean jar copyRuntimeLibs

The artifacts are then in

**/build/libs/*.jar
**/build/runtime-libs/*.jar

The container can then be built using the dockerfile:

docker build -f zeta-testdriver/Dockerfile .

The container can be built using the deployment.yml described here.

The configuration items in the deployment.yml file that need to be set are described above in the Configuration section.

In the example below these configuration items are set via helm variables, so they can be used depending on the environment.

The SMB keystore file is being mounted as kubernetes secret.

Other values are also set by helm variables, like the used image repository, version, etc.

A helm chart template for the Deployment descriptor can be found in the gematik ZETA github repository This folder includes examples for the ingress and the service definitions.

The continuous integration pipeline can be set up with the included .gitlab-ci.yml file, that you need to adapt to your development process.

.gitlab-ci.yml

This load driver extends the test driver functionality to support concurrent testing scenarios with independent SDK instances.

• Supports multiple SDK instances with independent state
• Per-instance configuration via CONFIG_FILE file

The load driver exposes endpoints:

Instances can be configured by passing configuration in the POST body to /load/create_instances

curl -X POST http://0.0.0.0:8080/load/create_instances \
  -H "Content-Type: application/json" \
  -d '{
    "count": 3,
    "autoInit": true,
    "instances": [
      {
        "id": 1,
        "fachdienstUrl": "https://example/pep/resource1/",
        "smbKeystoreFile": "/keystores/keystore1.p12",
        "smbKeystoreAlias": "cert1",
        "smbKeystorePassword": "secret1"
      },
      {
        "id": 2,
        "fachdienstUrl": "https://example/pep/resource2/",
        "smbKeystoreFile": "/keystores/keystore2.p12",
        "smbKeystoreAlias": "cert2",
        "smbKeystorePassword": "secret2"
      }
    ]
  }'

Response:

{
  "created": 2,
  "ids": [1, 2],
  "autoInit": true
}

You can then access instances using their IDs:

• http://0.0.0.0:8080/load/1/hellozeta (uses instance 1)
• http://0.0.0.0:8080/loaddriver-api/2/reset (resets instance 2)

NOTE: Custom instance IDs can be specified (optional)

The location of the config file can be configured via the CONFIG_FILE environment variable.

Instances can be configured individually via the CONFIG_FILE file with instance-specific properties:

# Instance 1 configuration
FACHDIENST_URL_1=https://example/pep/resource1/
SMB_FILE_1=/keystores/keystore1.p12
SMB_ALIAS_1=cert1
SMB_PASSWORD_1=secret1

# Instance 2 configuration
FACHDIENST_URL_2=https://example/pep/resource1/
SMB_FILE_2=keystores/keystore2.p12
SMB_ALIAS_2=cert2
SMB_PASSWORD_2=secret2

Note: If the CONFIG_FILE file contains instance 1 configuration, the test driver (non-load) will use those values instead of environment variables.

Configuration is resolved in this order:

1. API body (instances array in POST request)
2. Config file (CONFIG_FILE environment variable)
3. Environment variables (fallback)

The Java client shows how the ZETA SDK can be integrated into a Java-based application. It implements only the "hellozeta" call of the Test Fachdienst.

The Java class "Main" in zeta-client-java/main/java/de/gematik/zeta shows how the integration can be done.

The Java client can be built with

./gradlew zeta-client-java:build

and it can be run with

./gradlew zeta-client-java:run

Without any command line parameters, the configuration (as described above) needs to be provided with environment variables.

It if is run with a command line argument of a configuration file like so:

./gradlew zeta-client-java:run --args='config.file'

Then it will read the configuration from the given filename.

Note: when run from gradle, the filename is relative to the build directory, use an absolute path, or relative to the build directory, like ../config.file

The C++ client shows how the ZETA SDK can be integrated into a C++ application. It implements HTTP CRUD operations and WebSocket STOMP communication with a resource server.

The client is located in zeta-nativeclient-cpp/ and consists of:

• hello-http.cpp — HTTP client sample (GET, POST, PUT, DELETE, HEAD, OPTIONS)
• hello-ws.cpp — WebSocket client sample (STOMP connect, subscribe, create, read)
• Makefile — cross-platform build and run

The Makefile assumes the following folder structure:

zeta-sdk/
├── zeta-sdk/              <- SDK module
│   └── build/bin/
│       ├── macosArm64/debugShared/
│       ├── linuxX64/debugShared/
│       └── mingwX64/debugShared/
└── zeta-nativeclient-cpp/ <- C++ client
    ├── hello-http.cpp
    ├── hello-ws.cpp
    ├── Makefile
    └── .env

The Makefile automatically detects the OS and points to the correct SDK build output:

• macOS (Apple Silicon) → macosArm64/debugShared
• Linux → linuxX64/debugShared
• Windows → mingwX64/debugShared

If your folder structure is different, update the LIB_DIR variable in the Makefile accordingly.

• macOS / Linux: clang++ or g++, make
• Windows: MinGW (g++), mingw32-make

Create a .env file in the zeta-nativeclient-cpp/ folder (add to .gitignore):

FACHDIENST_URL=https://...
SMB_KEYSTORE_FILE=/path/to/keystore.p12
SMB_KEYSTORE_ALIAS=alias
SMB_KEYSTORE_PASSWORD=password
POPP_TOKEN=
ASL_PROD=false
WS_BASE_URL=wss://...
WS_SERVER_CONTEXT_PATH=/context

First build the SDK shared library:

./gradlew :zeta-sdk:linkDebugSharedMacosArm64   # macOS
./gradlew :zeta-sdk:linkDebugSharedLinuxX64     # Linux
./gradlew :zeta-sdk:linkDebugSharedMingwX64     # Windows

After building the SDK shared library, the output will be located at:

Then build and run the C++ client:

#macOs Linux
make run-http
make run-ws

# Windows
mingw32-make run-http
mingw32-make run-ws

On macOS and Linux, the library path is set automatically via RPATH at compile time. On Windows, make run-http will also copy zeta_sdk.dll next to the .exe automatically.

Here are the steps to build the C++ client

1. building docker image (needs to be done only once)

   docker build --platform linux/amd64 \
       -t zeta-cpp-dev \
       -f Dockerfile.cpp-dev .

2. Container starten (vom zeta-sdk Ordner):

   docker run -it \
       --platform linux/amd64 \
       --ulimit nofile=65536:65536 \
       -v $(pwd):/workspace \
       zeta-cpp-dev

3. Im Container den C++ Client bauen:

   ./gradlew :zeta-client-cpp:linkDebugSharedLinuxX64  // <— compile
   ./gradlew :zeta-client-cpp:runDebug  // <— run

Notes:

• --platform linux/amd64 is only used when using a Mac with Apple Silicon
• --ulimit is required to avoid the error "Too many open files"
• During the first start gradle downloads the Kotlin Native Toolchain (~ 300MB)

The C# client has its own README file.

NOTE: this will only be relevant in a later version of the specification! It is currently not used or required.

The attestation service is a service that runs locally alongside the Zeta SDK client. It provides TPM-based attestation capabilities for Windows and Linux, allowing the SDK to perform platform attestation as part of the ZETA protocol.

The SDK communicates with the attestation service locally to perform TPM operations, such as quote generation and PCR-based attestation. The endpoint of the attestation must be configured in the SDK configuration so the SDK can connect to it.

• A PC with Windows or Linux
• Installed JDK
• OpenSSL 3.X installed (libcrypto)

The TSS2 libraries (tpm2-tss) are bundled as static libraries within the project and do not need to be installed separately. At runtime, the attestation service requires access to a TPM 2.0 device.

The attestation service uses its own configuration file, and can also be configured via command line arguments.

FILES=/path/to/file1,=/path/to/file1
SERVER_PORT=8081
PCR_ID=23
ALLOWED_EXECUTABLES=/usr/bin/app1

./gradlew :attestation-service:linkReleaseExecutableLinux64

The attestation serivice exposes the following HTTP and Websocket endpoints:

The ZETA SDK consists of a number of modules as described above. The entry into the ZETA-SDK is the class ZetaSdk. It provides a builder interface that can be used to configure the SDK.

The build interface includes the URL of the resource server. Using different URLs, a client can create multiple instances of the SDK, one per resource server.

The following example shows in the kotlin version how a resource can be called.

The configuration includes config objects that allow reusing existing functionality where available. For example, we assume that a client implementation in the context of the TI already has ways to store items securely, or how to create an SM(C)-B token. So these functions can be injected.

The exact configuration items are described in the sourcecode.

class ZetaSdkTest {
    @Test
    @Ignore
    fun sdk_halloZetaTest() = runTest {
        // Arrange
        val sdk = ZetaSdk.build(
            "https://<resource-url>",
            BuildConfig(
                "demo-client",
                "0.2.0",
                "client-sdk",
                StorageConfig(aesB64Key = "7aae7xXr8rnzVqjpYbosS0CFMrlprkD7jbVotm0fd"),
                object : TpmConfig {},
                AuthConfig(
                    listOf(
                        "zero:audience",
                    ),
                    30,
                    true,
                    SmbTokenProvider(SmbTokenProvider.Credentials("", "", "")),
                    AttestationConfig.software(),
                    requiredRoleOid = "1.2.276.0.76.4.156",
                ),
            ),
        )

        // Act
        val client = sdk.httpClient {
            logging(
                LogLevel.ALL,
                object : Logger {
                    override fun log(message: String) {
                        println("log:" + message)
                    }
                },
            )
        }

        val helloResult = client.get("/hellozeta")
            .bodyAsText()
    }
}

This section gives an overview on how to use the API. More details can be found in the source code.

Note: this API is an intermediary target API and can deviate from the API in tne source code, depending on the state of the implementation according to the project milestones.

The ZETA API offers the following public API:

Inside the HTTP operations as provided by the HttpClient, the discovery, client registration and authentication are performed automatically. The methods discover(), register(), and authenticate() are idempotent. Providing them separately allows the client to implement flexible UI flows in case there is any client interaction needed. For example the authentication could be done at start without an actual call to the Fachdienst, so that any later Fachdienst call is then uninterrupted by manual interaction.

The status() method returns one of the following values:

The configuration is done by passing the BuildConfig object to the ZetaSdkClient. This object contains the following attributes and sub-objects.

Note: in implementation phase 1 callbacks are not expected. In implementation phase 2 callbacks may be added e.g. for pushed authentication requests to the IDP. Details are still to be determined.

The AuthConfig object configures the authentication process:

The attestation config allows three attestation modes:

Configures how the SDK stores session data. There are two mutually exclusive options:

Uses the SDK's built-in encrypted storage. This is the recommended option for production.

• Must be a Base64-encoded string
• Must decode to exactly 32 bytes (256 bits)
• Passing an invalid key will cause a runtime error during encryption/decryption

If the decoded key is not exactly 32 bytes, the SDK will throw: IllegalArgumentException: Key must be 32 bytes

Security notice: Keep this key secret. Store it in a secure vault or environment variable, do not hardcode it in source code.

Delegates storage entirely to your own implementation of SdkStorage. When using this option, encryption is the responsibility of the provided implementation.

This is useful for testing or environments where you manage persistence yourself:

val config = StorageConfig.Custom(provider = MemoryStorage())

You can provide your own implementation by injecting a custom connector via the AuthConfig. This is useful when you already have an existing SMC-B connector implementation, or when you want to control how the certificate and signing operations are performed.

Interface:

By default, the SDK uses platform-specific encrypted storage. You can replace this with your own storage implementation. When using a custom storage provider, encryption is the responsibility of the implementation - the aesB64Key is ignored. All pointers must remain valid for the lifetime of the SDK instance.

Interface:

By default, the SDK logs to stdout. You can redirect log output to your own logging system. The default log level is ERROR. The callback is invoked synchronously from SDK internal threads - implementations must be thread-safe. When a custom logger is set, stdout output is suppressed.

Interface:

Log levels:

This object configures the HTTP client. It contains three sub-objects:

This object contains configuration for e.g. retries and timeouts.

This object allows adding additional CAs that are validated against for the TLS certificate.

This object determines the log level for backend requests.

(C) EY Strategy and Transactions GmbH, 2025, licensed for gematik GmbH

Apache License, Version 2.0

See the LICENSE for the specific language governing permissions and limitations under the License

1. Copyright notice: Each published work result is accompanied by an explicit statement of the license conditions for use. These are regularly typical conditions in connection with open source or free software. Programs described/provided/linked here are free software, unless otherwise stated.
2. Permission notice: Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
   1. The copyright notice (Item 1) and the permission notice (Item 2) shall be included in all copies or substantial portions of the Software.
   2. The software is provided "as is" without warranty of any kind, either express or implied, including, but not limited to, the warranties of fitness for a particular purpose, merchantability, and/or non-infringement. The authors or copyright holders shall not be liable in any manner whatsoever for any damages or other claims arising from, out of or in connection with the software or the use or other dealings with the software, whether in an action of contract, tort, or otherwise.
   3. We take open source license compliance very seriously. We are always striving to achieve compliance at all times and to improve our processes. If you find any issues or have any suggestions or comments, or if you see any other ways in which we can improve, please reach out to: ospo@gematik.de
3. Please note: Parts of this code may have been generated using AI-supported technology. Please take this into account, especially when troubleshooting, for security analyses and possible adjustments.