This document lists all configuration options for oqsprovider.
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.
The default configuration is as defined in the algorithm configuration file.
Any PR changing this default must include all files changed by generate.py.
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.
By setting this cmake configuration option to "Release" all debug output is disabled.
This is the default setting.
In case of any problem, setting this value to "Debug" is highly recommended to activate further warning messages. In particular, when "Debug" has been set, distinct debugging capabilities are activated and additional setup warnings are output.
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.
This uses the find_package
command in cmake, which checks for local builds of a package at <PackageName>_DIR
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.
The default value is OFF.
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.
By setting this to "ON", oqsprovider is configured to provide encoders and decoders for
KEM algorithms both for public and private key file formats. This increases the size of
the provider but enables further use cases.
The default value is OFF.
By setting -DOQS_PROVIDER_BUILD_STATIC=ON at compile-time, oqs-provider can be
compiled as a static library (oqs-provider.a).
When built as a static library, the name of the provider entrypoint is oqs_provider_init.
The provider can be added using the OSSL_PROVIDER_add_builtin
function:
#include <openssl/provider.h>
// Entrypoint.
extern OSSL_provider_init_fn oqs_provider_init;
void load_oqs_provider(OSSL_LIB_CTX *libctx) {
int err;
if (OSSL_PROVIDER_add_builtin(libctx, "oqsprovider", oqs_provider_init) == 1) {
if (OSSL_PROVIDER_load(libctx, "oqsprovider") == 1) {
fputs("successfully loaded `oqsprovider`.", stderr);
} else {
fputs("failed to load `oqsprovider`", stderr);
}
} else {
fputs("failed to add the builtin provider `oqsprovider`", stderr);
}
}Warning
OQS_PROVIDER_BUILD_STATICandBUILD_SHARED_LIBSare mutually exclusive.
See examples/static_oqsprovider.c for a complete
example of how to load oqsprovider using OSSL_PROVIDER_add_builtin.
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:
Directory of an existing, non-standard OpenSSL binary distribution.
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.
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. If this variable is not set, the
"main" branch is built.
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.
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.
This environment variable permits passing parameters to the cmake
command used to build oqsprovider.
By setting this tests environment variable, testing of specific algorithm families as listed here 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.
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.
These are documented in full here.
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:
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.
The openssl property selection mechanism
can be utilized to make run-time algorithm selections.
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.