A java library for functionalities in PKI (Public Key Infrastructure) of products specified by gematik.
Products specified by gematik which have to deal with PKI will have to handle certificates and TSLs (TrustedServiceProvider Status Lists)/ BNetzA-VL (Bundesnetzagentur-Vertrauensliste). This library may help to understand the intention of the specification as a reference implementation. Please see liability limitation for further information.
- Specifications are published at gematik Fachportal.
See ReleaseNotes.md for all information regarding the (newest) releases.
Cryptographic private keys used in this project are solely used in test resources for the purpose of unit tests. We are fully aware of the content and meaning of the test data. We never publish productive data willingly.
For certificate checks the library offers interfaces:
as well as a couple of implementations for different checks alongside (see validators). You can build a chain of different checks or extend the library for your own requirements.
A complete implementation of the TUC_PKI_018 „Zertifikatsprüfung in der TI“ of the gematik document "Übergreifende Spezifikation PKI" (gemSpec_PKI)can be found in TucPki018Verifier Here we check against nonQES certificate profiles specified by gematik, not against usages and contexts (a special certificate profile for allowing any profile, i.e., disable profile checks is available as well)
OCSP requests are optional and activated by default. OCSP responses are verified according to TUC_PKI_006 "OCSP-Abfrage" (see OCSP checks section).
For examples of how to use the TUC_PKI_018 implementation see TucPki018VerifierTest.java (TI 1.0).
An implementation of TUC_PKI_030 „QES-Zertifikatsprüfung“ can be found in TucPki030Verifier.
The current implementation focuses on the validation of QES end-entity certificates. It checks the presence of the required QC statement, certificate validity, the expected KeyUsage, the matching QES-CA in the BNetzA-VL, the qualification and status of that QES-CA and the mathematical signature of the certificate chain based on the certificate issuance date.
OCSP checks are supported as part of TUC_PKI_030 and are enabled by default. The corresponding implementation can be found in TucPki030OcspVerifier and TucPki030OcspValidator.
For examples of how to use the current TUC_PKI_030 implementation see TucPki030VerifierTest.java.
OCSP responses can be generated with different properties. By default, a valid OCSP response,
according to rf2560, is generated. OCSP responses are validated according to TUC_PKI_006 of
gemSpec_PKI. There are the following deviations from the specification. To allow OCSP responses that
are, for example, months old, only plausibility checks are performed on the thisUpdate and
producedAt timestamps:
thisUpdatemust not be more than the specified tolerance in the future.producedAtmust not be more than the set tolerance in the future.thisUpdatemust not be later thanproducedAt.
OCSP validation can be disabled via builder parameter withOcspCheck of
TucPki018Verifier
or
TucPki030Verifier.
The location of the OCSP SSP (service supply point - address of the OCSP responder) is different for TI 1.0 and TI 2.0 (TI = Telematik Infrastruktur). The Interface OcspTransceiverFactory will take care of it. There following implementations of this interface exist:
nonQES:
The SSP is expected to be listed in the TSL, in the entry for the CA of the certificate.
The TucPki018Verifier
will use
the TslBasedSspOcspTransceiverFactory
as default and everything works as it did before TI 20 started.
QES:
The SSP is located on the internet and is therefore expected to be listed in the Extensions of the
certificate itself. But it can be overridden by the TSL entry for the CA of the certificate.
The TucPki030Verifier
will use
the TucPki30OcspTransceiverFactory
as default.
The SSP is located on the internet and is therefore expected to be listed in the Extensions of the
certificate itself. There it is the Extension AuthorityInformationAccess.
The TucPki018Verifier
needs
a CertificateBasedSspOcspTransceiverFactory
and this will do the work.
Examples can be found in the unit tests.
There are two different types of trust lists. They contain either QES certificates (BNetzA-VL) or non-QES certificates (TSL). From version 5.0.1 this library is able to handle both trust lists, except a TucPki036Verifier for QES (equivalent to TucPki001Verifier for nonQES) will be implemented later.
For nonQES, the library contains checks defined in TUC_PKI_001 „Periodische Aktualisierung TI-Vertrauensraum“ specified in gematik document "Übergreifende Spezifikation PKI" (gemSpec_PKI).
We provide several methods to get information, for parsing, modifying, signing and validation of a TSL (see: TSL package).
Attention: the trust anchor change mechanism is not completely implemented in this library, because
it has to be part of the TSL downloading component. An example of an implementation can be found in
the system under test simulator of the gematik PKI test suite,
component: TslProcurer.
- instantiate a TslReader to read a TSL
- use the result of the TslReader to instantiate a TslInformationProvider and call its public methods
- get TspServices from TslInformationProvider
- for nonQES instantiate
a TucPki001Verifier
(via builder) and call its public method
performTucPki001Checks(). The offline mode for TUC_PKI_001 (used solely for a Konnektor) is not implemented - for QES instantiate ... tbd
- error codes specified by gematik in gemSpec_PKI
Build with:
mvn clean installCopyright 2020-2026 gematik GmbH
Apache License, Version 2.0
See the LICENSE for the specific language governing permissions and limitations under the License
- 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.