Mercurial > hg > orthanc-book

comparison Sphinx/source/faq/https.rst @ 397:18ef1c795d17

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
extending page about https
author Sebastien Jodogne <s.jodogne@gmail.com>
date Wed, 22 Apr 2020 08:58:30 +0200
parents 011b01ccf52d
children be8b638f3f46
comparison
equal deleted inserted replaced
396:5388a611b7eb 397:18ef1c795d17
1 .. highlight:: bash
2 .. _https: 1 .. _https:
3 2
4 HTTPS encryption with Orthanc 3 HTTPS encryption with Orthanc
5 ============================= 4 =============================
5
6 .. contents::
7
8 Overview
9 --------
6 10
7 It is highly desirable to enable HTTPS (SSL) encryption with Orthanc 11 It is highly desirable to enable HTTPS (SSL) encryption with Orthanc
8 to protect its REST API, as it provides access to medical 12 to protect its REST API, as it provides access to medical
9 information. To this end, you have two possibilites: 13 information. To this end, you have two possibilites:
10 14
29 <https://en.wikipedia.org/wiki/X.509#Certificate_filename_extensions>`_. 33 <https://en.wikipedia.org/wiki/X.509#Certificate_filename_extensions>`_.
30 2. Prepend this certificate with the content of your private key. 34 2. Prepend this certificate with the content of your private key.
31 3. Modify the ``SslEnabled`` and ``SslCertificate`` variables in the 35 3. Modify the ``SslEnabled`` and ``SslCertificate`` variables in the
32 :ref:`Orthanc configuration file <configuration>`. 36 :ref:`Orthanc configuration file <configuration>`.
33 37
34 Here are simple instructions to create a self-signed SSL certificate 38
35 that is suitable for test environments with the `OpenSSL 39 Examples
40 --------
41
42 Securing Orthanc using self-signed certificate
43 ..............................................
44
45 .. highlight:: bash
46
47 Here are instructions to create a simple self-signed SSL certificate
48 that is suitable for test environments thanks to the `OpenSSL
36 <https://en.wikipedia.org/wiki/Openssl>`_ command-line tools:: 49 <https://en.wikipedia.org/wiki/Openssl>`_ command-line tools::
37 50
38 $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout private.key -out certificate.crt 51 $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /tmp/private.key -out /tmp/certificate.crt
39 $ cat private.key certificate.crt > certificate.pem 52 $ cat /tmp/private.key /tmp/certificate.crt > /tmp/certificate.pem
40 53
41 Some interesting references about this topic can be found `here 54 **Important:** While invoking ``openssl``, make sure to set the option
42 <http://www.devsec.org/info/ssl-cert.html>`__, `here 55 ``Common Name (e.g. server FQDN or YOUR name)`` to the name of your
43 <https://www.akadia.com/services/ssh_test_certificate.html>`__, and 56 server. For testing on your local computer, you would set this option
44 `here 57 to value ``localhost``.
58
59 The file ``/tmp/certificate.crt`` can be publicly distributed. The
60 files ``/tmp/private.key`` and ``/tmp/certificate.pem`` must be kept
61 secret and must be stored securely.
62
63 Some interesting references about generating self-signed certificates
64 can be found `here <http://www.devsec.org/info/ssl-cert.html>`__,
65 `here <https://www.akadia.com/services/ssh_test_certificate.html>`__,
66 and `here
45 <https://stackoverflow.com/questions/991758/how-to-get-pem-file-from-key-and-crt-files>`__. 67 <https://stackoverflow.com/questions/991758/how-to-get-pem-file-from-key-and-crt-files>`__.
68
69 .. highlight:: json
70
71 Once the certificate is generated, you can start Orthanc using the
72 following minimal configuration file::
73
74 {
75 "SslEnabled" : true,
76 "SslCertificate" : "/tmp/certificate.pem"
77 }
78
79
80
81
82 Querying Orthanc using HTTPS
83 ............................
84
85 .. highlight:: txt
86
87 If you contact Orthanc using a HTTP client, you will see that
88 encryption is enabled::
89
90 $ curl http://localhost:8042/studies
91 curl: (52) Empty reply from server
92
93 Nothing is returned from the Orthanc server using the HTTP protocol,
94 as it must contacted using the HTTPS protocol. You have to provide the
95 ``https`` prefix::
96
97 $ curl https://localhost:8042/studies
98 curl: (60) SSL certificate problem: self signed certificate
99 More details here: https://curl.haxx.se/docs/sslcerts.html
100
101 curl failed to verify the legitimacy of the server and therefore could not
102 establish a secure connection to it. To learn more about this situation and
103 how to fix it, please visit the web page mentioned above.
104
105 The HTTPS client now complains, as it was not provided with our
106 self-signed certificate. For the query to succeed, you must provide
107 the public certificate ``/tmp/certificate.crt`` that was generated
108 above to the HTTPS client::
109
110 $ curl --cacert /tmp/certificate.crt https://localhost:8042/studies
111 [ "66c8e41e-ac3a9029-0b85e42a-8195ee0a-92c2e62e" ]
112
113
114 Configuring Orthanc peers
115 .........................
116
117 .. highlight:: json
118
119 Let us configure a second instance of Orthanc on the localhost that
120 will act as a client (i.e., an :ref:`Orthanc peer <peers>`) to the
121 HTTPS-protected Orthanc server. One would create the following
122 configuration file::
123
124 {
125 "HttpPort" : 8043,
126 "DicomPort" : 4343,
127 "OrthancPeers" : {
128 "https" : [ "https://localhost:8042/" ]
129 }
130 }
131
132
133 .. highlight:: bash
134
135 The values of the ``HttpPort`` and ``DicomPort`` options are set to
136 non-default values in order to avoid a collision with the
137 HTTPS-protected Orthanc. Let us now trigger a query from our Orthanc
138 client to the Orthanc server using the REST API of the Orthanc
139 client::
140
141 $ curl http://localhost:8043/peers/https/system
142 {
143 "Details" : "libCURL error: Problem with the SSL CA cert (path? access rights?)",
144 "HttpError" : "Internal Server Error",
145 "HttpStatus" : 500,
146 [...]
147 }
148
149 .. highlight:: json
150
151 Just like the cURL command-line client, the Orthanc client complains
152 about the fact it wasn't provided with the HTTPS public certificate.
153 The certificate must be provided by adapting the configuration file as
154 follows::
155
156 {
157 "HttpPort" : 8043,
158 "DicomPort" : 4343,
159 "HttpsCACertificates" : "/tmp/certificate.crt",
160 "OrthancPeers" : {
161 "https" : [ "https://localhost:8042/" ]
162 }
163 }
164
165
166 .. highlight:: bash
167
168 Using this new configuration, the query will succeed::
169
170 $ curl http://localhost:8043/peers/https/system
171 {
172 "ApiVersion" : 6,
173 "DicomAet" : "ORTHANC",
174 "DicomPort" : 4242,
175 "HttpPort" : 8042,
176 [...]
177 }