projects / ceph.git / blame
| Commit | Line | Data |
|---|---|---|
| 7c673cae FG |
1 | Adding OpenSSL Support |
| 2 | ===== | |
| 3 | ||
| 4 | Civetweb supports *HTTPS* connections using the OpenSSL transport layer | |
| 5 | security (TLS) library. OpenSSL is a free, open source library (see | |
| 6 | http://www.openssl.org/). | |
| 7 | ||
| 8 | ||
| 9 | Getting 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 | ||
| 18 | Civetweb Configuration | |
| 19 | ---- | |
| 20 | ||
| 21 | The configuration file must contain an https port, identified by a letter 's' | |
| 22 | attached to the port number. | |
| 23 | To serve http and https from their standard ports use the following line in | |
| 24 | the configuration file 'civetweb.conf': | |
| 25 | <pre> | |
| 26 | listening_ports 80, 443s | |
| 27 | </pre> | |
| 28 | To serve only https use: | |
| 29 | <pre> | |
| 30 | listening_ports 443s | |
| 31 | </pre> | |
| 32 | ||
| 33 | Furthermore the SSL certificate file must be set: | |
| 34 | <pre> | |
| 35 | ssl_certificate d:\civetweb\certificate\server.pem | |
| 36 | </pre> | |
| 37 | ||
| 38 | ||
| 39 | Creating a self signed certificate | |
| 40 | ---- | |
| 41 | ||
| 42 | OpenSSL provides a command line interface, that can be used to create the | |
| 43 | certificate file required by civetweb (server.pem). | |
| 44 | ||
| 45 | One can use the following steps in Windows (in Linux replace "copy" by "cp" | |
| 46 | and "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 | ||
| 64 | The 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 | |
| 66 | encoded data): | |
| 67 | ||
| 68 | <pre> | |
| 69 | -----BEGIN CERTIFICATE----- | |
| 70 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 71 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 72 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 73 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 74 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 75 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 76 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 77 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 78 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 79 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 80 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 81 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 82 | xxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 83 | -----END CERTIFICATE----- | |
| 84 | -----BEGIN RSA PRIVATE KEY----- | |
| 85 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 86 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 87 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 88 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 89 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 90 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 91 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 92 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 93 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 94 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 95 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 96 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 97 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | |
| 98 | -----END RSA PRIVATE KEY----- | |
| 99 | </pre> | |
| 100 | ||
| 101 | ||
| 102 | Including a certificate from a certificate authority | |
| 103 | ---- | |
| 104 | ||
| 105 | CivetWeb requires one certificate file in PEM format. | |
| 106 | If you got multiple files from your certificate authority, | |
| 107 | you need to copy their content together into one file. | |
| 108 | Make sure the file has one section BEGIN RSA PRIVATE KEY / | |
| 109 | END RSA PRIVATE KEY, and at least one section | |
| 110 | BEGIN CERTIFICATE / END CERTIFICATE. | |
| 111 | In case you received a file with a section | |
| 112 | BEGIN PRIVATE KEY / END PRIVATE KEY, | |
| 113 | you may get a suitable file by adding the letters RSA manually. | |
| 114 | ||
| 115 | Set the "ssl_certificate" configuration parameter to the | |
| 116 | file name (including path) of the resulting *.pem file. | |
| 117 | ||
| 118 | The file must look like the file in the section | |
| 119 | "Creating a self signed certificate", but it will have several | |
| 120 | BEGIN CERTIFICATE / END CERTIFICATE sections. | |
| 121 | ||
| 122 | ||
| 123 | Common Problems | |
| 124 | ---- | |
| 125 | ||
| 126 | In case the OpenSSL configuration is not set up correctly, the server will not | |
| 127 | start. Configure an error log file in 'civetweb.conf' to get more information: | |
| 128 | <pre> | |
| 129 | error_log_file error.log | |
| 130 | </pre> | |
| 131 | ||
| 132 | Check the content of 'error.log': | |
| 133 | ||
| 134 | <pre> | |
| 135 | load_dll: cannot load libeay32.*/libcrypto.*/ssleay32.*/libssl.* | |
| 136 | </pre> | |
| 137 | This error message means, the SSL library has not been installed (correctly). | |
| 138 | For Windows you might use the pre-built binaries. A link is available at the | |
| 139 | OpenSSL project home page (http://www.openssl.org/related/binaries.html). | |
| 140 | Choose the windows system folder as installation directory - this is the | |
| 141 | default location. | |
| 142 | ||
| 143 | <pre> | |
| 144 | set_ssl_option: cannot open server.pem: error:PEM routines:*:PEM_read_bio:no start line | |
| 145 | set_ssl_option: cannot open server.pem: error:PEM routines:*:PEM_read_bio:bad end line | |
| 146 | </pre> | |
| 147 | These error messages indicate, that the format of the ssl_certificate file does | |
| 148 | not match the expectations of the SSL library. The PEM file must contain both, | |
| 149 | a 'CERTIFICATE' and a 'RSA PRIVATE KEY' section. It should be a strict ASCII | |
| 150 | file without byte-order marks. | |
| 151 | The instructions above may be used to create a valid ssl_certificate file. | |
| 152 | ||
| 153 |