public/openssl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

Browse source 
Reviewed-by: Tim Hudson <tjh@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/12109)
This commit is contained in:
Dr. David von Oheimb 2020-06-10 17:49:25 +02:00
parent 036cbb6bbf
commit 1dc1ea182b
28 changed files with 871 additions and 845 deletions
Download patch file Download diff file Expand all files Collapse all files

120
CHANGES.md
View file

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

11
CONTRIBUTING.md
View file

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

218
Configurations/README-design.md
View file

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

140
Configurations/README.md
View file

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

2
Configure
View file

@ -2739,7 +2739,7 @@ sub death_handler {
my @message = ( <<"_____", @_ ); my @message = ( <<"_____", @_ );
Failure! $build_file wasn't produced. 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. look over your available compiler tool chain or change your configuration.
_____ _____

29
HACKING.md
View file

@ -1,10 +1,13 @@
MODIFYING OPENSSL SOURCE MODIFYING OPENSSL SOURCE
------------------------ ========================
This document describes the way to add custom modifications to OpenSSL sources.
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 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; 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: After that perform the following steps:
@ -13,14 +16,18 @@
make make
make test make test
"make update" ensures that your functions declarations are added to util/libcrypto.num or util/libssl.num `make update` ensures that your functions declarations are added to
If you plan to submit the changes you made to OpenSSL (see CONTRIBUTING), it's worth running: `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 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. `make update` also generates files related to OIDs (in the `crypto/objects/`
If a merge error occurs in one of these generated files then the generated files need to be removed folder) and errors.
and regenerated using "make update". If a merge error occurs in one of these generated files then the
To aid in this process the generated files can be committed separately so they can be removed easily. 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.

24
INSTALL.md
View file

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

45
NOTES-Android.md
View file

@ -1,6 +1,5 @@
NOTES FOR ANDROID PLATFORMS
NOTES FOR ANDROID PLATFORMS ===========================
===========================
Requirement details Requirement details
------------------- -------------------
@ -15,27 +14,27 @@
Configuration 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 to find out the configuration target for you. You have to name your
target explicitly; there are android-arm, android-arm64, android-mips, target explicitly; there are `android-arm`, `android-arm64`, `android-mips`,
android-mip64, android-x86 and android-x86_64 (*MIPS targets are no `android-mip64`, `android-x86` and `android-x86_64` (`*MIPS` targets are no
longer supported with NDK R20+). longer supported with NDK R20+).
Do not pass --cross-compile-prefix (as you might be tempted), as it Do not pass --cross-compile-prefix (as you might be tempted), as it
will be "calculated" automatically based on chosen platform. However, will be "calculated" automatically based on chosen platform. However,
you still need to know the prefix to extend your PATH, in order to 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. 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.) (`./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 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 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 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>. standalone NDK the path will be something like `/some/where/android-ndk-<ver>`.
Both variables are significant at both configuration and compilation times. Both variables are significant at both configuration and compilation times.
The NDK customarily supports multiple Android API levels, e.g. android-14, 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 `android-21`, etc. By default latest API level is chosen. If you need to target
target an older platform pass the argument -D__ANDROID_API__=N to Configure, 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, 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 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 export ANDROID_NDK_ROOT=/home/whoever/Android/android-sdk/ndk/20.0.5594570
@ -52,13 +51,13 @@
./Configure android-arm -D__ANDROID_API__=14 ./Configure android-arm -D__ANDROID_API__=14
make make
Caveat lector! Earlier OpenSSL versions relied on additional CROSS_SYSROOT Caveat lector! Earlier OpenSSL versions relied on additional `CROSS_SYSROOT`
variable set to $ANDROID_NDK_ROOT/platforms/android-<api>/arch-<arch> to variable set to `$ANDROID_NDK_ROOT/platforms/android-<api>/arch-<arch>` to
appoint headers-n-libraries' location. It's still recognized in order appoint headers-n-libraries' location. It's still recognized in order
to facilitate migration from older projects. However, since API level 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 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 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... 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 Another option is to create so called "standalone toolchain" tailored
for single specific platform including Android API level, and assign its for single specific platform including Android API level, and assign its
location to ANDROID_NDK_ROOT. In such case you have to pass matching 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 target name to Configure and shouldn't use `-D__ANDROID_API__=N`. `PATH`
adjustment becomes simpler, $ANDROID_NDK_ROOT/bin:$PATH suffices. adjustment becomes simpler, `$ANDROID_NDK_ROOT/bin:$PATH` suffices.
Running tests (on Linux) Running tests (on Linux)
------------------------ ------------------------

36
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 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. 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 You should have a full DJGPP environment installed, including the
latest versions of DJGPP, GCC, BINUTILS, BASH, etc. This package latest versions of DJGPP, GCC, BINUTILS, BASH, etc. This package
requires that PERL and the PERL module Text::Template also be requires that PERL and the PERL module `Text::Template` also be
installed (see NOTES.PERL). installed (see [NOTES-Perl.md](NOTES-Perl.md)).
All of these can be obtained from the usual DJGPP mirror sites or 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 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 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 The Makefile assumes that the WATT-32 code is in the directory
specified by the environment variable WATT_ROOT. If you have watt-32 specified by the environment variable WATT_ROOT. If you have watt-32
in directory "watt32" under your main DJGPP directory, specify in directory `watt32` under your main DJGPP directory, specify
WATT_ROOT="/dev/env/DJDIR/watt32". `WATT_ROOT="/dev/env/DJDIR/watt32"`.
To compile OpenSSL, start your BASH shell, then configure for DJGPP by 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 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 RUN-TIME CAVEAT LECTOR
-------------- --------------
@ -41,8 +39,8 @@
"Cryptographic software needs a source of unpredictable data to work "Cryptographic software needs a source of unpredictable data to work
correctly. Many open source operating systems provide a "randomness 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 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 party "randomness" DOS driver. One such driver, `NOISE.SYS`, can be
obtained from "http://www.rahul.net/dkaufman/index.html". obtained from <http://www.rahul.net/dkaufman/index.html>.

50
NOTES-Perl.md
View file

@ -1,5 +1,5 @@
TOC TOC
=== ===
- Notes on Perl - Notes on Perl
- Notes on Perl on Windows - Notes on Perl on Windows
@ -18,10 +18,10 @@
installed properly. We do not claim to know them all, but experience installed properly. We do not claim to know them all, but experience
has told us the following: 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. install the core Perl modules as well, so you will be fine.
- on Linux distributions based on RPMs, you will need to install - 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 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 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". 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, MinGW and Cygwin. The key recommendation is to use "matching" Perl,
one that matches build environment. For example, if you will build one that matches build environment. For example, if you will build
on Cygwin be sure to use the Cygwin package manager to install Perl. on Cygwin be sure to use the Cygwin package manager to install Perl.
For MSYS builds use the MSYS provided Perl. For MSYS builds use the MSYS provided Perl.
For VC-* builds we recommend Strawberry Perl, from http://strawberryperl.com. For VC-* builds we recommend Strawberry Perl, from <http://strawberryperl.com>.
An alternative is ActiveState Perl, from http://www.activestate.com/ActivePerl 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 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 Notes on Perl on VMS
-------------------- --------------------
You will need to install Perl separately. One way to do so is to You will need to install Perl separately. One way to do so is to
download the source from http://perl.org/, unpacking it, reading download the source from <http://perl.org/>, unpacking it, reading
README.vms and follow the instructions. Another way is to download a `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 `.PCSI` file from <http://www.vmsperl.com/> and install it using the
POLYCENTER install tool. POLYCENTER install tool.
Notes on Perl modules we use Notes on Perl modules we use
@ -57,18 +57,22 @@
ourselves to core Perl modules to keep the requirements down. There ourselves to core Perl modules to keep the requirements down. There
are just a few exceptions: are just a few exceptions:
Test::More We require the minimum version to be 0.96, which * `Test::More`
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. We require the minimum version to be 0.96, which
As a matter of fact, the core Perl modules do not appeared in Perl 5.13.4, because that version was
include any templating module to date. the first to have all the features we're using.
This module is absolutely needed, configuration This module is required for testing only!
depends on it. 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 To avoid unnecessary initial hurdles, we have bundled a copy of the
following modules in our source. They will work as fallbacks if 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 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 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 favorite package manager. Usually, all you need to do is search

61
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-Windows.txt](NOTES-Windows.txt).
For Unix/POSIX runtime systems on Windows, please see NOTES.WIN.
OpenSSL uses the compiler to link programs and shared libraries 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 objects. Because of this, any linking option that's given to the
configuration scripts MUST be in a form that the compiler can accept. configuration scripts MUST be in a form that the compiler can accept.
This varies between systems, where some have compilers that 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, 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 Shared libraries and installation in non-default locations
---------------------------------------------------------- ----------------------------------------------------------
Every Unix system has its own set of default locations for shared 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 libraries are installed in non-default locations, dynamically linked
binaries will not find them and therefore fail to run, unless they get 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. 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 scripts do NOT generally set the runtime shared library search path for
you. It's therefore advisable to set it explicitly when configuring, you. It's therefore advisable to set it explicitly when configuring,
unless the libraries are to be installed in directories that you know 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 Possible options to set the runtime shared library search path include
the following: the following:
-Wl,-rpath,/whatever/path # Linux, *BSD, etc. -Wl,-rpath,/whatever/path # Linux, *BSD, etc.
-R /whatever/path # Solaris -R /whatever/path # Solaris
-Wl,-R,/whatever/path # AIX (-bsvr4 is passed internally) -Wl,-R,/whatever/path # AIX (-bsvr4 is passed internally)
-Wl,+b,/whatever/path # HP-UX -Wl,+b,/whatever/path # HP-UX
-rpath /whatever/path # Tru64, IRIX -rpath /whatever/path # Tru64, IRIX
OpenSSL's configuration scripts recognise all these options and pass OpenSSL's configuration scripts recognise all these options and pass
them to the Makefile that they build. (In fact, all arguments starting 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 Please do not use verbatim directories in your runtime shared library
search path! Some OpenSSL config targets add an extra directory level search path! Some OpenSSL config targets add an extra directory level
@ -63,28 +61,27 @@
'-Wl,-rpath,$(LIBRPATH)' '-Wl,-rpath,$(LIBRPATH)'
On modern ELF based systems, there are two runtime search paths tags to 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: this order:
1. Using directories specified in DT_RPATH, unless DT_RUNPATH is 1. Using directories specified in DT_RPATH, unless DT_RUNPATH is also set.
also set. 2. Using the environment variable LD_LIBRARY_PATH
2. Using the environment variable LD_LIBRARY_PATH 3. Using directories specified in DT_RUNPATH.
3. Using directories specified in DT_RUNPATH. 4. Using system shared object caches and default directories.
4. Using system shared object caches and default directories.
This means that the values in the environment variable LD_LIBRARY_PATH 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 won't matter if the library is found in the paths given by `DT_RPATH`
(and DT_RUNPATH isn't set). (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, depend on the system. For example, according to documentation,
DT_RPATH appears to be deprecated on Solaris in favor of DT_RUNPATH, `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 while on Debian GNU/Linux, either can be set, and `DT_RPATH` is the
default at the time of writing. default at the time of writing.
How to choose which runtime search path tag is to be set depends on 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 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 Debian GNU/Linux systems rather than DT_RPATH is to tell the linker to
set new dtags, like this: set new dtags, like this:
@ -93,7 +90,7 @@
It might be worth noting that some/most ELF systems implement support It might be worth noting that some/most ELF systems implement support
for runtime search path relative to the directory containing current 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. variables. Consult your system documentation.
Linking your application Linking your application
@ -104,7 +101,7 @@
The OpenSSL config options mentioned above might or might not have bearing The OpenSSL config options mentioned above might or might not have bearing
on linking of the target application. "Might" means that under some on linking of the target application. "Might" means that under some
circumstances it would be sufficient to link with OpenSSL shared library 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 also cases when you'd have to explicitly specify runtime search path
when linking your application. Consult your system documentation and use when linking your application. Consult your system documentation and use
above section as inspiration... above section as inspiration...
@ -114,4 +111,4 @@
for shared libraries first and tend to remain "blind" to static OpenSSL for shared libraries first and tend to remain "blind" to static OpenSSL
libraries. Referring to system documentation would suffice, if not for libraries. Referring to system documentation would suffice, if not for
a corner case. On AIX static libraries (in shared build) are named 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`.

32
NOTES-VMS.md
View file

@ -1,17 +1,15 @@
NOTES FOR THE OPENVMS PLATFORM
NOTES FOR THE OPENVMS PLATFORM ==============================
==============================
Requirement details Requirement details
------------------- -------------------
In addition to the requirements and instructions listed in INSTALL, In addition to the requirements and instructions listed
this are required as well: in [INSTALL.md](INSTALL.md), this are required as well:
* At least ODS-5 disk organization for source and build. * At least ODS-5 disk organization for source and build.
Installation can be done on any existing disk organization. Installation can be done on any existing disk organization.
About ANSI C compiler About ANSI C compiler
--------------------- ---------------------
@ -22,20 +20,19 @@
version 7.1 or later. Compiling with a different ANSI C compiler may version 7.1 or later. Compiling with a different ANSI C compiler may
require some work. 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 and testing OpenSSL. Most of all, they can be disruptive when
running the tests, as they affect the Perl interpreter. running the tests, as they affect the Perl interpreter.
About ODS-5 directory names and Perl 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 doesn't treat file specifications where the last directory name
contains periods very well. Unfortunately, some versions of VMS tar contains periods very well. Unfortunately, some versions of VMS tar
will keep the periods in the OpenSSL source directory instead of will keep the periods in the OpenSSL source directory instead of
converting them to underscore, thereby leaving your source in 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. configuring and building OpenSSL.
We have no replacement for Perl's canonpath(), so the best workaround 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 $ rename openssl-1^.1^.0.DIR openssl-1_1_0.DIR
About MMS and DCL About MMS and DCL
----------------- -----------------
@ -55,7 +51,6 @@
yourself up a few logical names for the directory trees you're going yourself up a few logical names for the directory trees you're going
to use. to use.
About debugging About debugging
--------------- ---------------
@ -68,7 +63,7 @@
directly for debugging. Do not try to use them from a script, such directly for debugging. Do not try to use them from a script, such
as running the test suite. 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 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, 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 $ set image /flag=nocall_debug [.test]evp_test.exe
Checking the distribution Checking the distribution
------------------------- -------------------------
@ -92,16 +86,16 @@
The easiest way to check if everything got through as it should is to The easiest way to check if everything got through as it should is to
check for one of the following files: 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 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 tar file from ftp://ftp.openssl.org/source/, use `GZIP -d` to uncompress
it and VMSTAR to unpack the resulting tar file. it and `VMSTAR` to unpack the resulting tar file.
Gzip and VMSTAR are available here: 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: 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>

34
NOTES-Valgrind.md
View file

@ -1,4 +1,3 @@
NOTES FOR VALGRIND NOTES FOR VALGRIND
================== ==================
@ -14,11 +13,11 @@ Requirements
------------ ------------
1. Platform supported by Valgrind 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 2. Valgrind installed on the platform
See: http://valgrind.org/downloads/current.html See <http://valgrind.org/downloads/current.html>
3. OpensSSL compiled 3. OpensSSL compiled
See: [INSTALL.md](INSTALL.md) See [INSTALL.md](INSTALL.md)
Running Tests Running Tests
------------- -------------
@ -28,18 +27,19 @@ Test behavior can be modified by adjusting environment variables.
`EXE_SHELL` `EXE_SHELL`
This variable is used to specify the shell used to execute OpenSSL test 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 allow programs to find shared libraries. The variable can be modified
to specify a different executable environment. 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). This will start up Valgrind with the default checker (`memcheck`).
The --error-exitcode=1 option specifies that Valgrind should exit with an The `--error-exitcode=1` option specifies that Valgrind should exit with an
error code of 1 when memory leaks occur. error code of 1 when memory leaks occur.
The --leak-check=full option specifies extensive memory checking. The `--leak-check=full` option specifies extensive memory checking.
The -q option prints only error messages. The `-q` option prints only error messages.
Additional Valgrind options may be added to the EXE_SHELL variable. Additional Valgrind options may be added to the `EXE_SHELL` variable.
`OPENSSL_ia32cap` `OPENSSL_ia32cap`
@ -55,16 +55,18 @@ supported. Setting the following disables instructions beyond AVX2:
This variable may need to be set to something different based on the This variable may need to be set to something different based on the
processor and Valgrind version you are running tests on. More information processor and Valgrind version you are running tests on. More information
may be found in [docs/man3/OPENSSL_ia32cap.pod](docs/man3/OPENSSL_ia32cap.pod). may be found in [doc/man3/OPENSSL_ia32cap.pod](doc/man3/OPENSSL_ia32cap.pod).
Additional variables (such as `VERBOSE` and `TESTS`) are described in the Additional variables (such as `VERBOSE` and `TESTS`) are described in the
file [test/README.md](test/README.md). file [test/README.md](test/README.md).
Example command line: Example command line:
$ make test EXE_SHELL="`/bin/pwd`/util/wrap.pl valgrind --error-exitcode=1 --leak-check=full -q" OPENSSL_ia32cap=":0" $ make test EXE_SHELL="`/bin/pwd`/util/wrap.pl valgrind --error-exitcode=1 \
--leak-check=full -q" OPENSSL_ia32cap=":0"
If an error occurs, you can then run the specific test via the `TESTS` If an error occurs, you can then run the specific test via the `TESTS` variable
variable with the VERBOSE option to gather additional information. with the `VERBOSE` or `VF` or `VFP` options to gather additional information.
$ make test VERBOSE=1 TESTS=test_test EXE_SHELL="`/bin/pwd`/util/wrap.pl valgrind --error-exitcode=1 --leak-check=full -q" OPENSSL_ia32cap=":0" $ make test VERBOSE=1 TESTS=test_test EXE_SHELL="`/bin/pwd`/util/wrap.pl \
valgrind --error-exitcode=1 --leak-check=full -q" OPENSSL_ia32cap=":0"

315
README-Engine.md
View file

@ -1,5 +1,5 @@
ENGINE ENGINES
====== =======
With OpenSSL 0.9.6, a new component was added to support alternative With OpenSSL 0.9.6, a new component was added to support alternative
cryptography implementations, most commonly for interfacing with external cryptography implementations, most commonly for interfacing with external
@ -13,9 +13,9 @@
There are currently built-in ENGINE implementations for the following There are currently built-in ENGINE implementations for the following
crypto devices: crypto devices:
o Microsoft CryptoAPI * Microsoft CryptoAPI
o VIA Padlock * VIA Padlock
o nCipher CHIL * nCipher CHIL
In addition, dynamic binding to external ENGINE implementations is now In addition, dynamic binding to external ENGINE implementations is now
provided by a special ENGINE called "dynamic". See the "DYNAMIC ENGINE" provided by a special ENGINE called "dynamic". See the "DYNAMIC ENGINE"
@ -23,16 +23,22 @@
At this stage, a number of things are still needed and are being worked on: At this stage, a number of things are still needed and are being worked on:
1 Integration of EVP support. 1. Integration of EVP support.
2 Configuration support. 2. Configuration support.
3 Documentation! 3. Documentation!
1 With respect to EVP, this relates to support for ciphers and digests in Integration of EVP support
--------------------------
With respect to EVP, this relates to support for ciphers and digests in
the ENGINE model so that alternative implementations of existing the ENGINE model so that alternative implementations of existing
algorithms/modes (or previously unimplemented ones) can be provided by algorithms/modes (or previously unimplemented ones) can be provided by
ENGINE implementations. ENGINE implementations.
2 Configuration support currently exists in the ENGINE API itself, in the Configuration support
---------------------
Configuration support currently exists in the ENGINE API itself, in the
form of "control commands". These allow an application to expose to the form of "control commands". These allow an application to expose to the
user/admin the set of commands and parameter types a given ENGINE user/admin the set of commands and parameter types a given ENGINE
implementation supports, and for an application to directly feed string implementation supports, and for an application to directly feed string
@ -47,10 +53,14 @@
Presently however, applications must use the ENGINE API itself to provide Presently however, applications must use the ENGINE API itself to provide
such functionality. To see first hand the types of commands available such functionality. To see first hand the types of commands available
with the various compiled-in ENGINEs (see further down for dynamic with the various compiled-in ENGINEs (see further down for dynamic
ENGINEs), use the "engine" openssl utility with full verbosity, ie; ENGINEs), use the "engine" openssl utility with full verbosity, i.e.:
openssl engine -vvvv openssl engine -vvvv
3 Documentation? Volunteers welcome! The source code is reasonably well Documentation
-------------
Documentation? Volunteers welcome! The source code is reasonably well
self-documenting, but some summaries and usage instructions are needed - self-documenting, but some summaries and usage instructions are needed -
moreover, they are needed in the same POD format the existing OpenSSL moreover, they are needed in the same POD format the existing OpenSSL
documentation is provided in. Any complete or incomplete contributions documentation is provided in. Any complete or incomplete contributions
@ -73,12 +83,12 @@
ENGINE API itself (ie. not necessarily specific to a particular ENGINE ENGINE API itself (ie. not necessarily specific to a particular ENGINE
implementation) then you should mail complete details to the relevant implementation) then you should mail complete details to the relevant
OpenSSL mailing list. For a definition of "complete details", refer to OpenSSL mailing list. For a definition of "complete details", refer to
the OpenSSL "README" file. As for which list to send it to; the OpenSSL "README" file. As for which list to send it to:
openssl-users: if you are *using* the ENGINE abstraction, either in an * openssl-users: if you are *using* the ENGINE abstraction, either in an
pre-compiled application or in your own application code. pre-compiled application or in your own application code.
openssl-dev: if you are discussing problems with OpenSSL source code. * openssl-dev: if you are discussing problems with OpenSSL source code.
USAGE USAGE
===== =====
@ -132,150 +142,161 @@
How does "dynamic" work? How does "dynamic" work?
------------------------ ------------------------
The dynamic ENGINE has a special flag in its implementation such that
every time application code asks for the 'dynamic' ENGINE, it in fact
gets its own copy of it. As such, multi-threaded code (or code that
multiplexes multiple uses of 'dynamic' in a single application in any
way at all) does not get confused by 'dynamic' being used to do many
independent things. Other ENGINEs typically don't do this so there is
only ever 1 ENGINE structure of its type (and reference counts are used
to keep order). The dynamic ENGINE itself provides absolutely no
cryptographic functionality, and any attempt to "initialise" the ENGINE
automatically fails. All it does provide are a few "control commands"
that can be used to control how it will load an external ENGINE
implementation from a shared-library. To see these control commands,
use the command-line;
openssl engine -vvvv dynamic The dynamic ENGINE has a special flag in its implementation such that
every time application code asks for the 'dynamic' ENGINE, it in fact
gets its own copy of it. As such, multi-threaded code (or code that
multiplexes multiple uses of 'dynamic' in a single application in any
way at all) does not get confused by 'dynamic' being used to do many
independent things. Other ENGINEs typically don't do this so there is
only ever 1 ENGINE structure of its type (and reference counts are used
to keep order). The dynamic ENGINE itself provides absolutely no
cryptographic functionality, and any attempt to "initialise" the ENGINE
automatically fails. All it does provide are a few "control commands"
that can be used to control how it will load an external ENGINE
implementation from a shared-library. To see these control commands,
use the command-line;
The "SO_PATH" control command should be used to identify the openssl engine -vvvv dynamic
shared-library that contains the ENGINE implementation, and "NO_VCHECK"
might possibly be useful if there is a minor version conflict and you
(or a vendor helpdesk) is convinced you can safely ignore it.
"ID" is probably only needed if a shared-library implements
multiple ENGINEs, but if you know the engine id you expect to be using,
it doesn't hurt to specify it (and this provides a sanity check if
nothing else). "LIST_ADD" is only required if you actually wish the
loaded ENGINE to be discoverable by application code later on using the
ENGINE's "id". For most applications, this isn't necessary - but some
application authors may have nifty reasons for using it. The "LOAD"
command is the only one that takes no parameters and is the command
that uses the settings from any previous commands to actually *load*
the shared-library ENGINE implementation. If this command succeeds, the
(copy of the) 'dynamic' ENGINE will magically morph into the ENGINE
that has been loaded from the shared-library. As such, any control
commands supported by the loaded ENGINE could then be executed as per
normal. Eg. if ENGINE "foo" is implemented in the shared-library
"libfoo.so" and it supports some special control command "CMD_FOO", the
following code would load and use it (NB: obviously this code has no
error checking);
ENGINE *e = ENGINE_by_id("dynamic"); The "SO_PATH" control command should be used to identify the
ENGINE_ctrl_cmd_string(e, "SO_PATH", "/lib/libfoo.so", 0); shared-library that contains the ENGINE implementation, and "NO_VCHECK"
ENGINE_ctrl_cmd_string(e, "ID", "foo", 0); might possibly be useful if there is a minor version conflict and you
ENGINE_ctrl_cmd_string(e, "LOAD", NULL, 0); (or a vendor helpdesk) is convinced you can safely ignore it.
ENGINE_ctrl_cmd_string(e, "CMD_FOO", "some input data", 0); "ID" is probably only needed if a shared-library implements
multiple ENGINEs, but if you know the engine id you expect to be using,
it doesn't hurt to specify it (and this provides a sanity check if
nothing else). "LIST_ADD" is only required if you actually wish the
loaded ENGINE to be discoverable by application code later on using the
ENGINE's "id". For most applications, this isn't necessary - but some
application authors may have nifty reasons for using it. The "LOAD"
command is the only one that takes no parameters and is the command
that uses the settings from any previous commands to actually *load*
the shared-library ENGINE implementation. If this command succeeds, the
(copy of the) 'dynamic' ENGINE will magically morph into the ENGINE
that has been loaded from the shared-library. As such, any control
commands supported by the loaded ENGINE could then be executed as per
normal. Eg. if ENGINE "foo" is implemented in the shared-library
"libfoo.so" and it supports some special control command "CMD_FOO", the
following code would load and use it (NB: obviously this code has no
error checking);
For testing, the "openssl engine" utility can be useful for this sort ENGINE *e = ENGINE_by_id("dynamic");
of thing. For example the above code excerpt would achieve much the ENGINE_ctrl_cmd_string(e, "SO_PATH", "/lib/libfoo.so", 0);
same result as; ENGINE_ctrl_cmd_string(e, "ID", "foo", 0);
ENGINE_ctrl_cmd_string(e, "LOAD", NULL, 0);
ENGINE_ctrl_cmd_string(e, "CMD_FOO", "some input data", 0);
openssl engine dynamic \ For testing, the "openssl engine" utility can be useful for this sort
-pre SO_PATH:/lib/libfoo.so \ of thing. For example the above code excerpt would achieve much the
-pre ID:foo \ same result as;
-pre LOAD \
-pre "CMD_FOO:some input data"
Or to simply see the list of commands supported by the "foo" ENGINE; openssl engine dynamic \
-pre SO_PATH:/lib/libfoo.so \
-pre ID:foo \
-pre LOAD \
-pre "CMD_FOO:some input data"
openssl engine -vvvv dynamic \ Or to simply see the list of commands supported by the "foo" ENGINE;
-pre SO_PATH:/lib/libfoo.so \
-pre ID:foo \
-pre LOAD
Applications that support the ENGINE API and more specifically, the openssl engine -vvvv dynamic \
"control commands" mechanism, will provide some way for you to pass -pre SO_PATH:/lib/libfoo.so \
such commands through to ENGINEs. As such, you would select "dynamic" -pre ID:foo \
as the ENGINE to use, and the parameters/commands you pass would -pre LOAD
control the *actual* ENGINE used. Each command is actually a name-value
pair and the value can sometimes be omitted (eg. the "LOAD" command). Applications that support the ENGINE API and more specifically, the
Whilst the syntax demonstrated in "openssl engine" uses a colon to "control commands" mechanism, will provide some way for you to pass
separate the command name from the value, applications may provide such commands through to ENGINEs. As such, you would select "dynamic"
their own syntax for making that separation (eg. a win32 registry as the ENGINE to use, and the parameters/commands you pass would
key-value pair may be used by some applications). The reason for the control the *actual* ENGINE used. Each command is actually a name-value
"-pre" syntax in the "openssl engine" utility is that some commands pair and the value can sometimes be omitted (eg. the "LOAD" command).
might be issued to an ENGINE *after* it has been initialised for use. Whilst the syntax demonstrated in "openssl engine" uses a colon to
Eg. if an ENGINE implementation requires a smart-card to be inserted separate the command name from the value, applications may provide
during initialisation (or a PIN to be typed, or whatever), there may be their own syntax for making that separation (eg. a win32 registry
a control command you can issue afterwards to "forget" the smart-card key-value pair may be used by some applications). The reason for the
so that additional initialisation is no longer possible. In "-pre" syntax in the "openssl engine" utility is that some commands
applications such as web-servers, where potentially volatile code may might be issued to an ENGINE *after* it has been initialised for use.
run on the same host system, this may provide some arguable security Eg. if an ENGINE implementation requires a smart-card to be inserted
value. In such a case, the command would be passed to the ENGINE after during initialisation (or a PIN to be typed, or whatever), there may be
it has been initialised for use, and so the "-post" switch would be a control command you can issue afterwards to "forget" the smart-card
used instead. Applications may provide a different syntax for so that additional initialisation is no longer possible. In
supporting this distinction, and some may simply not provide it at all applications such as web-servers, where potentially volatile code may
("-pre" is almost always what you're after, in reality). run on the same host system, this may provide some arguable security
value. In such a case, the command would be passed to the ENGINE after
it has been initialised for use, and so the "-post" switch would be
used instead. Applications may provide a different syntax for
supporting this distinction, and some may simply not provide it at all
("-pre" is almost always what you're after, in reality).
How do I build a "dynamic" ENGINE? How do I build a "dynamic" ENGINE?
---------------------------------- ----------------------------------
This question is trickier - currently OpenSSL bundles various ENGINE
implementations that are statically built in, and any application that
calls the "ENGINE_load_builtin_engines()" function will automatically
have all such ENGINEs available (and occupying memory). Applications
that don't call that function have no ENGINEs available like that and
would have to use "dynamic" to load any such ENGINE - but on the other
hand such applications would only have the memory footprint of any
ENGINEs explicitly loaded using user/admin provided control commands.
The main advantage of not statically linking ENGINEs and only using
"dynamic" for hardware support is that any installation using no
"external" ENGINE suffers no unnecessary memory footprint from unused
ENGINEs. Likewise, installations that do require an ENGINE incur the
overheads from only *that* ENGINE once it has been loaded.
Sounds good? Maybe, but currently building an ENGINE implementation as This question is trickier - currently OpenSSL bundles various ENGINE
a shared-library that can be loaded by "dynamic" isn't automated in implementations that are statically built in, and any application that
OpenSSL's build process. It can be done manually quite easily however. calls the "ENGINE_load_builtin_engines()" function will automatically
Such a shared-library can either be built with any OpenSSL code it have all such ENGINEs available (and occupying memory). Applications
needs statically linked in, or it can link dynamically against OpenSSL that don't call that function have no ENGINEs available like that and
if OpenSSL itself is built as a shared library. The instructions are would have to use "dynamic" to load any such ENGINE - but on the other
the same in each case, but in the former (statically linked any hand such applications would only have the memory footprint of any
dependencies on OpenSSL) you must ensure OpenSSL is built with ENGINEs explicitly loaded using user/admin provided control commands.
position-independent code ("PIC"). The default OpenSSL compilation may The main advantage of not statically linking ENGINEs and only using
already specify the relevant flags to do this, but you should consult "dynamic" for hardware support is that any installation using no
with your compiler documentation if you are in any doubt. "external" ENGINE suffers no unnecessary memory footprint from unused
ENGINEs. Likewise, installations that do require an ENGINE incur the
overheads from only *that* ENGINE once it has been loaded.
This example will show building the "atalla" ENGINE in the Sounds good? Maybe, but currently building an ENGINE implementation as
crypto/engine/ directory as a shared-library for use via the "dynamic" a shared-library that can be loaded by "dynamic" isn't automated in
ENGINE. OpenSSL's build process. It can be done manually quite easily however.
1) "cd" to the crypto/engine/ directory of a pre-compiled OpenSSL Such a shared-library can either be built with any OpenSSL code it
source tree. needs statically linked in, or it can link dynamically against OpenSSL
2) Recompile at least one source file so you can see all the compiler if OpenSSL itself is built as a shared library. The instructions are
flags (and syntax) being used to build normally. Eg; the same in each case, but in the former (statically linked any
touch hw_atalla.c ; make dependencies on OpenSSL) you must ensure OpenSSL is built with
will rebuild "hw_atalla.o" using all such flags. position-independent code ("PIC"). The default OpenSSL compilation may
3) Manually enter the same compilation line to compile the already specify the relevant flags to do this, but you should consult
"hw_atalla.c" file but with the following two changes; with your compiler documentation if you are in any doubt.
(a) add "-DENGINE_DYNAMIC_SUPPORT" to the command line switches,
(b) change the output file from "hw_atalla.o" to something new, This example will show building the "atalla" ENGINE in the
eg. "tmp_atalla.o" crypto/engine/ directory as a shared-library for use via the "dynamic"
4) Link "tmp_atalla.o" into a shared-library using the top-level ENGINE.
OpenSSL libraries to resolve any dependencies. The syntax for doing
this depends heavily on your system/compiler and is a nightmare 1. "cd" to the crypto/engine/ directory of a pre-compiled OpenSSL
known well to anyone who has worked with shared-library portability source tree.
before. 'gcc' on Linux, for example, would use the following syntax;
gcc -shared -o dyn_atalla.so tmp_atalla.o -L../.. -lcrypto 2. Recompile at least one source file so you can see all the compiler
5) Test your shared library using "openssl engine" as explained in the flags (and syntax) being used to build normally. Eg;
previous section. Eg. from the top-level directory, you might try;
apps/openssl engine -vvvv dynamic \ touch hw_atalla.c ; make
-pre SO_PATH:./crypto/engine/dyn_atalla.so -pre LOAD
If the shared-library loads successfully, you will see both "-pre" will rebuild "hw_atalla.o" using all such flags.
commands marked as "SUCCESS" and the list of control commands
displayed (because of "-vvvv") will be the control commands for the 3. Manually enter the same compilation line to compile the
*atalla* ENGINE (ie. *not* the 'dynamic' ENGINE). You can also add "hw_atalla.c" file but with the following two changes;
the "-t" switch to the utility if you want it to try and initialise * add "-DENGINE_DYNAMIC_SUPPORT" to the command line switches,
the atalla ENGINE for use to test any possible hardware/driver * change the output file from "hw_atalla.o" to something new,
issues. eg. "tmp_atalla.o"
4. Link "tmp_atalla.o" into a shared-library using the top-level
OpenSSL libraries to resolve any dependencies. The syntax for doing
this depends heavily on your system/compiler and is a nightmare
known well to anyone who has worked with shared-library portability
before. 'gcc' on Linux, for example, would use the following syntax;
gcc -shared -o dyn_atalla.so tmp_atalla.o -L../.. -lcrypto
5. Test your shared library using "openssl engine" as explained in the
previous section. Eg. from the top-level directory, you might try
apps/openssl engine -vvvv dynamic \
-pre SO_PATH:./crypto/engine/dyn_atalla.so -pre LOAD
If the shared-library loads successfully, you will see both "-pre"
commands marked as "SUCCESS" and the list of control commands
displayed (because of "-vvvv") will be the control commands for the
*atalla* ENGINE (ie. *not* the 'dynamic' ENGINE). You can also add
the "-t" switch to the utility if you want it to try and initialise
the atalla ENGINE for use to test any possible hardware/driver issues.
PROBLEMS PROBLEMS
======== ========

3
README-FIPS.md
View file

@ -1 +1,4 @@
OpenSSL FIPS support
====================
This release does not support a FIPS 140-2 validated module. This release does not support a FIPS 140-2 validated module.

14
README.md
View file

@ -105,13 +105,13 @@ detailed instructions about building and installing OpenSSL. For some
platforms, the installation instructions are amended by a platform specific platforms, the installation instructions are amended by a platform specific
document. document.
* [NOTES.ANDROID](NOTES.ANDROID) * [NOTES-Android.md](NOTES-Android.md)
* [NOTES.DJGPP](NOTES.DJGPP) * [NOTES-DJGPP.md](NOTES-DJGPP.md)
* [NOTES.PERL](NOTES.PERL) * [NOTES-Unix.md](NOTES-Unix.md)
* [NOTES.UNIX](NOTES.UNIX) * [NOTES-VMS.md](NOTES-VMS.md)
* [NOTES.VALGRIND](NOTES.VALGRIND) * [NOTES-Windows.txt](NOTES-Windows.txt)
* [NOTES.VMS](NOTES.VMS) * [NOTES-Perl.m](NOTES-Perl.md)
* [NOTES.WIN](NOTES.WIN) * [NOTES-Valgrind.md](NOTES-Valgrind.md)
Specific notes on upgrading to OpenSSL 3.0 from previous versions, as well as Specific notes on upgrading to OpenSSL 3.0 from previous versions, as well as
known issues are available on the OpenSSL known issues are available on the OpenSSL

7
VERSION.txt
View file

@ -1,7 +0,0 @@
MAJOR=3
MINOR=0
PATCH=0
PRE_RELEASE_TAG=alpha4-dev
BUILD_METADATA=
RELEASE_DATE=""
SHLIB_VERSION=3

17
crypto/README-sparse_array.md
View file

@ -1,4 +1,7 @@
The sparse_array.c file contains an implementation of a sparse array that Sparse Arrays
=============
The `sparse_array.c` file contains an implementation of a sparse array that
attempts to be both space and time efficient. attempts to be both space and time efficient.
The sparse array is represented using a tree structure. Each node in the The sparse array is represented using a tree structure. Each node in the
@ -13,13 +16,14 @@ There are a number of parameters used to define the block size:
SA_BLOCK_MAX_LEVELS Indicates the maximum possible height of the tree SA_BLOCK_MAX_LEVELS Indicates the maximum possible height of the tree
These constants are inter-related: These constants are inter-related:
SA_BLOCK_MAX = 2 ^ OPENSSL_SA_BLOCK_BITS SA_BLOCK_MAX = 2 ^ OPENSSL_SA_BLOCK_BITS
SA_BLOCK_MASK = SA_BLOCK_MAX - 1 SA_BLOCK_MASK = SA_BLOCK_MAX - 1
SA_BLOCK_MAX_LEVELS = number of bits in size_t divided by SA_BLOCK_MAX_LEVELS = number of bits in size_t divided by
OPENSSL_SA_BLOCK_BITS rounded up to the next multiple OPENSSL_SA_BLOCK_BITS rounded up to the next multiple
of OPENSSL_SA_BLOCK_BITS of OPENSSL_SA_BLOCK_BITS
OPENSSL_SA_BLOCK_BITS can be defined at compile time and this overrides the `OPENSSL_SA_BLOCK_BITS` can be defined at compile time and this overrides the
built in setting. built in setting.
As a space and performance optimisation, the height of the tree is usually As a space and performance optimisation, the height of the tree is usually
@ -67,7 +71,6 @@ brevity):
+----+ +----+
Index 0 Index 0
Inserting at element 2N+1 creates a new root node and pushes down the old root Inserting at element 2N+1 creates a new root node and pushes down the old root
node. It then creates a second second level node to hold the pointer to the node. It then creates a second second level node to hold the pointer to the
user's new data: user's new data:
@ -102,7 +105,6 @@ user's new data:
+----+ +----+ +----+ +----+
Index 0 Index 2N+1 Index 0 Index 2N+1
The nodes themselves are allocated in a sparse manner. Only nodes which exist The nodes themselves are allocated in a sparse manner. Only nodes which exist
along a path from the root of the tree to an added leaf will be allocated. along a path from the root of the tree to an added leaf will be allocated.
The complexity is hidden and nodes are allocated on an as needed basis. The complexity is hidden and nodes are allocated on an as needed basis.
@ -144,12 +146,11 @@ result in:
+----+ +----+
Index 2N+1 Index 2N+1
Accesses to elements in the sparse array take O(log n) time where n is the Accesses to elements in the sparse array take O(log n) time where n is the
largest element. The base of the logarithm is SA_BLOCK_MAX, so for moderately largest element. The base of the logarithm is `SA_BLOCK_MAX`, so for moderately
small indices (e.g. NIDs), single level (constant time) access is achievable. small indices (e.g. NIDs), single level (constant time) access is achievable.
Space usage is O(minimum(m, n log(n)) where m is the number of elements in the Space usage is O(minimum(m, n log(n)) where m is the number of elements in the
array. array.
Note: sparse arrays only include pointers to types. Thus, SPARSE_ARRAY_OF(char) Note: sparse arrays only include pointers to types.
can be used to store a string. Thus, `SPARSE_ARRAY_OF(char)` can be used to store a string.

27
crypto/engine/README.md
View file

@ -1,12 +1,12 @@
Notes: 2001-09-24 Notes on engines of 2001-09-24
----------------- ==============================
This "description" (if one chooses to call it that) needed some major updating This "description" (if one chooses to call it that) needed some major updating
so here goes. This update addresses a change being made at the same time to so here goes. This update addresses a change being made at the same time to
OpenSSL, and it pretty much completely restructures the underlying mechanics of OpenSSL, and it pretty much completely restructures the underlying mechanics of
the "ENGINE" code. So it serves a double purpose of being a "ENGINE internals the "ENGINE" code. So it serves a double purpose of being a "ENGINE internals
for masochists" document *and* a rather extensive commit log message. (I'd get for masochists" document *and* a rather extensive commit log message. (I'd get
lynched for sticking all this in CHANGES or the commit mails :-). lynched for sticking all this in CHANGES.md or the commit mails :-).
ENGINE_TABLE underlies this restructuring, as described in the internal header ENGINE_TABLE underlies this restructuring, as described in the internal header
"eng_local.h", implemented in eng_table.c, and used in each of the "class" files; "eng_local.h", implemented in eng_table.c, and used in each of the "class" files;
@ -21,16 +21,16 @@ or can be loaded "en masse" into EVP storage so that they can be catalogued and
searched in various ways, ie. two ways of encrypting with the "des_cbc" searched in various ways, ie. two ways of encrypting with the "des_cbc"
algorithm/mode pair are; algorithm/mode pair are;
(i) directly; (i) directly;
const EVP_CIPHER *cipher = EVP_des_cbc(); const EVP_CIPHER *cipher = EVP_des_cbc();
EVP_EncryptInit(&ctx, cipher, key, iv); EVP_EncryptInit(&ctx, cipher, key, iv);
[ ... use EVP_EncryptUpdate() and EVP_EncryptFinal() ...] [ ... use EVP_EncryptUpdate() and EVP_EncryptFinal() ...]
(ii) indirectly; (ii) indirectly;
OpenSSL_add_all_ciphers(); OpenSSL_add_all_ciphers();
cipher = EVP_get_cipherbyname("des_cbc"); cipher = EVP_get_cipherbyname("des_cbc");
EVP_EncryptInit(&ctx, cipher, key, iv); EVP_EncryptInit(&ctx, cipher, key, iv);
[ ... etc ... ] [ ... etc ... ]
The latter is more generally used because it also allows ciphers/digests to be The latter is more generally used because it also allows ciphers/digests to be
looked up based on other identifiers which can be useful for automatic cipher looked up based on other identifiers which can be useful for automatic cipher
@ -177,7 +177,7 @@ is deliberately a distinct step. Moreover, registration and unregistration has
nothing to do with whether an ENGINE is *functional* or not (ie. you can even nothing to do with whether an ENGINE is *functional* or not (ie. you can even
register an ENGINE and its implementations without it being operational, you may register an ENGINE and its implementations without it being operational, you may
not even have the drivers to make it operate). What actually happens with not even have the drivers to make it operate). What actually happens with
respect to cleanup is managed inside eng_lib.c with the "engine_cleanup_***" respect to cleanup is managed inside eng_lib.c with the `engine_cleanup_***`
functions. These functions are internal-only and each part of ENGINE code that functions. These functions are internal-only and each part of ENGINE code that
could require cleanup will, upon performing its first allocation, register a could require cleanup will, upon performing its first allocation, register a
callback with the "engine_cleanup" code. The other part of this that makes it callback with the "engine_cleanup" code. The other part of this that makes it
@ -208,4 +208,3 @@ hooking of ENGINE is now automatic (and passive, it can internally use a NULL
ENGINE pointer to simply ignore ENGINE from then on). ENGINE pointer to simply ignore ENGINE from then on).
Hell, that should be enough for now ... comments welcome. Hell, that should be enough for now ... comments welcome.

24
crypto/err/README.md
View file

@ -1,17 +1,17 @@
Adding new libraries Adding new libraries
-------------------- ====================
When adding a new sub-library to OpenSSL, assign it a library number When adding a new sub-library to OpenSSL, assign it a library number
ERR_LIB_XXX, define a macro XXXerr() (both in err.h), add its `ERR_LIB_XXX`, define a macro `XXXerr()` (both in `err.h`), add its
name to ERR_str_libraries[] (in crypto/err/err.c), and add name to `ERR_str_libraries[]` (in `crypto/err/err.c`), and add
ERR_load_XXX_strings() to the ERR_load_crypto_strings() function `ERR_load_XXX_strings()` to the `ERR_load_crypto_strings()` function
(in crypto/err/err_all.c). Finally, add an entry: (in `crypto/err/err_all.c`). Finally, add an entry:
L XXX xxx.h xxx_err.c L XXX xxx.h xxx_err.c
to crypto/err/openssl.ec, and add xxx_err.c to the Makefile. to `crypto/err/openssl.ec`, and add `xxx_err.c` to the `Makefile`.
Running make errors will then generate a file xxx_err.c, and Running make errors will then generate a file `xxx_err.c`, and
add all error codes used in the library to xxx.h. add all error codes used in the library to `xxx.h`.
Additionally the library include file must have a certain form. Additionally the library include file must have a certain form.
Typically it will initially look like this: Typically it will initially look like this:
@ -33,12 +33,12 @@ Typically it will initially look like this:
/* BEGIN ERROR CODES */ /* BEGIN ERROR CODES */
The BEGIN ERROR CODES sequence is used by the error code The `BEGIN ERROR CODES` sequence is used by the error code
generation script as the point to place new error codes, any text generation script as the point to place new error codes, any text
after this point will be overwritten when make errors is run. after this point will be overwritten when make errors is run.
The closing #endif etc will be automatically added by the script. The closing `#endif` etc will be automatically added by the script.
The generated C error code file xxx_err.c will load the header The generated C error code file `xxx_err.c` will load the header
files stdio.h, openssl/err.h and openssl/xxx.h so the files `stdio.h`, `openssl/err.h` and `openssl/xxx.h` so the
header file must load any additional header files containing any header file must load any additional header files containing any
definitions it uses. definitions it uses.

51
crypto/objects/README.md
View file

@ -1,44 +1,43 @@
objects.txt syntax objects.txt syntax
------------------ ==================
To cover all the naming hacks that were previously in objects.h needed some To cover all the naming hacks that were previously in `objects.h` needed some
kind of hacks in objects.txt. kind of hacks in `objects.txt`.
The basic syntax for adding an object is as follows: The basic syntax for adding an object is as follows:
1 2 3 4 : shortName : Long Name 1 2 3 4 : shortName : Long Name
If Long Name contains only word characters and hyphen-minus If Long Name contains only word characters and hyphen-minus
(0x2D) or full stop (0x2E) then Long Name is used as basis (0x2D) or full stop (0x2E) then Long Name is used as basis
for the base name in C. Otherwise, the shortName is used. for the base name in C. Otherwise, the shortName is used.
The base name (let's call it 'base') will then be used to The base name (let's call it 'base') will then be used to
create the C macros SN_base, LN_base, NID_base and OBJ_base. create the C macros SN_base, LN_base, NID_base and OBJ_base.
Note that if the base name contains spaces, dashes or periods, Note that if the base name contains spaces, dashes or periods,
those will be converted to underscore. those will be converted to underscore.
Then there are some extra commands: Then there are some extra commands:
!Alias foo 1 2 3 4 !Alias foo 1 2 3 4
This just makes a name foo for an OID. The C macro This just makes a name foo for an OID. The C macro
OBJ_foo will be created as a result. OBJ_foo will be created as a result.
!Cname foo !Cname foo
This makes sure that the name foo will be used as base name This makes sure that the name foo will be used as base name
in C. in C.
!module foo !module foo
1 2 3 4 : shortName : Long Name 1 2 3 4 : shortName : Long Name
!global !global
The !module command was meant to define a kind of modularity. The !module command was meant to define a kind of modularity.
What it does is to make sure the module name is prepended What it does is to make sure the module name is prepended
to the base name. !global turns this off. This construction to the base name. !global turns this off. This construction
is not recursive. is not recursive.
Lines starting with # are treated as comments, as well as any line starting Lines starting with `#` are treated as comments, as well as any line starting
with ! and not matching the commands above. with ! and not matching the commands above.

170
crypto/perlasm/README.md
View file

@ -1,124 +1,130 @@
Perl scripts for assembler sources
==================================
The perl scripts in this directory are my 'hack' to generate The perl scripts in this directory are my 'hack' to generate
multiple different assembler formats via the one original script. multiple different assembler formats via the one original script.
The way to use this library is to start with adding the path to this directory The way to use this library is to start with adding the path to this directory
and then include it. and then include it.
push(@INC,"perlasm","../../perlasm"); push(@INC,"perlasm","../../perlasm");
require "x86asm.pl"; require "x86asm.pl";
The first thing we do is setup the file and type of assembler The first thing we do is setup the file and type of assembler
&asm_init($ARGV[0]); &asm_init($ARGV[0]);
The first argument is the 'type'. Currently The first argument is the 'type'. Currently
'cpp', 'sol', 'a.out', 'elf' or 'win32'. `cpp`, `sol`, `a.out`, `elf` or `win32`.
Argument 2 is the file name. The second argument is the file name.
The reciprocal function is The reciprocal function is
&asm_finish() which should be called at the end. `&asm_finish()` which should be called at the end.
There are 2 main 'packages'. x86ms.pl, which is the Microsoft assembler, There are two main 'packages'. `x86ms.pl`, which is the Microsoft assembler,
and x86unix.pl which is the unix (gas) version. and `x86unix.pl` which is the unix (gas) version.
Functions of interest are: Functions of interest are:
&external_label("des_SPtrans"); declare and external variable
&LB(reg); Low byte for a register &external_label("des_SPtrans"); declare and external variable
&HB(reg); High byte for a register &LB(reg); Low byte for a register
&BP(off,base,index,scale) Byte pointer addressing &HB(reg); High byte for a register
&DWP(off,base,index,scale) Word pointer addressing &BP(off,base,index,scale) Byte pointer addressing
&stack_push(num) Basically a 'sub esp, num*4' with extra &DWP(off,base,index,scale) Word pointer addressing
&stack_pop(num) inverse of stack_push &stack_push(num) Basically a 'sub esp, num*4' with extra
&function_begin(name,extra) Start a function with pushing of &stack_pop(num) inverse of stack_push
edi, esi, ebx and ebp. extra is extra win32 &function_begin(name,extra) Start a function with pushing of
external info that may be required. edi, esi, ebx and ebp. extra is extra win32
&function_begin_B(name,extra) Same as normal function_begin but no pushing. external info that may be required.
&function_end(name) Call at end of function. &function_begin_B(name,extra) Same as normal function_begin but no
&function_end_A(name) Standard pop and ret, for use inside functions pushing.
&function_end_B(name) Call at end but with pop or ret. &function_end(name) Call at end of function.
&swtmp(num) Address on stack temp word. &function_end_A(name) Standard pop and ret, for use inside
&wparam(num) Parameter number num, that was push functions.
in C convention. This all works over pushes &function_end_B(name) Call at end but with pop or ret.
and pops. &swtmp(num) Address on stack temp word.
&comment("hello there") Put in a comment. &wparam(num) Parameter number num, that was push in
&label("loop") Refer to a label, normally a jmp target. C convention. This all works over pushes
&set_label("loop") Set a label at this point. and pops.
&data_word(word) Put in a word of data. &comment("hello there") Put in a comment.
&label("loop") Refer to a label, normally a jmp target.
&set_label("loop") Set a label at this point.
&data_word(word) Put in a word of data.
So how does this all hold together? Given So how does this all hold together? Given
int calc(int len, int *data) int calc(int len, int *data)
{ {
int i,j=0; int i,j=0;
for (i=0; i<len; i++) for (i=0; i<len; i++)
{ {
j+=other(data[i]); j+=other(data[i]);
} }
} }
So a very simple version of this function could be coded as So a very simple version of this function could be coded as
push(@INC,"perlasm","../../perlasm"); push(@INC,"perlasm","../../perlasm");
require "x86asm.pl"; require "x86asm.pl";
&asm_init($ARGV[0]);
&external_label("other"); &asm_init($ARGV[0]);
$tmp1= "eax"; &external_label("other");
$j= "edi";
$data= "esi";
$i= "ebp";
&comment("a simple function"); $tmp1= "eax";
&function_begin("calc"); $j= "edi";
&mov( $data, &wparam(1)); # data $data= "esi";
&xor( $j, $j); $i= "ebp";
&xor( $i, $i);
&set_label("loop"); &comment("a simple function");
&cmp( $i, &wparam(0)); &function_begin("calc");
&jge( &label("end")); &mov( $data, &wparam(1)); # data
&xor( $j, $j);
&xor( $i, $i);
&mov( $tmp1, &DWP(0,$data,$i,4)); &set_label("loop");
&push( $tmp1); &cmp( $i, &wparam(0));
&call( "other"); &jge( &label("end"));
&add( $j, "eax");
&pop( $tmp1);
&inc( $i);
&jmp( &label("loop"));
&set_label("end"); &mov( $tmp1, &DWP(0,$data,$i,4));
&mov( "eax", $j); &push( $tmp1);
&call( "other");
&add( $j, "eax");
&pop( $tmp1);
&inc( $i);
&jmp( &label("loop"));
&function_end("calc"); &set_label("end");
&mov( "eax", $j);
&asm_finish(); &function_end("calc");
&asm_finish();
The above example is very very unoptimised but gives an idea of how The above example is very very unoptimised but gives an idea of how
things work. things work.
There is also a cbc mode function generator in cbc.pl There is also a cbc mode function generator in cbc.pl
&cbc( $name, &cbc($name,
$encrypt_function_name, $encrypt_function_name,
$decrypt_function_name, $decrypt_function_name,
$true_if_byte_swap_needed, $true_if_byte_swap_needed,
$parameter_number_for_iv, $parameter_number_for_iv,
$parameter_number_for_encrypt_flag, $parameter_number_for_encrypt_flag,
$first_parameter_to_pass, $first_parameter_to_pass,
$second_parameter_to_pass, $second_parameter_to_pass,
$third_parameter_to_pass); $third_parameter_to_pass);
So for example, given So for example, given
void BF_encrypt(BF_LONG *data,BF_KEY *key);
void BF_decrypt(BF_LONG *data,BF_KEY *key);
void BF_cbc_encrypt(unsigned char *in, unsigned char *out, long length,
BF_KEY *ks, unsigned char *iv, int enc);
&cbc("BF_cbc_encrypt","BF_encrypt","BF_encrypt",1,4,5,3,-1,-1); void BF_encrypt(BF_LONG *data,BF_KEY *key);
void BF_decrypt(BF_LONG *data,BF_KEY *key);
void BF_cbc_encrypt(unsigned char *in, unsigned char *out, long length,
BF_KEY *ks, unsigned char *iv, int enc);
&cbc("des_ncbc_encrypt","des_encrypt","des_encrypt",0,4,5,3,5,-1); &cbc("BF_cbc_encrypt","BF_encrypt","BF_encrypt",1,4,5,3,-1,-1);
&cbc("des_ede3_cbc_encrypt","des_encrypt3","des_decrypt3",0,6,7,3,4,5);
&cbc("des_ncbc_encrypt","des_encrypt","des_encrypt",0,4,5,3,5,-1);
&cbc("des_ede3_cbc_encrypt","des_encrypt3","des_decrypt3",0,6,7,3,4,5);

23
crypto/property/README.md
View file

@ -1,4 +1,8 @@
Properties are associated with algorithms and are used to select between different implementations dynamically. Selecting algorithm implementations by properties
=================================================
Properties are associated with algorithms and are used to select between
different implementations dynamically.
This implementation is based on a number of assumptions: This implementation is based on a number of assumptions:
@ -23,7 +27,6 @@ This implementation is based on a number of assumptions:
* Property queries can never add new property definitions. * Property queries can never add new property definitions.
Some consequences of these assumptions are: Some consequences of these assumptions are:
* That definition is uncommon and queries are very common, we can treat * That definition is uncommon and queries are very common, we can treat
@ -52,14 +55,15 @@ Some consequences of these assumptions are:
properties are changed as doing so removes the need to index on both the properties are changed as doing so removes the need to index on both the
global and requested property strings. global and requested property strings.
The implementation: The implementation:
* property_lock.c contains some wrapper functions to handle the global * [property_lock.c](property_lock.c)
contains some wrapper functions to handle the global
lock more easily. The global lock is held for short periods of time with lock more easily. The global lock is held for short periods of time with
per algorithm locking being used for longer intervals. per algorithm locking being used for longer intervals.
* property_string.c contains the string cache which converts property * [property_string.c](property_string.c)
contains the string cache which converts property
names and values to small integer indices. Names and values are stored in names and values to small integer indices. Names and values are stored in
separate hash tables. The two Boolean values, the strings "yes" and "no", separate hash tables. The two Boolean values, the strings "yes" and "no",
are populated as the first two members of the value table. All property are populated as the first two members of the value table. All property
@ -67,13 +71,15 @@ The implementation:
provided to convert from an index back to the original string (this can be provided to convert from an index back to the original string (this can be
done by maintaining parallel stacks of strings if required). done by maintaining parallel stacks of strings if required).
* property_parse.c contains the property definition and query parsers. * [property_parse.c](property_parse.c)
contains the property definition and query parsers.
These convert ASCII strings into lists of properties. The resulting These convert ASCII strings into lists of properties. The resulting
lists are sorted by the name index. Some additional utility functions lists are sorted by the name index. Some additional utility functions
for dealing with property lists are also included: comparison of a query for dealing with property lists are also included: comparison of a query
against a definition and merging two queries into a single larger query. against a definition and merging two queries into a single larger query.
* property.c contains the main APIs for defining and using properties. * [property.c](property.c)
contains the main APIs for defining and using properties.
Algorithms are discovered from their NID and a query string. Algorithms are discovered from their NID and a query string.
The results are cached. The results are cached.
@ -82,6 +88,7 @@ The implementation:
without bounds and must garbage collect under-used entries. The garbage without bounds and must garbage collect under-used entries. The garbage
collection does not have to be exact. collection does not have to be exact.
* defn_cache.c contains a cache that maps property definition strings to * [defn_cache.c](defn_cache.c)
contains a cache that maps property definition strings to
parsed properties. It is used by property.c to improve performance when parsed properties. It is used by property.c to improve performance when
the same definition appears multiple times. the same definition appears multiple times.

2
demos/README.txt
View file

@ -1,7 +1,7 @@
NOTE: Don't expect any of these programs to work with current NOTE: Don't expect any of these programs to work with current
OpenSSL releases, or even with later SSLeay releases. OpenSSL releases, or even with later SSLeay releases.
Original README.md: Original README:
============================================================================= =============================================================================
Some demo programs sent to me by various people Some demo programs sent to me by various people

19
doc/README.md
View file

@ -1,27 +1,30 @@
OpenSSL Documentation
=====================
README.md This file README.md This file
fingerprints.txt [fingerprints.txt](fingerprints.txt)
PGP fingerprints of authorised release signers PGP fingerprints of authorised release signers
standards.txt standards.txt
Moved to the web, https://www.openssl.org/docs/standards.html standards.txt
Moved to the web, <https://www.openssl.org/docs/standards.html>
HOWTO/ [HOWTO/](HOWTO/)
A few how-to documents; not necessarily up-to-date A few how-to documents; not necessarily up-to-date
man1/ [man1/](man1/)
The openssl command-line tools; start with openssl.pod The openssl command-line tools; start with openssl.pod
man3/ [man3/](man3/)
The SSL library and the crypto library The SSL library and the crypto library
man5/ [man5/](man5/)
File formats File formats
man7/ [man7/](man7/)
Overviews; start with crypto.pod and ssl.pod, for example Overviews; start with crypto.pod and ssl.pod, for example
Algorithm specific EVP_PKEY documentation. Algorithm specific EVP_PKEY documentation.
Formatted versions of the manpages (apps,ssl,crypto) can be found at Formatted versions of the manpages (apps,ssl,crypto) can be found at
https://www.openssl.org/docs/manpages.html <https://www.openssl.org/docs/manpages.html>

61
ssl/record/README.md
View file

@ -18,10 +18,10 @@ of libssl.
The source files map to components as follows: The source files map to components as follows:
dtls1_bitmap.c -> DTLS1_BITMAP component dtls1_bitmap.c -> DTLS1_BITMAP component
ssl3_buffer.c -> SSL3_BUFFER component ssl3_buffer.c -> SSL3_BUFFER component
ssl3_record.c -> SSL3_RECORD component ssl3_record.c -> SSL3_RECORD component
rec_layer_s3.c, rec_layer_d1.c -> RECORD_LAYER component rec_layer_s3.c, rec_layer_d1.c -> RECORD_LAYER component
The RECORD_LAYER component is a facade pattern, i.e. it provides a simplified The RECORD_LAYER component is a facade pattern, i.e. it provides a simplified
interface to the record layer for the rest of libssl. The other 3 components are interface to the record layer for the rest of libssl. The other 3 components are
@ -38,33 +38,32 @@ RECORD_LAYER_* macros.
Conceptually it looks like this: Conceptually it looks like this:
libssl libssl
| |
---------------------------|-----record.h-------------------------------------- -------------------------|-----record.h------------------------------------
| |
_______V______________ _______V______________
| | | |
| RECORD_LAYER | | RECORD_LAYER |
| | | |
| rec_layer_s3.c | | rec_layer_s3.c |
| ^ | | ^ |
| _________|__________ | | _________|__________ |
|| || || ||
|| DTLS1_RECORD_LAYER || || DTLS1_RECORD_LAYER ||
|| || || ||
|| rec_layer_d1.c || || rec_layer_d1.c ||
||____________________|| ||____________________||
|______________________| |______________________|
record_local.h ^ ^ ^ record_local.h ^ ^ ^
_________________| | |_________________ _________________| | |_________________
| | | | | |
_____V_________ ______V________ _______V________ _____V_________ ______V________ _______V________
| | | | | | | | | | | |
| SSL3_BUFFER | | SSL3_RECORD | | DTLS1_BITMAP | | SSL3_BUFFER | | SSL3_RECORD | | DTLS1_BITMAP |
| |--->| | | | | |--->| | | |
| ssl3_buffer.c | | ssl3_record.c | | dtls1_bitmap.c | | ssl3_buffer.c | | ssl3_record.c | | dtls1_bitmap.c |
|_______________| |_______________| |________________| |_______________| |_______________| |________________|
The two RECORD_LAYER source files build on each other, i.e. The two RECORD_LAYER source files build on each other, i.e.
the main one is rec_layer_s3.c which provides the core SSL/TLS layer. The second the main one is rec_layer_s3.c which provides the core SSL/TLS layer. The second

96
ssl/statem/README.md
View file

@ -6,23 +6,24 @@ state machine code to aid future maintenance.
The state machine code replaces an older state machine present in OpenSSL The state machine code replaces an older state machine present in OpenSSL
versions 1.0.2 and below. The new state machine has the following objectives: versions 1.0.2 and below. The new state machine has the following objectives:
- Remove duplication of state code between client and server
- Remove duplication of state code between TLS and DTLS - Remove duplication of state code between client and server
- Simplify transitions and bring the logic together in a single location - Remove duplication of state code between TLS and DTLS
so that it is easier to validate - Simplify transitions and bring the logic together in a single location
- Remove duplication of code between each of the message handling functions so that it is easier to validate
- Receive a message first and then work out whether that is a valid - Remove duplication of code between each of the message handling functions
transition - not the other way around (the other way causes lots of issues - Receive a message first and then work out whether that is a valid
where we are expecting one type of message next but actually get something transition - not the other way around (the other way causes lots of issues
else) where we are expecting one type of message next but actually get something
- Separate message flow state from handshake state (in order to better else)
understand each) - Separate message flow state from handshake state (in order to better
- message flow state = when to flush buffers; handling restarts in the understand each)
event of NBIO events; handling the common flow of steps for reading a * message flow state = when to flush buffers; handling restarts in the
message and the common flow of steps for writing a message etc event of NBIO events; handling the common flow of steps for reading a
- handshake state = what handshake message are we working on now message and the common flow of steps for writing a message etc
- Control complexity: only the state machine can change state: keep all * handshake state = what handshake message are we working on now
the state changes local to the state machine component - Control complexity: only the state machine can change state: keep all
the state changes local to the state machine component
The message flow state machine is divided into a reading sub-state machine and a The message flow state machine is divided into a reading sub-state machine and a
writing sub-state machine. See the source comments in statem.c for a more writing sub-state machine. See the source comments in statem.c for a more
@ -30,34 +31,33 @@ detailed description of the various states and transitions possible.
Conceptually the state machine component is designed as follows: Conceptually the state machine component is designed as follows:
libssl libssl
| |
---------------------------|-----statem.h-------------------------------------- -------------------------|-----statem.h------------------------------------
| |
_______V____________________ _______V____________________
| | | |
| statem.c | | statem.c |
| | | |
| Core state machine code | | Core state machine code |
|____________________________| |____________________________|
statem_local.h ^ ^ statem_local.h ^ ^
_________| |_______ _________| |_______
| | | |
_____________|____________ _____________|____________ _____________|____________ _____________|____________
| | | | | | | |
| statem_clnt.c | | statem_srvr.c | | statem_clnt.c | | statem_srvr.c |
| | | | | | | |
| TLS/DTLS client specific | | TLS/DTLS server specific | | TLS/DTLS client specific | | TLS/DTLS server specific |
| state machine code | | state machine code | | state machine code | | state machine code |
|__________________________| |__________________________| |__________________________| |__________________________|
| |_______________|__ | | |_______________|__ |
| ________________| | | | ________________| | |
| | | | | | | |
____________V_______V________ ________V______V_______________ ____________V_______V________ ________V______V_______________
| | | | | | | |
| statem_both.c | | statem_dtls.c | | statem_both.c | | statem_dtls.c |
| | | | | | | |
| Non core functions common | | Non core functions common to | | Non core functions common | | Non core functions common to |
| to both servers and clients | | both DTLS servers and clients | | to both servers and clients | | both DTLS servers and clients |
|_____________________________| |_______________________________| |_____________________________| |_______________________________|

85
test/README-external.md
View file

@ -1,12 +1,10 @@
Running external test suites with OpenSSL Running external test suites with OpenSSL
========================================= =========================================
It is possible to integrate external test suites into OpenSSL's "make test". It is possible to integrate external test suites into OpenSSL's `make test`.
This capability is considered a developer option and does not work on all This capability is considered a developer option and does not work on all
platforms. platforms.
The BoringSSL test suite The BoringSSL test suite
======================== ========================
@ -15,31 +13,31 @@ source code into an appropriate directory. This can be done in two ways:
1) Separately from the OpenSSL checkout using: 1) Separately from the OpenSSL checkout using:
$ git clone https://boringssl.googlesource.com/boringssl boringssl $ git clone https://boringssl.googlesource.com/boringssl boringssl
The BoringSSL tests are only confirmed to work at a specific commit in the The BoringSSL tests are only confirmed to work at a specific commit in the
BoringSSL repository. Later commits may or may not pass the test suite: BoringSSL repository. Later commits may or may not pass the test suite:
$ cd boringssl $ cd boringssl
$ git checkout 490469f850e $ git checkout 490469f850e
2) Using the already configured submodule settings in OpenSSL: 2) Using the already configured submodule settings in OpenSSL:
$ git submodule update --init $ git submodule update --init
Configure the OpenSSL source code to enable the external tests: Configure the OpenSSL source code to enable the external tests:
$ cd ../openssl $ cd ../openssl
$ ./config enable-ssl3 enable-ssl3-method enable-weak-ssl-ciphers \ $ ./config enable-ssl3 enable-ssl3-method enable-weak-ssl-ciphers \
enable-external-tests enable-external-tests
Note that using other config options than those given above may cause the tests Note that using other config options than those given above may cause the tests
to fail. to fail.
Run the OpenSSL tests by providing the path to the BoringSSL test runner in the Run the OpenSSL tests by providing the path to the BoringSSL test runner in the
BORING_RUNNER_DIR environment variable: `BORING_RUNNER_DIR` environment variable:
$ BORING_RUNNER_DIR=/path/to/boringssl/ssl/test/runner make test $ BORING_RUNNER_DIR=/path/to/boringssl/ssl/test/runner make test
Note that the test suite may change directory while running so the path provided Note that the test suite may change directory while running so the path provided
should be absolute and not relative to the current working directory. should be absolute and not relative to the current working directory.
@ -47,9 +45,8 @@ should be absolute and not relative to the current working directory.
To see more detailed output you can run just the BoringSSL tests with the To see more detailed output you can run just the BoringSSL tests with the
verbose option: verbose option:
$ VERBOSE=1 BORING_RUNNER_DIR=/path/to/boringssl/ssl/test/runner make \ $ VERBOSE=1 BORING_RUNNER_DIR=/path/to/boringssl/ssl/test/runner make \
TESTS="test_external_boringssl" test TESTS="test_external_boringssl" test
Test failures and suppressions Test failures and suppressions
------------------------------ ------------------------------
@ -71,26 +68,25 @@ within the OpenSSL source code.
The community is encouraged to contribute patches which reduce the number of The community is encouraged to contribute patches which reduce the number of
suppressions that are currently present. suppressions that are currently present.
Python PYCA/Cryptography test suite Python PYCA/Cryptography test suite
=================================== ===================================
This python test suite runs cryptographic tests with a local OpenSSL build as This python test suite runs cryptographic tests with a local OpenSSL build as
the implementation. the implementation.
First checkout the PYCA/Cryptography module into ./pyca-cryptography using: First checkout the `PYCA/Cryptography` module into `./pyca-cryptography` using:
$ git submodule update --init $ git submodule update --init
Then configure/build OpenSSL compatible with the python module: Then configure/build OpenSSL compatible with the python module:
$ ./config shared enable-external-tests $ ./config shared enable-external-tests
$ make $ make
The tests will run in a python virtual environment which requires virtualenv The tests will run in a python virtual environment which requires virtualenv
to be installed. to be installed.
$ make test VERBOSE=1 TESTS=test_external_pyca $ make test VERBOSE=1 TESTS=test_external_pyca
Test failures and suppressions Test failures and suppressions
------------------------------ ------------------------------
@ -98,7 +94,6 @@ Test failures and suppressions
Some tests target older (<=1.0.2) versions so will not run. Other tests target Some tests target older (<=1.0.2) versions so will not run. Other tests target
other crypto implementations so are not relevant. Currently no tests fail. other crypto implementations so are not relevant. Currently no tests fail.
krb5 test suite krb5 test suite
=============== ===============
@ -107,24 +102,24 @@ tests against the local OpenSSL build.
You will need a git checkout of krb5 at the top level: You will need a git checkout of krb5 at the top level:
$ git clone https://github.com/krb5/krb5 $ git clone https://github.com/krb5/krb5
krb5's master has to pass this same CI, but a known-good version is krb5's master has to pass this same CI, but a known-good version is
krb5-1.15.1-final if you want to be sure. krb5-1.15.1-final if you want to be sure.
$ cd krb5 $ cd krb5
$ git checkout krb5-1.15.1-final $ git checkout krb5-1.15.1-final
$ cd .. $ cd ..
OpenSSL must be built with external tests enabled: OpenSSL must be built with external tests enabled:
$ ./config enable-external-tests $ ./config enable-external-tests
$ make $ make
krb5's tests will then be run as part of the rest of the suite, or can be krb5's tests will then be run as part of the rest of the suite, or can be
explicitly run (with more debugging): explicitly run (with more debugging):
$ VERBOSE=1 make TESTS=test_external_krb5 test $ VERBOSE=1 make TESTS=test_external_krb5 test
Test-failures suppressions Test-failures suppressions
-------------------------- --------------------------
@ -133,7 +128,6 @@ krb5 will automatically adapt its test suite to account for the configuration
of your system. Certain tests may require more installed packages to run. No of your system. Certain tests may require more installed packages to run. No
tests are expected to fail. tests are expected to fail.
GOST engine test suite GOST engine test suite
=============== ===============
@ -142,19 +136,19 @@ tests against the local OpenSSL build.
You will need a git checkout of gost-engine at the top level: You will need a git checkout of gost-engine at the top level:
$ git submodule update --init $ git submodule update --init
Then configure/build OpenSSL enabling external tests: Then configure/build OpenSSL enabling external tests:
$ ./config shared enable-external-tests $ ./config shared enable-external-tests
$ make $ make
GOST engine requires CMake for the build process. GOST engine requires CMake for the build process.
GOST engine tests will then be run as part of the rest of the suite, or can be GOST engine tests will then be run as part of the rest of the suite, or can be
explicitly run (with more debugging): explicitly run (with more debugging):
$ make test VERBOSE=1 TESTS=test_external_gost_engine $ make test VERBOSE=1 TESTS=test_external_gost_engine
Updating test suites Updating test suites
==================== ====================
@ -163,24 +157,23 @@ To update the commit for any of the above test suites:
- Make sure the submodules are cloned locally: - Make sure the submodules are cloned locally:
$ git submodule update --init --recursive $ git submodule update --init --recursive
- Enter subdirectory and pull from the repository (use a specific branch/tag if required): - Enter subdirectory and pull from the repository (use a specific branch/tag if required):
$ cd <submodule-dir> $ cd `<submodule-dir>`
$ git pull origin master $ git pull origin master
- Go to root directory, there should be a new git status: - Go to root directory, there should be a new git status:
$ cd ../ $ cd ../
$ git status $ git status
... ...
# modified: <submodule-dir> (new commits) # modified: `<submodule-dir>` (new commits)
... ...
- Add/commit/push the update - Add/commit/push the update
git add <submodule-dir> $ git add `<submodule-dir>`
git commit -m "Updated <submodule> to latest commit" $ git commit -m `"Updated <submodule> to latest commit"`
git push $ git push