Browse Source

Fix many MarkDown issues in {NOTES*,README*,HACKING,LICENSE}.md files

Reviewed-by: Tim Hudson <tjh@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/12109)
master
Dr. David von Oheimb 1 year ago
parent
commit
1dc1ea182b
28 changed files with 881 additions and 855 deletions
  1. +60
    -60
      CHANGES.md
  2. +7
    -4
      CONTRIBUTING.md
  3. +107
    -111
      Configurations/README-design.md
  4. +71
    -69
      Configurations/README.md
  5. +1
    -1
      Configure
  6. +18
    -11
      HACKING.md
  7. +12
    -12
      INSTALL.md
  8. +22
    -23
      NOTES-Android.md
  9. +17
    -19
      NOTES-DJGPP.md
  10. +27
    -23
      NOTES-Perl.md
  11. +29
    -32
      NOTES-Unix.md
  12. +13
    -19
      NOTES-VMS.md
  13. +18
    -16
      NOTES-Valgrind.md
  14. +178
    -157
      README-Engine.md
  15. +3
    -0
      README-FIPS.md
  16. +7
    -7
      README.md
  17. +0
    -7
      VERSION.txt
  18. +9
    -8
      crypto/README-sparse_array.md
  19. +13
    -14
      crypto/engine/README.md
  20. +12
    -12
      crypto/err/README.md
  21. +25
    -26
      crypto/objects/README.md
  22. +88
    -82
      crypto/perlasm/README.md
  23. +15
    -8
      crypto/property/README.md
  24. +1
    -1
      demos/README.txt
  25. +11
    -8
      doc/README.md
  26. +30
    -31
      ssl/record/README.md
  27. +48
    -48
      ssl/statem/README.md
  28. +39
    -46
      test/README-external.md

+ 60
- 60
CHANGES.md View File

@ -174,12 +174,12 @@ OpenSSL 3.0
*Richard Levitte*
* Project text documents not yet having a proper file name extension
(HACKING, LICENSE, NOTES*, README*, VERSION) have been renamed to *.md
as far as reasonable, else to *.txt, for better use with file managers.
(`HACKING`, `LICENSE`, `NOTES*`, `README*`, `VERSION`) have been renamed to
`*.md` as far as reasonable, else `*.txt`, for better use with file managers.
*David von Oheimb*
* The main project documents (README, NEWS, CHANGES, INSTALL, SUPPORT)
* The main project documents (README, NEWS, CHANGES, INSTALL, SUPPORT)
have been converted to Markdown with the goal to produce documents
which not only look pretty when viewed online in the browser, but
remain well readable inside a plain text editor.
@ -1060,7 +1060,7 @@ OpenSSL 3.0
* Added EVP_MAC, an EVP layer MAC API, to simplify adding MAC
implementations. This includes a generic EVP_PKEY to EVP_MAC bridge,
to facilitate the continued use of MACs through raw private keys in
functionality such as EVP_DigestSign* and EVP_DigestVerify*.
functionality such as `EVP_DigestSign*` and `EVP_DigestVerify*`.
*Richard Levitte*
@ -1732,9 +1732,9 @@ OpenSSL 1.1.1
*Paul Yang*
* Add SM3 implemented according to GB/T 32905-2016
* Jack Lloyd <jack.lloyd@ribose.com>,
Ronald Tse <ronald.tse@ribose.com>,
Erick Borsboom <erick.borsboom@ribose.com> *
*Jack Lloyd <jack.lloyd@ribose.com>,*
*Ronald Tse <ronald.tse@ribose.com>,*
*Erick Borsboom <erick.borsboom@ribose.com>*
* Add 'Maximum Fragment Length' TLS extension negotiation and support
as documented in RFC6066.
@ -1743,9 +1743,9 @@ OpenSSL 1.1.1
*Filipe Raimundo da Silva*
* Add SM4 implemented according to GB/T 32907-2016.
* Jack Lloyd <jack.lloyd@ribose.com>,
Ronald Tse <ronald.tse@ribose.com>,
Erick Borsboom <erick.borsboom@ribose.com> *
*Jack Lloyd <jack.lloyd@ribose.com>,*
*Ronald Tse <ronald.tse@ribose.com>,*
*Erick Borsboom <erick.borsboom@ribose.com>*
* Reimplement -newreq-nodes and ERR_error_string_n; the
original author does not agree with the license change.
@ -2931,7 +2931,7 @@ OpenSSL 1.1.0
Makefile. Instead, Configure produces a perl module in
configdata.pm which holds most of the config data (in the hash
table %config), the target data that comes from the target
configuration in one of the `Configurations/*.conf~ files (in
configuration in one of the `Configurations/*.conf` files (in
%target).
*Richard Levitte*
@ -3062,21 +3062,21 @@ OpenSSL 1.1.0
opaque. For HMAC_CTX, the following constructors and destructors
were added:
HMAC_CTX *HMAC_CTX_new(void);
void HMAC_CTX_free(HMAC_CTX *ctx);
HMAC_CTX *HMAC_CTX_new(void);
void HMAC_CTX_free(HMAC_CTX *ctx);
For EVP_MD and EVP_CIPHER, complete APIs to create, fill and
destroy such methods has been added. See EVP_MD_meth_new(3) and
EVP_CIPHER_meth_new(3) for documentation.
Additional changes:
1) EVP_MD_CTX_cleanup(), EVP_CIPHER_CTX_cleanup() and
HMAC_CTX_cleanup() were removed. HMAC_CTX_reset() and
EVP_MD_CTX_reset() should be called instead to reinitialise
1) `EVP_MD_CTX_cleanup()`, `EVP_CIPHER_CTX_cleanup()` and
`HMAC_CTX_cleanup()` were removed. `HMAC_CTX_reset()` and
`EVP_MD_CTX_reset()` should be called instead to reinitialise
an already created structure.
2) For consistency with the majority of our object creators and
destructors, EVP_MD_CTX_(create|destroy) were renamed to
EVP_MD_CTX_(new|free). The old names are retained as macros
destructors, `EVP_MD_CTX_(create|destroy)` were renamed to
`EVP_MD_CTX_(new|free)`. The old names are retained as macros
for deprecated builds.
*Richard Levitte*
@ -3174,8 +3174,8 @@ OpenSSL 1.1.0
*Emilia Käsper*
* Fix no-stdio build.
* David Woodhouse <David.Woodhouse@intel.com> and also
Ivan Nestlerode <ivan.nestlerode@sonos.com> *
*David Woodhouse <David.Woodhouse@intel.com> and also*
*Ivan Nestlerode <ivan.nestlerode@sonos.com>*
* New testing framework
The testing framework has been largely rewritten and is now using
@ -3579,7 +3579,7 @@ OpenSSL 1.1.0
*Steve Henson*
* Rename old X9.31 PRNG functions of the form FIPS_rand* to FIPS_x931*.
* Rename old X9.31 PRNG functions of the form `FIPS_rand*` to `FIPS_x931*`.
This shouldn't present any incompatibility problems because applications
shouldn't be using these directly and any that are will need to rethink
anyway as the X9.31 PRNG is now deprecated by FIPS 140-2
@ -4458,11 +4458,11 @@ OpenSSL 1.0.2
* Fix BN_hex2bn/BN_dec2bn NULL pointer deref/heap corruption
In the BN_hex2bn function the number of hex digits is calculated using an
int value |i|. Later |bn_expand| is called with a value of |i * 4|. For
large values of |i| this can result in |bn_expand| not allocating any
memory because |i * 4| is negative. This can leave the internal BIGNUM data
int value `i`. Later `bn_expand` is called with a value of `i * 4`. For
large values of `i` this can result in `bn_expand` not allocating any
memory because `i * 4` is negative. This can leave the internal BIGNUM data
field as NULL leading to a subsequent NULL ptr deref. For very large values
of |i|, the calculation |i * 4| could be a positive value smaller than |i|.
of `i`, the calculation `i * 4` could be a positive value smaller than `i`.
In this case memory is allocated to the internal BIGNUM data field, but it
is insufficiently sized leading to heap corruption. A similar issue exists
in BN_dec2bn. This could have security consequences if BN_hex2bn/BN_dec2bn
@ -4482,11 +4482,11 @@ OpenSSL 1.0.2
* Fix memory issues in `BIO_*printf` functions
The internal |fmtstr| function used in processing a "%s" format string in
The internal `fmtstr` function used in processing a "%s" format string in
the `BIO_*printf` functions could overflow while calculating the length of a
string and cause an OOB read when printing very long strings.
Additionally the internal |doapr_outch| function can attempt to write to an
Additionally the internal `doapr_outch` function can attempt to write to an
OOB memory location (at an offset from the NULL pointer) in the event of a
memory allocation failure. In 1.0.2 and below this could be caused where
the size of a buffer to be allocated is greater than INT_MAX. E.g. this
@ -5660,11 +5660,11 @@ OpenSSL 1.0.1
* Fix BN_hex2bn/BN_dec2bn NULL pointer deref/heap corruption
In the BN_hex2bn function the number of hex digits is calculated using an
int value |i|. Later |bn_expand| is called with a value of |i * 4|. For
large values of |i| this can result in |bn_expand| not allocating any
memory because |i * 4| is negative. This can leave the internal BIGNUM data
int value `i`. Later `bn_expand` is called with a value of `i * 4`. For
large values of `i` this can result in `bn_expand` not allocating any
memory because `i * 4` is negative. This can leave the internal BIGNUM data
field as NULL leading to a subsequent NULL ptr deref. For very large values
of |i|, the calculation |i * 4| could be a positive value smaller than |i|.
of `i`, the calculation `i * 4` could be a positive value smaller than `i`.
In this case memory is allocated to the internal BIGNUM data field, but it
is insufficiently sized leading to heap corruption. A similar issue exists
in BN_dec2bn. This could have security consequences if BN_hex2bn/BN_dec2bn
@ -5684,11 +5684,11 @@ OpenSSL 1.0.1
* Fix memory issues in `BIO_*printf` functions
The internal |fmtstr| function used in processing a "%s" format string in
The internal `fmtstr` function used in processing a "%s" format string in
the `BIO_*printf` functions could overflow while calculating the length of a
string and cause an OOB read when printing very long strings.
Additionally the internal |doapr_outch| function can attempt to write to an
Additionally the internal `doapr_outch` function can attempt to write to an
OOB memory location (at an offset from the NULL pointer) in the event of a
memory allocation failure. In 1.0.2 and below this could be caused where
the size of a buffer to be allocated is greater than INT_MAX. E.g. this
@ -6505,8 +6505,8 @@ OpenSSL 1.0.1
disable just protocol X, but all protocols above X *if* there are
protocols *below* X still enabled. In more practical terms it means
that if application wants to disable TLS1.0 in favor of TLS1.1 and
above, it's not sufficient to pass SSL_OP_NO_TLSv1, one has to pass
SSL_OP_NO_TLSv1|SSL_OP_NO_SSLv3|SSL_OP_NO_SSLv2. This applies to
above, it's not sufficient to pass `SSL_OP_NO_TLSv1`, one has to pass
`SSL_OP_NO_TLSv1|SSL_OP_NO_SSLv3|SSL_OP_NO_SSLv2`. This applies to
client side.
*Andy Polyakov*
@ -12328,8 +12328,8 @@ s-cbc 3624.96k 5258.21k 5530.91k 5624.30k 5628.26k
*Geoff Thorpe, Lutz Jaenicke*
* Modify mkdef.pl to recognise and parse preprocessor conditionals
of the form '#if defined(...) || defined(...) || ...' and
'#if !defined(...) && !defined(...) && ...'. This also avoids
of the form `#if defined(...) || defined(...) || ...` and
`#if !defined(...) && !defined(...) && ...`. This also avoids
the growing number of special cases it was previously handling.
*Richard Levitte*
@ -12902,9 +12902,9 @@ s-cbc 3624.96k 5258.21k 5530.91k 5624.30k 5628.26k
*Bodo Moeller*
* Move `BN_mod_...` functions into new file crypto/bn/bn_mod.c
(except for exponentiation, which stays in crypto/bn/bn_exp.c,
and BN_mod_mul_reciprocal, which stays in crypto/bn/bn_recp.c)
* Move `BN_mod_...` functions into new file `crypto/bn/bn_mod.c`
(except for exponentiation, which stays in `crypto/bn/bn_exp.c`,
and `BN_mod_mul_reciprocal`, which stays in `crypto/bn/bn_recp.c`)
and add new functions:
BN_nnmod
@ -12920,16 +12920,16 @@ s-cbc 3624.96k 5258.21k 5530.91k 5624.30k 5628.26k
These functions always generate non-negative results.
BN_nnmod otherwise is like BN_mod (if BN_mod computes a remainder r
such that |m| < r < 0, BN_nnmod will output rem + |m| instead).
`BN_nnmod` otherwise is `like BN_mod` (if `BN_mod` computes a remainder `r`
such that `|m| < r < 0`, `BN_nnmod` will output `rem + |m|` instead).
BN_mod_XXX_quick(r, a, [b,] m) generates the same result as
BN_mod_XXX(r, a, [b,] m, ctx), but requires that a [and b]
be reduced modulo m.
`BN_mod_XXX_quick(r, a, [b,] m)` generates the same result as
`BN_mod_XXX(r, a, [b,] m, ctx)`, but requires that `a` [and `b`]
be reduced modulo `m`.
*Lenka Fibikova <fibikova@exp-math.uni-essen.de>, Bodo Moeller*
f 0
<!--
The following entry accidentally appeared in the CHANGES file
distributed with OpenSSL 0.9.7. The modifications described in
it do *not* apply to OpenSSL 0.9.7.
@ -12943,7 +12943,7 @@ f 0
differing sizes.
*Richard Levitte*
ndif
-->
* In 'openssl passwd', verify passwords read from the terminal
unless the '-salt' option is used (which usually means that
@ -14683,7 +14683,7 @@ ndif
* Change the handling of OID objects as follows:
- New object identifiers are inserted in objects.txt, following
the syntax given in objects.README.
the syntax given in [crypto/objects/README.md](crypto/objects/README.md).
- objects.pl is used to process obj_mac.num and create a new
obj_mac.h.
- obj_dat.pl is used to create a new obj_dat.h, using the data in
@ -17399,10 +17399,10 @@ ndif
*Steve Henson*
* Be less restrictive and allow also `perl util/perlpath.pl
/path/to/bin/perl' in addition to `perl util/perlpath.pl /path/to/bin',
because this way one can also use an interpreter named `perl5' (which is
/path/to/bin/perl` in addition to `perl util/perlpath.pl /path/to/bin`,
because this way one can also use an interpreter named `perl5` (which is
usually the name of Perl 5.xxx on platforms where an Perl 4.x is still
installed as `perl').
installed as `perl`).
*Matthias Loepfe <Matthias.Loepfe@adnovum.ch>*
@ -17435,7 +17435,7 @@ ndif
*Steve Henson*
* Make `openssl version' output lines consistent.
* Make `openssl version` output lines consistent.
*Ralf S. Engelschall*
@ -17492,7 +17492,7 @@ ndif
*Ben Laurie*
* Allow DSO flags like -fpic, -fPIC, -KPIC etc. to be specified
on the `perl Configure ...' command line. This way one can compile
on the `perl Configure ...` command line. This way one can compile
OpenSSL libraries with Position Independent Code (PIC) which is needed
for linking it into DSOs.
@ -17511,9 +17511,9 @@ ndif
*Ralf S. Engelschall*
* General source tree makefile cleanups: Made `making xxx in yyy...'
display consistent in the source tree and replaced `/bin/rm' by `rm'.
Additionally cleaned up the `make links' target: Remove unnecessary
* General source tree makefile cleanups: Made `making xxx in yyy...`
display consistent in the source tree and replaced `/bin/rm` by `rm`.
Additionally cleaned up the `make links` target: Remove unnecessary
semicolons, subsequent redundant removes, inline point.sh into mklink.sh
to speed processing and no longer clutter the display with confusing
stuff. Instead only the actually done links are displayed.
@ -17640,12 +17640,12 @@ ndif
*Ralf S. Engelschall*
* Make `openssl x509 -noout -modulus' functional also for DSA certificates
* Make `openssl x509 -noout -modulus`' functional also for DSA certificates
(in addition to RSA certificates) to match the behaviour of `openssl dsa
-noout -modulus' as it's already the case for `openssl rsa -noout
-modulus'. For RSA the -modulus is the real "modulus" while for DSA
-noout -modulus` as it's already the case for `openssl rsa -noout
-modulus`. For RSA the -modulus is the real "modulus" while for DSA
currently the public key is printed (a decision which was already done by
`openssl dsa -modulus' in the past) which serves a similar purpose.
`openssl dsa -modulus` in the past) which serves a similar purpose.
Additionally the NO_RSA no longer completely removes the whole -modulus
option; it now only avoids using the RSA stuff. Same applies to NO_DSA
now, too.


+ 7
- 4
CONTRIBUTING.md View File

@ -54,8 +54,8 @@ guidelines:
(usually by rebasing) before it will be acceptable.
4. Patches should follow our [coding style][] and compile without warnings.
Where gcc or clang is available you should use the
--strict-warnings Configure option. OpenSSL compiles on many varied
Where `gcc` or `clang` is available you should use the
`--strict-warnings` `Configure` option. OpenSSL compiles on many varied
platforms: try to ensure you only use portable features. Clean builds
via Travis and AppVeyor are required, and they are started automatically
whenever a PR is created or updated.
@ -64,7 +64,7 @@ guidelines:
5. When at all possible, patches should include tests. These can
either be added to an existing test, or completely new. Please see
test/README.md for information on the test framework.
[test/README.md](test/README.md) for information on the test framework.
6. New features or changed functionality must include
documentation. Please look at the "pod" files in doc/man[1357] for
@ -77,7 +77,7 @@ guidelines:
explain the grander details.
Have a look through existing entries for inspiration.
Please note that this is NOT simply a copy of git-log one-liners.
Also note that security fixes get an entry in CHANGES.md.
Also note that security fixes get an entry in [CHANGES.md](CHANGES.md).
This file helps users get more in depth information of what comes
with a specific release without having to sift through the higher
noise ratio in git-log.
@ -89,3 +89,6 @@ guidelines:
OpenSSL 1.1.0).
This file helps users get a very quick summary of what comes with a
specific release, to see if an upgrade is worth the effort.
9. Guidelines how to integrate error output of new crypto library modules
can be found in [crypto/err/README.md](crypto/err/README.md).

+ 107
- 111
Configurations/README-design.md View File

@ -4,17 +4,17 @@ Design document for the unified scheme data
How are things connected?
-------------------------
The unified scheme takes all its data from the build.info files seen
The unified scheme takes all its data from the `build.info` files seen
throughout the source tree. These files hold the minimum information
needed to build end product files from diverse sources. See the
section on build.info files below.
section on `build.info` files below.
From the information in build.info files, Configure builds up an
information database as a hash table called %unified_info, which is
From the information in `build.info` files, `Configure` builds up an
information database as a hash table called `%unified_info`, which is
stored in configdata.pm, found at the top of the build tree (which may
or may not be the same as the source tree).
Configurations/common.tmpl uses the data from %unified_info to
[`Configurations/common.tmpl`](common.tmpl) uses the data from `%unified_info` to
generate the rules for building end product files as well as
intermediary files with the help of a few functions found in the
build-file templates. See the section on build-file templates further
@ -23,36 +23,35 @@ down for more information.
build.info files
----------------
As mentioned earlier, build.info files are meant to hold the minimum
As mentioned earlier, `build.info` files are meant to hold the minimum
information needed to build output files, and therefore only (with a
few possible exceptions [1]) have information about end products (such
as scripts, library files and programs) and source files (such as C
files, C header files, assembler files, etc). Intermediate files such
as object files are rarely directly referred to in build.info files (and
when they are, it's always with the file name extension .o), they are
inferred by Configure. By the same rule of minimalism, end product
file name extensions (such as .so, .a, .exe, etc) are never mentioned
in build.info. Their file name extensions will be inferred by the
as object files are rarely directly referred to in `build.info` files (and
when they are, it's always with the file name extension `.o`), they are
inferred by `Configure`. By the same rule of minimalism, end product
file name extensions (such as `.so`, `.a`, `.exe`, etc) are never mentioned
in `build.info`. Their file name extensions will be inferred by the
build-file templates, adapted for the platform they are meant for (see
sections on %unified_info and build-file templates further down).
sections on `%unified_info` and build-file templates further down).
The variables PROGRAMS, LIBS, MODULES and SCRIPTS are used to declare
end products. There are variants for them with '_NO_INST' as suffix
(PROGRAM_NO_INST etc) to specify end products that shouldn't get
installed.
The variables `PROGRAMS`, `LIBS`, `MODULES` and `SCRIPTS` are used to declare
end products. There are variants for them with `_NO_INST` as suffix
(`PROGRAM_NO_INST` etc) to specify end products that shouldn't get installed.
The variables SOURCE, DEPEND, INCLUDE and DEFINE are indexed by a
The variables `SOURCE`, `DEPEND`, `INCLUDE` and `DEFINE` are indexed by a
produced file, and their values are the source used to produce that
particular produced file, extra dependencies, include directories
needed, or C macros to be defined.
All their values in all the build.info throughout the source tree are
All their values in all the `build.info` throughout the source tree are
collected together and form a set of programs, libraries, modules and
scripts to be produced, source files, dependencies, etc etc etc.
Let's have a pretend example, a very limited contraption of OpenSSL,
composed of the program 'apps/openssl', the libraries 'libssl' and
'libcrypto', an module 'engines/ossltest' and their sources and
composed of the program `apps/openssl`, the libraries `libssl` and
`libcrypto`, an module `engines/ossltest` and their sources and
dependencies.
# build.info
@ -61,11 +60,11 @@ dependencies.
INCLUDE[libssl]=include
DEPEND[libssl]=libcrypto
This is the top directory build.info file, and it tells us that two
libraries are to be built, the include directory 'include/' shall be
This is the top directory `build.info` file, and it tells us that two
libraries are to be built, the include directory `include/` shall be
used throughout when building anything that will end up in each
library, and that the library 'libssl' depend on the library
'libcrypto' to function properly.
library, and that the library `libssl` depend on the library
`libcrypto` to function properly.
# apps/build.info
PROGRAMS=openssl
@ -73,15 +72,15 @@ library, and that the library 'libssl' depend on the library
INCLUDE[openssl]=.. ../include
DEPEND[openssl]=../libssl
This is the build.info file in 'apps/', one may notice that all file
paths mentioned are relative to the directory the build.info file is
This is the `build.info` file in `apps/`, one may notice that all file
paths mentioned are relative to the directory the `build.info` file is
located in. This one tells us that there's a program to be built
called 'apps/openssl' (the file name extension will depend on the
platform and is therefore not mentioned in the build.info file). It's
built from one source file, 'apps/openssl.c', and building it requires
the use of '.' and 'include' include directories (both are declared
from the point of view of the 'apps/' directory), and that the program
depends on the library 'libssl' to function properly.
called `apps/openss` (the file name extension will depend on the
platform and is therefore not mentioned in the `build.info` file). It's
built from one source file, `apps/openssl.c`, and building it requires
the use of `.` and `include/` include directories (both are declared
from the point of view of the `apps/` directory), and that the program
depends on the library `libssl` to function properly.
# crypto/build.info
LIBS=../libcrypto
@ -92,32 +91,32 @@ depends on the library 'libssl' to function properly.
DEPEND[buildinf.h]=../Makefile
DEPEND[../util/mkbuildinf.pl]=../util/Foo.pm
This is the build.info file in 'crypto', and it tells us a little more
about what's needed to produce 'libcrypto'. LIBS is used again to
declare that 'libcrypto' is to be produced. This declaration is
really unnecessary as it's already mentioned in the top build.info
This is the `build.info` file in `crypto/`, and it tells us a little more
about what's needed to produce `libcrypto`. LIBS is used again to
declare that `libcrypto` is to be produced. This declaration is
really unnecessary as it's already mentioned in the top `build.info`
file, but can make the info file easier to understand. This is to
show that duplicate information isn't an issue.
This build.info file informs us that 'libcrypto' is built from a few
source files, 'crypto/aes.c', 'crypto/evp.c' and 'crypto/cversion.c'.
This `build.info` file informs us that `libcrypto` is built from a few
source files, `crypto/aes.c`, `crypto/evp.c` and `crypto/cversion.c`.
It also shows us that building the object file inferred from
'crypto/cversion.c' depends on 'crypto/buildinf.h'. Finally, it
`crypto/cversion.c` depends on `crypto/buildinf.h`. Finally, it
also shows the possibility to declare how some files are generated
using some script, in this case a perl script, and how such scripts
can be declared to depend on other files, in this case a perl module.
Two things are worth an extra note:
'DEPEND[cversion.o]' mentions an object file. DEPEND indexes is the
`DEPEND[cversion.o]` mentions an object file. DEPEND indexes is the
only location where it's valid to mention them
# ssl/build.info
LIBS=../libssl
SOURCE[../libssl]=tls.c
This is the build.info file in 'ssl/', and it tells us that the
library 'libssl' is built from the source file 'ssl/tls.c'.
This is the build.info file in `ssl/`, and it tells us that the
library `libssl` is built from the source file `ssl/tls.c`.
# engines/build.info
MODULES=dasync
@ -130,17 +129,17 @@ library 'libssl' is built from the source file 'ssl/tls.c'.
DEPEND[ossltest]=../libcrypto.a
INCLUDE[ossltest]=../include
This is the build.info file in 'engines/', telling us that two modules
called 'engines/dasync' and 'engines/ossltest' shall be built, that
dasync's source is 'engines/e_dasync.c' and ossltest's source is
'engines/e_ossltest.c' and that the include directory 'include/' may
This is the `build.info` file in `engines/`, telling us that two modules
called `engines/dasync` and `engines/ossltest` shall be built, that
`dasync`'s source is `engines/e_dasync.c` and `ossltest`'s source is
`engines/e_ossltest.c` and that the include directory `include/` may
be used when building anything that will be part of these modules.
Also, both modules depend on the library 'libcrypto' to function
properly. ossltest is explicitly linked with the static variant of
the library 'libcrypto'. Finally, only dasync is being installed, as
ossltest is only for internal testing.
Also, both modules depend on the library `libcrypto` to function
properly. `ossltest` is explicitly linked with the static variant of
the library `libcrypto`. Finally, only `dasync` is being installed, as
`ossltest` is only for internal testing.
When Configure digests these build.info files, the accumulated
When `Configure` digests these `build.info` files, the accumulated
information comes down to this:
LIBS=libcrypto libssl
@ -170,83 +169,81 @@ information comes down to this:
DEPEND[crypto/buildinf.h]=Makefile
DEPEND[util/mkbuildinf.pl]=util/Foo.pm
A few notes worth mentioning:
LIBS may be used to declare routine libraries only.
`LIBS` may be used to declare routine libraries only.
PROGRAMS may be used to declare programs only.
`PROGRAMS` may be used to declare programs only.
MODULES may be used to declare modules only.
`MODULES` may be used to declare modules only.
The indexes for SOURCE must only be end product files, such as
libraries, programs or modules. The values of SOURCE variables must
The indexes for `SOURCE` must only be end product files, such as
libraries, programs or modules. The values of `SOURCE` variables must
only be source files (possibly generated).
INCLUDE and DEPEND shows a relationship between different files
`INCLUDE` and `DEPEND` shows a relationship between different files
(usually produced files) or between files and directories, such as a
program depending on a library, or between an object file and some
extra source file.
When Configure processes the build.info files, it will take it as
When `Configure` processes the `build.info` files, it will take it as
truth without question, and will therefore perform very few checks.
If the build tree is separate from the source tree, it will assume
that all built files and up in the build directory and that all source
files are to be found in the source tree, if they can be found there.
Configure will assume that source files that can't be found in the
source tree (such as 'crypto/bildinf.h' in the example above) are
`Configure` will assume that source files that can't be found in the
source tree (such as `crypto/bildinf.h` in the example above) are
generated and will be found in the build tree.
The `%unified_info` database
----------------------------
The %unified_info database
--------------------------
The information in all the build.info get digested by Configure and
collected into the %unified_info database, divided into the following
The information in all the `build.info` get digested by `Configure` and
collected into the `%unified_info` database, divided into the following
indexes:
depends => a hash table containing 'file' => [ 'dependency' ... ]
pairs. These are directly inferred from the DEPEND
variables in build.info files.
depends => a hash table containing 'file' => [ 'dependency' ... ]
pairs. These are directly inferred from the DEPEND
variables in build.info files.
modules => a list of modules. These are directly inferred from
the MODULES variable in build.info files.
modules => a list of modules. These are directly inferred from
the MODULES variable in build.info files.
generate => a hash table containing 'file' => [ 'generator' ... ]
pairs. These are directly inferred from the GENERATE
variables in build.info files.
generate => a hash table containing 'file' => [ 'generator' ... ]
pairs. These are directly inferred from the GENERATE
variables in build.info files.
includes => a hash table containing 'file' => [ 'include' ... ]
pairs. These are directly inferred from the INCLUDE
variables in build.info files.
includes => a hash table containing 'file' => [ 'include' ... ]
pairs. These are directly inferred from the INCLUDE
variables in build.info files.
install => a hash table containing 'type' => [ 'file' ... ] pairs.
The types are 'programs', 'libraries', 'modules' and
'scripts', and the array of files list the files of
that type that should be installed.
install => a hash table containing 'type' => [ 'file' ... ] pairs.
The types are 'programs', 'libraries', 'modules' and
'scripts', and the array of files list the files of
that type that should be installed.
libraries => a list of libraries. These are directly inferred from
the LIBS variable in build.info files.
libraries => a list of libraries. These are directly inferred from
the LIBS variable in build.info files.
programs => a list of programs. These are directly inferred from
the PROGRAMS variable in build.info files.
programs => a list of programs. These are directly inferred from
the PROGRAMS variable in build.info files.
scripts => a list of scripts. There are directly inferred from
the SCRIPTS variable in build.info files.
scripts => a list of scripts. There are directly inferred from
the SCRIPTS variable in build.info files.
sources => a hash table containing 'file' => [ 'sourcefile' ... ]
pairs. These are indirectly inferred from the SOURCE
variables in build.info files. Object files are
mentioned in this hash table, with source files from
SOURCE variables, and AS source files for programs and
libraries.
sources => a hash table containing 'file' => [ 'sourcefile' ... ]
pairs. These are indirectly inferred from the SOURCE
variables in build.info files. Object files are
mentioned in this hash table, with source files from
SOURCE variables, and AS source files for programs and
libraries.
shared_sources =>
a hash table just like 'sources', but only as source
files (object files) for building shared libraries.
shared_sources =>
a hash table just like 'sources', but only as source
files (object files) for building shared libraries.
As an example, here is how the build.info files example from the
section above would be digested into a %unified_info table:
As an example, here is how the `build.info` files example from the
section above would be digested into a `%unified_info` table:
our %unified_info = (
"depends" =>
@ -399,20 +396,19 @@ section above would be digested into a %unified_info table:
},
);
As can be seen, everything in %unified_info is fairly simple suggest
As can be seen, everything in `%unified_info` is fairly simple suggest
of information. Still, it tells us that to build all programs, we
must build 'apps/openssl', and to build the latter, we will need to
build all its sources ('apps/openssl.o' in this case) and all the
other things it depends on (such as 'libssl'). All those dependencies
need to be built as well, using the same logic, so to build 'libssl',
we need to build 'ssl/tls.o' as well as 'libcrypto', and to build the
must build `apps/openssl`, and to build the latter, we will need to
build all its sources (`apps/openssl.o` in this case) and all the
other things it depends on (such as `libssl`). All those dependencies
need to be built as well, using the same logic, so to build `libssl`,
we need to build `ssl/tls.o` as well as `libcrypto`, and to build the
latter...
Build-file templates
--------------------
Build-file templates are essentially build-files (such as Makefile on
Build-file templates are essentially build-files (such as `Makefile` on
Unix) with perl code fragments mixed in. Those perl code fragment
will generate all the configuration dependent data, including all the
rules needed to build end product files and intermediary files alike.
@ -461,7 +457,7 @@ etc.
incs => [ "INCL/PATH", ... ]
intent => one of "lib", "dso", "bin" );
'obj' has the intended object file with '.o'
'obj' has the intended object file with `.o`
extension, src2obj() is expected to change it to
something more suitable for the platform.
'srcs' has the list of source files to build the
@ -557,13 +553,13 @@ etc.
resulting script from.
Along with the build-file templates is the driving template
Configurations/common.tmpl, which looks through all the information in
%unified_info and generates all the rulesets to build libraries,
[`Configurations/common.tmpl`](common.tmpl), which looks through all the
information in `%unified_info` and generates all the rulesets to build libraries,
programs and all intermediate files, using the rule generating
functions defined in the build-file template.
As an example with the smaller build.info set we've seen as an
example, producing the rules to build 'libcrypto' would result in the
As an example with the smaller `build.info` set we've seen as an
example, producing the rules to build `libcrypto` would result in the
following calls:
# Note: obj2shlib will only be called if shared libraries are


+ 71
- 69
Configurations/README.md View File

@ -14,7 +14,6 @@ configuration in diverse ways:
script. See 'Configure helper scripts for more
information.
Configurations of OpenSSL target platforms
==========================================
@ -54,12 +53,12 @@ In each table entry, the following keys are significant:
usually good enough.
cppflags => Default C preprocessor flags [4].
defines => As an alternative, macro definitions may be
given here instead of in `cppflags' [4].
given here instead of in 'cppflags' [4].
If given here, they MUST be as an array of
the string such as "MACRO=value", or just
"MACRO" for definitions without value.
includes => As an alternative, inclusion directories
may be given here instead of in `cppflags'
may be given here instead of in 'cppflags'
[4]. If given here, the MUST be an array
of strings, one directory specification
each.
@ -99,9 +98,9 @@ In each table entry, the following keys are significant:
module_cppflags
module_cflags
module_ldflags => Has the same function as the corresponding
`shared_' attributes, but for building DSOs.
'shared_' attributes, but for building DSOs.
When unset, they get the same values as the
corresponding `shared_' attributes.
corresponding 'shared_' attributes.
ar => The library archive command, the default is
"ar".
@ -237,31 +236,30 @@ In each table entry, the following keys are significant:
RC4_INT RC4 key schedule is made
up of 'unsigned int's;
[1] as part of the target configuration, one can have a key called
'inherit_from' that indicate what other configurations to inherit
data from. These are resolved recursively.
`inherit_from` that indicates what other configurations to inherit
data from. These are resolved recursively.
Inheritance works as a set of default values that can be overridden
by corresponding key values in the inheriting configuration.
Inheritance works as a set of default values that can be overridden
by corresponding key values in the inheriting configuration.
Note 1: any configuration table can be used as a template.
Note 2: pure templates have the attribute 'template => 1' and
cannot be used as build targets.
Note 1: any configuration table can be used as a template.
Note 2: pure templates have the attribute `template => 1` and
cannot be used as build targets.
If several configurations are given in the 'inherit_from' array,
the values of same attribute are concatenated with space
separation. With this, it's possible to have several smaller
templates for different configuration aspects that can be combined
into a complete configuration.
If several configurations are given in the `inherit_from` array,
the values of same attribute are concatenated with space
separation. With this, it's possible to have several smaller
templates for different configuration aspects that can be combined
into a complete configuration.
instead of a scalar value or an array, a value can be a code block
of the form 'sub { /* your code here */ }'. This code block will
be called with the list of inherited values for that key as
arguments. In fact, the concatenation of strings is really done
by using 'sub { join(" ",@_) }' on the list of inherited values.
Instead of a scalar value or an array, a value can be a code block
of the form `sub { /* your code here */ }`. This code block will
be called with the list of inherited values for that key as
arguments. In fact, the concatenation of strings is really done
by using `sub { join(" ",@_) }` on the list of inherited values.
An example:
An example:
"foo" => {
template => 1,
@ -291,21 +289,21 @@ In each table entry, the following keys are significant:
}
[2] OpenSSL is built with threading capabilities unless the user
specifies 'no-threads'. The value of the key 'thread_scheme' may
be "(unknown)", in which case the user MUST give some compilation
flags to Configure.
specifies `no-threads`. The value of the key `thread_scheme` may
be `(unknown)`, in which case the user MUST give some compilation
flags to `Configure`.
[3] OpenSSL has three types of things to link from object files or
static libraries:
static libraries:
- shared libraries; that would be libcrypto and libssl.
- shared objects (sometimes called dynamic libraries); that would
be the modules.
- applications; those are apps/openssl and all the test apps.
- shared libraries; that would be libcrypto and libssl.
- shared objects (sometimes called dynamic libraries); that would
be the modules.
- applications; those are apps/openssl and all the test apps.
Very roughly speaking, linking is done like this (words in braces
represent the configuration settings documented at the beginning
of this file):
Very roughly speaking, linking is done like this (words in braces
represent the configuration settings documented at the beginning
of this file):
shared libraries:
{ld} $(CFLAGS) {lflags} {shared_ldflag} -o libfoo.so \
@ -319,38 +317,43 @@ In each table entry, the following keys are significant:
{ld} $(CFLAGS) {lflags} -o app \
app1.o utils.o -lssl -lcrypto {ex_libs}
[4] There are variants of these attribute, prefixed with `lib_',
`dso_' or `bin_'. Those variants replace the unprefixed attribute
when building library, DSO or program modules specifically.
[4] There are variants of these attribute, prefixed with `lib_`,
`dso_` or `bin_`. Those variants replace the unprefixed attribute
when building library, DSO or program modules specifically.
Historically, the target configurations came in form of a string with
values separated by colons. This use is deprecated. The string form
looked like this:
"target" => "{cc}:{cflags}:{unistd}:{thread_cflag}:{sys_id}:{lflags}:{bn_ops}:{cpuid_obj}:{bn_obj}:{ec_obj}:{des_obj}:{aes_obj}:{bf_obj}:{md5_obj}:{sha1_obj}:{cast_obj}:{rc4_obj}:{rmd160_obj}:{rc5_obj}:{wp_obj}:{cmll_obj}:{modes_obj}:{padlock_obj}:{perlasm_scheme}:{dso_scheme}:{shared_target}:{shared_cflag}:{shared_ldflag}:{shared_extension}:{ranlib}:{arflags}:{multilib}"
"target" => "{cc}:{cflags}:{unistd}:{thread_cflag}:{sys_id}:{lflags}:
{bn_ops}:{cpuid_obj}:{bn_obj}:{ec_obj}:{des_obj}:{aes_obj}:
{bf_obj}:{md5_obj}:{sha1_obj}:{cast_obj}:{rc4_obj}:
{rmd160_obj}:{rc5_obj}:{wp_obj}:{cmll_obj}:{modes_obj}:
{padlock_obj}:{perlasm_scheme}:{dso_scheme}:{shared_target}:
{shared_cflag}:{shared_ldflag}:{shared_extension}:{ranlib}:
{arflags}:{multilib}"
Build info files
================
The build.info files that are spread over the source tree contain the
The `build.info` files that are spread over the source tree contain the
minimum information needed to build and distribute OpenSSL. It uses a
simple and yet fairly powerful language to determine what needs to be
built, from what sources, and other relationships between files.
For every build.info file, all file references are relative to the
directory of the build.info file for source files, and the
For every `build.info` file, all file references are relative to the
directory of the `build.info` file for source files, and the
corresponding build directory for built files if the build tree
differs from the source tree.
When processed, every line is processed with the perl module
Text::Template, using the delimiters "{-" and "-}". The hashes
%config and %target are passed to the perl fragments, along with
Text::Template, using the delimiters `{-` and `-}`. The hashes
`%config` and `%target` are passed to the perl fragments, along with
$sourcedir and $builddir, which are the locations of the source
directory for the current build.info file and the corresponding build
directory for the current `build.info` file and the corresponding build
directory, all relative to the top of the build tree.
'Configure' only knows inherently about the top build.info file. For
`Configure` only knows inherently about the top `build.info` file. For
any other directory that has one, further directories to look into
must be indicated like this:
@ -393,7 +396,7 @@ This should be rarely used, and care should be taken to make sure it's
only used when supported. For example, native Windows build doesn't
support building static libraries and DLLs at the same time, so using
static libraries on Windows can only be done when configured
'no-shared'.
`no-shared`.
In some cases, it's desirable to include some source files in the
shared form of a library only:
@ -435,7 +438,7 @@ be used in that case:
NOTE: GENERATE lines are limited to one command only per GENERATE.
Finally, you can have some simple conditional use of the build.info
Finally, you can have some simple conditional use of the `build.info`
information, looking like this:
IF[1]
@ -461,37 +464,37 @@ conditions based on something in the passed variables, for example:
SOURCE[libfoo]=...
ENDIF
Build-file programming with the "unified" build system
======================================================
"Build files" are called "Makefile" on Unix-like operating systems,
"descrip.mms" for MMS on VMS, "makefile" for nmake on Windows, etc.
"Build files" are called `Makefile` on Unix-like operating systems,
`descrip.mms` for MMS on VMS, `makefile` for `nmake` on Windows, etc.
To use the "unified" build system, the target configuration needs to
set the three items 'build_scheme', 'build_file' and 'build_command'.
In the rest of this section, we will assume that 'build_scheme' is set
set the three items `build_scheme`, `build_file` and `build_command`.
In the rest of this section, we will assume that `build_scheme` is set
to "unified" (see the configurations documentation above for the
details).
For any name given by 'build_file', the "unified" system expects a
template file in Configurations/ named like the build file, with
".tmpl" appended, or in case of possible ambiguity, a combination of
the second 'build_scheme' list item and the 'build_file' name. For
example, if 'build_file' is set to "Makefile", the template could be
Configurations/Makefile.tmpl or Configurations/unix-Makefile.tmpl.
In case both Configurations/unix-Makefile.tmpl and
Configurations/Makefile.tmpl are present, the former takes
For any name given by `build_file`, the "unified" system expects a
template file in `Configurations/` named like the build file, with
`.tmpl` appended, or in case of possible ambiguity, a combination of
the second `build_scheme` list item and the `build_file` name. For
example, if `build_file` is set to `Makefile`, the template could be
[`Configurations/Makefile.tmpl`](Makefile.tmpl) or
[`Configurations/unix-Makefile.tmpl`](unix-Makefile.tmpl).
In case both [`Configurations/unix-Makefile.tmpl`](Makefile.tmpl) and
[`Configurations/Makefile.tmpl`](Makefile.tmpl) are present, the former takes
precedence.
The build-file template is processed with the perl module
Text::Template, using "{-" and "-}" as delimiters that enclose the
Text::Template, using `{-` and `-}` as delimiters that enclose the
perl code fragments that generate configuration-dependent content.
Those perl fragments have access to all the hash variables from
configdata.pem.
The build-file template is expected to define at least the following
perl functions in a perl code fragment enclosed with "{-" and "-}".
perl functions in a perl code fragment enclosed with `{-` and `-}`.
They are all expected to return a string with the lines they produce.
generatesrc - function that produces build file lines to generate
@ -640,7 +643,6 @@ else, end it like this:
""; # Make sure no lingering values end up in the Makefile
-}
Configure helper scripts
========================
@ -651,10 +653,10 @@ Checker scripts
These scripts are per platform family, to check the integrity of the
tools used for configuration and building. The checker script used is
either {build_platform}-{build_file}-checker.pm or
{build_platform}-checker.pm, where {build_platform} is the second
'build_scheme' list element from the configuration target data, and
{build_file} is 'build_file' from the same target data.
either `{build_platform}-{build_file}-checker.pm` or
`{build_platform}-checker.pm`, where `{build_platform}` is the second
`build_scheme` list element from the configuration target data, and
`{build_file}` is `build_file` from the same target data.
If the check succeeds, the script is expected to end with a non-zero
expression. If the check fails, the script can end with a zero, or


+ 1
- 1
Configure View File

@ -2739,7 +2739,7 @@ sub death_handler {
my @message = ( <<"_____", @_ );
Failure! $build_file wasn't produced.
Please read INSTALL.md and associated NOTES files. You may also have to
Please read INSTALL.md and associated NOTES-* files. You may also have to
look over your available compiler tool chain or change your configuration.
_____


+ 18
- 11
HACKING.md View File

@ -1,10 +1,13 @@
MODIFYING OPENSSL SOURCE
------------------------
This document describes the way to add custom modifications to OpenSSL sources.
MODIFYING OPENSSL SOURCE
========================
This document describes the way to add custom modifications to OpenSSL sources.
If you are adding new public functions to the custom library build, you need to
either add a prototype in one of the existing OpenSSL header files;
or provide a new header file and edit Configurations/unix-Makefile.tmpl to pick up that file.
or provide a new header file and edit
[Configurations/unix-Makefile.tmpl](Configurations/unix-Makefile.tmpl)
to pick up that file.
After that perform the following steps:
@ -13,14 +16,18 @@
make
make test
"make update" ensures that your functions declarations are added to util/libcrypto.num or util/libssl.num
If you plan to submit the changes you made to OpenSSL (see CONTRIBUTING), it's worth running:
`make update` ensures that your functions declarations are added to
`util/libcrypto.num` or `util/libssl.num`.
If you plan to submit the changes you made to OpenSSL
(see [CONTRIBUTING.md](CONTRIBUTING.md)), it's worth running:
make doc-nits
after running "make update" to ensure that documentation has correct format.
after running `make update` to ensure that documentation has correct format.
"make update" also generates files related to OIDs (in the crypto/objects/ folder) and errors.
If a merge error occurs in one of these generated files then the generated files need to be removed
and regenerated using "make update".
To aid in this process the generated files can be committed separately so they can be removed easily.
`make update` also generates files related to OIDs (in the `crypto/objects/`
folder) and errors.
If a merge error occurs in one of these generated files then the
generated files need to be removed and regenerated using `make update`.
To aid in this process the generated files can be committed separately
so they can be removed easily.

+ 12
- 12
INSTALL.md View File

@ -48,8 +48,8 @@ Prerequisites
To install OpenSSL, you will need:
* A "make" implementation
* Perl 5 with core modules (please read [NOTES.PERL](NOTES.PERL))
* The Perl module Text::Template (please read [NOTES.PERL](NOTES.PERL))
* Perl 5 with core modules (please read [NOTES-Perl.md](NOTES-Perl.md))
* The Perl module `Text::Template` (please read [NOTES-PERL.md](NOTES-Perl.md))
* an ANSI C compiler
* a development environment in the form of development libraries and C
header files
@ -58,13 +58,13 @@ To install OpenSSL, you will need:
For additional platform specific requirements, solutions to specific
issues and other details, please read one of these:
* [NOTES.UNIX](NOTES.UNIX) - notes for Unix like systems
* [NOTES.VMS](NOTES.VMS) - notes related to OpenVMS
* [NOTES.WIN](NOTES.WIN) - notes related to the Windows platform
* [NOTES.DJGPP](NOTES.DJGPP) - building for DOS with DJGPP
* [NOTES.ANDROID](NOTES.ANDROID) - building for Android platforms (using NDK)
* [NOTES.VALGRIND](NOTES.VALGRIND) - testing with Valgrind
* [NOTES.PERL](NOTES.PERL) - some notes on Perl
* [NOTES-Unix.md](NOTES-Unix.md) - notes for Unix like systems
* [NOTES-VMS.md](NOTES-VMS.md) - notes related to OpenVMS
* [NOTES-Windows.txt](NOTES-Windows.txt) - notes related to the Windows platform
* [NOTES-DJGPP.md](NOTES-DJGPP.md) - building for DOS with DJGPP
* [NOTES-Android.md](NOTES-Android.md) - building for Android platforms (using NDK)
* [NOTES-Valgrind.md](NOTES-Valgrind.md) - testing with Valgrind
* [NOTES-Perl.m](NOTES-Perl.md) - some notes on Perl
Notational conventions
======================
@ -275,7 +275,7 @@ On OpenVMS:
$ perl Configure --prefix=PROGRAM:[INSTALLS] --openssldir=SYS$MANAGER:[OPENSSL]
Note: if you do add options to the configuration command, please make sure
you've read more than just this Quick Start, such as relevant `NOTES.*` files,
you've read more than just this Quick Start, such as relevant `NOTES-*` files,
the options outline below, as configuration options may change the outcome
in otherwise unexpected ways.
@ -285,7 +285,7 @@ Configuration Options
There are several options to `./Configure` to customize the build (note that
for Windows, the defaults for `--prefix` and `--openssldir` depend on what
configuration is used and what Windows implementation OpenSSL is built on.
More notes on this in [NOTES.WIN](NOTES.WIN)):
More notes on this in [NOTES-Windows.txt](NOTES-Windows.txt):
API Level
---------
@ -1505,7 +1505,7 @@ cases it does not succeed. You will see a message like the following:
$ ./Configure
Operating system: x86-whatever-minix
This system (minix) is not supported. See file INSTALL for details.
This system (minix) is not supported. See file INSTALL.md for details.
Even if the automatic target selection by the `./Configure` script fails,
chances are that you still might find a suitable target in the `Configurations`


+ 22
- 23
NOTES-Android.md View File

@ -1,6 +1,5 @@
NOTES FOR ANDROID PLATFORMS
===========================
NOTES FOR ANDROID PLATFORMS
===========================
Requirement details
-------------------
@ -15,27 +14,27 @@
Configuration
-------------
Android is a cross-compiled target and you can't rely on ./Configure
Android is a cross-compiled target and you can't rely on `./Configure`
to find out the configuration target for you. You have to name your
target explicitly; there are android-arm, android-arm64, android-mips,
android-mip64, android-x86 and android-x86_64 (*MIPS targets are no
target explicitly; there are `android-arm`, `android-arm64`, `android-mips`,
`android-mip64`, `android-x86` and `android-x86_64` (`*MIPS` targets are no
longer supported with NDK R20+).
Do not pass --cross-compile-prefix (as you might be tempted), as it
will be "calculated" automatically based on chosen platform. However,
you still need to know the prefix to extend your PATH, in order to
invoke $(CROSS_COMPILE)clang [*gcc on NDK 19 and lower] and company.
(Configure will fail and give you a hint if you get it wrong.)
invoke `$(CROSS_COMPILE)clang` [`*gcc` on NDK 19 and lower] and company.
(`./Configure` will fail and give you a hint if you get it wrong.)
Apart from PATH adjustment you need to set ANDROID_NDK_ROOT environment
to point at the NDK directory. If you're using a side-by-side NDK the path
will look something like /some/where/android-sdk/ndk/<ver>, and for a
standalone NDK the path will be something like /some/where/android-ndk-<ver>.
Apart from `PATH` adjustment you need to set `ANDROID_NDK_ROOT` environment
to point at the `NDK` directory. If you're using a side-by-side NDK the path
will look something like `/some/where/android-sdk/ndk/<ver>`, and for a
standalone NDK the path will be something like `/some/where/android-ndk-<ver>`.
Both variables are significant at both configuration and compilation times.
The NDK customarily supports multiple Android API levels, e.g. android-14,
android-21, etc. By default latest API level is chosen. If you need to
target an older platform pass the argument -D__ANDROID_API__=N to Configure,
with N being the numerical value of the target platform version. For example,
The NDK customarily supports multiple Android API levels, e.g. `android-14`,
`android-21`, etc. By default latest API level is chosen. If you need to target
an older platform pass the argument `-D__ANDROID_API__=N` to `Configure`,
with `N` being the numerical value of the target platform version. For example,
to compile for Android 10 arm64 with a side-by-side NDK r20.0.5594570
export ANDROID_NDK_ROOT=/home/whoever/Android/android-sdk/ndk/20.0.5594570
@ -52,13 +51,13 @@
./Configure android-arm -D__ANDROID_API__=14
make
Caveat lector! Earlier OpenSSL versions relied on additional CROSS_SYSROOT
variable set to $ANDROID_NDK_ROOT/platforms/android-<api>/arch-<arch> to
Caveat lector! Earlier OpenSSL versions relied on additional `CROSS_SYSROOT`
variable set to `$ANDROID_NDK_ROOT/platforms/android-<api>/arch-<arch>` to
appoint headers-n-libraries' location. It's still recognized in order
to facilitate migration from older projects. However, since API level
appears in CROSS_SYSROOT value, passing -D__ANDROID_API__=N can be in
appears in `CROSS_SYSROOT` value, passing `-D__ANDROID_API__=N` can be in
conflict, and mixing the two is therefore not supported. Migration to
CROSS_SYSROOT-less setup is recommended.
`CROSS_SYSROOT`-less setup is recommended.
One can engage clang by adjusting PATH to cover same NDK's clang. Just
keep in mind that if you miss it, Configure will try to use gcc...
@ -68,9 +67,9 @@
Another option is to create so called "standalone toolchain" tailored
for single specific platform including Android API level, and assign its
location to ANDROID_NDK_ROOT. In such case you have to pass matching
target name to Configure and shouldn't use -D__ANDROID_API__=N. PATH
adjustment becomes simpler, $ANDROID_NDK_ROOT/bin:$PATH suffices.
location to `ANDROID_NDK_ROOT`. In such case you have to pass matching
target name to Configure and shouldn't use `-D__ANDROID_API__=N`. `PATH`
adjustment becomes simpler, `$ANDROID_NDK_ROOT/bin:$PATH` suffices.
Running tests (on Linux)
------------------------


+ 17
- 19
NOTES-DJGPP.md View File

@ -1,7 +1,5 @@
INSTALLATION ON THE DOS PLATFORM WITH DJGPP
-------------------------------------------
INSTALLATION ON THE DOS PLATFORM WITH DJGPP
===========================================
OpenSSL has been ported to DJGPP, a Unix look-alike 32-bit run-time
environment for 16-bit DOS, but only with long filename support.
@ -11,28 +9,28 @@
You should have a full DJGPP environment installed, including the
latest versions of DJGPP, GCC, BINUTILS, BASH, etc. This package
requires that PERL and the PERL module Text::Template also be
installed (see NOTES.PERL).
requires that PERL and the PERL module `Text::Template` also be
installed (see [NOTES-Perl.md](NOTES-Perl.md)).
All of these can be obtained from the usual DJGPP mirror sites or
directly at "http://www.delorie.com/pub/djgpp". For help on which
directly at <http://www.delorie.com/pub/djgpp>. For help on which
files to download, see the DJGPP "ZIP PICKER" page at
"http://www.delorie.com/djgpp/zip-picker.html". You also need to have
<http://www.delorie.com/djgpp/zip-picker.html>. You also need to have
the WATT-32 networking package installed before you try to compile
OpenSSL. This can be obtained from "http://www.watt-32.net/".
OpenSSL. This can be obtained from <http://www.watt-32.net/>.
The Makefile assumes that the WATT-32 code is in the directory
specified by the environment variable WATT_ROOT. If you have watt-32
in directory "watt32" under your main DJGPP directory, specify
WATT_ROOT="/dev/env/DJDIR/watt32".
in directory `watt32` under your main DJGPP directory, specify
`WATT_ROOT="/dev/env/DJDIR/watt32"`.
To compile OpenSSL, start your BASH shell, then configure for DJGPP by
running "./Configure" with appropriate arguments:
running `./Configure` with appropriate arguments:
./Configure no-threads --prefix=/dev/env/DJDIR DJGPP
./Configure no-threads --prefix=/dev/env/DJDIR DJGPP
And finally fire up "make". You may run out of DPMI selectors when
And finally fire up `make`. You may run out of DPMI selectors when
running in a DOS box under Windows. If so, just close the BASH
shell, go back to Windows, and restart BASH. Then run "make" again.
shell, go back to Windows, and restart BASH. Then run `make` again.
RUN-TIME CAVEAT LECTOR
--------------
@ -41,8 +39,8 @@
"Cryptographic software needs a source of unpredictable data to work
correctly. Many open source operating systems provide a "randomness
device" (/dev/urandom or /dev/random) that serves this purpose."
device" (`/dev/urandom` or `/dev/random`) that serves this purpose."
As of version 0.9.7f DJGPP port checks upon /dev/urandom$ for a 3rd
party "randomness" DOS driver. One such driver, NOISE.SYS, can be
obtained from "http://www.rahul.net/dkaufman/index.html".
As of version 0.9.7f DJGPP port checks upon `/dev/urandom$` for a 3rd
party "randomness" DOS driver. One such driver, `NOISE.SYS`, can be
obtained from <http://www.rahul.net/dkaufman/index.html>.

+ 27
- 23
NOTES-Perl.md View File

@ -1,5 +1,5 @@
TOC
===
TOC
===
- Notes on Perl
- Notes on Perl on Windows
@ -18,10 +18,10 @@
installed properly. We do not claim to know them all, but experience
has told us the following:
- on Linux distributions based on Debian, the package 'perl' will
- on Linux distributions based on Debian, the package `perl` will
install the core Perl modules as well, so you will be fine.
- on Linux distributions based on RPMs, you will need to install
'perl-core' rather than just 'perl'.
`perl-core` rather than just `perl`.
You MUST have at least Perl version 5.10.0 installed. This minimum
requirement is due to our use of regexp backslash sequence \R among
@ -31,23 +31,23 @@
------------------------
There are a number of build targets that can be viewed as "Windows".
Indeed, there are VC-* configs targeting VisualStudio C, as well as
Indeed, there are `VC-*` configs targeting VisualStudio C, as well as
MinGW and Cygwin. The key recommendation is to use "matching" Perl,
one that matches build environment. For example, if you will build
on Cygwin be sure to use the Cygwin package manager to install Perl.
For MSYS builds use the MSYS provided Perl.
For VC-* builds we recommend Strawberry Perl, from http://strawberryperl.com.
An alternative is ActiveState Perl, from http://www.activestate.com/ActivePerl
For VC-* builds we recommend Strawberry Perl, from <http://strawberryperl.com>.
An alternative is ActiveState Perl, from <http://www.activestate.com/ActivePerl>
for which you may need to explicitly select the Perl module Win32/Console.pm
available via https://platform.activestate.com/ActiveState.
available via <https://platform.activestate.com/ActiveState>.
Notes on Perl on VMS
--------------------
You will need to install Perl separately. One way to do so is to
download the source from http://perl.org/, unpacking it, reading
README.vms and follow the instructions. Another way is to download a
.PCSI file from http://www.vmsperl.com/ and install it using the
download the source from <http://perl.org/>, unpacking it, reading
`README-VMS.md` and follow the instructions. Another way is to download a
`.PCSI` file from <http://www.vmsperl.com/> and install it using the
POLYCENTER install tool.
Notes on Perl modules we use
@ -57,18 +57,22 @@
ourselves to core Perl modules to keep the requirements down. There
are just a few exceptions:
Test::More We require the minimum version to be 0.96, which
appeared in Perl 5.13.4, because that version was
the first to have all the features we're using.
This module is required for testing only! If you
don't plan on running the tests, you don't need to
bother with this one.
* `Test::More`
Text::Template This module is not part of the core Perl modules.
As a matter of fact, the core Perl modules do not
include any templating module to date.
This module is absolutely needed, configuration
depends on it.
We require the minimum version to be 0.96, which
appeared in Perl 5.13.4, because that version was
the first to have all the features we're using.
This module is required for testing only!
If you don't plan on running the tests,
you don't need to bother with this one.
* `Text::Template`
This module is not part of the core Perl modules.
As a matter of fact, the core Perl modules do not
include any templating module to date.
This module is absolutely needed,
configuration depends on it.
To avoid unnecessary initial hurdles, we have bundled a copy of the
following modules in our source. They will work as fallbacks if
@ -80,7 +84,7 @@
---------------------------------
There are a number of ways to install a perl module. In all
descriptions below, Text::Template will serve as an example.
descriptions below, `Text::Template` will serve as an example.
1. for Linux users, the easiest is to install with the use of your
favorite package manager. Usually, all you need to do is search


+ 29
- 32
NOTES-Unix.md View File

@ -1,9 +1,8 @@
NOTES FOR UNIX-LIKE PLATFORMS
=============================
NOTES FOR UNIX LIKE PLATFORMS
=============================
For Unix/POSIX runtime systems on Windows, please see NOTES.WIN.
For Unix/POSIX runtime systems on Windows,
please see [NOTES-Windows.txt](NOTES-Windows.txt).
OpenSSL uses the compiler to link programs and shared libraries
---------------------------------------------------------------
@ -13,21 +12,20 @@
objects. Because of this, any linking option that's given to the
configuration scripts MUST be in a form that the compiler can accept.
This varies between systems, where some have compilers that accept
linker flags directly, while others take them in '-Wl,' form. You need
linker flags directly, while others take them in `-Wl,` form. You need
to read your compiler documentation to figure out what is acceptable,
and ld(1) to figure out what linker options are available.
and `ld(1)` to figure out what linker options are available.
Shared libraries and installation in non-default locations
----------------------------------------------------------
Every Unix system has its own set of default locations for shared
libraries, such as /lib, /usr/lib or possibly /usr/local/lib. If
libraries, such as `/lib`, `/usr/lib` or possibly `/usr/local/lib`. If
libraries are installed in non-default locations, dynamically linked
binaries will not find them and therefore fail to run, unless they get
a bit of help from a defined runtime shared library search path.
For OpenSSL's application (the 'openssl' command), our configuration
For OpenSSL's application (the `openssl` command), our configuration
scripts do NOT generally set the runtime shared library search path for
you. It's therefore advisable to set it explicitly when configuring,
unless the libraries are to be installed in directories that you know
@ -42,15 +40,15 @@
Possible options to set the runtime shared library search path include
the following:
-Wl,-rpath,/whatever/path # Linux, *BSD, etc.
-R /whatever/path # Solaris
-Wl,-R,/whatever/path # AIX (-bsvr4 is passed internally)
-Wl,+b,/whatever/path # HP-UX
-rpath /whatever/path # Tru64, IRIX
-Wl,-rpath,/whatever/path # Linux, *BSD, etc.
-R /whatever/path # Solaris
-Wl,-R,/whatever/path # AIX (-bsvr4 is passed internally)
-Wl,+b,/whatever/path # HP-UX
-rpath /whatever/path # Tru64, IRIX
OpenSSL's configuration scripts recognise all these options and pass
them to the Makefile that they build. (In fact, all arguments starting
with '-Wl,' are recognised as linker options.)
with `-Wl,` are recognised as linker options.)
Please do not use verbatim directories in your runtime shared library
search path! Some OpenSSL config targets add an extra directory level
@ -63,28 +61,27 @@
'-Wl,-rpath,$(LIBRPATH)'
On modern ELF based systems, there are two runtime search paths tags to
consider, DT_RPATH and DT_RUNPATH. Shared objects are searched for in
consider, `DT_RPATH` and `DT_RUNPATH`. Shared objects are searched for in
this order:
1. Using directories specified in DT_RPATH, unless DT_RUNPATH is
also set.
2. Using the environment variable LD_LIBRARY_PATH
3. Using directories specified in DT_RUNPATH.
4. Using system shared object caches and default directories.
1. Using directories specified in DT_RPATH, unless DT_RUNPATH is also set.
2. Using the environment variable LD_LIBRARY_PATH
3. Using directories specified in DT_RUNPATH.
4. Using system shared object caches and default directories.
This means that the values in the environment variable LD_LIBRARY_PATH
won't matter if the library is found in the paths given by DT_RPATH
(and DT_RUNPATH isn't set).
This means that the values in the environment variable `LD_LIBRARY_PATH`
won't matter if the library is found in the paths given by `DT_RPATH`
(and `DT_RUNPATH` isn't set).
Exactly which of DT_RPATH or DT_RUNPATH is set by default appears to
Exactly which of `DT_RPATH` or `DT_RUNPATH` is set by default appears to
depend on the system. For example, according to documentation,
DT_RPATH appears to be deprecated on Solaris in favor of DT_RUNPATH,
while on Debian GNU/Linux, either can be set, and DT_RPATH is the
`DT_RPATH` appears to be deprecated on Solaris in favor of `DT_RUNPATH`,
while on Debian GNU/Linux, either can be set, and `DT_RPATH` is the
default at the time of writing.
How to choose which runtime search path tag is to be set depends on
your system, please refer to ld(1) for the exact information on your
system. As an example, the way to ensure the DT_RUNPATH is set on
system. As an example, the way to ensure the `DT_RUNPATH` is set on
Debian GNU/Linux systems rather than DT_RPATH is to tell the linker to
set new dtags, like this:
@ -93,7 +90,7 @@
It might be worth noting that some/most ELF systems implement support
for runtime search path relative to the directory containing current
executable, by interpreting $ORIGIN along with some other internal
executable, by interpreting `$ORIGIN` along with some other internal
variables. Consult your system documentation.
Linking your application
@ -104,7 +101,7 @@
The OpenSSL config options mentioned above might or might not have bearing
on linking of the target application. "Might" means that under some
circumstances it would be sufficient to link with OpenSSL shared library
"naturally", i.e. with -L/whatever/path -lssl -lcrypto. But there are
"naturally", i.e. with `-L/whatever/path -lssl -lcrypto`. But there are
also cases when you'd have to explicitly specify runtime search path
when linking your application. Consult your system documentation and use
above section as inspiration...
@ -114,4 +111,4 @@
for shared libraries first and tend to remain "blind" to static OpenSSL
libraries. Referring to system documentation would suffice, if not for
a corner case. On AIX static libraries (in shared build) are named
differently, add _a suffix to link with them, e.g. -lcrypto_a.
differently, add `_a` suffix to link with them, e.g. `-lcrypto_a`.

+ 13
- 19
NOTES-VMS.md View File

@ -1,17 +1,15 @@
NOTES FOR THE OPENVMS PLATFORM
==============================
NOTES FOR THE OPENVMS PLATFORM
==============================
Requirement details
-------------------
In addition to the requirements and instructions listed in INSTALL,
this are required as well:
In addition to the requirements and instructions listed
in [INSTALL.md](INSTALL.md), this are required as well:
* At least ODS-5 disk organization for source and build.
Installation can be done on any existing disk organization.
About ANSI C compiler
---------------------
@ -22,20 +20,19 @@
version 7.1 or later. Compiling with a different ANSI C compiler may
require some work.
Please avoid using C RTL feature logical names DECC$* when building
Please avoid using C RTL feature logical names `DECC$*` when building
and testing OpenSSL. Most of all, they can be disruptive when
running the tests, as they affect the Perl interpreter.
About ODS-5 directory names and Perl
------------------------------------
It seems that the perl function canonpath() in the File::Spec module
It seems that the perl function canonpath() in the `File::Spec` module
doesn't treat file specifications where the last directory name
contains periods very well. Unfortunately, some versions of VMS tar
will keep the periods in the OpenSSL source directory instead of
converting them to underscore, thereby leaving your source in
something like [.openssl-1^.1^.0]. This will lead to issues when
something like `[.openssl-1^.1^.0]`. This will lead to issues when
configuring and building OpenSSL.
We have no replacement for Perl's canonpath(), so the best workaround
@ -44,7 +41,6 @@
$ rename openssl-1^.1^.0.DIR openssl-1_1_0.DIR
About MMS and DCL
-----------------
@ -55,7 +51,6 @@
yourself up a few logical names for the directory trees you're going
to use.
About debugging
---------------
@ -68,7 +63,7 @@
directly for debugging. Do not try to use them from a script, such
as running the test suite.
*The following is not available on Alpha*
### The following is not available on Alpha
As a compromise, we're turning off the flag that makes the debugger
start automatically. If there is a program that you need to debug,
@ -81,7 +76,6 @@
$ set image /flag=nocall_debug [.test]evp_test.exe
Checking the distribution
-------------------------
@ -92,16 +86,16 @@
The easiest way to check if everything got through as it should is to
check for one of the following files:
[.crypto]opensslconf^.h.in
[.crypto]opensslconf^.h.in
The best way to get a correct distribution is to download the gzipped
tar file from ftp://ftp.openssl.org/source/, use GZIP -d to uncompress
it and VMSTAR to unpack the resulting tar file.
tar file from ftp://ftp.openssl.org/source/, use `GZIP -d` to uncompress
it and `VMSTAR` to unpack the resulting tar file.
Gzip and VMSTAR are available here:
http://antinode.info/dec/index.html#Software
<http://antinode.info/dec/index.html#Software>
Should you need it, you can find UnZip for VMS here:
http://www.info-zip.org/UnZip.html
<http://www.info-zip.org/UnZip.html>

+ 18
- 16
NOTES-Valgrind.md View File

@ -1,4 +1,3 @@
NOTES FOR VALGRIND
==================
@ -14,11 +13,11 @@ Requirements
------------
1. Platform supported by Valgrind
See: http://valgrind.org/info/platforms.html
See <http://valgrind.org/info/platforms.html>
2. Valgrind installed on the platform
See: http://valgrind.org/downloads/current.html
See <http://valgrind.org/downloads/current.html>
3. OpensSSL compiled
See: [INSTALL.md](INSTALL.md)
See [INSTALL.md](INSTALL.md)
Running Tests
-------------
@ -28,18 +27,19 @@ Test behavior can be modified by adjusting environment variables.
`EXE_SHELL`
This variable is used to specify the shell used to execute OpenSSL test
programs. The default wrapper (util/wrap.pl) initializes the environment
programs. The default wrapper (`util/wrap.pl`) initializes the environment
to allow programs to find shared libraries. The variable can be modified
to specify a different executable environment.
EXE_SHELL="`/bin/pwd`/util/wrap.pl valgrind --error-exitcode=1 --leak-check=full -q"
EXE_SHELL=\
"`/bin/pwd`/util/wrap.pl valgrind --error-exitcode=1 --leak-check=full -q"
This will start up Valgrind with the default checker (memcheck).
The --error-exitcode=1 option specifies that Valgrind should exit with an
This will start up Valgrind with the default checker (`memcheck`).
The `--error-exitcode=1` option specifies that Valgrind should exit with an
error code of 1 when memory leaks occur.
The --leak-check=full option specifies extensive memory checking.
The -q option prints only error messages.
Additional Valgrind options may be added to the EXE_SHELL variable.
The `--leak-check=full` option specifies extensive memory checking.
The `-q` option prints only error messages.
Additional Valgrind options may be added to the `EXE_SHELL` variable.