1Adding OpenSSL Support
2=====
3
4Civetweb supports *HTTPS* connections using the OpenSSL transport layer
5security (TLS) library. OpenSSL is a free, open source library (see
6http://www.openssl.org/). While there are other TLS libraries beside OpenSSL (like gnuTLS and wolfSSL), new TLS features in CivetWeb are tested only using OpenSSL.
7
8
9Getting Started
10----
11
12- Install OpenSSL on your system. There are OpenSSL install packages for all
13  major Linux distributions as well as a setup for Windows.
14- The default build configuration of the civetweb web server will load the
15  required OpenSSL libraries, if a HTTPS certificate has been configured.
16
17
18Civetweb Configuration
19----
20
21The configuration file must contain an https port, identified by a letter 's'
22attached to the port number.
23To serve http and https from their standard ports use the following line in
24the configuration file 'civetweb.conf':
25<pre>
26  listening_ports 80, 443s
27</pre>
28To serve only https use:
29<pre>
30  listening_ports 443s
31</pre>
32
33Furthermore the SSL certificate file must be set:
34<pre>
35  ssl_certificate d:\civetweb\certificate\server.pem
36</pre>
37
38
39Creating a self signed certificate
40----
41
42OpenSSL provides a command line interface, that can be used to create the
43certificate file required by civetweb (server.pem).
44
45One can use the following steps in Windows (in Linux replace "copy" by "cp"
46and "type" by "cat"):
47
48<pre>
49  openssl genrsa -des3 -out server.key 1024
50
51  openssl req -new -key server.key -out server.csr
52
53  copy server.key server.key.orig
54
55  openssl rsa -in server.key.orig -out server.key
56
57  openssl x509 -req -days 3650 -in server.csr -signkey server.key -out server.crt
58
59  copy server.crt server.pem
60
61  type server.key >> server.pem
62</pre>
63
64The server.pem file created must contain a 'CERTIFICATE' section as well as a
65'RSA PRIVATE KEY' section. It should look like this (x represents BASE64
66encoded data):
67
68<pre>
69-----BEGIN CERTIFICATE-----
70xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
71xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
72xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
73xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
74xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
75xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
76xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
77xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
78xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
79xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
80xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
81xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
82xxxxxxxxxxxxxxxxxxxxxxxxxxxx
83-----END CERTIFICATE-----
84-----BEGIN RSA PRIVATE KEY-----
85xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
86xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
87xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
88xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
89xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
90xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
91xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
92xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
93xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
94xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
95xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
96xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
97xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
98-----END RSA PRIVATE KEY-----
99</pre>
100
101Some additional useful OpenSSL commands can be found here: https://geekflare.com/openssl-commands-certificates/
102
103Certificates may contain [subject alternative names (SAN)](https://en.wikipedia.org/wiki/Subject_Alternative_Name)
104to support multiple websites: https://geekflare.com/san-ssl-certificate/
105
106
107Including a certificate from a certificate authority
108----
109
110CivetWeb requires one certificate file in PEM format.
111If you got multiple files from your certificate authority,
112you need to copy their content together into one file.
113Make sure the file has one section BEGIN RSA PRIVATE KEY /
114END RSA PRIVATE KEY, and at least one section
115BEGIN CERTIFICATE / END CERTIFICATE.
116In case you received a file with a section
117BEGIN PRIVATE KEY / END PRIVATE KEY,
118you may get a suitable file by adding the letters RSA manually.
119
120Set the "ssl_certificate" configuration parameter to the
121file name (including path) of the resulting *.pem file.
122
123The file must look like the file in the section
124"Creating a self signed certificate", but it will have several
125BEGIN CERTIFICATE / END CERTIFICATE sections.
126
127
128Common Problems
129----
130
131In case the OpenSSL configuration is not set up correctly, the server will not
132start. Configure an error log file in 'civetweb.conf' to get more information:
133<pre>
134  error_log_file error.log
135</pre>
136
137Check the content of 'error.log':
138
139<pre>
140load_dll: cannot load libeay32.*/libcrypto.*/ssleay32.*/libssl.*
141</pre>
142This error message means, the SSL library has not been installed (correctly).
143For Windows you might use the pre-built binaries. A link is available at the
144OpenSSL project home page (http://www.openssl.org/related/binaries.html).
145Choose the windows system folder as installation directory - this is the
146default location.
147
148<pre>
149set_ssl_option: cannot open server.pem: error:PEM routines:*:PEM_read_bio:no start line
150set_ssl_option: cannot open server.pem: error:PEM routines:*:PEM_read_bio:bad end line
151</pre>
152These error messages indicate, that the format of the ssl_certificate file does
153not match the expectations of the SSL library. The PEM file must contain both,
154a 'CERTIFICATE' and a 'RSA PRIVATE KEY' section. It should be a strict ASCII
155file without byte-order marks.
156The instructions above may be used to create a valid ssl_certificate file.
157
158
159