Mercurial > hg > orthanc-book

annotate Sphinx/source/faq/dicom-tls.rst @ 1069:a714c5fdc4cf

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
DicomTlsRemoteCertificateRequired=false is now equivalent to --ignore-peer-cert DCMTK option instead of --verify-peer-cert
author Alain Mazy <am@orthanc.team>
date Tue, 21 May 2024 12:34:32 +0200
parents 94f5fc38b927
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
609
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
1 .. _dicom-tls:
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
2
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
3 Configuring DICOM TLS
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
4 =====================
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
5
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
6 .. contents::
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
7 :depth: 3
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
8
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
9 Starting with release 1.9.0, Orthanc supports the encryption of the
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
10 DICOM protocol using `DICOM TLS
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
11 <https://www.dicomstandard.org/using/security/>`__. This allows the
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
12 secure exchange of medical images between different sites, even if
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
13 using the DICOM protocol.
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
14
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
15 Configuration
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
16 -------------
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
17
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
18 .. highlight:: bash
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
19
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
20 To enable DICOM TLS, each DICOM modality must have been assigned with
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
21 a `X.509 certificate
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
22 <https://en.wikipedia.org/wiki/X.509>`__. Obtaining such a certificate
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
23 from a `recognized certification authority
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
24 <https://en.wikipedia.org/wiki/Certificate_authority>`__ is obviously
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
25 out of the scope of the Orthanc project. Here is a simple command-line
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
26 to generate a self-signed certificate using the `OpenSSL
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
27 <https://www.openssl.org/>`__ command-line tools::
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
28
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
29 $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
30 -keyout orthanc.key -out orthanc.crt -subj "/C=BE/CN=localhost"
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
31
756
Alain Mazy <am@osimis.io>
parents: 724
diff changeset
32 Obviously, you must adapt the arguments to your setup (notably the
609
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
33 ``subj`` argument that generates a certificate for Belgium for the
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
34 server whose DNS address is ``localhost``). This command line will
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
35 generate two files using the `PEM file format
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
36 <https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail>`__:
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
37 ``orthanc.crt`` is the newly-generated certificate, and
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
38 ``orthanc.key`` contains the private key that protects the
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
39 certificate. The ``orthanc.crt`` can be openly distributed, but
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
40 ``orthanc.key`` must be kept secret (it should only be placed on the
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
41 modality using the corresponding certificate).
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
42
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
43 Once ``orthanc.crt`` and ``orthanc.key`` have been generated, all the
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
44 modalities that will be in touch with Orthanc (either as SCP or as
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
45 SCU) through DICOM TLS must be identified, and their public
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
46 certificates must be collected. All those certificates must be
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
47 concatenated into a single file in order to tell Orthanc which
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
48 modalities can be trusted.
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
49
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
50 Concretely, if one has collected ``a.crt``, ``b.crt`` and ``c.crt`` as
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
51 the certificates (in the PEM format) for trusted remote DICOM
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
52 modalities, a ``trusted.crt`` file can be generated as follows::
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
53
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
54 $ cat a.crt b.crt c.crt > trusted.crt
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
55
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
56 Once the three files ``orthanc.crt``, ``orthanc.key`` and
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
57 ``trusted.crt`` are available, setting the following
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
58 :ref:`configuration options <configuration>` will enable DICOM TLS in
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
59 **Orthanc SCP**:
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
60
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
61 * ``DicomTlsEnabled`` must be set to ``true``.
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
62 * ``DicomTlsCertificate`` must be set to ``orthanc.crt``.
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
63 * ``DicomTlsPrivateKey`` must be set to ``orthanc.key`` (note that
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
64 this private key must not be password-protected).
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
65 * ``DicomTlsTrustedCertificates`` must be set to ``trusted.crt``.
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
66
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
67 If Orthanc acts as a **DICOM SCU** against one remote DICOM modality,
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
68 and if this remote modality is protected by DICOM TLS, the
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
69 ``UseDicomTls`` field must be set to ``true`` in the definition of the
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
70 modality in the configuration file of Orthanc (cf. the
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
71 ``DicomModalities`` option). The file indicated by
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
72 ``DicomTlsCertificate`` will be used to authentify Orthanc by the
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
73 remote modality: This modality must thus include ``orthanc.crt`` in
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
74 its list of trusted certificates.
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
75
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
76
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
77 **Remark 1:** Pay attention not to confuse the configuration options
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
78 related to HTTPS encryption, with the options related to DICOM TLS.
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
79 In Orthanc, HTTPS and DICOM TLS are not obliged to use the same
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
80 encryption certificates.
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
81
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
82 **Remark 2:** Orthanc SCU and Orthanc SCP share the same set of
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
83 trusted certificates.
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
84
757
980ffad93dc5 remark about Debian Buster and DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 756
diff changeset
85 **Important:** `DCMTK 3.6.4 seems to have an issue with DICOM TLS
980ffad93dc5 remark about Debian Buster and DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 756
diff changeset
86 <https://forum.dcmtk.org/viewtopic.php?t=5073>`__, which produces the
980ffad93dc5 remark about Debian Buster and DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 756
diff changeset
87 errors ``DUL secure transport layer: no suitable signature algorithm``
980ffad93dc5 remark about Debian Buster and DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 756
diff changeset
88 (in the DICOM SCP) and ``DUL secure transport layer: sslv3 alert
759
94f5fc38b927 clarifications
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 757
diff changeset
89 handshake failure`` (in the DICOM SCU). This problem is not specific
94f5fc38b927 clarifications
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 757
diff changeset
90 to Orthanc, as it also occurs between two command-line tools of the
94f5fc38b927 clarifications
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 757
diff changeset
91 DCMTK 3.6.4 suite. Make sure to use either DCMTK 3.6.2 or DCMTK
94f5fc38b927 clarifications
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 757
diff changeset
92 3.6.6. In particular, Debian Buster (10) uses DCMTK 3.6.4 and should
94f5fc38b927 clarifications
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 757
diff changeset
93 be avoided in non-static builds of Orthanc, or if using the DCMTK
94f5fc38b927 clarifications
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 757
diff changeset
94 command-line tools.
757
980ffad93dc5 remark about Debian Buster and DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 756
diff changeset
95
980ffad93dc5 remark about Debian Buster and DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 756
diff changeset
96
609
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
97
724
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
98 Examples
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
99 --------
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
100
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
101 Using DCMTK
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
102 ^^^^^^^^^^^
609
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
103
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
104 .. highlight:: bash
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
105
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
106 Let us generate one certificate for Orthanc, and one certificate for
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
107 DCMTK::
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
108
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
109 $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
110 -keyout orthanc.key -out orthanc.crt -subj "/C=BE/CN=localhost"
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
111 $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
112 -keyout dcmtk.key -out dcmtk.crt -subj "/C=BE/CN=localhost"
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
113
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
114 .. highlight:: json
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
115
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
116 Let us start Orthanc using the following minimal configuration file::
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
117
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
118 {
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
119 "DicomTlsEnabled" : true,
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
120 "DicomTlsCertificate" : "orthanc.crt",
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
121 "DicomTlsPrivateKey" : "orthanc.key",
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
122 "DicomTlsTrustedCertificates" : "dcmtk.crt",
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
123 "DicomModalities" : {
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
124 "dmctk" : {
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
125 "Host" : "localhost",
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
126 "Port" : 4242,
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
127 "AET" : "DCMTK",
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
128 "UseDicomTls" : true
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
129 }
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
130 }
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
131 }
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
132
677
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
133 .. highlight:: text
609
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
134
724
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
135 It is then possible to trigger a secure C-ECHO SCU request from DCMTK
609
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
136 to Orthanc as follows::
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
137
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
138 $ echoscu -v -aet DCMTK localhost 4242 +tls dcmtk.key dcmtk.crt +cf orthanc.crt
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
139 I: Requesting Association
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
140 I: Association Accepted (Max Send PDV: 16372)
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
141 I: Sending Echo Request (MsgID 1)
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
142 I: Received Echo Response (Success)
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
143 I: Releasing Association
677
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
144
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
145
724
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
146 Using dcm4che
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
147 ^^^^^^^^^^^^^
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
148
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
149 .. highlight:: bash
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
150
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
151 To use the dcm4che command-line tools instead of DCMTK, the two
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
152 certificates must first be converted from `X.509
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
153 <https://en.wikipedia.org/wiki/X.509>`__ to `PKCS #12
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
154 <https://en.wikipedia.org/wiki/PKCS_12>`__::
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
155
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
156 $ openssl pkcs12 -export -out orthanc.p12 -in orthanc.crt -inkey orthanc.key
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
157 $ openssl pkcs12 -export -out dcm4che.p12 -in dcmtk.crt -inkey dcmtk.key
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
158
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
159 For this example, you can let the ``Export Password`` as an empty
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
160 string in the two calls above. Then, here is how to trigger a secure
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
161 C-STORE SCU request to send the ``sample.dcm`` file from dcm4che to
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
162 Orthanc::
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
163
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
164 $ ~/Downloads/dcm4che-5.23.3/bin/storescu -c ORTHANC@localhost:4242 --tls \
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
165 --trust-store ./orthanc.p12 --key-store ./dcm4che.p12 --trust-store-pass "" --key-store-pass "" sample.dcm
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
166
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
167 **Remarks:**
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
168
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
169 * The empty strings provided to the ``--trust-store-pass`` and
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
170 ``--key-store-pass`` options correspond to the empty strings
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
171 provided to ``Export Password``.
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
172
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
173 * Disclaimer: In this setup, ``orthanc.p12`` contains the private key
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
174 of the Orthanc server. It is unclear how to remove this private key
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
175 that should be unknown to the DICOM client for security reasons.
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
176
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
177
677
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
178 Secure TLS connections without certificate
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
179 ------------------------------------------
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
180
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
181 In Orthanc <= 1.9.2, the remote DICOM modalities are required to
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
182 provide a valide DICOM TLS certificate (which corresponds to the
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
183 default ``--require-peer-cert`` option of the DCMTK command-line
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
184 tools).
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
185
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
186 Starting from Orthanc 1.9.3, it is possible to allow connections
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
187 to/from remote DICOM modalities that do not provide a DICOM TLS
1069
a714c5fdc4cf DicomTlsRemoteCertificateRequired=false is now equivalent to --ignore-peer-cert DCMTK option instead of --verify-peer-cert
Alain Mazy <am@orthanc.team>
parents: 759
diff changeset
188 certificate (which corresponds to the ``--ignore-peer-cert`` option of
677
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
189 DCMTK). This requires setting the :ref:`configuration option
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
190 <configuration>` ``DicomTlsRemoteCertificateRequired`` of Orthanc to
1069
a714c5fdc4cf DicomTlsRemoteCertificateRequired=false is now equivalent to --ignore-peer-cert DCMTK option instead of --verify-peer-cert
Alain Mazy <am@orthanc.team>
parents: 759
diff changeset
191 ``false``. Note: between Orthanc 1.9.3 and Orthanc 1.12.3 included,
a714c5fdc4cf DicomTlsRemoteCertificateRequired=false is now equivalent to --ignore-peer-cert DCMTK option instead of --verify-peer-cert
Alain Mazy <am@orthanc.team>
parents: 759
diff changeset
192 this option was actually equivalent to ``--verify-peer-cert``.
677
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
193
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
194 .. highlight:: bash
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
195
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
196 As an example, let us generate one single certificate that is
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
197 dedicated to Orthanc::
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
198
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
199 $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
200 -keyout orthanc.key -out orthanc.crt -subj "/C=BE/CN=localhost"
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
201
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
202
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
203 .. highlight:: json
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
204
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
205 Let us start Orthanc using the following minimal configuration file::
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
206
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
207 {
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
208 "DicomTlsEnabled" : true,
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
209 "DicomTlsCertificate" : "orthanc.crt",
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
210 "DicomTlsPrivateKey" : "orthanc.key",
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
211 "DicomTlsRemoteCertificateRequired" : false
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
212 }
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
213
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
214 .. highlight:: text
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
215
1069
a714c5fdc4cf DicomTlsRemoteCertificateRequired=false is now equivalent to --ignore-peer-cert DCMTK option instead of --verify-peer-cert
Alain Mazy <am@orthanc.team>
parents: 759
diff changeset
216 It is then possible to
677
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
217 connect to Orthanc without SCU certificate as follows::
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
218
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
219 $ echoscu -v localhost 4242 --anonymous-tls +cf /tmp/k/orthanc.crt
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
220 I: Requesting Association
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
221 I: Association Accepted (Max Send PDV: 16372)
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
222 I: Sending Echo Request (MsgID 1)
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
223 I: Received Echo Response (Success)
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
224 I: Releasing Association