Mercurial > hg > orthanc-book

annotate Sphinx/source/faq/https.rst @ 1112:ad26102adccc default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
fix broken link
author Alain Mazy <am@orthanc.team>
date Wed, 23 Oct 2024 16:52:30 +0200
parents 01f61385877f
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
1 .. _https:
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
2
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
3 HTTPS encryption with Orthanc
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
4 =============================
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
5
397
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
6 .. contents::
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
7
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
8 Overview
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
9 --------
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
10
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
11 It is highly desirable to enable HTTPS (SSL) encryption with Orthanc
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
12 to protect its REST API, as it provides access to medical
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
13 information. To this end, you have two possibilites:
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
14
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
15 1. Put Orthanc behind an enterprise-ready HTTPS server such as
17
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 0
diff changeset
16 :ref:`Apache <apache>`, :ref:`nginx <nginx>` or :ref:`Microsoft IIS <iis>`.
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
17 2. For simple deployments, use Orthanc :ref:`built-in HTTPS server <https-builtin>`.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
18
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
19 **You should always favor the first option**. The second option might make
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
20 sense in the context of an hospital Intranet, i.e. the Orthanc server
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
21 is not publicly accessible from the Internet.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
22
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
23
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
24 .. _https-builtin:
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
25
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
26 Built-in encryption
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
27 -------------------
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
28
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
29 To enable the built-in HTTP server of Orthanc, you need to:
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
30
25
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 17
diff changeset
31 1. Obtain a `X.509 certificate <https://en.wikipedia.org/wiki/X.509>`_
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
32 in the `PEM format
25
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 17
diff changeset
33 <https://en.wikipedia.org/wiki/X.509#Certificate_filename_extensions>`_.
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
34 2. Prepend this certificate with the content of your private key.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
35 3. Modify the ``SslEnabled`` and ``SslCertificate`` variables in the
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
36 :ref:`Orthanc configuration file <configuration>`.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
37
909
5622e4ac108b note about missing libssl-dev
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 649
diff changeset
38 **Warning:** If you have installed Orthanc using the official package
5622e4ac108b note about missing libssl-dev
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 649
diff changeset
39 of a GNU/Linux distribution of the Debian family (such as Ubuntu),
5622e4ac108b note about missing libssl-dev
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 649
diff changeset
40 make sure that the ``libssl-dev`` package is installed. Otherwise,
5622e4ac108b note about missing libssl-dev
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 649
diff changeset
41 Orthanc will fail to start with the error message ``The TCP port of
5622e4ac108b note about missing libssl-dev
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 649
diff changeset
42 the HTTP server is privileged or already in use``. This is because
5622e4ac108b note about missing libssl-dev
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 649
diff changeset
43 Civetweb (the embedded HTTP server of Orthanc) cannot find the
5622e4ac108b note about missing libssl-dev
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 649
diff changeset
44 ``/usr/lib/x86_64-linux-gnu/libcrypto.so`` shared library (`reference
5622e4ac108b note about missing libssl-dev
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 649
diff changeset
45 <https://groups.google.com/g/orthanc-users/c/5N1K9iniBoA/m/EXiYrKt3BQAJ>`__).
5622e4ac108b note about missing libssl-dev
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 649
diff changeset
46
397
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
47
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
48 Examples
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
49 --------
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
50
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
51 Securing Orthanc using self-signed certificate
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
52 ..............................................
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
53
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
54 .. highlight:: bash
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
55
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
56 Here are instructions to create a simple self-signed SSL certificate
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
57 that is suitable for test environments thanks to the `OpenSSL
25
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 17
diff changeset
58 <https://en.wikipedia.org/wiki/Openssl>`_ command-line tools::
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
59
397
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
60 $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /tmp/private.key -out /tmp/certificate.crt
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
61 $ cat /tmp/private.key /tmp/certificate.crt > /tmp/certificate.pem
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
62
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
63 **Important:** While invoking ``openssl``, make sure to set the option
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
64 ``Common Name (e.g. server FQDN or YOUR name)`` to the name of your
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
65 server. For testing on your local computer, you would set this option
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
66 to value ``localhost``.
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
67
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
68 The file ``/tmp/certificate.crt`` can be publicly distributed. The
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
69 files ``/tmp/private.key`` and ``/tmp/certificate.pem`` must be kept
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
70 secret and must be stored securely.
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
71
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
72 Some interesting references about generating self-signed certificates
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
73 can be found `here <http://www.devsec.org/info/ssl-cert.html>`__,
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
74 `here <https://www.akadia.com/services/ssh_test_certificate.html>`__,
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
75 and `here
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
76 <https://stackoverflow.com/questions/991758/how-to-get-pem-file-from-key-and-crt-files>`__.
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
77
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
78 .. highlight:: json
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
79
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
80 Once the certificate is generated, you can start Orthanc using the
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
81 following minimal configuration file::
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
82
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
83 {
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
84 "SslEnabled" : true,
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
85 "SslCertificate" : "/tmp/certificate.pem"
649
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
86 }
397
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
87
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
88
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
89 Querying Orthanc using HTTPS
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
90 ............................
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
91
974
01f61385877f fix syntax
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 962
diff changeset
92 .. highlight:: none
397
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
93
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
94 If you contact Orthanc using a HTTP client, you will see that
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
95 encryption is enabled::
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
96
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
97 $ curl http://localhost:8042/studies
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
98 curl: (52) Empty reply from server
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
99
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
100 Nothing is returned from the Orthanc server using the HTTP protocol,
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
101 as it must contacted using the HTTPS protocol. You have to provide the
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
102 ``https`` prefix::
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
103
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
104 $ curl https://localhost:8042/studies
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
105 curl: (60) SSL certificate problem: self signed certificate
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
106 More details here: https://curl.haxx.se/docs/sslcerts.html
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
107
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
108 curl failed to verify the legitimacy of the server and therefore could not
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
109 establish a secure connection to it. To learn more about this situation and
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
110 how to fix it, please visit the web page mentioned above.
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
111
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
112 The HTTPS client now complains, as it was not provided with our
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
113 self-signed certificate. For the query to succeed, you must provide
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
114 the public certificate ``/tmp/certificate.crt`` that was generated
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
115 above to the HTTPS client::
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
116
397
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
117 $ curl --cacert /tmp/certificate.crt https://localhost:8042/studies
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
118 [ "66c8e41e-ac3a9029-0b85e42a-8195ee0a-92c2e62e" ]
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
119
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
120
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
121 Configuring Orthanc peers
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
122 .........................
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
123
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
124 .. highlight:: json
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
125
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
126 Let us configure a second instance of Orthanc on the localhost that
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
127 will act as a client (i.e., an :ref:`Orthanc peer <peers>`) to the
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
128 HTTPS-protected Orthanc server. One would create the following
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
129 configuration file::
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
130
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
131 {
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
132 "HttpPort" : 8043,
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
133 "DicomPort" : 4343,
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
134 "OrthancPeers" : {
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
135 "https" : [ "https://localhost:8042/" ]
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
136 }
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
137 }
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
138
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
139
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
140 .. highlight:: bash
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
141
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
142 The values of the ``HttpPort`` and ``DicomPort`` options are set to
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
143 non-default values in order to avoid a collision with the
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
144 HTTPS-protected Orthanc. Let us now trigger a query from our Orthanc
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
145 client to the Orthanc server using the REST API of the Orthanc
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
146 client::
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
147
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
148 $ curl http://localhost:8043/peers/https/system
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
149 {
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
150 "Details" : "libCURL error: Problem with the SSL CA cert (path? access rights?)",
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
151 "HttpError" : "Internal Server Error",
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
152 "HttpStatus" : 500,
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
153 [...]
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
154 }
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
155
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
156 .. highlight:: json
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
157
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
158 Just like the cURL command-line client, the Orthanc client complains
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
159 about the fact it wasn't provided with the HTTPS public certificate.
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
160 The certificate must be provided by adapting the configuration file as
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
161 follows::
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
162
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
163 {
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
164 "HttpPort" : 8043,
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
165 "DicomPort" : 4343,
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
166 "HttpsCACertificates" : "/tmp/certificate.crt",
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
167 "OrthancPeers" : {
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
168 "https" : [ "https://localhost:8042/" ]
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
169 }
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
170 }
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
171
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
172
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
173 .. highlight:: bash
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
174
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
175 Using this new configuration, the query will succeed::
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
176
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
177 $ curl http://localhost:8043/peers/https/system
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
178 {
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
179 "ApiVersion" : 6,
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
180 "DicomAet" : "ORTHANC",
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
181 "DicomPort" : 4242,
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
182 "HttpPort" : 8042,
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
183 [...]
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
184 }
512
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
185
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
186
649
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
187 Securing Orthanc peers with mutual TLS authentication
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
188 .....................................................
512
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
189
649
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
190 .. highlight:: json
512
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
191
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
192 Once HTTPS is enabled, Orthanc can also be configured to accept incoming
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
193 connections based on a certificate provided by the client.
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
194
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
195 Server side, this is configured via::
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
196
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
197 {
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
198 "SslVerifyPeers": true,
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
199 "SslTrustedClientCertificates": "trustedClientCertificates.pem"
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
200 }
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
201
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
202 ``SslTrustedClientCertificates`` shall contain a list of certificates
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
203 that are trusted. This can be a list of individual self-signed certificates
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
204 or this can contain a list of trusted root CAs.
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
205
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
206 Client side, this is configured via::
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
207
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
208 {
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
209 "OrthancPeers" : {
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
210 "orthanc-b" : {
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
211 "Url" : "https://localhost:8043",
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
212 "CertificateFile" : "client-crt.pem",
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
213 "CertificateKeyFile" : "client-key.pem",
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
214 "CertificateKeyPassword": ""
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
215 }
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
216 }
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
217 }
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
218
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
219 Note that the same kind of configuration is also available for
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
220 :ref:`DICOMweb client <dicomweb-client>`.
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
221
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
222 An example of such a setup with instructions to generate the
649
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
223 certificates is available `here
962
5df222ddd7d1 fix links to setup-samples
Alain Mazy <am@osimis.io>
parents: 947
diff changeset
224 <https://github.com/orthanc-server/orthanc-setup-samples/tree/master/docker/tls-mutual-auth/>`__.
649
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
225
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
226
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
227 .. _client-certificate-web-browser:
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
228
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
229 Securing Orthanc with a client certificate and access it using a Web browser
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
230 ............................................................................
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
231
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
232 .. highlight:: bash
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
233
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
234 Firstly, create a PEM certificate for the Orthanc HTTPS server, and another
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
235 PKCS12 certificate for the client::
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
236
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
237 $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
238 -keyout server.key -out server.crt -subj "/C=BE/CN=localhost"
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
239 $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
240 -keyout client.key -out client.crt -subj "/C=BE/CN=localhost"
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
241 $ cat server.key server.crt > server.pem
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
242 $ openssl pkcs12 -export -in client.crt -inkey client.key -out client.p12
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
243
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
244 In the last step, you'll have to provide a password (that can be
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
245 empty).
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
246
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
247 .. highlight:: bash
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
248
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
249 Secondly, start Orthanc using the following configuration file for Orthanc::
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
250
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
251 {
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
252 "SslEnabled" : true,
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
253 "SslCertificate" : "server.pem",
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
254 "SslVerifyPeers": true,
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
255 "SslTrustedClientCertificates": "client.crt"
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
256 }
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
257
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
258 Thirdly, install the PKCS12 client-side certificate ``client.p12`` in
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
259 your Web browser. For instance, check out `these instructions for
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
260 Mozilla Firefox
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
261 <https://security.stackexchange.com/questions/163199/firefox-certificate-can-t-be-installed>`__.
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
262
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
263 You are then able to access Orthanc using HTTPS encryption, with
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
264 cryptographic identification of a client Web browser. Note that
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
265 because the certificate is self-signed, the Web browser will warn
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
266 about a potential security risk.
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
267