Check TLS Client Certificate in Java

Motivation

The gematik document “Übergreifende Spezifikation PKI” gemSpec_PKI specifies the certificate validation process within the TI (Telematik Infrastruktur): TUC_PKI_018 “ Zertifikatsprüfung in der TI”.
Among other things, the document defines that the TLS handshake must be interrupted to validate the client’s certificate. This results in 2 main tasks:

1. Implementing a certificate validation process.
2. Integrating this validation into the TLS handshake.

Certificate Validation Process

The certificate validation process is already implemented and well-documented in the gemLibPki library. Simply use this library (introduced below) and follow the instructions in its README.md.

Library gemLibPki

The gemLibPki implements all the checks defined in TUC_PKI_018 and is already used by several software companies.
source code -> gitHub
binaries -> maven central

Interrupting the TLS Handshake on the Server Side to Validate the Client Certificate

The following code snippets demonstrate how to interrupt the TLS handshake in a Spring Boot application.
You need to implement a Spring Boot component that extends X509TrustManager and use it as a HandshakeInterceptor in the TomcatServletCustomizer.

TLS handshake with validation of client’s certificate

The overridden method checkClientTrusted serves as the entry point for invoking the certificate validation process:

/**
 * This class is not managed by Spring, it is managed by TomcatServletCustomizer...
 */
@Slf4j
@Component("HandshakeInterceptor")
@RequiredArgsConstructor
public final class HandshakeInterceptor implements X509TrustManager { 
  ...

  @Override
  public void checkClientTrusted(final X509Certificate[] chain, final String authType)
      throws CertificateException {
    ...
    final TucPki018Verifier tucPki18Verifier;
    ...
    tucPki18Verifier.performTucPki018Checks(chain[0]);
    ...
  }
}

Set your HandshakeInterceptor in the TomcatServletCustomizer:

@Component
public class TomcatServletCustomizer
    implements WebServerFactoryCustomizer<TomcatServletWebServerFactory> {
  ...

  @Override
  public void customize(final TomcatServletWebServerFactory factory) {
    ...
    factory.addConnectorCustomizers(
        connector -> {
          ...
          sslHostConfig.setTrustManagerClassName(HandshakeInterceptor.class.getCanonicalName());
          ...
        });

  }
}

Example Implementation on GitHub

The PKI testsuite published by gematik, includes a “System Under Test Server Simulator” (gitHub -> pkits-sut-server-sim) that interrupts the TLS handshake to validate the client’s certificate. The simulator uses the gemLibPki library to perform the required validation.

---

About the Author

Robert Stäber is a software engineer for more than 20 years. He joined the gematik in 2016 and is member of the product team IDM (Identity Management) and the Chapter Identity & Security as well.

---