General documentation overhaul

CONFIGURE.md

@@ -0,0 +1,143 @@
+Configuring oqsprovider
+=======================
+
+This document lists all configuration options for `oqsprovider`.
+
+## Pre-build configuration
+
+Significant parts of this code are generated by the script `oqs-template/generate.py`.
+This script permits integration and activation of all quantum safe
+algorithms made available by [liboqs](https://github.com/open-quantum-safe/liboqs).
+The default configuration is as defined in the [algorithm configuration file](oqs-template/generate.yml).
+
+Any PR changing this default must include all files changed by `generate.py`.
+
+## Build install options
+
+### OPENSSL_ROOT_DIR
+
+Defines a non-standard location for an OpenSSL(v3) installation via `cmake` define.
+By default this value is unset, requiring presence of an OpenSSL3 installation
+in a standard OS deployment location.
+
+### CMAKE_BUILD_TYPE
+
+By setting this `cmake` configuration option to "Release" all debug output is disabled.
+This is the default setting.
+
+### liboqs_DIR
+
+This environment variable must be set to the location of the `liboqs` installation to be
+utilized in the build.
+By default, this is un-set, requiring installation of `liboqs` in a standard
+location for the OS.
+
+### USE_ENCODING_LIB
+
+By setting `-DUSE_ENCODING_LIB=<ON/OFF>` at compile-time, oqs-provider can be
+compiled with with an an external encoding library `qsc-key-encoder`.
+Configuring the encodings is done via environment as described in [ALGORITHMS.md](ALGORITHMS.md).
+The default value is `OFF`.
+
+### NOPUBKEY_IN_PRIVKEY
+
+By setting this to "ON", it can be specified to omit explicitly serializing
+the public key in a `privateKey` structure, e.g., for interoperability testing.
+The default value is `OFF`.
+
+## Convenience build script options
+
+For anyone interested in building the complete software stack
+(`openssl`(v3), `liboqs` and `oqs-provider`) the files `fullbuild.sh`
+and `runtests.sh` in the `scripts` directory cater for that.
+These files can be configured via the following environment variables:
+
+### OPENSSL_INSTALL
+
+Directory of an existing, non-standard OpenSSL binary distribution.
+
+### OPENSSL_BRANCH
+
+Tag of a specific OpenSSL release to be built and used in testing.
+Care is advised setting this to values lower than "3.0.9" due to many known
+code deficiencies related to providers in such old OpenSSL branches.
+
+### LIBOQS_BRANCH
+
+This defines the branch of `liboqs` against which `oqs-provider` is built.
+This can be used, for example, to facilitate a release of `oqsprovider`
+to track an old/stable `liboqs` release.
+Default is "main" (most current code).
+
+### liboqs_DIR
+
+If this environment variable is set, `liboqs` is not being built but
+used from the directory specified in this variable: Both `include`
+and `lib` directories must be present in that location.
+By not setting this variable, `liboqs` is build from source.
+
+### LIBOQS_BRANCH
+
+If set, this environment variable designates the `liboqs` branch to
+be built. If this variable is not set, the "main" branch is built.
+
+### MAKE_PARAMS
+
+This environment variable permits passing parameters to the `make`
+command used to build `openssl`, e.g., "-j 8" to activate 8-fold
+parallel builds to reduce the compilation time on a suitable multicore
+machine.
+
+### OQS_SKIP_TESTS
+
+By setting this tests environment variable, testing of specific
+algorithm families as listed [here](https://github.com/open-quantum-safe/openssl#supported-algorithms)
+can be disabled in testing.
+By default this variable is unset.
+
+Example use:
+
+    OQS_SKIP_TESTS="sphincs" ./scripts/runtests.sh
+
+excludes all algorithms of the "Sphincs" family (speeding up testing significantly).
+
+*Note*: By default, interoperability testing with oqs-openssl111 is no longer
+performed by default but can be manually enabled in the script `scripts/runtests.sh`.
+
+### OPENSSL_CONF
+
+This test environment variable can be used to instruct `openssl` to use a 
+configuration file from a non-standard location. Setting this value also
+disables the automation logic built into `runtests.sh`, thus requiring
+knowledge of `openssl` operations when setting it.
+By default this variable is unset.
+
+## LIBOQS configuration options
+
+These are [documented in full here](https://github.com/open-quantum-safe/liboqs/wiki/Customizing-liboqs).
+One option is of particular context here, particularly if building
+`oqs-provider` static, i.e., as a standalone binary not requiring
+presence of `liboqs` during deployment:
+
+### OQS_ALGS_ENABLED
+
+In order to reduce the size of the oqsprovider, it is possible to limit the number
+of algorithms supported, e.g., to the set of NIST standardized algorithms. This is
+facilitated by setting the `liboqs` build option `-DOQS_ALGS_ENABLED=STD` when building
+`liboqs`. The list of algorithms supported by `oqs-provider` is defined by
+the contents of the file `generate.yml` documented in the [pre-build configuration](#pre-build-configuration).
+
+## Runtime options
+
+The `openssl` [property selection mechanism](https://www.openssl.org/docs/manmaster/man7/property.html)
+can be utilized to make run-time algorithm selections.
+
+### oqsprovider.security_bits
+
+It is possible to select only algorithms of a specific bit strength by using
+the openssl property selection mechanism on the key "oqsprovider.security_bits",
+e.g., as such: `openssl list -kem-algorithms -propquery oqsprovider.security_bits=256`.
+The bit strength of hybrid algorithms is always defined by the bit strength
+of the classic algorithm.
+
+

NOTES-UNIX.md

@@ -0,0 +1,60 @@
+UNIX-specific build/install instructions
+========================================
+
+`oqsprovider` is first and foremost being developed and maintained under
+Linux. Therefore, all UNIX-like builds, incl. `cygwin`, should work with
+least problems.
+
+## Dependencies
+
+### OpenSSLv3
+
+OpenSSL (>=3.0.0) is becoming generally available via the various package
+managers and distributions, e.g., via `apt install openssl` or `brew install openssl@3`.
+
+If it is not, please build and install via the instructions [here](https://github.com/openssl/openssl/blob/master/NOTES-UNIX.md).
+
+### liboqs
+
+`liboqs` is available in some select distributions and package managers,
+e.g., via `brew install liboqs` on MacOS, but typically needs to be build
+from source. See instructions [here](https://github.com/open-quantum-safe/liboqs#linuxmacos).
+
+## Build tooling
+
+`oqsprovider` at minimum needs `git` access, `cmake` and a C compiler
+to be present to be build, e.g., via `apt install cmake build-essential git`.
+
+## Build
+
+Standard `cmake` build sequence can be used (assuming prerequisites are installed)
+to build in/install from directory `_build`:
+
+    cmake -S . -B _build && cmake --build _build && cmake --install _build
+
+If `openssl` and/or `liboqs` have not been installed to system standard locations
+use the `cmake` define "-DOPENSSL_ROOT_DIR" and/or the environment variable 
+"liboqs_DIR" to utilize those, e.g., like this:
+
+    liboqs_DIR=../liboqs cmake -DOPENSSL_ROOT_DIR=/opt/openssl3 -S . -B _build && cmake --build _build && cmake --install _build
+
+Further configuration options are documented [here](CONFIGURE.md#build-install-options).
+
+## Test
+
+Standard `ctest` can be used to validate correct operation in build directory `_build`, e.g.:
+
+    cd _build && ctest --parallel 5 --rerun-failed --output-on-failure -V
+
+## Packaging
+
+### Debian
+
+A build target to create UNIX .deb packaging is available via the standard
+`package` target, e.g., executing `make package` in the `_build` subdirectory.
+The resultant file can be installed as usual via `dpkg -i ...`.
+
+### MacOS
+
+An ".rb" packaging script for `brew` is available in the `scripts` directory
+and is regularly tested as part of CI.

NOTES-Windows.md

@@ -0,0 +1,57 @@
+UNIX-specific build/install instructions
+========================================
+
+`oqsprovider` can also be build on/for Windows using Microsoft Visual
+Studio for C (MSVC) or `cygwin`. For the latter, please check the
+[notes for Unix](NOTES-UNIX.md).
+
+## Dependencies
+
+### OpenSSLv3
+
+OpenSSL (>=3.0.0) is not yet generally available under Windows. It is
+therefore sensible to build it from scratch.
+
+For that, please follow the instructions [here](https://github.com/openssl/openssl/blob/master/NOTES-WINDOWS.md).
+A complete scripted setup is available in the [CI tooling for oqs-provider](https://github.com/open-quantum-safe/oqs-provider/blob/main/.github/workflows/windows.yml).
+
+### liboqs
+
+Instructions for building `liboqs` from source is available 
+[here](https://github.com/open-quantum-safe/liboqs#windows).
+
+## Build tooling
+
+`oqsprovider` is best built on Windows when `git` access, `cmake`, `ninja` and
+a C compiler are present, e.g., as in MS Visual Studio 2022.
+
+## Build
+
+A standard `cmake` build sequence can be used (assuming prerequisites are installed)
+to build in/install from directory `_build`:
+
+    cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_FLAGS="/wd5105" -GNinja -S . -B _build && cd _build && ninja && ninja install
+
+The specific `CMAKE_C_FLAGS` silence some overly strict warning messages and
+the specific reference to the build type ensures a shared library with
+release symbols, suitable for use with a release-symbol `openssl` build
+is created.
+
+If `openssl` and/or `liboqs` have not been installed to system standard locations
+use the `cmake` defines "-DOPENSSL_ROOT_DIR" and/or "-Dliboqs_DIR" to utilize
+those, e.g., like this:
+
+    cmake -DOPENSSL_ROOT_DIR=c:\opt\openssl3 -Dliboqs_DIR=c:\liboqs -S . -B _build && cmake --build _build && cmake --install _build
+
+Further configuration options are documented [here](CONFIGURE.md#build-install-options).
+
+## Test
+
+Standard `ctest` can be used to validate correct operation in build directory `_build`, e.g.:
+
+    ctest -V --test-dir _build
+
+## Packaging
+
+Packaging the resultant .DLL is not yet implemented. Suggestions which package manager
+to use are welcome.