TLS troubleshooting

If TLS is enabled but clients cannot connect, use this checklist to verify the effective server setup and client compatibility.

1. Verify webPDF configuration and startup logs

Check the HTTPS connector in conf/server.xml:

<connector enabled="true" port="8443" address="">
  <ssl ...>
    <protocols>
      <protocol>TLSv1.2</protocol>
      <protocol>TLSv1.3</protocol>
    </protocols>
    <ciphers forceOrder="false">
      <cipher>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</cipher>
    </ciphers>
  </ssl>
</connector>

After restart, verify startup log entries for the HTTPS connector:

• Starting SSL connector '...'
• Using SSL protocols '...' for '...'
• Using SSL ciphers ... '...' for '...'
• Using '...' keystore '...' for '...'

If these entries are missing, the connector is usually disabled, not loaded, or failed during startup.

2. Verify negotiated TLS version and cipher

Use OpenSSL from a client system and always send SNI (-servername):

openssl s_client -connect <host>:8443 -servername <host> < /dev/null

In the output, check:

• Protocol : ...
• Cipher : ...
• certificate subject / issuer

Test specific TLS versions

# force TLS 1.2
openssl s_client -connect <host>:8443 -servername <host> -tls1_2 < /dev/null

# force TLS 1.3
openssl s_client -connect <host>:8443 -servername <host> -tls1_3 < /dev/null

If one command fails and the other succeeds, there is a protocol mismatch between client and server policy.

Test specific ciphers

For TLS 1.2 and older:

openssl s_client -connect <host>:8443 -servername <host> -tls1_2 -cipher 'ECDHE-RSA-AES128-GCM-SHA256' < /dev/null

For TLS 1.3:

openssl s_client -connect <host>:8443 -servername <host> -tls1_3 -ciphersuites 'TLS_AES_128_GCM_SHA256' < /dev/null

tip

OpenSSL uses -cipher for TLS 1.2 and -ciphersuites for TLS 1.3.

For deeper cipher matching checks (server offers vs client supports), see Ciphers.

3. Verify certificate chain presented by server

openssl s_client -connect <host>:8443 -servername <host> -showcerts < /dev/null

Check that:

• server certificate is correct for hostname (CN/SAN)
• intermediate certificates are present
• certificate is not expired

4. Verify whether the client supports your policy

A handshake works only if both sides share at least one protocol and one cipher.

Check local OpenSSL capabilities:

openssl version
openssl ciphers -v | grep -E 'TLS_AES_128_GCM_SHA256|TLS_AES_256_GCM_SHA384|ECDHE'

For Java clients, check runtime and disabled algorithms (can remove old/weak options):

java -version
java -XshowSettings:security -version 2>&1 | grep -i 'jdk.tls.disabledAlgorithms'

If needed, test from the exact client environment (same JRE/container/OS image), not only from an admin workstation.

5. Provider-specific environments (Azure, AWS, SAP)

In cloud and enterprise setups, TLS is often terminated or filtered before webPDF. Always test both paths:

• external path: client -> public endpoint (for example App Gateway, ALB, reverse proxy)
• internal path: client (or bastion) -> webPDF directly (<host>:8443)

If external fails but internal works, the issue is usually in the gateway/proxy TLS policy.

Azure

• Check TLS policy and SNI handling on Application Gateway / Front Door.
• Test using the real FQDN:

openssl s_client -connect <fqdn>:443 -servername <fqdn> -tls1_2 < /dev/null

• If backend TLS is enabled, also test direct access to webPDF (:8443) from the same network.

AWS

• ALB usually terminates TLS, NLB can pass TLS through.
• Test public endpoint and internal webPDF endpoint separately.
• Compare negotiated protocol/cipher and presented certificate on both hops.

SAP environments

• Test from the real SAP runtime host (same network, same runtime).
• Verify Java/runtime crypto policy and trust configuration.
• Typical client-side issue: trust chain not available in SAP/JRE trust store.
• On ABAP systems, TLS capabilities depend on SAP Kernel patch level (disp+work) and CommonCryptoLib.
• NetWeaver stack matters: ABAP and Java stacks can have different TLS behavior and trust handling.
• Deployment model matters:
  • On-premise: TLS behavior is strongly influenced by kernel and crypto library level.
  • S/4HANA Cloud: TLS behavior is mainly governed by platform-managed communication setup and tenant configuration.
• For analysis, always capture landscape context (On-Prem / S/4HANA Cloud, ABAP / Java stack, and runtime generation) before comparing failures.

6. Client runtimes (programming languages)

Different runtimes use different TLS defaults. Test from the exact runtime/container used in production.

Java

java -version
java -XshowSettings:security -version 2>&1 | grep -i 'jdk.tls.disabledAlgorithms'

.NET

dotnet --info

In code, use HttpClientHandler.SslProtocols if you must pin protocol versions.

Node.js

node -v
node -p "process.versions.openssl"

In code, set minVersion / maxVersion in https options if needed.

Python

python -c "import ssl; print(ssl.OPENSSL_VERSION)"

In code, use ssl.SSLContext and set minimum_version / maximum_version.

Go

go version

In code, configure tls.Config (MinVersion, MaxVersion; CipherSuites for TLS 1.2).

PHP

php -i | grep -i -E 'OpenSSL|SSL Version'

For client calls, verify TLS settings in cURL or stream context options.

7. Quick matrix (first checks)

Environment	Typical issue	First check
Direct client -> webPDF	Protocol/cipher mismatch	openssl s_client -connect <host>:8443 -servername <host> -tls1_2 and -tls1_3
Azure App Gateway / Front Door	TLS policy mismatch, SNI/routing	openssl s_client -connect <fqdn>:443 -servername <fqdn> plus internal :8443 test
AWS ALB/NLB	TLS termination vs pass-through confusion	Compare public endpoint handshake vs internal webPDF handshake
SAP NetWeaver ABAP	Kernel/crypto library limitations	Check disp+work -version, then test from SAP host with openssl s_client
SAP NetWeaver Java	JRE trust/protocol policy	java -version and jdk.tls.disabledAlgorithms; test from same runtime host
Containerized clients	Different runtime/OpenSSL than workstation	Run checks inside container image (not only on admin machine)

8. Common error patterns

• alert protocol version Server and client do not share an enabled TLS protocol.
• no shared cipher or handshake_failure No common cipher (or cipher restricted by TLS version / JDK policy).
• PKIX path building failed (Java client) Client does not trust the issuing CA chain.
• Certificate shown by s_client is unexpected Missing -servername (SNI), wrong virtual host binding, or wrong certificate alias.

9. Fast fallback for isolation

For quick isolation, temporarily use:

• protocols: TLSv1.2 and TLSv1.3
• ciphers: default (JDK default)

If this works, reintroduce custom cipher restrictions step by step until the failing entry is identified.