Mercurial > hg > orthanc-book

annotate Sphinx/source/faq/dicom-tls.rst @ 660:a6e371768a70

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
dicom-as-json
author Sebastien Jodogne <s.jodogne@gmail.com>
date Thu, 29 Apr 2021 12:41:31 +0200
parents 0dde82745e0d
children 25e44dba9dba
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
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
86 Example using DCMTK
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
87 -------------------
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
88
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
89 .. highlight:: bash
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
90
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
91 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
92 DCMTK::
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 $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
95 -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
96 $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
97 -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
98
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
99 .. highlight:: json
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
100
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
101 Let us start Orthanc using the following minimal configuration file::
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
102
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 "DicomTlsEnabled" : true,
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
105 "DicomTlsCertificate" : "orthanc.crt",
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
106 "DicomTlsPrivateKey" : "orthanc.key",
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
107 "DicomTlsTrustedCertificates" : "dcmtk.crt",
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
108 "DicomModalities" : {
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
109 "dmctk" : {
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
110 "Host" : "localhost",
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
111 "Port" : 4242,
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
112 "AET" : "DCMTK",
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
113 "UseDicomTls" : true
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
114 }
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 }
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 .. highlight:: txt
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 It is then possible to trigger a secure C-GET SCU request from DCMTK
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
121 to Orthanc as follows::
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
122
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
123 $ 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
124 I: Requesting Association
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
125 I: Association Accepted (Max Send PDV: 16372)
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
126 I: Sending Echo Request (MsgID 1)
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
127 I: Received Echo Response (Success)
0dde82745e0d documentation of DICOM TLS
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
128 I: Releasing Association