diff --git a/scripts/config_check/Disabled-Features.txt b/scripts/config_check/Disabled-Features.txt new file mode 100644 index 0000000000..f4ef0f6d9f --- /dev/null +++ b/scripts/config_check/Disabled-Features.txt @@ -0,0 +1 @@ +After running the refresh.sh command, this file will contain a list of disabled wolfSSL features. diff --git a/scripts/config_check/Enabled-Features.txt b/scripts/config_check/Enabled-Features.txt new file mode 100644 index 0000000000..290acf691e --- /dev/null +++ b/scripts/config_check/Enabled-Features.txt @@ -0,0 +1 @@ +After running the refresh.sh command, this file will contain a list of enabled wolfSSL features. diff --git a/scripts/config_check/README.md b/scripts/config_check/README.md new file mode 100644 index 0000000000..351b902a78 --- /dev/null +++ b/scripts/config_check/README.md @@ -0,0 +1,122 @@ +# wolfSSL Configuration Assistance + +This directory contains an utility script called [refresh.sh](./refresh.sh) that reads a bash-like command in [cmd.txt](./cmd.txt) +and runs it. + +The command expected is the wolfSSL `./configure` that expects a potentially _large_ number of parameters. (see `./configure --help` +and the [build documentation](https://www.wolfssl.com/documentation/manuals/wolfssl/chapter02.html)). + +Unlike normal bash commands spanning multiple lines, comments are allowed. Use the same `#` on a line for everything afterwards to be ignored. + +Line continuation characters `\` are ignored in the command [cmd.txt](./cmd.txt) file. + +Blank lines will be ignored and do not need line continuation characters in the command [cmd.txt](./cmd.txt) file. + +Embedded comments with the `#` character are supported and can be used for your own personal comments +regarding each of the options enabled or disabled. + +The multi-line `./configure` command with all parameters on subsequent lines is stripped of comments and everything placed on a single line statement when executed. + +Upon execution, the entire output is set to a file called [output.txt](./output.txt). Additionally, the enabled/disabled features (those items with an asterisk in the output and the word "yes" or "no") +are separated and stored in the respective [Enabled-Features.txt](./Enabled-Features.txt) and [Disabled-Features.txt](./Disabled-Features.txt) files. + +## Purpose + +This script may help in a variety of ways: + +- Observe which options have side-effects that may enable other options. +- Determine which `--option-setting` causes a specific `#define` to be enabled (helpful for embedded developers). +- Record specific project settings of enabled and disabled features. + +## Installation + +There's no need to install this script, as it can be run from the wolfSSL `./scripts/config_check` directory as noted in the Usage section, below. + +If you'd like to run from a someplace else, place the [refresh.sh](./refresh.sh) and [cmd.txt](./cmd.txt) files in a directory and +edit the respective `refresh.sh` file. The first `cd "../.."` command will need to be edited to change to your wolfssl directory +to run the `./configure` command. See the [Configuration](https://github.com/gojimmypi/wolfssl/tree/ConfigCheck/scripts/config_check#configuration) section, below. + +It may be convenient for the command and output files to be in a included in GitHub fork repo for +easily tracking changes to the output files, typically your project that is using wolfSSL. + +## Configuration + +See the variables in the [refresh.sh](./refresh.sh) script: + +Note in particular the environment variables: + +``` +WOLFSSL_REPO="$PWD" +WOLFSSL_FILE_ROOT="$WOLFSSL_REPO/scripts/config_check" +``` +If you'd like to save the results someplace else, the file output locations are set like this: + +``` +WOLFSSL_OUTPUT="$WOLFSSL_FILE_ROOT/output.txt" +WOLFSSL_OPTIONS="$WOLFSSL_FILE_ROOT/options.h" +WOLFSSL_YES="$WOLFSSL_FILE_ROOT/Enabled-Features.txt" +WOLFSSL_NO="$WOLFSSL_FILE_ROOT/Disabled-Features.txt" +``` + +Edit those locations to suit your needs. See below for more details: + +#### `WOLFSSL_REPO` + +This is the location of wolfSSL where the `./configure` script should run and is typically the location of your wolfSSL `git clone`. +For example in WSL for a clone command from the `C:\workspace` directory, this value would be: + +`WOLFSSL_REPO="/mnt/c/workspace/wolfssl"` + +#### `WOLFSSL_FILE_ROOT` + +The directory where `./configure` console output will be saved in various files (a github repo is helpful for tracking changes). +For example, you could choose to redirect to a different location: + +`WOLFSSL_FILE_ROOT="~/myproject/_debug"` + + +#### `WOLFSSL_CMD_FILE` + +This is the `./configure` command to edit. This is typically the location of the [cmd.txt](./cmd.txt) file +located in the same `WOLFSSL_FILE_ROOT` directory. + +`WOLFSSL_CMD_FILE="$WOLFSSL_FILE_ROOT/cmd.txt"` + + +#### Output files + +The output files currently all go to the `$WOLFSSL_FILE_ROOT` but can be adjusted as needed: + +``` +WOLFSSL_OUTPUT="$WOLFSSL_FILE_ROOT/output.txt" +WOLFSSL_OPTIONS="$WOLFSSL_FILE_ROOT/options.h" +WOLFSSL_YES="$WOLFSSL_FILE_ROOT/Enabled-Features.txt" +WOLFSSL_NO="$WOLFSSL_FILE_ROOT/Disabled-Features.txt" +``` + +These files are all included in the GitHub `.ignore` file in the root of the repository. +Edit that file or redirect the output to a different location if you'd like to track changes. + +Note that a fresh `help.txt` file will be generated each time this script runs. +If you are tracking this in your own repo, you can readily see what new features may have been +added since last used. + +## Usage + +Run the `./refresh.sh` command from the `wolfssl/scripts/config_check` directory: + +``` +cd wolfssl/scripts/config_check +./refresh.sh +``` + +Observe the generated output text files and `options.h`. + + + +## Other Resources + +- [Building wolfSSL](https://www.wolfssl.com/documentation/manuals/wolfssl/chapter02.html) +- Kaleb's [wolfSoFT - wolf Suite of Frameworks and Tools](https://github.com/kaleb-himes/wolfSoFT) + +* Note Kaleb is working on a "user settings to configure file" feature to create a wolfSSL `.configure` command with the parameters used to create the provided header file. \ No newline at end of file diff --git a/scripts/config_check/cmd.txt b/scripts/config_check/cmd.txt new file mode 100644 index 0000000000..cb6ba94578 --- /dev/null +++ b/scripts/config_check/cmd.txt @@ -0,0 +1,44 @@ +# command script for refresh.sh +# +# comments must be removed in calling script (e.g. cut -d'#' -f1) +# +# Do not edit this ./configure command: +./configure +# +# Edit parameters as needed (example shown, set your own parameters and comments) +# + ## + ## enabled features: + ## + --enable-sha # SHA required for TLS1.2 connect, beware of side-effect enable (e.g. old TLS) + --enable-stacksize=verbose + --enable-trackmemory=verbose + --enable-stacksize + + ## + ## disabled features: + ## + --disable-inline # when you don't want to inline functions + --disable-crypttests # crypttests + --disable-crypttests-libs # crypttests-libs + --disable-sha3 # + --disable-sha512 + --disable-sha224 + --disable-sha512 + --disable-sha384 + --disable-oldtls # disable old TLS versions < 1.2 (default: enabled) + --disable-tlsv10 # + --disable-sslv3 + + + ## + ## WPA + ## + --disable-wpas + --disable-wpas-dpp + + ## + ## Debugging + ## + --disable-memtest # memory testing: WOLFSSL_DEBUG_MEMORY (not active unless defined) + --enable-errorstrings # relatively little benefit to RAM either way diff --git a/scripts/config_check/options.h b/scripts/config_check/options.h new file mode 100644 index 0000000000..5f21b71173 --- /dev/null +++ b/scripts/config_check/options.h @@ -0,0 +1 @@ +/* After running the refresh.sh command, this file will contain a copy of the generated options.h file. */ diff --git a/scripts/config_check/output.txt b/scripts/config_check/output.txt new file mode 100644 index 0000000000..ced81d257b --- /dev/null +++ b/scripts/config_check/output.txt @@ -0,0 +1 @@ +After running the refresh.sh command, this file will contain the output history. \ No newline at end of file diff --git a/scripts/config_check/refresh.sh b/scripts/config_check/refresh.sh new file mode 100644 index 0000000000..6a4bffe475 --- /dev/null +++ b/scripts/config_check/refresh.sh @@ -0,0 +1,142 @@ +#!/bin/bash + +# requires autoconf, automake and libtool +# See https://github.com/wolfSSL/wolfssl/blob/master/INSTALL + +# we expect to be starting in the scripts directory, so move to the parent. +cd "../.." + +# the location of wolfSSL where the ./configure script should run +WOLFSSL_REPO="$PWD" + + +if [ ! -f "configure" ]; then + echo "configure not found! did you forget to run autogen.sh in $PWD?" + exit 1 +fi + +echo This WOLFSSL_REPO = $PWD + +# the directory where output files go (a github repo is helpful for tracking changes) +WOLFSSL_FILE_ROOT="$WOLFSSL_REPO/scripts/config_check" +echo "WOLFSSL_FILE_ROOT = $WOLFSSL_FILE_ROOT" + +mkdir -p "$WOLFSSL_FILE_ROOT" + +# set a variable for the input command +WOLFSSL_CMD_FILE="$WOLFSSL_FILE_ROOT/cmd.txt" + +# make sure we actually have a cmd.txt file +if [ ! -f "$WOLFSSL_CMD_FILE" ]; then + echo "Looking for $WOLFSSL_CMD_FILE" + echo "The needed cmd.txt file was not found. Please see README.md file." + exit 1 +fi + +# setup some variables for output files +WOLFSSL_OUTPUT="$WOLFSSL_FILE_ROOT/output.txt" +WOLFSSL_OPTIONS="$WOLFSSL_FILE_ROOT/options.h" +WOLFSSL_YES="$WOLFSSL_FILE_ROOT/Enabled-Features.txt" +WOLFSSL_NO="$WOLFSSL_FILE_ROOT/Disabled-Features.txt" + +# we'll want to run configure from the root directory of wolfssl +cd "$WOLFSSL_REPO" + +# save current help text for reference +./configure --help > "./help.txt" +retVal=$? +if [ $retVal -ne 0 ]; then + echo "Error" + exit $retVal +fi + +# show the command text found +echo "CMD File= $WOLFSSL_CMD_FILE" +echo "" + +# test drive the cat, cut, awk, sed as a preview. +# this command should exactly math the one below: WOLFSSL_CMD="$(cat ... +cat $WOLFSSL_CMD_FILE | cut -d'#' -f1 | awk NF | sed 's/\\//g'> /dev/null + +# the first digit will be cat exit code, the second will be cut exit code. +# the third digit is awk result, forth is sed result. +# success is expected to be "0000". +retVal="${PIPESTATUS[0]}${PIPESTATUS[1]}${PIPESTATUS[2]}${PIPESTATUS[3]}" + +# both the command and tee output must return a success (zero) to proceed. +# echo "cat & cut = $retVal" +if [ "$retVal" != "0000" ]; then + echo "Error parsing the command in $WOLFSSL_CMD_FILE" + exit 1 +fi + +# get the contents of the command file, trimming all text after the # character +# this exact command text should have been preview tested (above). +WOLFSSL_CMD="$(cat $WOLFSSL_CMD_FILE | cut -d'#' -f1 | awk NF | sed 's/\\//g')" +retVal=$? + +if [ $retVal -ne 0 ]; then + echo "Error assigning command value." + exit $retVal +fi + + +echo "Running command: " > $WOLFSSL_OUTPUT +echo "" >> $WOLFSSL_OUTPUT +echo "CMD = $WOLFSSL_CMD" | tee -a "$WOLFSSL_OUTPUT" +echo "" + +echo Running configure from $PWD | tee -a "$WOLFSSL_OUTPUT" + +echo "" >> $WOLFSSL_OUTPUT +echo "------------------------" >> $WOLFSSL_OUTPUT +echo "Output:" >> $WOLFSSL_OUTPUT +echo "------------------------" >> $WOLFSSL_OUTPUT +echo "" >> $WOLFSSL_OUTPUT + +# Execute the command: +# bash -c $WOLFSSL_CMD +$(echo $WOLFSSL_CMD) | tee -a "$WOLFSSL_OUTPUT" + +# the first digit will be CMD exit code; the second will be tee exit code. +# success is expected to be "00" +retVal="${PIPESTATUS[0]}${PIPESTATUS[1]}" + +# check if the command failed, but tee success +if [ "$retVal" == "10" ]; then + echo "The command in $WOLFSSL_CMD_FILE failed." + exit 1 +fi + +# check if the command was successful, but tee failes +if [ "$retVal" == "01" ]; then + echo "Error running command to tee in $WOLFSSL_CMD_FILE" + exit 1 +fi + +# both the command and tee output must return a success (zero) to proceed. +if [ "$retVal" != "00" ]; then + echo "Error running command $WOLFSSL_CMD_FILE" + exit 1 +fi + +# save the generated options.h +echo "" +echo Copying $PWD/wolfssl/options.h to "$WOLFSSL_OPTIONS" +cp wolfssl/options.h "$WOLFSSL_OPTIONS" + +# pull out the enabled and disabled features into separate files +echo "" +echo "Saving enabled summary to $WOLFSSL_YES" +grep "\*" "$WOLFSSL_OUTPUT" | grep yes > "$WOLFSSL_YES" + +echo "" +echo "Saving disabled summary to $WOLFSSL_NO" +grep "\*" "$WOLFSSL_OUTPUT" | grep no > "$WOLFSSL_NO" + +echo "" +echo "See output history in $WOLFSSL_OUTPUT" + +echo "" +echo "Done! Thank you for using wolfSSL" +echo "" diff --git a/scripts/include.am b/scripts/include.am index 97aae0776a..8d374fcc05 100644 --- a/scripts/include.am +++ b/scripts/include.am @@ -126,3 +126,8 @@ endif EXTRA_DIST += scripts/bench/bench_functions.sh EXTRA_DIST += scripts/user_settings_asm.sh + +EXTRA_DIST += \ + scripts/config_check/README.md \ + scripts/config_check/cmd.txt \ + scripts/config_check/refresh.sh