################################################################################
# Jitter RNG entropy source configuration
################################################################################

option('es_jent', type: 'feature', value: 'enabled',
       description: '''Enable support for Jitter RNG entropy source.

The ESDM may use the Jitter RNG as entropy source. Enabling
this option enables the use of the Jitter RNG.
''')

# Option for: ESDM_JENT_ENTROPY_RATE
option('es_jent_entropy_rate', type: 'integer', min: 0, max: 256, value: 256,
       description:'''Jitter RNG entropy source entropy rate

The option defines the amount of entropy the ESDM applies to 256 bits of
data obtained from the Jitter RNG entropy source. The ESDM enforces the
limit that this value must be in the range between 0 and 256.
''')

# Option for: ESDM_JENT_ENTROPY_BLOCKS
option('es_jent_entropy_blocks', type: 'integer', value: 128,
       description:'''Jitter RNG entropy buffer size

The Jitter RNG as an entropy buffer that is filled with a separate thread
using the Jitter RNG. This shall ensure that data from the Jitter RNG is readily
available when needed by the ESDM. When using this buffer is enabled via
runtime option, the thread is started. Otherwise the Jitter RNG is asked to
produce random numbers when the caller needs it.

This option sets the size of the buffer in term of Jitter RNG blocks.

This value must be a power of 2 which is checked during compilation!

When set to zero, the Jitter RNG entropy buffer is not compiled which implies
a synchronous generation of data from the Jitter RNG.
''')

################################################################################
# CPU-based Entropy Source configuration options
################################################################################

option('es_cpu', type: 'feature', value: 'enabled',
       description: '''Enable support for CPU-based entropy source.

Current CPUs commonly contain entropy sources which can be
used to seed the ESDM. For example, the Intel RDSEED
instruction, or the POWER DARN instruction will be sourced
to seed the ESDM if this option is enabled.

Note, if this option is enabled and the underlying CPU
does not offer such entropy source, the ESDM will
automatically detect this and ignore the hardware.
''')

# Option for: ESDM_CPU_ENTROPY_RATE
option('es_cpu_entropy_rate', type: 'integer', min: 0, max: 256, value: 8,
       description:'''CPU-based entropy source entropy rate.

The option defines the amount of entropy the ESDM applies to 256
bits of data obtained from the CPU entropy source. The ESDM
enforces the limit that this value must be in the range between 0 and 256.

When configuring this value to 0, the CPU entropy source will provide
256 bits of data without being credited to contain entropy.
''')

# Option for: ESDM_CPU_FULL_ENT_MULTIPLIER
option('es_cpu_multiplier', type: 'integer', min: 1, value: 1,
       description: '''CPU-based entropy source data multiplier.

Some entropy sources specify that its entropy source requires an
oversampling. This multiplier is set to a default not performing an
oversampling. However, this value is adjusted by specific CPU entropy
source glue code.
''')

################################################################################
# Kernel RNG entropy source configuration (/dev/random)
################################################################################

option('es_kernel', type: 'feature', value: 'enabled',
       description: 'Enable support for kernel entropy source (/dev/random).')

# Option for: ESDM_KERNEL_RNG_ENTROPY_RATE
option('es_kernel_entropy_rate', type: 'integer', min: 0, max: 256, value: 128,
       description:'''Kernel entropy source entropy rate.

The option defines the amount of entropy the ESDM applies to 256 bits of
data obtained from the kernel RNG entropy source. The ESDM enforces the
limit that this value must be in the range between 0 and 256.

When configuring this value to 0, the kernel RNG entropy source will provide
256 bits of data without being credited to contain entropy.

Note: This value is set to 0 automatically when booting the kernel in FIPS
mode (with fips=1 kernel command line option). This is due to the fact that
random.c is not SP800-90B compliant.
''')

################################################################################
# Interrupt-based entropy source configuration
################################################################################

# Option for: ESDM_ES_IRQ
 option('es_irq', type: 'feature', value: 'enabled',
       description: '''Enable support for interrupt-based entropy source.

The ESDM models an entropy source based on the timing of the
occurrence of interrupts. Enable this option to enable this
IRQ entropy source.

The IRQ entropy source is triggered every time an interrupt
arrives and thus causes the interrupt handler to execute
slightly longer. Disabling the IRQ entropy source implies
that the performance penalty on the interrupt handler added
by the ESDM is eliminated. Yet, this entropy source is
considered to be an internal entropy source of the ESDM.
Thus, only disable it if you ensured that other entropy
sources are available that supply the ESDM with entropy.

Side note: when enabling this entropy source, one of the main
entropy sources of the kernel RNG is divered into ESDM. This
means that this entropy source is not available to the kernel
RNG any more. To offset the issue, the ESDM reseeds the
kernel RNG once in a while.
''')

# Option for: ESDM_IRQ_ENTROPY_RATE
option('es_irq_entropy_rate', type: 'integer', min: 0, max: 256, value: 256,
       description:'''Interrupt-based entropy source entropy rate.

ES configuration done in the kernel module - see kernel module code.

The option defines the amount of entropy the ESDM applies to 256 bits of
data obtained from the interrupt entropy source. The ESDM enforces the
limit that this value must be between 0 and 256 bits. Note, this entropy
rate is applied on the entropy value reported by the interrupt-ES kernel
module.

Note, this value caps the interrupt ES kernel module value!

Note 2: The events for the interrupt-baased and scheduler-based ES
both have some dependencies. Thus it is not permissible to award both
entropy sources an entropy rate greater than zero.
''')

################################################################################
# Scheduler-based entropy source configuration
################################################################################

# Option for: ESDM_ES_SCHED
option('es_sched', type: 'feature', value: 'enabled',
       description: '''Enable support for scheduler-based entropy source.

The ESDM models an entropy source based on the timing of the
occurrence of scheduler-triggered context switches. Enable
this option to enable this scheduler entropy source.

The scheduler entropy source is triggered every time a
context switch is triggered thus causes the scheduler to
execute slightly longer. Disabling the scheduler entropy
source implies that the performance penalty on the scheduler
added by the ESDM is eliminated. Yet, this entropy source is
considered to be an internal entropy source of the ESDM.
Thus, only disable it if you ensured that other entropy
sources are available that supply the ESDM with entropy.

If you disable the scheduler entropy source, you MUST
ensure one or more entropy sources collectively have the
capability to deliver sufficient entropy with one invocation
at a rate compliant to the security strength of the DRNG
(usually 256 bits of entropy). In addition, if those
entropy sources do not deliver sufficient entropy during
first request, the reseed must be triggered from user
space or kernel space when sufficient entropy is considered
to be present.
''')

# Option for: ESDM_SCHED_ENTROPY_RATE
option('es_sched_entropy_rate', type: 'integer', min: 0, max: 256, value: 0,
       description:'''Scheduler-based entropy source entropy rate.

ES configuration done in the kernel module - see kernel module code.

The option defines the amount of entropy the ESDM applies to 256 bits of
data obtained from the scheduler entropy source. The ESDM enforces the
limit that this value must be between 0 and 256 bits. Note, this entropy
rate is applied on the entropy value reported by the scheduler-ES kernel
module.

Note, this value caps the scheduler ES kernel module value!

Note 2: The events for the interrupt-baased and scheduler-based ES
both have some dependencies. Thus it is not permissible to award both
entropy sources an entropy rate greater than zero.
''')

################################################################################
# /dev/hwrand-based Entropy Source configuration options
################################################################################

option('es_hwrand', type: 'feature', value: 'enabled',
       description: '''Enable support for /dev/hwrng-based entropy source.

The Linux kernel offers the hardware random number generator framework
which is accessible via /dev/hwrng. This interface covers also TPM2.0
devices.

Note, if this option is enabled and the underlying Linux system
does not offer such entropy source, the ESDM will
automatically detect this and ignore the hardware.
''')

# Option for: ESDM_HWRAND_ENTROPY_RATE
option('es_hwrand_entropy_rate', type: 'integer', min: 0, max: 256, value: 128,
       description:'''CPU-based entropy source entropy rate.

The option defines the amount of entropy the ESDM applies to 256
bits of data obtained from the CPU entropy source. The ESDM
enforces the limit that this value must be in the range between 0 and 256.

When configuring this value to 0, the CPU entropy source will provide
256 bits of data without being credited to contain entropy.
''')

################################################################################
# Linux-kernel jitterentropy Entropy Source
################################################################################

option('es_jent_kernel', type: 'feature', value: 'disabled',
       description: '''Enable support for jitterentropy-based entropy source
       (in-kernel).
''')

# Option for: ESDM_JENT_KERNEL_ENTROPY_RATE
option('es_jent_kernel_entropy_rate', type: 'integer', min: 0, max: 256, value: 256,
       description:'''kernel-based jitter entropy source entropy rate.

The option defines the amount of entropy the ESDM applies to 256
bits of data obtained from the kernel jitter entropy source. The ESDM
enforces the limit that this value must be in the range between 0 and 256.

When configuring this value to 0, the kernel jitter entropy source will provide
256 bits of data without being credited to contain entropy.
''')

################################################################################
# Common Options
################################################################################

# Enable multi-node-DRNG support
option('node', type: 'feature', value: 'enabled',
       description: 'Enable support for multiple DRNG nodes.')

# Enable FIPS 140 support
option('fips140', type: 'boolean', value: 'false',
       description: '''Enable FIPS 140 support.

This option implicitly enables the SP800-90C compliance mode.
''')

# Option for: ESDM_OVERSAMPLE_ENTROPY_SOURCES
option('sp80090c', type: 'boolean', value: 'false',
       description:'''SP800-90C compliance

If enabled, the ESDM oversamples the entropy sources compliant to SP800-90C.

The following oversampling is applied:
* Seed the DRNG with 128 more bits of entropy from the conditioning component.
* Inject 64 more bits of entropy from the noise source into the conditioning
  component.
''')

# Option for: ESDM_AIS2031_NTG1_SEEDING_STRATEGY
option('ais2031', type: 'boolean', value: 'false',
       description:'''German AIS 20/31 (2022) compliance.

When enabling this option, two entropy sources must
deliver 220 bits of entropy each to consider a DRNG
as fully seeded. Any two entropy sources can be used
to fulfill this requirement. If specific entropy sources
shall not be capable of contributing to this seeding
strategy, the respective entropy source must be configured
to provide less than 220 bits of entropy.

The strategy is consistent with the requirements for
NTG.1 compliance in German AIS 20/31 draft from 2022.

Compliance with German AIS 20/31 from 2011 is always
present when using /dev/random with the flag O_SYNC or
getrandom(2) with GRND_RANDOM.
''')

# Option for: THREADING_MAX_THREADS
option('threading_max_threads', type: 'integer', min: 1, value: 64,
       description:'''Maximum number of concurrent threads supported.

This value can be set to any arbitrary number. Depending on the number
of threads, the required numbers of thread contexts are statically allocated.

The number of threads define:

* the number of concurrent DRNG instances that are maintained independent of
  each other - this value is limited by the number of found CPUs as it makes no
  sense to have more DRNG instances than CPUs that can execute them.

There is no other value that needs changing if the number of threads
shall be adjusted.

The value must not be lower than 1.
''')

################################################################################
# Cryptographic backends configuration
################################################################################

# Option for: ESDM_DRNG_HASH_DRBG
option('drng_hash_drbg', type: 'feature', value: 'enabled',
       description:'''Builtin: SP800-90A Hash Deterministic Random Number Generator.

This configuration enables an SP800-90A Hash DRBG with SHA-512 core
without prediction resistance when the builtin crypto primitives are selected.
''')

option('drng_chacha20', type: 'feature', value: 'disabled',
       description: 'Builtin: ChaCha20-based Deterministic Random Number Generator.')

option('hash_sha512', type: 'feature', value: 'enabled',
       description: 'Builtin: Enable SHA2-512 conditioning hash')

option('hash_sha3_512', type: 'feature', value: 'disabled',
       description: 'Builtin: Enable SHA3-512 conditioning hash')

option('crypto_backend', type: 'combo', value: 'builtin',
       choices: ['builtin',
		 'leancrypto',
		 'openssl',
		 'botan',
		 # 'gnutls' - GnuTLS disabled as DRBG only runs without DF
		],
       description: '''Select the cryptographic backend

The cryptographic backend provides the cryptographic primitives used by the
ESDM for the conditioning operation as well as random number generation. Only
one backend can be enabled.
''')

################################################################################
# Linux Interface Configuration
################################################################################

# Enable SELinux support
option('selinux', type: 'feature', value: 'enabled',
       description: '''Enable SELinux labeling support.

On some Linux environments, SELinux is used to label the
/dev/random and /dev/urandom device files. This allows specially
restricted applications, such as the OpenSSH daemon to access
those device files.

When creating the /dev/random and /dev/urandom devices, the
SELinux support of this option is used to ensure both are labeled
identically to the original device files.
''')

option('linux-devfiles', type: 'feature', value: 'enabled',
       description: '''Enable the Linux /dev/random and /dev/urandom support.

Using CUSE, the device files are provided.
''')

option('linux-getrandom', type: 'feature', value: 'enabled',
       description: 'Enable the Linux getrandom system call support.')

option('botan-rng', type: 'feature', value: 'disabled',
       description: '''Enable the Botan >= 3 RNG support.

In contrast to crypto backends, e.g. for leancrypto or OpenSSL, which provide
cryptographic primitives for usage inside ESDM, this enables support for a small
frontend library providing an ESDM-based RNG class for the Botan crypto library.
''')

option('openssl-rand-provider', type: 'feature', value: 'disabled',
       description: '''Enable the OpenSSL >= 3 RAND/SEED-SRC provider support.

Please note, that this is a ESDM frontend, which can provide random numbers
originated in ESDM to applications based on OpenSSL. Use -Dcrypto_backend=openssl
if you want to use the OpenSSL as a provider for ESDM-internal crypto algorithms,
like hash algorithms.
''')

option('esdm-server', type: 'feature', value: 'enabled',
       description: 'Enable the ESDM server')

################################################################################
# Client-related Configuration
################################################################################

# WARNING: handle all of these options with care as they may lead to an increased
# number of failed RPC replies to the client without random data or higher load
# due to faster retries!

option('client-connect-timeout-exponent', type: 'integer', min: 20, max: 29, value: 28,
       description: '''Timeout for ESDM client/server connection

Set the rpc client connect timeout to
1 << VAL nanoseconds. Change the default with care/know the consequences!
(perform tests under load, ...)''')

option('client-rx-tx-timeout-exponent', type: 'integer', min: 20, max: 29, value: 28,
       description: '''Timeout for ESDM client/server rx/tx operations

Set the rpc client send/receive timeout to
1 << VAL nanoseconds. Change the default with care/know the consequences!
(perform tests under load, ...)''')

option('client-reconnect-attempts', type: 'integer', min: 5, max: 30, value: 10,
       description: '''Reconnect tries for ESDM client/server connection

With this option, you have the possibility to increase the reconnect attempts
when decreasing the client connection timeout.
Change the default with care/know the consequences!
(perform tests under load, ...)''')

################################################################################
# Enable Test configuration
#
# WARNING: DO NOT ENABLE FOR PRODUCTION MODE
################################################################################
option('testmode', type: 'feature', value: 'disabled',
       description: '''Enable test configuration.

This option enables various test configurations for functional verification
testing.

WARNING: DO NOT ENABLE FOR PRODUCTION MODE!''')
