]>
Commit | Line | Data |
---|---|---|
79e259e3 | 1 | |
6ede7d73 DMSP |
2 | Build and Install |
3 | ================= | |
4 | ||
5 | This document describes installation on all supported operating | |
6 | systems (the Unix/Linux family, including macOS), OpenVMS, | |
7 | and Windows). | |
8 | ||
9 | Table of Contents | |
10 | ================= | |
11 | ||
12 | - [Prerequisites](#prerequisites) | |
13 | - [Notational Conventions](#notational-conventions) | |
14 | - [Quick Installation Guide](#quick-installation-guide) | |
15 | - [Building OpenSSL](#building-openssl) | |
16 | - [Installing OpenSSL](#installing-openssl) | |
17 | - [Configuration Options](#configuration-options) | |
18 | - [API Level](#api-level) | |
19 | - [Cross Compile Prefix](#cross-compile-prefix) | |
20 | - [Build Type](#build-type) | |
21 | - [Directories](#directories) | |
22 | - [Compiler Warnings](#compiler-warnings) | |
23 | - [ZLib Flags](#zlib-flags) | |
24 | - [Seeding the Random Generator](#seeding-the-random-generator) | |
25 | - [Enable and Disable Features](#enable-and-disable-features) | |
26 | - [Displaying configuration data](#displaying-configuration-data) | |
27 | - [Installation Steps in Detail](#installation-steps-in-detail) | |
28 | - [Configure](#configure-openssl) | |
29 | - [Build](#build-openssl) | |
30 | - [Test](#test-openssl) | |
31 | - [Install](#install-openssl) | |
32 | - [Advanced Build Options](#advanced-build-options) | |
33 | - [Environment Variables](#environment-variables) | |
34 | - [Makefile Targets](#makefile-targets) | |
35 | - [Running Selected Tests](#running-selected-tests) | |
36 | - [Troubleshooting](#troubleshooting) | |
37 | - [Configuration Problems](#configuration-problems) | |
38 | - [Build Failures](#build-failures) | |
39 | - [Test Failures](#test-failures) | |
40 | - [Notes](#notes) | |
41 | - [Notes on multi-threading](#notes-on-multi-threading) | |
42 | - [Notes on shared libraries](#notes-on-shared-libraries) | |
43 | - [Notes on random number generation](#notes-on-random-number-generation) | |
4109b97c | 44 | |
79e259e3 | 45 | |
6ede7d73 DMSP |
46 | Prerequisites |
47 | ============= | |
2acd8ec7 | 48 | |
6ede7d73 | 49 | To install OpenSSL, you will need: |
2acd8ec7 | 50 | |
6ede7d73 DMSP |
51 | * A make implementation |
52 | * Perl 5 with core modules (please read [NOTES.PERL](NOTES.PERL)) | |
53 | * The Perl module Text::Template (please read [NOTES.PERL](NOTES.PERL)) | |
54 | * an ANSI C compiler | |
55 | * a development environment in the form of development libraries and C | |
56 | header files | |
57 | * a supported operating system | |
79e259e3 | 58 | |
6ede7d73 DMSP |
59 | For additional platform specific requirements, solutions to specific |
60 | issues and other details, please read one of these: | |
ea24fe29 | 61 | |
6ede7d73 DMSP |
62 | * [NOTES.UNIX](NOTES.UNIX) - notes for Unix like systems |
63 | * [NOTES.VMS](NOTES.VMS) - notes related to OpenVMS | |
64 | * [NOTES.WIN](NOTES.WIN) - notes related to the Windows platform | |
65 | * [NOTES.DJGPP](NOTES.DJGPP) - building for DOS with DJGPP | |
66 | * [NOTES.ANDROID](NOTES.ANDROID) - building for Android platforms (using NDK) | |
67 | * [NOTES.VALGRIND](NOTES.VALGRIND) - testing with Valgrind | |
68 | * [NOTES.PERL](NOTES.PERL) - some notes on Perl | |
ea24fe29 | 69 | |
ea24fe29 | 70 | |
6ede7d73 DMSP |
71 | Notational conventions |
72 | ====================== | |
ea24fe29 | 73 | |
6ede7d73 | 74 | Throughout this document, we use the following conventions. |
ea24fe29 | 75 | |
6ede7d73 DMSP |
76 | Commands |
77 | -------- | |
ea24fe29 | 78 | |
6ede7d73 | 79 | Any line starting with a dollar sign is a command line. |
ea24fe29 | 80 | |
6ede7d73 | 81 | $ command |
ea24fe29 | 82 | |
6ede7d73 DMSP |
83 | The dollar sign indicates the shell prompt and is not to be entered as |
84 | part of the command. | |
ea24fe29 | 85 | |
6ede7d73 DMSP |
86 | Choices |
87 | ------- | |
ea24fe29 | 88 | |
6ede7d73 DMSP |
89 | Several words in curly braces separated by pipe characters indicate a |
90 | **mandatory choice**, to be replaced with one of the given words. | |
91 | For example, the line | |
ea24fe29 | 92 | |
6ede7d73 | 93 | $ echo { WORD1 | WORD2 | WORD3 } |
ea24fe29 | 94 | |
6ede7d73 | 95 | represents one of the following three commands |
ea24fe29 | 96 | |
6ede7d73 DMSP |
97 | $ echo WORD1 |
98 | - or - | |
99 | $ echo WORD2 | |
100 | - or - | |
101 | $ echo WORD3 | |
ea24fe29 | 102 | |
6ede7d73 DMSP |
103 | One or several words in square brackets separated by pipe characters |
104 | denote an **optional choice**. It is similar to the mandatory choice, | |
105 | but it can also be omitted entirely. | |
79e259e3 | 106 | |
6ede7d73 | 107 | So the line |
79e259e3 | 108 | |
6ede7d73 DMSP |
109 | $ echo [ WORD1 | WORD2 | WORD3 ] |
110 | ||
111 | represents one of the four commands | |
112 | ||
113 | $ echo WORD1 | |
114 | - or - | |
115 | $ echo WORD2 | |
116 | - or - | |
117 | $ echo WORD3 | |
118 | - or - | |
119 | $ echo | |
120 | ||
121 | Arguments | |
122 | --------- | |
123 | ||
124 | **Mandatory arguments** are enclosed in double curly braces. | |
125 | A simple example would be | |
126 | ||
127 | $ type {{ filename }} | |
128 | ||
129 | which is to be understood to use the command `type` on some file name | |
130 | determined by the user. | |
131 | ||
132 | ||
133 | **Optional Arguments** are enclosed in double square brackets. | |
134 | ||
135 | [[ options ]] | |
136 | ||
137 | Note that the notation assumes spaces around {, }, [, ], {{, }} and | |
138 | [[, ]]. This is to differentiate from OpenVMS directory | |
139 | specifications, which also use [ and ], but without spaces. | |
140 | ||
141 | ||
142 | Quick Installation Guide | |
143 | ======================== | |
144 | ||
145 | If you just want to get OpenSSL installed without bothering too much | |
146 | about the details, here is the short version of how to build and install | |
147 | OpenSSL. If any of the following steps fails, please consult the | |
148 | [Installation in Detail](#installation-in-detail) section below. | |
149 | ||
150 | Building OpenSSL | |
151 | ---------------- | |
152 | ||
153 | Use the following commands to configure, build and test OpenSSL. | |
154 | The testing is optional, but recommended if you intend to install | |
155 | OpenSSL for production use. | |
156 | ||
157 | ### Unix / Linux / macOS ### | |
2acd8ec7 RL |
158 | |
159 | $ ./config | |
160 | $ make | |
161 | $ make test | |
2acd8ec7 | 162 | |
6ede7d73 DMSP |
163 | ### OpenVMS ### |
164 | ||
165 | Use the following commands to build OpenSSL: | |
2acd8ec7 RL |
166 | |
167 | $ @config | |
168 | $ mms | |
169 | $ mms test | |
79e259e3 | 170 | |
6ede7d73 DMSP |
171 | ### Windows ### |
172 | ||
173 | If you are using Visual Studio, open a Developer Command Prompt and | |
174 | and issue the following commands to build OpenSSL. | |
b32b8961 RL |
175 | |
176 | $ perl Configure { VC-WIN32 | VC-WIN64A | VC-WIN64I | VC-CE } | |
177 | $ nmake | |
178 | $ nmake test | |
6ede7d73 DMSP |
179 | |
180 | As mentioned in the [Choices](#choices) section, you need to pick one | |
181 | of the four Configure targets in the first command. | |
182 | ||
183 | Most likely you will be using the VC-WIN64A target for 64bit Windows | |
184 | binaries (AMD64) or VC-WIN32 for 32bit Windows binaries (X86). | |
185 | The other two options are VC_WIN64I (Intel IA64, Itanium) and | |
186 | VC-CE (Windows CE) are rather uncommon nowadays. | |
187 | ||
188 | Installing OpenSSL | |
189 | ------------------ | |
190 | ||
191 | The following commands will install OpenSSL to a default system location. | |
192 | ||
193 | **Danger Zone:** even if you are impatient, please read the following two | |
194 | paragraphs carefully before you install OpenSSL. | |
195 | ||
196 | For security reasons the default system location is by default not writable | |
197 | for unprivileged users. So for the final installation step administrative | |
198 | privileges are required. The default system location and the procedure to | |
199 | obtain administrative privileges depends on the operating sytem. | |
200 | It is recommended to compile and test OpenSSL with normal user privileges | |
201 | and use administrative privileges only for the final installation step. | |
202 | ||
203 | On some platforms OpenSSL is preinstalled as part of the Operating System. | |
204 | In this case it is highly recommended not to overwrite the system versions, | |
205 | because other applications or libraries might depend on it. | |
206 | To avoid breaking other applications, install your copy of OpenSSL to a | |
207 | [different location](#installing-to-a-different-location) which is not in | |
208 | the global search path for system libraries. | |
209 | ||
41149648 RL |
210 | Finally, if you plan on using the FIPS module, you need to read the |
211 | [Post-installation Notes](#post-installation-notes) further down. | |
212 | ||
6ede7d73 DMSP |
213 | ### Unix / Linux / macOS ### |
214 | ||
215 | Depending on your distribution, you need to run the following command as | |
216 | root user or prepend `sudo` to the command: | |
217 | ||
218 | $ make install | |
219 | ||
220 | By default, OpenSSL will be installed to | |
221 | ||
222 | /usr/local | |
223 | ||
224 | More precisely, the files will be installed into the subdirectories | |
225 | ||
226 | /usr/local/bin | |
227 | /usr/local/lib | |
228 | /usr/local/include | |
229 | ... | |
230 | ||
231 | depending on the file type, as it is custom on Unix-like operating systems. | |
232 | ||
233 | ### OpenVMS ### | |
234 | ||
235 | Use the following command to install OpenSSL. | |
236 | ||
237 | $ mms install | |
238 | ||
239 | By default, OpenSSL will be installed to | |
240 | ||
241 | SYS$COMMON:[OPENSSL-'version'...] | |
242 | ||
243 | where 'version' is the OpenSSL version number with underscores instead | |
244 | of periods. | |
245 | ||
246 | ### Windows ### | |
247 | ||
248 | If you are using Visual Studio, open the Developer Command Prompt _elevated_ | |
249 | and issue the following command. | |
250 | ||
8c16829e | 251 | $ nmake install |
b32b8961 | 252 | |
6ede7d73 DMSP |
253 | The easiest way to elevate the Command Prompt is to press and hold down |
254 | the both the `<CTRL>` and `<SHIFT>` key while clicking the menu item in the | |
255 | task menu. | |
256 | ||
257 | The default installation location is | |
258 | ||
259 | C:\Program Files\OpenSSL | |
7c03bb9f | 260 | |
6ede7d73 | 261 | for native binaries, or |
b1fe6b43 | 262 | |
6ede7d73 | 263 | C:\Program Files (x86)\OpenSSL |
2acd8ec7 | 264 | |
6ede7d73 | 265 | for 32bit binaries on 64bit Windows (WOW64). |
2acd8ec7 | 266 | |
7c03bb9f | 267 | |
6ede7d73 | 268 | #### Installing to a different location #### |
79e259e3 | 269 | |
6ede7d73 DMSP |
270 | To install OpenSSL to a different location (for example into your home |
271 | directory for testing purposes) run config like this: | |
272 | ||
273 | **On Unix** | |
2acd8ec7 RL |
274 | |
275 | $ ./config --prefix=/opt/openssl --openssldir=/usr/local/ssl | |
276 | ||
6ede7d73 | 277 | **On OpenVMS** |
2acd8ec7 RL |
278 | |
279 | $ @config --prefix=PROGRAM:[INSTALLS] --openssldir=SYS$MANAGER:[OPENSSL] | |
79e259e3 | 280 | |
6ede7d73 DMSP |
281 | Note: if you do add options to the configuration command, please make sure |
282 | you've read more than just this Quick Start, such as relevant NOTES.* files, | |
283 | the options outline below, as configuration options may change the outcome | |
284 | in otherwise unexpected ways. | |
285 | ||
286 | ||
287 | Configuration Options | |
288 | ===================== | |
289 | ||
290 | There are several options to ./config (or ./Configure) to customize | |
291 | the build (note that for Windows, the defaults for `--prefix` and | |
292 | `--openssldir` depend in what configuration is used and what Windows | |
293 | implementation OpenSSL is built on. More notes on this in NOTES.WIN): | |
294 | ||
295 | API Level | |
296 | --------- | |
297 | ||
298 | --api=x.y[.z] | |
299 | ||
300 | Build the OpenSSL libraries to support the API for the specified version. | |
301 | If [no-deprecated](#no-deprecated) is also given, don't build with support | |
302 | for deprecated APIs in or below the specified version number. For example, | |
303 | addding | |
304 | ||
305 | --api=1.1.0 no-deprecated | |
306 | ||
307 | will remove support for all APIs that were deprecated in OpenSSL version | |
308 | 1.1.0 or below. This is a rather specialized option for developers. | |
309 | If you just intend to remove all deprecated APIs up to the current version | |
310 | entirely, just specify [no-deprecated](#no-deprecated). | |
311 | If `--api` isn't given, it defaults to the current (minor) OpenSSL version. | |
312 | ||
313 | ||
314 | Cross Compile Prefix | |
315 | -------------------- | |
316 | ||
317 | --cross-compile-prefix=PREFIX | |
318 | ||
319 | The PREFIX to include in front of commands for your toolchain. | |
320 | ||
321 | It is likely to have to end with dash, e.g. a-b-c- would invoke GNU compiler as | |
322 | a-b-c-gcc, etc. Unfortunately cross-compiling is too case-specific to put | |
323 | together one-size-fits-all instructions. You might have to pass more flags or | |
324 | set up environment variables to actually make it work. Android and iOS cases are | |
325 | discussed in corresponding `Configurations/15-*.conf` files. But there are cases | |
326 | when this option alone is sufficient. For example to build the mingw64 target on | |
327 | Linux `--cross-compile-prefix=x86_64-w64-mingw32-` works. Naturally provided | |
328 | that mingw packages are installed. Today Debian and Ubuntu users have option to | |
329 | install a number of prepackaged cross-compilers along with corresponding | |
330 | run-time and development packages for "alien" hardware. To give another example | |
331 | `--cross-compile-prefix=mipsel-linux-gnu-` suffices in such case. Needless to | |
332 | mention that you have to invoke `./Configure`, not `./config`, and pass your target | |
333 | name explicitly. Also, note that `--openssldir` refers to target's file system, | |
334 | not one you are building on. | |
335 | ||
336 | ||
337 | Build Type | |
338 | ---------- | |
339 | ||
340 | --debug | |
341 | ||
342 | Build OpenSSL with debugging symbols and zero optimization level. | |
343 | ||
344 | --release | |
345 | ||
346 | Build OpenSSL without debugging symbols. This is the default. | |
347 | ||
348 | ||
349 | Directories | |
350 | ----------- | |
351 | ||
352 | ### libdir ### | |
353 | ||
354 | --libdir=DIR | |
355 | ||
356 | The name of the directory under the top of the installation directory tree | |
357 | (see the `--prefix` option) where libraries will be installed. By default | |
358 | this is "lib". Note that on Windows only static libraries (`*.lib`) will | |
359 | be stored in this location. Shared libraries (`*.dll`) will always be | |
360 | installed to the "bin" directory. | |
361 | ||
362 | ### openssldir ### | |
363 | ||
364 | --openssldir=DIR | |
365 | ||
366 | Directory for OpenSSL configuration files, and also the default certificate | |
367 | and key store. Defaults are: | |
368 | ||
369 | Unix: /usr/local/ssl | |
370 | Windows: C:\Program Files\Common Files\SSL | |
371 | OpenVMS: SYS$COMMON:[OPENSSL-COMMON] | |
372 | ||
373 | For 32bit Windows applications on Windows 64bit (WOW64), always replace | |
374 | `C:\Program Files` by `C:\Program Files (x86)`. | |
375 | ||
376 | ### prefix ### | |
377 | ||
378 | --prefix=DIR | |
379 | ||
380 | The top of the installation directory tree. Defaults are: | |
381 | ||
382 | Unix: /usr/local | |
383 | Windows: C:\Program Files\OpenSSL | |
384 | OpenVMS: SYS$COMMON:[OPENSSL-'version'] | |
385 | ||
386 | ||
387 | Compiler Warnings | |
388 | ----------------- | |
389 | ||
390 | --strict-warnings | |
391 | ||
392 | This is a developer flag that switches on various compiler options recommended | |
393 | for OpenSSL development. It only works when using gcc or clang as the compiler. | |
394 | If you are developing a patch for OpenSSL then it is recommended that you use | |
395 | this option where possible. | |
396 | ||
397 | ZLib Flags | |
398 | ---------- | |
399 | ||
400 | ### with-zlib-include ### | |
401 | ||
402 | --with-zlib-include=DIR | |
403 | ||
404 | The directory for the location of the zlib include file. This option is only | |
405 | necessary if [enable-zlib](#enable-zlib) is used and the include file is not | |
406 | already on the system include path. | |
407 | ||
408 | ### with-zlib-lib ### | |
409 | ||
410 | --with-zlib-lib=LIB | |
411 | ||
412 | **On Unix**: this is the directory containing the zlib library. | |
413 | If not provided the system library path will be used. | |
414 | ||
415 | **On Windows:** this is the filename of the zlib library (with or | |
416 | without a path). This flag must be provided if the | |
417 | [zlib-dynamic](#zlib-dynamic) option is not also used. If zlib-dynamic is used | |
418 | then this flag is optional and defaults to "ZLIB1" if not provided. | |
419 | ||
420 | **On VMS:** this is the filename of the zlib library (with or without a path). | |
421 | This flag is optional and if not provided then "GNV$LIBZSHR", "GNV$LIBZSHR32" | |
422 | or "GNV$LIBZSHR64" is used by default depending on the pointer size chosen. | |
423 | ||
424 | ||
425 | Seeding the Random Generator | |
426 | ---------------------------- | |
427 | ||
428 | --with-rand-seed=seed1[,seed2,...] | |
429 | ||
430 | A comma separated list of seeding methods which will be tried by OpenSSL | |
431 | in order to obtain random input (a.k.a "entropy") for seeding its | |
432 | cryptographically secure random number generator (CSPRNG). | |
433 | The current seeding methods are: | |
434 | ||
435 | ### os ### | |
436 | ||
437 | Use a trusted operating system entropy source. | |
438 | This is the default method if such an entropy source exists. | |
439 | ||
440 | ### getrandom ### | |
441 | ||
442 | Use the [getrandom(2)][man-getrandom] or equivalent system call. | |
443 | ||
444 | [man-getrandom]: http://man7.org/linux/man-pages/man2/getrandom.2.html | |
445 | ||
446 | ### devrandom ### | |
447 | ||
448 | Use the first device from the DEVRANDOM list which can be opened to read | |
449 | random bytes. The DEVRANDOM preprocessor constant expands to | |
450 | ||
451 | "/dev/urandom","/dev/random","/dev/srandom" | |
452 | ||
453 | on most unix-ish operating systems. | |
454 | ||
455 | ### egd ### | |
456 | ||
457 | Check for an entropy generating daemon. | |
458 | ||
459 | ### rdcpu ### | |
460 | ||
461 | Use the RDSEED or RDRAND command if provided by the CPU. | |
462 | ||
463 | ### librandom ### | |
464 | ||
465 | Use librandom (not implemented yet). | |
466 | ||
467 | ### none ### | |
468 | ||
469 | Disable automatic seeding. This is the default on some operating systems where | |
470 | no suitable entropy source exists, or no support for it is implemented yet. | |
471 | ||
472 | For more information, see the section [Notes on random number generation][rng] | |
473 | at the end of this document. | |
474 | ||
475 | [rng]: #notes-on-random-number-generation | |
476 | ||
477 | ||
478 | Enable and Disable Features | |
479 | --------------------------- | |
480 | ||
481 | Feature options always come in pairs, an option to enable feature xxxx, and | |
482 | and option to disable it: | |
483 | ||
484 | [ enable-xxxx | no-xxxx ] | |
485 | ||
486 | Whether a feature is enabled or disabled by default, depends on the feature. | |
487 | In the following list, always the non-default variant is documented: if | |
488 | feature xxxx is disabled by default then enable-xxxx is documented and | |
489 | if feature xxxx is enabled by default then no-xxxx is documented. | |
490 | ||
491 | ||
492 | ### no-afalgeng ### | |
493 | ||
494 | Don't build the AFALG engine. | |
495 | ||
496 | This option will be forced on a platform that does not support AFALG. | |
497 | ||
498 | ### enable-ktls ### | |
499 | ||
500 | Build with Kernel TLS support. | |
501 | ||
502 | This option will enable the use of the Kernel TLS data-path, which can improve | |
503 | performance and allow for the use of sendfile and splice system calls on | |
504 | TLS sockets. The Kernel may use TLS accelerators if any are available on the | |
505 | system. This option will be forced off on systems that do not support the | |
506 | Kernel TLS data-path. | |
507 | ||
508 | ### enable-asan ### | |
509 | ||
510 | Build with the Address sanitiser. | |
511 | ||
512 | This is a developer option only. It may not work on all platforms and should | |
513 | never be used in production environments. It will only work when used with | |
514 | gcc or clang and should be used in conjunction with the [no-shared](#no-shared) | |
515 | option. | |
516 | ||
517 | ### no-asm ### | |
518 | ||
519 | Do not use assembler code. | |
520 | ||
521 | This should be viewed as debugging/troubleshooting option rather than for | |
522 | production use. On some platforms a small amount of assembler code may still | |
523 | be used even with this option. | |
524 | ||
525 | ### no-async ### | |
526 | ||
527 | Do not build support for async operations. | |
528 | ||
529 | ### no-autoalginit ### | |
530 | ||
531 | Don't automatically load all supported ciphers and digests. | |
532 | ||
533 | Typically OpenSSL will make available all of its supported ciphers and digests. | |
534 | For a statically linked application this may be undesirable if small executable | |
535 | size is an objective. This only affects libcrypto. Ciphers and digests will | |
536 | have to be loaded manually using EVP_add_cipher() and EVP_add_digest() if this | |
537 | option is used. This option will force a non-shared build. | |
538 | ||
539 | ### no-autoerrinit ### | |
540 | ||
541 | Don't automatically load all libcrypto/libssl error strings. | |
542 | ||
543 | Typically OpenSSL will automatically load human readable error strings. For a | |
544 | statically linked application this may be undesirable if small executable size | |
545 | is an objective. | |
546 | ||
547 | ### no-autoload-config ### | |
548 | ||
549 | Don't automatically load the default openssl.cnf file. | |
550 | ||
551 | Typically OpenSSL will automatically load a system config file which configures | |
552 | default SSL options. | |
553 | ||
554 | ### enable-buildtest-c++ ### | |
555 | ||
556 | While testing, generate C++ buildtest files that simply check that the public | |
557 | OpenSSL header files are usable standalone with C++. | |
558 | ||
559 | Enabling this option demands extra care. For any compiler flag given directly | |
560 | as configuration option, you must ensure that it's valid for both the C and | |
561 | the C++ compiler. If not, the C++ build test will most likely break. As an | |
562 | alternative, you can use the language specific variables, CFLAGS and CXXFLAGS. | |
563 | ||
564 | ### no-capieng ### | |
565 | ||
566 | Don't build the CAPI engine. | |
567 | ||
568 | This option will be forced if on a platform that does not support CAPI. | |
569 | ||
570 | ### no-cmp ### | |
571 | ||
572 | Don't build support for Certificate Management Protocol (CMP). | |
573 | ||
574 | ### no-cms ### | |
575 | ||
576 | Don't build support for Cryptographic Message Syntax (CMS). | |
577 | ||
578 | ### no-comp ### | |
579 | ||
580 | Don't build support for SSL/TLS compression. | |
581 | ||
582 | If this option is enabled (the default), then compression will only work if | |
583 | the zlib or zlib-dynamic options are also chosen. | |
584 | ||
585 | ### enable-crypto-mdebug ### | |
586 | ||
587 | This now only enables the failed-malloc feature. | |
588 | ||
589 | ### enable-crypto-mdebug-backtrace ### | |
590 | ||
591 | This is a no-op; the project uses the compiler's address/leak sanitizer instead. | |
592 | ||
593 | ### no-ct ### | |
594 | ||
595 | Don't build support for Certificate Transparency (CT). | |
596 | ||
597 | ### no-deprecated ### | |
598 | ||
599 | Don't build with support for deprecated APIs up until and including the version | |
600 | given with `--api` (or the current version, if `--api` wasn't specified). | |
601 | ||
602 | ### no-dgram ### | |
603 | ||
604 | Don't build support for datagram based BIOs. | |
605 | ||
606 | Selecting this option will also force the disabling of DTLS. | |
607 | ||
608 | ### no-dso ### | |
609 | ||
610 | Don't build support for loading Dynamic Shared Objects (DSO) | |
611 | ||
612 | ### enable-devcryptoeng ### | |
613 | ||
614 | Build the `/dev/crypto` engine. | |
615 | ||
616 | This option is automatically selected on the BSD platform, in which case it can | |
617 | be disabled with no-devcryptoeng. | |
618 | ||
619 | ### no-dynamic-engine ### | |
620 | ||
621 | Don't build the dynamically loaded engines. | |
622 | ||
623 | This only has an effect in a shared build. | |
624 | ||
625 | ### no-ec ### | |
626 | ||
627 | Don't build support for Elliptic Curves. | |
628 | ||
629 | ### no-ec2m ### | |
630 | ||
631 | Don't build support for binary Elliptic Curves | |
632 | ||
633 | ### enable-ec_nistp_64_gcc_128 ### | |
634 | ||
635 | Enable support for optimised implementations of some commonly used NIST | |
636 | elliptic curves. | |
637 | ||
638 | This option is only supported on platforms: | |
639 | ||
640 | - with little-endian storage of non-byte types | |
641 | - that tolerate misaligned memory references | |
642 | - where the compiler: | |
643 | - supports the non-standard type `__uint128_t` | |
644 | - defines the built-in macro `__SIZEOF_INT128__` | |
645 | ||
646 | ### enable-egd ### | |
647 | ||
648 | Build support for gathering entropy from the Entropy Gathering Daemon (EGD). | |
649 | ||
650 | ### no-engine ### | |
651 | ||
652 | Don't build support for loading engines. | |
653 | ||
654 | ### no-err ### | |
655 | ||
656 | Don't compile in any error strings. | |
657 | ||
658 | ### enable-external-tests ### | |
659 | ||
660 | Enable building of integration with external test suites. | |
661 | ||
662 | This is a developer option and may not work on all platforms. The following | |
663 | external test suites are currently supported: | |
664 | ||
665 | - BoringSSL test suite | |
666 | - Python PYCA/Cryptography test suite | |
667 | - krb5 test suite | |
668 | ||
669 | See the file [test/README.external]/(test/README.external) for further details. | |
670 | ||
671 | ### no-filenames ### | |
672 | ||
673 | Don't compile in filename and line number information (e.g. for errors and | |
674 | memory allocation). | |
675 | ||
676 | ### no-fips ### | |
677 | ||
678 | Don't compile the FIPS provider | |
679 | ||
680 | ### enable-fuzz-libfuzzer, enable-fuzz-afl ### | |
681 | ||
682 | Build with support for fuzzing using either libfuzzer or AFL. | |
683 | ||
684 | These are developer options only. They may not work on all platforms and | |
685 | should never be used in production environments. | |
686 | ||
687 | See the file [fuzz/README.md](fuzz/README.md) for further details. | |
688 | ||
689 | ### no-gost ### | |
690 | ||
691 | Don't build support for GOST based ciphersuites. | |
692 | ||
693 | Note that if this feature is enabled then GOST ciphersuites are only available | |
694 | if the GOST algorithms are also available through loading an externally supplied | |
695 | engine. | |
696 | ||
697 | ### no-legacy ### | |
698 | ||
699 | Don't build the legacy provider. | |
700 | ||
701 | Disabling this also disables the legacy algorithms: MD2 (already disabled by default). | |
702 | ||
703 | ||
704 | ### no-makedepend ### | |
705 | ||
706 | Don't generate dependencies. | |
707 | ||
708 | ### no-module ### | |
79e259e3 | 709 | |
6ede7d73 | 710 | Don't build any dynamically loadable engines. |
917a1b2e | 711 | |
6ede7d73 | 712 | This also implies 'no-dynamic-engine'. |
917a1b2e | 713 | |
6ede7d73 | 714 | ### no-multiblock ### |
917a1b2e | 715 | |
6ede7d73 | 716 | Don't build support for writing multiple records in one go in libssl |
917a1b2e | 717 | |
6ede7d73 | 718 | Note: this is a different capability to the pipelining functionality. |
917a1b2e | 719 | |
6ede7d73 | 720 | ### no-nextprotoneg ### |
917a1b2e | 721 | |
6ede7d73 | 722 | Don't build support for the Next Protocol Negotiation (NPN) TLS extension. |
c9f06e7f | 723 | |
6ede7d73 | 724 | ### no-ocsp ### |
c9f06e7f | 725 | |
6ede7d73 | 726 | Don't build support for Online Certificate Status Protocol (OCSP). |
b32b8961 | 727 | |
2acd8ec7 | 728 | |
6ede7d73 | 729 | ### no-padlockeng ### |
2acd8ec7 | 730 | |
6ede7d73 | 731 | Don't build the padlock engine. |
2acd8ec7 | 732 | |
6ede7d73 | 733 | ### no-hw-padlock ### |
c9f06e7f | 734 | |
6ede7d73 | 735 | As synonyme for no-padlockeng. Deprecated and should not be used. |
c9f06e7f | 736 | |
6ede7d73 | 737 | ### no-pic ### |
b1fe6b43 | 738 | |
6ede7d73 | 739 | Don't build with support for Position Independent Code. |
b1fe6b43 | 740 | |
6ede7d73 | 741 | ### no-pinshared ### |
79e259e3 | 742 | |
6ede7d73 | 743 | Don't pin the shared libraries. |
79e259e3 | 744 | |
6ede7d73 DMSP |
745 | By default OpenSSL will attempt to stay in memory until the process exits. |
746 | This is so that libcrypto and libssl can be properly cleaned up automatically | |
747 | via an atexit() handler. The handler is registered by libcrypto and cleans | |
748 | up both libraries. On some platforms the atexit() handler will run on unload of | |
749 | libcrypto (if it has been dynamically loaded) rather than at process exit. This | |
750 | option can be used to stop OpenSSL from attempting to stay in memory until the | |
751 | process exits. This could lead to crashes if either libcrypto or libssl have | |
752 | already been unloaded at the point that the atexit handler is invoked, e.g. on a | |
753 | platform which calls atexit() on unload of the library, and libssl is unloaded | |
754 | before libcrypto then a crash is likely to happen. Applications can suppress | |
755 | running of the atexit() handler at run time by using the OPENSSL_INIT_NO_ATEXIT | |
756 | option to OPENSSL_init_crypto(). See the man page for it for further details. | |
2acd8ec7 | 757 | |
6ede7d73 | 758 | ### no-posix-io ### |
2acd8ec7 | 759 | |
6ede7d73 | 760 | Don't use POSIX IO capabilities. |
2acd8ec7 | 761 | |
6ede7d73 | 762 | ### no-psk ### |
79e259e3 | 763 | |
6ede7d73 | 764 | Don't build support for Pre-Shared Key based ciphersuites. |
79e259e3 | 765 | |
6ede7d73 | 766 | ### no-rdrand ### |
79e259e3 | 767 | |
6ede7d73 | 768 | Don't use hardware RDRAND capabilities. |
79e259e3 | 769 | |
6ede7d73 | 770 | ### no-rfc3779 ### |
5bb9e2b4 | 771 | |
6ede7d73 DMSP |
772 | Don't build support for RFC3779, "X.509 Extensions for IP Addresses and |
773 | AS Identifiers". | |
79e259e3 | 774 | |
6ede7d73 | 775 | ### sctp ### |
2acd8ec7 | 776 | |
6ede7d73 | 777 | Build support for Stream Control Transmission Protocol (SCTP). |
2acd8ec7 | 778 | |
6ede7d73 | 779 | ### no-shared ### |
2acd8ec7 | 780 | |
6ede7d73 | 781 | Do not create shared libraries, only static ones. |
2acd8ec7 | 782 | |
2acd8ec7 | 783 | |
6ede7d73 | 784 | See [Notes on shared libraries](#notes-on-shared-libraries) below. |
2acd8ec7 | 785 | |
6ede7d73 | 786 | ### no-sock ### |
2acd8ec7 | 787 | |
6ede7d73 | 788 | Don't build support for socket BIOs. |
2acd8ec7 | 789 | |
6ede7d73 | 790 | ### no-srp ### |
2acd8ec7 | 791 | |
6ede7d73 DMSP |
792 | Don't build support for Secure Remote Password (SRP) protocol or |
793 | SRP based ciphersuites. | |
2acd8ec7 | 794 | |
6ede7d73 | 795 | ### no-srtp ### |
b32b8961 | 796 | |
6ede7d73 | 797 | Don't build Secure Real-Time Transport Protocol (SRTP) support. |
b32b8961 | 798 | |
6ede7d73 | 799 | ### no-sse2 ### |
2acd8ec7 | 800 | |
6ede7d73 | 801 | Exclude SSE2 code paths from 32-bit x86 assembly modules. |
79e259e3 | 802 | |
6ede7d73 DMSP |
803 | Normally SSE2 extension is detected at run-time, but the decision whether or not |
804 | the machine code will be executed is taken solely on CPU capability vector. This | |
805 | means that if you happen to run OS kernel which does not support SSE2 extension | |
806 | on Intel P4 processor, then your application might be exposed to "illegal | |
807 | instruction" exception. There might be a way to enable support in kernel, e.g. | |
808 | FreeBSD kernel can be compiled with CPU_ENABLE_SSE, and there is a way to | |
809 | disengage SSE2 code paths upon application start-up, but if you aim for wider | |
810 | "audience" running such kernel, consider no-sse2. Both the 386 and no-asm | |
811 | options imply no-sse2. | |
79e259e3 | 812 | |
6ede7d73 | 813 | ### enable-ssl-trace ### |
79e259e3 | 814 | |
6ede7d73 | 815 | Build with the SSL Trace capabilities. |
1af66bb7 | 816 | |
6ede7d73 | 817 | This adds the "-trace" option to s_client and s_server. |
1af66bb7 | 818 | |
6ede7d73 | 819 | ### no-static-engine ### |
1af66bb7 | 820 | |
6ede7d73 | 821 | Don't build the statically linked engines. |
1af66bb7 | 822 | |
6ede7d73 | 823 | This only has an impact when not built "shared". |
1af66bb7 | 824 | |
6ede7d73 | 825 | ### no-stdio ### |
1af66bb7 | 826 | |
6ede7d73 DMSP |
827 | Don't use anything from the C header file "stdio.h" that makes use of the "FILE" |
828 | type. Only libcrypto and libssl can be built in this way. Using this option will | |
829 | suppress building the command line applications. Additionally, since the OpenSSL | |
830 | tests also use the command line applications, the tests will also be skipped. | |
b1fe6b43 | 831 | |
6ede7d73 | 832 | ### no-tests ### |
79e259e3 | 833 | |
6ede7d73 | 834 | Don't build test programs or run any tests. |
79e259e3 | 835 | |
6ede7d73 | 836 | ### no-threads ### |
6616429d | 837 | |
6ede7d73 | 838 | Don't build with support for multi-threaded applications. |
2e996acf | 839 | |
6ede7d73 | 840 | ### threads ### |
2acd8ec7 | 841 | |
6ede7d73 DMSP |
842 | Build with support for multi-threaded applications. Most platforms will enable |
843 | this by default. However if on a platform where this is not the case then this | |
844 | will usually require additional system-dependent options! | |
2e996acf | 845 | |
6ede7d73 | 846 | See [Notes on multi-threading](#notes-on-multi-threading) below. |
e3d9a6b5 | 847 | |
6ede7d73 | 848 | ### enable-trace ### |
b32b8961 | 849 | |
6ede7d73 | 850 | Build with support for the integrated tracing api. |
2e996acf | 851 | |
6ede7d73 | 852 | See manual pages OSSL_trace_set_channel(3) and OSSL_trace_enabled(3) for details. |
2e996acf | 853 | |
6ede7d73 | 854 | ### no-ts ### |
a73d990e | 855 | |
6ede7d73 | 856 | Don't build Time Stamping (TS) Authority support. |
2e996acf | 857 | |
6ede7d73 | 858 | ### enable-ubsan ### |
2e996acf | 859 | |
6ede7d73 | 860 | Build with the Undefined Behaviour sanitiser (UBSAN). |
2e996acf | 861 | |
6ede7d73 DMSP |
862 | This is a developer option only. It may not work on all platforms and should |
863 | never be used in production environments. It will only work when used with gcc | |
864 | or clang and should be used in conjunction with the `-DPEDANTIC` option | |
865 | (or the `--strict-warnings` option). | |
d40b0622 | 866 | |
301ea192 | 867 | ### no-ui-console ### |
2e996acf | 868 | |
301ea192 | 869 | Don't build with the User Interface (UI) console method |
b1fe6b43 | 870 | |
301ea192 | 871 | The User Interface console method enables text based console prompts. |
b3e718e2 | 872 | |
6ede7d73 | 873 | ### enable-unit-test ### |
79e259e3 | 874 | |
6ede7d73 | 875 | Enable additional unit test APIs. |
2acd8ec7 | 876 | |
6ede7d73 | 877 | This should not typically be used in production deployments. |
7c03bb9f | 878 | |
6ede7d73 | 879 | ### no-uplink ### |
2acd8ec7 | 880 | |
6ede7d73 | 881 | Don't build support for UPLINK interface. |
2acd8ec7 | 882 | |
6ede7d73 | 883 | ### enable-weak-ssl-ciphers ### |
b0940b33 | 884 | |
6ede7d73 | 885 | Build support for SSL/TLS ciphers that are considered "weak" |
fa28bfd6 | 886 | |
6ede7d73 | 887 | Enabling this includes for example the RC4 based ciphersuites. |
fa28bfd6 | 888 | |
6ede7d73 | 889 | ### zlib ### |
fa28bfd6 | 890 | |
6ede7d73 | 891 | Build with support for zlib compression/decompression. |
fa28bfd6 | 892 | |
6ede7d73 | 893 | ### zlib-dynamic ### |
fa28bfd6 | 894 | |
6ede7d73 DMSP |
895 | Like the zlib option, but has OpenSSL load the zlib library dynamically |
896 | when needed. | |
fa28bfd6 | 897 | |
6ede7d73 | 898 | This is only supported on systems where loading of shared libraries is supported. |
fa28bfd6 | 899 | |
6ede7d73 | 900 | ### 386 ### |
fa28bfd6 | 901 | |
6ede7d73 | 902 | In 32-bit x86 builds, use the 80386 instruction set only in assembly modules |
fa28bfd6 | 903 | |
6ede7d73 DMSP |
904 | The default x86 code is more efficient, but requires at least an 486 processor. |
905 | Note: This doesn't affect compiler generated code, so this option needs to be | |
906 | accompanied by a corresponding compiler-specific option. | |
fa28bfd6 | 907 | |
6ede7d73 | 908 | ### no-{protocol} ### |
bf01fbbf | 909 | |
6ede7d73 | 910 | no-{ssl|ssl3|tls|tls1|tls1_1|tls1_2|tls1_3|dtls|dtls1|dtls1_2} |
4fd53220 | 911 | |
6ede7d73 | 912 | Don't build support for negotiating the specified SSL/TLS protocol. |
b3e718e2 | 913 | |
6ede7d73 DMSP |
914 | If "no-tls" is selected then all of tls1, tls1_1, tls1_2 and tls1_3 are disabled. |
915 | Similarly "no-dtls" will disable dtls1 and dtls1_2. The "no-ssl" option is | |
916 | synonymous with "no-ssl3". Note this only affects version negotiation. | |
917 | OpenSSL will still provide the methods for applications to explicitly select | |
918 | the individual protocol versions. | |
b3e718e2 | 919 | |
6ede7d73 | 920 | ### no-{protocol}-method ### |
b3e718e2 | 921 | |
6ede7d73 | 922 | no-{ssl|ssl3|tls|tls1|tls1_1|tls1_2|tls1_3|dtls|dtls1|dtls1_2}-method |
b3e718e2 | 923 | |
6ede7d73 DMSP |
924 | Analogous to no-{protocol} but in addition do not build the methods for |
925 | applications to explicitly select individual protocol versions. Note that there | |
926 | is no "no-tls1_3-method" option because there is no application method for | |
927 | TLSv1.3. | |
b3e718e2 | 928 | |
6ede7d73 DMSP |
929 | Using individual protocol methods directly is deprecated. Applications should |
930 | use TLS_method() instead. | |
b3e718e2 | 931 | |
6ede7d73 | 932 | ### enable-{algorithm} ### |
b3e718e2 | 933 | |
6ede7d73 | 934 | enable-{md2|rc5} |
b3e718e2 | 935 | |
6ede7d73 | 936 | Build with support for the specified algorithm. |
b3e718e2 | 937 | |
6ede7d73 | 938 | ### no-{algorithm} ### |
b3e718e2 | 939 | |
6ede7d73 DMSP |
940 | no-{aria|bf|blake2|camellia|cast|chacha|cmac| |
941 | des|dh|dsa|ecdh|ecdsa|idea|md4|mdc2|ocb| | |
942 | poly1305|rc2|rc4|rmd160|scrypt|seed| | |
943 | siphash|siv|sm2|sm3|sm4|whirlpool} | |
d0631327 | 944 | |
6ede7d73 | 945 | Build without support for the specified algorithm. |
d0631327 | 946 | |
6ede7d73 | 947 | The "ripemd" algorithm is deprecated and if used is synonymous with rmd160. |
d0631327 | 948 | |
6ede7d73 | 949 | ### Compiler-specific options ### |
d0631327 | 950 | |
6ede7d73 | 951 | -Dxxx, -Ixxx, -Wp, -lxxx, -Lxxx, -Wl, -rpath, -R, -framework, -static |
d0631327 | 952 | |
6ede7d73 DMSP |
953 | These system specific options will be recognised and passed through to the |
954 | compiler to allow you to define preprocessor symbols, specify additional | |
955 | libraries, library directories or other compiler options. It might be worth | |
956 | noting that some compilers generate code specifically for processor the | |
957 | compiler currently executes on. This is not necessarily what you might have | |
958 | in mind, since it might be unsuitable for execution on other, typically older, | |
959 | processor. Consult your compiler documentation. | |
960 | ||
961 | Take note of the [Environment Variables](#environment-variables) documentation | |
962 | below and how these flags interact with those variables. | |
963 | ||
964 | -xxx, +xxx, /xxx | |
965 | ||
966 | Additional options that are not otherwise recognised are passed through as | |
967 | they are to the compiler as well. Unix-style options beginning with a | |
968 | '-' or '+' and Windows-style options beginning with a '/' are recognized. | |
969 | Again, consult your compiler documentation. | |
970 | ||
971 | If the option contains arguments separated by spaces, then the URL-style | |
972 | notation %20 can be used for the space character in order to avoid having | |
973 | to quote the option. For example, -opt%20arg gets expanded to -opt arg. | |
974 | In fact, any ASCII character can be encoded as %xx using its hexadecimal | |
975 | encoding. | |
976 | ||
977 | Take note of the [Environment Variables](#environment-variables) documentation | |
978 | below and how these flags interact with those variables. | |
979 | ||
980 | ### Environment Variables ### | |
981 | ||
982 | VAR=value | |
983 | ||
984 | Assign the given value to the environment variable VAR for Configure. | |
985 | ||
986 | These work just like normal environment variable assignments, but are supported | |
987 | on all platforms and are confined to the configuration scripts only. | |
988 | These assignments override the corresponding value in the inherited environment, | |
989 | if there is one. | |
990 | ||
991 | The following variables are used as "make variables" and can be used as an | |
992 | alternative to giving preprocessor, compiler and linker options directly as | |
993 | configuration. The following variables are supported: | |
994 | ||
995 | AR The static library archiver. | |
996 | ARFLAGS Flags for the static library archiver. | |
997 | AS The assembler compiler. | |
998 | ASFLAGS Flags for the assembler compiler. | |
999 | CC The C compiler. | |
1000 | CFLAGS Flags for the C compiler. | |
1001 | CXX The C++ compiler. | |
1002 | CXXFLAGS Flags for the C++ compiler. | |
1003 | CPP The C/C++ preprocessor. | |
1004 | CPPFLAGS Flags for the C/C++ preprocessor. | |
1005 | CPPDEFINES List of CPP macro definitions, separated | |
1006 | by a platform specific character (':' or | |
1007 | space for Unix, ';' for Windows, ',' for | |
1008 | VMS). This can be used instead of using | |
1009 | -D (or what corresponds to that on your | |
1010 | compiler) in CPPFLAGS. | |
1011 | CPPINCLUDES List of CPP inclusion directories, separated | |
1012 | the same way as for CPPDEFINES. This can | |
1013 | be used instead of -I (or what corresponds | |
1014 | to that on your compiler) in CPPFLAGS. | |
1015 | HASHBANGPERL Perl invocation to be inserted after '#!' | |
1016 | in public perl scripts (only relevant on | |
1017 | Unix). | |
1018 | LD The program linker (not used on Unix, $(CC) | |
1019 | is used there). | |
1020 | LDFLAGS Flags for the shared library, DSO and | |
1021 | program linker. | |
1022 | LDLIBS Extra libraries to use when linking. | |
1023 | Takes the form of a space separated list | |
1024 | of library specifications on Unix and | |
1025 | Windows, and as a comma separated list of | |
1026 | libraries on VMS. | |
1027 | RANLIB The library archive indexer. | |
1028 | RC The Windows resource compiler. | |
1029 | RCFLAGS Flags for the Windows resource compiler. | |
1030 | RM The command to remove files and directories. | |
1031 | ||
1032 | These cannot be mixed with compiling/linking flags given on the command line. | |
1033 | In other words, something like this isn't permitted. | |
1034 | ||
1035 | ./config -DFOO CPPFLAGS=-DBAR -DCOOKIE | |
1036 | ||
1037 | Backward compatibility note: | |
1038 | ||
1039 | To be compatible with older configuration scripts, the environment variables | |
1040 | are ignored if compiling/linking flags are given on the command line, except | |
1041 | for the following: | |
1042 | ||
1043 | AR, CC, CXX, CROSS_COMPILE, HASHBANGPERL, PERL, RANLIB, RC, and WINDRES | |
1044 | ||
1045 | For example, the following command will not see -DBAR: | |
1046 | ||
1047 | CPPFLAGS=-DBAR ./config -DCOOKIE | |
1048 | ||
1049 | However, the following will see both set variables: | |
1050 | ||
1051 | CC=gcc CROSS_COMPILE=x86_64-w64-mingw32- ./config -DCOOKIE | |
1052 | ||
1053 | If CC is set, it is advisable to also set CXX to ensure both the C and C++ | |
1054 | compiler are in the same "family". This becomes relevant with | |
1055 | 'enable-external-tests' and 'enable-buildtest-c++'. | |
1056 | ||
1057 | ### Reconfigure ### | |
1058 | ||
1059 | reconf | |
1060 | reconfigure | |
1061 | ||
1062 | Reconfigure from earlier data. | |
1063 | ||
1064 | This fetches the previous command line options and environment from data saved | |
1065 | in "configdata.pm" and runs the configuration process again, using these | |
1066 | options and environment. Note: NO other option is permitted together with | |
1067 | "reconf". This means that you also MUST use "./Configure" (or what corresponds | |
1068 | to that on non-Unix platforms) directly to invoke this option. Note: The | |
1069 | original configuration saves away values for ALL environment variables that were | |
1070 | used, and if they weren't defined, they are still saved away with information | |
1071 | that they weren't originally defined. This information takes precedence over | |
1072 | environment variables that are defined when reconfiguring. | |
1073 | ||
1074 | Displaying configuration data | |
1075 | ----------------------------- | |
1076 | ||
1077 | The configuration script itself will say very little, and finishes by | |
1078 | creating "configdata.pm". This perl module can be loaded by other scripts | |
1079 | to find all the configuration data, and it can also be used as a script to | |
1080 | display all sorts of configuration data in a human readable form. | |
1081 | ||
1082 | For more information, please do: | |
1083 | ||
1084 | $ ./configdata.pm --help # Unix | |
1085 | ||
1086 | or | |
1087 | ||
1088 | $ perl configdata.pm --help # Windows and VMS | |
1089 | ||
1090 | Installation Steps in Detail | |
1091 | ============================ | |
1092 | ||
1093 | Configure OpenSSL | |
1094 | ----------------- | |
1095 | ||
1096 | ### Automatic Configuration ### | |
1097 | ||
1098 | On some platform a `config` script is available which attempts to guess | |
1099 | your operating system (and compiler, if necessary) and calls the `Configure` | |
1100 | Perl script with appropriate target based on its guess. Further options can | |
1101 | be supplied to the `config` script, which will be passed on to the `Configure` | |
1102 | script. | |
1103 | ||
1104 | #### Unix / Linux / macOS #### | |
1105 | ||
1106 | $ ./config [[ options ]] | |
1107 | ||
1108 | #### OpenVMS #### | |
1109 | ||
1110 | $ @config [[ options ]] | |
1111 | ||
1112 | #### Windows #### | |
1113 | ||
1114 | Automatic configuration is not available on Windows. | |
1115 | ||
1116 | For the remainder of this text, the Unix form will be used in all examples, | |
1117 | please use the appropriate form for your platform. | |
1118 | ||
1119 | You can run | |
1120 | ||
1121 | $ ./config -t | |
1122 | ||
1123 | to see whether your target is guessed correctly. If you want to use a different | |
1124 | compiler, you are cross-compiling for another platform, or the ./config guess | |
1125 | was wrong for other reasons, see the [Manual Configuration](#manual-configuration) | |
1126 | section. Oherwise continue with the [Build OpenSSL](#build-openssl) section below. | |
1127 | ||
1128 | On some systems, you can include debugging information as follows: | |
1129 | ||
1130 | $ ./config -d [[ options ]] | |
1131 | ||
1132 | ### Manual Configuration ### | |
1133 | ||
1134 | OpenSSL knows about a range of different operating system, hardware and | |
1135 | compiler combinations. To see the ones it knows about, run | |
1136 | ||
1137 | $ ./Configure # Unix | |
1138 | ||
1139 | or | |
1140 | ||
1141 | $ perl Configure # All other platforms | |
1142 | ||
1143 | For the remainder of this text, the Unix form will be used in all examples. | |
1144 | Please use the appropriate form for your platform. | |
1145 | ||
1146 | Pick a suitable name from the list that matches your system. For most | |
1147 | operating systems there is a choice between using "cc" or "gcc". | |
1148 | When you have identified your system (and if necessary compiler) use this | |
1149 | name as the argument to Configure. For example, a "linux-elf" user would | |
1150 | run: | |
1151 | ||
1152 | $ ./Configure linux-elf [[ options ]] | |
1153 | ||
1154 | ||
1155 | ### Creating your own Configuration ### | |
1156 | ||
1157 | If your system isn't listed, you will have to create a configuration | |
1158 | file named Configurations/{{ something }}.conf and add the correct | |
1159 | configuration for your system. See the available configs as examples | |
1160 | and read Configurations/README and Configurations/README.design for | |
1161 | more information. | |
1162 | ||
1163 | The generic configurations "cc" or "gcc" should usually work on 32 bit | |
1164 | Unix-like systems. | |
1165 | ||
1166 | Configure creates a build file ("Makefile" on Unix, "makefile" on Windows | |
1167 | and "descrip.mms" on OpenVMS) from a suitable template in Configurations, | |
1168 | and defines various macros in include/openssl/configuration.h (generated | |
1169 | from include/openssl/configuration.h.in). | |
1170 | ||
1171 | ### Out of Tree Builds ### | |
1172 | ||
1173 | OpenSSL can be configured to build in a build directory separate from the | |
1174 | source code directory. It's done by placing yourself in some other | |
1175 | directory and invoking the configuration commands from there. | |
1176 | ||
1177 | #### Unix example #### | |
1178 | ||
1179 | $ mkdir /var/tmp/openssl-build | |
1180 | $ cd /var/tmp/openssl-build | |
1181 | $ /PATH/TO/OPENSSL/SOURCE/config [[ options ]] | |
1182 | ||
1183 | or | |
1184 | ||
1185 | $ /PATH/TO/OPENSSL/SOURCE/Configure {{ target }} [[ options ]] | |
1186 | ||
1187 | #### OpenVMS example #### | |
1188 | ||
1189 | $ set default sys$login: | |
1190 | $ create/dir [.tmp.openssl-build] | |
1191 | $ set default [.tmp.openssl-build] | |
1192 | $ @[PATH.TO.OPENSSL.SOURCE]config [[ options ]] | |
1193 | ||
1194 | or | |
1195 | ||
1196 | $ @[PATH.TO.OPENSSL.SOURCE]Configure {{ target }} [[ options ]] | |
1197 | ||
1198 | #### Windows example #### | |
1199 | ||
1200 | $ C: | |
1201 | $ mkdir \temp-openssl | |
1202 | $ cd \temp-openssl | |
1203 | $ perl d:\PATH\TO\OPENSSL\SOURCE\Configure {{ target }} [[ options ]] | |
1204 | ||
1205 | Paths can be relative just as well as absolute. Configure will do its best | |
1206 | to translate them to relative paths whenever possible. | |
1207 | ||
1208 | ||
1209 | Build OpenSSL | |
1210 | ------------- | |
1211 | ||
1212 | Build OpenSSL by running: | |
1213 | ||
1214 | $ make # Unix | |
1215 | $ mms ! (or mmk) OpenVMS | |
1216 | $ nmake # Windows | |
1217 | ||
1218 | This will build the OpenSSL libraries (libcrypto.a and libssl.a on | |
1219 | Unix, corresponding on other platforms) and the OpenSSL binary | |
1220 | ("openssl"). The libraries will be built in the top-level directory, | |
1221 | and the binary will be in the "apps" subdirectory. | |
1222 | ||
1223 | If the build fails, take a look at the [Build Failures](#build-failures) | |
1224 | subsection of the [Troubleshooting](#troubleshooting) section. | |
1225 | ||
1226 | Test OpenSSL | |
1227 | ------------ | |
1228 | ||
1229 | After a successful build, and before installing, the libraries should | |
1230 | be tested. Run: | |
1231 | ||
1232 | $ make test # Unix | |
1233 | $ mms test ! OpenVMS | |
1234 | $ nmake test # Windows | |
1235 | ||
1236 | **Warning:** you MUST run the tests from an unprivileged account (or disable | |
1237 | your privileges temporarily if your platform allows it). | |
1238 | ||
1239 | If some tests fail, take a look at the [Test Failures](#test-failures) | |
1240 | subsection of the [Troubleshooting](#troubleshooting) section. | |
1241 | ||
1242 | ||
1243 | Install OpenSSL | |
1244 | --------------- | |
1245 | ||
1246 | If everything tests ok, install OpenSSL with | |
1247 | ||
1248 | $ make install # Unix | |
1249 | $ mms install ! OpenVMS | |
1250 | $ nmake install # Windows | |
1251 | ||
1252 | Note that in order to perform the install step above you need to have | |
1253 | appropriate permissions to write to the installation directory. | |
1254 | ||
1255 | The above commands will install all the software components in this | |
1256 | directory tree under PREFIX (the directory given with `--prefix` or | |
1257 | its default): | |
1258 | ||
1259 | #### Unix / Linux / macOS #### | |
1260 | ||
1261 | bin/ Contains the openssl binary and a few other | |
1262 | utility scripts. | |
1263 | include/openssl | |
1264 | Contains the header files needed if you want | |
1265 | to build your own programs that use libcrypto | |
1266 | or libssl. | |
1267 | lib Contains the OpenSSL library files. | |
1268 | lib/engines Contains the OpenSSL dynamically loadable engines. | |
1269 | ||
1270 | share/man/man1 Contains the OpenSSL command line man-pages. | |
1271 | share/man/man3 Contains the OpenSSL library calls man-pages. | |
1272 | share/man/man5 Contains the OpenSSL configuration format man-pages. | |
1273 | share/man/man7 Contains the OpenSSL other misc man-pages. | |
1274 | ||
1275 | share/doc/openssl/html/man1 | |
1276 | share/doc/openssl/html/man3 | |
1277 | share/doc/openssl/html/man5 | |
1278 | share/doc/openssl/html/man7 | |
1279 | Contains the HTML rendition of the man-pages. | |
1280 | ||
1281 | #### OpenVMS #### | |
1282 | ||
1283 | 'arch' is replaced with the architecture name, "Alpha" or "ia64", | |
1284 | 'sover' is replaced with the shared library version (0101 for 1.1), and | |
1285 | 'pz' is replaced with the pointer size OpenSSL was built with: | |
1286 | ||
1287 | [.EXE.'arch'] Contains the openssl binary. | |
1288 | [.EXE] Contains a few utility scripts. | |
1289 | [.include.openssl] | |
1290 | Contains the header files needed if you want | |
1291 | to build your own programs that use libcrypto | |
1292 | or libssl. | |
1293 | [.LIB.'arch'] Contains the OpenSSL library files. | |
1294 | [.ENGINES'sover''pz'.'arch'] | |
1295 | Contains the OpenSSL dynamically loadable engines. | |
1296 | [.SYS$STARTUP] Contains startup, login and shutdown scripts. | |
1297 | These define appropriate logical names and | |
1298 | command symbols. | |
1299 | [.SYSTEST] Contains the installation verification procedure. | |
1300 | [.HTML] Contains the HTML rendition of the manual pages. | |
1301 | ||
1302 | ||
1303 | #### Additional Directories #### | |
1304 | ||
1305 | Additionally, install will add the following directories under | |
1306 | OPENSSLDIR (the directory given with `--openssldir` or its default) | |
1307 | for you convenience: | |
1308 | ||
1309 | certs Initially empty, this is the default location | |
1310 | for certificate files. | |
1311 | private Initially empty, this is the default location | |
1312 | for private key files. | |
1313 | misc Various scripts. | |
1314 | ||
1315 | The installation directory should be appropriately protected to ensure | |
1316 | unprivileged users cannot make changes to OpenSSL binaries or files, or | |
1317 | install engines. If you already have a pre-installed version of OpenSSL as | |
1318 | part of your Operating System it is recommended that you do not overwrite | |
1319 | the system version and instead install to somewhere else. | |
1320 | ||
1321 | Package builders who want to configure the library for standard locations, | |
1322 | but have the package installed somewhere else so that it can easily be | |
1323 | packaged, can use | |
1324 | ||
1325 | $ make DESTDIR=/tmp/package-root install # Unix | |
1326 | $ mms/macro="DESTDIR=TMP:[PACKAGE-ROOT]" install ! OpenVMS | |
1327 | ||
1328 | The specified destination directory will be prepended to all installation | |
1329 | target paths. | |
1330 | ||
1331 | ### Compatibility issues with previous OpenSSL versions ### | |
1332 | ||
1333 | #### COMPILING existing applications #### | |
1334 | ||
1335 | Starting with version 1.1.0, OpenSSL hides a number of structures that were | |
1336 | previously open. This includes all internal libssl structures and a number | |
1337 | of EVP types. Accessor functions have been added to allow controlled access | |
1338 | to the structures' data. | |
1339 | ||
1340 | This means that some software needs to be rewritten to adapt to the new ways | |
1341 | of doing things. This often amounts to allocating an instance of a structure | |
1342 | explicitly where you could previously allocate them on the stack as automatic | |
1343 | variables, and using the provided accessor functions where you would previously | |
1344 | access a structure's field directly. | |
1345 | ||
1346 | Some APIs have changed as well. However, older APIs have been preserved when | |
1347 | possible. | |
1348 | ||
1349 | ||
41149648 RL |
1350 | Post-installation Notes |
1351 | ----------------------- | |
1352 | ||
1353 | With the default OpenSSL installation comes a FIPS provider module, which | |
1354 | needs some post-installation attention, without which it will not be usable. | |
1355 | This involves using the following command: | |
1356 | ||
1357 | openssl fipsinstall | |
1358 | ||
1359 | See the openssl-fipsinstall(1) manual for details and examples. | |
1360 | ||
1361 | ||
6ede7d73 DMSP |
1362 | Advanced Build Options |
1363 | ====================== | |
1364 | ||
1365 | ||
1366 | Environment Variables | |
1367 | --------------------- | |
1368 | ||
1369 | A number of environment variables can be used to provide additional control | |
1370 | over the build process. Typically these should be defined prior to running | |
1371 | config or Configure. Not all environment variables are relevant to all | |
1372 | platforms. | |
1373 | ||
1374 | AR | |
1375 | The name of the ar executable to use. | |
1376 | ||
1377 | BUILDFILE | |
1378 | Use a different build file name than the platform default | |
1379 | ("Makefile" on Unix-like platforms, "makefile" on native Windows, | |
1380 | "descrip.mms" on OpenVMS). This requires that there is a | |
1381 | corresponding build file template. See Configurations/README | |
1382 | for further information. | |
1383 | ||
1384 | CC | |
1385 | The compiler to use. Configure will attempt to pick a default | |
1386 | compiler for your platform but this choice can be overridden | |
1387 | using this variable. Set it to the compiler executable you wish | |
1388 | to use, e.g. "gcc" or "clang". | |
1389 | ||
1390 | CROSS_COMPILE | |
1391 | This environment variable has the same meaning as for the | |
1392 | "--cross-compile-prefix" Configure flag described above. If both | |
1393 | are set then the Configure flag takes precedence. | |
1394 | ||
1395 | NM | |
1396 | The name of the nm executable to use. | |
1397 | ||
1398 | OPENSSL_LOCAL_CONFIG_DIR | |
1399 | OpenSSL comes with a database of information about how it | |
1400 | should be built on different platforms as well as build file | |
1401 | templates for those platforms. The database is comprised of | |
1402 | ".conf" files in the Configurations directory. The build | |
1403 | file templates reside there as well as ".tmpl" files. See the | |
1404 | file Configurations/README for further information about the | |
1405 | format of ".conf" files as well as information on the ".tmpl" | |
1406 | files. | |
1407 | In addition to the standard ".conf" and ".tmpl" files, it is | |
1408 | possible to create your own ".conf" and ".tmpl" files and store | |
1409 | them locally, outside the OpenSSL source tree. This environment | |
1410 | variable can be set to the directory where these files are held | |
1411 | and will be considered by Configure before it looks in the | |
1412 | standard directories. | |
1413 | ||
1414 | PERL | |
1415 | The name of the Perl executable to use when building OpenSSL. | |
1416 | This variable is used in config script only. Configure on the | |
1417 | other hand imposes the interpreter by which it itself was | |
1418 | executed on the whole build procedure. | |
1419 | ||
1420 | HASHBANGPERL | |
1421 | The command string for the Perl executable to insert in the | |
1422 | #! line of perl scripts that will be publicly installed. | |
1423 | Default: /usr/bin/env perl | |
1424 | Note: the value of this variable is added to the same scripts | |
1425 | on all platforms, but it's only relevant on Unix-like platforms. | |
1426 | ||
1427 | RC | |
1428 | The name of the rc executable to use. The default will be as | |
1429 | defined for the target platform in the ".conf" file. If not | |
1430 | defined then "windres" will be used. The WINDRES environment | |
1431 | variable is synonymous to this. If both are defined then RC | |
1432 | takes precedence. | |
1433 | ||
1434 | RANLIB | |
1435 | The name of the ranlib executable to use. | |
1436 | ||
1437 | WINDRES | |
1438 | See RC. | |
1439 | ||
1440 | ||
1441 | Makefile Targets | |
1442 | ---------------- | |
1443 | ||
1444 | The Configure script generates a Makefile in a format relevant to the specific | |
1445 | platform. The Makefiles provide a number of targets that can be used. Not all | |
1446 | targets may be available on all platforms. Only the most common targets are | |
1447 | described here. Examine the Makefiles themselves for the full list. | |
1448 | ||
1449 | all | |
1450 | The target to build all the software components and | |
1451 | documentation. | |
1452 | ||
1453 | build_sw | |
1454 | Build all the software components. | |
1455 | THIS IS THE DEFAULT TARGET. | |
1456 | ||
1457 | build_docs | |
1458 | Build all documentation components. | |
1459 | ||
1460 | clean | |
1461 | Remove all build artefacts and return the directory to a "clean" | |
1462 | state. | |
1463 | ||
1464 | depend | |
1465 | Rebuild the dependencies in the Makefiles. This is a legacy | |
1466 | option that no longer needs to be used since OpenSSL 1.1.0. | |
1467 | ||
1468 | install | |
1469 | Install all OpenSSL components. | |
1470 | ||
1471 | install_sw | |
1472 | Only install the OpenSSL software components. | |
1473 | ||
1474 | install_docs | |
1475 | Only install the OpenSSL documentation components. | |
1476 | ||
1477 | install_man_docs | |
1478 | Only install the OpenSSL man pages (Unix only). | |
1479 | ||
1480 | install_html_docs | |
1481 | Only install the OpenSSL html documentation. | |
1482 | ||
1483 | list-tests | |
1484 | Prints a list of all the self test names. | |
1485 | ||
1486 | test | |
1487 | Build and run the OpenSSL self tests. | |
1488 | ||
1489 | uninstall | |
1490 | Uninstall all OpenSSL components. | |
1491 | ||
1492 | reconfigure | |
1493 | reconf | |
1494 | Re-run the configuration process, as exactly as the last time | |
1495 | as possible. | |
1496 | ||
1497 | update | |
1498 | This is a developer option. If you are developing a patch for | |
1499 | OpenSSL you may need to use this if you want to update | |
1500 | automatically generated files; add new error codes or add new | |
1501 | (or change the visibility of) public API functions. (Unix only). | |
1502 | ||
1503 | Running Selected Tests | |
1504 | ---------------------- | |
1505 | ||
1506 | The make variable TESTS supports a versatile set of space separated tokens | |
1507 | with which you can specify a set of tests to be performed. With a "current | |
1508 | set of tests" in mind, initially being empty, here are the possible tokens: | |
1509 | ||
1510 | alltests The current set of tests becomes the whole set of available | |
1511 | tests (as listed when you do 'make list-tests' or similar). | |
1512 | ||
1513 | xxx Adds the test 'xxx' to the current set of tests. | |
1514 | ||
1515 | -xxx Removes 'xxx' from the current set of tests. If this is the | |
1516 | first token in the list, the current set of tests is first | |
1517 | assigned the whole set of available tests, effectively making | |
1518 | this token equivalent to TESTS="alltests -xxx". | |
1519 | ||
1520 | nn Adds the test group 'nn' (which is a number) to the current | |
1521 | set of tests. | |
1522 | ||
1523 | -nn Removes the test group 'nn' from the current set of tests. | |
1524 | If this is the first token in the list, the current set of | |
1525 | tests is first assigned the whole set of available tests, | |
1526 | effectively making this token equivalent to | |
1527 | TESTS="alltests -xxx". | |
1528 | ||
1529 | Also, all tokens except for "alltests" may have wildcards, such as *. | |
1530 | (on Unix and Windows, BSD style wildcards are supported, while on VMS, | |
1531 | it's VMS style wildcards) | |
1532 | ||
1533 | ### Examples ### | |
1534 | ||
1535 | Run all tests except for the fuzz tests: | |
1536 | ||
1537 | $ make TESTS=-test_fuzz test | |
1538 | ||
1539 | or, if you want to be explicit: | |
1540 | ||
1541 | $ make TESTS='alltests -test_fuzz' test | |
1542 | ||
1543 | Run all tests that have a name starting with "test_ssl" but not those | |
1544 | starting with "test_ssl_": | |
1545 | ||
1546 | $ make TESTS='test_ssl* -test_ssl_*' test | |
1547 | ||
1548 | Run only test group 10: | |
1549 | ||
1550 | $ make TESTS='10' | |
1551 | ||
1552 | Run all tests except the slow group (group 99): | |
1553 | ||
1554 | $ make TESTS='-99' | |
1555 | ||
1556 | Run all tests in test groups 80 to 99 except for tests in group 90: | |
1557 | ||
1558 | $ make TESTS='[89]? -90' | |
d0631327 | 1559 | |
5d2f3e4a P |
1560 | To stochastically verify that the algorithm that produces uniformly distributed |
1561 | random numbers is operating correctly (with a false positive rate of 0.01%): | |
1562 | ||
30a4cda5 | 1563 | $ ./util/wrap.sh test/bntest -stochastic |
6ede7d73 DMSP |
1564 | |
1565 | Troubleshooting | |
1566 | =============== | |
1567 | ||
1568 | Configuration Problems | |
1569 | ---------------------- | |
1570 | ||
1571 | ### Selecting the correct target ### | |
1572 | ||
1573 | The `./config` script tries hard to guess your operating system, but in some | |
1574 | cases it does not succeed. You will see a message like the following: | |
1575 | ||
1576 | $ ./config | |
1577 | Operating system: x86-whatever-minix | |
1578 | This system (minix) is not supported. See file INSTALL for details. | |
1579 | ||
1580 | Even if the automatic target selection by the `./config` script fails, chances | |
1581 | are that you still might find a suitable target in the Configurations directory, | |
1582 | which you can supply to the `./Configure` command, possibly after some adjustment. | |
1583 | ||
1584 | The Configurations directory contains a lot of examples of such targets. | |
1585 | The main configuration file is [10-main.conf][], which contains all targets that | |
1586 | are officially supported by the OpenSSL team. Other configuration files contain | |
1587 | targets contributed by other OpenSSL users. The list of targets can be found in | |
1588 | a Perl list `my %targets = ( ... )`. | |
1589 | ||
1590 | my %targets = ( | |
1591 | ... | |
1592 | "target-name" => { | |
1593 | inherit_from => [ "base-target" ], | |
1594 | CC => "...", | |
1595 | cflags => add("..."), | |
1596 | asm_arch => '...', | |
1597 | perlasm_scheme => "...", | |
1598 | }, | |
1599 | ... | |
1600 | ) | |
1601 | ||
1602 | If you call `.\Configure` without arguments, it will give you a list of all | |
1603 | known targets. Using `grep`, you can lookup the target definition in the | |
1604 | Configurations directory. For example the "android-x86_64" can be found in | |
1605 | Configurations/15-android.conf. | |
1606 | ||
1607 | The directory contains two README files, which explain the general syntax and | |
1608 | design of the configurations files. | |
1609 | ||
1610 | - [Configurations/README](Configurations/README) | |
1611 | - [Configurations/README.design](Configurations/README.design) | |
1612 | ||
1613 | If you need further help, try to search the [openssl-users][] mailing list | |
1614 | or the [GitHub Issues][] for existing solutions. If you don't find anything, | |
1615 | you can [raise an issue][] to ask a question yourself. | |
1616 | ||
1617 | More about our support resources can be found in the [SUPPORT][] file. | |
1618 | ||
1619 | ### Configuration Errors ### | |
1620 | ||
1621 | If the `./config` or `./Configure` command fails with an error message, | |
1622 | read the error message carefully and try to figure out whether you made | |
1623 | a mistake (e.g., by providing a wrong option), or whether the script is | |
1624 | working incorrectly. If you think you encountered a bug, please | |
1625 | [raise an issue][] on GitHub to file a bug report. | |
1626 | ||
1627 | Along with a short description of the bug, please provide the complete | |
1628 | configure command line and the relevant output including the error message. | |
1629 | ||
1630 | Note: To make the output readable, pleace add a 'code fence' (three backquotes | |
1631 | ` ``` ` on a separate line) before and after your output: | |
1632 | ||
1633 | ``` | |
1634 | $ ./Configure [your arguments...] | |
1635 | ||
1636 | [output...] | |
1637 | ||
1638 | ``` | |
1639 | ||
1640 | ||
1641 | Build Failures | |
1642 | -------------- | |
1643 | ||
1644 | If the build fails, look carefully at the output. Try to locate and understand | |
1645 | the error message. It might be that the compiler is already telling you | |
1646 | exactly what you need to do to fix your problem. | |
1647 | ||
1648 | There may be reasons for the failure that aren't problems in OpenSSL itself, | |
1649 | for example if the compiler reports missing standard or third party headers. | |
1650 | ||
1651 | If the build succeeded previously, but fails after a source or configuration | |
1652 | change, it might be helpful to clean the build tree before attempting another | |
1653 | build. Use this command: | |
1654 | ||
1655 | $ make clean # Unix | |
1656 | $ mms clean ! (or mmk) OpenVMS | |
1657 | $ nmake clean # Windows | |
1658 | ||
1659 | Assembler error messages can sometimes be sidestepped by using the | |
1660 | "no-asm" configuration option. | |
1661 | ||
1662 | Compiling parts of OpenSSL with gcc and others with the system compiler will | |
1663 | result in unresolved symbols on some systems. | |
1664 | ||
1665 | If you are still having problems, try to search the [openssl-users][] mailing | |
1666 | list or the [GitHub Issues][] for existing solutions. If you think you | |
1667 | encountered an OpenSSL bug, please [raise an issue][] to file a bug report. | |
1668 | Please take the time to review the existing issues first; maybe the bug was | |
1669 | already reported or has already been fixed. | |
1670 | ||
1671 | ||
1672 | Test Failures | |
1673 | ------------- | |
1674 | ||
1675 | If some tests fail, look at the output. There may be reasons for the failure | |
1676 | that isn't a problem in OpenSSL itself (like a malfunction with Perl). | |
1677 | You may want increased verbosity, that can be accomplished like this: | |
1678 | ||
1679 | Verbosity on failure only (make macro VERBOSE_FAILURE or VF): | |
1680 | ||
1681 | $ make VF=1 test # Unix | |
1682 | $ mms /macro=(VF=1) test ! OpenVMS | |
1683 | $ nmake VF=1 test # Windows | |
1684 | ||
1685 | Full verbosity (make macro VERBOSE or V): | |
1686 | ||
1687 | $ make V=1 test # Unix | |
1688 | $ mms /macro=(V=1) test ! OpenVMS | |
1689 | $ nmake V=1 test # Windows | |
1690 | ||
1691 | If you want to run just one or a few specific tests, you can use | |
1692 | the make variable TESTS to specify them, like this: | |
1693 | ||
1694 | $ make TESTS='test_rsa test_dsa' test # Unix | |
1695 | $ mms/macro="TESTS=test_rsa test_dsa" test ! OpenVMS | |
1696 | $ nmake TESTS='test_rsa test_dsa' test # Windows | |
1697 | ||
1698 | And of course, you can combine (Unix example shown): | |
1699 | ||
1700 | $ make VF=1 TESTS='test_rsa test_dsa' test | |
1701 | ||
1702 | You can find the list of available tests like this: | |
1703 | ||
1704 | $ make list-tests # Unix | |
1705 | $ mms list-tests ! OpenVMS | |
1706 | $ nmake list-tests # Windows | |
1707 | ||
1708 | Have a look at the manual for the perl module Test::Harness to | |
1709 | see what other HARNESS_* variables there are. | |
1710 | ||
1711 | If you find a problem with OpenSSL itself, try removing any | |
1712 | compiler optimization flags from the CFLAGS line in Makefile and | |
1713 | run "make clean; make" or corresponding. | |
1714 | ||
1715 | To report a bug please open an issue on GitHub, at | |
1716 | https://github.com/openssl/openssl/issues. | |
1717 | ||
1718 | For more details on how the make variables TESTS can be used, | |
1719 | see section [Running Selected Tests](#running-selected-tests) below. | |
1720 | ||
1721 | ||
1722 | Notes | |
1723 | ===== | |
1724 | ||
1725 | Notes on multi-threading | |
1726 | ------------------------ | |
1727 | ||
1728 | For some systems, the OpenSSL Configure script knows what compiler options | |
1729 | are needed to generate a library that is suitable for multi-threaded | |
1730 | applications. On these systems, support for multi-threading is enabled | |
1731 | by default; use the "no-threads" option to disable (this should never be | |
1732 | necessary). | |
1733 | ||
1734 | On other systems, to enable support for multi-threading, you will have | |
1735 | to specify at least two options: "threads", and a system-dependent option. | |
1736 | (The latter is "-D_REENTRANT" on various systems.) The default in this | |
1737 | case, obviously, is not to include support for multi-threading (but | |
1738 | you can still use "no-threads" to suppress an annoying warning message | |
1739 | from the Configure script.) | |
1740 | ||
1741 | OpenSSL provides built-in support for two threading models: pthreads (found on | |
1742 | most UNIX/Linux systems), and Windows threads. No other threading models are | |
1743 | supported. If your platform does not provide pthreads or Windows threads then | |
1744 | you should Configure with the "no-threads" option. | |
1745 | ||
1746 | Notes on shared libraries | |
1747 | ------------------------- | |
1748 | ||
1749 | For most systems the OpenSSL Configure script knows what is needed to | |
1750 | build shared libraries for libcrypto and libssl. On these systems | |
1751 | the shared libraries will be created by default. This can be suppressed and | |
1752 | only static libraries created by using the "no-shared" option. On systems | |
1753 | where OpenSSL does not know how to build shared libraries the "no-shared" | |
1754 | option will be forced and only static libraries will be created. | |
1755 | ||
1756 | Shared libraries are named a little differently on different platforms. | |
1757 | One way or another, they all have the major OpenSSL version number as | |
1758 | part of the file name, i.e. for OpenSSL 1.1.x, 1.1 is somehow part of | |
1759 | the name. | |
1760 | ||
1761 | On most POSIX platforms, shared libraries are named libcrypto.so.1.1 | |
1762 | and libssl.so.1.1. | |
1763 | ||
1764 | on Cygwin, shared libraries are named cygcrypto-1.1.dll and cygssl-1.1.dll | |
1765 | with import libraries libcrypto.dll.a and libssl.dll.a. | |
1766 | ||
1767 | On Windows build with MSVC or using MingW, shared libraries are named | |
1768 | libcrypto-1_1.dll and libssl-1_1.dll for 32-bit Windows, libcrypto-1_1-x64.dll | |
1769 | and libssl-1_1-x64.dll for 64-bit x86_64 Windows, and libcrypto-1_1-ia64.dll | |
1770 | and libssl-1_1-ia64.dll for IA64 Windows. With MSVC, the import libraries | |
1771 | are named libcrypto.lib and libssl.lib, while with MingW, they are named | |
1772 | libcrypto.dll.a and libssl.dll.a. | |
1773 | ||
1774 | On VMS, shareable images (VMS speak for shared libraries) are named | |
1775 | ossl$libcrypto0101_shr.exe and ossl$libssl0101_shr.exe. However, when | |
1776 | OpenSSL is specifically built for 32-bit pointers, the shareable images | |
1777 | are named ossl$libcrypto0101_shr32.exe and ossl$libssl0101_shr32.exe | |
1778 | instead, and when built for 64-bit pointers, they are named | |
1779 | ossl$libcrypto0101_shr64.exe and ossl$libssl0101_shr64.exe. | |
1780 | ||
1781 | Notes on random number generation | |
1782 | --------------------------------- | |
1783 | ||
1784 | Availability of cryptographically secure random numbers is required for | |
1785 | secret key generation. OpenSSL provides several options to seed the | |
1786 | internal CSPRNG. If not properly seeded, the internal CSPRNG will refuse | |
1787 | to deliver random bytes and a "PRNG not seeded error" will occur. | |
1788 | ||
1789 | The seeding method can be configured using the `--with-rand-seed` option, | |
1790 | which can be used to specify a comma separated list of seed methods. | |
1791 | However in most cases OpenSSL will choose a suitable default method, | |
1792 | so it is not necessary to explicitly provide this option. Note also | |
1793 | that not all methods are available on all platforms. | |
1794 | ||
1795 | I) On operating systems which provide a suitable randomness source (in | |
1796 | form of a system call or system device), OpenSSL will use the optimal | |
1797 | available method to seed the CSPRNG from the operating system's | |
1798 | randomness sources. This corresponds to the option `--with-rand-seed=os`. | |
1799 | ||
1800 | II) On systems without such a suitable randomness source, automatic seeding | |
1801 | and reseeding is disabled (--with-rand-seed=none) and it may be necessary | |
1802 | to install additional support software to obtain a random seed and reseed | |
1803 | the CSPRNG manually. Please check out the manual pages for RAND_add(), | |
1804 | RAND_bytes(), RAND_egd(), and the FAQ for more information. | |
1805 | ||
1806 | ||
1807 | <!-- Links --> | |
1808 | ||
1809 | [openssl-users]: | |
1810 | https://mta.openssl.org/mailman/listinfo/openssl-users | |
1811 | ||
1812 | [SUPPORT]: | |
1813 | ./SUPPORT.md | |
1814 | ||
1815 | [GitHub Issues]: | |
1816 | https://github.com/openssl/openssl/issues | |
1817 | ||
1818 | [raise an issue]: | |
1819 | https://github.com/openssl/openssl/issues/new/choose | |
1820 | ||
1821 | [10-main.conf]: | |
1822 | Configurations/10-main.conf |