# HG changeset patch # User Sebastien Jodogne # Date 1611927355 -3600 # Node ID 0dde82745e0da2b9396e0c5811220fe50e82ef52 # Parent a6d27fe896501c2ea9243ff1cabc88d3f2e3553f documentation of DICOM TLS diff -r a6d27fe89650 -r 0dde82745e0d Sphinx/source/contributing.rst --- 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 ` - - :ref:`DICOM TLS ` * **Stone Web viewer**: diff -r a6d27fe89650 -r 0dde82745e0d Sphinx/source/dicom-guide.rst --- 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 `, 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 diff -r a6d27fe89650 -r 0dde82745e0d Sphinx/source/faq.rst --- 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 diff -r a6d27fe89650 -r 0dde82745e0d Sphinx/source/faq/dicom-tls.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 +`__. 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 +`__. Obtaining such a certificate +from a `recognized certification 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 +`__ 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 +`__: +``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 ` 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 diff -r a6d27fe89650 -r 0dde82745e0d Sphinx/source/faq/security.rst --- 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 -`__ is not supported -yet. As a temporary workaround, `it has been reported +Starting with Orthanc 1.9.0, `DICOM TLS encryption +`__ 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 ` 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 `__ that the "*SSL Termination for TCP Upstream Servers*" feature of nginx can be used to emulate DICOM TLS. Another option is to use `stunnel -`__. We are looking for :ref:`an industrial -sponsor ` to implement DICOM TLS in the core of Orthanc, -as this feature is dedicated to enterprise and cloud environments. +`__. Securing the storage diff -r a6d27fe89650 -r 0dde82745e0d Sphinx/source/users/rest.rst --- 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 `. +On the server side, we recommend to put Orthanc behind an :ref:`HTTPS +server that will take care of the TLS `. -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,