Mercurial > hg > orthanc-book

annotate Sphinx/source/faq/https.rst @ 844:41bae819d80b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
added uclouvain
author Sebastien Jodogne <s.jodogne@gmail.com>
date Thu, 12 May 2022 09:39:48 +0200
parents 22e3868d2eb1
children 5622e4ac108b
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
397
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
38
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
39 Examples
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
40 --------
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
41
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
42 Securing Orthanc using self-signed certificate
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
43 ..............................................
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
44
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
45 .. highlight:: bash
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
46
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
47 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
48 that is suitable for test environments thanks to the `OpenSSL
25
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 17
diff changeset
49 <https://en.wikipedia.org/wiki/Openssl>`_ command-line tools::
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
50
397
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
51 $ 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
52 $ 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
53
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
54 **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
55 ``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
56 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
57 to value ``localhost``.
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
58
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
59 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
60 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
61 secret and must be stored securely.
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 Some interesting references about generating self-signed certificates
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
64 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
65 `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
66 and `here
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
67 <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
68
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
69 .. highlight:: json
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
70
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
71 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
72 following minimal configuration file::
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
73
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
74 {
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
75 "SslEnabled" : true,
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
76 "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
77 }
397
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
78
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 Querying Orthanc using HTTPS
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
81 ............................
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 .. highlight:: txt
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
84
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
85 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
86 encryption is enabled::
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 $ curl http://localhost:8042/studies
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
89 curl: (52) Empty reply from server
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 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
92 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
93 ``https`` prefix::
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
94
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
95 $ curl https://localhost:8042/studies
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
96 curl: (60) SSL certificate problem: self signed certificate
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
97 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
98
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
99 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
100 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
101 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
102
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
103 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
104 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
105 the public certificate ``/tmp/certificate.crt`` that was generated
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
106 above to the HTTPS client::
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
107
397
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
108 $ curl --cacert /tmp/certificate.crt https://localhost:8042/studies
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
109 [ "66c8e41e-ac3a9029-0b85e42a-8195ee0a-92c2e62e" ]
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
110
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 Configuring Orthanc peers
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
113 .........................
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
114
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
115 .. highlight:: json
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
116
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
117 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
118 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
119 HTTPS-protected Orthanc server. One would create the following
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
120 configuration file::
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
121
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 "HttpPort" : 8043,
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
124 "DicomPort" : 4343,
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
125 "OrthancPeers" : {
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
126 "https" : [ "https://localhost:8042/" ]
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
127 }
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
128 }
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
129
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 .. highlight:: bash
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
132
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
133 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
134 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
135 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
136 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
137 client::
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 $ curl http://localhost:8043/peers/https/system
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
140 {
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
141 "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
142 "HttpError" : "Internal Server Error",
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
143 "HttpStatus" : 500,
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
144 [...]
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
145 }
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
146
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
147 .. highlight:: json
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
148
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
149 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
150 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
151 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
152 follows::
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 "HttpPort" : 8043,
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
156 "DicomPort" : 4343,
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
157 "HttpsCACertificates" : "/tmp/certificate.crt",
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
158 "OrthancPeers" : {
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
159 "https" : [ "https://localhost:8042/" ]
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
160 }
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
161 }
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 .. highlight:: bash
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
165
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
166 Using this new configuration, the query will succeed::
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
167
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
168 $ curl http://localhost:8043/peers/https/system
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 "ApiVersion" : 6,
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
171 "DicomAet" : "ORTHANC",
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
172 "DicomPort" : 4242,
18ef1c795d17 extending page about https
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 358
diff changeset
173 "HttpPort" : 8042,
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 }
512
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
176
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
177
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
178 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
179 .....................................................
512
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
180
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
181 .. highlight:: json
512
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
182
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
183 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
184 connections based on a certificate provided by the client.
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 Server side, this is configured via::
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
187
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
188 {
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
189 "SslVerifyPeers": true,
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
190 "SslTrustedClientCertificates": "trustedClientCertificates.pem"
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
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
193 ``SslTrustedClientCertificates`` shall contain a list of certificates
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
194 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
195 or this can contain a list of trusted root CAs.
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 Client side, this is configured via::
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
198
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
199 {
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
200 "OrthancPeers" : {
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
201 "orthanc-b" : {
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
202 "Url" : "https://localhost:8043",
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
203 "CertificateFile" : "client-crt.pem",
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
204 "CertificateKeyFile" : "client-key.pem",
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
205 "CertificateKeyPassword": ""
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
206 }
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
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
210 Note that the same kind of configuration is also available for
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
211 :ref:`DICOMweb client <dicomweb-client>`.
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
212
be8b638f3f46 added mutual auth
Alain Mazy <alain@mazy.be>
parents: 397
diff changeset
213 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
214 certificates is available `here
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
215 <https://bitbucket.org/osimis/orthanc-setup-samples/src/master/docker/tls-mutual-auth/>`__.
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
216
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
217
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
218 .. _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
219
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
220 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
221 ............................................................................
22e3868d2eb1 Securing Orthanc with a client certificate and access it using a Web browser
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 512
diff changeset
222
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 .. 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
224
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 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
226 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
227
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 $ 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
229 -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
230 $ 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
231 -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
232 $ 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
233 $ 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
234
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 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
236 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
237
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 .. 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
239
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 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
241
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 {
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 "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
244 "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
245 "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
246 "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
247 }
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 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
250 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
251 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
252 <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
253
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 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
255 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
256 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
257 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
258