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