Mercurial > hg > orthanc-book

comparison Sphinx/source/faq/dicom-tls.rst @ 609:0dde82745e0d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
documentation of DICOM TLS
author Sebastien Jodogne <s.jodogne@gmail.com>
date Fri, 29 Jan 2021 14:35:55 +0100
parents
children 25e44dba9dba
comparison
equal deleted inserted replaced
608:a6d27fe89650 609:0dde82745e0d
1 .. _dicom-tls:
2
3 Configuring DICOM TLS
4 =====================
5
6 .. contents::
7 :depth: 3
8
9 Starting with release 1.9.0, Orthanc supports the encryption of the
10 DICOM protocol using `DICOM TLS
11 <https://www.dicomstandard.org/using/security/>`__. This allows the
12 secure exchange of medical images between different sites, even if
13 using the DICOM protocol.
14
15 Configuration
16 -------------
17
18 .. highlight:: bash
19
20 To enable DICOM TLS, each DICOM modality must have been assigned with
21 a `X.509 certificate
22 <https://en.wikipedia.org/wiki/X.509>`__. Obtaining such a certificate
23 from a `recognized certification authority
24 <https://en.wikipedia.org/wiki/Certificate_authority>`__ is obviously
25 out of the scope of the Orthanc project. Here is a simple command-line
26 to generate a self-signed certificate using the `OpenSSL
27 <https://www.openssl.org/>`__ command-line tools::
28
29 $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
30 -keyout orthanc.key -out orthanc.crt -subj "/C=BE/CN=localhost"
31
32 Obviously, you have adapt the arguments to your setup (notably the
33 ``subj`` argument that generates a certificate for Belgium for the
34 server whose DNS address is ``localhost``). This command line will
35 generate two files using the `PEM file format
36 <https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail>`__:
37 ``orthanc.crt`` is the newly-generated certificate, and
38 ``orthanc.key`` contains the private key that protects the
39 certificate. The ``orthanc.crt`` can be openly distributed, but
40 ``orthanc.key`` must be kept secret (it should only be placed on the
41 modality using the corresponding certificate).
42
43 Once ``orthanc.crt`` and ``orthanc.key`` have been generated, all the
44 modalities that will be in touch with Orthanc (either as SCP or as
45 SCU) through DICOM TLS must be identified, and their public
46 certificates must be collected. All those certificates must be
47 concatenated into a single file in order to tell Orthanc which
48 modalities can be trusted.
49
50 Concretely, if one has collected ``a.crt``, ``b.crt`` and ``c.crt`` as
51 the certificates (in the PEM format) for trusted remote DICOM
52 modalities, a ``trusted.crt`` file can be generated as follows::
53
54 $ cat a.crt b.crt c.crt > trusted.crt
55
56 Once the three files ``orthanc.crt``, ``orthanc.key`` and
57 ``trusted.crt`` are available, setting the following
58 :ref:`configuration options <configuration>` will enable DICOM TLS in
59 **Orthanc SCP**:
60
61 * ``DicomTlsEnabled`` must be set to ``true``.
62 * ``DicomTlsCertificate`` must be set to ``orthanc.crt``.
63 * ``DicomTlsPrivateKey`` must be set to ``orthanc.key`` (note that
64 this private key must not be password-protected).
65 * ``DicomTlsTrustedCertificates`` must be set to ``trusted.crt``.
66
67 If Orthanc acts as a **DICOM SCU** against one remote DICOM modality,
68 and if this remote modality is protected by DICOM TLS, the
69 ``UseDicomTls`` field must be set to ``true`` in the definition of the
70 modality in the configuration file of Orthanc (cf. the
71 ``DicomModalities`` option). The file indicated by
72 ``DicomTlsCertificate`` will be used to authentify Orthanc by the
73 remote modality: This modality must thus include ``orthanc.crt`` in
74 its list of trusted certificates.
75
76
77 **Remark 1:** Pay attention not to confuse the configuration options
78 related to HTTPS encryption, with the options related to DICOM TLS.
79 In Orthanc, HTTPS and DICOM TLS are not obliged to use the same
80 encryption certificates.
81
82 **Remark 2:** Orthanc SCU and Orthanc SCP share the same set of
83 trusted certificates.
84
85
86 Example using DCMTK
87 -------------------
88
89 .. highlight:: bash
90
91 Let us generate one certificate for Orthanc, and one certificate for
92 DCMTK::
93
94 $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
95 -keyout orthanc.key -out orthanc.crt -subj "/C=BE/CN=localhost"
96 $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
97 -keyout dcmtk.key -out dcmtk.crt -subj "/C=BE/CN=localhost"
98
99 .. highlight:: json
100
101 Let us start Orthanc using the following minimal configuration file::
102
103 {
104 "DicomTlsEnabled" : true,
105 "DicomTlsCertificate" : "orthanc.crt",
106 "DicomTlsPrivateKey" : "orthanc.key",
107 "DicomTlsTrustedCertificates" : "dcmtk.crt",
108 "DicomModalities" : {
109 "dmctk" : {
110 "Host" : "localhost",
111 "Port" : 4242,
112 "AET" : "DCMTK",
113 "UseDicomTls" : true
114 }
115 }
116 }
117
118 .. highlight:: txt
119
120 It is then possible to trigger a secure C-GET SCU request from DCMTK
121 to Orthanc as follows::
122
123 $ echoscu -v -aet DCMTK localhost 4242 +tls dcmtk.key dcmtk.crt +cf orthanc.crt
124 I: Requesting Association
125 I: Association Accepted (Max Send PDV: 16372)
126 I: Sending Echo Request (MsgID 1)
127 I: Received Echo Response (Success)
128 I: Releasing Association