diff --git a/README.OpenSSL.md b/README.OpenSSL.md index 72e1faf93b..525bf866f5 100644 --- a/README.OpenSSL.md +++ b/README.OpenSSL.md @@ -3,126 +3,120 @@ Virtuoso and OpenSSL *Copyright (C) 1998-2019 OpenLink Software * -Virtuoso Open Source Edition uses the OpenSSL libraries for cryptographic operations as well as -handling both client-side and server-side secure connections for both HTTPS as well as iSQL/ODBC -transport layers. +Virtuoso Open Source Edition uses the OpenSSL libraries for cryptographic +operations as well as handling both client-side and server-side secure +connections for both HTTPS as well as iSQL/ODBC transport layers. -Virtuoso can be compiled against OpenSSL 0.9.8i upto OpenSSL v1.0.2p which is the current -Long Term Support (LTS) release of OpenSSL. +Virtuoso can be compiled against OpenSSL 0.9.8i up to OpenSSL v1.0.2p which +is the current Long Term Support (LTS) release of OpenSSL. -The development team is currently working on enhancing the code to support OpenSSL v1.1.x but as -this version uses a newer API that is incompatible with the previous versions this work is not yet -completed. +The OpenSSL v1.1.x API is incompatible with previous versions. The Virtuoso +development team is currently working on enhancing the Virtuoso code to +support the new API, but this work is not yet completed. -Many new Linux distributions are including OpenSSL v1.1.0 as their base version, although they -also supply an OpenSSL v1.0.x development kit for backward compatibility. +Many new Linux distributions are including OpenSSL v1.1.0 as their base +version, although they typically also supply an OpenSSL v1.0.x development +kit for backward compatibility. -Other operating systems like Mac OS X or Windows do not supply OpenSSL at all, but require third -party ports in order to work. +Other operating systems like macOS and Windows do not supply OpenSSL at all, +but require third party ports for this support. -During configure time Virtuoso will check the availability and version of the installed OpenSSL -development headers and libraries on your system and will report any issues it finds. +During `configure` time, Virtuoso will check the availability and version of +the installed OpenSSL development headers and libraries on your system and +will report any issues it finds. -Mac OS X --------- -As Apple is actively deprecating OpenSSL from Mac OS X, your system either has a pretty old version -of openssl, and in case of High Sierra (10.13) Apple removed the required include files from the -/usr/include/openssl directory completely. +macOS +----- +Apple is actively deprecating OpenSSL from macOS, so your system likely +has a pretty old version of `openssl`, and as of High Sierra (10.13), +Apple completely removed the required `include` files from the +`/usr/include/openssl` directory. We recommend installing the OpenSSL 1.0.2 library using: -``` + $ brew install openssl -``` -And at configure time you can use the following: -``` +At configure time, you can then use the following: + $ sh ./configure \ - ..... \ ..... \ --enable-openssl=/usr/local/opt/openssl/ -``` - -More information on porting VOS on Mac OS X can be found in [README.MACOSX.md](README.MACOSX.md) +More information on porting VOS to macOS can be found in +[`README.MACOSX.md`](README.MACOSX.md). Ubuntu 18.04 LTS ---------------- -Ubuntu installs both an OpenSSL v1.0.2 runtime as well as an OpenSSL v1.1.0 runtime in the form -of shared libraries which are installed side-by-side on the system. +Ubuntu installs both an OpenSSL v1.0.2 runtime and an OpenSSL v1.1.0 runtime +in the form of shared libraries which are installed side-by-side on the system. + +A developer can choose to install either the 1.0 or the 1.1 software +development kit (SDK) which includes the necessary header files and +development libraries. -A developer can choose to install either the 1.0 or the 1.1 software development kit (SDK) which -includes the necessary header files and development libraries. +To build VOS, you need to run the following command which will uninstall +the 1.1 SDK and replace it with the 1.0 SDK. -For building VOS you need to run the following command which will uninstall the 1.1 SDK and -replace it with the 1.0 SDK. -``` $ sudo apt-get install libssl1.0-dev -``` -Since Ubuntu installs runtime libraries for both versions of OpenSSL side-by-side, after compiling -and installing VOS on your system, you can re-install the newer 1.1 SDK for compiling other programs -by running: -``` - $ sudo apt-get install libssl-dev -``` +Since Ubuntu installs runtime libraries for both versions of OpenSSL +side-by-side, after compiling and installing VOS on your system, you can +re-install the newer 1.1 SDK for compiling other programs by running: + $ sudo apt-get install libssl-dev Debian 9 -------- Debian uses the same package names as Ubuntu: -``` + $ sudo apt-get install libssl1.0-dev -``` And to switch back: -``` + $ sudo apt-get install libssl-dev -``` Fedora 28 --------- Fedora 28 also has separate SDKs for both versions of OpenSSL. To install the 1.0 SDK use: -``` + $ sudo dnf install --allowerasing compat-openssl10-devel -``` To switch back to the 1.1 SDK use: -``` - $ sudo dnf install --allowerasign openssl-devel -``` + $ sudo dnf install --allowerasign openssl-devel Windows ------- -The OpenSSL library needs to be built as a static library using Visual Studio. -The detailed instructions for building OpenSSL can be found in the INSTALL.W32 -document in the OpenSSL source distribution. +The OpenSSL library needs to be built as a static library using Visual +Studio. Detailed instructions for building OpenSSL can be found in the +`INSTALL.W32` document in the OpenSSL source distribution. -**IMPORTANT**: By default the OpenSSL library is built using MSVCRT compile flags, -leading to conflicts when linking the Virtuoso Open-Source binaries. To resolve -the conflicts, after unpacking the OpenSSL source tarball, you need to edit the -/util/pl/VC-32.pl and change the "cflags" to use the "/MT" and "/MTd" compiler -switches instead of the "/MD" and "/MDd". +**IMPORTANT**: By default the OpenSSL library is built using `MSVCRT` compile +flags, leading to conflicts when linking the Virtuoso Open-Source binaries. +To resolve the conflicts, after unpacking the OpenSSL source tarball, you +need to edit `/util/pl/VC-32.pl`, and change the `cflags` to use the `/MT` +and `/MTd` compiler switches instead of the `/MD` and `/MDd`. -Finally the libeay32.lib and ssleay32.lib from /out32 and files from /inc32/ -openssl must be copied to the /win32/openssl/ +Finally, the `libeay32.lib` and `ssleay32.lib` from `/out32` and files from +`/inc32/openssl` must be copied to `/win32/openssl/`. -More notes on porting Virtuoso on Windows can be found in [README.WINDOWS](README.WINDOWS). +More notes on porting Virtuoso on Windows can be found in +[`README.WINDOWS`](README.WINDOWS). Custom installation ------------------- -If you have performed a custom build of OpenSSL on your own system and/or if OpenSSL is installed -in a non-standard location, you can use the following flag during configure to point the build -system to the location where your OpenSSL headers and libraries are installed: -``` +If you have performed a custom build of OpenSSL on your own system, and/or +if OpenSSL is installed in a non-standard location, you can use the +`--enable-openssl` flag during `configure` to point the build system to the +location where your OpenSSL headers and libraries are installed: + $ sh ./configure \ - ..... \ ..... \ --enable-openssl=/opt/openssl/ -``` -The configure script will check /opt/openssl/include for the required header files and -/opt/openssl/lib for the libraries, before any standard locations embedded in the compiler. +The `configure` script will also check `/opt/openssl/include` for the +required header files and `/opt/openssl/lib` for the libraries, before any +standard locations embedded in the compiler.