Mercurial > hg > orthanc-book
comparison Sphinx/source/faq/https.rst @ 397:18ef1c795d17
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 } |