articles/openssl-mingw.html

   1 <HTML><HEAD>
   2 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=koi8-r">
   3 <TITLE>Building OpenSSL for Windows with Mingw32</TITLE>
   4 <META NAME="DESCRIPTION" CONTENT="Summary of experience of building both
   5 stable and development versions of OpenSSL for Windows"> </HEAD><BODY>
   6 <H1>Building OpenSSL for Windows with Mingw32</H1>
   7 <p>
   8 If you want to get OpenSSL libraries (either .dll or static libraries),
   9 usable by native Windows compilers, you can use entirely free GNU
  10 compiler, downloadable from internet.
  11 </p>
  12 <p>
  13 OpenSSL is written on plain old C, which means that as long as compilers
  14 use common object file format, you can easily link object files and
  15 static libraries, produced by one compiler, with another.
  16 </p>
  17 <p>
  18 GNU MinGW32 compiler uses COFF object format, same as Microsoft Visual
  19 studio. It just has different naming convention. Rename libssl.a,
  20 produced with MinGW to ssl.lib, and you can use it in MSVC.
  21 </p>
  22 <H2>Build environments</H2>
  23 <p>
  24 OpenSSL distribution includes file mingw.bat to build dll version with
  25 MinGW. Forget about it. It is outdated, unsupported and soon to be
  26 removed.
  27 </p>
  28 <p>Better to use unix style configure-make-make install approach. For
  29 this approach you'll need unix-like shell, perl and some utilities.
  30 </p>
  31 <p>There are three possible choices for the build environment:
  32 </p>
  33 <ol>
  34 <li><p>Use minimal needed set of utilites. You'll need:</p>
  35 <ul>
  36 <li>mingw32 compiler from <a href="http://www.mingw.org">mingw.org</a>
  37 <li>Minimal system (MSYS) from same site
  38 <li>Win32 version of Perl from <a
  39 href="http://www.activestate.com">ActiveState</a>
  40 </ul><p>
  41 This would take less than 100Mb on your disk and let your build lots of
  42 interesting things other than OpenSSL.</p>
  43 </li>
  44 <li><p>Use Cygwin toolchain. Yes, you can build native win32 programs,
  45 which don't depend on cygwin.dll with cygwin compiler.
  46 You'll need cygwin perl, make, coreutils and all some packages from
  47 cygwin  which have mingw in its name (from development section) You
  48 don-t need C++ compiler, but, probably would like to use mingw zlib.
  49 </p><p>I
  50 recommend to use this way only if you already have cygwin and
  51 accustomized to use it.
  52 </p>
  53 </li>
  54 <li><p>Compile all thing on nearby Linux/Unix machine using cross-compiler.
  55 If you use Debian GNU/Linux, you need just to install packages mingw32,
  56 mingw32-runtime and mingw32-binutils. You typically have make, perl and
  57 coreutils on Linux system. On other Unixes you probably will need to
  58 build mingw32 cross-compiler from gcc sources.
  59 </p>
  60 <p>
  61 I wouldn't cover building and  installing cross-compiler here.
  62 </p>
  63 </li>
  64 It is also possible to combine cygwin compiler and shell with
  65 ActiveState perl, but I wouldn't recommend to do so.
  66 <h2>Building static version</h2>
  67 <p>
  68 Download and unpack sources of openssl. It comes in the tar.gz archive.
  69 Any build environment mentioned above includes <tt>tar</tt> program
  70 which is used to unpack archives.
  71 </p>
  72 <p>
  73 Open command window (or terminal window on Unix), make sure that
  74 cygwin (or all of msys, mingw and ActiveState perl) directories are in
  75 your  PATH (on Unix cross compiler automatically installed into PATH and
  76 perl is already there),
  77 change into top-level  directory of unpacked source.
  78 <p>
  79 Open Configure script with text editor, find line
  80 </p>
  81 <pre>
  82 $IsMK1MF=1 if ($target eq "mingw" &amp;&amp; $^O ne "cygwin" &amp;&amp; !is_msys());
  83 </pre>
  84 <p>
  85 and comment it out (or delete altogether). If you are using Cygwin perl,
  86 you can omit this step. Condition would be false anyway. But function
  87 is_msys() might not work properly, and of course it wouldn't work when
  88 cross-compiling for Unix.
  89 </p>
  90 <tt>Configure</tt> script. On *nix you can just start
  91 </p>
  92 <pre>
  93 ./Configure mingw
  94 </pre>
  95 <p>
  96 With cygwin or ActiveState perl you'll have to feed this script to perl
  97 </p>
  98 <pre>
  99 perl Configure mingw
 100 </pre>
 101 <p>
 102 Soon you get message "Configured for mingw".
 103 </p>
 104 <p>
 105 Now, you are ready to run make. In the cygwin or msys environment just
 106 type make. On unix, if you type just  make, native compiler would be
 107 invoked. You have to specify crosscompiler in the CC makefile variable:
 108 </p>
 109 <pre>
 110  make CC=i586-mingw32msvc-gcc RANLIB=i585-mingw32msvc-ranlib
 111 </pre>
 112 <p>
 113 With current stable (0.9.8d) verything should go fine until rehash
 114 target would be invoked. With development branch (0.9.9) you can go into
 115 some trouble - it is development version, it supposed to be buggy. See
 116 <a href="#troubleshooting">Troubleshooting</a> section below for some
 117 hints.
 118 </p>
 119 <p>
 120 When make tells &quot;Doing certs&quot; it would probably complain about
 121 'openssl' program not found in msys and about inability to run program
 122 on Unix. You can safely ignore that for a while.
 123 </p>
 124 <p>
 125 After build is finished you should have <tt>openssl.exe</tt> file in the
 126 apps directory, and two library files <tt>libssl.a</tt> and
 127 <tt>libcrypto.a</tt> in the toplevel directory.
 128 </p>
 129 <p>
 130 If you are on native Win32 system, you may run test suite typing
 131 </p>
 132 <pre>
 133 make test
 134 </pre>
 135 <p>
 136 If you are doing build on Unix and want to run test, you have to find
 137 windows system to do so. This system should have MSYS and perl
 138 installed.
 139 </p>
 140 <h2>Doing shared build</h2>
 141 <p>
 142 You are probably not interesting in static build. Probably you want to
 143 have OpenSSL dlls which can be used with some native Win32 application
 144 such as <a href="http://www.miranda-im.org">Miranda IM</a>.
 145 </p>
 146 <p>
 147 To achieve this, you have to add <b>shared</b> parameter to
 148 <tt>Configure</tt>.
 149 <pre>
 150  perl Configure mingw shared
 151 </pre>
 152 <p>
 153 But there bad thing happens:
 154 </p>
 155 <p>
 156 everything is compiled, cryptoeay32-0.9.8.dll is built, but when it
 157 comes to building something that depends on this dll (such as
 158 ssleay32-0.9.8.dll), you get lot of complaints about unresolved symbols.
 159 </p>
 160 <p>
 161 If you examine dll with dumpbin tool from MSVC you'll see that it
 162 doesn't export anything.
 163 </p>
 164 <p>
 165 Fix is quite simple:
 166 </p>
 167 <p>
 168 Open Configure script with text editor, find line with mingw
 169 configuration option:
 170
 171 <pre>
 172 &quot;mingw&quot;,&quot;gcc:-mno-cygwin -DL_ENDIAN....
 173 </pre>
 174
 175 Find  fragment which defines options for dll building (it lloks like
 176 <pre>
 177 :-mno-cygwin -shared:
 178 </pre>
 179 and add there <tt>-Wl,--export-all</tt>, so section would look like:
 180 <pre>
 181 :-mno-cygwin -Wl,--export-all -shared:
 182 </pre>
 183
 184 Then rerun <tt>Configure mingw shared</tt> and make.
 185 Anything should run fine except certificate rehash.
 186 <H2>Defining openssl directory</H2>
 187 <p>
 188 There is some things, which OpenSSL searches in the compiled-in
 189 directory - configuration files and certificates. Path for openssl
 190 directory can be seen by issuing a command:
 191 </p>
 192 <pre>
 193 openssl version -d
 194 </pre>
 195 <p>
 196 Typically, it is unix-style path <tt>/usr/local/ssl</tt>. It is evident
 197 that there is little use of such path on Windows system. But it is not
 198 absolutely useless - if you have just one logical drive in your Windows
 199 machine, you can create there  <tt>c:\usr\local\ssl</tt> directory
 200 there, and OpenSSL would find its configuration file as long as current
 201 working directory of your OpenSSL application is on the C: drive.
 202 </p>
 203 <p>
 204 But it is better to define actual path during Configure stage. This is
 205 done via Configure option <tt>--openssldir</tt>.
 206 </p>
 207 <pre>
 208  perl Configure mingw shared --openssldir=c:/OpenSSL
 209 </pre>
 210 <p>
 211 There is another option - <tt>--prefix</tt> which is taken into account
 212 during make install, and used for search for dynamically loadable engine
 213 modules. But if you have working configuration file, you can always
 214 write <tt>dynamic_path</tt> there.
 215 </p>
 216 <p>
 217 There is a method to override location of configuration file.
 218 You can specify exact filename (not just directory name, but filename)
 219 in the <TT>OPENSSL_CONF</TT> environment variable.
 220 </p>
 221 <h2>Installing runtime modules of OpenSSL</h2>
 222 <p>
 223 There is no need to use <tt>make install</tt> under Windows.
 224 You just cope <tt>openssl.exe</tt> and two dlls (in case of shared
 225 build) into some dir in the your PATH. On Unix shared libraries go into
 226 <i>prefix</i>/<tt>lib</tt> directory, and executable files into
 227 <i>prefix</i>/<tt>bin</tt> and only bin has to be added to PATH.
 228 So does standard OpenSSL installation procedure.
 229 </p>
 230 <p>
 231 On Windows application search for DLLs using the same PATH as system
 232 uses to find executable files, but prepends directory where program
 233 itself resides. So if you throw executable and the dlls into same
 234 directory, it is guaranteed, that application would find those dlls.
 235 </p>
 236 <h2>Compiling 3rd party applications with OpenSSL</h2>
 237 <p>
 238 Typically, one compiles OpenSSL in order to use it in some programs.
 239 This can be windows-only programs, such as Miranda IM, or ports of Unix
 240 software such as PostgreSQL.
 241 </p>
 242 <p>
 243 In both cases you need to have include files and import libraries for
 244 DLLs available for you compiler. (you may choose to use static
 245 libraries, but DLLs are better - they allow to quickly upgrade OpenSSL
 246 in case of security update without recompiling all the applications).
 247 </p>
 248 <p>After you have built OpenSSL, there is include directory with openssl
 249 subdirectory. Copy this subdirectory with all its content into include
 250 directory of your compiler.
 251 </p>
 252 <p>
 253 Then, copy libssl.dll.a and libcrypto.dll.a to the library directory of
 254 your compiler.  Now you can use -lssl.dll -lcrypto.dll command line
 255 options for you Mingw32 compiler to link with OpenSSL libraries.
 256 </p>
 257 <p>
 258 Typically, windows applications expect something other than these names.
 259 For instance, PostgreSQL build system expects these libraries to be
 260 named libeay32.a for libcrypto and libssleay32.a for libssl.
 261 You can just rename libraries appropriately, or copy them (they are
 262 quite small because contains just references to DLL, not actual code).
 263 </p>
 264 <p>
 265 If you want to use openssl with Microsoft Visual Studio, you can just
 266 rename libcrypto.dll.a into libeay32.lib, and libssl.dll.a into
 267 ssleay32.lib. Microsoft .lib files are really ar archives and are
 268 compatible with mingw static libraries.
 269 </p>
 270 <h2><a name="trobuleshooting">Troubleshouting development version of
 271 OpenSSL</h2>
 272 <h3>Case 1. ws2tcpip incompatible with winsock</h3>
 273 <p>
 274 With OpenSSL cvs of Oct-20-2006 I've encountered problems that
 275 compilation fails with message "ws2tcpip.h is not compatible with
 276 winsock.h".
 277 </p>
 278 <p>
 279 Problem is that Windows has two versions of its TCPIP code winsock.h and
 280 winsock2.h. If you want to use newer version, you have to use
 281 winsock2.h. If your include winsock2.h, and then winsock.h everything is
 282 good - winsock.h sees if you have included winsock2 and does nothing. So
 283 you can use IPV6 functions declared in ws2tcpip.h etc.
 284 </p>
 285 <p>
 286 But windows.h file which comes with Mingw32 runtime includes winsock.h
 287 for some constants and types. So, if you haven't included winsock2.h
 288 prior to first inclusion of windows.h, and than want to include
 289 ws2tcpip.h,  compilation fails.
 290 </p>
 291 <p>
 292 OpenSSL includes winsock2.h and ws2tcpip.h via local include file
 293 e_os.h. But  windows.h is included not only via this file, but also via
 294 rand.h. So, if some code file includes rand.h (directly, or indirectly,
 295 via engine.h for example), prior to e_os.h, you are in trouble.
 296 </p>
 297 <p>
 298 Solution is simple - find out where offending file is included, and
 299 add <tt>#include "e_os.h"</tt> on the previous line. I've found
 300 three such files - <tt>ssl/ssl_sess.c</tt>, <tt>apps/apps.c</tt> and
 301 <tt>test/randtest.c</tt>.
 302 </p>
 303 <p>Hopefully OpenSSL core team would fix this problem soon.
 304 </p>
 305 <h3>Case 2. Duplicate extern</h3>
 306 <p>
 307 I've also found than compilation fails on the file
 308 <tt>engines/ccgost/gost_eng.c</tt> with message &quot;Duplicate
 309 extern&quot;. Solution is very simple. Just remove offending
 310 <tt>__declspec(dllexport)</tt> declartions exactly where compiler
 311 reports error.
 312 </p>
 313 <p>
 314 Since I'm author of ccgost code, I can tell you exact story how this
 315 error crawl into OpenSSL.
 316 </p>
 317 <p>
 318 There is macros IMPLEMENT_DINAMIC_CHECK_FUNCTION and
 319 IMPLEMENT_DYNAMIC_BIND_FUNCTION intended for use by engine writers.
 320 </p>
 321 <p>
 322 Before June 2006 these macros don't have any win32 specific things.
 323 Probably people just didn't use engines on Win32. So, we have to add
 324 export declarations in order to OpenSSL to be able to load our engine on
 325 Win32.
 326 </p>
 327 <p>
 328 Then we forget about it for a while and haven't tested development
 329 version on Win32.
 330 </p>
 331 <p>
 332 Meanwhile core developers have added OPENSSL_EXPORT to definitions of
 333 these macros (this happened on 0.9.8b in stable and nearly at the same
 334 time in development branch). We've fixed it in our engine for stable
 335 version (available at <a
 336 href="http://www.cryptocom.ru/OpenSource/OpenSSL_eng.html">www.cryptocom.ru</a>,
 337 but have forgotte to check development version. Then our engine was
 338 accepted into development distribution, and nobody cares to test it
 339 under Win32 until Oct 20.
 340 </p>
 341 </BODY>
 342 </HTML>