NOTES-WINDOWS.md

   1 NOTES FOR WINDOWS PLATFORMS
   2 ===========================
   3
   4  There are various options to build and run OpenSSL on the Windows platforms.
   5
   6  "Native" OpenSSL uses the Windows APIs directly at run time.
   7  To build a native OpenSSL you can either use:
   8
   9      Microsoft Visual C++ (MSVC) C compiler on the command line
  10  or
  11      MinGW cross compiler
  12      run on the GNU-like development environment MSYS2
  13      or run on Linux or Cygwin
  14
  15  "Hosted" OpenSSL relies on an external POSIX compatibility layer
  16  for building (using GNU/Unix shell, compiler, and tools) and at run time.
  17  For this option you can use Cygwin.
  18
  19  Visual C++ native builds, aka VC-*
  20  =====================================
  21
  22  Requirement details
  23  -------------------
  24
  25  In addition to the requirements and instructions listed in INSTALL.md,
  26  these are required as well:
  27
  28  - Perl.
  29    We recommend Strawberry Perl, available from <http://strawberryperl.com/>
  30    Please read NOTES.PERL for more information, including the use of CPAN.
  31    An alternative is ActiveState Perl, <https://www.activestate.com/ActivePerl>
  32    for which you may need to explicitly build the Perl module Win32/Console.pm
  33    via <https://platform.activestate.com/ActiveState> and then download it.
  34
  35  - Microsoft Visual C compiler.
  36    Since these are proprietary and ever-changing we cannot test them all.
  37    Older versions may not work. Use a recent version wherever possible.
  38
  39  - Netwide Assembler (NASM), available from <https://www.nasm.us>
  40    Note that NASM is the only supported assembler.
  41
  42  Quick start
  43  -----------
  44
  45  1. Install Perl
  46
  47  2. Install NASM
  48
  49  3. Make sure both Perl and NASM are on your %PATH%
  50
  51  4. Use Visual Studio Developer Command Prompt with administrative privileges,
  52     choosing one of its variants depending on the intended architecture.
  53     Or run "cmd" and execute "vcvarsall.bat" with one of the options x86,
  54     x86_amd64, x86_arm, x86_arm64, amd64, amd64_x86, amd64_arm, or amd64_arm64.
  55     This sets up the environment variables needed for nmake.exe, cl.exe, etc.
  56     See also
  57     <https://docs.microsoft.com/cpp/build/building-on-the-command-line>
  58
  59  5. From the root of the OpenSSL source directory enter
  60     perl Configure VC-WIN32    if you want 32-bit OpenSSL or
  61     perl Configure VC-WIN64A   if you want 64-bit OpenSSL or
  62     perl Configure             to let Configure figure out the platform
  63
  64  6. nmake
  65
  66  7. nmake test
  67
  68  8. nmake install
  69
  70  For the full installation instructions, or if anything goes wrong at any stage,
  71  check the INSTALL.md file.
  72
  73  Installation directories
  74  ------------------------
  75
  76  The default installation directories are derived from environment
  77  variables.
  78
  79  For VC-WIN32, the following defaults are use:
  80
  81      PREFIX:      %ProgramFiles(86)%\OpenSSL
  82      OPENSSLDIR:  %CommonProgramFiles(86)%\SSL
  83
  84  For VC-WIN64, the following defaults are use:
  85
  86      PREFIX:      %ProgramW6432%\OpenSSL
  87      OPENSSLDIR:  %CommonProgramW6432%\SSL
  88
  89  Should those environment variables not exist (on a pure Win32
  90  installation for examples), these fallbacks are used:
  91
  92      PREFIX:      %ProgramFiles%\OpenSSL
  93      OPENSSLDIR:  %CommonProgramFiles%\SSL
  94
  95  ALSO NOTE that those directories are usually write protected, even if
  96  your account is in the Administrators group.  To work around that,
  97  start the command prompt by right-clicking on it and choosing "Run as
  98  Administrator" before running 'nmake install'.  The other solution
  99  is, of course, to choose a different set of directories by using
 100  --prefix and --openssldir when configuring.
 101
 102  Special notes for Universal Windows Platform builds, aka VC-*-UWP
 103  --------------------------------------------------------------------
 104
 105  - UWP targets only support building the static and dynamic libraries.
 106
 107  - You should define the platform type to "uwp" and the target arch via
 108    "vcvarsall.bat" before you compile. For example, if you want to build
 109    "arm64" builds, you should run "vcvarsall.bat x86_arm64 uwp".
 110
 111  Native OpenSSL built using MinGW
 112  ================================
 113
 114  MinGW offers an alternative way to build native OpenSSL, by cross compilation.
 115
 116  * Usually the build is done on Windows in a GNU-like environment called MSYS2.
 117
 118    MSYS2 provides GNU tools, a Unix-like command prompt,
 119    and a UNIX compatibility layer for applications.
 120    However, in this context it is only used for building OpenSSL.
 121    The resulting OpenSSL does not rely on MSYS2 to run and is fully native.
 122
 123    Requirement details
 124
 125    - MSYS2 shell, from <https://www.msys2.org/>
 126
 127    - Perl, at least version 5.10.0, which usually comes pre-installed with MSYS2
 128
 129    - make, installed using "pacman -S make" into the MSYS2 environment
 130
 131    - MinGW[64] compiler: mingw-w64-i686-gcc and/or mingw-w64-x86_64-gcc.
 132      These compilers must be on your MSYS2 $PATH.
 133      A common error is to not have these on your $PATH.
 134      The MSYS2 version of gcc will not work correctly here.
 135
 136    In the MSYS2 shell do the configuration depending on the target architecture:
 137
 138      ./Configure mingw ...
 139    or
 140      ./Configure mingw64 ...
 141    or
 142      ./Configure ...
 143    for the default architecture.
 144
 145    Apart from that, follow the Unix / Linux instructions in INSTALL.md.
 146
 147  * It is also possible to build mingw[64] on Linux or Cygwin.
 148
 149    In this case configure with the corresponding --cross-compile-prefix= option.
 150    For example
 151
 152      ./Configure mingw --cross-compile-prefix=i686-w64-mingw32- ...
 153    or
 154      ./Configure mingw64 --cross-compile-prefix=x86_64-w64-mingw32- ...
 155
 156    This requires that you've installed the necessary add-on packages for
 157    mingw[64] cross compilation.
 158
 159  Linking your application
 160  ========================
 161
 162  This section applies to all "native" builds.
 163
 164  If you link with static OpenSSL libraries then you're expected to
 165  additionally link your application with WS2_32.LIB, GDI32.LIB,
 166  ADVAPI32.LIB, CRYPT32.LIB and USER32.LIB. Those developing
 167  non-interactive service applications might feel concerned about
 168  linking with GDI32.LIB and USER32.LIB, as they are justly associated
 169  with interactive desktop, which is not available to service
 170  processes. The toolkit is designed to detect in which context it's
 171  currently executed, GUI, console app or service, and act accordingly,
 172  namely whether or not to actually make GUI calls. Additionally those
 173  who wish to /DELAYLOAD:GDI32.DLL and /DELAYLOAD:USER32.DLL and
 174  actually keep them off service process should consider implementing
 175  and exporting from .exe image in question own _OPENSSL_isservice not
 176  relying on USER32.DLL. E.g., on Windows Vista and later you could:
 177
 178         __declspec(dllexport) __cdecl BOOL _OPENSSL_isservice(void)
 179         {
 180             DWORD sess;
 181
 182             if (ProcessIdToSessionId(GetCurrentProcessId(), &sess))
 183                 return sess == 0;
 184             return FALSE;
 185         }
 186
 187  If you link with OpenSSL .DLLs, then you're expected to include into
 188  your application code a small "shim" snippet, which provides
 189  the glue between the OpenSSL BIO layer and your compiler run-time.
 190  See also the OPENSSL_Applink manual page.
 191
 192  Hosted OpenSSL built using Cygwin
 193  =================================
 194
 195  Cygwin implements a POSIX/Unix runtime system (cygwin1.dll) on top of the
 196  Windows subsystem and provides a Bash shell and GNU tools environment.
 197  Consequently, a build of OpenSSL with Cygwin is virtually identical to the
 198  Unix procedure.
 199
 200  To build OpenSSL using Cygwin, you need to:
 201
 202  * Install Cygwin, see <https://cygwin.com/>
 203
 204  * Install Cygwin Perl, at least version 5.10.0
 205    and ensure it is in the $PATH
 206
 207  * Run the Cygwin Bash shell
 208
 209  Apart from that, follow the Unix / Linux instructions in INSTALL.md.
 210
 211  NOTE: "make test" and normal file operations may fail in directories
 212  mounted as text (i.e. mount -t c:\somewhere /home) due to Cygwin
 213  stripping of carriage returns. To avoid this ensure that a binary
 214  mount is used, e.g. mount -b c:\somewhere /home.