INSTALL@ 86560

Last change on this file since 86560 was 86560, checked in by vboxsync, 4 years ago
openssl-1.1.1h: Applied our OpenSSL changes to 1.1.1h. Didn't check te build. bugref:9847
File size: 56.5 KB

Line
1	OPENSSL INSTALLATION
2	--------------------
3
4	This document describes installation on all supported operating
5	systems (the Unix/Linux family (which includes Mac OS/X), OpenVMS,
6	and Windows).
7
8	To install OpenSSL, you will need:
9
10	* A make implementation
11	* Perl 5 with core modules (please read NOTES.PERL)
12	* The perl module Text::Template (please read NOTES.PERL)
13	* an ANSI C compiler
14	* a development environment in the form of development libraries and C
15	header files
16	* a supported operating system
17
18	For additional platform specific requirements, solutions to specific
19	issues and other details, please read one of these:
20
21	* NOTES.UNIX (any supported Unix like system)
22	* NOTES.VMS (OpenVMS)
23	* NOTES.WIN (any supported Windows)
24	* NOTES.DJGPP (DOS platform with DJGPP)
25	* NOTES.ANDROID (obviously Android [NDK])
26
27	Notational conventions in this document
28	---------------------------------------
29
30	Throughout this document, we use the following conventions in command
31	examples:
32
33	$ command Any line starting with a dollar sign
34	($) is a command line.
35
36	{ word1 \| word2 \| word3 } This denotes a mandatory choice, to be
37	replaced with one of the given words.
38	A simple example would be this:
39
40	$ echo { FOO \| BAR \| COOKIE }
41
42	which is to be understood as one of
43	these:
44
45	$ echo FOO
46	- or -
47	$ echo BAR
48	- or -
49	$ echo COOKIE
50
51	[ word1 \| word2 \| word3 ] Similar to { word1 \| word2 \| word3 }
52	except it's optional to give any of
53	those. In addition to the examples
54	above, this would also be valid:
55
56	$ echo
57
58	{{ target }} This denotes a mandatory word or
59	sequence of words of some sort. A
60	simple example would be this:
61
62	$ type {{ filename }}
63
64	which is to be understood to use the
65	command 'type' on some file name
66	determined by the user.
67
68	[[ options ]] Similar to {{ target }}, but is
69	optional.
70
71	Note that the notation assumes spaces around {, }, [, ], {{, }} and
72	[[, ]]. This is to differentiate from OpenVMS directory
73	specifications, which also use [ and ], but without spaces.
74
75	Quick Start
76	-----------
77
78	If you want to just get on with it, do:
79
80	on Unix (again, this includes Mac OS/X):
81
82	$ ./config
83	$ make
84	$ make test
85	$ make install
86
87	on OpenVMS:
88
89	$ @config
90	$ mms
91	$ mms test
92	$ mms install
93
94	on Windows (only pick one of the targets for configuration):
95
96	$ perl Configure { VC-WIN32 \| VC-WIN64A \| VC-WIN64I \| VC-CE }
97	$ nmake
98	$ nmake test
99	$ nmake install
100
101	Note that in order to perform the install step above you need to have
102	appropriate permissions to write to the installation directory.
103
104	If any of these steps fails, see section Installation in Detail below.
105
106	This will build and install OpenSSL in the default location, which is:
107
108	Unix: normal installation directories under /usr/local
109	OpenVMS: SYS$COMMON:[OPENSSL-'version'...], where 'version' is the
110	OpenSSL version number with underscores instead of periods.
111	Windows: C:\Program Files\OpenSSL or C:\Program Files (x86)\OpenSSL
112
113	The installation directory should be appropriately protected to ensure
114	unprivileged users cannot make changes to OpenSSL binaries or files, or install
115	engines. If you already have a pre-installed version of OpenSSL as part of
116	your Operating System it is recommended that you do not overwrite the system
117	version and instead install to somewhere else.
118
119	If you want to install it anywhere else, run config like this:
120
121	On Unix:
122
123	$ ./config --prefix=/opt/openssl --openssldir=/usr/local/ssl
124
125	On OpenVMS:
126
127	$ @config --prefix=PROGRAM:[INSTALLS] --openssldir=SYS$MANAGER:[OPENSSL]
128
129	(Note: if you do add options to the configuration command, please make sure
130	you've read more than just this Quick Start, such as relevant NOTES.* files,
131	the options outline below, as configuration options may change the outcome
132	in otherwise unexpected ways)
133
134
135	Configuration Options
136	---------------------
137
138	There are several options to ./config (or ./Configure) to customize
139	the build (note that for Windows, the defaults for --prefix and
140	--openssldir depend in what configuration is used and what Windows
141	implementation OpenSSL is built on. More notes on this in NOTES.WIN):
142
143	--api=x.y.z
144	Don't build with support for deprecated APIs below the
145	specified version number. For example "--api=1.1.0" will
146	remove support for all APIS that were deprecated in OpenSSL
147	version 1.1.0 or below. This is a rather specialized option
148	for developers. If you just intend to remove all deprecated
149	APIs entirely (up to the current version), it is easier
150	to add the 'no-deprecated' option instead (see below).
151
152	--cross-compile-prefix=PREFIX
153	The PREFIX to include in front of commands for your
154	toolchain. It's likely to have to end with dash, e.g.
155	a-b-c- would invoke GNU compiler as a-b-c-gcc, etc.
156	Unfortunately cross-compiling is too case-specific to
157	put together one-size-fits-all instructions. You might
158	have to pass more flags or set up environment variables
159	to actually make it work. Android and iOS cases are
160	discussed in corresponding Configurations/15-*.conf
161	files. But there are cases when this option alone is
162	sufficient. For example to build the mingw64 target on
163	Linux "--cross-compile-prefix=x86_64-w64-mingw32-"
164	works. Naturally provided that mingw packages are
165	installed. Today Debian and Ubuntu users have option to
166	install a number of prepackaged cross-compilers along
167	with corresponding run-time and development packages for
168	"alien" hardware. To give another example
169	"--cross-compile-prefix=mipsel-linux-gnu-" suffices
170	in such case. Needless to mention that you have to
171	invoke ./Configure, not ./config, and pass your target
172	name explicitly. Also, note that --openssldir refers
173	to target's file system, not one you are building on.
174
175	--debug
176	Build OpenSSL with debugging symbols and zero optimization
177	level.
178
179	--libdir=DIR
180	The name of the directory under the top of the installation
181	directory tree (see the --prefix option) where libraries will
182	be installed. By default this is "lib". Note that on Windows
183	only ".lib" files will be stored in this location. dll files
184	will always be installed to the "bin" directory.
185
186	--openssldir=DIR
187	Directory for OpenSSL configuration files, and also the
188	default certificate and key store. Defaults are:
189
190	Unix: /usr/local/ssl
191	Windows: C:\Program Files\Common Files\SSL
192	or C:\Program Files (x86)\Common Files\SSL
193	OpenVMS: SYS$COMMON:[OPENSSL-COMMON]
194
195	--prefix=DIR
196	The top of the installation directory tree. Defaults are:
197
198	Unix: /usr/local
199	Windows: C:\Program Files\OpenSSL
200	or C:\Program Files (x86)\OpenSSL
201	OpenVMS: SYS$COMMON:[OPENSSL-'version']
202
203	--release
204	Build OpenSSL without debugging symbols. This is the default.
205
206	--strict-warnings
207	This is a developer flag that switches on various compiler
208	options recommended for OpenSSL development. It only works
209	when using gcc or clang as the compiler. If you are
210	developing a patch for OpenSSL then it is recommended that
211	you use this option where possible.
212
213	--with-zlib-include=DIR
214	The directory for the location of the zlib include file. This
215	option is only necessary if enable-zlib (see below) is used
216	and the include file is not already on the system include
217	path.
218
219	--with-zlib-lib=LIB
220	On Unix: this is the directory containing the zlib library.
221	If not provided the system library path will be used.
222	On Windows: this is the filename of the zlib library (with or
223	without a path). This flag must be provided if the
224	zlib-dynamic option is not also used. If zlib-dynamic is used
225	then this flag is optional and a default value ("ZLIB1") is
226	used if not provided.
227	On VMS: this is the filename of the zlib library (with or
228	without a path). This flag is optional and if not provided
229	then "GNV$LIBZSHR", "GNV$LIBZSHR32" or "GNV$LIBZSHR64" is
230	used by default depending on the pointer size chosen.
231
232
233	--with-rand-seed=seed1[,seed2,...]
234	A comma separated list of seeding methods which will be tried
235	by OpenSSL in order to obtain random input (a.k.a "entropy")
236	for seeding its cryptographically secure random number
237	generator (CSPRNG). The current seeding methods are:
238
239	os: Use a trusted operating system entropy source.
240	This is the default method if such an entropy
241	source exists.
242	getrandom: Use the L<getrandom(2)> or equivalent system
243	call.
244	devrandom: Use the first device from the DEVRANDOM list
245	which can be opened to read random bytes. The
246	DEVRANDOM preprocessor constant expands to
247	"/dev/urandom","/dev/random","/dev/srandom" on
248	most unix-ish operating systems.
249	egd: Check for an entropy generating daemon.
250	rdcpu: Use the RDSEED or RDRAND command if provided by
251	the CPU.
252	librandom: Use librandom (not implemented yet).
253	none: Disable automatic seeding. This is the default
254	on some operating systems where no suitable
255	entropy source exists, or no support for it is
256	implemented yet.
257
258	For more information, see the section 'Note on random number
259	generation' at the end of this document.
260
261	no-afalgeng
262	Don't build the AFALG engine. This option will be forced if
263	on a platform that does not support AFALG.
264
265	enable-asan
266	Build with the Address sanitiser. This is a developer option
267	only. It may not work on all platforms and should never be
268	used in production environments. It will only work when used
269	with gcc or clang and should be used in conjunction with the
270	no-shared option.
271
272	no-asm
273	Do not use assembler code. This should be viewed as
274	debugging/trouble-shooting option rather than production.
275	On some platforms a small amount of assembler code may
276	still be used even with this option.
277
278	no-async
279	Do not build support for async operations.
280
281	no-autoalginit
282	Don't automatically load all supported ciphers and digests.
283	Typically OpenSSL will make available all of its supported
284	ciphers and digests. For a statically linked application this
285	may be undesirable if small executable size is an objective.
286	This only affects libcrypto. Ciphers and digests will have to
287	be loaded manually using EVP_add_cipher() and
288	EVP_add_digest() if this option is used. This option will
289	force a non-shared build.
290
291	no-autoerrinit
292	Don't automatically load all libcrypto/libssl error strings.
293	Typically OpenSSL will automatically load human readable
294	error strings. For a statically linked application this may
295	be undesirable if small executable size is an objective.
296
297	no-autoload-config
298	Don't automatically load the default openssl.cnf file.
299	Typically OpenSSL will automatically load a system config
300	file which configures default ssl options.
301
302	enable-buildtest-c++
303	While testing, generate C++ buildtest files that
304	simply check that the public OpenSSL header files
305	are usable standalone with C++.
306
307	Enabling this option demands extra care. For any
308	compiler flag given directly as configuration
309	option, you must ensure that it's valid for both
310	the C and the C++ compiler. If not, the C++ build
311	test will most likely break. As an alternative,
312	you can use the language specific variables, CFLAGS
313	and CXXFLAGS.
314
315	no-capieng
316	Don't build the CAPI engine. This option will be forced if
317	on a platform that does not support CAPI.
318
319	no-cms
320	Don't build support for CMS features
321
322	no-comp
323	Don't build support for SSL/TLS compression. If this option
324	is left enabled (the default), then compression will only
325	work if the zlib or zlib-dynamic options are also chosen.
326
327	enable-crypto-mdebug
328	Build support for debugging memory allocated via
329	OPENSSL_malloc() or OPENSSL_zalloc().
330
331	enable-crypto-mdebug-backtrace
332	As for crypto-mdebug, but additionally provide backtrace
333	information for allocated memory.
334	TO BE USED WITH CARE: this uses GNU C functionality, and
335	is therefore not usable for non-GNU config targets. If
336	your build complains about the use of '-rdynamic' or the
337	lack of header file execinfo.h, this option is not for you.
338	ALSO NOTE that even though execinfo.h is available on your
339	system (through Gnulib), the functions might just be stubs
340	that do nothing.
341
342	no-ct
343	Don't build support for Certificate Transparency.
344
345	no-deprecated
346	Don't build with support for any deprecated APIs. This is the
347	same as using "--api" and supplying the latest version
348	number.
349
350	no-dgram
351	Don't build support for datagram based BIOs. Selecting this
352	option will also force the disabling of DTLS.
353
354	no-dso
355	Don't build support for loading Dynamic Shared Objects.
356
357	enable-devcryptoeng
358	Build the /dev/crypto engine. It is automatically selected
359	on BSD implementations, in which case it can be disabled with
360	no-devcryptoeng.
361
362	no-dynamic-engine
363	Don't build the dynamically loaded engines. This only has an
364	effect in a "shared" build
365
366	no-ec
367	Don't build support for Elliptic Curves.
368
369	no-ec2m
370	Don't build support for binary Elliptic Curves
371
372	enable-ec_nistp_64_gcc_128
373	Enable support for optimised implementations of some commonly
374	used NIST elliptic curves.
375	This is only supported on platforms:
376	- with little-endian storage of non-byte types
377	- that tolerate misaligned memory references
378	- where the compiler:
379	- supports the non-standard type __uint128_t
380	- defines the built-in macro __SIZEOF_INT128__
381
382	enable-egd
383	Build support for gathering entropy from EGD (Entropy
384	Gathering Daemon).
385
386	no-engine
387	Don't build support for loading engines.
388
389	no-err
390	Don't compile in any error strings.
391
392	enable-external-tests
393	Enable building of integration with external test suites.
394	This is a developer option and may not work on all platforms.
395	The only supported external test suite at the current time is
396	the BoringSSL test suite. See the file test/README.external
397	for further details.
398
399	no-filenames
400	Don't compile in filename and line number information (e.g.
401	for errors and memory allocation).
402
403	enable-fuzz-libfuzzer, enable-fuzz-afl
404	Build with support for fuzzing using either libfuzzer or AFL.
405	These are developer options only. They may not work on all
406	platforms and should never be used in production environments.
407	See the file fuzz/README.md for further details.
408
409	no-gost
410	Don't build support for GOST based ciphersuites. Note that
411	if this feature is enabled then GOST ciphersuites are only
412	available if the GOST algorithms are also available through
413	loading an externally supplied engine.
414
415	no-hw-padlock
416	Don't build the padlock engine.
417
418	no-makedepend
419	Don't generate dependencies.
420
421	no-multiblock
422	Don't build support for writing multiple records in one
423	go in libssl (Note: this is a different capability to the
424	pipelining functionality).
425
426	no-nextprotoneg
427	Don't build support for the NPN TLS extension.
428
429	no-ocsp
430	Don't build support for OCSP.
431
432	no-pic
433	Don't build with support for Position Independent Code.
434
435	no-pinshared By default OpenSSL will attempt to stay in memory until the
436	process exits. This is so that libcrypto and libssl can be
437	properly cleaned up automatically via an "atexit()" handler.
438	The handler is registered by libcrypto and cleans up both
439	libraries. On some platforms the atexit() handler will run on
440	unload of libcrypto (if it has been dynamically loaded)
441	rather than at process exit. This option can be used to stop
442	OpenSSL from attempting to stay in memory until the process
443	exits. This could lead to crashes if either libcrypto or
444	libssl have already been unloaded at the point
445	that the atexit handler is invoked, e.g. on a platform which
446	calls atexit() on unload of the library, and libssl is
447	unloaded before libcrypto then a crash is likely to happen.
448	Applications can suppress running of the atexit() handler at
449	run time by using the OPENSSL_INIT_NO_ATEXIT option to
450	OPENSSL_init_crypto(). See the man page for it for further
451	details.
452
453	no-posix-io
454	Don't use POSIX IO capabilities.
455
456	no-psk
457	Don't build support for Pre-Shared Key based ciphersuites.
458
459	no-rdrand
460	Don't use hardware RDRAND capabilities.
461
462	no-rfc3779
463	Don't build support for RFC3779 ("X.509 Extensions for IP
464	Addresses and AS Identifiers")
465
466	sctp
467	Build support for SCTP
468
469	no-shared
470	Do not create shared libraries, only static ones. See "Note
471	on shared libraries" below.
472
473	no-sock
474	Don't build support for socket BIOs
475
476	no-srp
477	Don't build support for SRP or SRP based ciphersuites.
478
479	no-srtp
480	Don't build SRTP support
481
482	no-sse2
483	Exclude SSE2 code paths from 32-bit x86 assembly modules.
484	Normally SSE2 extension is detected at run-time, but the
485	decision whether or not the machine code will be executed
486	is taken solely on CPU capability vector. This means that
487	if you happen to run OS kernel which does not support SSE2
488	extension on Intel P4 processor, then your application
489	might be exposed to "illegal instruction" exception.
490	There might be a way to enable support in kernel, e.g.
491	FreeBSD kernel can be compiled with CPU_ENABLE_SSE, and
492	there is a way to disengage SSE2 code paths upon application
493	start-up, but if you aim for wider "audience" running
494	such kernel, consider no-sse2. Both the 386 and
495	no-asm options imply no-sse2.
496
497	enable-ssl-trace
498	Build with the SSL Trace capabilities (adds the "-trace"
499	option to s_client and s_server).
500
501	no-static-engine
502	Don't build the statically linked engines. This only
503	has an impact when not built "shared".
504
505	no-stdio
506	Don't use anything from the C header file "stdio.h" that
507	makes use of the "FILE" type. Only libcrypto and libssl can
508	be built in this way. Using this option will suppress
509	building the command line applications. Additionally since
510	the OpenSSL tests also use the command line applications the
511	tests will also be skipped.
512
513	no-tests
514	Don't build test programs or run any test.
515
516	no-threads
517	Don't try to build with support for multi-threaded
518	applications.
519
520	threads
521	Build with support for multi-threaded applications. Most
522	platforms will enable this by default. However if on a
523	platform where this is not the case then this will usually
524	require additional system-dependent options! See "Note on
525	multi-threading" below.
526
527	no-ts
528	Don't build Time Stamping Authority support.
529
530	enable-ubsan
531	Build with the Undefined Behaviour sanitiser. This is a
532	developer option only. It may not work on all platforms and
533	should never be used in production environments. It will only
534	work when used with gcc or clang and should be used in
535	conjunction with the "-DPEDANTIC" option (or the
536	--strict-warnings option).
537
538	no-ui-console
539	Don't build with the "UI" console method (i.e. the "UI"
540	method that enables text based console prompts).
541
542	enable-unit-test
543	Enable additional unit test APIs. This should not typically
544	be used in production deployments.
545
546	enable-weak-ssl-ciphers
547	Build support for SSL/TLS ciphers that are considered "weak"
548	(e.g. RC4 based ciphersuites).
549
550	zlib
551	Build with support for zlib compression/decompression.
552
553	zlib-dynamic
554	Like "zlib", but has OpenSSL load the zlib library
555	dynamically when needed. This is only supported on systems
556	where loading of shared libraries is supported.
557
558	386
559	In 32-bit x86 builds, when generating assembly modules,
560	use the 80386 instruction set only (the default x86 code
561	is more efficient, but requires at least a 486). Note:
562	This doesn't affect code generated by compiler, you're
563	likely to complement configuration command line with
564	suitable compiler-specific option.
565
566	no-<prot>
567	Don't build support for negotiating the specified SSL/TLS
568	protocol (one of ssl, ssl3, tls, tls1, tls1_1, tls1_2,
569	tls1_3, dtls, dtls1 or dtls1_2). If "no-tls" is selected then
570	all of tls1, tls1_1, tls1_2 and tls1_3 are disabled.
571	Similarly "no-dtls" will disable dtls1 and dtls1_2. The
572	"no-ssl" option is synonymous with "no-ssl3". Note this only
573	affects version negotiation. OpenSSL will still provide the
574	methods for applications to explicitly select the individual
575	protocol versions.
576
577	no-<prot>-method
578	As for no-<prot> but in addition do not build the methods for
579	applications to explicitly select individual protocol
580	versions. Note that there is no "no-tls1_3-method" option
581	because there is no application method for TLSv1.3. Using
582	individual protocol methods directly is deprecated.
583	Applications should use TLS_method() instead.
584
585	enable-<alg>
586	Build with support for the specified algorithm, where <alg>
587	is one of: md2 or rc5.
588
589	no-<alg>
590	Build without support for the specified algorithm, where
591	<alg> is one of: aria, bf, blake2, camellia, cast, chacha,
592	cmac, des, dh, dsa, ecdh, ecdsa, idea, md4, mdc2, ocb,
593	poly1305, rc2, rc4, rmd160, scrypt, seed, siphash, sm2, sm3,
594	sm4 or whirlpool. The "ripemd" algorithm is deprecated and
595	if used is synonymous with rmd160.
596
597	-Dxxx, -Ixxx, -Wp, -lxxx, -Lxxx, -Wl, -rpath, -R, -framework, -static
598	These system specific options will be recognised and
599	passed through to the compiler to allow you to define
600	preprocessor symbols, specify additional libraries, library
601	directories or other compiler options. It might be worth
602	noting that some compilers generate code specifically for
603	processor the compiler currently executes on. This is not
604	necessarily what you might have in mind, since it might be
605	unsuitable for execution on other, typically older,
606	processor. Consult your compiler documentation.
607
608	Take note of the VAR=value documentation below and how
609	these flags interact with those variables.
610
611	-xxx, +xxx, /xxx
612	Additional options that are not otherwise recognised are
613	passed through as they are to the compiler as well.
614	Unix-style options beginning with a '-' or '+' and
615	Windows-style options beginning with a '/' are recognized.
616	Again, consult your compiler documentation.
617
618	If the option contains arguments separated by spaces,
619	then the URL-style notation %20 can be used for the space
620	character in order to avoid having to quote the option.
621	For example, -opt%20arg gets expanded to -opt arg.
622	In fact, any ASCII character can be encoded as %xx using its
623	hexadecimal encoding.
624
625	Take note of the VAR=value documentation below and how
626	these flags interact with those variables.
627
628	VAR=value
629	Assignment of environment variable for Configure. These
630	work just like normal environment variable assignments,
631	but are supported on all platforms and are confined to
632	the configuration scripts only. These assignments override
633	the corresponding value in the inherited environment, if
634	there is one.
635
636	The following variables are used as "make variables" and
637	can be used as an alternative to giving preprocessor,
638	compiler and linker options directly as configuration.
639	The following variables are supported:
640
641	AR The static library archiver.
642	ARFLAGS Flags for the static library archiver.
643	AS The assembler compiler.
644	ASFLAGS Flags for the assembler compiler.
645	CC The C compiler.
646	CFLAGS Flags for the C compiler.
647	CXX The C++ compiler.
648	CXXFLAGS Flags for the C++ compiler.
649	CPP The C/C++ preprocessor.
650	CPPFLAGS Flags for the C/C++ preprocessor.
651	CPPDEFINES List of CPP macro definitions, separated
652	by a platform specific character (':' or
653	space for Unix, ';' for Windows, ',' for
654	VMS). This can be used instead of using
655	-D (or what corresponds to that on your
656	compiler) in CPPFLAGS.
657	CPPINCLUDES List of CPP inclusion directories, separated
658	the same way as for CPPDEFINES. This can
659	be used instead of -I (or what corresponds
660	to that on your compiler) in CPPFLAGS.
661	HASHBANGPERL Perl invocation to be inserted after '#!'
662	in public perl scripts (only relevant on
663	Unix).
664	LD The program linker (not used on Unix, $(CC)
665	is used there).
666	LDFLAGS Flags for the shared library, DSO and
667	program linker.
668	LDLIBS Extra libraries to use when linking.
669	Takes the form of a space separated list
670	of library specifications on Unix and
671	Windows, and as a comma separated list of
672	libraries on VMS.
673	RANLIB The library archive indexer.
674	RC The Windows resource compiler.
675	RCFLAGS Flags for the Windows resource compiler.
676	RM The command to remove files and directories.
677
678	These cannot be mixed with compiling / linking flags given
679	on the command line. In other words, something like this
680	isn't permitted.
681
682	./config -DFOO CPPFLAGS=-DBAR -DCOOKIE
683
684	Backward compatibility note:
685
686	To be compatible with older configuration scripts, the
687	environment variables are ignored if compiling / linking
688	flags are given on the command line, except for these:
689
690	AR, CC, CXX, CROSS_COMPILE, HASHBANGPERL, PERL, RANLIB, RC
691	and WINDRES
692
693	For example, the following command will not see -DBAR:
694
695	CPPFLAGS=-DBAR ./config -DCOOKIE
696
697	However, the following will see both set variables:
698
699	CC=gcc CROSS_COMPILE=x86_64-w64-mingw32- \
700	./config -DCOOKIE
701
702	If CC is set, it is advisable to also set CXX to ensure
703	both C and C++ compilers are in the same "family". This
704	becomes relevant with 'enable-external-tests' and
705	'enable-buildtest-c++'.
706
707	reconf
708	reconfigure
709	Reconfigure from earlier data. This fetches the previous
710	command line options and environment from data saved in
711	"configdata.pm", and runs the configuration process again,
712	using these options and environment.
713	Note: NO other option is permitted together with "reconf".
714	This means that you also MUST use "./Configure" (or
715	what corresponds to that on non-Unix platforms) directly
716	to invoke this option.
717	Note: The original configuration saves away values for ALL
718	environment variables that were used, and if they weren't
719	defined, they are still saved away with information that
720	they weren't originally defined. This information takes
721	precedence over environment variables that are defined
722	when reconfiguring.
723
724	Displaying configuration data
725	-----------------------------
726
727	The configuration script itself will say very little, and finishes by
728	creating "configdata.pm". This perl module can be loaded by other scripts
729	to find all the configuration data, and it can also be used as a script to
730	display all sorts of configuration data in a human readable form.
731
732	For more information, please do:
733
734	$ ./configdata.pm --help # Unix
735
736	or
737
738	$ perl configdata.pm --help # Windows and VMS
739
740	Installation in Detail
741	----------------------
742
743	1a. Configure OpenSSL for your operation system automatically:
744
745	NOTE: This is not available on Windows.
746
747	$ ./config [[ options ]] # Unix
748
749	or
750
751	$ @config [[ options ]] ! OpenVMS
752
753	For the remainder of this text, the Unix form will be used in all
754	examples, please use the appropriate form for your platform.
755
756	This guesses at your operating system (and compiler, if necessary) and
757	configures OpenSSL based on this guess. Run ./config -t to see
758	if it guessed correctly. If you want to use a different compiler, you
759	are cross-compiling for another platform, or the ./config guess was
760	wrong for other reasons, go to step 1b. Otherwise go to step 2.
761
762	On some systems, you can include debugging information as follows:
763
764	$ ./config -d [[ options ]]
765
766	1b. Configure OpenSSL for your operating system manually
767
768	OpenSSL knows about a range of different operating system, hardware and
769	compiler combinations. To see the ones it knows about, run
770
771	$ ./Configure # Unix
772
773	or
774
775	$ perl Configure # All other platforms
776
777	For the remainder of this text, the Unix form will be used in all
778	examples, please use the appropriate form for your platform.
779
780	Pick a suitable name from the list that matches your system. For most
781	operating systems there is a choice between using "cc" or "gcc". When
782	you have identified your system (and if necessary compiler) use this name
783	as the argument to Configure. For example, a "linux-elf" user would
784	run:
785
786	$ ./Configure linux-elf [[ options ]]
787
788	If your system isn't listed, you will have to create a configuration
789	file named Configurations/{{ something }}.conf and add the correct
790	configuration for your system. See the available configs as examples
791	and read Configurations/README and Configurations/README.design for
792	more information.
793
794	The generic configurations "cc" or "gcc" should usually work on 32 bit
795	Unix-like systems.
796
797	Configure creates a build file ("Makefile" on Unix, "makefile" on Windows
798	and "descrip.mms" on OpenVMS) from a suitable template in Configurations,
799	and defines various macros in include/openssl/opensslconf.h (generated from
800	include/openssl/opensslconf.h.in).
801
802	1c. Configure OpenSSL for building outside of the source tree.
803
804	OpenSSL can be configured to build in a build directory separate from
805	the directory with the source code. It's done by placing yourself in
806	some other directory and invoking the configuration commands from
807	there.
808
809	Unix example:
810
811	$ mkdir /var/tmp/openssl-build
812	$ cd /var/tmp/openssl-build
813	$ /PATH/TO/OPENSSL/SOURCE/config [[ options ]]
814
815	or
816
817	$ /PATH/TO/OPENSSL/SOURCE/Configure {{ target }} [[ options ]]
818
819	OpenVMS example:
820
821	$ set default sys$login:
822	$ create/dir [.tmp.openssl-build]
823	$ set default [.tmp.openssl-build]
824	$ @[PATH.TO.OPENSSL.SOURCE]config [[ options ]]
825
826	or
827
828	$ @[PATH.TO.OPENSSL.SOURCE]Configure {{ target }} [[ options ]]
829
830	Windows example:
831
832	$ C:
833	$ mkdir \temp-openssl
834	$ cd \temp-openssl
835	$ perl d:\PATH\TO\OPENSSL\SOURCE\Configure {{ target }} [[ options ]]
836
837	Paths can be relative just as well as absolute. Configure will
838	do its best to translate them to relative paths whenever possible.
839
840	2. Build OpenSSL by running:
841
842	$ make # Unix
843	$ mms ! (or mmk) OpenVMS
844	$ nmake # Windows
845
846	This will build the OpenSSL libraries (libcrypto.a and libssl.a on
847	Unix, corresponding on other platforms) and the OpenSSL binary
848	("openssl"). The libraries will be built in the top-level directory,
849	and the binary will be in the "apps" subdirectory.
850
851	Troubleshooting:
852
853	If the build fails, look at the output. There may be reasons
854	for the failure that aren't problems in OpenSSL itself (like
855	missing standard headers).
856
857	If the build succeeded previously, but fails after a source or
858	configuration change, it might be helpful to clean the build tree
859	before attempting another build. Use this command:
860
861	$ make clean # Unix
862	$ mms clean ! (or mmk) OpenVMS
863	$ nmake clean # Windows
864
865	Assembler error messages can sometimes be sidestepped by using the
866	"no-asm" configuration option.
867
868	Compiling parts of OpenSSL with gcc and others with the system
869	compiler will result in unresolved symbols on some systems.
870
871	If you are still having problems you can get help by sending an email
872	to the openssl-users email list (see
873	https://www.openssl.org/community/mailinglists.html for details). If
874	it is a bug with OpenSSL itself, please open an issue on GitHub, at
875	https://github.com/openssl/openssl/issues. Please review the existing
876	ones first; maybe the bug was already reported or has already been
877	fixed.
878
879	3. After a successful build, the libraries should be tested. Run:
880
881	$ make test # Unix
882	$ mms test ! OpenVMS
883	$ nmake test # Windows
884
885	NOTE: you MUST run the tests from an unprivileged account (or
886	disable your privileges temporarily if your platform allows it).
887
888	If some tests fail, look at the output. There may be reasons for
889	the failure that isn't a problem in OpenSSL itself (like a
890	malfunction with Perl). You may want increased verbosity, that
891	can be accomplished like this:
892
893	$ make VERBOSE=1 test # Unix
894
895	$ mms /macro=(VERBOSE=1) test ! OpenVMS
896
897	$ nmake VERBOSE=1 test # Windows
898
899	If you want to run just one or a few specific tests, you can use
900	the make variable TESTS to specify them, like this:
901
902	$ make TESTS='test_rsa test_dsa' test # Unix
903	$ mms/macro="TESTS=test_rsa test_dsa" test ! OpenVMS
904	$ nmake TESTS='test_rsa test_dsa' test # Windows
905
906	And of course, you can combine (Unix example shown):
907
908	$ make VERBOSE=1 TESTS='test_rsa test_dsa' test
909
910	You can find the list of available tests like this:
911
912	$ make list-tests # Unix
913	$ mms list-tests ! OpenVMS
914	$ nmake list-tests # Windows
915
916	Have a look at the manual for the perl module Test::Harness to
917	see what other HARNESS_* variables there are.
918
919	If you find a problem with OpenSSL itself, try removing any
920	compiler optimization flags from the CFLAGS line in Makefile and
921	run "make clean; make" or corresponding.
922
923	To report a bug please open an issue on GitHub, at
924	https://github.com/openssl/openssl/issues.
925
926	For more details on how the make variables TESTS can be used,
927	see section TESTS in Detail below.
928
929	4. If everything tests ok, install OpenSSL with
930
931	$ make install # Unix
932	$ mms install ! OpenVMS
933	$ nmake install # Windows
934
935	Note that in order to perform the install step above you need to have
936	appropriate permissions to write to the installation directory.
937
938	The above commands will install all the software components in this
939	directory tree under PREFIX (the directory given with --prefix or its
940	default):
941
942	Unix:
943
944	bin/ Contains the openssl binary and a few other
945	utility scripts.
946	include/openssl
947	Contains the header files needed if you want
948	to build your own programs that use libcrypto
949	or libssl.
950	lib Contains the OpenSSL library files.
951	lib/engines Contains the OpenSSL dynamically loadable engines.
952
953	share/man/man1 Contains the OpenSSL command line man-pages.
954	share/man/man3 Contains the OpenSSL library calls man-pages.
955	share/man/man5 Contains the OpenSSL configuration format man-pages.
956	share/man/man7 Contains the OpenSSL other misc man-pages.
957
958	share/doc/openssl/html/man1
959	share/doc/openssl/html/man3
960	share/doc/openssl/html/man5
961	share/doc/openssl/html/man7
962	Contains the HTML rendition of the man-pages.
963
964	OpenVMS ('arch' is replaced with the architecture name, "Alpha"
965	or "ia64", 'sover' is replaced with the shared library version
966	(0101 for 1.1), and 'pz' is replaced with the pointer size
967	OpenSSL was built with):
968
969	[.EXE.'arch'] Contains the openssl binary.
970	[.EXE] Contains a few utility scripts.
971	[.include.openssl]
972	Contains the header files needed if you want
973	to build your own programs that use libcrypto
974	or libssl.
975	[.LIB.'arch'] Contains the OpenSSL library files.
976	[.ENGINES'sover''pz'.'arch']
977	Contains the OpenSSL dynamically loadable engines.
978	[.SYS$STARTUP] Contains startup, login and shutdown scripts.
979	These define appropriate logical names and
980	command symbols.
981	[.SYSTEST] Contains the installation verification procedure.
982	[.HTML] Contains the HTML rendition of the manual pages.
983
984
985	Additionally, install will add the following directories under
986	OPENSSLDIR (the directory given with --openssldir or its default)
987	for you convenience:
988
989	certs Initially empty, this is the default location
990	for certificate files.
991	private Initially empty, this is the default location
992	for private key files.
993	misc Various scripts.
994
995	The installation directory should be appropriately protected to ensure
996	unprivileged users cannot make changes to OpenSSL binaries or files, or
997	install engines. If you already have a pre-installed version of OpenSSL as
998	part of your Operating System it is recommended that you do not overwrite
999	the system version and instead install to somewhere else.
1000
1001	Package builders who want to configure the library for standard
1002	locations, but have the package installed somewhere else so that
1003	it can easily be packaged, can use
1004
1005	$ make DESTDIR=/tmp/package-root install # Unix
1006	$ mms/macro="DESTDIR=TMP:[PACKAGE-ROOT]" install ! OpenVMS
1007
1008	The specified destination directory will be prepended to all
1009	installation target paths.
1010
1011	Compatibility issues with previous OpenSSL versions:
1012
1013	* COMPILING existing applications
1014
1015	Starting with version 1.1.0, OpenSSL hides a number of structures
1016	that were previously open. This includes all internal libssl
1017	structures and a number of EVP types. Accessor functions have
1018	been added to allow controlled access to the structures' data.
1019
1020	This means that some software needs to be rewritten to adapt to
1021	the new ways of doing things. This often amounts to allocating
1022	an instance of a structure explicitly where you could previously
1023	allocate them on the stack as automatic variables, and using the
1024	provided accessor functions where you would previously access a
1025	structure's field directly.
1026
1027	Some APIs have changed as well. However, older APIs have been
1028	preserved when possible.
1029
1030	Environment Variables
1031	---------------------
1032
1033	A number of environment variables can be used to provide additional control
1034	over the build process. Typically these should be defined prior to running
1035	config or Configure. Not all environment variables are relevant to all
1036	platforms.
1037
1038	AR
1039	The name of the ar executable to use.
1040
1041	BUILDFILE
1042	Use a different build file name than the platform default
1043	("Makefile" on Unix-like platforms, "makefile" on native Windows,
1044	"descrip.mms" on OpenVMS). This requires that there is a
1045	corresponding build file template. See Configurations/README
1046	for further information.
1047
1048	CC
1049	The compiler to use. Configure will attempt to pick a default
1050	compiler for your platform but this choice can be overridden
1051	using this variable. Set it to the compiler executable you wish
1052	to use, e.g. "gcc" or "clang".
1053
1054	CROSS_COMPILE
1055	This environment variable has the same meaning as for the
1056	"--cross-compile-prefix" Configure flag described above. If both
1057	are set then the Configure flag takes precedence.
1058
1059	NM
1060	The name of the nm executable to use.
1061
1062	OPENSSL_LOCAL_CONFIG_DIR
1063	OpenSSL comes with a database of information about how it
1064	should be built on different platforms as well as build file
1065	templates for those platforms. The database is comprised of
1066	".conf" files in the Configurations directory. The build
1067	file templates reside there as well as ".tmpl" files. See the
1068	file Configurations/README for further information about the
1069	format of ".conf" files as well as information on the ".tmpl"
1070	files.
1071	In addition to the standard ".conf" and ".tmpl" files, it is
1072	possible to create your own ".conf" and ".tmpl" files and store
1073	them locally, outside the OpenSSL source tree. This environment
1074	variable can be set to the directory where these files are held
1075	and will be considered by Configure before it looks in the
1076	standard directories.
1077
1078	PERL
1079	The name of the Perl executable to use when building OpenSSL.
1080	This variable is used in config script only. Configure on the
1081	other hand imposes the interpreter by which it itself was
1082	executed on the whole build procedure.
1083
1084	HASHBANGPERL
1085	The command string for the Perl executable to insert in the
1086	#! line of perl scripts that will be publicly installed.
1087	Default: /usr/bin/env perl
1088	Note: the value of this variable is added to the same scripts
1089	on all platforms, but it's only relevant on Unix-like platforms.
1090
1091	RC
1092	The name of the rc executable to use. The default will be as
1093	defined for the target platform in the ".conf" file. If not
1094	defined then "windres" will be used. The WINDRES environment
1095	variable is synonymous to this. If both are defined then RC
1096	takes precedence.
1097
1098	RANLIB
1099	The name of the ranlib executable to use.
1100
1101	WINDRES
1102	See RC.
1103
1104	Makefile targets
1105	----------------
1106
1107	The Configure script generates a Makefile in a format relevant to the specific
1108	platform. The Makefiles provide a number of targets that can be used. Not all
1109	targets may be available on all platforms. Only the most common targets are
1110	described here. Examine the Makefiles themselves for the full list.
1111
1112	all
1113	The default target to build all the software components.
1114
1115	clean
1116	Remove all build artefacts and return the directory to a "clean"
1117	state.
1118
1119	depend
1120	Rebuild the dependencies in the Makefiles. This is a legacy
1121	option that no longer needs to be used since OpenSSL 1.1.0.
1122
1123	install
1124	Install all OpenSSL components.
1125
1126	install_sw
1127	Only install the OpenSSL software components.
1128
1129	install_docs
1130	Only install the OpenSSL documentation components.
1131
1132	install_man_docs
1133	Only install the OpenSSL man pages (Unix only).
1134
1135	install_html_docs
1136	Only install the OpenSSL html documentation.
1137
1138	list-tests
1139	Prints a list of all the self test names.
1140
1141	test
1142	Build and run the OpenSSL self tests.
1143
1144	uninstall
1145	Uninstall all OpenSSL components.
1146
1147	reconfigure
1148	reconf
1149	Re-run the configuration process, as exactly as the last time
1150	as possible.
1151
1152	update
1153	This is a developer option. If you are developing a patch for
1154	OpenSSL you may need to use this if you want to update
1155	automatically generated files; add new error codes or add new
1156	(or change the visibility of) public API functions. (Unix only).
1157
1158	TESTS in Detail
1159	---------------
1160
1161	The make variable TESTS supports a versatile set of space separated tokens
1162	with which you can specify a set of tests to be performed. With a "current
1163	set of tests" in mind, initially being empty, here are the possible tokens:
1164
1165	alltests The current set of tests becomes the whole set of available
1166	tests (as listed when you do 'make list-tests' or similar).
1167	xxx Adds the test 'xxx' to the current set of tests.
1168	-xxx Removes 'xxx' from the current set of tests. If this is the
1169	first token in the list, the current set of tests is first
1170	assigned the whole set of available tests, effectively making
1171	this token equivalent to TESTS="alltests -xxx".
1172	nn Adds the test group 'nn' (which is a number) to the current
1173	set of tests.
1174	-nn Removes the test group 'nn' from the current set of tests.
1175	If this is the first token in the list, the current set of
1176	tests is first assigned the whole set of available tests,
1177	effectively making this token equivalent to
1178	TESTS="alltests -xxx".
1179
1180	Also, all tokens except for "alltests" may have wildcards, such as *.
1181	(on Unix and Windows, BSD style wildcards are supported, while on VMS,
1182	it's VMS style wildcards)
1183
1184	Example: All tests except for the fuzz tests:
1185
1186	$ make TESTS=-test_fuzz test
1187
1188	or (if you want to be explicit)
1189
1190	$ make TESTS='alltests -test_fuzz' test
1191
1192	Example: All tests that have a name starting with "test_ssl" but not those
1193	starting with "test_ssl_":
1194
1195	$ make TESTS='test_ssl* -test_ssl_*' test
1196
1197	Example: Only test group 10:
1198
1199	$ make TESTS='10'
1200
1201	Example: All tests except the slow group (group 99):
1202
1203	$ make TESTS='-99'
1204
1205	Example: All tests in test groups 80 to 99 except for tests in group 90:
1206
1207	$ make TESTS='[89]? -90'
1208
1209	Note on multi-threading
1210	-----------------------
1211
1212	For some systems, the OpenSSL Configure script knows what compiler options
1213	are needed to generate a library that is suitable for multi-threaded
1214	applications. On these systems, support for multi-threading is enabled
1215	by default; use the "no-threads" option to disable (this should never be
1216	necessary).
1217
1218	On other systems, to enable support for multi-threading, you will have
1219	to specify at least two options: "threads", and a system-dependent option.
1220	(The latter is "-D_REENTRANT" on various systems.) The default in this
1221	case, obviously, is not to include support for multi-threading (but
1222	you can still use "no-threads" to suppress an annoying warning message
1223	from the Configure script.)
1224
1225	OpenSSL provides built-in support for two threading models: pthreads (found on
1226	most UNIX/Linux systems), and Windows threads. No other threading models are
1227	supported. If your platform does not provide pthreads or Windows threads then
1228	you should Configure with the "no-threads" option.
1229
1230	Notes on shared libraries
1231	-------------------------
1232
1233	For most systems the OpenSSL Configure script knows what is needed to
1234	build shared libraries for libcrypto and libssl. On these systems
1235	the shared libraries will be created by default. This can be suppressed and
1236	only static libraries created by using the "no-shared" option. On systems
1237	where OpenSSL does not know how to build shared libraries the "no-shared"
1238	option will be forced and only static libraries will be created.
1239
1240	Shared libraries are named a little differently on different platforms.
1241	One way or another, they all have the major OpenSSL version number as
1242	part of the file name, i.e. for OpenSSL 1.1.x, 1.1 is somehow part of
1243	the name.
1244
1245	On most POSIX platforms, shared libraries are named libcrypto.so.1.1
1246	and libssl.so.1.1.
1247
1248	on Cygwin, shared libraries are named cygcrypto-1.1.dll and cygssl-1.1.dll
1249	with import libraries libcrypto.dll.a and libssl.dll.a.
1250
1251	On Windows build with MSVC or using MingW, shared libraries are named
1252	libcrypto-1_1.dll and libssl-1_1.dll for 32-bit Windows, libcrypto-1_1-x64.dll
1253	and libssl-1_1-x64.dll for 64-bit x86_64 Windows, and libcrypto-1_1-ia64.dll
1254	and libssl-1_1-ia64.dll for IA64 Windows. With MSVC, the import libraries
1255	are named libcrypto.lib and libssl.lib, while with MingW, they are named
1256	libcrypto.dll.a and libssl.dll.a.
1257
1258	On VMS, shareable images (VMS speak for shared libraries) are named
1259	ossl$libcrypto0101_shr.exe and ossl$libssl0101_shr.exe. However, when
1260	OpenSSL is specifically built for 32-bit pointers, the shareable images
1261	are named ossl$libcrypto0101_shr32.exe and ossl$libssl0101_shr32.exe
1262	instead, and when built for 64-bit pointers, they are named
1263	ossl$libcrypto0101_shr64.exe and ossl$libssl0101_shr64.exe.
1264
1265	Note on random number generation
1266	--------------------------------
1267
1268	Availability of cryptographically secure random numbers is required for
1269	secret key generation. OpenSSL provides several options to seed the
1270	internal CSPRNG. If not properly seeded, the internal CSPRNG will refuse
1271	to deliver random bytes and a "PRNG not seeded error" will occur.
1272
1273	The seeding method can be configured using the --with-rand-seed option,
1274	which can be used to specify a comma separated list of seed methods.
1275	However in most cases OpenSSL will choose a suitable default method,
1276	so it is not necessary to explicitly provide this option. Note also
1277	that not all methods are available on all platforms.
1278
1279	I) On operating systems which provide a suitable randomness source (in
1280	form of a system call or system device), OpenSSL will use the optimal
1281	available method to seed the CSPRNG from the operating system's
1282	randomness sources. This corresponds to the option --with-rand-seed=os.
1283
1284	II) On systems without such a suitable randomness source, automatic seeding
1285	and reseeding is disabled (--with-rand-seed=none) and it may be necessary
1286	to install additional support software to obtain a random seed and reseed
1287	the CSPRNG manually. Please check out the manual pages for RAND_add(),
1288	RAND_bytes(), RAND_egd(), and the FAQ for more information.

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/libs/openssl-1.1.1h/INSTALL@ 86560

Download in other formats: