[openssl] master update
dev at ddvo.net
dev at ddvo.net
Sun Jul 5 09:36:41 UTC 2020
The branch master has been updated
via 1dc1ea182be183d8a393fdce4494360aee059cd2 (commit)
via 036cbb6bbf30955abdcffaf6e52cd926d8d8ee75 (commit)
via 915e7e75a49343ff5ddd23a54219eb32f57aa01c (commit)
from c996f71bab433c5d0f75945206a8cfd422829a49 (commit)
- Log -----------------------------------------------------------------
commit 1dc1ea182be183d8a393fdce4494360aee059cd2
Author: Dr. David von Oheimb <David.von.Oheimb at siemens.com>
Date: Wed Jun 10 17:49:25 2020 +0200
Fix many MarkDown issues in {NOTES*,README*,HACKING,LICENSE}.md files
Reviewed-by: Tim Hudson <tjh at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/12109)
commit 036cbb6bbf30955abdcffaf6e52cd926d8d8ee75
Author: Dr. David von Oheimb <David.von.Oheimb at siemens.com>
Date: Wed Jun 10 14:15:28 2020 +0200
Rename NOTES*, README*, VERSION, HACKING, LICENSE to .md or .txt
Reviewed-by: Tim Hudson <tjh at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/12109)
commit 915e7e75a49343ff5ddd23a54219eb32f57aa01c
Author: Dr. David von Oheimb <David.von.Oheimb at siemens.com>
Date: Thu Jun 11 11:28:02 2020 +0200
util/markdownlint.rb: Add two rule exceptions: MD023 and MD026
exclude_rule 'MD023' # Headers must start at the beginning of the line
exclude_rule 'MD026' # Trailing punctuation in header
Reviewed-by: Tim Hudson <tjh at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/12109)
-----------------------------------------------------------------------
Summary of changes:
CHANGES.md | 140 +++++-----
CONTRIBUTING.md | 11 +-
Configurations/15-android.conf | 2 +-
Configurations/{README.design => README-design.md} | 218 +++++++--------
Configurations/{README => README.md} | 140 +++++-----
Configure | 8 +-
HACKING | 26 --
HACKING.md | 33 +++
INSTALL.md | 58 ++--
LICENSE => LICENSE.txt | 0
NEWS.md | 2 +-
NOTES.ANDROID => NOTES-Android.md | 45 ++-
NOTES.DJGPP => NOTES-DJGPP.md | 36 ++-
NOTES.PERL => NOTES-Perl.md | 50 ++--
NOTES.UNIX => NOTES-Unix.md | 61 ++--
NOTES.VMS => NOTES-VMS.md | 32 +--
NOTES.VALGRIND => NOTES-Valgrind.md | 34 +--
NOTES.WIN => NOTES-Windows.txt | 0
README-Engine.md | 308 +++++++++++++++++++++
README.FIPS => README-FIPS.md | 3 +
README.ENGINE | 287 -------------------
README.md | 16 +-
VERSION => VERSION.dat | 0
config.com | 2 +-
...{README.sparse_array => README-sparse_array.md} | 17 +-
crypto/engine/{README => README.md} | 27 +-
crypto/err/{README => README.md} | 24 +-
crypto/objects/README | 44 ---
crypto/objects/README.md | 43 +++
crypto/perlasm/README | 124 ---------
crypto/perlasm/README.md | 130 +++++++++
crypto/property/{README => README.md} | 23 +-
demos/{README => README.txt} | 0
demos/bio/{README => README.txt} | 1 -
demos/certs/{README => README.txt} | 3 -
dev/{README => README.md} | 0
dev/release-aux/release-version-fn.sh | 4 +-
dev/release.sh | 2 +-
doc/{README => README.md} | 21 +-
ssl/record/{README => README.md} | 61 ++--
ssl/statem/README | 63 -----
ssl/statem/README.md | 63 +++++
test/{README => README-dev.md} | 115 ++++----
test/{README.external => README-external.md} | 85 +++---
test/README.md | 4 +-
test/data.txt | 4 +
test/{README.external => data2.txt} | 2 +
test/recipes/04-test_pem_data/{NOTES => NOTES.txt} | 0
test/recipes/20-test_dgst.t | 4 +-
test/recipes/20-test_pkeyutl.t | 4 +-
test/recipes/95-test_external_krb5.t | 2 +-
util/markdownlint.rb | 2 +
52 files changed, 1216 insertions(+), 1168 deletions(-)
rename Configurations/{README.design => README-design.md} (71%)
rename Configurations/{README => README.md} (86%)
delete mode 100644 HACKING
create mode 100644 HACKING.md
rename LICENSE => LICENSE.txt (100%)
rename NOTES.ANDROID => NOTES-Android.md (67%)
rename NOTES.DJGPP => NOTES-DJGPP.md (52%)
rename NOTES.PERL => NOTES-Perl.md (71%)
rename NOTES.UNIX => NOTES-Unix.md (69%)
rename NOTES.VMS => NOTES-VMS.md (81%)
rename NOTES.VALGRIND => NOTES-Valgrind.md (64%)
rename NOTES.WIN => NOTES-Windows.txt (100%)
create mode 100644 README-Engine.md
rename README.FIPS => README-FIPS.md (58%)
delete mode 100644 README.ENGINE
rename VERSION => VERSION.dat (100%)
rename crypto/{README.sparse_array => README-sparse_array.md} (93%)
rename crypto/engine/{README => README.md} (95%)
rename crypto/err/{README => README.md} (50%)
delete mode 100644 crypto/objects/README
create mode 100644 crypto/objects/README.md
delete mode 100644 crypto/perlasm/README
create mode 100644 crypto/perlasm/README.md
rename crypto/property/{README => README.md} (86%)
rename demos/{README => README.txt} (100%)
rename demos/bio/{README => README.txt} (99%)
rename demos/certs/{README => README.txt} (99%)
rename dev/{README => README.md} (100%)
rename doc/{README => README.md} (58%)
rename ssl/record/{README => README.md} (56%)
delete mode 100644 ssl/statem/README
create mode 100644 ssl/statem/README.md
rename test/{README => README-dev.md} (52%)
copy test/{README.external => README-external.md} (73%)
create mode 100644 test/data.txt
rename test/{README.external => data2.txt} (99%)
rename test/recipes/04-test_pem_data/{NOTES => NOTES.txt} (100%)
diff --git a/CHANGES.md b/CHANGES.md
index 585a451d18..2cb73985a3 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -173,6 +173,12 @@ OpenSSL 3.0
*Richard Levitte*
+ * Project text documents not yet having a proper file name extension
+ (`HACKING`, `LICENSE`, `NOTES*`, `README*`, `VERSION`) have been renamed to
+ `*.md` as far as reasonable, else `*.txt`, for better use with file managers.
+
+ *David von Oheimb*
+
* The main project documents (README, NEWS, CHANGES, INSTALL, SUPPORT)
have been converted to Markdown with the goal to produce documents
which not only look pretty when viewed online in the browser, but
@@ -1054,7 +1060,7 @@ OpenSSL 3.0
* Added EVP_MAC, an EVP layer MAC API, to simplify adding MAC
implementations. This includes a generic EVP_PKEY to EVP_MAC bridge,
to facilitate the continued use of MACs through raw private keys in
- functionality such as EVP_DigestSign* and EVP_DigestVerify*.
+ functionality such as `EVP_DigestSign*` and `EVP_DigestVerify*`.
*Richard Levitte*
@@ -1726,9 +1732,9 @@ OpenSSL 1.1.1
*Paul Yang*
* Add SM3 implemented according to GB/T 32905-2016
- * Jack Lloyd <jack.lloyd at ribose.com>,
- Ronald Tse <ronald.tse at ribose.com>,
- Erick Borsboom <erick.borsboom at ribose.com> *
+ *Jack Lloyd <jack.lloyd at ribose.com>,*
+ *Ronald Tse <ronald.tse at ribose.com>,*
+ *Erick Borsboom <erick.borsboom at ribose.com>*
* Add 'Maximum Fragment Length' TLS extension negotiation and support
as documented in RFC6066.
@@ -1737,9 +1743,9 @@ OpenSSL 1.1.1
*Filipe Raimundo da Silva*
* Add SM4 implemented according to GB/T 32907-2016.
- * Jack Lloyd <jack.lloyd at ribose.com>,
- Ronald Tse <ronald.tse at ribose.com>,
- Erick Borsboom <erick.borsboom at ribose.com> *
+ *Jack Lloyd <jack.lloyd at ribose.com>,*
+ *Ronald Tse <ronald.tse at ribose.com>,*
+ *Erick Borsboom <erick.borsboom at ribose.com>*
* Reimplement -newreq-nodes and ERR_error_string_n; the
original author does not agree with the license change.
@@ -2925,7 +2931,7 @@ OpenSSL 1.1.0
Makefile. Instead, Configure produces a perl module in
configdata.pm which holds most of the config data (in the hash
table %config), the target data that comes from the target
- configuration in one of the `Configurations/*.conf~ files (in
+ configuration in one of the `Configurations/*.conf` files (in
%target).
*Richard Levitte*
@@ -3056,21 +3062,21 @@ OpenSSL 1.1.0
opaque. For HMAC_CTX, the following constructors and destructors
were added:
- HMAC_CTX *HMAC_CTX_new(void);
- void HMAC_CTX_free(HMAC_CTX *ctx);
+ HMAC_CTX *HMAC_CTX_new(void);
+ void HMAC_CTX_free(HMAC_CTX *ctx);
For EVP_MD and EVP_CIPHER, complete APIs to create, fill and
destroy such methods has been added. See EVP_MD_meth_new(3) and
EVP_CIPHER_meth_new(3) for documentation.
Additional changes:
- 1) EVP_MD_CTX_cleanup(), EVP_CIPHER_CTX_cleanup() and
- HMAC_CTX_cleanup() were removed. HMAC_CTX_reset() and
- EVP_MD_CTX_reset() should be called instead to reinitialise
+ 1) `EVP_MD_CTX_cleanup()`, `EVP_CIPHER_CTX_cleanup()` and
+ `HMAC_CTX_cleanup()` were removed. `HMAC_CTX_reset()` and
+ `EVP_MD_CTX_reset()` should be called instead to reinitialise
an already created structure.
2) For consistency with the majority of our object creators and
- destructors, EVP_MD_CTX_(create|destroy) were renamed to
- EVP_MD_CTX_(new|free). The old names are retained as macros
+ destructors, `EVP_MD_CTX_(create|destroy)` were renamed to
+ `EVP_MD_CTX_(new|free)`. The old names are retained as macros
for deprecated builds.
*Richard Levitte*
@@ -3104,12 +3110,12 @@ OpenSSL 1.1.0
* State machine rewrite. The state machine code has been significantly
refactored in order to remove much duplication of code and solve issues
- with the old code (see ssl/statem/README for further details). This change
- does have some associated API changes. Notably the SSL_state() function
- has been removed and replaced by SSL_get_state which now returns an
- "OSSL_HANDSHAKE_STATE" instead of an int. SSL_set_state() has been removed
- altogether. The previous handshake states defined in ssl.h and ssl3.h have
- also been removed.
+ with the old code (see [ssl/statem/README.md](ssl/statem/README.md) for
+ further details). This change does have some associated API changes.
+ Notably the SSL_state() function has been removed and replaced by
+ SSL_get_state which now returns an "OSSL_HANDSHAKE_STATE" instead of an int.
+ SSL_set_state() has been removed altogether. The previous handshake states
+ defined in ssl.h and ssl3.h have also been removed.
*Matt Caswell*
@@ -3168,8 +3174,8 @@ OpenSSL 1.1.0
*Emilia Käsper*
* Fix no-stdio build.
- * David Woodhouse <David.Woodhouse at intel.com> and also
- Ivan Nestlerode <ivan.nestlerode at sonos.com> *
+ *David Woodhouse <David.Woodhouse at intel.com> and also*
+ *Ivan Nestlerode <ivan.nestlerode at sonos.com>*
* New testing framework
The testing framework has been largely rewritten and is now using
@@ -3573,7 +3579,7 @@ OpenSSL 1.1.0
*Steve Henson*
- * Rename old X9.31 PRNG functions of the form FIPS_rand* to FIPS_x931*.
+ * Rename old X9.31 PRNG functions of the form `FIPS_rand*` to `FIPS_x931*`.
This shouldn't present any incompatibility problems because applications
shouldn't be using these directly and any that are will need to rethink
anyway as the X9.31 PRNG is now deprecated by FIPS 140-2
@@ -4452,11 +4458,11 @@ OpenSSL 1.0.2
* Fix BN_hex2bn/BN_dec2bn NULL pointer deref/heap corruption
In the BN_hex2bn function the number of hex digits is calculated using an
- int value |i|. Later |bn_expand| is called with a value of |i * 4|. For
- large values of |i| this can result in |bn_expand| not allocating any
- memory because |i * 4| is negative. This can leave the internal BIGNUM data
+ int value `i`. Later `bn_expand` is called with a value of `i * 4`. For
+ large values of `i` this can result in `bn_expand` not allocating any
+ memory because `i * 4` is negative. This can leave the internal BIGNUM data
field as NULL leading to a subsequent NULL ptr deref. For very large values
- of |i|, the calculation |i * 4| could be a positive value smaller than |i|.
+ of `i`, the calculation `i * 4` could be a positive value smaller than `i`.
In this case memory is allocated to the internal BIGNUM data field, but it
is insufficiently sized leading to heap corruption. A similar issue exists
in BN_dec2bn. This could have security consequences if BN_hex2bn/BN_dec2bn
@@ -4476,11 +4482,11 @@ OpenSSL 1.0.2
* Fix memory issues in `BIO_*printf` functions
- The internal |fmtstr| function used in processing a "%s" format string in
+ The internal `fmtstr` function used in processing a "%s" format string in
the `BIO_*printf` functions could overflow while calculating the length of a
string and cause an OOB read when printing very long strings.
- Additionally the internal |doapr_outch| function can attempt to write to an
+ Additionally the internal `doapr_outch` function can attempt to write to an
OOB memory location (at an offset from the NULL pointer) in the event of a
memory allocation failure. In 1.0.2 and below this could be caused where
the size of a buffer to be allocated is greater than INT_MAX. E.g. this
@@ -5654,11 +5660,11 @@ OpenSSL 1.0.1
* Fix BN_hex2bn/BN_dec2bn NULL pointer deref/heap corruption
In the BN_hex2bn function the number of hex digits is calculated using an
- int value |i|. Later |bn_expand| is called with a value of |i * 4|. For
- large values of |i| this can result in |bn_expand| not allocating any
- memory because |i * 4| is negative. This can leave the internal BIGNUM data
+ int value `i`. Later `bn_expand` is called with a value of `i * 4`. For
+ large values of `i` this can result in `bn_expand` not allocating any
+ memory because `i * 4` is negative. This can leave the internal BIGNUM data
field as NULL leading to a subsequent NULL ptr deref. For very large values
- of |i|, the calculation |i * 4| could be a positive value smaller than |i|.
+ of `i`, the calculation `i * 4` could be a positive value smaller than `i`.
In this case memory is allocated to the internal BIGNUM data field, but it
is insufficiently sized leading to heap corruption. A similar issue exists
in BN_dec2bn. This could have security consequences if BN_hex2bn/BN_dec2bn
@@ -5678,11 +5684,11 @@ OpenSSL 1.0.1
* Fix memory issues in `BIO_*printf` functions
- The internal |fmtstr| function used in processing a "%s" format string in
+ The internal `fmtstr` function used in processing a "%s" format string in
the `BIO_*printf` functions could overflow while calculating the length of a
string and cause an OOB read when printing very long strings.
- Additionally the internal |doapr_outch| function can attempt to write to an
+ Additionally the internal `doapr_outch` function can attempt to write to an
OOB memory location (at an offset from the NULL pointer) in the event of a
memory allocation failure. In 1.0.2 and below this could be caused where
the size of a buffer to be allocated is greater than INT_MAX. E.g. this
@@ -6499,8 +6505,8 @@ OpenSSL 1.0.1
disable just protocol X, but all protocols above X *if* there are
protocols *below* X still enabled. In more practical terms it means
that if application wants to disable TLS1.0 in favor of TLS1.1 and
- above, it's not sufficient to pass SSL_OP_NO_TLSv1, one has to pass
- SSL_OP_NO_TLSv1|SSL_OP_NO_SSLv3|SSL_OP_NO_SSLv2. This applies to
+ above, it's not sufficient to pass `SSL_OP_NO_TLSv1`, one has to pass
+ `SSL_OP_NO_TLSv1|SSL_OP_NO_SSLv3|SSL_OP_NO_SSLv2`. This applies to
client side.
*Andy Polyakov*
@@ -11587,7 +11593,8 @@ OpenSSL 0.9.7.]
of specific crypto interfaces. This change also introduces integrated
support for symmetric ciphers and digest implementations - so ENGINEs
can now accelerate these by providing EVP_CIPHER and EVP_MD
- implementations of their own. This is detailed in crypto/engine/README
+ implementations of their own. This is detailed in
+ [crypto/engine/README.md](crypto/engine/README.md)
as it couldn't be adequately described here. However, there are a few
API changes worth noting - some RSA, DSA, DH, and RAND functions that
were changed in the original introduction of ENGINE code have now
@@ -11663,7 +11670,7 @@ OpenSSL 0.9.7.]
makes them more flexible to be built both as statically-linked ENGINEs
and self-contained shared-libraries loadable via the "dynamic" ENGINE.
Also, add stub code to each that makes building them as self-contained
- shared-libraries easier (see README.ENGINE).
+ shared-libraries easier (see [README-Engine.md](README-Engine.md)).
*Geoff Thorpe*
@@ -11672,7 +11679,8 @@ OpenSSL 0.9.7.]
self-contained shared-libraries. The "dynamic" ENGINE exposes control
commands that can be used to configure what shared-library to load and
to control aspects of the way it is handled. Also, made an update to
- the README.ENGINE file that brings its information up-to-date and
+ the [README-Engine.md](README-Engine.md) file
+ that brings its information up-to-date and
provides some information and instructions on the "dynamic" ENGINE
(ie. how to use it, how to build "dynamic"-loadable ENGINEs, etc).
@@ -12320,8 +12328,8 @@ s-cbc 3624.96k 5258.21k 5530.91k 5624.30k 5628.26k
*Geoff Thorpe, Lutz Jaenicke*
* Modify mkdef.pl to recognise and parse preprocessor conditionals
- of the form '#if defined(...) || defined(...) || ...' and
- '#if !defined(...) && !defined(...) && ...'. This also avoids
+ of the form `#if defined(...) || defined(...) || ...` and
+ `#if !defined(...) && !defined(...) && ...`. This also avoids
the growing number of special cases it was previously handling.
*Richard Levitte*
@@ -12894,9 +12902,9 @@ s-cbc 3624.96k 5258.21k 5530.91k 5624.30k 5628.26k
*Bodo Moeller*
- * Move `BN_mod_...` functions into new file crypto/bn/bn_mod.c
- (except for exponentiation, which stays in crypto/bn/bn_exp.c,
- and BN_mod_mul_reciprocal, which stays in crypto/bn/bn_recp.c)
+ * Move `BN_mod_...` functions into new file `crypto/bn/bn_mod.c`
+ (except for exponentiation, which stays in `crypto/bn/bn_exp.c`,
+ and `BN_mod_mul_reciprocal`, which stays in `crypto/bn/bn_recp.c`)
and add new functions:
BN_nnmod
@@ -12912,16 +12920,16 @@ s-cbc 3624.96k 5258.21k 5530.91k 5624.30k 5628.26k
These functions always generate non-negative results.
- BN_nnmod otherwise is like BN_mod (if BN_mod computes a remainder r
- such that |m| < r < 0, BN_nnmod will output rem + |m| instead).
+ `BN_nnmod` otherwise is `like BN_mod` (if `BN_mod` computes a remainder `r`
+ such that `|m| < r < 0`, `BN_nnmod` will output `rem + |m|` instead).
- BN_mod_XXX_quick(r, a, [b,] m) generates the same result as
- BN_mod_XXX(r, a, [b,] m, ctx), but requires that a [and b]
- be reduced modulo m.
+ `BN_mod_XXX_quick(r, a, [b,] m)` generates the same result as
+ `BN_mod_XXX(r, a, [b,] m, ctx)`, but requires that `a` [and `b`]
+ be reduced modulo `m`.
*Lenka Fibikova <fibikova at exp-math.uni-essen.de>, Bodo Moeller*
-f 0
+<!--
The following entry accidentally appeared in the CHANGES file
distributed with OpenSSL 0.9.7. The modifications described in
it do *not* apply to OpenSSL 0.9.7.
@@ -12935,7 +12943,7 @@ f 0
differing sizes.
*Richard Levitte*
-ndif
+-->
* In 'openssl passwd', verify passwords read from the terminal
unless the '-salt' option is used (which usually means that
@@ -14675,7 +14683,7 @@ ndif
* Change the handling of OID objects as follows:
- New object identifiers are inserted in objects.txt, following
- the syntax given in objects.README.
+ the syntax given in [crypto/objects/README.md](crypto/objects/README.md).
- objects.pl is used to process obj_mac.num and create a new
obj_mac.h.
- obj_dat.pl is used to create a new obj_dat.h, using the data in
@@ -17391,10 +17399,10 @@ ndif
*Steve Henson*
* Be less restrictive and allow also `perl util/perlpath.pl
- /path/to/bin/perl' in addition to `perl util/perlpath.pl /path/to/bin',
- because this way one can also use an interpreter named `perl5' (which is
+ /path/to/bin/perl` in addition to `perl util/perlpath.pl /path/to/bin`,
+ because this way one can also use an interpreter named `perl5` (which is
usually the name of Perl 5.xxx on platforms where an Perl 4.x is still
- installed as `perl').
+ installed as `perl`).
*Matthias Loepfe <Matthias.Loepfe at adnovum.ch>*
@@ -17427,7 +17435,7 @@ ndif
*Steve Henson*
- * Make `openssl version' output lines consistent.
+ * Make `openssl version` output lines consistent.
*Ralf S. Engelschall*
@@ -17484,7 +17492,7 @@ ndif
*Ben Laurie*
* Allow DSO flags like -fpic, -fPIC, -KPIC etc. to be specified
- on the `perl Configure ...' command line. This way one can compile
+ on the `perl Configure ...` command line. This way one can compile
OpenSSL libraries with Position Independent Code (PIC) which is needed
for linking it into DSOs.
@@ -17503,9 +17511,9 @@ ndif
*Ralf S. Engelschall*
- * General source tree makefile cleanups: Made `making xxx in yyy...'
- display consistent in the source tree and replaced `/bin/rm' by `rm'.
- Additionally cleaned up the `make links' target: Remove unnecessary
+ * General source tree makefile cleanups: Made `making xxx in yyy...`
+ display consistent in the source tree and replaced `/bin/rm` by `rm`.
+ Additionally cleaned up the `make links` target: Remove unnecessary
semicolons, subsequent redundant removes, inline point.sh into mklink.sh
to speed processing and no longer clutter the display with confusing
stuff. Instead only the actually done links are displayed.
@@ -17632,12 +17640,12 @@ ndif
*Ralf S. Engelschall*
- * Make `openssl x509 -noout -modulus' functional also for DSA certificates
+ * Make `openssl x509 -noout -modulus`' functional also for DSA certificates
(in addition to RSA certificates) to match the behaviour of `openssl dsa
- -noout -modulus' as it's already the case for `openssl rsa -noout
- -modulus'. For RSA the -modulus is the real "modulus" while for DSA
+ -noout -modulus` as it's already the case for `openssl rsa -noout
+ -modulus`. For RSA the -modulus is the real "modulus" while for DSA
currently the public key is printed (a decision which was already done by
- `openssl dsa -modulus' in the past) which serves a similar purpose.
+ `openssl dsa -modulus` in the past) which serves a similar purpose.
Additionally the NO_RSA no longer completely removes the whole -modulus
option; it now only avoids using the RSA stuff. Same applies to NO_DSA
now, too.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 23756a5d4a..3e11b0b89f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -54,8 +54,8 @@ guidelines:
(usually by rebasing) before it will be acceptable.
4. Patches should follow our [coding style][] and compile without warnings.
- Where gcc or clang is available you should use the
- --strict-warnings Configure option. OpenSSL compiles on many varied
+ Where `gcc` or `clang` is available you should use the
+ `--strict-warnings` `Configure` option. OpenSSL compiles on many varied
platforms: try to ensure you only use portable features. Clean builds
via Travis and AppVeyor are required, and they are started automatically
whenever a PR is created or updated.
@@ -64,7 +64,7 @@ guidelines:
5. When at all possible, patches should include tests. These can
either be added to an existing test, or completely new. Please see
- test/README for information on the test framework.
+ [test/README.md](test/README.md) for information on the test framework.
6. New features or changed functionality must include
documentation. Please look at the "pod" files in doc/man[1357] for
@@ -77,7 +77,7 @@ guidelines:
explain the grander details.
Have a look through existing entries for inspiration.
Please note that this is NOT simply a copy of git-log one-liners.
- Also note that security fixes get an entry in CHANGES.md.
+ Also note that security fixes get an entry in [CHANGES.md](CHANGES.md).
This file helps users get more in depth information of what comes
with a specific release without having to sift through the higher
noise ratio in git-log.
@@ -89,3 +89,6 @@ guidelines:
OpenSSL 1.1.0).
This file helps users get a very quick summary of what comes with a
specific release, to see if an upgrade is worth the effort.
+
+ 9. Guidelines how to integrate error output of new crypto library modules
+ can be found in [crypto/err/README.md](crypto/err/README.md).
\ No newline at end of file
diff --git a/Configurations/15-android.conf b/Configurations/15-android.conf
index d3b2ff6a1c..77d6c8b47d 100644
--- a/Configurations/15-android.conf
+++ b/Configurations/15-android.conf
@@ -1,6 +1,6 @@
#### Android...
#
-# See NOTES.ANDROID for details, and don't miss platform-specific
+# See NOTES-Android.md for details, and don't miss platform-specific
# comments below...
{
diff --git a/Configurations/README.design b/Configurations/README-design.md
similarity index 71%
rename from Configurations/README.design
rename to Configurations/README-design.md
index b79d0b2e49..ef21a3ae28 100644
--- a/Configurations/README.design
+++ b/Configurations/README-design.md
@@ -4,17 +4,17 @@ Design document for the unified scheme data
How are things connected?
-------------------------
-The unified scheme takes all its data from the build.info files seen
+The unified scheme takes all its data from the `build.info` files seen
throughout the source tree. These files hold the minimum information
needed to build end product files from diverse sources. See the
-section on build.info files below.
+section on `build.info` files below.
-From the information in build.info files, Configure builds up an
-information database as a hash table called %unified_info, which is
+From the information in `build.info` files, `Configure` builds up an
+information database as a hash table called `%unified_info`, which is
stored in configdata.pm, found at the top of the build tree (which may
or may not be the same as the source tree).
-Configurations/common.tmpl uses the data from %unified_info to
+[`Configurations/common.tmpl`](common.tmpl) uses the data from `%unified_info` to
generate the rules for building end product files as well as
intermediary files with the help of a few functions found in the
build-file templates. See the section on build-file templates further
@@ -23,36 +23,35 @@ down for more information.
build.info files
----------------
-As mentioned earlier, build.info files are meant to hold the minimum
+As mentioned earlier, `build.info` files are meant to hold the minimum
information needed to build output files, and therefore only (with a
few possible exceptions [1]) have information about end products (such
as scripts, library files and programs) and source files (such as C
files, C header files, assembler files, etc). Intermediate files such
-as object files are rarely directly referred to in build.info files (and
-when they are, it's always with the file name extension .o), they are
-inferred by Configure. By the same rule of minimalism, end product
-file name extensions (such as .so, .a, .exe, etc) are never mentioned
-in build.info. Their file name extensions will be inferred by the
+as object files are rarely directly referred to in `build.info` files (and
+when they are, it's always with the file name extension `.o`), they are
+inferred by `Configure`. By the same rule of minimalism, end product
+file name extensions (such as `.so`, `.a`, `.exe`, etc) are never mentioned
+in `build.info`. Their file name extensions will be inferred by the
build-file templates, adapted for the platform they are meant for (see
-sections on %unified_info and build-file templates further down).
+sections on `%unified_info` and build-file templates further down).
-The variables PROGRAMS, LIBS, MODULES and SCRIPTS are used to declare
-end products. There are variants for them with '_NO_INST' as suffix
-(PROGRAM_NO_INST etc) to specify end products that shouldn't get
-installed.
+The variables `PROGRAMS`, `LIBS`, `MODULES` and `SCRIPTS` are used to declare
+end products. There are variants for them with `_NO_INST` as suffix
+(`PROGRAM_NO_INST` etc) to specify end products that shouldn't get installed.
-The variables SOURCE, DEPEND, INCLUDE and DEFINE are indexed by a
+The variables `SOURCE`, `DEPEND`, `INCLUDE` and `DEFINE` are indexed by a
produced file, and their values are the source used to produce that
particular produced file, extra dependencies, include directories
needed, or C macros to be defined.
-All their values in all the build.info throughout the source tree are
+All their values in all the `build.info` throughout the source tree are
collected together and form a set of programs, libraries, modules and
scripts to be produced, source files, dependencies, etc etc etc.
Let's have a pretend example, a very limited contraption of OpenSSL,
-composed of the program 'apps/openssl', the libraries 'libssl' and
-'libcrypto', an module 'engines/ossltest' and their sources and
+composed of the program `apps/openssl`, the libraries `libssl` and
+`libcrypto`, an module `engines/ossltest` and their sources and
dependencies.
# build.info
@@ -61,11 +60,11 @@ dependencies.
INCLUDE[libssl]=include
DEPEND[libssl]=libcrypto
-This is the top directory build.info file, and it tells us that two
-libraries are to be built, the include directory 'include/' shall be
+This is the top directory `build.info` file, and it tells us that two
+libraries are to be built, the include directory `include/` shall be
used throughout when building anything that will end up in each
-library, and that the library 'libssl' depend on the library
-'libcrypto' to function properly.
+library, and that the library `libssl` depend on the library
+`libcrypto` to function properly.
# apps/build.info
PROGRAMS=openssl
@@ -73,15 +72,15 @@ library, and that the library 'libssl' depend on the library
INCLUDE[openssl]=.. ../include
DEPEND[openssl]=../libssl
-This is the build.info file in 'apps/', one may notice that all file
-paths mentioned are relative to the directory the build.info file is
+This is the `build.info` file in `apps/`, one may notice that all file
+paths mentioned are relative to the directory the `build.info` file is
located in. This one tells us that there's a program to be built
-called 'apps/openssl' (the file name extension will depend on the
-platform and is therefore not mentioned in the build.info file). It's
-built from one source file, 'apps/openssl.c', and building it requires
-the use of '.' and 'include' include directories (both are declared
-from the point of view of the 'apps/' directory), and that the program
-depends on the library 'libssl' to function properly.
+called `apps/openss` (the file name extension will depend on the
+platform and is therefore not mentioned in the `build.info` file). It's
+built from one source file, `apps/openssl.c`, and building it requires
+the use of `.` and `include/` include directories (both are declared
+from the point of view of the `apps/` directory), and that the program
+depends on the library `libssl` to function properly.
# crypto/build.info
LIBS=../libcrypto
@@ -92,32 +91,32 @@ depends on the library 'libssl' to function properly.
DEPEND[buildinf.h]=../Makefile
DEPEND[../util/mkbuildinf.pl]=../util/Foo.pm
-This is the build.info file in 'crypto', and it tells us a little more
-about what's needed to produce 'libcrypto'. LIBS is used again to
-declare that 'libcrypto' is to be produced. This declaration is
-really unnecessary as it's already mentioned in the top build.info
+This is the `build.info` file in `crypto/`, and it tells us a little more
+about what's needed to produce `libcrypto`. LIBS is used again to
+declare that `libcrypto` is to be produced. This declaration is
+really unnecessary as it's already mentioned in the top `build.info`
file, but can make the info file easier to understand. This is to
show that duplicate information isn't an issue.
-This build.info file informs us that 'libcrypto' is built from a few
-source files, 'crypto/aes.c', 'crypto/evp.c' and 'crypto/cversion.c'.
+This `build.info` file informs us that `libcrypto` is built from a few
+source files, `crypto/aes.c`, `crypto/evp.c` and `crypto/cversion.c`.
It also shows us that building the object file inferred from
-'crypto/cversion.c' depends on 'crypto/buildinf.h'. Finally, it
+`crypto/cversion.c` depends on `crypto/buildinf.h`. Finally, it
also shows the possibility to declare how some files are generated
using some script, in this case a perl script, and how such scripts
can be declared to depend on other files, in this case a perl module.
Two things are worth an extra note:
-'DEPEND[cversion.o]' mentions an object file. DEPEND indexes is the
+`DEPEND[cversion.o]` mentions an object file. DEPEND indexes is the
only location where it's valid to mention them
# ssl/build.info
LIBS=../libssl
SOURCE[../libssl]=tls.c
-This is the build.info file in 'ssl/', and it tells us that the
-library 'libssl' is built from the source file 'ssl/tls.c'.
+This is the build.info file in `ssl/`, and it tells us that the
+library `libssl` is built from the source file `ssl/tls.c`.
# engines/build.info
MODULES=dasync
@@ -130,17 +129,17 @@ library 'libssl' is built from the source file 'ssl/tls.c'.
DEPEND[ossltest]=../libcrypto.a
INCLUDE[ossltest]=../include
-This is the build.info file in 'engines/', telling us that two modules
-called 'engines/dasync' and 'engines/ossltest' shall be built, that
-dasync's source is 'engines/e_dasync.c' and ossltest's source is
-'engines/e_ossltest.c' and that the include directory 'include/' may
+This is the `build.info` file in `engines/`, telling us that two modules
+called `engines/dasync` and `engines/ossltest` shall be built, that
+`dasync`'s source is `engines/e_dasync.c` and `ossltest`'s source is
+`engines/e_ossltest.c` and that the include directory `include/` may
be used when building anything that will be part of these modules.
-Also, both modules depend on the library 'libcrypto' to function
-properly. ossltest is explicitly linked with the static variant of
-the library 'libcrypto'. Finally, only dasync is being installed, as
-ossltest is only for internal testing.
+Also, both modules depend on the library `libcrypto` to function
+properly. `ossltest` is explicitly linked with the static variant of
+the library `libcrypto`. Finally, only `dasync` is being installed, as
+`ossltest` is only for internal testing.
-When Configure digests these build.info files, the accumulated
+When `Configure` digests these `build.info` files, the accumulated
information comes down to this:
LIBS=libcrypto libssl
@@ -170,83 +169,81 @@ information comes down to this:
DEPEND[crypto/buildinf.h]=Makefile
DEPEND[util/mkbuildinf.pl]=util/Foo.pm
-
A few notes worth mentioning:
-LIBS may be used to declare routine libraries only.
+`LIBS` may be used to declare routine libraries only.
-PROGRAMS may be used to declare programs only.
+`PROGRAMS` may be used to declare programs only.
-MODULES may be used to declare modules only.
+`MODULES` may be used to declare modules only.
-The indexes for SOURCE must only be end product files, such as
-libraries, programs or modules. The values of SOURCE variables must
+The indexes for `SOURCE` must only be end product files, such as
+libraries, programs or modules. The values of `SOURCE` variables must
only be source files (possibly generated).
-INCLUDE and DEPEND shows a relationship between different files
+`INCLUDE` and `DEPEND` shows a relationship between different files
(usually produced files) or between files and directories, such as a
program depending on a library, or between an object file and some
extra source file.
-When Configure processes the build.info files, it will take it as
+When `Configure` processes the `build.info` files, it will take it as
truth without question, and will therefore perform very few checks.
If the build tree is separate from the source tree, it will assume
that all built files and up in the build directory and that all source
files are to be found in the source tree, if they can be found there.
-Configure will assume that source files that can't be found in the
-source tree (such as 'crypto/bildinf.h' in the example above) are
+`Configure` will assume that source files that can't be found in the
+source tree (such as `crypto/bildinf.h` in the example above) are
generated and will be found in the build tree.
+The `%unified_info` database
+----------------------------
-The %unified_info database
---------------------------
-
-The information in all the build.info get digested by Configure and
-collected into the %unified_info database, divided into the following
+The information in all the `build.info` get digested by `Configure` and
+collected into the `%unified_info` database, divided into the following
indexes:
- depends => a hash table containing 'file' => [ 'dependency' ... ]
- pairs. These are directly inferred from the DEPEND
- variables in build.info files.
+ depends => a hash table containing 'file' => [ 'dependency' ... ]
+ pairs. These are directly inferred from the DEPEND
+ variables in build.info files.
- modules => a list of modules. These are directly inferred from
- the MODULES variable in build.info files.
+ modules => a list of modules. These are directly inferred from
+ the MODULES variable in build.info files.
- generate => a hash table containing 'file' => [ 'generator' ... ]
- pairs. These are directly inferred from the GENERATE
- variables in build.info files.
+ generate => a hash table containing 'file' => [ 'generator' ... ]
+ pairs. These are directly inferred from the GENERATE
+ variables in build.info files.
- includes => a hash table containing 'file' => [ 'include' ... ]
- pairs. These are directly inferred from the INCLUDE
- variables in build.info files.
+ includes => a hash table containing 'file' => [ 'include' ... ]
+ pairs. These are directly inferred from the INCLUDE
+ variables in build.info files.
- install => a hash table containing 'type' => [ 'file' ... ] pairs.
- The types are 'programs', 'libraries', 'modules' and
- 'scripts', and the array of files list the files of
- that type that should be installed.
+ install => a hash table containing 'type' => [ 'file' ... ] pairs.
+ The types are 'programs', 'libraries', 'modules' and
+ 'scripts', and the array of files list the files of
+ that type that should be installed.
- libraries => a list of libraries. These are directly inferred from
- the LIBS variable in build.info files.
+ libraries => a list of libraries. These are directly inferred from
+ the LIBS variable in build.info files.
- programs => a list of programs. These are directly inferred from
- the PROGRAMS variable in build.info files.
+ programs => a list of programs. These are directly inferred from
+ the PROGRAMS variable in build.info files.
- scripts => a list of scripts. There are directly inferred from
- the SCRIPTS variable in build.info files.
+ scripts => a list of scripts. There are directly inferred from
+ the SCRIPTS variable in build.info files.
- sources => a hash table containing 'file' => [ 'sourcefile' ... ]
- pairs. These are indirectly inferred from the SOURCE
- variables in build.info files. Object files are
- mentioned in this hash table, with source files from
- SOURCE variables, and AS source files for programs and
- libraries.
+ sources => a hash table containing 'file' => [ 'sourcefile' ... ]
+ pairs. These are indirectly inferred from the SOURCE
+ variables in build.info files. Object files are
+ mentioned in this hash table, with source files from
+ SOURCE variables, and AS source files for programs and
+ libraries.
- shared_sources =>
- a hash table just like 'sources', but only as source
- files (object files) for building shared libraries.
+ shared_sources =>
+ a hash table just like 'sources', but only as source
+ files (object files) for building shared libraries.
-As an example, here is how the build.info files example from the
-section above would be digested into a %unified_info table:
+As an example, here is how the `build.info` files example from the
+section above would be digested into a `%unified_info` table:
our %unified_info = (
"depends" =>
@@ -399,20 +396,19 @@ section above would be digested into a %unified_info table:
},
);
-As can be seen, everything in %unified_info is fairly simple suggest
+As can be seen, everything in `%unified_info` is fairly simple suggest
of information. Still, it tells us that to build all programs, we
-must build 'apps/openssl', and to build the latter, we will need to
-build all its sources ('apps/openssl.o' in this case) and all the
-other things it depends on (such as 'libssl'). All those dependencies
-need to be built as well, using the same logic, so to build 'libssl',
-we need to build 'ssl/tls.o' as well as 'libcrypto', and to build the
+must build `apps/openssl`, and to build the latter, we will need to
+build all its sources (`apps/openssl.o` in this case) and all the
+other things it depends on (such as `libssl`). All those dependencies
+need to be built as well, using the same logic, so to build `libssl`,
+we need to build `ssl/tls.o` as well as `libcrypto`, and to build the
latter...
-
Build-file templates
--------------------
-Build-file templates are essentially build-files (such as Makefile on
+Build-file templates are essentially build-files (such as `Makefile` on
Unix) with perl code fragments mixed in. Those perl code fragment
will generate all the configuration dependent data, including all the
rules needed to build end product files and intermediary files alike.
@@ -461,7 +457,7 @@ etc.
incs => [ "INCL/PATH", ... ]
intent => one of "lib", "dso", "bin" );
- 'obj' has the intended object file with '.o'
+ 'obj' has the intended object file with `.o`
extension, src2obj() is expected to change it to
something more suitable for the platform.
'srcs' has the list of source files to build the
@@ -557,13 +553,13 @@ etc.
resulting script from.
Along with the build-file templates is the driving template
-Configurations/common.tmpl, which looks through all the information in
-%unified_info and generates all the rulesets to build libraries,
+[`Configurations/common.tmpl`](common.tmpl), which looks through all the
+information in `%unified_info` and generates all the rulesets to build libraries,
programs and all intermediate files, using the rule generating
functions defined in the build-file template.
-As an example with the smaller build.info set we've seen as an
-example, producing the rules to build 'libcrypto' would result in the
+As an example with the smaller `build.info` set we've seen as an
+example, producing the rules to build `libcrypto` would result in the
following calls:
# Note: obj2shlib will only be called if shared libraries are
diff --git a/Configurations/README b/Configurations/README.md
similarity index 86%
rename from Configurations/README
rename to Configurations/README.md
index a0618ca2d3..3fa80a3fab 100644
--- a/Configurations/README
+++ b/Configurations/README.md
@@ -14,7 +14,6 @@ configuration in diverse ways:
script. See 'Configure helper scripts for more
information.
-
Configurations of OpenSSL target platforms
==========================================
@@ -54,12 +53,12 @@ In each table entry, the following keys are significant:
usually good enough.
cppflags => Default C preprocessor flags [4].
defines => As an alternative, macro definitions may be
- given here instead of in `cppflags' [4].
+ given here instead of in 'cppflags' [4].
If given here, they MUST be as an array of
the string such as "MACRO=value", or just
"MACRO" for definitions without value.
includes => As an alternative, inclusion directories
- may be given here instead of in `cppflags'
+ may be given here instead of in 'cppflags'
[4]. If given here, the MUST be an array
of strings, one directory specification
each.
@@ -99,9 +98,9 @@ In each table entry, the following keys are significant:
module_cppflags
module_cflags
module_ldflags => Has the same function as the corresponding
- `shared_' attributes, but for building DSOs.
+ 'shared_' attributes, but for building DSOs.
When unset, they get the same values as the
- corresponding `shared_' attributes.
+ corresponding 'shared_' attributes.
ar => The library archive command, the default is
"ar".
@@ -237,31 +236,30 @@ In each table entry, the following keys are significant:
RC4_INT RC4 key schedule is made
up of 'unsigned int's;
-
[1] as part of the target configuration, one can have a key called
- 'inherit_from' that indicate what other configurations to inherit
- data from. These are resolved recursively.
+ `inherit_from` that indicates what other configurations to inherit
+ data from. These are resolved recursively.
- Inheritance works as a set of default values that can be overridden
- by corresponding key values in the inheriting configuration.
+ Inheritance works as a set of default values that can be overridden
+ by corresponding key values in the inheriting configuration.
- Note 1: any configuration table can be used as a template.
- Note 2: pure templates have the attribute 'template => 1' and
- cannot be used as build targets.
+ Note 1: any configuration table can be used as a template.
+ Note 2: pure templates have the attribute `template => 1` and
+ cannot be used as build targets.
- If several configurations are given in the 'inherit_from' array,
- the values of same attribute are concatenated with space
- separation. With this, it's possible to have several smaller
- templates for different configuration aspects that can be combined
- into a complete configuration.
+ If several configurations are given in the `inherit_from` array,
+ the values of same attribute are concatenated with space
+ separation. With this, it's possible to have several smaller
+ templates for different configuration aspects that can be combined
+ into a complete configuration.
- instead of a scalar value or an array, a value can be a code block
- of the form 'sub { /* your code here */ }'. This code block will
- be called with the list of inherited values for that key as
- arguments. In fact, the concatenation of strings is really done
- by using 'sub { join(" ", at _) }' on the list of inherited values.
+ Instead of a scalar value or an array, a value can be a code block
+ of the form `sub { /* your code here */ }`. This code block will
+ be called with the list of inherited values for that key as
+ arguments. In fact, the concatenation of strings is really done
+ by using `sub { join(" ", at _) }` on the list of inherited values.
- An example:
+ An example:
"foo" => {
template => 1,
@@ -291,21 +289,21 @@ In each table entry, the following keys are significant:
}
[2] OpenSSL is built with threading capabilities unless the user
- specifies 'no-threads'. The value of the key 'thread_scheme' may
- be "(unknown)", in which case the user MUST give some compilation
- flags to Configure.
+ specifies `no-threads`. The value of the key `thread_scheme` may
+ be `(unknown)`, in which case the user MUST give some compilation
+ flags to `Configure`.
[3] OpenSSL has three types of things to link from object files or
- static libraries:
+ static libraries:
- - shared libraries; that would be libcrypto and libssl.
- - shared objects (sometimes called dynamic libraries); that would
- be the modules.
- - applications; those are apps/openssl and all the test apps.
+ - shared libraries; that would be libcrypto and libssl.
+ - shared objects (sometimes called dynamic libraries); that would
+ be the modules.
+ - applications; those are apps/openssl and all the test apps.
- Very roughly speaking, linking is done like this (words in braces
- represent the configuration settings documented at the beginning
- of this file):
+ Very roughly speaking, linking is done like this (words in braces
+ represent the configuration settings documented at the beginning
+ of this file):
shared libraries:
{ld} $(CFLAGS) {lflags} {shared_ldflag} -o libfoo.so \
@@ -319,38 +317,43 @@ In each table entry, the following keys are significant:
{ld} $(CFLAGS) {lflags} -o app \
app1.o utils.o -lssl -lcrypto {ex_libs}
-[4] There are variants of these attribute, prefixed with `lib_',
- `dso_' or `bin_'. Those variants replace the unprefixed attribute
- when building library, DSO or program modules specifically.
+[4] There are variants of these attribute, prefixed with `lib_`,
+ `dso_` or `bin_`. Those variants replace the unprefixed attribute
+ when building library, DSO or program modules specifically.
Historically, the target configurations came in form of a string with
values separated by colons. This use is deprecated. The string form
looked like this:
- "target" => "{cc}:{cflags}:{unistd}:{thread_cflag}:{sys_id}:{lflags}:{bn_ops}:{cpuid_obj}:{bn_obj}:{ec_obj}:{des_obj}:{aes_obj}:{bf_obj}:{md5_obj}:{sha1_obj}:{cast_obj}:{rc4_obj}:{rmd160_obj}:{rc5_obj}:{wp_obj}:{cmll_obj}:{modes_obj}:{padlock_obj}:{perlasm_scheme}:{dso_scheme}:{shared_target}:{shared_cflag}:{shared_ldflag}:{shared_extension}:{ranlib}:{arflags}:{multilib}"
-
+ "target" => "{cc}:{cflags}:{unistd}:{thread_cflag}:{sys_id}:{lflags}:
+ {bn_ops}:{cpuid_obj}:{bn_obj}:{ec_obj}:{des_obj}:{aes_obj}:
+ {bf_obj}:{md5_obj}:{sha1_obj}:{cast_obj}:{rc4_obj}:
+ {rmd160_obj}:{rc5_obj}:{wp_obj}:{cmll_obj}:{modes_obj}:
+ {padlock_obj}:{perlasm_scheme}:{dso_scheme}:{shared_target}:
+ {shared_cflag}:{shared_ldflag}:{shared_extension}:{ranlib}:
+ {arflags}:{multilib}"
Build info files
================
-The build.info files that are spread over the source tree contain the
+The `build.info` files that are spread over the source tree contain the
minimum information needed to build and distribute OpenSSL. It uses a
simple and yet fairly powerful language to determine what needs to be
built, from what sources, and other relationships between files.
-For every build.info file, all file references are relative to the
-directory of the build.info file for source files, and the
+For every `build.info` file, all file references are relative to the
+directory of the `build.info` file for source files, and the
corresponding build directory for built files if the build tree
differs from the source tree.
When processed, every line is processed with the perl module
-Text::Template, using the delimiters "{-" and "-}". The hashes
-%config and %target are passed to the perl fragments, along with
+Text::Template, using the delimiters `{-` and `-}`. The hashes
+`%config` and `%target` are passed to the perl fragments, along with
$sourcedir and $builddir, which are the locations of the source
-directory for the current build.info file and the corresponding build
+directory for the current `build.info` file and the corresponding build
directory, all relative to the top of the build tree.
-'Configure' only knows inherently about the top build.info file. For
+`Configure` only knows inherently about the top `build.info` file. For
any other directory that has one, further directories to look into
must be indicated like this:
@@ -393,7 +396,7 @@ This should be rarely used, and care should be taken to make sure it's
only used when supported. For example, native Windows build doesn't
support building static libraries and DLLs at the same time, so using
static libraries on Windows can only be done when configured
-'no-shared'.
+`no-shared`.
In some cases, it's desirable to include some source files in the
shared form of a library only:
@@ -435,7 +438,7 @@ be used in that case:
NOTE: GENERATE lines are limited to one command only per GENERATE.
-Finally, you can have some simple conditional use of the build.info
+Finally, you can have some simple conditional use of the `build.info`
information, looking like this:
IF[1]
@@ -461,37 +464,37 @@ conditions based on something in the passed variables, for example:
SOURCE[libfoo]=...
ENDIF
-
Build-file programming with the "unified" build system
======================================================
-"Build files" are called "Makefile" on Unix-like operating systems,
-"descrip.mms" for MMS on VMS, "makefile" for nmake on Windows, etc.
+"Build files" are called `Makefile` on Unix-like operating systems,
+`descrip.mms` for MMS on VMS, `makefile` for `nmake` on Windows, etc.
To use the "unified" build system, the target configuration needs to
-set the three items 'build_scheme', 'build_file' and 'build_command'.
-In the rest of this section, we will assume that 'build_scheme' is set
+set the three items `build_scheme`, `build_file` and `build_command`.
+In the rest of this section, we will assume that `build_scheme` is set
to "unified" (see the configurations documentation above for the
details).
-For any name given by 'build_file', the "unified" system expects a
-template file in Configurations/ named like the build file, with
-".tmpl" appended, or in case of possible ambiguity, a combination of
-the second 'build_scheme' list item and the 'build_file' name. For
-example, if 'build_file' is set to "Makefile", the template could be
-Configurations/Makefile.tmpl or Configurations/unix-Makefile.tmpl.
-In case both Configurations/unix-Makefile.tmpl and
-Configurations/Makefile.tmpl are present, the former takes
+For any name given by `build_file`, the "unified" system expects a
+template file in `Configurations/` named like the build file, with
+`.tmpl` appended, or in case of possible ambiguity, a combination of
+the second `build_scheme` list item and the `build_file` name. For
+example, if `build_file` is set to `Makefile`, the template could be
+[`Configurations/Makefile.tmpl`](Makefile.tmpl) or
+[`Configurations/unix-Makefile.tmpl`](unix-Makefile.tmpl).
+In case both [`Configurations/unix-Makefile.tmpl`](Makefile.tmpl) and
+[`Configurations/Makefile.tmpl`](Makefile.tmpl) are present, the former takes
precedence.
The build-file template is processed with the perl module
-Text::Template, using "{-" and "-}" as delimiters that enclose the
+Text::Template, using `{-` and `-}` as delimiters that enclose the
perl code fragments that generate configuration-dependent content.
Those perl fragments have access to all the hash variables from
configdata.pem.
The build-file template is expected to define at least the following
-perl functions in a perl code fragment enclosed with "{-" and "-}".
+perl functions in a perl code fragment enclosed with `{-` and `-}`.
They are all expected to return a string with the lines they produce.
generatesrc - function that produces build file lines to generate
@@ -640,7 +643,6 @@ else, end it like this:
""; # Make sure no lingering values end up in the Makefile
-}
-
Configure helper scripts
========================
@@ -651,10 +653,10 @@ Checker scripts
These scripts are per platform family, to check the integrity of the
tools used for configuration and building. The checker script used is
-either {build_platform}-{build_file}-checker.pm or
-{build_platform}-checker.pm, where {build_platform} is the second
-'build_scheme' list element from the configuration target data, and
-{build_file} is 'build_file' from the same target data.
+either `{build_platform}-{build_file}-checker.pm` or
+`{build_platform}-checker.pm`, where `{build_platform}` is the second
+`build_scheme` list element from the configuration target data, and
+`{build_file}` is `build_file` from the same target data.
If the check succeeds, the script is expected to end with a non-zero
expression. If the check fails, the script can end with a zero, or
diff --git a/Configure b/Configure
index b8dfeec477..ce7c895ca0 100755
--- a/Configure
+++ b/Configure
@@ -301,7 +301,7 @@ foreach ( reverse sort( 'aes', 'aria', 'bf', 'camellia', 'cast', 'des', 'dh',
my %version = ();
collect_information(
- collect_from_file(catfile($srcdir,'VERSION')),
+ collect_from_file(catfile($srcdir,'VERSION.dat')),
qr/\s*(\w+)\s*=\s*(.*?)\s*$/ =>
sub {
# Only define it if there is a value at all
@@ -314,7 +314,7 @@ collect_information(
}
},
"OTHERWISE" =>
- sub { die "Something wrong with this line:\n$_\nin $srcdir/VERSION" },
+ sub { die "Something wrong with this line:\n$_\nin $srcdir/VERSION.dat" },
);
$config{major} = $version{MAJOR} // 'unknown';
@@ -330,7 +330,7 @@ $config{release_date} = $version{RELEASE_DATE} // 'xx XXX xxxx';
$config{version} = "$config{major}.$config{minor}.$config{patch}";
$config{full_version} = "$config{version}$config{prerelease}$config{build_metadata}";
-die "erroneous version information in VERSION: ",
+die "erroneous version information in VERSION.dat: ",
"$config{version}, $config{shlib_version}\n"
unless (defined $version{MAJOR}
&& defined $version{MINOR}
@@ -2739,7 +2739,7 @@ sub death_handler {
my @message = ( <<"_____", @_ );
Failure! $build_file wasn't produced.
-Please read INSTALL.md and associated NOTES files. You may also have to
+Please read INSTALL.md and associated NOTES-* files. You may also have to
look over your available compiler tool chain or change your configuration.
_____
diff --git a/HACKING b/HACKING
deleted file mode 100644
index abf199f541..0000000000
--- a/HACKING
+++ /dev/null
@@ -1,26 +0,0 @@
- MODIFYING OPENSSL SOURCE
- ------------------------
- This document describes the way to add custom modifications to OpenSSL sources.
-
- If you are adding new public functions to the custom library build, you need to
- either add a prototype in one of the existing OpenSSL header files;
- or provide a new header file and edit Configurations/unix-Makefile.tmpl to pick up that file.
-
- After that perform the following steps:
-
- ./Configure -Werror --strict-warnings [your-options]
- make update
- make
- make test
-
- "make update" ensures that your functions declarations are added to util/libcrypto.num or util/libssl.num
- If you plan to submit the changes you made to OpenSSL (see CONTRIBUTING), it's worth running:
-
- make doc-nits
-
- after running "make update" to ensure that documentation has correct format.
-
- "make update" also generates files related to OIDs (in the crypto/objects/ folder) and errors.
- If a merge error occurs in one of these generated files then the generated files need to be removed
- and regenerated using "make update".
- To aid in this process the generated files can be committed separately so they can be removed easily.
diff --git a/HACKING.md b/HACKING.md
new file mode 100644
index 0000000000..6375450c24
--- /dev/null
+++ b/HACKING.md
@@ -0,0 +1,33 @@
+MODIFYING OPENSSL SOURCE
+========================
+
+This document describes the way to add custom modifications to OpenSSL sources.
+
+ If you are adding new public functions to the custom library build, you need to
+ either add a prototype in one of the existing OpenSSL header files;
+ or provide a new header file and edit
+ [Configurations/unix-Makefile.tmpl](Configurations/unix-Makefile.tmpl)
+ to pick up that file.
+
+ After that perform the following steps:
+
+ ./Configure -Werror --strict-warnings [your-options]
+ make update
+ make
+ make test
+
+ `make update` ensures that your functions declarations are added to
+ `util/libcrypto.num` or `util/libssl.num`.
+ If you plan to submit the changes you made to OpenSSL
+ (see [CONTRIBUTING.md](CONTRIBUTING.md)), it's worth running:
+
+ make doc-nits
+
+ after running `make update` to ensure that documentation has correct format.
+
+ `make update` also generates files related to OIDs (in the `crypto/objects/`
+ folder) and errors.
+ If a merge error occurs in one of these generated files then the
+ generated files need to be removed and regenerated using `make update`.
+ To aid in this process the generated files can be committed separately
+ so they can be removed easily.
diff --git a/INSTALL.md b/INSTALL.md
index 5686415ad8..3ad854823b 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -48,8 +48,8 @@ Prerequisites
To install OpenSSL, you will need:
* A "make" implementation
- * Perl 5 with core modules (please read [NOTES.PERL](NOTES.PERL))
- * The Perl module Text::Template (please read [NOTES.PERL](NOTES.PERL))
+ * Perl 5 with core modules (please read [NOTES-Perl.md](NOTES-Perl.md))
+ * The Perl module `Text::Template` (please read [NOTES-PERL.md](NOTES-Perl.md))
* an ANSI C compiler
* a development environment in the form of development libraries and C
header files
@@ -58,13 +58,13 @@ To install OpenSSL, you will need:
For additional platform specific requirements, solutions to specific
issues and other details, please read one of these:
- * [NOTES.UNIX](NOTES.UNIX) - notes for Unix like systems
- * [NOTES.VMS](NOTES.VMS) - notes related to OpenVMS
- * [NOTES.WIN](NOTES.WIN) - notes related to the Windows platform
- * [NOTES.DJGPP](NOTES.DJGPP) - building for DOS with DJGPP
- * [NOTES.ANDROID](NOTES.ANDROID) - building for Android platforms (using NDK)
- * [NOTES.VALGRIND](NOTES.VALGRIND) - testing with Valgrind
- * [NOTES.PERL](NOTES.PERL) - some notes on Perl
+ * [NOTES-Unix.md](NOTES-Unix.md) - notes for Unix like systems
+ * [NOTES-VMS.md](NOTES-VMS.md) - notes related to OpenVMS
+ * [NOTES-Windows.txt](NOTES-Windows.txt) - notes related to the Windows platform
+ * [NOTES-DJGPP.md](NOTES-DJGPP.md) - building for DOS with DJGPP
+ * [NOTES-Android.md](NOTES-Android.md) - building for Android platforms (using NDK)
+ * [NOTES-Valgrind.md](NOTES-Valgrind.md) - testing with Valgrind
+ * [NOTES-Perl.m](NOTES-Perl.md) - some notes on Perl
Notational conventions
======================
@@ -275,7 +275,7 @@ On OpenVMS:
$ perl Configure --prefix=PROGRAM:[INSTALLS] --openssldir=SYS$MANAGER:[OPENSSL]
Note: if you do add options to the configuration command, please make sure
-you've read more than just this Quick Start, such as relevant `NOTES.*` files,
+you've read more than just this Quick Start, such as relevant `NOTES-*` files,
the options outline below, as configuration options may change the outcome
in otherwise unexpected ways.
@@ -285,7 +285,7 @@ Configuration Options
There are several options to `./Configure` to customize the build (note that
for Windows, the defaults for `--prefix` and `--openssldir` depend on what
configuration is used and what Windows implementation OpenSSL is built on.
-More notes on this in [NOTES.WIN](NOTES.WIN)):
+More notes on this in [NOTES-Windows.txt](NOTES-Windows.txt):
API Level
---------
@@ -680,7 +680,8 @@ external test suites are currently supported:
- Python PYCA/Cryptography test suite
- krb5 test suite
-See the file [test/README.external](test/README.external) for further details.
+See the file [test/README-external.md](test/README-external.md)
+for further details.
### no-filenames
@@ -1152,8 +1153,8 @@ run:
If your system isn't listed, you will have to create a configuration
file named `Configurations/{{ something }}.conf` and add the correct
configuration for your system. See the available configs as examples
-and read [Configurations/README](Configurations/README)
-and [Configurations/README.design](Configurations/README.design)
+and read [Configurations/README.md](Configurations/README.md) and
+[Configurations/README-design.md](Configurations/README-design.md)
for more information.
The generic configurations `cc` or `gcc` should usually work on 32 bit
@@ -1223,7 +1224,9 @@ be tested. Run:
**Warning:** you MUST run the tests from an unprivileged account (or disable
your privileges temporarily if your platform allows it).
-See the file [test/README.md](test/README.md) for further details.
+See [test/README.md](test/README.md) for further details how run tests.
+
+See [test/README-dev.md](test/README-dev.md) for guidelines on adding tests.
Install OpenSSL
---------------
@@ -1359,7 +1362,8 @@ over the build process. Typically these should be defined prior to running
Use a different build file name than the platform default
("Makefile" on Unix-like platforms, "makefile" on native Windows,
"descrip.mms" on OpenVMS). This requires that there is a
- corresponding build file template. See Configurations/README
+ corresponding build file template.
+ See [Configurations/README.md](Configurations/README.md)
for further information.
CC
@@ -1382,15 +1386,15 @@ over the build process. Typically these should be defined prior to running
templates for those platforms. The database is comprised of
".conf" files in the Configurations directory. The build
file templates reside there as well as ".tmpl" files. See the
- file Configurations/README for further information about the
- format of ".conf" files as well as information on the ".tmpl"
- files.
+ file [Configurations/README.md](Configurations/README.md)
+ for further information about the format of ".conf" files
+ as well as information on the ".tmpl" files.
In addition to the standard ".conf" and ".tmpl" files, it is
- possible to create your own ".conf" and ".tmpl" files and store
- them locally, outside the OpenSSL source tree. This environment
- variable can be set to the directory where these files are held
- and will be considered by Configure before it looks in the
- standard directories.
+ possible to create your own ".conf" and ".tmpl" files and
+ store them locally, outside the OpenSSL source tree.
+ This environment variable can be set to the directory where
+ these files are held and will be considered by Configure
+ before it looks in the standard directories.
PERL
The name of the Perl executable to use when building OpenSSL.
@@ -1501,7 +1505,7 @@ cases it does not succeed. You will see a message like the following:
$ ./Configure
Operating system: x86-whatever-minix
- This system (minix) is not supported. See file INSTALL for details.
+ This system (minix) is not supported. See file INSTALL.md for details.
Even if the automatic target selection by the `./Configure` script fails,
chances are that you still might find a suitable target in the `Configurations`
@@ -1534,8 +1538,8 @@ known targets. Using `grep`, you can lookup the target definition in the
The directory contains two README files, which explain the general syntax and
design of the configuration files.
- - [Configurations/README](Configurations/README)
- - [Configurations/README.design](Configurations/README.design)
+ - [Configurations/README.md](Configurations/README.md)
+ - [Configurations/README-design.md](Configurations/README-design.md)
If you need further help, try to search the [openssl-users][] mailing list
or the [GitHub Issues][] for existing solutions. If you don't find anything,
diff --git a/LICENSE b/LICENSE.txt
similarity index 100%
rename from LICENSE
rename to LICENSE.txt
diff --git a/NEWS.md b/NEWS.md
index 9985bbfd05..e04e5b95c8 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1196,7 +1196,7 @@ OpenSSL 0.9.x
* Enhanced EVP interface.
[1] The support for external crypto devices is currently a separate
- distribution. See the file README.ENGINE.
+ distribution. See the file README-Engine.md.
### Major changes between OpenSSL 0.9.5 and OpenSSL 0.9.5a [1 Apr 2000]
diff --git a/NOTES.ANDROID b/NOTES-Android.md
similarity index 67%
rename from NOTES.ANDROID
rename to NOTES-Android.md
index 087d5e6f49..e1e7370d26 100644
--- a/NOTES.ANDROID
+++ b/NOTES-Android.md
@@ -1,6 +1,5 @@
-
- NOTES FOR ANDROID PLATFORMS
- ===========================
+NOTES FOR ANDROID PLATFORMS
+===========================
Requirement details
-------------------
@@ -15,27 +14,27 @@
Configuration
-------------
- Android is a cross-compiled target and you can't rely on ./Configure
+ Android is a cross-compiled target and you can't rely on `./Configure`
to find out the configuration target for you. You have to name your
- target explicitly; there are android-arm, android-arm64, android-mips,
- android-mip64, android-x86 and android-x86_64 (*MIPS targets are no
+ target explicitly; there are `android-arm`, `android-arm64`, `android-mips`,
+ `android-mip64`, `android-x86` and `android-x86_64` (`*MIPS` targets are no
longer supported with NDK R20+).
Do not pass --cross-compile-prefix (as you might be tempted), as it
will be "calculated" automatically based on chosen platform. However,
you still need to know the prefix to extend your PATH, in order to
- invoke $(CROSS_COMPILE)clang [*gcc on NDK 19 and lower] and company.
- (Configure will fail and give you a hint if you get it wrong.)
+ invoke `$(CROSS_COMPILE)clang` [`*gcc` on NDK 19 and lower] and company.
+ (`./Configure` will fail and give you a hint if you get it wrong.)
- Apart from PATH adjustment you need to set ANDROID_NDK_ROOT environment
- to point at the NDK directory. If you're using a side-by-side NDK the path
- will look something like /some/where/android-sdk/ndk/<ver>, and for a
- standalone NDK the path will be something like /some/where/android-ndk-<ver>.
+ Apart from `PATH` adjustment you need to set `ANDROID_NDK_ROOT` environment
+ to point at the `NDK` directory. If you're using a side-by-side NDK the path
+ will look something like `/some/where/android-sdk/ndk/<ver>`, and for a
+ standalone NDK the path will be something like `/some/where/android-ndk-<ver>`.
Both variables are significant at both configuration and compilation times.
- The NDK customarily supports multiple Android API levels, e.g. android-14,
- android-21, etc. By default latest API level is chosen. If you need to
- target an older platform pass the argument -D__ANDROID_API__=N to Configure,
- with N being the numerical value of the target platform version. For example,
+ The NDK customarily supports multiple Android API levels, e.g. `android-14`,
+ `android-21`, etc. By default latest API level is chosen. If you need to target
+ an older platform pass the argument `-D__ANDROID_API__=N` to `Configure`,
+ with `N` being the numerical value of the target platform version. For example,
to compile for Android 10 arm64 with a side-by-side NDK r20.0.5594570
export ANDROID_NDK_ROOT=/home/whoever/Android/android-sdk/ndk/20.0.5594570
@@ -52,13 +51,13 @@
./Configure android-arm -D__ANDROID_API__=14
make
- Caveat lector! Earlier OpenSSL versions relied on additional CROSS_SYSROOT
- variable set to $ANDROID_NDK_ROOT/platforms/android-<api>/arch-<arch> to
+ Caveat lector! Earlier OpenSSL versions relied on additional `CROSS_SYSROOT`
+ variable set to `$ANDROID_NDK_ROOT/platforms/android-<api>/arch-<arch>` to
appoint headers-n-libraries' location. It's still recognized in order
to facilitate migration from older projects. However, since API level
- appears in CROSS_SYSROOT value, passing -D__ANDROID_API__=N can be in
+ appears in `CROSS_SYSROOT` value, passing `-D__ANDROID_API__=N` can be in
conflict, and mixing the two is therefore not supported. Migration to
- CROSS_SYSROOT-less setup is recommended.
+ `CROSS_SYSROOT`-less setup is recommended.
One can engage clang by adjusting PATH to cover same NDK's clang. Just
keep in mind that if you miss it, Configure will try to use gcc...
@@ -68,9 +67,9 @@
Another option is to create so called "standalone toolchain" tailored
for single specific platform including Android API level, and assign its
- location to ANDROID_NDK_ROOT. In such case you have to pass matching
- target name to Configure and shouldn't use -D__ANDROID_API__=N. PATH
- adjustment becomes simpler, $ANDROID_NDK_ROOT/bin:$PATH suffices.
+ location to `ANDROID_NDK_ROOT`. In such case you have to pass matching
+ target name to Configure and shouldn't use `-D__ANDROID_API__=N`. `PATH`
+ adjustment becomes simpler, `$ANDROID_NDK_ROOT/bin:$PATH` suffices.
Running tests (on Linux)
------------------------
diff --git a/NOTES.DJGPP b/NOTES-DJGPP.md
similarity index 52%
rename from NOTES.DJGPP
rename to NOTES-DJGPP.md
index d43d4e86de..739710b09c 100644
--- a/NOTES.DJGPP
+++ b/NOTES-DJGPP.md
@@ -1,7 +1,5 @@
-
-
- INSTALLATION ON THE DOS PLATFORM WITH DJGPP
- -------------------------------------------
+INSTALLATION ON THE DOS PLATFORM WITH DJGPP
+===========================================
OpenSSL has been ported to DJGPP, a Unix look-alike 32-bit run-time
environment for 16-bit DOS, but only with long filename support.
@@ -11,28 +9,28 @@
You should have a full DJGPP environment installed, including the
latest versions of DJGPP, GCC, BINUTILS, BASH, etc. This package
- requires that PERL and the PERL module Text::Template also be
- installed (see NOTES.PERL).
+ requires that PERL and the PERL module `Text::Template` also be
+ installed (see [NOTES-Perl.md](NOTES-Perl.md)).
All of these can be obtained from the usual DJGPP mirror sites or
- directly at "http://www.delorie.com/pub/djgpp". For help on which
+ directly at <http://www.delorie.com/pub/djgpp>. For help on which
files to download, see the DJGPP "ZIP PICKER" page at
- "http://www.delorie.com/djgpp/zip-picker.html". You also need to have
+ <http://www.delorie.com/djgpp/zip-picker.html>. You also need to have
the WATT-32 networking package installed before you try to compile
- OpenSSL. This can be obtained from "http://www.watt-32.net/".
+ OpenSSL. This can be obtained from <http://www.watt-32.net/>.
The Makefile assumes that the WATT-32 code is in the directory
specified by the environment variable WATT_ROOT. If you have watt-32
- in directory "watt32" under your main DJGPP directory, specify
- WATT_ROOT="/dev/env/DJDIR/watt32".
+ in directory `watt32` under your main DJGPP directory, specify
+ `WATT_ROOT="/dev/env/DJDIR/watt32"`.
To compile OpenSSL, start your BASH shell, then configure for DJGPP by
- running "./Configure" with appropriate arguments:
+ running `./Configure` with appropriate arguments:
- ./Configure no-threads --prefix=/dev/env/DJDIR DJGPP
+ ./Configure no-threads --prefix=/dev/env/DJDIR DJGPP
- And finally fire up "make". You may run out of DPMI selectors when
+ And finally fire up `make`. You may run out of DPMI selectors when
running in a DOS box under Windows. If so, just close the BASH
- shell, go back to Windows, and restart BASH. Then run "make" again.
+ shell, go back to Windows, and restart BASH. Then run `make` again.
RUN-TIME CAVEAT LECTOR
--------------
@@ -41,8 +39,8 @@
"Cryptographic software needs a source of unpredictable data to work
correctly. Many open source operating systems provide a "randomness
- device" (/dev/urandom or /dev/random) that serves this purpose."
+ device" (`/dev/urandom` or `/dev/random`) that serves this purpose."
- As of version 0.9.7f DJGPP port checks upon /dev/urandom$ for a 3rd
- party "randomness" DOS driver. One such driver, NOISE.SYS, can be
- obtained from "http://www.rahul.net/dkaufman/index.html".
+ As of version 0.9.7f DJGPP port checks upon `/dev/urandom$` for a 3rd
+ party "randomness" DOS driver. One such driver, `NOISE.SYS`, can be
+ obtained from <http://www.rahul.net/dkaufman/index.html>.
diff --git a/NOTES.PERL b/NOTES-Perl.md
similarity index 71%
rename from NOTES.PERL
rename to NOTES-Perl.md
index 6c1d7c8cb1..13565dea6c 100644
--- a/NOTES.PERL
+++ b/NOTES-Perl.md
@@ -1,5 +1,5 @@
- TOC
- ===
+TOC
+===
- Notes on Perl
- Notes on Perl on Windows
@@ -18,10 +18,10 @@
installed properly. We do not claim to know them all, but experience
has told us the following:
- - on Linux distributions based on Debian, the package 'perl' will
+ - on Linux distributions based on Debian, the package `perl` will
install the core Perl modules as well, so you will be fine.
- on Linux distributions based on RPMs, you will need to install
- 'perl-core' rather than just 'perl'.
+ `perl-core` rather than just `perl`.
You MUST have at least Perl version 5.10.0 installed. This minimum
requirement is due to our use of regexp backslash sequence \R among
@@ -31,23 +31,23 @@
------------------------
There are a number of build targets that can be viewed as "Windows".
- Indeed, there are VC-* configs targeting VisualStudio C, as well as
+ Indeed, there are `VC-*` configs targeting VisualStudio C, as well as
MinGW and Cygwin. The key recommendation is to use "matching" Perl,
one that matches build environment. For example, if you will build
on Cygwin be sure to use the Cygwin package manager to install Perl.
For MSYS builds use the MSYS provided Perl.
- For VC-* builds we recommend Strawberry Perl, from http://strawberryperl.com.
- An alternative is ActiveState Perl, from http://www.activestate.com/ActivePerl
+ For VC-* builds we recommend Strawberry Perl, from <http://strawberryperl.com>.
+ An alternative is ActiveState Perl, from <http://www.activestate.com/ActivePerl>
for which you may need to explicitly select the Perl module Win32/Console.pm
- available via https://platform.activestate.com/ActiveState.
+ available via <https://platform.activestate.com/ActiveState>.
Notes on Perl on VMS
--------------------
You will need to install Perl separately. One way to do so is to
- download the source from http://perl.org/, unpacking it, reading
- README.vms and follow the instructions. Another way is to download a
- .PCSI file from http://www.vmsperl.com/ and install it using the
+ download the source from <http://perl.org/>, unpacking it, reading
+ `README-VMS.md` and follow the instructions. Another way is to download a
+ `.PCSI` file from <http://www.vmsperl.com/> and install it using the
POLYCENTER install tool.
Notes on Perl modules we use
@@ -57,18 +57,22 @@
ourselves to core Perl modules to keep the requirements down. There
are just a few exceptions:
- Test::More We require the minimum version to be 0.96, which
- appeared in Perl 5.13.4, because that version was
- the first to have all the features we're using.
- This module is required for testing only! If you
- don't plan on running the tests, you don't need to
- bother with this one.
+ * `Test::More`
- Text::Template This module is not part of the core Perl modules.
- As a matter of fact, the core Perl modules do not
- include any templating module to date.
- This module is absolutely needed, configuration
- depends on it.
+ We require the minimum version to be 0.96, which
+ appeared in Perl 5.13.4, because that version was
+ the first to have all the features we're using.
+ This module is required for testing only!
+ If you don't plan on running the tests,
+ you don't need to bother with this one.
+
+ * `Text::Template`
+
+ This module is not part of the core Perl modules.
+ As a matter of fact, the core Perl modules do not
+ include any templating module to date.
+ This module is absolutely needed,
+ configuration depends on it.
To avoid unnecessary initial hurdles, we have bundled a copy of the
following modules in our source. They will work as fallbacks if
@@ -80,7 +84,7 @@
---------------------------------
There are a number of ways to install a perl module. In all
- descriptions below, Text::Template will serve as an example.
+ descriptions below, `Text::Template` will serve as an example.
1. for Linux users, the easiest is to install with the use of your
favorite package manager. Usually, all you need to do is search
diff --git a/NOTES.UNIX b/NOTES-Unix.md
similarity index 69%
rename from NOTES.UNIX
rename to NOTES-Unix.md
index 0e3c099ea2..98f3a799cc 100644
--- a/NOTES.UNIX
+++ b/NOTES-Unix.md
@@ -1,9 +1,8 @@
+NOTES FOR UNIX-LIKE PLATFORMS
+=============================
- NOTES FOR UNIX LIKE PLATFORMS
- =============================
-
- For Unix/POSIX runtime systems on Windows, please see NOTES.WIN.
-
+ For Unix/POSIX runtime systems on Windows,
+ please see [NOTES-Windows.txt](NOTES-Windows.txt).
OpenSSL uses the compiler to link programs and shared libraries
---------------------------------------------------------------
@@ -13,21 +12,20 @@
objects. Because of this, any linking option that's given to the
configuration scripts MUST be in a form that the compiler can accept.
This varies between systems, where some have compilers that accept
- linker flags directly, while others take them in '-Wl,' form. You need
+ linker flags directly, while others take them in `-Wl,` form. You need
to read your compiler documentation to figure out what is acceptable,
- and ld(1) to figure out what linker options are available.
-
+ and `ld(1)` to figure out what linker options are available.
Shared libraries and installation in non-default locations
----------------------------------------------------------
Every Unix system has its own set of default locations for shared
- libraries, such as /lib, /usr/lib or possibly /usr/local/lib. If
+ libraries, such as `/lib`, `/usr/lib` or possibly `/usr/local/lib`. If
libraries are installed in non-default locations, dynamically linked
binaries will not find them and therefore fail to run, unless they get
a bit of help from a defined runtime shared library search path.
- For OpenSSL's application (the 'openssl' command), our configuration
+ For OpenSSL's application (the `openssl` command), our configuration
scripts do NOT generally set the runtime shared library search path for
you. It's therefore advisable to set it explicitly when configuring,
unless the libraries are to be installed in directories that you know
@@ -42,15 +40,15 @@
Possible options to set the runtime shared library search path include
the following:
- -Wl,-rpath,/whatever/path # Linux, *BSD, etc.
- -R /whatever/path # Solaris
- -Wl,-R,/whatever/path # AIX (-bsvr4 is passed internally)
- -Wl,+b,/whatever/path # HP-UX
- -rpath /whatever/path # Tru64, IRIX
+ -Wl,-rpath,/whatever/path # Linux, *BSD, etc.
+ -R /whatever/path # Solaris
+ -Wl,-R,/whatever/path # AIX (-bsvr4 is passed internally)
+ -Wl,+b,/whatever/path # HP-UX
+ -rpath /whatever/path # Tru64, IRIX
OpenSSL's configuration scripts recognise all these options and pass
them to the Makefile that they build. (In fact, all arguments starting
- with '-Wl,' are recognised as linker options.)
+ with `-Wl,` are recognised as linker options.)
Please do not use verbatim directories in your runtime shared library
search path! Some OpenSSL config targets add an extra directory level
@@ -63,28 +61,27 @@
'-Wl,-rpath,$(LIBRPATH)'
On modern ELF based systems, there are two runtime search paths tags to
- consider, DT_RPATH and DT_RUNPATH. Shared objects are searched for in
+ consider, `DT_RPATH` and `DT_RUNPATH`. Shared objects are searched for in
this order:
- 1. Using directories specified in DT_RPATH, unless DT_RUNPATH is
- also set.
- 2. Using the environment variable LD_LIBRARY_PATH
- 3. Using directories specified in DT_RUNPATH.
- 4. Using system shared object caches and default directories.
+ 1. Using directories specified in DT_RPATH, unless DT_RUNPATH is also set.
+ 2. Using the environment variable LD_LIBRARY_PATH
+ 3. Using directories specified in DT_RUNPATH.
+ 4. Using system shared object caches and default directories.
- This means that the values in the environment variable LD_LIBRARY_PATH
- won't matter if the library is found in the paths given by DT_RPATH
- (and DT_RUNPATH isn't set).
+ This means that the values in the environment variable `LD_LIBRARY_PATH`
+ won't matter if the library is found in the paths given by `DT_RPATH`
+ (and `DT_RUNPATH` isn't set).
- Exactly which of DT_RPATH or DT_RUNPATH is set by default appears to
+ Exactly which of `DT_RPATH` or `DT_RUNPATH` is set by default appears to
depend on the system. For example, according to documentation,
- DT_RPATH appears to be deprecated on Solaris in favor of DT_RUNPATH,
- while on Debian GNU/Linux, either can be set, and DT_RPATH is the
+ `DT_RPATH` appears to be deprecated on Solaris in favor of `DT_RUNPATH`,
+ while on Debian GNU/Linux, either can be set, and `DT_RPATH` is the
default at the time of writing.
How to choose which runtime search path tag is to be set depends on
your system, please refer to ld(1) for the exact information on your
- system. As an example, the way to ensure the DT_RUNPATH is set on
+ system. As an example, the way to ensure the `DT_RUNPATH` is set on
Debian GNU/Linux systems rather than DT_RPATH is to tell the linker to
set new dtags, like this:
@@ -93,7 +90,7 @@
It might be worth noting that some/most ELF systems implement support
for runtime search path relative to the directory containing current
- executable, by interpreting $ORIGIN along with some other internal
+ executable, by interpreting `$ORIGIN` along with some other internal
variables. Consult your system documentation.
Linking your application
@@ -104,7 +101,7 @@
The OpenSSL config options mentioned above might or might not have bearing
on linking of the target application. "Might" means that under some
circumstances it would be sufficient to link with OpenSSL shared library
- "naturally", i.e. with -L/whatever/path -lssl -lcrypto. But there are
+ "naturally", i.e. with `-L/whatever/path -lssl -lcrypto`. But there are
also cases when you'd have to explicitly specify runtime search path
when linking your application. Consult your system documentation and use
above section as inspiration...
@@ -114,4 +111,4 @@
for shared libraries first and tend to remain "blind" to static OpenSSL
libraries. Referring to system documentation would suffice, if not for
a corner case. On AIX static libraries (in shared build) are named
- differently, add _a suffix to link with them, e.g. -lcrypto_a.
+ differently, add `_a` suffix to link with them, e.g. `-lcrypto_a`.
diff --git a/NOTES.VMS b/NOTES-VMS.md
similarity index 81%
rename from NOTES.VMS
rename to NOTES-VMS.md
index c82e231ad7..c317e82de2 100644
--- a/NOTES.VMS
+++ b/NOTES-VMS.md
@@ -1,17 +1,15 @@
-
- NOTES FOR THE OPENVMS PLATFORM
- ==============================
+NOTES FOR THE OPENVMS PLATFORM
+==============================
Requirement details
-------------------
- In addition to the requirements and instructions listed in INSTALL,
- this are required as well:
+ In addition to the requirements and instructions listed
+ in [INSTALL.md](INSTALL.md), this are required as well:
* At least ODS-5 disk organization for source and build.
Installation can be done on any existing disk organization.
-
About ANSI C compiler
---------------------
@@ -22,20 +20,19 @@
version 7.1 or later. Compiling with a different ANSI C compiler may
require some work.
- Please avoid using C RTL feature logical names DECC$* when building
+ Please avoid using C RTL feature logical names `DECC$*` when building
and testing OpenSSL. Most of all, they can be disruptive when
running the tests, as they affect the Perl interpreter.
-
About ODS-5 directory names and Perl
------------------------------------
- It seems that the perl function canonpath() in the File::Spec module
+ It seems that the perl function canonpath() in the `File::Spec` module
doesn't treat file specifications where the last directory name
contains periods very well. Unfortunately, some versions of VMS tar
will keep the periods in the OpenSSL source directory instead of
converting them to underscore, thereby leaving your source in
- something like [.openssl-1^.1^.0]. This will lead to issues when
+ something like `[.openssl-1^.1^.0]`. This will lead to issues when
configuring and building OpenSSL.
We have no replacement for Perl's canonpath(), so the best workaround
@@ -44,7 +41,6 @@
$ rename openssl-1^.1^.0.DIR openssl-1_1_0.DIR
-
About MMS and DCL
-----------------
@@ -55,7 +51,6 @@
yourself up a few logical names for the directory trees you're going
to use.
-
About debugging
---------------
@@ -68,7 +63,7 @@
directly for debugging. Do not try to use them from a script, such
as running the test suite.
- *The following is not available on Alpha*
+ ### The following is not available on Alpha
As a compromise, we're turning off the flag that makes the debugger
start automatically. If there is a program that you need to debug,
@@ -81,7 +76,6 @@
$ set image /flag=nocall_debug [.test]evp_test.exe
-
Checking the distribution
-------------------------
@@ -92,16 +86,16 @@
The easiest way to check if everything got through as it should is to
check for one of the following files:
- [.crypto]opensslconf^.h.in
+ [.crypto]opensslconf^.h.in
The best way to get a correct distribution is to download the gzipped
- tar file from ftp://ftp.openssl.org/source/, use GZIP -d to uncompress
- it and VMSTAR to unpack the resulting tar file.
+ tar file from ftp://ftp.openssl.org/source/, use `GZIP -d` to uncompress
+ it and `VMSTAR` to unpack the resulting tar file.
Gzip and VMSTAR are available here:
- http://antinode.info/dec/index.html#Software
+ <http://antinode.info/dec/index.html#Software>
Should you need it, you can find UnZip for VMS here:
- http://www.info-zip.org/UnZip.html
+ <http://www.info-zip.org/UnZip.html>
diff --git a/NOTES.VALGRIND b/NOTES-Valgrind.md
similarity index 64%
rename from NOTES.VALGRIND
rename to NOTES-Valgrind.md
index 0ecca4f7dc..00647cbd9b 100644
--- a/NOTES.VALGRIND
+++ b/NOTES-Valgrind.md
@@ -1,4 +1,3 @@
-
NOTES FOR VALGRIND
==================
@@ -14,11 +13,11 @@ Requirements
------------
1. Platform supported by Valgrind
- See: http://valgrind.org/info/platforms.html
+ See <http://valgrind.org/info/platforms.html>
2. Valgrind installed on the platform
- See: http://valgrind.org/downloads/current.html
+ See <http://valgrind.org/downloads/current.html>
3. OpensSSL compiled
- See: [INSTALL.md](INSTALL.md)
+ See [INSTALL.md](INSTALL.md)
Running Tests
-------------
@@ -28,18 +27,19 @@ Test behavior can be modified by adjusting environment variables.
`EXE_SHELL`
This variable is used to specify the shell used to execute OpenSSL test
-programs. The default wrapper (util/wrap.pl) initializes the environment
+programs. The default wrapper (`util/wrap.pl`) initializes the environment
to allow programs to find shared libraries. The variable can be modified
to specify a different executable environment.
- EXE_SHELL="`/bin/pwd`/util/wrap.pl valgrind --error-exitcode=1 --leak-check=full -q"
+ EXE_SHELL=\
+ "`/bin/pwd`/util/wrap.pl valgrind --error-exitcode=1 --leak-check=full -q"
-This will start up Valgrind with the default checker (memcheck).
-The --error-exitcode=1 option specifies that Valgrind should exit with an
+This will start up Valgrind with the default checker (`memcheck`).
+The `--error-exitcode=1` option specifies that Valgrind should exit with an
error code of 1 when memory leaks occur.
-The --leak-check=full option specifies extensive memory checking.
-The -q option prints only error messages.
-Additional Valgrind options may be added to the EXE_SHELL variable.
+The `--leak-check=full` option specifies extensive memory checking.
+The `-q` option prints only error messages.
+Additional Valgrind options may be added to the `EXE_SHELL` variable.
`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
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
file [test/README.md](test/README.md).
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`
-variable with the VERBOSE option to gather additional information.
+If an error occurs, you can then run the specific test via the `TESTS` variable
+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"
diff --git a/NOTES.WIN b/NOTES-Windows.txt
similarity index 100%
rename from NOTES.WIN
rename to NOTES-Windows.txt
diff --git a/README-Engine.md b/README-Engine.md
new file mode 100644
index 0000000000..2fc4e40a2b
--- /dev/null
+++ b/README-Engine.md
@@ -0,0 +1,308 @@
+ENGINES
+=======
+
+ With OpenSSL 0.9.6, a new component was added to support alternative
+ cryptography implementations, most commonly for interfacing with external
+ crypto devices (eg. accelerator cards). This component is called ENGINE,
+ and its presence in OpenSSL 0.9.6 (and subsequent bug-fix releases)
+ caused a little confusion as 0.9.6** releases were rolled in two
+ versions, a "standard" and an "engine" version. In development for 0.9.7,
+ the ENGINE code has been merged into the main branch and will be present
+ in the standard releases from 0.9.7 forwards.
+
+ There are currently built-in ENGINE implementations for the following
+ crypto devices:
+
+ * Microsoft CryptoAPI
+ * VIA Padlock
+ * nCipher CHIL
+
+ In addition, dynamic binding to external ENGINE implementations is now
+ provided by a special ENGINE called "dynamic". See the "DYNAMIC ENGINE"
+ section below for details.
+
+ At this stage, a number of things are still needed and are being worked on:
+
+ 1. Integration of EVP support.
+ 2. Configuration support.
+ 3. Documentation!
+
+ 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
+ algorithms/modes (or previously unimplemented ones) can be provided by
+ ENGINE implementations.
+
+ 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
+ user/admin the set of commands and parameter types a given ENGINE
+ implementation supports, and for an application to directly feed string
+ based input to those ENGINEs, in the form of name-value pairs. This is an
+ extensible way for ENGINEs to define their own "configuration" mechanisms
+ that are specific to a given ENGINE (eg. for a particular hardware
+ device) but that should be consistent across *all* OpenSSL-based
+ applications when they use that ENGINE. Work is in progress (or at least
+ in planning) for supporting these control commands from the CONF (or
+ NCONF) code so that applications using OpenSSL's existing configuration
+ file format can have ENGINE settings specified in much the same way.
+ Presently however, applications must use the ENGINE API itself to provide
+ such functionality. To see first hand the types of commands available
+ with the various compiled-in ENGINEs (see further down for dynamic
+ ENGINEs), use the "engine" openssl utility with full verbosity, i.e.:
+
+ openssl engine -vvvv
+
+ Documentation
+ -------------
+
+ Documentation? Volunteers welcome! The source code is reasonably well
+ self-documenting, but some summaries and usage instructions are needed -
+ moreover, they are needed in the same POD format the existing OpenSSL
+ documentation is provided in. Any complete or incomplete contributions
+ would help make this happen.
+
+ STABILITY & BUG-REPORTS
+ =======================
+
+ What already exists is fairly stable as far as it has been tested, but
+ the test base has been a bit small most of the time. For the most part,
+ the vendors of the devices these ENGINEs support have contributed to the
+ development and/or testing of the implementations, and *usually* (with no
+ guarantees) have experience in using the ENGINE support to drive their
+ devices from common OpenSSL-based applications. Bugs and/or inexplicable
+ behaviour in using a specific ENGINE implementation should be sent to the
+ author of that implementation (if it is mentioned in the corresponding C
+ file), and in the case of implementations for commercial hardware
+ devices, also through whatever vendor support channels are available. If
+ none of this is possible, or the problem seems to be something about the
+ ENGINE API itself (ie. not necessarily specific to a particular ENGINE
+ implementation) then you should mail complete details to the relevant
+ OpenSSL mailing list. For a definition of "complete details", refer 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
+ pre-compiled application or in your own application code.
+
+ * openssl-dev: if you are discussing problems with OpenSSL source code.
+
+ USAGE
+ =====
+
+ The default "openssl" ENGINE is always chosen when performing crypto
+ operations unless you specify otherwise. You must actively tell the
+ openssl utility commands to use anything else through a new command line
+ switch called "-engine". Also, if you want to use the ENGINE support in
+ your own code to do something similar, you must likewise explicitly
+ select the ENGINE implementation you want.
+
+ Depending on the type of hardware, system, and configuration, "settings"
+ may need to be applied to an ENGINE for it to function as expected/hoped.
+ The recommended way of doing this is for the application to support
+ ENGINE "control commands" so that each ENGINE implementation can provide
+ whatever configuration primitives it might require and the application
+ can allow the user/admin (and thus the hardware vendor's support desk
+ also) to provide any such input directly to the ENGINE implementation.
+ This way, applications do not need to know anything specific to any
+ device, they only need to provide the means to carry such user/admin
+ input through to the ENGINE in question. Ie. this connects *you* (and
+ your helpdesk) to the specific ENGINE implementation (and device), and
+ allows application authors to not get buried in hassle supporting
+ arbitrary devices they know (and care) nothing about.
+
+ A new "openssl" utility, "openssl engine", has been added in that allows
+ for testing and examination of ENGINE implementations. Basic usage
+ instructions are available by specifying the "-?" command line switch.
+
+ DYNAMIC ENGINES
+ ===============
+
+ The new "dynamic" ENGINE provides a low-overhead way to support ENGINE
+ implementations that aren't pre-compiled and linked into OpenSSL-based
+ applications. This could be because existing compiled-in implementations
+ have known problems and you wish to use a newer version with an existing
+ application. It could equally be because the application (or OpenSSL
+ library) you are using simply doesn't have support for the ENGINE you
+ wish to use, and the ENGINE provider (eg. hardware vendor) is providing
+ you with a self-contained implementation in the form of a shared-library.
+ The other use-case for "dynamic" is with applications that wish to
+ maintain the smallest foot-print possible and so do not link in various
+ ENGINE implementations from OpenSSL, but instead leaves you to provide
+ them, if you want them, in the form of "dynamic"-loadable
+ shared-libraries. It should be possible for hardware vendors to provide
+ their own shared-libraries to support arbitrary hardware to work with
+ applications based on OpenSSL 0.9.7 or later. If you're using an
+ application based on 0.9.7 (or later) and the support you desire is only
+ announced for versions later than the one you need, ask the vendor to
+ backport their ENGINE to the version you need.
+
+ 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 "SO_PATH" control command should be used to identify the
+ 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");
+ ENGINE_ctrl_cmd_string(e, "SO_PATH", "/lib/libfoo.so", 0);
+ 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);
+
+ For testing, the "openssl engine" utility can be useful for this sort
+ of thing. For example the above code excerpt would achieve much the
+ same result as;
+
+ openssl engine dynamic \
+ -pre SO_PATH:/lib/libfoo.so \
+ -pre ID:foo \
+ -pre LOAD \
+ -pre "CMD_FOO:some input data"
+
+ Or to simply see the list of commands supported by the "foo" ENGINE;
+
+ openssl engine -vvvv dynamic \
+ -pre SO_PATH:/lib/libfoo.so \
+ -pre ID:foo \
+ -pre LOAD
+
+ Applications that support the ENGINE API and more specifically, the
+ "control commands" mechanism, will provide some way for you to pass
+ such commands through to ENGINEs. As such, you would select "dynamic"
+ as the ENGINE to use, and the parameters/commands you pass would
+ control the *actual* ENGINE used. Each command is actually a name-value
+ pair and the value can sometimes be omitted (eg. the "LOAD" command).
+ Whilst the syntax demonstrated in "openssl engine" uses a colon to
+ separate the command name from the value, applications may provide
+ their own syntax for making that separation (eg. a win32 registry
+ key-value pair may be used by some applications). The reason for the
+ "-pre" syntax in the "openssl engine" utility is that some commands
+ might be issued to an ENGINE *after* it has been initialised for use.
+ Eg. if an ENGINE implementation requires a smart-card to be inserted
+ during initialisation (or a PIN to be typed, or whatever), there may be
+ a control command you can issue afterwards to "forget" the smart-card
+ so that additional initialisation is no longer possible. In
+ applications such as web-servers, where potentially volatile code may
+ 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?
+ ----------------------------------
+
+ 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
+ a shared-library that can be loaded by "dynamic" isn't automated in
+ OpenSSL's build process. It can be done manually quite easily however.
+ Such a shared-library can either be built with any OpenSSL code it
+ needs statically linked in, or it can link dynamically against OpenSSL
+ if OpenSSL itself is built as a shared library. The instructions are
+ the same in each case, but in the former (statically linked any
+ dependencies on OpenSSL) you must ensure OpenSSL is built with
+ position-independent code ("PIC"). The default OpenSSL compilation may
+ already specify the relevant flags to do this, but you should consult
+ with your compiler documentation if you are in any doubt.
+
+ This example will show building the "atalla" ENGINE in the
+ crypto/engine/ directory as a shared-library for use via the "dynamic"
+ ENGINE.
+
+ 1. "cd" to the crypto/engine/ directory of a pre-compiled OpenSSL
+ source tree.
+
+ 2. Recompile at least one source file so you can see all the compiler
+ flags (and syntax) being used to build normally. Eg;
+
+ touch hw_atalla.c ; make
+
+ will rebuild "hw_atalla.o" using all such flags.
+
+ 3. Manually enter the same compilation line to compile the
+ "hw_atalla.c" file but with the following two changes;
+ * add "-DENGINE_DYNAMIC_SUPPORT" to the command line switches,
+ * change the output file from "hw_atalla.o" to something new,
+ 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
+ ========
+
+ It seems like the ENGINE part doesn't work too well with CryptoSwift on Win32.
+ A quick test done right before the release showed that trying "openssl speed
+ -engine cswift" generated errors. If the DSO gets enabled, an attempt is made
+ to write at memory address 0x00000002.
+
diff --git a/README.FIPS b/README-FIPS.md
similarity index 58%
rename from README.FIPS
rename to README-FIPS.md
index 859348664e..ec70370177 100644
--- a/README.FIPS
+++ b/README-FIPS.md
@@ -1 +1,4 @@
+OpenSSL FIPS support
+====================
+
This release does not support a FIPS 140-2 validated module.
diff --git a/README.ENGINE b/README.ENGINE
deleted file mode 100644
index 230dc82a87..0000000000
--- a/README.ENGINE
+++ /dev/null
@@ -1,287 +0,0 @@
- ENGINE
- ======
-
- With OpenSSL 0.9.6, a new component was added to support alternative
- cryptography implementations, most commonly for interfacing with external
- crypto devices (eg. accelerator cards). This component is called ENGINE,
- and its presence in OpenSSL 0.9.6 (and subsequent bug-fix releases)
- caused a little confusion as 0.9.6** releases were rolled in two
- versions, a "standard" and an "engine" version. In development for 0.9.7,
- the ENGINE code has been merged into the main branch and will be present
- in the standard releases from 0.9.7 forwards.
-
- There are currently built-in ENGINE implementations for the following
- crypto devices:
-
- o Microsoft CryptoAPI
- o VIA Padlock
- o nCipher CHIL
-
- In addition, dynamic binding to external ENGINE implementations is now
- provided by a special ENGINE called "dynamic". See the "DYNAMIC ENGINE"
- section below for details.
-
- At this stage, a number of things are still needed and are being worked on:
-
- 1 Integration of EVP support.
- 2 Configuration support.
- 3 Documentation!
-
-1 With respect to EVP, this relates to support for ciphers and digests in
- the ENGINE model so that alternative implementations of existing
- algorithms/modes (or previously unimplemented ones) can be provided by
- ENGINE implementations.
-
-2 Configuration support currently exists in the ENGINE API itself, in 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
- implementation supports, and for an application to directly feed string
- based input to those ENGINEs, in the form of name-value pairs. This is an
- extensible way for ENGINEs to define their own "configuration" mechanisms
- that are specific to a given ENGINE (eg. for a particular hardware
- device) but that should be consistent across *all* OpenSSL-based
- applications when they use that ENGINE. Work is in progress (or at least
- in planning) for supporting these control commands from the CONF (or
- NCONF) code so that applications using OpenSSL's existing configuration
- file format can have ENGINE settings specified in much the same way.
- Presently however, applications must use the ENGINE API itself to provide
- such functionality. To see first hand the types of commands available
- with the various compiled-in ENGINEs (see further down for dynamic
- ENGINEs), use the "engine" openssl utility with full verbosity, ie;
- openssl engine -vvvv
-
-3 Documentation? Volunteers welcome! The source code is reasonably well
- self-documenting, but some summaries and usage instructions are needed -
- moreover, they are needed in the same POD format the existing OpenSSL
- documentation is provided in. Any complete or incomplete contributions
- would help make this happen.
-
- STABILITY & BUG-REPORTS
- =======================
-
- What already exists is fairly stable as far as it has been tested, but
- the test base has been a bit small most of the time. For the most part,
- the vendors of the devices these ENGINEs support have contributed to the
- development and/or testing of the implementations, and *usually* (with no
- guarantees) have experience in using the ENGINE support to drive their
- devices from common OpenSSL-based applications. Bugs and/or inexplicable
- behaviour in using a specific ENGINE implementation should be sent to the
- author of that implementation (if it is mentioned in the corresponding C
- file), and in the case of implementations for commercial hardware
- devices, also through whatever vendor support channels are available. If
- none of this is possible, or the problem seems to be something about the
- ENGINE API itself (ie. not necessarily specific to a particular ENGINE
- implementation) then you should mail complete details to the relevant
- OpenSSL mailing list. For a definition of "complete details", refer 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
- pre-compiled application or in your own application code.
-
- openssl-dev: if you are discussing problems with OpenSSL source code.
-
- USAGE
- =====
-
- The default "openssl" ENGINE is always chosen when performing crypto
- operations unless you specify otherwise. You must actively tell the
- openssl utility commands to use anything else through a new command line
- switch called "-engine". Also, if you want to use the ENGINE support in
- your own code to do something similar, you must likewise explicitly
- select the ENGINE implementation you want.
-
- Depending on the type of hardware, system, and configuration, "settings"
- may need to be applied to an ENGINE for it to function as expected/hoped.
- The recommended way of doing this is for the application to support
- ENGINE "control commands" so that each ENGINE implementation can provide
- whatever configuration primitives it might require and the application
- can allow the user/admin (and thus the hardware vendor's support desk
- also) to provide any such input directly to the ENGINE implementation.
- This way, applications do not need to know anything specific to any
- device, they only need to provide the means to carry such user/admin
- input through to the ENGINE in question. Ie. this connects *you* (and
- your helpdesk) to the specific ENGINE implementation (and device), and
- allows application authors to not get buried in hassle supporting
- arbitrary devices they know (and care) nothing about.
-
- A new "openssl" utility, "openssl engine", has been added in that allows
- for testing and examination of ENGINE implementations. Basic usage
- instructions are available by specifying the "-?" command line switch.
-
- DYNAMIC ENGINES
- ===============
-
- The new "dynamic" ENGINE provides a low-overhead way to support ENGINE
- implementations that aren't pre-compiled and linked into OpenSSL-based
- applications. This could be because existing compiled-in implementations
- have known problems and you wish to use a newer version with an existing
- application. It could equally be because the application (or OpenSSL
- library) you are using simply doesn't have support for the ENGINE you
- wish to use, and the ENGINE provider (eg. hardware vendor) is providing
- you with a self-contained implementation in the form of a shared-library.
- The other use-case for "dynamic" is with applications that wish to
- maintain the smallest foot-print possible and so do not link in various
- ENGINE implementations from OpenSSL, but instead leaves you to provide
- them, if you want them, in the form of "dynamic"-loadable
- shared-libraries. It should be possible for hardware vendors to provide
- their own shared-libraries to support arbitrary hardware to work with
- applications based on OpenSSL 0.9.7 or later. If you're using an
- application based on 0.9.7 (or later) and the support you desire is only
- announced for versions later than the one you need, ask the vendor to
- backport their ENGINE to the version you need.
-
- 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 "SO_PATH" control command should be used to identify the
- 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");
- ENGINE_ctrl_cmd_string(e, "SO_PATH", "/lib/libfoo.so", 0);
- 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);
-
- For testing, the "openssl engine" utility can be useful for this sort
- of thing. For example the above code excerpt would achieve much the
- same result as;
-
- openssl engine dynamic \
- -pre SO_PATH:/lib/libfoo.so \
- -pre ID:foo \
- -pre LOAD \
- -pre "CMD_FOO:some input data"
-
- Or to simply see the list of commands supported by the "foo" ENGINE;
-
- openssl engine -vvvv dynamic \
- -pre SO_PATH:/lib/libfoo.so \
- -pre ID:foo \
- -pre LOAD
-
- Applications that support the ENGINE API and more specifically, the
- "control commands" mechanism, will provide some way for you to pass
- such commands through to ENGINEs. As such, you would select "dynamic"
- as the ENGINE to use, and the parameters/commands you pass would
- control the *actual* ENGINE used. Each command is actually a name-value
- pair and the value can sometimes be omitted (eg. the "LOAD" command).
- Whilst the syntax demonstrated in "openssl engine" uses a colon to
- separate the command name from the value, applications may provide
- their own syntax for making that separation (eg. a win32 registry
- key-value pair may be used by some applications). The reason for the
- "-pre" syntax in the "openssl engine" utility is that some commands
- might be issued to an ENGINE *after* it has been initialised for use.
- Eg. if an ENGINE implementation requires a smart-card to be inserted
- during initialisation (or a PIN to be typed, or whatever), there may be
- a control command you can issue afterwards to "forget" the smart-card
- so that additional initialisation is no longer possible. In
- applications such as web-servers, where potentially volatile code may
- 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?
- ----------------------------------
- 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
- a shared-library that can be loaded by "dynamic" isn't automated in
- OpenSSL's build process. It can be done manually quite easily however.
- Such a shared-library can either be built with any OpenSSL code it
- needs statically linked in, or it can link dynamically against OpenSSL
- if OpenSSL itself is built as a shared library. The instructions are
- the same in each case, but in the former (statically linked any
- dependencies on OpenSSL) you must ensure OpenSSL is built with
- position-independent code ("PIC"). The default OpenSSL compilation may
- already specify the relevant flags to do this, but you should consult
- with your compiler documentation if you are in any doubt.
-
- This example will show building the "atalla" ENGINE in the
- crypto/engine/ directory as a shared-library for use via the "dynamic"
- ENGINE.
- 1) "cd" to the crypto/engine/ directory of a pre-compiled OpenSSL
- source tree.
- 2) Recompile at least one source file so you can see all the compiler
- flags (and syntax) being used to build normally. Eg;
- touch hw_atalla.c ; make
- will rebuild "hw_atalla.o" using all such flags.
- 3) Manually enter the same compilation line to compile the
- "hw_atalla.c" file but with the following two changes;
- (a) add "-DENGINE_DYNAMIC_SUPPORT" to the command line switches,
- (b) change the output file from "hw_atalla.o" to something new,
- 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
- ========
-
- It seems like the ENGINE part doesn't work too well with CryptoSwift on Win32.
- A quick test done right before the release showed that trying "openssl speed
- -engine cswift" generated errors. If the DSO gets enabled, an attempt is made
- to write at memory address 0x00000002.
-
diff --git a/README.md b/README.md
index e566d3161c..c126116ed8 100644
--- a/README.md
+++ b/README.md
@@ -105,13 +105,13 @@ detailed instructions about building and installing OpenSSL. For some
platforms, the installation instructions are amended by a platform specific
document.
- * [NOTES.ANDROID](NOTES.ANDROID)
- * [NOTES.DJGPP](NOTES.DJGPP)
- * [NOTES.PERL](NOTES.PERL)
- * [NOTES.UNIX](NOTES.UNIX)
- * [NOTES.VALGRIND](NOTES.VALGRIND)
- * [NOTES.VMS](NOTES.VMS)
- * [NOTES.WIN](NOTES.WIN)
+ * [NOTES-Android.md](NOTES-Android.md)
+ * [NOTES-DJGPP.md](NOTES-DJGPP.md)
+ * [NOTES-Unix.md](NOTES-Unix.md)
+ * [NOTES-VMS.md](NOTES-VMS.md)
+ * [NOTES-Windows.txt](NOTES-Windows.txt)
+ * [NOTES-Perl.m](NOTES-Perl.md)
+ * [NOTES-Valgrind.md](NOTES-Valgrind.md)
Specific notes on upgrading to OpenSSL 3.0 from previous versions, as well as
known issues are available on the OpenSSL
@@ -142,7 +142,7 @@ OpenSSL is licensed under the Apache License 2.0, which means that
you are free to get and use it for commercial and non-commercial
purposes as long as you fulfill its conditions.
-See the [LICENSE](LICENSE) file for more details.
+See the [LICENSE.txt](LICENSE.txt) file for more details.
Support
=======
diff --git a/VERSION b/VERSION.dat
similarity index 100%
rename from VERSION
rename to VERSION.dat
diff --git a/config.com b/config.com
index 1e1b925ab8..252cada5e9 100644
--- a/config.com
+++ b/config.com
@@ -42,7 +42,7 @@ Usage: @config [options]
-h This help.
Any other text will be passed to the Configure perl script.
-See INSTALL for instructions.
+See INSTALL.md for instructions.
$ EOD
$ ENDIF
diff --git a/crypto/README.sparse_array b/crypto/README-sparse_array.md
similarity index 93%
rename from crypto/README.sparse_array
rename to crypto/README-sparse_array.md
index d86a48d9e1..bc2ff0cb8a 100644
--- a/crypto/README.sparse_array
+++ b/crypto/README-sparse_array.md
@@ -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.
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
These constants are inter-related:
+
SA_BLOCK_MAX = 2 ^ OPENSSL_SA_BLOCK_BITS
SA_BLOCK_MASK = SA_BLOCK_MAX - 1
SA_BLOCK_MAX_LEVELS = number of bits in size_t divided by
OPENSSL_SA_BLOCK_BITS rounded up to the next multiple
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.
As a space and performance optimisation, the height of the tree is usually
@@ -67,7 +71,6 @@ brevity):
+----+
Index 0
-
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
user's new data:
@@ -102,7 +105,6 @@ user's new data:
+----+ +----+
Index 0 Index 2N+1
-
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.
The complexity is hidden and nodes are allocated on an as needed basis.
@@ -144,12 +146,11 @@ result in:
+----+
Index 2N+1
-
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.
Space usage is O(minimum(m, n log(n)) where m is the number of elements in the
array.
-Note: sparse arrays only include pointers to types. Thus, SPARSE_ARRAY_OF(char)
-can be used to store a string.
+Note: sparse arrays only include pointers to types.
+Thus, `SPARSE_ARRAY_OF(char)` can be used to store a string.
diff --git a/crypto/engine/README b/crypto/engine/README.md
similarity index 95%
rename from crypto/engine/README
rename to crypto/engine/README.md
index 0f8a8fbde4..b45115ca24 100644
--- a/crypto/engine/README
+++ b/crypto/engine/README.md
@@ -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
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
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
-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
"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"
algorithm/mode pair are;
-(i) directly;
- const EVP_CIPHER *cipher = EVP_des_cbc();
- EVP_EncryptInit(&ctx, cipher, key, iv);
- [ ... use EVP_EncryptUpdate() and EVP_EncryptFinal() ...]
+ (i) directly;
+ const EVP_CIPHER *cipher = EVP_des_cbc();
+ EVP_EncryptInit(&ctx, cipher, key, iv);
+ [ ... use EVP_EncryptUpdate() and EVP_EncryptFinal() ...]
-(ii) indirectly;
- OpenSSL_add_all_ciphers();
- cipher = EVP_get_cipherbyname("des_cbc");
- EVP_EncryptInit(&ctx, cipher, key, iv);
- [ ... etc ... ]
+ (ii) indirectly;
+ OpenSSL_add_all_ciphers();
+ cipher = EVP_get_cipherbyname("des_cbc");
+ EVP_EncryptInit(&ctx, cipher, key, iv);
+ [ ... etc ... ]
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
@@ -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
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
-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
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
@@ -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).
Hell, that should be enough for now ... comments welcome.
-
diff --git a/crypto/err/README b/crypto/err/README.md
similarity index 50%
rename from crypto/err/README
rename to crypto/err/README.md
index 6d2ce0cd0e..78085b3779 100644
--- a/crypto/err/README
+++ b/crypto/err/README.md
@@ -1,17 +1,17 @@
Adding new libraries
---------------------
+====================
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
-name to ERR_str_libraries[] (in crypto/err/err.c), and add
-ERR_load_XXX_strings() to the ERR_load_crypto_strings() function
-(in crypto/err/err_all.c). Finally, add an entry:
+`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
+`ERR_load_XXX_strings()` to the `ERR_load_crypto_strings()` function
+(in `crypto/err/err_all.c`). Finally, add an entry:
L XXX xxx.h xxx_err.c
-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
-add all error codes used in the library to xxx.h.
+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
+add all error codes used in the library to `xxx.h`.
Additionally the library include file must have a certain form.
Typically it will initially look like this:
@@ -33,12 +33,12 @@ Typically it will initially look like this:
/* 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
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
-files stdio.h, openssl/err.h and openssl/xxx.h so the
+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
header file must load any additional header files containing any
definitions it uses.
diff --git a/crypto/objects/README b/crypto/objects/README
deleted file mode 100644
index 700f9c5e54..0000000000
--- a/crypto/objects/README
+++ /dev/null
@@ -1,44 +0,0 @@
-objects.txt syntax
-------------------
-
-To cover all the naming hacks that were previously in objects.h needed some
-kind of hacks in objects.txt.
-
-The basic syntax for adding an object is as follows:
-
- 1 2 3 4 : shortName : Long Name
-
- If Long Name contains only word characters and hyphen-minus
- (0x2D) or full stop (0x2E) then Long Name is used as basis
- for the base name in C. Otherwise, the shortName is used.
-
- 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.
-
- Note that if the base name contains spaces, dashes or periods,
- those will be converted to underscore.
-
-Then there are some extra commands:
-
- !Alias foo 1 2 3 4
-
- This just makes a name foo for an OID. The C macro
- OBJ_foo will be created as a result.
-
- !Cname foo
-
- This makes sure that the name foo will be used as base name
- in C.
-
- !module foo
- 1 2 3 4 : shortName : Long Name
- !global
-
- The !module command was meant to define a kind of modularity.
- What it does is to make sure the module name is prepended
- to the base name. !global turns this off. This construction
- is not recursive.
-
-Lines starting with # are treated as comments, as well as any line starting
-with ! and not matching the commands above.
-
diff --git a/crypto/objects/README.md b/crypto/objects/README.md
new file mode 100644
index 0000000000..49c749887d
--- /dev/null
+++ b/crypto/objects/README.md
@@ -0,0 +1,43 @@
+objects.txt syntax
+==================
+
+To cover all the naming hacks that were previously in `objects.h` needed some
+kind of hacks in `objects.txt`.
+
+The basic syntax for adding an object is as follows:
+
+ 1 2 3 4 : shortName : Long Name
+
+ If Long Name contains only word characters and hyphen-minus
+ (0x2D) or full stop (0x2E) then Long Name is used as basis
+ for the base name in C. Otherwise, the shortName is used.
+
+ 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.
+
+ Note that if the base name contains spaces, dashes or periods,
+ those will be converted to underscore.
+
+Then there are some extra commands:
+
+ !Alias foo 1 2 3 4
+
+ This just makes a name foo for an OID. The C macro
+ OBJ_foo will be created as a result.
+
+ !Cname foo
+
+ This makes sure that the name foo will be used as base name
+ in C.
+
+ !module foo
+ 1 2 3 4 : shortName : Long Name
+ !global
+
+ The !module command was meant to define a kind of modularity.
+ What it does is to make sure the module name is prepended
+ to the base name. !global turns this off. This construction
+ is not recursive.
+
+Lines starting with `#` are treated as comments, as well as any line starting
+with ! and not matching the commands above.
diff --git a/crypto/perlasm/README b/crypto/perlasm/README
deleted file mode 100644
index 59f2c95515..0000000000
--- a/crypto/perlasm/README
+++ /dev/null
@@ -1,124 +0,0 @@
-The perl scripts in this directory are my 'hack' to generate
-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
-and then include it.
-
-push(@INC,"perlasm","../../perlasm");
-require "x86asm.pl";
-
-The first thing we do is setup the file and type of assembler
-
-&asm_init($ARGV[0]);
-
-The first argument is the 'type'. Currently
-'cpp', 'sol', 'a.out', 'elf' or 'win32'.
-Argument 2 is the file name.
-
-The reciprocal function is
-&asm_finish() which should be called at the end.
-
-There are 2 main 'packages'. x86ms.pl, which is the Microsoft assembler,
-and x86unix.pl which is the unix (gas) version.
-
-Functions of interest are:
-&external_label("des_SPtrans"); declare and external variable
-&LB(reg); Low byte for a register
-&HB(reg); High byte for a register
-&BP(off,base,index,scale) Byte pointer addressing
-&DWP(off,base,index,scale) Word pointer addressing
-&stack_push(num) Basically a 'sub esp, num*4' with extra
-&stack_pop(num) inverse of stack_push
-&function_begin(name,extra) Start a function with pushing of
- edi, esi, ebx and ebp. extra is extra win32
- external info that may be required.
-&function_begin_B(name,extra) Same as normal function_begin but no pushing.
-&function_end(name) Call at end of function.
-&function_end_A(name) Standard pop and ret, for use inside functions
-&function_end_B(name) Call at end but with pop or ret.
-&swtmp(num) Address on stack temp word.
-&wparam(num) Parameter number num, that was push
- in C convention. This all works over pushes
- and pops.
-&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
-
-int calc(int len, int *data)
- {
- int i,j=0;
-
- for (i=0; i<len; i++)
- {
- j+=other(data[i]);
- }
- }
-
-So a very simple version of this function could be coded as
-
- push(@INC,"perlasm","../../perlasm");
- require "x86asm.pl";
-
- &asm_init($ARGV[0]);
-
- &external_label("other");
-
- $tmp1= "eax";
- $j= "edi";
- $data= "esi";
- $i= "ebp";
-
- &comment("a simple function");
- &function_begin("calc");
- &mov( $data, &wparam(1)); # data
- &xor( $j, $j);
- &xor( $i, $i);
-
- &set_label("loop");
- &cmp( $i, &wparam(0));
- &jge( &label("end"));
-
- &mov( $tmp1, &DWP(0,$data,$i,4));
- &push( $tmp1);
- &call( "other");
- &add( $j, "eax");
- &pop( $tmp1);
- &inc( $i);
- &jmp( &label("loop"));
-
- &set_label("end");
- &mov( "eax", $j);
-
- &function_end("calc");
-
- &asm_finish();
-
-The above example is very very unoptimised but gives an idea of how
-things work.
-
-There is also a cbc mode function generator in cbc.pl
-
-&cbc( $name,
- $encrypt_function_name,
- $decrypt_function_name,
- $true_if_byte_swap_needed,
- $parameter_number_for_iv,
- $parameter_number_for_encrypt_flag,
- $first_parameter_to_pass,
- $second_parameter_to_pass,
- $third_parameter_to_pass);
-
-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);
-
-&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);
-
diff --git a/crypto/perlasm/README.md b/crypto/perlasm/README.md
new file mode 100644
index 0000000000..912dac7f07
--- /dev/null
+++ b/crypto/perlasm/README.md
@@ -0,0 +1,130 @@
+Perl scripts for assembler sources
+==================================
+
+The perl scripts in this directory are my 'hack' to generate
+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
+and then include it.
+
+ push(@INC,"perlasm","../../perlasm");
+ require "x86asm.pl";
+
+The first thing we do is setup the file and type of assembler
+
+ &asm_init($ARGV[0]);
+
+The first argument is the 'type'. Currently
+`cpp`, `sol`, `a.out`, `elf` or `win32`.
+The second argument is the file name.
+
+The reciprocal function is
+`&asm_finish()` which should be called at the end.
+
+There are two main 'packages'. `x86ms.pl`, which is the Microsoft assembler,
+and `x86unix.pl` which is the unix (gas) version.
+
+Functions of interest are:
+
+ &external_label("des_SPtrans"); declare and external variable
+ &LB(reg); Low byte for a register
+ &HB(reg); High byte for a register
+ &BP(off,base,index,scale) Byte pointer addressing
+ &DWP(off,base,index,scale) Word pointer addressing
+ &stack_push(num) Basically a 'sub esp, num*4' with extra
+ &stack_pop(num) inverse of stack_push
+ &function_begin(name,extra) Start a function with pushing of
+ edi, esi, ebx and ebp. extra is extra win32
+ external info that may be required.
+ &function_begin_B(name,extra) Same as normal function_begin but no
+ pushing.
+ &function_end(name) Call at end of function.
+ &function_end_A(name) Standard pop and ret, for use inside
+ functions.
+ &function_end_B(name) Call at end but with pop or ret.
+ &swtmp(num) Address on stack temp word.
+ &wparam(num) Parameter number num, that was push in
+ C convention. This all works over pushes
+ and pops.
+ &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
+
+ int calc(int len, int *data)
+ {
+ int i,j=0;
+
+ for (i=0; i<len; i++)
+ {
+ j+=other(data[i]);
+ }
+ }
+
+So a very simple version of this function could be coded as
+
+ push(@INC,"perlasm","../../perlasm");
+ require "x86asm.pl";
+
+ &asm_init($ARGV[0]);
+
+ &external_label("other");
+
+ $tmp1= "eax";
+ $j= "edi";
+ $data= "esi";
+ $i= "ebp";
+
+ &comment("a simple function");
+ &function_begin("calc");
+ &mov( $data, &wparam(1)); # data
+ &xor( $j, $j);
+ &xor( $i, $i);
+
+ &set_label("loop");
+ &cmp( $i, &wparam(0));
+ &jge( &label("end"));
+
+ &mov( $tmp1, &DWP(0,$data,$i,4));
+ &push( $tmp1);
+ &call( "other");
+ &add( $j, "eax");
+ &pop( $tmp1);
+ &inc( $i);
+ &jmp( &label("loop"));
+
+ &set_label("end");
+ &mov( "eax", $j);
+
+ &function_end("calc");
+
+ &asm_finish();
+
+The above example is very very unoptimised but gives an idea of how
+things work.
+
+There is also a cbc mode function generator in cbc.pl
+
+ &cbc($name,
+ $encrypt_function_name,
+ $decrypt_function_name,
+ $true_if_byte_swap_needed,
+ $parameter_number_for_iv,
+ $parameter_number_for_encrypt_flag,
+ $first_parameter_to_pass,
+ $second_parameter_to_pass,
+ $third_parameter_to_pass);
+
+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);
+
+ &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);
diff --git a/crypto/property/README b/crypto/property/README.md
similarity index 86%
rename from crypto/property/README
rename to crypto/property/README.md
index b3f56cfa2f..9d97a69873 100644
--- a/crypto/property/README
+++ b/crypto/property/README.md
@@ -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:
@@ -23,7 +27,6 @@ This implementation is based on a number of assumptions:
* Property queries can never add new property definitions.
-
Some consequences of these assumptions are:
* 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
global and requested property strings.
-
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
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
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
@@ -67,13 +71,15 @@ The implementation:
provided to convert from an index back to the original string (this can be
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
lists are sorted by the name index. Some additional utility functions
for dealing with property lists are also included: comparison of a 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.
The results are cached.
@@ -82,6 +88,7 @@ The implementation:
without bounds and must garbage collect under-used entries. The garbage
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
the same definition appears multiple times.
diff --git a/demos/README b/demos/README.txt
similarity index 100%
rename from demos/README
rename to demos/README.txt
diff --git a/demos/bio/README b/demos/bio/README.txt
similarity index 99%
rename from demos/bio/README
rename to demos/bio/README.txt
index a36bb48a5d..a8467cda64 100644
--- a/demos/bio/README
+++ b/demos/bio/README.txt
@@ -4,4 +4,3 @@ to simplify socket programming.
The client-conf, server-conf, client-arg and client-conf include examples
of how to use the SSL_CONF API for configuration file or command line
processing.
-
diff --git a/demos/certs/README b/demos/certs/README.txt
similarity index 99%
rename from demos/certs/README
rename to demos/certs/README.txt
index fde832eb2f..88cf56b1f8 100644
--- a/demos/certs/README
+++ b/demos/certs/README.txt
@@ -16,6 +16,3 @@ client certificates.
The script ocspquery.sh queries the status of the certificates using the
test responder.
-
-
-
diff --git a/dev/README b/dev/README.md
similarity index 100%
rename from dev/README
rename to dev/README.md
diff --git a/dev/release-aux/release-version-fn.sh b/dev/release-aux/release-version-fn.sh
index f0ac69fa6e..e9e1ac3850 100644
--- a/dev/release-aux/release-version-fn.sh
+++ b/dev/release-aux/release-version-fn.sh
@@ -36,7 +36,7 @@
# OpenSSL source directory as value.
get_version () {
- eval $(git cat-file blob HEAD:VERSION)
+ eval $(git cat-file blob HEAD:VERSION.dat)
VERSION="$MAJOR.$MINOR.$PATCH"
SERIES="$MAJOR.$MINOR"
TYPE=$( echo "$PRE_RELEASE_TAG" \
@@ -102,7 +102,7 @@ set_version () {
PRE_RELEASE_TAG="$PRE_LABEL$PRE_NUM"
;;
esac
- cat > "$SOURCEDIR/VERSION" <<EOF
+ cat > "$SOURCEDIR/VERSION.dat" <<EOF
MAJOR=$MAJOR
MINOR=$MINOR
PATCH=$PATCH
diff --git a/dev/release.sh b/dev/release.sh
index 7f7042fb18..770495fc93 100755
--- a/dev/release.sh
+++ b/dev/release.sh
@@ -681,7 +681,7 @@ B<release.sh> recognises both forms.
=head1 VERSION AND STATE
With OpenSSL 3.0, all the version and state information is in the file
-F<VERSION>, where the following variables are used and changed:
+F<VERSION.dat>, where the following variables are used and changed:
=over 4
diff --git a/doc/README b/doc/README.md
similarity index 58%
rename from doc/README
rename to doc/README.md
index 964d879810..12bb37ddb8 100644
--- a/doc/README
+++ b/doc/README.md
@@ -1,27 +1,30 @@
+OpenSSL Documentation
+=====================
-README This file
+README.md This file
-fingerprints.txt
+[fingerprints.txt](fingerprints.txt)
PGP fingerprints of authorised release signers
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
-man1/
+[man1/](man1/)
The openssl command-line tools; start with openssl.pod
-man3/
+[man3/](man3/)
The SSL library and the crypto library
-man5/
+[man5/](man5/)
File formats
-man7/
+[man7/](man7/)
Overviews; start with crypto.pod and ssl.pod, for example
Algorithm specific EVP_PKEY documentation.
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>
diff --git a/ssl/record/README b/ssl/record/README.md
similarity index 56%
rename from ssl/record/README
rename to ssl/record/README.md
index 630fe8027a..263f257c84 100644
--- a/ssl/record/README
+++ b/ssl/record/README.md
@@ -18,10 +18,10 @@ of libssl.
The source files map to components as follows:
-dtls1_bitmap.c -> DTLS1_BITMAP component
-ssl3_buffer.c -> SSL3_BUFFER component
-ssl3_record.c -> SSL3_RECORD component
-rec_layer_s3.c, rec_layer_d1.c -> RECORD_LAYER component
+ dtls1_bitmap.c -> DTLS1_BITMAP component
+ ssl3_buffer.c -> SSL3_BUFFER component
+ ssl3_record.c -> SSL3_RECORD 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
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:
- libssl
- |
----------------------------|-----record.h--------------------------------------
- |
- _______V______________
- | |
- | RECORD_LAYER |
- | |
- | rec_layer_s3.c |
- | ^ |
- | _________|__________ |
- || ||
- || DTLS1_RECORD_LAYER ||
- || ||
- || rec_layer_d1.c ||
- ||____________________||
- |______________________|
- record_local.h ^ ^ ^
- _________________| | |_________________
- | | |
- _____V_________ ______V________ _______V________
- | | | | | |
- | SSL3_BUFFER | | SSL3_RECORD | | DTLS1_BITMAP |
- | |--->| | | |
- | ssl3_buffer.c | | ssl3_record.c | | dtls1_bitmap.c |
- |_______________| |_______________| |________________|
-
+ libssl
+ |
+ -------------------------|-----record.h------------------------------------
+ |
+ _______V______________
+ | |
+ | RECORD_LAYER |
+ | |
+ | rec_layer_s3.c |
+ | ^ |
+ | _________|__________ |
+ || ||
+ || DTLS1_RECORD_LAYER ||
+ || ||
+ || rec_layer_d1.c ||
+ ||____________________||
+ |______________________|
+ record_local.h ^ ^ ^
+ _________________| | |_________________
+ | | |
+ _____V_________ ______V________ _______V________
+ | | | | | |
+ | SSL3_BUFFER | | SSL3_RECORD | | DTLS1_BITMAP |
+ | |--->| | | |
+ | ssl3_buffer.c | | ssl3_record.c | | dtls1_bitmap.c |
+ |_______________| |_______________| |________________|
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
diff --git a/ssl/statem/README b/ssl/statem/README
deleted file mode 100644
index 86cc066372..0000000000
--- a/ssl/statem/README
+++ /dev/null
@@ -1,63 +0,0 @@
-State Machine Design
-====================
-
-This file provides some guidance on the thinking behind the design of the
-state machine code to aid future maintenance.
-
-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:
- - Remove duplication of state code between client and server
- - Remove duplication of state code between TLS and DTLS
- - Simplify transitions and bring the logic together in a single location
- so that it is easier to validate
- - Remove duplication of code between each of the message handling functions
- - Receive a message first and then work out whether that is a valid
- transition - not the other way around (the other way causes lots of issues
- where we are expecting one type of message next but actually get something
- else)
- - Separate message flow state from handshake state (in order to better
- understand each)
- - message flow state = when to flush buffers; handling restarts in the
- event of NBIO events; handling the common flow of steps for reading a
- message and the common flow of steps for writing a message etc
- - handshake state = what handshake message are we working on now
- - 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
-writing sub-state machine. See the source comments in statem.c for a more
-detailed description of the various states and transitions possible.
-
-Conceptually the state machine component is designed as follows:
-
- libssl
- |
----------------------------|-----statem.h--------------------------------------
- |
- _______V____________________
- | |
- | statem.c |
- | |
- | Core state machine code |
- |____________________________|
- statem_local.h ^ ^
- _________| |_______
- | |
- _____________|____________ _____________|____________
- | | | |
- | statem_clnt.c | | statem_srvr.c |
- | | | |
- | TLS/DTLS client specific | | TLS/DTLS server specific |
- | state machine code | | state machine code |
- |__________________________| |__________________________|
- | |_______________|__ |
- | ________________| | |
- | | | |
- ____________V_______V________ ________V______V_______________
- | | | |
- | statem_both.c | | statem_dtls.c |
- | | | |
- | Non core functions common | | Non core functions common to |
- | to both servers and clients | | both DTLS servers and clients |
- |_____________________________| |_______________________________|
-
diff --git a/ssl/statem/README.md b/ssl/statem/README.md
new file mode 100644
index 0000000000..ef33f77c82
--- /dev/null
+++ b/ssl/statem/README.md
@@ -0,0 +1,63 @@
+State Machine Design
+====================
+
+This file provides some guidance on the thinking behind the design of the
+state machine code to aid future maintenance.
+
+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:
+
+ - Remove duplication of state code between client and server
+ - Remove duplication of state code between TLS and DTLS
+ - Simplify transitions and bring the logic together in a single location
+ so that it is easier to validate
+ - Remove duplication of code between each of the message handling functions
+ - Receive a message first and then work out whether that is a valid
+ transition - not the other way around (the other way causes lots of issues
+ where we are expecting one type of message next but actually get something
+ else)
+ - Separate message flow state from handshake state (in order to better
+ understand each)
+ * message flow state = when to flush buffers; handling restarts in the
+ event of NBIO events; handling the common flow of steps for reading a
+ message and the common flow of steps for writing a message etc
+ * handshake state = what handshake message are we working on now
+ - 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
+writing sub-state machine. See the source comments in statem.c for a more
+detailed description of the various states and transitions possible.
+
+Conceptually the state machine component is designed as follows:
+
+ libssl
+ |
+ -------------------------|-----statem.h------------------------------------
+ |
+ _______V____________________
+ | |
+ | statem.c |
+ | |
+ | Core state machine code |
+ |____________________________|
+ statem_local.h ^ ^
+ _________| |_______
+ | |
+ _____________|____________ _____________|____________
+ | | | |
+ | statem_clnt.c | | statem_srvr.c |
+ | | | |
+ | TLS/DTLS client specific | | TLS/DTLS server specific |
+ | state machine code | | state machine code |
+ |__________________________| |__________________________|
+ | |_______________|__ |
+ | ________________| | |
+ | | | |
+ ____________V_______V________ ________V______V_______________
+ | | | |
+ | statem_both.c | | statem_dtls.c |
+ | | | |
+ | Non core functions common | | Non core functions common to |
+ | to both servers and clients | | both DTLS servers and clients |
+ |_____________________________| |_______________________________|
diff --git a/test/README b/test/README-dev.md
similarity index 52%
rename from test/README
rename to test/README-dev.md
index 9094d9a38d..56114fdc34 100644
--- a/test/README
+++ b/test/README-dev.md
@@ -1,44 +1,46 @@
+Guidelines for test developers
+==============================
+
How to add recipes
-==================
+------------------
For any test that you want to perform, you write a script located in
-test/recipes/, named {nn}-test_{name}.t, where {nn} is a two digit number and
-{name} is a unique name of your choice.
+`test/recipes/`, named `{nn}-test_{name}.t`,
+where `{nn}` is a two digit number and
+`{name}` is a unique name of your choice.
Please note that if a test involves a new testing executable, you will need to
-do some additions in test/build.info. Please refer to the section "Changes to
-test/build.info" below.
-
+do some additions in test/build.info. Please refer to the section
+["Changes to test/build.info"](README.md#changes-to-testbuildinfo) below.
Naming conventions
-=================
-
-A test executable is named test/{name}test.c
-
-A test recipe is named test/recipes/{nn}-test_{name}.t, where {nn} is a two
-digit number and {name} is a unique name of your choice.
-
-The number {nn} is (somewhat loosely) grouped as follows:
-
-00-04 sanity, internal and essential API tests
-05-09 individual symmetric cipher algorithms
-10-14 math (bignum)
-15-19 individual asymmetric cipher algorithms
-20-24 openssl commands (some otherwise not tested)
-25-29 certificate forms, generation and verification
-30-35 engine and evp
-60-79 APIs:
- 60 X509 subsystem
- 61 BIO subsystem
- 65 CMP subsystem
- 70 PACKET layer
-80-89 "larger" protocols (CA, CMS, OCSP, SSL, TSA)
-90-98 misc
-99 most time consuming tests [such as test_fuzz]
-
+------------------
+
+A test executable is named `test/{name}test.c`
+
+A test recipe is named `test/recipes/{nn}-test_{name}.t`, where `{nn}` is a two
+digit number and `{name}` is a unique name of your choice.
+
+The number `{nn}` is (somewhat loosely) grouped as follows:
+
+ 00-04 sanity, internal and essential API tests
+ 05-09 individual symmetric cipher algorithms
+ 10-14 math (bignum)
+ 15-19 individual asymmetric cipher algorithms
+ 20-24 openssl commands (some otherwise not tested)
+ 25-29 certificate forms, generation and verification
+ 30-35 engine and evp
+ 60-79 APIs:
+ 60 X509 subsystem
+ 61 BIO subsystem
+ 65 CMP subsystem
+ 70 PACKET layer
+ 80-89 "larger" protocols (CA, CMS, OCSP, SSL, TSA)
+ 90-98 misc
+ 99 most time consuming tests [such as test_fuzz]
A recipe that just runs a test executable
-=========================================
+-----------------------------------------
A script that just runs a program looks like this:
@@ -48,21 +50,20 @@ A script that just runs a program looks like this:
simple_test("test_{name}", "{name}test", "{name}");
-{name} is the unique name you have chosen for your test.
-
-The second argument to `simple_test' is the test executable, and `simple_test'
-expects it to be located in test/
+`{name}` is the unique name you have chosen for your test.
-For documentation on OpenSSL::Test::Simple, do
-`perldoc util/perl/OpenSSL/Test/Simple.pm'.
+The second argument to `simple_test` is the test executable, and `simple_test`
+expects it to be located in `test/`
+For documentation on `OpenSSL::Test::Simple`,
+do `perldoc util/perl/OpenSSL/Test/Simple.pm`.
A recipe that runs a more complex test
-======================================
+--------------------------------------
For more complex tests, you will need to read up on Test::More and
-OpenSSL::Test. Test::More is normally preinstalled, do `man Test::More' for
-documentation. For OpenSSL::Test, do `perldoc util/perl/OpenSSL/Test.pm'.
+OpenSSL::Test. Test::More is normally preinstalled, do `man Test::More` for
+documentation. For OpenSSL::Test, do `perldoc util/perl/OpenSSL/Test.pm`.
A script to start from could be this:
@@ -89,26 +90,25 @@ A script to start from could be this:
# test feature 2
}
-
Changes to test/build.info
-==========================
+--------------------------
Whenever a new test involves a new test executable you need to do the
following (at all times, replace {NAME} and {name} with the name of your
test):
-* add {name} to the list of programs under PROGRAMS_NO_INST
+ * add `{name}` to the list of programs under `PROGRAMS_NO_INST`
-* create a three line description of how to build the test, you will have
-to modify the include paths and source files if you don't want to use the
-basic test framework:
+ * create a three line description of how to build the test, you will have
+ to modify the include paths and source files if you don't want to use the
+ basic test framework:
- SOURCE[{name}]={name}.c
- INCLUDE[{name}]=.. ../include ../apps/include
- DEPEND[{name}]=../libcrypto libtestutil.a
+ SOURCE[{name}]={name}.c
+ INCLUDE[{name}]=.. ../include ../apps/include
+ DEPEND[{name}]=../libcrypto libtestutil.a
Generic form of C test executables
-==================================
+----------------------------------
#include "testutil.h"
@@ -133,12 +133,12 @@ Generic form of C test executables
return 1; /* Indicate success */
}
-You should use the TEST_xxx macros provided by testutil.h to test all failure
+You should use the `TEST_xxx` macros provided by `testutil.h` to test all failure
conditions. These macros produce an error message in a standard format if the
condition is not met (and nothing if the condition is met). Additional
-information can be presented with the TEST_info macro that takes a printf
-format string and arguments. TEST_error is useful for complicated conditions,
-it also takes a printf format string and argument. In all cases the TEST_xxx
+information can be presented with the `TEST_info` macro that takes a `printf`
+format string and arguments. `TEST_error` is useful for complicated conditions,
+it also takes a `printf` format string and argument. In all cases the `TEST_xxx`
macros are guaranteed to evaluate their arguments exactly once. This means
that expressions with side effects are allowed as parameters. Thus,
@@ -152,6 +152,5 @@ works fine and can be used in place of:
The former produces a more meaningful message on failure than the latter.
Note that the test infrastructure automatically sets up all required environment
-variables (such as OPENSSL_MODULES, OPENSSL_CONF etc) for the tests. Individual
-tests may choose to override the default settings as required.
-
+variables (such as `OPENSSL_MODULES`, `OPENSSL_CONF`, etc.) for the tests.
+Individual tests may choose to override the default settings as required.
diff --git a/test/README.external b/test/README-external.md
similarity index 73%
copy from test/README.external
copy to test/README-external.md
index 8069ce8d00..b06deaac4f 100644
--- a/test/README.external
+++ b/test/README-external.md
@@ -1,12 +1,10 @@
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
platforms.
-
-
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:
- $ 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
BoringSSL repository. Later commits may or may not pass the test suite:
- $ cd boringssl
- $ git checkout 490469f850e
+ $ cd boringssl
+ $ git checkout 490469f850e
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:
-$ cd ../openssl
-$ ./config enable-ssl3 enable-ssl3-method enable-weak-ssl-ciphers \
- enable-external-tests
+ $ cd ../openssl
+ $ ./config enable-ssl3 enable-ssl3-method enable-weak-ssl-ciphers \
+ enable-external-tests
Note that using other config options than those given above may cause the tests
to fail.
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
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
verbose option:
-$ VERBOSE=1 BORING_RUNNER_DIR=/path/to/boringssl/ssl/test/runner make \
- TESTS="test_external_boringssl" test
-
+ $ VERBOSE=1 BORING_RUNNER_DIR=/path/to/boringssl/ssl/test/runner make \
+ TESTS="test_external_boringssl" test
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
suppressions that are currently present.
-
Python PYCA/Cryptography test suite
===================================
This python test suite runs cryptographic tests with a local OpenSSL build as
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:
-$ ./config shared enable-external-tests
-$ make
+ $ ./config shared enable-external-tests
+ $ make
The tests will run in a python virtual environment which requires virtualenv
to be installed.
-$ make test VERBOSE=1 TESTS=test_external_pyca
+ $ make test VERBOSE=1 TESTS=test_external_pyca
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
other crypto implementations so are not relevant. Currently no tests fail.
-
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:
-$ 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-1.15.1-final if you want to be sure.
-$ cd krb5
-$ git checkout krb5-1.15.1-final
-$ cd ..
+ $ cd krb5
+ $ git checkout krb5-1.15.1-final
+ $ cd ..
OpenSSL must be built with external tests enabled:
-$ ./config enable-external-tests
-$ make
+ $ ./config enable-external-tests
+ $ make
krb5's tests will then be run as part of the rest of the suite, or can be
explicitly run (with more debugging):
-$ VERBOSE=1 make TESTS=test_external_krb5 test
+ $ VERBOSE=1 make TESTS=test_external_krb5 test
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
tests are expected to fail.
-
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:
-$ git submodule update --init
+ $ git submodule update --init
Then configure/build OpenSSL enabling external tests:
-$ ./config shared enable-external-tests
-$ make
+ $ ./config shared enable-external-tests
+ $ make
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
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
====================
@@ -163,24 +157,23 @@ To update the commit for any of the above test suites:
- 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):
- $ cd <submodule-dir>
- $ git pull origin master
+ $ cd `<submodule-dir>`
+ $ git pull origin master
- Go to root directory, there should be a new git status:
- $ cd ../
- $ git status
- ...
- # modified: <submodule-dir> (new commits)
- ...
+ $ cd ../
+ $ git status
+ ...
+ # modified: `<submodule-dir>` (new commits)
+ ...
- Add/commit/push the update
- git add <submodule-dir>
- git commit -m "Updated <submodule> to latest commit"
- git push
-
+ $ git add `<submodule-dir>`
+ $ git commit -m `"Updated <submodule> to latest commit"`
+ $ git push
diff --git a/test/README.md b/test/README.md
index a9e0c827d1..f9058a0026 100644
--- a/test/README.md
+++ b/test/README.md
@@ -1,5 +1,5 @@
-Test OpenSSL
-============
+Using OpenSSL Tests
+===================
After a successful build, and before installing, the libraries should be tested.
Run:
diff --git a/test/data.txt b/test/data.txt
new file mode 100644
index 0000000000..3442255280
--- /dev/null
+++ b/test/data.txt
@@ -0,0 +1,4 @@
+TEST DATA
+
+Please note that if a test involves a new testing executable,
+you will need to do some additions in test/build.info.
diff --git a/test/README.external b/test/data2.txt
similarity index 99%
rename from test/README.external
rename to test/data2.txt
index 8069ce8d00..c4f9691a26 100644
--- a/test/README.external
+++ b/test/data2.txt
@@ -1,3 +1,5 @@
+TEST DATA2
+
Running external test suites with OpenSSL
=========================================
diff --git a/test/recipes/04-test_pem_data/NOTES b/test/recipes/04-test_pem_data/NOTES.txt
similarity index 100%
rename from test/recipes/04-test_pem_data/NOTES
rename to test/recipes/04-test_pem_data/NOTES.txt
diff --git a/test/recipes/20-test_dgst.t b/test/recipes/20-test_dgst.t
index c10da5a9f4..0b7ab2d5d1 100644
--- a/test/recipes/20-test_dgst.t
+++ b/test/recipes/20-test_dgst.t
@@ -24,8 +24,8 @@ sub tsignverify {
my $privkey = shift;
my $pubkey = shift;
- my $data_to_sign = srctop_file('test', 'README');
- my $other_data = srctop_file('test', 'README.external');
+ my $data_to_sign = srctop_file('test', 'data.txt');
+ my $other_data = srctop_file('test', 'data2.txt');
my $sigfile = basename($privkey, '.pem') . '.sig';
plan tests => 4;
diff --git a/test/recipes/20-test_pkeyutl.t b/test/recipes/20-test_pkeyutl.t
index 753995428d..543038cab9 100644
--- a/test/recipes/20-test_pkeyutl.t
+++ b/test/recipes/20-test_pkeyutl.t
@@ -74,8 +74,8 @@ sub tsignverify {
my $pubkey = shift;
my @extraopts = @_;
- my $data_to_sign = srctop_file('test', 'README');
- my $other_data = srctop_file('test', 'README.external');
+ my $data_to_sign = srctop_file('test', 'data.txt');
+ my $other_data = srctop_file('test', 'data2.txt');
my $sigfile = basename($privkey, '.pem') . '.sig';
my @args = ();
diff --git a/test/recipes/95-test_external_krb5.t b/test/recipes/95-test_external_krb5.t
index c431d966b3..ad262da2d9 100644
--- a/test/recipes/95-test_external_krb5.t
+++ b/test/recipes/95-test_external_krb5.t
@@ -17,7 +17,7 @@ setup("test_external_krb5");
plan skip_all => "No external tests in this configuration"
if disabled("external-tests");
plan skip_all => "krb5 not available"
- if ! -f srctop_file("krb5", "README");
+ if ! -f srctop_file("krb5", "data.txt");
plan tests => 1;
diff --git a/util/markdownlint.rb b/util/markdownlint.rb
index 66517484ad..64a82e3684 100644
--- a/util/markdownlint.rb
+++ b/util/markdownlint.rb
@@ -15,6 +15,8 @@ exclude_rule 'MD004' # Unordered list style TODO(fix?)
exclude_rule 'MD005' # Inconsistent indentation for list items at the same level
exclude_rule 'MD006' # Consider starting bulleted lists at the beginning of the line
exclude_rule 'MD014' # Dollar signs used before commands without showing output
+exclude_rule 'MD023' # Headers must start at the beginning of the line
exclude_rule 'MD024' # Multiple headers with the same content
exclude_rule 'MD025' # Multiple top level headers in the same document
+exclude_rule 'MD026' # Trailing punctuation in header
exclude_rule 'MD029' # Ordered list item prefix
More information about the openssl-commits
mailing list