NOTES-Windows.txt

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