gematik · sigabrtz · Nov 27, 2025 · Nov 6, 2025
diff --git a/.github/README.adoc b/.github/README.adoc
@@ -1,9 +1,7 @@
 ////
 Execute `make readme` after editing <project_root>/README.adoc
 ////
-:toc-title: Table of Contents
-:toc:
-:toclevels: 2
+:doctype: book
 :source-highlighter: prettify
 
 :testdir: ../../Tests
@@ -12,6 +10,32 @@ Execute `make readme` after editing <project_root>/README.adoc
 
 = OpenHealthCardKit
 
+++++
+<details>
+  <summary>Table of Contents</summary>
+  <ol>
+    <li>
+      <a href="#about-the-project">About The Project</a>
+       <ul>
+        <li><a href="#release-notes">Release Notes</a></li>
+      </ul>
+    </li>
+    <li>
+      <a href="#getting-started">Getting Started</a>
+      <ul>
+        <li><a href="#prerequisites">Prerequisites</a></li>
+        <li><a href="#installation">Installation</a></li>
+      </ul>
+    </li>
+    <li><a href="#usage">Usage</a></li>
+    <li><a href="#license">License</a></li>
+    <li><a href="#contact">Contact</a></li>
+  </ol>
+</details>
+++++
+
+== About The Project
+
 Controlling/Use-case framework for accessing smart cards of the telematic infrastructure.
 
 == Introduction
@@ -22,51 +46,71 @@ and a German Health Card (elektronische Gesundheitskarte) using an NFC, Blue Too
 
 This document describes the functionalitiy and structure of OpenHealthCardKit.
 
-== API Documentation
+== Overview
 
-Generated API docs are available at https://swiftpackageindex.com/gematik/ref-OpenHealthCardKit[Swift Package Index]:
+OpenHealthCardKit bundles submodules that provide the functionality
+necessary for accessing and interacting with German Health Cards via a mobile iOS device.
 
-* HealthCardControl (tbd)
-* https://swiftpackageindex.com/gematik/ref-OpenHealthCardKit/main/documentation/healthcardaccess[HealthCardAccess]
-* https://swiftpackageindex.com/gematik/ref-OpenHealthCardKit/main/documentation/nfccardreaderprovider[NFCCardReaderProvider]
-* https://swiftpackageindex.com/gematik/ref-OpenHealthCardKit/main/documentation/cardreaderproviderapi[CardReaderProviderApi]
+OpenHealthCardKit consists of the submodules
 
-NOTE: As of now the automatic API doc generation for `HealthCardControl` is broken. It's possible to generate it manually via Xcode: Select the target `HealthCardControl` and select `Product -> Build Documentation`.
+- CardReaderProviderApi
+- HealthCardAccess
+- HealthCardControl
+- NFCCardReaderProvider
+
+As a reference for the usage of each submodule see also the `IntegrationTests`.
+
+=== Release Notes
+See `link:../ReleaseNotes.md[ReleaseNotes]` for all information regarding the (newest) releases.
 
 == Getting Started
 
 OpenHealthCardKit requires Swift 5.6.
 
-=== Setup for integration
+=== Prerequisites
+
+- Swift 5.6 or later
+- Xcode (for iOS development)
+- Swift Package Manager, Carthage, or manual integration
+
+=== Installation
 
-- **Swift Package Manager:** Put this in your `Package.swift`:
+==== Swift Package Manager
 
-    .package(url: "https://github.com/gematik/ref-OpenHealthCardKit", from: "5.6.0"),
+Put this in your `Package.swift`:
 
-- **Carthage:** Put this in your `Cartfile`:
+[source,swift]
+----
+.package(url: "https://github.com/gematik/ref-OpenHealthCardKit", from: "5.6.0"),
+----
 
-    github "gematik/ref-openHealthCardKit" ~> 5.0
+==== Carthage
 
-=== Setup for development
+Put this in your `Cartfile`:
+
+----
+github "gematik/ref-openHealthCardKit" ~> 5.0
+----
+
+==== Setup for Development
 
 Run `$ make setup` to start developing locally. This will make sure all the dependencies are put in place and the Xcode-project will be generated and/or overwritten.
 
 Dependencies are a mix of SPM (Swift Package Manager) and Carthage right now. The Xcode-project is generated using `xcodegen`.
 The more complex build configuration(s) is done with the help of Fastlane. See the `./fastlane` directory for full setup.
 
-== Overview
+== Usage
 
-OpenHealthCardKit bundles submodules that provide the functionality
-necessary for accessing and interacting with German Health Cards via a mobile iOS device.
+== API Documentation
 
-OpenHealthCardKit consists of the submodules
+Generated API docs are available at https://swiftpackageindex.com/gematik/ref-OpenHealthCardKit[Swift Package Index]:
 
-- CardReaderProviderApi
-- HealthCardAccess
-- HealthCardControl
-- NFCCardReaderProvider
+* HealthCardControl (tbd)
+* https://swiftpackageindex.com/gematik/ref-OpenHealthCardKit/main/documentation/healthcardaccess[HealthCardAccess]
+* https://swiftpackageindex.com/gematik/ref-OpenHealthCardKit/main/documentation/nfccardreaderprovider[NFCCardReaderProvider]
+* https://swiftpackageindex.com/gematik/ref-OpenHealthCardKit/main/documentation/cardreaderproviderapi[CardReaderProviderApi]
 
-As a reference for the usage of each submodule see also the `IntegrationTests`.
+NOTE: As of now the automatic API doc generation for `HealthCardControl` is broken. It's possible to generate it manually via Xcode: Select the target `HealthCardControl` and select `Product -> Build Documentation`.
 
 [#CardReaderProviderApi]
 === CardReaderProviderApi
@@ -323,6 +367,7 @@ The `NFCHealthCardSession` also gives you an endpoint to invalidate the underlyi
     return
 }
 ----
+
 [#NFCDemo]
 === NFCDemo
 
@@ -332,16 +377,27 @@ said framework to connect to and establish a secure communications channel with
 The App consist out of two screens/views. The first one will prompt the user for the CAN number.
 The second prompts for the PIN. This PIN is verified on the card against `mrpinHome` when the `connect` button is tapped.
 
+For more examples or in-depth documentation, please refer to the included user guide sections above.
+
 == License
 
-Copyright 2023 gematik GmbH
+Copyright 2020-2025 gematik GmbH
+
+Apache License, Version 2.0
 
-Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
+See the `link:../LICENSE[LICENSE]` for the specific language governing permissions and limitations under the License
 
-See the link:./LICENSE[LICENSE] for the specific language governing permissions and limitations under the License.
+== Additional Notes and Disclaimer from gematik GmbH
 
-Unless required by applicable law 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.
+. 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.
+. 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:
+.. The copyright notice (Item 1) and the permission notice (Item 2) shall be included in all copies or substantial portions of the Software.
+.. 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.
+.. The software is the result of research and development activities, therefore not necessarily quality assured and without the character of a liable product. For this reason, gematik does not provide any support or other user assistance (unless otherwise stated in individual cases and without justification of a legal obligation). Furthermore, there is no claim to further development and adaptation of the results to a more current state of the art.
+. Gematik may remove published results temporarily or permanently from the place of publication at any time without prior notice or justification.
+. 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.
 
-The software is the result of research and development activities, therefore not necessarily quality assured and without the character of a liable product. For this reason, gematik does not provide any support or other user assistance (unless otherwise stated in individual cases and without justification of a legal obligation). Furthermore, there is no claim to further development and adaptation of the results to a more current state of the art.
+== Contact
 
-Gematik may remove published results temporarily or permanently from the place of publication at any time without prior notice or justification.
+This software is currently being tested to ensure its technical quality and legal compliance. Your feedback is highly valued.
+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
diff --git a/.swiftlint.yml b/.swiftlint.yml
@@ -72,5 +72,5 @@ custom_rules:
 file_header:
   required_pattern: |
     \/\/
-    \/\/  Copyright \(c\) \d{4} gematik GmbH
+    \/\/ Copyright \(Change Date see Readme\), gematik GmbH
     \/\/
diff --git a/CardSimulationTestKit/.swiftlint.yml b/CardSimulationTestKit/.swiftlint.yml
@@ -55,5 +55,5 @@ custom_rules:
 file_header:
   required_pattern: |
     \/\/
-    \/\/  Copyright \(c\) \d{4} gematik GmbH
+    \/\/ Copyright \(Change Date see Readme\), gematik GmbH
     \/\/
diff --git a/CardSimulationTestKit/Sources/AEXMLExt/AEXMLElement+Root.swift b/CardSimulationTestKit/Sources/AEXMLExt/AEXMLElement+Root.swift
@@ -1,17 +1,21 @@
 //
-//  Copyright (c) 2023 gematik GmbH
+// Copyright (Change Date see Readme), gematik GmbH
 //
-//  Licensed under the Apache License, Version 2.0 (the License);
-//  you may not use this file except in compliance with the License.
-//  You may obtain a copy of the License at
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
 //
-//      http://www.apache.org/licenses/LICENSE-2.0
+//     http://www.apache.org/licenses/LICENSE-2.0
 //
-//  Unless required by applicable law or agreed to in writing, software
-//  distributed under the License is distributed on an 'AS IS' BASIS,
-//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-//  See the License for the specific language governing permissions and
-//  limitations under the License.
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// *******
+//
+// For additional notes and disclaimer from gematik and in case of changes by gematik find details in the "Readme" file.
 //
 
 import AEXML

diff --git a/CardSimulationTestKit/Sources/CardSimulationCardReaderProvider/Card/SimulatorCard.swift b/CardSimulationTestKit/Sources/CardSimulationCardReaderProvider/Card/SimulatorCard.swift
@@ -1,17 +1,21 @@
 //
-//  Copyright (c) 2023 gematik GmbH
+// Copyright (Change Date see Readme), gematik GmbH
 //
-//  Licensed under the Apache License, Version 2.0 (the License);
-//  you may not use this file except in compliance with the License.
-//  You may obtain a copy of the License at
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
 //
-//      http://www.apache.org/licenses/LICENSE-2.0
+//     http://www.apache.org/licenses/LICENSE-2.0
 //
-//  Unless required by applicable law or agreed to in writing, software
-//  distributed under the License is distributed on an 'AS IS' BASIS,
-//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-//  See the License for the specific language governing permissions and
-//  limitations under the License.
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// *******
+//
+// For additional notes and disclaimer from gematik and in case of changes by gematik find details in the "Readme" file.
 //
 
 import CardReaderProviderApi

diff --git a/...imulationTestKit/Sources/CardSimulationCardReaderProvider/Card/SimulatorCardChannel.swift b/...imulationTestKit/Sources/CardSimulationCardReaderProvider/Card/SimulatorCardChannel.swift
@@ -1,17 +1,21 @@
 //
-//  Copyright (c) 2023 gematik GmbH
+// Copyright (Change Date see Readme), gematik GmbH
 //
-//  Licensed under the Apache License, Version 2.0 (the License);
-//  you may not use this file except in compliance with the License.
-//  You may obtain a copy of the License at
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
 //
-//      http://www.apache.org/licenses/LICENSE-2.0
+//     http://www.apache.org/licenses/LICENSE-2.0
 //
-//  Unless required by applicable law or agreed to in writing, software
-//  distributed under the License is distributed on an 'AS IS' BASIS,
-//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-//  See the License for the specific language governing permissions and
-//  limitations under the License.
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// *******
+//
+// For additional notes and disclaimer from gematik and in case of changes by gematik find details in the "Readme" file.
 //
 
 import CardReaderProviderApi

diff --git a/CardSimulationTestKit/Sources/CardSimulationCardReaderProvider/Logger.swift b/CardSimulationTestKit/Sources/CardSimulationCardReaderProvider/Logger.swift
@@ -1,17 +1,21 @@
 //
-//  Copyright (c) 2024 gematik GmbH
+// Copyright (Change Date see Readme), gematik GmbH
 //
-//  Licensed under the Apache License, Version 2.0 (the License);
-//  you may not use this file except in compliance with the License.
-//  You may obtain a copy of the License at
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
 //
-//      http://www.apache.org/licenses/LICENSE-2.0
+//     http://www.apache.org/licenses/LICENSE-2.0
 //
-//  Unless required by applicable law or agreed to in writing, software
-//  distributed under the License is distributed on an 'AS IS' BASIS,
-//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-//  See the License for the specific language governing permissions and
-//  limitations under the License.
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// *******
+//
+// For additional notes and disclaimer from gematik and in case of changes by gematik find details in the "Readme" file.
 //
 
 import OSLog

diff --git a/...stKit/Sources/CardSimulationCardReaderProvider/Provider/SimulatorCardReaderProvider.swift b/...stKit/Sources/CardSimulationCardReaderProvider/Provider/SimulatorCardReaderProvider.swift
@@ -1,17 +1,21 @@
 //
-//  Copyright (c) 2023 gematik GmbH
+// Copyright (Change Date see Readme), gematik GmbH
 //
-//  Licensed under the Apache License, Version 2.0 (the License);
-//  you may not use this file except in compliance with the License.
-//  You may obtain a copy of the License at
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
 //
-//      http://www.apache.org/licenses/LICENSE-2.0
+//     http://www.apache.org/licenses/LICENSE-2.0
 //
-//  Unless required by applicable law or agreed to in writing, software
-//  distributed under the License is distributed on an 'AS IS' BASIS,
-//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-//  See the License for the specific language governing permissions and
-//  limitations under the License.
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// *******
+//
+// For additional notes and disclaimer from gematik and in case of changes by gematik find details in the "Readme" file.
 //
 
 import CardReaderProviderApi

diff --git a/...lationTestKit/Sources/CardSimulationCardReaderProvider/Terminal/SimulatorCardReader.swift b/...lationTestKit/Sources/CardSimulationCardReaderProvider/Terminal/SimulatorCardReader.swift
@@ -1,17 +1,21 @@
 //
-//  Copyright (c) 2023 gematik GmbH
+// Copyright (Change Date see Readme), gematik GmbH
 //
-//  Licensed under the Apache License, Version 2.0 (the License);
-//  you may not use this file except in compliance with the License.
-//  You may obtain a copy of the License at
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
 //
-//      http://www.apache.org/licenses/LICENSE-2.0
+//     http://www.apache.org/licenses/LICENSE-2.0
 //
-//  Unless required by applicable law or agreed to in writing, software
-//  distributed under the License is distributed on an 'AS IS' BASIS,
-//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-//  See the License for the specific language governing permissions and
-//  limitations under the License.
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// *******
+//
+// For additional notes and disclaimer from gematik and in case of changes by gematik find details in the "Readme" file.
 //
 
 import CardReaderProviderApi