Mercurial > hg > orthanc-book

annotate Sphinx/source/faq/dicom-tls.rst @ 724:2ea133e0fa8e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
dicom tls and dcm4che
author Sebastien Jodogne <s.jodogne@gmail.com>
date Thu, 24 Jun 2021 22:29:34 +0200
parents 25e44dba9dba
children 9484a3c65136
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
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
32 Obviously, you have adapt the arguments to your setup (notably the
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
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
85
724
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
86 Examples
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
87 --------
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
88
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
89 Using DCMTK
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
90 ^^^^^^^^^^^
609
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
91
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
92 .. highlight:: bash
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
93
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
94 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
95 DCMTK::
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
96
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
97 $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
98 -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
99 $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
100 -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
101
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
102 .. highlight:: json
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 Let us start Orthanc using the following minimal configuration file::
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 {
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
107 "DicomTlsEnabled" : true,
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
108 "DicomTlsCertificate" : "orthanc.crt",
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
109 "DicomTlsPrivateKey" : "orthanc.key",
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
110 "DicomTlsTrustedCertificates" : "dcmtk.crt",
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
111 "DicomModalities" : {
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
112 "dmctk" : {
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
113 "Host" : "localhost",
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
114 "Port" : 4242,
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
115 "AET" : "DCMTK",
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
116 "UseDicomTls" : true
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 }
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
120
677
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
121 .. highlight:: text
609
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
122
724
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
123 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
124 to Orthanc as follows::
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
125
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
126 $ 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
127 I: Requesting Association
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
128 I: Association Accepted (Max Send PDV: 16372)
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
129 I: Sending Echo Request (MsgID 1)
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
130 I: Received Echo Response (Success)
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
131 I: Releasing Association
677
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
132
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
133
724
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
134 Using dcm4che
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
135 ^^^^^^^^^^^^^
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
136
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
137 .. highlight:: bash
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
138
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
139 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
140 certificates must first be converted from `X.509
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
141 <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
142 <https://en.wikipedia.org/wiki/PKCS_12>`__::
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
143
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
144 $ 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
145 $ 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
146
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
147 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
148 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
149 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
150 Orthanc::
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
151
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
152 $ ~/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
153 --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
154
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
155 **Remarks:**
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
156
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
157 * 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
158 ``--key-store-pass`` options correspond to the empty strings
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
159 provided to ``Export Password``.
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
160
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
161 * 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
162 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
163 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
164
2ea133e0fa8e dicom tls and dcm4che
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 677
diff changeset
165
677
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
166 Secure TLS connections without certificate
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
167 ------------------------------------------
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
168
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
169 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
170 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
171 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
172 tools).
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
173
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
174 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
175 to/from remote DICOM modalities that do not provide a DICOM TLS
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
176 certificate (which corresponds to the ``--verify-peer-cert`` option of
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
177 DCMTK). This requires setting the :ref:`configuration option
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
178 <configuration>` ``DicomTlsRemoteCertificateRequired`` of Orthanc to
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
179 ``false``.
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 .. highlight:: bash
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
182
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
183 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
184 dedicated to Orthanc::
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 $ 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
187 -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
188
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
189
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
190 .. highlight:: json
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
191
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
192 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
193
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
194 {
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
195 "DicomTlsEnabled" : true,
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
196 "DicomTlsCertificate" : "orthanc.crt",
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
197 "DicomTlsPrivateKey" : "orthanc.key",
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
198 "DicomTlsTrustedCertificates" : "orthanc.crt",
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
199 "DicomTlsRemoteCertificateRequired" : false
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
200 }
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 .. highlight:: text
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
203
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
204 Note that the ``DicomTlsTrustedCertificates`` is set to a dummy value,
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
205 because this option must always be present. It is then possible to
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
206 connect to Orthanc without SCU certificate as follows::
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 $ 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
209 I: Requesting Association
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
210 I: Association Accepted (Max Send PDV: 16372)
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
211 I: Sending Echo Request (MsgID 1)
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
212 I: Received Echo Response (Success)
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
213 I: Releasing Association
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
214
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
215
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
216 **Remark:** Importantly, if the remote DICOM modality provides an
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
217 invalid DICOM TLS certificate, Orthanc will never accept the
25e44dba9dba Secure TLS connections without certificate
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 609
diff changeset
218 connection.