Check more return values in the SRP code
[openssl.git] / INSTALL
diff --git a/INSTALL b/INSTALL
index c0163a9..3570dea 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -2,7 +2,8 @@
  --------------------
 
  This document describes installation on all supported operating
- systems (the Linux/Unix family, OpenVMS and Windows)
+ systems (the Unix/Linux family (which includes Mac OS/X), OpenVMS,
+ and Windows).
 
  To install OpenSSL, you will need:
 
@@ -76,7 +77,7 @@
 
  If you want to just get on with it, do:
 
-  on Unix:
+  on Unix (again, this includes Mac OS/X):
 
     $ ./config
     $ make
                    put together one-size-fits-all instructions. You might
                    have to pass more flags or set up environment variables
                    to actually make it work. Android and iOS cases are
-                   discussed in corresponding Configurations/10-main.cf
-                   sections. But there are cases when this option alone is
+                   discussed in corresponding Configurations/15-*.conf
+                   files. But there are cases when this option alone is
                    sufficient. For example to build the mingw64 target on
                    Linux "--cross-compile-prefix=x86_64-w64-mingw32-"
                    works. Naturally provided that mingw packages are
                    "--cross-compile-prefix=mipsel-linux-gnu-" suffices
                    in such case. Needless to mention that you have to
                    invoke ./Configure, not ./config, and pass your target
-                   name explicitly.
+                   name explicitly. Also, note that --openssldir refers
+                   to target's file system, not one you are building on.
 
   --debug
-                   Build OpenSSL with debugging symbols.
+                   Build OpenSSL with debugging symbols and zero optimization
+                   level.
 
   --libdir=DIR
                    The name of the directory under the top of the installation
                    os:         Use a trusted operating system entropy source.
                                This is the default method if such an entropy
                                source exists.
-                   getrandom:  Use the L<getrandom(2)> system call if available.
+                   getrandom:  Use the L<getrandom(2)> or equivalent system
+                               call.
                    devrandom:  Use the the first device from the DEVRANDOM list
                                which can be opened to read random bytes. The
                                DEVRANDOM preprocessor constant expands to
                    no-shared option.
 
   no-asm
-                   Do not use assembler code. On some platforms a small amount
-                   of assembler code may still be used.
+                   Do not use assembler code. This should be viewed as
+                   debugging/trouble-shooting option rather than production.
+                   On some platforms a small amount of assembler code may
+                   still be used even with this option.
 
   no-async
                    Do not build support for async operations.
                    Don't build support for datagram based BIOs. Selecting this
                    option will also force the disabling of DTLS.
 
+  enable-devcryptoeng
+                   Build the /dev/crypto engine.  It is automatically selected
+                   on BSD implementations, in which case it can be disabled with
+                   no-devcryptoeng.
+
   no-dso
                    Don't build support for loading Dynamic Shared Objects.
 
 
   enable-ec_nistp_64_gcc_128
                    Enable support for optimised implementations of some commonly
-                   used NIST elliptic curves. This is only supported on some
-                   platforms.
+                   used NIST elliptic curves.
+                   This is only supported on platforms:
+                   - with little-endian storage of non-byte types
+                   - that tolerate misaligned memory references
+                   - where the compiler:
+                     - supports the non-standard type __uint128_t
+                     - defines the built-in macro __SIZEOF_INT128__
 
   enable-egd
                    Build support for gathering entropy from EGD (Entropy
   no-pic
                    Don't build with support for Position Independent Code.
 
+  no-pinshared     By default OpenSSL will attempt to stay in memory until the
+                   process exits. This is so that libcrypto and libssl can be
+                   properly cleaned up automatically via an "atexit()" handler.
+                   The handler is registered by libcrypto and cleans up both
+                   libraries. On some platforms the atexit() handler will run on
+                   unload of libcrypto (if it has been dynamically loaded)
+                   rather than at process exit. This option can be used to stop
+                   OpenSSL from attempting to stay in memory until the process
+                   exits. This could lead to crashes if either libcrypto or
+                   libssl have already been unloaded at the point
+                   that the atexit handler is invoked, e.g. on a platform which
+                   calls atexit() on unload of the library, and libssl is
+                   unloaded before libcrypto then a crash is likely to happen.
+                   Applications can suppress running of the atexit() handler at
+                   run time by using the OPENSSL_INIT_NO_ATEXIT option to
+                   OPENSSL_init_crypto(). See the man page for it for further
+                   details.
+
   no-posix-io
                    Don't use POSIX IO capabilities.
 
                    require additional system-dependent options! See "Note on
                    multi-threading" below.
 
-  enable-tls13downgrade
-                   TODO(TLS1.3): Make this enabled by default and remove the
-                   option when TLSv1.3 is out of draft
-                   TLSv1.3 offers a downgrade protection mechanism. This is
-                   implemented but disabled by default. It should not typically
-                   be enabled except for testing purposes. Otherwise this could
-                   cause problems if a pre-RFC version of OpenSSL talks to an
-                   RFC implementation (it will erroneously be detected as a
-                   downgrade).
-
   no-ts
                    Don't build Time Stamping Authority support.
 
                    Build without support for the specified algorithm, where
                    <alg> is one of: aria, bf, blake2, camellia, cast, chacha,
                    cmac, des, dh, dsa, ecdh, ecdsa, idea, md4, mdc2, ocb,
-                   poly1305, rc2, rc4, rmd160, scrypt, seed, siphash, sm3, sm4
-                   or whirlpool.  The "ripemd" algorithm is deprecated and if
-                   used is synonymous with rmd160.
+                   poly1305, rc2, rc4, rmd160, scrypt, seed, siphash, sm2, sm3,
+                   sm4 or whirlpool.  The "ripemd" algorithm is deprecated and
+                   if used is synonymous with rmd160.
 
   -Dxxx, -Ixxx, -Wp, -lxxx, -Lxxx, -Wl, -rpath, -R, -framework, -static
                    These system specific options will be recognised and
                                    Windows, and as a comma separated list of
                                    libraries on VMS.
                    RANLIB          The library archive indexer.
-                   RC              The Windows resources manipulator.
-                   RCFLAGS         Flags for the Windows reources manipulator.
+                   RC              The Windows resource compiler.
+                   RCFLAGS         Flags for the Windows resource compiler.
                    RM              The command to remove files and directories.
 
                    These cannot be mixed with compiling / linking flags given
 
  BUILDFILE
                 Use a different build file name than the platform default
-                ("Makefile" on Unixly platforms, "makefile" on native Windows,
+                ("Makefile" on Unix-like platforms, "makefile" on native Windows,
                 "descrip.mms" on OpenVMS).  This requires that there is a
                 corresponding build file template.  See Configurations/README
                 for further information.
  part of the file name, i.e. for OpenSSL 1.1.x, 1.1 is somehow part of
  the name.
 
- On most POSIXly platforms, shared libraries are named libcrypto.so.1.1
+ On most POSIX platforms, shared libraries are named libcrypto.so.1.1
  and libssl.so.1.1.
 
  on Cygwin, shared libraries are named cygcrypto-1.1.dll and cygssl-1.1.dll
  The seeding method can be configured using the --with-rand-seed option,
  which can be used to specify a comma separated list of seed methods.
  However in most cases OpenSSL will choose a suitable default method,
- so it is not necessary to explicitely provide this option. Note also
+ so it is not necessary to explicitly provide this option. Note also
  that not all methods are available on all platforms.
 
  I) On operating systems which provide a suitable randomness source (in