################################################################################
# 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 3.0 (2024) compliance.

When enabling this option, two entropy sources must
deliver 240 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 240 bits of entropy.

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

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: 1024,
       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.
''')

option('drng_reseed_threshold_bits', type: 'integer', value: 0xffffffff,
       description: '''Besides request count based reseeding, this option can
       be used to enable request size (Bit) based reseeding. Set this to
       UINT32_MAX (0xffffffff) to disable it (default).

       Request size based reseeding works in two stages.
       After 'drng_reseed_threshold_bits' (this option) the DRNG code
       tries to reseed the DRNG instance.

       If this was unsucessful multiple times, the DRNG changes into
       the unseeded state after 'drng_max_reseed_bits' bits.
       Therefore 'drng_max_reseed_bits' always has to be larger than
       'drng_reseed_threshold_bits'.

       Set this setting to anything lower than 131072 (2**17) to enforce
       DRG.4.10 of AIS 20/31 Version 3.0. E.g. 65536 (2**16) and
       'drng_max_reseed_bits' to 131072 (2**17).
       ''')

option('drng_max_reseed_bits', type: 'integer', value: 0xffffffff,
       description: '''This sets the maximum number of output/request bits before
       the DRNG instances become loose their fully seeded state without
       successful reseeding.

       UINT32_MAX (0xffffffff) disables this setting. For more details on this
       setting see the description of 'drng_reseed_threshold_bits'.
       ''')

option('num-aux-pools', type: 'integer', value: 1, min: 1, max: 1024,
       description: '''Increases the number of aux pools in order to be more robust
       on seed bursts.
       ''')

option('systemd', type: 'feature', value: 'enabled',
       description: '''Enable support for systemd notify and systemd socket activation

       ESDM services will notify systemd about beeing ready and use provided FDs
       for their sockets (socket activation).
       ''')

################################################################################
# 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.
''')

option('openssl_drng_type', type: 'combo', value: 'hash',
       choices: [ 'ctr', 'hash', 'hmac' ],
       description: '''Selects the OpenSSL DRNG implementation

In addition to the Hash DRBG, OpenSSL supports a faster CTR DRBG and a more conservative HMAC-DRBG implementation,
which conforms to SP800-90A. Default to the middle ground option 'hash'.
''')

option('botan_drng_type', type: 'combo', value: 'hmac',
       choices: [ 'chacha20', 'hmac' ],
       description: '''Selects the botan DRNG implementation

Botan supports a faster ChaCha20 DRNG and a more conservative HMAC-DRBG implementation,
which conforms to SP800-90A. Default to the conservative option 'hmac'.
''')

################################################################################
# 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('linux-getrandom-num-nodes', type: 'integer', value: 1, min: 0, max: 64,
       description: 'Number of DRNG nodes to allocate for getrandom. 0 means no limit.')

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('linux-reseed-interval', type: 'integer', value: 120,
       description: 'interval between forced Linux kernel RNG reseeds (in seconds)')
option('linux-reseed-entropy-count', type: 'integer', value: 0, min: 0, max: 256,
       description: 'amount of entropy to account on kernel reseed (without es_irq)')

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

option('esdm-server-rpc-path-unprivileged', type: 'string', value: '/run',
       description: '''Sets the base path of ESDM's RPC sockets (default: /run)

       If this value is changed from the default, custom systemd units need to be adapted accordingly
       by the integrator of ESDM (if systemd is used at all).

       Use this e.g. combination with chroot to create a directory
       with only the unprivileged endpoint.
       ''')

option('esdm-server-rpc-path-privileged', type: 'string', value: '/run',
       description: '''Sets the base path of ESDM's RPC sockets (default: /run)

       If this value is changed from the default, custom systemd units need to be adapted accordingly
       by the integrator of ESDM (if systemd is used at all).

       You may use this option to keep the privileged socket in a different path than
       the unprivileged socket.
       ''')

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

option('esdm-aux-client', type: 'feature', value: 'enabled',
       description: '''Enable the ESDM auxiliary client library

With this option, the ESDM auxiliary client library is enabled allowing access
to auxiliary functions offered by the ESDM. This library is a convenience
wrapper around interfaces offered by ESDM that can be directly used.''')

# 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, ...)''')

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

################################################################################
# Server-related Configuration
################################################################################

option('esdm-server-term-on-signal', type: 'boolean', value: true,
       description:'''ESDM-Server: Terminate on signal

When enabled, the ESDM server sleeps on accept() either until a connection
arrives or until a terminating signal is received. When a signal is recieved,
the workerloop terminates and with it the server terminates. Conversely if
this option is disabled, the ESDM server wakes up regularly to check whether
the termination signal was received.

This option is intended when for unknown reasons the accept() does not terminate
even though the server shall exit.
''')

option('esdm-server-rpc-idle-timeout-usec', type: 'integer', value: 2000000,
       description:'''ESDM-Server: idle connection timeout

Defines the period of time, in which idle/stale RPC sockets are kept in a server
thread. The client code also uses this value to close idle connections after half
of this time in order to reduce timeouts.

Lower this value further, when the amount of worker threads shall be not increased
further and a high rate of short connections may saturates them.
''')


################################################################################
# Auxiliary Options
################################################################################

option('small_memory', type: 'boolean', value: false,
       description:'''Reduce Memory Footprint

When enabled, the code is compiled such that it attempts to reduce the memory
foot print of the entire code base as much as possible. This goes to the expense
of the performance.
''')

option('validation-helpers', type: 'feature', value: 'disabled',
       description: 'Enabled build of entropy validation helpers for esdm_es.')

################################################################################
# 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!''')
