Testing DIMSE Over Mutual TLS Locally
- Mutual TLS testing requires three credentials: a root CA certificate, a server certificate, and a client certificate, each with private keys.
- DCMTK's storescp accepts TLS connections using the +tls flag paired with a trusted CA file.
- The echoscu tool verifies DICOM connectivity over TLS before any association or DIMSE message is exchanged.
- Certificate trust failures, cipher suite mismatches, and AE title rejections each produce distinct DCMTK error codes.
- DCMTK's modern TLS defaults follow the BCP 195 profile, which forbids outdated ciphers like CBC mode and SHA-1.
You can test DICOM DIMSE services over mutual TLS directly on your workstation without an external network. You generate a temporary Certificate Authority (CA) with OpenSSL, issue signed certificates for both peers, and pass those files to DCMTK tools like storescp and echoscu. Mutual TLS verifies cryptographic identity in both directions before opening a DICOM association.
This guide walks through creating test certificates, running a secure storage receiver, and diagnosing handshake failures. We tested these commands using DCMTK 3.7.0 and OpenSSL 3.6.4.
How do you test DCMTK TLS with a self-signed certificate?
A mutual TLS (mTLS) connection requires three credentials: a root CA certificate, a server certificate with its private key, and a client certificate with its private key. If you generate a single self-signed certificate and try to use it on both ends, verification fails because neither side presents a valid signing authority.
You should create an isolated test directory to keep your keys organized:
mkdir -p dicom-tls-lab && cd dicom-tls-lab
Next, generate a local root CA. This certificate acts as the trusted root for your local testing:
openssl req -x509 -newkey rsa:2048 -nodes -days 1 \
-keyout ca.key -out ca.crt \
-subj "/CN=Local Test CA/O=DCMTK Lab"
Now generate the server certificate key and signing request. Sign it with your test CA:
openssl req -newkey rsa:2048 -nodes \
-keyout server.key -out server.csr \
-subj "/CN=localhost/O=Test SCP"
openssl x509 -req -in server.csr \
-CA ca.crt -CAkey ca.key -CAcreateserial \
-out server.crt -days 1
Generate the client certificate using the same CA:
openssl req -newkey rsa:2048 -nodes \
-keyout client.key -out client.csr \
-subj "/CN=Test SCU/O=Test Client"
openssl x509 -req -in client.csr \
-CA ca.crt -CAkey ca.key -CAcreateserial \
-out client.crt -days 1
You now have a complete, two-tier Public Key Infrastructure (PKI). Both server.crt and client.crt link back to ca.crt.
Starting a secure DICOM receiver with storescp
DCMTK’s storescp utility acts as a Service Class Provider (SCP) for C-STORE and C-ECHO requests. To accept mutual TLS connections, you pass the +tls flag along with your certificate authority file.
Start the receiver on port 11114:
storescp -v +tls server.key server.crt -pw +cf ca.crt -rc 11114
Here is what those flags tell storescp to do:
+tls server.key server.crtenables TLS using your private key and server certificate.-pwconfirms your private key has no passphrase, avoiding an interactive prompt.+cf ca.crtadds your test CA to the list of trusted certificate authorities.-rcenforces peer verification, dropping handshakes if the client certificate is missing.
The listening port 11114 must appear as the final argument on the command line.
We use port 11114 for local testing. Standard DICOM port 104 requires root privileges on Unix systems, and port 11112 may conflict with background services.
Notice that the server process stays in the foreground waiting for incoming connections. Leave this terminal open.
Testing the connection with echoscu and storescu
Open a second terminal window. You can verify network and TLS connectivity using echoscu, the DICOM equivalent of a network ping. For a broader overview of how DICOM ping operates, see our guide to DICOM C-ECHO verification.
Run echoscu with the client certificate:
echoscu -v localhost 11114 +tls client.key client.crt -pw +cf ca.crt
When both sides agree on certificates and ciphers, echoscu establishes a TLS session, requests a DICOM association, and completes the echo:
I: Requesting Association
I: Association Accepted (Max Send PDV: 16372)
I: Sending Echo Request (MsgID 1)
I: Received Echo Response (Success)
I: Releasing Association
Once C-ECHO succeeds, you can send an actual DICOM instance using storescu. The command structure matches echoscu:
storescu -v localhost 11114 sample.dcm +tls client.key client.crt -pw +cf ca.crt
The server receives the file, stores it on disk, and acknowledges the C-STORE operation. You can learn more about DCMTK command options in our reference on DCMTK commands for developers.
Why did the handshake fail? Decoding DCMTK TLS errors
When a secure association fails, the root cause could sit at the TCP layer, the TLS handshake, or the DICOM Upper Layer. DCMTK error messages pinpoint the exact layer if you know how to read them.
Run your client with verbose (-v) or trace logging (-ll trace) to inspect connection events. Never add --log-level and --verbose simultaneously, because DCMTK rejects conflicting logging arguments.
Let us examine the three failure modes you will encounter in practice.
Certificate error vs cipher mismatch vs AE title rejection
A broken connection produces distinct terminal errors depending on where the validation fails.
1. Untrusted or missing certificate
Generate a rogue certificate signed by a completely separate CA to test trust failures:
openssl req -x509 -newkey rsa:2048 -nodes -days 1 \
-keyout rogue-ca.key -out rogue-ca.crt -subj "/CN=Rogue CA"
openssl req -newkey rsa:2048 -nodes \
-keyout rogue.key -out rogue.csr -subj "/CN=Rogue Client"
openssl x509 -req -in rogue.csr \
-CA rogue-ca.crt -CAkey rogue-ca.key -CAcreateserial \
-out rogue.crt -days 1
Now run echoscu using the rogue credentials against your storescp listener:
echoscu -v localhost 11114 +tls rogue.key rogue.crt -pw +cf ca.crt
The client reports an abrupt abort:
I: Requesting Association
F: Association Request Failed: 0006:0317 Peer aborted Association (or never connected)
Look at the storescp server terminal to find the real explanation:
E: Receiving Association failed: 000b:0886 TLS error: certificate verify failed
The error code 000b:0886 specifically marks a certificate verification failure in OpenSSL. The server dropped the TCP connection during the TLS handshake before reading any DICOM bytes.
If the client rejects the server’s certificate instead, echoscu displays 000b:0886, while storescp logs 000b:0c18 TLS error: tlsv1 alert unknown ca. In both cases, the fix is updating the CA bundle passed via +cf.
2. Cipher suite or protocol mismatch
A cipher mismatch happens when client and server cannot find a shared encryption algorithm.
Modern DCMTK defaults to the BCP 195 profile specified in RFC 8996 and RFC 9325. This profile forbids outdated ciphers like CBC mode and SHA-1 hashes.
If an older modality or test script requests a legacy cipher, storescp rejects the handshake. For example, if a client forces the retired AES profile with an obsolete RSA key exchange cipher:
echoscu -v localhost 11114 +tls client.key client.crt -pw +cf ca.crt \
+pa +cs TLS_RSA_WITH_AES_128_CBC_SHA
The client fails with a handshake alert:
F: Association Request Failed: 000b:0c10 TLS error: ssl/tls alert handshake failure
The server terminal pinpoints the exact mismatch:
E: Receiving Association failed: 000b:08c1 TLS error: no shared cipher
Notice the difference from a certificate error. Error 000b:08c1 means the certificates were acceptable, but neither side supported a matching cipher suite.
Similarly, if a client attempts a plain unencrypted connection to a TLS port, the server logs 000b:090b TLS error: wrong version number. The server expected a TLS record header and received raw DICOM preamble bytes instead.
3. Application Entity (AE) title rejection
An AE title rejection is not a TLS failure. In this scenario, the TLS handshake completes with zero errors, but the DICOM Upper Layer rejects the association.
DICOM devices identify themselves using Application Entity titles. You can review naming rules in our guide to DICOM Application Entity (AE) titles.
If a PACS or receiver rejects the Calling AE title or Called AE title, echoscu prints an A-ASSOCIATE-RJ packet summary:
I: Requesting Association
F: Association Rejected:
F: Result: Rejected Permanent, Source: Service User
F: Reason: Called AE title not recognized
On the receiver terminal, you will see Association Received printed before the refusal. That confirmation proves the cryptographic channel works. The fix requires updating your -aet (Calling AE title) or -aec (Called AE title) flags, not your TLS certificates.
Understanding these three error boundaries prevents hours of wasted debugging. For production architectures connecting modalities over the internet, read our analysis of mutual TLS for DICOM connections. When moving from local testing to hospital onboarding, follow our guide on how to connect a DICOM sender. You can also review the getting started guide.
Practical limitations of a local test CA
A local OpenSSL test environment lets you validate application logic quickly, but it has boundaries you must keep in mind:
First, local certificates do not validate revocation mechanisms. Real hospital environments use Certificate Revocation Lists (CRLs) or Online Certificate Status Protocol (OCSP) responders. A self-signed local CA does not test how your system reacts when a CRL server goes offline.
Second, your test CA trusts everything it signs. In a hospital deployment, modalities may use certificates issued by internal enterprise PKIs with multi-tiered intermediate authorities.
Third, test certificates expire quickly if you set low validity windows. Generating certificates with -days 1 is great for immediate debugging, but automated test suites should use deterministic test fixtures with known validity periods.
Despite these limitations, running local mutual TLS associations provides rapid feedback. You confirm cipher support, verify certificate parsing, and isolate protocol errors before deploying code to staging environments.
Dicomly builds infrastructure for healthcare software teams that receive DICOM studies from hospitals. Why we built Dicomly →