]>
Commit | Line | Data |
---|---|---|
26abc8f0 RL |
1 | |
2 | INSTALLATION ON THE WIN32 PLATFORM | |
3 | ---------------------------------- | |
4 | ||
5 | [Instructions for building for Windows CE can be found in INSTALL.WCE] | |
1875e6db | 6 | [Instructions for building for Win64 can be found in INSTALL.W64] |
26abc8f0 | 7 | |
3189772e AP |
8 | Here are a few comments about building OpenSSL for Win32 environments, |
9 | such as Windows NT and Windows 9x. It should be noted though that | |
10 | Windows 9x are not ordinarily tested. Its mention merely means that we | |
11 | attempt to maintain certain programming discipline and pay attention | |
12 | to backward compatibility issues, in other words it's kind of expected | |
13 | to work on Windows 9x, but no regression tests are actually performed. | |
26abc8f0 | 14 | |
3189772e AP |
15 | On additional note newer OpenSSL versions are compiled and linked with |
16 | Winsock 2. This means that minimum OS requirement was elevated to NT 4 | |
17 | and Windows 98 [there is Winsock 2 update for Windows 95 though]. | |
26abc8f0 | 18 | |
3189772e AP |
19 | - you need Perl for Win32. Unless you will build on Cygwin, you will need |
20 | ActiveState Perl, available from http://www.activestate.com/ActivePerl. | |
21 | ||
22 | - one of the following C compilers: | |
26abc8f0 RL |
23 | |
24 | * Visual C++ | |
25 | * Borland C | |
26 | * GNU C (Cygwin or MinGW) | |
27 | ||
39c63e16 AP |
28 | - Netwide Assembler, a.k.a. NASM, available from http://nasm.sourceforge.net/ |
29 | is required if you intend to utilize assembler modules. Note that NASM | |
d7f0d147 | 30 | is now the only supported assembler. |
3189772e | 31 | |
5584a954 | 32 | If you are compiling from a tarball or a Git snapshot then the Win32 files |
26abc8f0 RL |
33 | may well be not up to date. This may mean that some "tweaking" is required to |
34 | get it all to work. See the trouble shooting section later on for if (when?) | |
35 | it goes wrong. | |
36 | ||
d333ebaf RL |
37 | CAVEAT LECTOR |
38 | ------------- | |
39 | ||
40 | ### Default install and config paths | |
41 | ||
42 | ./Configure defaults to '/usr/local/ssl' as installation top. This is | |
43 | suitable for Unix, but not for Windows, where this usually is a world | |
44 | writable directory and therefore accessible for change by untrusted users. | |
45 | It is therefore recommended to set your own --prefix or --openssldir to | |
46 | some location that is not world writeable (see the example above) | |
47 | ||
26abc8f0 RL |
48 | Visual C++ |
49 | ---------- | |
50 | ||
3189772e AP |
51 | If you want to compile in the assembly language routines with Visual |
52 | C++, then you will need already mentioned Netwide Assembler binary, | |
39c63e16 | 53 | nasmw.exe or nasm.exe, to be available on your %PATH%. |
26abc8f0 | 54 | |
b839d734 | 55 | Firstly you should run Configure with platform VC-WIN32: |
26abc8f0 | 56 | |
d7f0d147 | 57 | > perl Configure VC-WIN32 --prefix=c:\some\openssl\dir |
df8dae1d | 58 | |
3189772e | 59 | Where the prefix argument specifies where OpenSSL will be installed to. |
26abc8f0 | 60 | |
3189772e AP |
61 | Next you need to build the Makefiles and optionally the assembly |
62 | language files: | |
26abc8f0 | 63 | |
26abc8f0 RL |
64 | - If you are using NASM then run: |
65 | ||
66 | > ms\do_nasm | |
67 | ||
68 | - If you don't want to use the assembly language files at all then run: | |
69 | ||
d7f0d147 | 70 | > perl Configure VC-WIN32 no-asm --prefix=c:/some/openssl/dir |
26abc8f0 RL |
71 | > ms\do_ms |
72 | ||
73 | If you get errors about things not having numbers assigned then check the | |
74 | troubleshooting section: you probably won't be able to compile it as it | |
75 | stands. | |
76 | ||
77 | Then from the VC++ environment at a prompt do: | |
78 | ||
79 | > nmake -f ms\ntdll.mak | |
80 | ||
3189772e AP |
81 | If all is well it should compile and you will have some DLLs and |
82 | executables in out32dll. If you want to try the tests then do: | |
26abc8f0 | 83 | |
df8dae1d DSH |
84 | > nmake -f ms\ntdll.mak test |
85 | ||
86 | ||
3189772e | 87 | To install OpenSSL to the specified location do: |
df8dae1d | 88 | |
3189772e | 89 | > nmake -f ms\ntdll.mak install |
26abc8f0 RL |
90 | |
91 | Tweaks: | |
92 | ||
3189772e AP |
93 | There are various changes you can make to the Win32 compile |
94 | environment. By default the library is not compiled with debugging | |
4563c1e0 DSH |
95 | symbols. If you use the platform debug-VC-WIN32 instead of VC-WIN32 |
96 | then debugging symbols will be compiled in. | |
26abc8f0 | 97 | |
4563c1e0 DSH |
98 | By default in 1.0.0 OpenSSL will compile builtin ENGINES into the |
99 | separate shared librariesy. If you specify the "enable-static-engine" | |
3189772e | 100 | option on the command line to Configure the shared library build |
4563c1e0 | 101 | (ms\ntdll.mak) will compile the engines into libeay32.dll instead. |
df8dae1d | 102 | |
26abc8f0 RL |
103 | The default Win32 environment is to leave out any Windows NT specific |
104 | features. | |
105 | ||
3189772e AP |
106 | If you want to enable the NT specific features of OpenSSL (currently |
107 | only the logging BIO) follow the instructions above but call the batch | |
108 | file do_nt.bat instead of do_ms.bat. | |
26abc8f0 RL |
109 | |
110 | You can also build a static version of the library using the Makefile | |
111 | ms\nt.mak | |
112 | ||
df8dae1d | 113 | |
26abc8f0 RL |
114 | Borland C++ builder 5 |
115 | --------------------- | |
116 | ||
117 | * Configure for building with Borland Builder: | |
d333ebaf | 118 | > perl Configure BC-32 --prefix=c:\some\openssl\dir |
26abc8f0 RL |
119 | |
120 | * Create the appropriate makefile | |
121 | > ms\do_nasm | |
122 | ||
123 | * Build | |
124 | > make -f ms\bcb.mak | |
125 | ||
126 | Borland C++ builder 3 and 4 | |
127 | --------------------------- | |
128 | ||
129 | * Setup PATH. First must be GNU make then bcb4/bin | |
130 | ||
131 | * Run ms\bcb4.bat | |
132 | ||
133 | * Run make: | |
134 | > make -f bcb.mak | |
135 | ||
136 | GNU C (Cygwin) | |
137 | -------------- | |
138 | ||
3189772e AP |
139 | Cygwin implements a Posix/Unix runtime system (cygwin1.dll) on top of |
140 | Win32 subsystem and provides a bash shell and GNU tools environment. | |
141 | Consequently, a make of OpenSSL with Cygwin is virtually identical to | |
142 | Unix procedure. It is also possible to create Win32 binaries that only | |
143 | use the Microsoft C runtime system (msvcrt.dll or crtdll.dll) using | |
144 | MinGW. MinGW can be used in the Cygwin development environment or in a | |
145 | standalone setup as described in the following section. | |
26abc8f0 RL |
146 | |
147 | To build OpenSSL using Cygwin: | |
148 | ||
149 | * Install Cygwin (see http://cygwin.com/) | |
150 | ||
151 | * Install Perl and ensure it is in the path. Both Cygwin perl | |
152 | (5.6.1-2 or newer) and ActivePerl work. | |
153 | ||
154 | * Run the Cygwin bash shell | |
155 | ||
156 | * $ tar zxvf openssl-x.x.x.tar.gz | |
157 | $ cd openssl-x.x.x | |
158 | ||
159 | To build the Cygwin version of OpenSSL: | |
160 | ||
161 | $ ./config | |
162 | [...] | |
163 | $ make | |
164 | [...] | |
165 | $ make test | |
166 | $ make install | |
167 | ||
168 | This will create a default install in /usr/local/ssl. | |
169 | ||
170 | To build the MinGW version (native Windows) in Cygwin: | |
171 | ||
172 | $ ./Configure mingw | |
173 | [...] | |
174 | $ make | |
175 | [...] | |
176 | $ make test | |
177 | $ make install | |
178 | ||
179 | Cygwin Notes: | |
180 | ||
181 | "make test" and normal file operations may fail in directories | |
182 | mounted as text (i.e. mount -t c:\somewhere /home) due to Cygwin | |
183 | stripping of carriage returns. To avoid this ensure that a binary | |
184 | mount is used, e.g. mount -b c:\somewhere /home. | |
185 | ||
186 | "bc" is not provided in older Cygwin distribution. This causes a | |
187 | non-fatal error in "make test" but is otherwise harmless. If | |
188 | desired and needed, GNU bc can be built with Cygwin without change. | |
189 | ||
3189772e | 190 | GNU C (MinGW/MSYS) |
26abc8f0 RL |
191 | ------------- |
192 | ||
3189772e | 193 | * Compiler and shell environment installation: |
26abc8f0 | 194 | |
3189772e AP |
195 | MinGW and MSYS are available from http://www.mingw.org/, both are |
196 | required. Run the installers and do whatever magic they say it takes | |
197 | to start MSYS bash shell with GNU tools on its PATH. | |
26abc8f0 | 198 | |
736d6580 AP |
199 | N.B. Since source tar-ball can contain symbolic links, it's essential |
200 | that you use accompanying MSYS tar to unpack the source. It will | |
201 | either handle them in one way or another or fail to extract them, | |
202 | which does the trick too. Latter means that you may safely ignore all | |
203 | "cannot create symlink" messages, as they will be "re-created" at | |
204 | configure stage by copying corresponding files. Alternative programs | |
205 | were observed to create empty files instead, which results in build | |
206 | failure. | |
207 | ||
26abc8f0 RL |
208 | * Compile OpenSSL: |
209 | ||
d333ebaf | 210 | $ ./config --prefix=c:/some/openssl/dir |
3189772e AP |
211 | [...] |
212 | $ make | |
213 | [...] | |
214 | $ make test | |
215 | ||
216 | This will create the library and binaries in root source directory | |
217 | and openssl.exe application in apps directory. | |
26abc8f0 | 218 | |
3189772e | 219 | It is also possible to cross-compile it on Linux by configuring |
d333ebaf RL |
220 | like this: |
221 | ||
222 | $ ./Configure --cross-compile-prefix=i386-mingw32- \ | |
223 | --prefix=c:/some/openssl/dir mingw ... | |
224 | ||
3189772e | 225 | 'make test' is naturally not applicable then. |
26abc8f0 RL |
226 | |
227 | libcrypto.a and libssl.a are the static libraries. To use the DLLs, | |
228 | link with libeay32.a and libssl32.a instead. | |
229 | ||
3189772e AP |
230 | See troubleshooting if you get error messages about functions not |
231 | having a number assigned. | |
26abc8f0 RL |
232 | |
233 | Installation | |
234 | ------------ | |
235 | ||
236 | If you used the Cygwin procedure above, you have already installed and | |
237 | can skip this section. For all other procedures, there's currently no real | |
238 | installation procedure for Win32. There are, however, some suggestions: | |
239 | ||
240 | - do nothing. The include files are found in the inc32/ subdirectory, | |
241 | all binaries are found in out32dll/ or out32/ depending if you built | |
242 | dynamic or static libraries. | |
243 | ||
244 | - do as is written in INSTALL.Win32 that comes with modssl: | |
245 | ||
246 | $ md c:\openssl | |
247 | $ md c:\openssl\bin | |
248 | $ md c:\openssl\lib | |
249 | $ md c:\openssl\include | |
250 | $ md c:\openssl\include\openssl | |
0ad2c4f8 | 251 | $ copy /b inc32\openssl\* c:\openssl\include\openssl |
26abc8f0 RL |
252 | $ copy /b out32dll\ssleay32.lib c:\openssl\lib |
253 | $ copy /b out32dll\libeay32.lib c:\openssl\lib | |
254 | $ copy /b out32dll\ssleay32.dll c:\openssl\bin | |
255 | $ copy /b out32dll\libeay32.dll c:\openssl\bin | |
256 | $ copy /b out32dll\openssl.exe c:\openssl\bin | |
257 | ||
d333ebaf RL |
258 | ("c:\openssl" should be whatever you specified to --prefix when |
259 | configuring the build) | |
260 | ||
26abc8f0 RL |
261 | Of course, you can choose another device than c:. C: is used here |
262 | because that's usually the first (and often only) harddisk device. | |
263 | Note: in the modssl INSTALL.Win32, p: is used rather than c:. | |
264 | ||
265 | ||
266 | Troubleshooting | |
267 | --------------- | |
268 | ||
269 | Since the Win32 build is only occasionally tested it may not always compile | |
270 | cleanly. If you get an error about functions not having numbers assigned | |
271 | when you run ms\do_ms then this means the Win32 ordinal files are not up to | |
272 | date. You can do: | |
273 | ||
274 | > perl util\mkdef.pl crypto ssl update | |
275 | ||
276 | then ms\do_XXX should not give a warning any more. However the numbers that | |
277 | get assigned by this technique may not match those that eventually get | |
5584a954 | 278 | assigned in the Git tree: so anything linked against this version of the |
26abc8f0 RL |
279 | library may need to be recompiled. |
280 | ||
281 | If you get errors about unresolved symbols there are several possible | |
282 | causes. | |
283 | ||
284 | If this happens when the DLL is being linked and you have disabled some | |
285 | ciphers then it is possible the DEF file generator hasn't removed all | |
286 | the disabled symbols: the easiest solution is to edit the DEF files manually | |
287 | to delete them. The DEF files are ms\libeay32.def ms\ssleay32.def. | |
288 | ||
289 | Another cause is if you missed or ignored the errors about missing numbers | |
290 | mentioned above. | |
291 | ||
292 | If you get warnings in the code then the compilation will halt. | |
293 | ||
294 | The default Makefile for Win32 halts whenever any warnings occur. Since VC++ | |
295 | has its own ideas about warnings which don't always match up to other | |
296 | environments this can happen. The best fix is to edit the file with the | |
297 | warning in and fix it. Alternatively you can turn off the halt on warnings by | |
298 | editing the CFLAG line in the Makefile and deleting the /WX option. | |
299 | ||
300 | You might get compilation errors. Again you will have to fix these or report | |
301 | them. | |
302 | ||
303 | One final comment about compiling applications linked to the OpenSSL library. | |
304 | If you don't use the multithreaded DLL runtime library (/MD option) your | |
305 | program will almost certainly crash because malloc gets confused -- the | |
306 | OpenSSL DLLs are statically linked to one version, the application must | |
307 | not use a different one. You might be able to work around such problems | |
308 | by adding CRYPTO_malloc_init() to your program before any calls to the | |
309 | OpenSSL libraries: This tells the OpenSSL libraries to use the same | |
310 | malloc(), free() and realloc() as the application. However there are many | |
311 | standard library functions used by OpenSSL that call malloc() internally | |
312 | (e.g. fopen()), and OpenSSL cannot change these; so in general you cannot | |
313 | rely on CRYPTO_malloc_init() solving your problem, and you should | |
314 | consistently use the multithreaded library. | |
b3836ed3 AP |
315 | |
316 | Linking your application | |
317 | ------------------------ | |
318 | ||
319 | If you link with static OpenSSL libraries [those built with ms/nt.mak], | |
320 | then you're expected to additionally link your application with | |
05fc0bae RL |
321 | WS2_32.LIB, GDI32.LIB, ADVAPI32.LIB, CRYPT32.LIB and USER32.LIB. Those |
322 | developing non-interactive service applications might feel concerned about | |
323 | linking with GDI32.LIB and USER32.LIB, as they are justly associated with | |
324 | interactive desktop, which is not available to service processes. The toolkit | |
325 | is designed to detect in which context it's currently executed, GUI, console | |
326 | app or service, and act accordingly, namely whether or not to actually make | |
327 | GUI calls. Additionally those who wish to /DELAYLOAD:GDI32.DLL and | |
328 | /DELAYLOAD:USER32.DLL and actually keep them off service process should | |
329 | consider implementing and exporting from .exe image in question own | |
330 | _OPENSSL_isservice not relying on USER32.DLL. E.g., on Windows Vista and | |
331 | later you could: | |
30dd0681 AP |
332 | |
333 | __declspec(dllexport) __cdecl BOOL _OPENSSL_isservice(void) | |
334 | { DWORD sess; | |
335 | if (ProcessIdToSessionId(GetCurrentProcessId(),&sess)) | |
336 | return sess==0; | |
337 | return FALSE; | |
338 | } | |
b3836ed3 AP |
339 | |
340 | If you link with OpenSSL .DLLs, then you're expected to include into | |
341 | your application code small "shim" snippet, which provides glue between | |
342 | OpenSSL BIO layer and your compiler run-time. Look up OPENSSL_Applink | |
343 | reference page for further details. |