From 036cbb6bbf30955abdcffaf6e52cd926d8d8ee75 Mon Sep 17 00:00:00 2001 From: "Dr. David von Oheimb" Date: Wed, 10 Jun 2020 14:15:28 +0200 Subject: [PATCH] Rename NOTES*, README*, VERSION, HACKING, LICENSE to .md or .txt Reviewed-by: Tim Hudson (Merged from https://github.com/openssl/openssl/pull/12109) --- CHANGES.md | 28 ++- CONTRIBUTING.md | 2 +- Configurations/15-android.conf | 2 +- .../{README.design => README-design.md} | 0 Configurations/{README => README.md} | 0 Configure | 6 +- HACKING => HACKING.md | 0 INSTALL.md | 34 ++-- LICENSE => LICENSE.txt | 0 NEWS.md | 2 +- NOTES.ANDROID => NOTES-Android.md | 0 NOTES.DJGPP => NOTES-DJGPP.md | 0 NOTES.PERL => NOTES-Perl.md | 0 NOTES.UNIX => NOTES-Unix.md | 0 NOTES.VMS => NOTES-VMS.md | 0 NOTES.VALGRIND => NOTES-Valgrind.md | 0 NOTES.WIN => NOTES-Windows.txt | 0 README.ENGINE => README-Engine.md | 0 README.FIPS => README-FIPS.md | 0 README.md | 2 +- VERSION => VERSION.dat | 0 VERSION.txt | 7 + config.com | 2 +- ...ME.sparse_array => README-sparse_array.md} | 0 crypto/engine/{README => README.md} | 0 crypto/err/{README => README.md} | 0 crypto/objects/{README => README.md} | 0 crypto/perlasm/{README => README.md} | 0 crypto/property/{README => README.md} | 0 demos/{README => README.txt} | 2 +- 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} | 2 +- ssl/record/{README => README.md} | 0 ssl/statem/{README => README.md} | 0 test/{README => README-dev.md} | 107 +++++----- test/{README.external => README-external.md} | 0 test/README.md | 4 +- test/data.txt | 4 + test/data2.txt | 188 ++++++++++++++++++ .../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 +- 47 files changed, 309 insertions(+), 103 deletions(-) rename Configurations/{README.design => README-design.md} (100%) rename Configurations/{README => README.md} (100%) rename HACKING => HACKING.md (100%) rename LICENSE => LICENSE.txt (100%) rename NOTES.ANDROID => NOTES-Android.md (100%) rename NOTES.DJGPP => NOTES-DJGPP.md (100%) rename NOTES.PERL => NOTES-Perl.md (100%) rename NOTES.UNIX => NOTES-Unix.md (100%) rename NOTES.VMS => NOTES-VMS.md (100%) rename NOTES.VALGRIND => NOTES-Valgrind.md (100%) rename NOTES.WIN => NOTES-Windows.txt (100%) rename README.ENGINE => README-Engine.md (100%) rename README.FIPS => README-FIPS.md (100%) rename VERSION => VERSION.dat (100%) create mode 100644 VERSION.txt rename crypto/{README.sparse_array => README-sparse_array.md} (100%) rename crypto/engine/{README => README.md} (100%) rename crypto/err/{README => README.md} (100%) rename crypto/objects/{README => README.md} (100%) rename crypto/perlasm/{README => README.md} (100%) rename crypto/property/{README => README.md} (100%) rename demos/{README => README.txt} (92%) 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} (96%) rename ssl/record/{README => README.md} (100%) rename ssl/statem/{README => README.md} (100%) rename test/{README => README-dev.md} (52%) rename test/{README.external => README-external.md} (100%) create mode 100644 test/data.txt create mode 100644 test/data2.txt rename test/recipes/04-test_pem_data/{NOTES => NOTES.txt} (100%) diff --git a/CHANGES.md b/CHANGES.md index 585a451d18..c0140a35bb 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -173,7 +173,13 @@ OpenSSL 3.0 *Richard Levitte* - * The main project documents (README, NEWS, CHANGES, INSTALL, SUPPORT) + * Project text documents not yet having a proper file name extension + (HACKING, LICENSE, NOTES*, README*, VERSION) have been renamed to *.md + as far as reasonable, else to *.txt, for better use with file managers. + + *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 remain well readable inside a plain text editor. @@ -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* @@ -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). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 23756a5d4a..96290fffca 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 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 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 100% rename from Configurations/README.design rename to Configurations/README-design.md diff --git a/Configurations/README b/Configurations/README.md similarity index 100% rename from Configurations/README rename to Configurations/README.md diff --git a/Configure b/Configure index b8dfeec477..df42603855 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} diff --git a/HACKING b/HACKING.md similarity index 100% rename from HACKING rename to HACKING.md diff --git a/INSTALL.md b/INSTALL.md index 5686415ad8..dfa1276378 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -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. @@ -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 100% rename from NOTES.ANDROID rename to NOTES-Android.md diff --git a/NOTES.DJGPP b/NOTES-DJGPP.md similarity index 100% rename from NOTES.DJGPP rename to NOTES-DJGPP.md diff --git a/NOTES.PERL b/NOTES-Perl.md similarity index 100% rename from NOTES.PERL rename to NOTES-Perl.md diff --git a/NOTES.UNIX b/NOTES-Unix.md similarity index 100% rename from NOTES.UNIX rename to NOTES-Unix.md diff --git a/NOTES.VMS b/NOTES-VMS.md similarity index 100% rename from NOTES.VMS rename to NOTES-VMS.md diff --git a/NOTES.VALGRIND b/NOTES-Valgrind.md similarity index 100% rename from NOTES.VALGRIND rename to NOTES-Valgrind.md 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 b/README-Engine.md similarity index 100% rename from README.ENGINE rename to README-Engine.md diff --git a/README.FIPS b/README-FIPS.md similarity index 100% rename from README.FIPS rename to README-FIPS.md diff --git a/README.md b/README.md index e566d3161c..a0ea69074a 100644 --- a/README.md +++ b/README.md @@ -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/VERSION.txt b/VERSION.txt new file mode 100644 index 0000000000..48c68bdd04 --- /dev/null +++ b/VERSION.txt @@ -0,0 +1,7 @@ +MAJOR=3 +MINOR=0 +PATCH=0 +PRE_RELEASE_TAG=alpha4-dev +BUILD_METADATA= +RELEASE_DATE="" +SHLIB_VERSION=3 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 100% rename from crypto/README.sparse_array rename to crypto/README-sparse_array.md diff --git a/crypto/engine/README b/crypto/engine/README.md similarity index 100% rename from crypto/engine/README rename to crypto/engine/README.md diff --git a/crypto/err/README b/crypto/err/README.md similarity index 100% rename from crypto/err/README rename to crypto/err/README.md diff --git a/crypto/objects/README b/crypto/objects/README.md similarity index 100% rename from crypto/objects/README rename to crypto/objects/README.md diff --git a/crypto/perlasm/README b/crypto/perlasm/README.md similarity index 100% rename from crypto/perlasm/README rename to crypto/perlasm/README.md diff --git a/crypto/property/README b/crypto/property/README.md similarity index 100% rename from crypto/property/README rename to crypto/property/README.md diff --git a/demos/README b/demos/README.txt similarity index 92% rename from demos/README rename to demos/README.txt index d2155ef973..ef48bf580f 100644 --- a/demos/README +++ b/demos/README.txt @@ -1,7 +1,7 @@ NOTE: Don't expect any of these programs to work with current OpenSSL releases, or even with later SSLeay releases. -Original README: +Original README.md: ============================================================================= Some demo programs sent to me by various people 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" < "$SOURCEDIR/VERSION.dat" < recognises both forms. =head1 VERSION AND STATE With OpenSSL 3.0, all the version and state information is in the file -F, where the following variables are used and changed: +F, where the following variables are used and changed: =over 4 diff --git a/doc/README b/doc/README.md similarity index 96% rename from doc/README rename to doc/README.md index 964d879810..f6110ff488 100644 --- a/doc/README +++ b/doc/README.md @@ -1,5 +1,5 @@ -README This file +README.md This file fingerprints.txt PGP fingerprints of authorised release signers diff --git a/ssl/record/README b/ssl/record/README.md similarity index 100% rename from ssl/record/README rename to ssl/record/README.md diff --git a/ssl/statem/README b/ssl/statem/README.md similarity index 100% rename from ssl/statem/README rename to ssl/statem/README.md 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 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. +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] +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. +`{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/ - -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 100% rename from test/README.external rename to test/README-external.md 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/data2.txt b/test/data2.txt new file mode 100644 index 0000000000..c4f9691a26 --- /dev/null +++ b/test/data2.txt @@ -0,0 +1,188 @@ +TEST DATA2 + +Running external test suites with OpenSSL +========================================= + +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 +======================== + +In order to run the BoringSSL tests with OpenSSL, first checkout the BoringSSL +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 + + 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 + +2) Using the already configured submodule settings in OpenSSL: + + $ 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 + +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=/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. + +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 + + +Test failures and suppressions +------------------------------ + +A large number of the BoringSSL tests are known to fail. A test could fail +because of many possible reasons. For example: + +- A bug in OpenSSL +- Different interpretations of standards +- Assumptions about the way BoringSSL works that do not apply to OpenSSL +- The test uses APIs added to BoringSSL that are not present in OpenSSL +- etc + +In order to provide a "clean" baseline run with all the tests passing a config +file has been provided that suppresses the running of tests that are known to +fail. These suppressions are held in the file "test/ossl_shim/ossl_config.json" +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: + +$ git submodule update --init + +Then configure/build OpenSSL compatible with the python module: + +$ ./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 + +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 +=============== + +Much like the PYCA/Cryptography test suite, this builds and runs the krb5 +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 + +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 .. + +OpenSSL must be built with external tests enabled: + +$ ./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 + +Test-failures suppressions +-------------------------- + +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 +=============== + +Much like the PYCA/Cryptography test suite, this builds and runs the GOST engine +tests against the local OpenSSL build. + +You will need a git checkout of gost-engine at the top level: + +$ git submodule update --init + +Then configure/build OpenSSL enabling external tests: + +$ ./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 + +Updating test suites +==================== + +To update the commit for any of the above test suites: + +- Make sure the submodules are cloned locally: + + $ git submodule update --init --recursive + +- Enter subdirectory and pull from the repository (use a specific branch/tag if required): + + $ cd + $ git pull origin master + +- Go to root directory, there should be a new git status: + + $ cd ../ + $ git status + ... + # modified: (new commits) + ... + +- Add/commit/push the update + + git add + git commit -m "Updated to latest commit" + git push + 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;