changeset 609:0dde82745e0d

documentation of DICOM TLS
author Sebastien Jodogne <s.jodogne@gmail.com>
date Fri, 29 Jan 2021 14:35:55 +0100
parents a6d27fe89650
children ec8a9bcf1cdf 235e5a01ca4a
files Sphinx/source/contributing.rst Sphinx/source/dicom-guide.rst Sphinx/source/faq.rst Sphinx/source/faq/dicom-tls.rst Sphinx/source/faq/security.rst Sphinx/source/users/rest.rst
diffstat 6 files changed, 150 insertions(+), 13 deletions(-) [+]
line wrap: on
line diff
--- a/Sphinx/source/contributing.rst	Fri Jan 29 12:26:50 2021 +0100
+++ b/Sphinx/source/contributing.rst	Fri Jan 29 14:35:55 2021 +0100
@@ -19,7 +19,6 @@
 
             - Improved scalability of PostgreSQL databases
             - :ref:`Improved Web user interface <improving-interface>`
-            - :ref:`DICOM TLS <security>`
           
           * **Stone Web viewer**:
      
--- a/Sphinx/source/dicom-guide.rst	Fri Jan 29 12:26:50 2021 +0100
+++ b/Sphinx/source/dicom-guide.rst	Fri Jan 29 14:35:55 2021 +0100
@@ -671,8 +671,9 @@
 hospital, not the Internet or the cloud. This protocol might be
 blocked by outbound firewalls, and there is no convention ensuring
 that the AETs are globally unique across all the
-hospitals. Furthermore, even though the DICOM protocol supports TLS
-encryption, this feature is rarely enabled.
+hospitals. Furthermore, even though :ref:`Orthanc supports DICOM TLS
+encryption <dicom-tls>`, this feature is rarely enabled within
+hospitals.
 
 Depending on your application, you might therefore want to leverage
 the **HTTP protocol** in the context of DICOM. Such Web-based
--- a/Sphinx/source/faq.rst	Fri Jan 29 12:26:50 2021 +0100
+++ b/Sphinx/source/faq.rst	Fri Jan 29 14:35:55 2021 +0100
@@ -28,6 +28,7 @@
    faq/dicom.rst
    faq/compiling.rst
    faq/query-retrieve.rst
+   faq/dicom-tls.rst
    faq/rest-samples.rst
    faq/transcoding.rst
    faq/orthanc-storage.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Sphinx/source/faq/dicom-tls.rst	Fri Jan 29 14:35:55 2021 +0100
@@ -0,0 +1,128 @@
+.. _dicom-tls:
+
+Configuring DICOM TLS
+=====================
+
+.. contents::
+   :depth: 3
+
+Starting with release 1.9.0, Orthanc supports the encryption of the
+DICOM protocol using `DICOM TLS
+<https://www.dicomstandard.org/using/security/>`__. This allows the
+secure exchange of medical images between different sites, even if
+using the DICOM protocol.
+
+Configuration
+-------------
+
+.. highlight:: bash
+
+To enable DICOM TLS, each DICOM modality must have been assigned with
+a `X.509 certificate
+<https://en.wikipedia.org/wiki/X.509>`__. Obtaining such a certificate
+from a `recognized certification authority
+<https://en.wikipedia.org/wiki/Certificate_authority>`__ is obviously
+out of the scope of the Orthanc project. Here is a simple command-line
+to generate a self-signed certificate using the `OpenSSL
+<https://www.openssl.org/>`__ command-line tools::
+
+  $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
+            -keyout orthanc.key -out orthanc.crt -subj "/C=BE/CN=localhost"
+
+Obviously, you have adapt the arguments to your setup (notably the
+``subj`` argument that generates a certificate for Belgium for the
+server whose DNS address is ``localhost``). This command line will
+generate two files using the `PEM file format
+<https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail>`__:
+``orthanc.crt`` is the newly-generated certificate, and
+``orthanc.key`` contains the private key that protects the
+certificate. The ``orthanc.crt`` can be openly distributed, but
+``orthanc.key`` must be kept secret (it should only be placed on the
+modality using the corresponding certificate).
+
+Once ``orthanc.crt`` and ``orthanc.key`` have been generated, all the
+modalities that will be in touch with Orthanc (either as SCP or as
+SCU) through DICOM TLS must be identified, and their public
+certificates must be collected. All those certificates must be
+concatenated into a single file in order to tell Orthanc which
+modalities can be trusted.
+
+Concretely, if one has collected ``a.crt``, ``b.crt`` and ``c.crt`` as
+the certificates (in the PEM format) for trusted remote DICOM
+modalities, a ``trusted.crt`` file can be generated as follows::
+
+  $ cat a.crt b.crt c.crt > trusted.crt
+
+Once the three files ``orthanc.crt``, ``orthanc.key`` and
+``trusted.crt`` are available, setting the following
+:ref:`configuration options <configuration>` will enable DICOM TLS in
+**Orthanc SCP**:
+
+* ``DicomTlsEnabled`` must be set to ``true``.
+* ``DicomTlsCertificate`` must be set to ``orthanc.crt``.
+* ``DicomTlsPrivateKey`` must be set to ``orthanc.key`` (note that
+  this private key must not be password-protected).
+* ``DicomTlsTrustedCertificates`` must be set to ``trusted.crt``.
+
+If Orthanc acts as a **DICOM SCU** against one remote DICOM modality,
+and if this remote modality is protected by DICOM TLS, the
+``UseDicomTls`` field must be set to ``true`` in the definition of the
+modality in the configuration file of Orthanc (cf. the
+``DicomModalities`` option). The file indicated by
+``DicomTlsCertificate`` will be used to authentify Orthanc by the
+remote modality: This modality must thus include ``orthanc.crt`` in
+its list of trusted certificates.
+
+
+**Remark 1:** Pay attention not to confuse the configuration options
+related to HTTPS encryption, with the options related to DICOM TLS.
+In Orthanc, HTTPS and DICOM TLS are not obliged to use the same
+encryption certificates.
+
+**Remark 2:** Orthanc SCU and Orthanc SCP share the same set of
+trusted certificates.
+
+
+Example using DCMTK
+-------------------
+
+.. highlight:: bash
+
+Let us generate one certificate for Orthanc, and one certificate for
+DCMTK::
+
+  $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
+            -keyout orthanc.key -out orthanc.crt -subj "/C=BE/CN=localhost"
+  $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
+            -keyout dcmtk.key -out dcmtk.crt -subj "/C=BE/CN=localhost"
+
+.. highlight:: json
+
+Let us start Orthanc using the following minimal configuration file::
+
+  {
+    "DicomTlsEnabled" : true,
+    "DicomTlsCertificate" : "orthanc.crt",
+    "DicomTlsPrivateKey" : "orthanc.key",
+    "DicomTlsTrustedCertificates" : "dcmtk.crt",
+    "DicomModalities" : {
+      "dmctk" : {
+        "Host" : "localhost",
+        "Port" : 4242,
+        "AET" : "DCMTK",
+        "UseDicomTls" : true
+      }
+    }  
+  }
+
+.. highlight:: txt
+
+It is then possible to trigger a secure C-GET SCU request from DCMTK
+to Orthanc as follows::
+
+  $ echoscu -v -aet DCMTK localhost 4242 +tls dcmtk.key dcmtk.crt +cf orthanc.crt 
+  I: Requesting Association
+  I: Association Accepted (Max Send PDV: 16372)
+  I: Sending Echo Request (MsgID 1)
+  I: Received Echo Response (Success)
+  I: Releasing Association
--- a/Sphinx/source/faq/security.rst	Fri Jan 29 12:26:50 2021 +0100
+++ b/Sphinx/source/faq/security.rst	Fri Jan 29 14:35:55 2021 +0100
@@ -197,15 +197,19 @@
   configuration of remote modalities.
   
 
-**Remark:** As of Orthanc 1.8.2, `DICOM TLS encryption
-<https://www.dicomstandard.org/using/security/>`__ is not supported
-yet. As a temporary workaround, `it has been reported
+Starting with Orthanc 1.9.0, `DICOM TLS encryption
+<https://www.dicomstandard.org/using/security/>`__ is supported by
+Orthanc. If you need to share DICOM instances between sites, but if
+you don't want to use DICOMweb or Orthanc peers over HTTPS, you must
+enable :ref:`DICOM TLS in Orthanc <dicom-tls>` to ensure secure
+exchanges.
+
+As a workaround for the releases <= 1.8.2 of Orthanc that don't
+support DICOM TLS, `it has been reported
 <https://www.digihunch.com/2020/11/medical-imaging-web-server-deployment-pipeline/>`__
 that the "*SSL Termination for TCP Upstream Servers*" feature of nginx
 can be used to emulate DICOM TLS. Another option is to use `stunnel
-<https://www.stunnel.org/>`__. We are looking for :ref:`an industrial
-sponsor <contributing>` to implement DICOM TLS in the core of Orthanc,
-as this feature is dedicated to enterprise and cloud environments.
+<https://www.stunnel.org/>`__.
 
 
 Securing the storage
--- a/Sphinx/source/users/rest.rst	Fri Jan 29 12:26:50 2021 +0100
+++ b/Sphinx/source/users/rest.rst	Fri Jan 29 14:35:55 2021 +0100
@@ -492,12 +492,16 @@
 Using HTTPS
 ^^^^^^^^^^^
 
-If you're transfering medical data over internet, it is mandatory to use HTTPS.  
+If you're transfering medical data over internet, it is mandatory to
+use HTTPS.
 
-On the server side, we recommend to put Orthanc behing an :ref:`HTTPS server that will take care of the TLS <https>`.
+On the server side, we recommend to put Orthanc behind an :ref:`HTTPS
+server that will take care of the TLS <https>`.
 
-On the client side, in order for the client Orthanc to recognize the server certificate, you'll have to provide a path
-to the CA (certification authority) certificates.  This is done in the configuration file through this configurationg::
+On the client side, in order for the client Orthanc to recognize the
+server certificate, you'll have to provide a path to the CA
+(certification authority) certificates.  This is done in the
+configuration file through this configurationg::
 
     ...
     "HttpsCACertificates" : "/etc/ssl/certs/ca-certificates.crt,