management.util.startup_strategies¶

Startup strategies for Trustpoint initialization and restoration.

Attributes¶

`DEK_EXPECTED_LENGTH`
`DEFAULT_TOKEN_LABEL`

Classes¶

`OutputWriter`	Protocol for output writing (stdout/stderr).
`WizardState`	Enumeration of wizard completion states.
`DekCacheState`	Enumeration of DEK cache states (for HSM storage only).
`StartupScenario`	Enumeration of possible startup scenarios.
`StartupContext`	Context information for startup decisions.
`StartupStrategy`	Abstract base class for startup strategies.
`TlsCredentialStrategy`	Abstract base class for TLS credential generation strategies.
`StandardTlsCredentialStrategy`	Standard TLS credential generation using TlsServerCredentialGenerator.
`InitializationStrategy`	Abstract base class for Trustpoint initialization strategies.
`StandardInitializationStrategy`	Standard initialization: migrations, static files, messages.
`DatabaseNotInitializedStrategy`	Strategy for handling uninitialized database.
`DatabaseInitializedNoVersionStrategy`	Strategy for handling initialized database without version record.
`VersionMatchStrategy`	Strategy for handling version match (normal startup).
`VersionUpgradeStrategy`	Strategy for handling version upgrade.
`RestoreSoftwareWizardCompletedStrategy`	Strategy: Software storage + Wizard completed - extract TLS only.
`RestoreSoftwareWizardIncompleteStrategy`	Strategy: Software storage + Wizard incomplete - reset to beginning.
`RestoreSoftHsmWizardCompletedDekCachedStrategy`	Strategy: SoftHSM + Wizard completed + DEK cached - extract TLS and unwrap DEK.
`RestoreSoftHsmWizardCompletedDekNotCachedStrategy`	Strategy: SoftHSM + Wizard completed + DEK not cached - needs auto restore.
`RestoreSoftHsmNewKekWizardCompletedStrategy`	Strategy: SoftHSM + New KEK (old KEK lost) + Wizard completed - generate temp TLS, wait for backup password.
`RestoreSoftHsmWizardIncompleteDekCachedStrategy`	Strategy: SoftHSM + Wizard incomplete + DEK cached - reset to beginning.
`RestoreSoftHsmWizardIncompleteDekNotCachedStrategy`	Strategy: SoftHSM + Wizard incomplete + DEK not cached - reset to beginning.
`RestorePhysicalHsmWizardCompletedDekCachedStrategy`	Strategy: Physical HSM + Wizard completed + DEK cached - NOT SUPPORTED.
`RestorePhysicalHsmWizardCompletedDekNotCachedStrategy`	Strategy: Physical HSM + Wizard completed + DEK not cached - NOT SUPPORTED.
`RestorePhysicalHsmWizardIncompleteDekCachedStrategy`	Strategy: Physical HSM + Wizard incomplete + DEK cached - NOT SUPPORTED.
`RestorePhysicalHsmWizardIncompleteDekNotCachedStrategy`	Strategy: Physical HSM + Wizard incomplete + DEK not cached - NOT SUPPORTED.
`StartupStrategySelector`	Selector for determining the appropriate startup strategy.

Module Contents¶

management.util.startup_strategies.DEK_EXPECTED_LENGTH = 32[source]¶

management.util.startup_strategies.DEFAULT_TOKEN_LABEL = 'Trustpoint-SoftHSM'[source]¶

class management.util.startup_strategies.OutputWriter[source]¶

Bases: Protocol

Protocol for output writing (stdout/stderr).

write(msg)[source]¶

Write a message to output.

Parameters:: msg (str)
Return type:: None

success(msg)[source]¶

Format a success message.

Parameters:: msg (str)
Return type:: str

error(msg)[source]¶

Format an error message.

Parameters:: msg (str)
Return type:: str

warning(msg)[source]¶

Format a warning message.

Parameters:: msg (str)
Return type:: str

class management.util.startup_strategies.WizardState(*args, **kwds)[source]¶

Bases: enum.Enum

Enumeration of wizard completion states.

COMPLETED = 'COMPLETED'[source]¶

INCOMPLETE = 'INCOMPLETE'[source]¶

class management.util.startup_strategies.DekCacheState(*args, **kwds)[source]¶

Bases: enum.Enum

Enumeration of DEK cache states (for HSM storage only).

CACHED = 'CACHED'[source]¶

NOT_CACHED = 'NOT_CACHED'[source]¶

class management.util.startup_strategies.StartupScenario(*args, **kwds)[source]¶

Bases: enum.Enum

Enumeration of possible startup scenarios.

DB_NOT_INITIALIZED[source]¶

DB_INITIALIZED_NO_VERSION[source]¶

VERSION_MATCH[source]¶

VERSION_UPGRADE[source]¶

VERSION_DOWNGRADE[source]¶

RESTORE_SOFTWARE_WIZARD_COMPLETED[source]¶

RESTORE_SOFTWARE_WIZARD_INCOMPLETE[source]¶

RESTORE_SOFTHSM_WIZARD_COMPLETED_DEK_CACHED[source]¶

RESTORE_SOFTHSM_WIZARD_COMPLETED_DEK_NOT_CACHED[source]¶

RESTORE_SOFTHSM_WIZARD_INCOMPLETE_DEK_CACHED[source]¶

RESTORE_SOFTHSM_WIZARD_INCOMPLETE_DEK_NOT_CACHED[source]¶

RESTORE_SOFTHSM_NEW_KEK_WIZARD_COMPLETED[source]¶

RESTORE_PHYSICAL_HSM_WIZARD_COMPLETED_DEK_CACHED[source]¶

RESTORE_PHYSICAL_HSM_WIZARD_COMPLETED_DEK_NOT_CACHED[source]¶

RESTORE_PHYSICAL_HSM_WIZARD_INCOMPLETE_DEK_CACHED[source]¶

RESTORE_PHYSICAL_HSM_WIZARD_INCOMPLETE_DEK_NOT_CACHED[source]¶

class management.util.startup_strategies.StartupContext[source]¶

Context information for startup decisions.

db_initialized: bool[source]¶

db_version: packaging.version.Version | None[source]¶

current_version: packaging.version.Version[source]¶

wizard_state_enum: WizardState[source]¶

wizard_state_raw: setup_wizard.SetupWizardState | None[source]¶

storage_type: management.models.KeyStorageConfig.StorageType | None[source]¶

dek_cache_state: DekCacheState | None[source]¶

output: OutputWriter[source]¶

has_kek: bool = False[source]¶

has_backup_encrypted_dek: bool = False[source]¶

property is_wizard_completed: bool[source]¶

Check if wizard is completed.

Return type:: bool

property is_software_storage: bool[source]¶

Check if using software storage.

Return type:: bool

property is_softhsm_storage: bool[source]¶

Check if using SoftHSM storage.

Return type:: bool

property is_physical_hsm_storage: bool[source]¶

Check if using physical HSM storage.

Return type:: bool

property is_hsm_storage: bool[source]¶

Check if using any HSM storage (SoftHSM or Physical).

Return type:: bool

property is_dek_cached: bool[source]¶

Check if DEK is cached (only applicable for HSM storage).

Return type:: bool

property is_new_kek_scenario: bool[source]¶

Check if this is a new KEK scenario (old KEK lost, requires backup password).

This scenario occurs when: - Using HSM storage - DEK is not cached - KEK does NOT exist on the HSM (old KEK lost from previous installation) - Backup-encrypted DEK exists in the database

Note: We don’t check wizard_completed here because the wizard state might be inconsistent if restoring a database from a previous installation.

Returns:: True if this is a new KEK scenario requiring backup password recovery.
Return type:: bool

class management.util.startup_strategies.StartupStrategy[source]¶

Bases: abc.ABC

Abstract base class for startup strategies.

abstractmethod execute(context)[source]¶

Execute the startup strategy.

Parameters:: context (StartupContext) – The startup context with all relevant information.
Return type:: None

abstractmethod get_description()[source]¶

Get a human-readable description of this strategy.

Return type:: str

class management.util.startup_strategies.TlsCredentialStrategy[source]¶

Bases: abc.ABC

Abstract base class for TLS credential generation strategies.

abstractmethod generate_and_save_tls_credential(context)[source]¶

Generate and save TLS credentials.

Parameters:: context (StartupContext) – The startup context with all relevant information.
Return type:: None

class management.util.startup_strategies.StandardTlsCredentialStrategy(*, save_to_db=True)[source]¶

Bases: TlsCredentialStrategy

Standard TLS credential generation using TlsServerCredentialGenerator.

Parameters:: save_to_db (bool)

save_to_db = True[source]¶

generate_and_save_tls_credential(context)[source]¶

Generate TLS credentials and save to database and files.

Parameters:: context (StartupContext)
Return type:: None

_save_to_database(context, tls_server_credential)[source]¶

Save TLS credential to database and return PEM data.

Returns:

Tuple of (private_key_pem, certificate_pem, trust_store_pem, active_tls)

Parameters:

context (StartupContext)
tls_server_credential (Any)

Return type:

tuple[str, str, str, Any]

_get_pem_without_db_save(context, tls_server_credential)[source]¶

Get PEM data without saving to database.

Returns:

Tuple of (private_key_pem, certificate_pem, trust_store_pem)

Parameters:

context (StartupContext)
tls_server_credential (Any)

Return type:

tuple[str, str, str]

_write_pem_files(private_key_pem, certificate_pem, trust_store_pem)[source]¶

Write PEM files to Nginx paths.

Parameters:

private_key_pem (str)
certificate_pem (str)
trust_store_pem (str)

Return type:

None

_display_fingerprint(context, active_tls, tls_server_credential)[source]¶

Display SHA256 fingerprint of the certificate.

Parameters:

context (StartupContext)
active_tls (Any)
tls_server_credential (Any)

Return type:

None

class management.util.startup_strategies.InitializationStrategy[source]¶

Bases: abc.ABC

Abstract base class for Trustpoint initialization strategies.

abstractmethod initialize(context, *, with_tls=False)[source]¶

Initialize Trustpoint.

Parameters:

context (StartupContext) – The startup context with all relevant information.
with_tls (bool) – Whether to initialize TLS credentials.

Return type:

None

class management.util.startup_strategies.StandardInitializationStrategy(tls_strategy=None)[source]¶

Bases: InitializationStrategy

Standard initialization: migrations, static files, messages.

Parameters:: tls_strategy (TlsCredentialStrategy | None)

tls_strategy[source]¶

initialize(context, *, with_tls=False)[source]¶

Initialize Trustpoint with standard workflow.

Parameters:

context (StartupContext)
with_tls (bool)

Return type:

None

_raise_runtime_error(error_msg)[source]¶

Raise a RuntimeError.

Parameters:: error_msg (str) – The error message to log and raise.
Raises:: RuntimeError – Always raised with the provided error message.
Return type:: None

_check_softhsm_connectivity(context)[source]¶

Check if SoftHSM daemon is reachable.

Parameters:: context (StartupContext) – The startup context.
Raises:: RuntimeError – If SoftHSM daemon is not reachable.
Return type:: None

class management.util.startup_strategies.DatabaseNotInitializedStrategy(init_strategy=None)[source]¶

Bases: StartupStrategy

Strategy for handling uninitialized database.

Parameters:: init_strategy (InitializationStrategy | None)

init_strategy[source]¶

execute(context)[source]¶

Initialize database with TLS setup.

Parameters:: context (StartupContext)
Return type:: None

get_description()[source]¶

Get strategy description.

Return type:: str

class management.util.startup_strategies.DatabaseInitializedNoVersionStrategy(init_strategy=None)[source]¶

Bases: StartupStrategy

Strategy for handling initialized database without version record.

Parameters:: init_strategy (InitializationStrategy | None)

init_strategy[source]¶

execute(context)[source]¶

Initialize database with TLS setup.

Parameters:: context (StartupContext)
Return type:: None

get_description()[source]¶

Get strategy description.

Return type:: str

class management.util.startup_strategies.VersionMatchStrategy(restore_strategy, init_strategy=None)[source]¶

Bases: StartupStrategy

Strategy for handling version match (normal startup).

Parameters:

restore_strategy (StartupStrategy)
init_strategy (InitializationStrategy | None)

restore_strategy[source]¶

init_strategy[source]¶

execute(context)[source]¶

Initialize Trustpoint and perform restoration.

Parameters:: context (StartupContext)
Return type:: None

get_description()[source]¶

Get strategy description.

Return type:: str

class management.util.startup_strategies.VersionUpgradeStrategy(restore_strategy, app_version, init_strategy=None)[source]¶

Bases: StartupStrategy

Strategy for handling version upgrade.

Parameters:

restore_strategy (StartupStrategy)
app_version (management.models.AppVersion)
init_strategy (InitializationStrategy | None)

restore_strategy[source]¶

app_version[source]¶

init_strategy[source]¶

execute(context)[source]¶

Upgrade database version and perform restoration.

Parameters:: context (StartupContext)
Return type:: None

get_description()[source]¶

Get strategy description.

Return type:: str

class management.util.startup_strategies.RestoreSoftwareWizardCompletedStrategy[source]¶

Bases: StartupStrategy

Strategy: Software storage + Wizard completed - extract TLS only.

execute(context)[source]¶

Extract TLS certificates for software storage mode.

Parameters:: context (StartupContext)
Return type:: None

get_description()[source]¶

Get strategy description.

Return type:: str

static unwrap_dek_for_token(context, token_label=DEFAULT_TOKEN_LABEL)[source]¶

Test KEK loading and unwrap DEK for the specified token to make it available in cache.

This method follows the same logic as the unwrap_dek management command: 1. Get the token (or return gracefully if not found - software storage case) 2. Test KEK loading 3. Unwrap DEK (only if encrypted_dek exists)

Parameters:

context (StartupContext) – The startup context.
token_label (str) – The label of the PKCS11 token to unwrap DEK for.

Return type:

None

static extract_tls_from_database(context)[source]¶

Extract TLS certificates from database and write to Nginx paths.

Parameters:: context (StartupContext)
Return type:: None

class management.util.startup_strategies.RestoreSoftwareWizardIncompleteStrategy(tls_strategy=None)[source]¶

Bases: StartupStrategy

Strategy: Software storage + Wizard incomplete - reset to beginning.

Parameters:: tls_strategy (TlsCredentialStrategy | None)

tls_strategy[source]¶

execute(context)[source]¶

Reset wizard to WIZARD_SETUP_CRYPTO_STORAGE state and generate TLS certificates.

Parameters:: context (StartupContext)
Return type:: None

get_description()[source]¶

Get strategy description.

Return type:: str

static _reset_wizard_state(context)[source]¶

Reset wizard state to WIZARD_SETUP_CRYPTO_STORAGE.

Parameters:: context (StartupContext)
Return type:: None

static _map_exit_code_to_message(return_code)[source]¶

Map script exit codes to meaningful error messages.

Parameters:: return_code (int)
Return type:: str

class management.util.startup_strategies.RestoreSoftHsmWizardCompletedDekCachedStrategy[source]¶

Bases: StartupStrategy

Strategy: SoftHSM + Wizard completed + DEK cached - extract TLS and unwrap DEK.

execute(context)[source]¶

Extract TLS certificates and unwrap DEK for application use.

Parameters:: context (StartupContext)
Return type:: None

get_description()[source]¶

Get strategy description.

Return type:: str

class management.util.startup_strategies.RestoreSoftHsmWizardCompletedDekNotCachedStrategy[source]¶

Bases: StartupStrategy

Strategy: SoftHSM + Wizard completed + DEK not cached - needs auto restore.

execute(context)[source]¶

Trigger auto restore flow for SoftHSM with DEK not cached.

Parameters:: context (StartupContext)
Return type:: None

get_description()[source]¶

Get strategy description.

Return type:: str

static _set_auto_restore_state(context)[source]¶

Transition to WIZARD_AUTO_RESTORE_PASSWORD state.

Parameters:: context (StartupContext)
Return type:: None

static _map_exit_code_to_message(return_code)[source]¶

Map script exit codes to meaningful error messages.

Parameters:: return_code (int)
Return type:: str

class management.util.startup_strategies.RestoreSoftHsmNewKekWizardCompletedStrategy(tls_strategy=None)[source]¶

Bases: StartupStrategy

Strategy: SoftHSM + New KEK (old KEK lost) + Wizard completed - generate temp TLS, wait for backup password.

This scenario occurs when: - Trustpoint container and SoftHSM are new (fresh installation) - But there’s an existing database with encrypted data - The database was encrypted with a KEK that no longer exists on the new SoftHSM - The wizard was previously completed

The strategy: 1. Generates a temporary TLS certificate (since DB TLS cert is encrypted and inaccessible) 2. Transitions to WIZARD_AUTO_RESTORE_PASSWORD state 3. Waits for user to input backup password 4. BackupAutoRestorePasswordView will:

Generate a new KEK on the new SoftHSM

Decrypt the DEK using the backup password

Re-wrap the DEK with the new KEK

Extract and activate the actual TLS certificate from the database

Complete the wizard

Parameters:: tls_strategy (TlsCredentialStrategy | None)

tls_strategy[source]¶

execute(context)[source]¶

Generate temporary TLS certificate and trigger auto restore flow.

Parameters:: context (StartupContext)
Return type:: None

get_description()[source]¶

Get strategy description.

Return type:: str

class management.util.startup_strategies.RestoreSoftHsmWizardIncompleteDekCachedStrategy(tls_strategy=None)[source]¶

Bases: StartupStrategy

Strategy: SoftHSM + Wizard incomplete + DEK cached - reset to beginning.

Parameters:: tls_strategy (TlsCredentialStrategy | None)

tls_strategy[source]¶

execute(context)[source]¶

Reset wizard to WIZARD_SETUP_CRYPTO_STORAGE state and generate TLS certificates.

Parameters:: context (StartupContext)
Return type:: None

get_description()[source]¶

Get strategy description.

Return type:: str

class management.util.startup_strategies.RestoreSoftHsmWizardIncompleteDekNotCachedStrategy(tls_strategy=None)[source]¶

Bases: StartupStrategy

Strategy: SoftHSM + Wizard incomplete + DEK not cached - reset to beginning.

Parameters:: tls_strategy (TlsCredentialStrategy | None)

tls_strategy[source]¶

execute(context)[source]¶

Reset wizard to WIZARD_SETUP_CRYPTO_STORAGE state and generate TLS certificates.

Parameters:: context (StartupContext)
Return type:: None

get_description()[source]¶

Get strategy description.

Return type:: str

class management.util.startup_strategies.RestorePhysicalHsmWizardCompletedDekCachedStrategy[source]¶

Bases: StartupStrategy

Strategy: Physical HSM + Wizard completed + DEK cached - NOT SUPPORTED.

execute(context)[source]¶

Raise error as Physical HSM is not yet supported.

Parameters:: context (StartupContext)
Return type:: None

get_description()[source]¶

Get strategy description.

Return type:: str

class management.util.startup_strategies.RestorePhysicalHsmWizardCompletedDekNotCachedStrategy[source]¶

Bases: StartupStrategy

Strategy: Physical HSM + Wizard completed + DEK not cached - NOT SUPPORTED.

execute(context)[source]¶

Raise error as Physical HSM is not yet supported.

Parameters:: context (StartupContext)
Return type:: None

get_description()[source]¶

Get strategy description.

Return type:: str

class management.util.startup_strategies.RestorePhysicalHsmWizardIncompleteDekCachedStrategy[source]¶

Bases: StartupStrategy

Strategy: Physical HSM + Wizard incomplete + DEK cached - NOT SUPPORTED.

execute(context)[source]¶

Raise error as Physical HSM is not yet supported.

Parameters:: context (StartupContext)
Return type:: None

get_description()[source]¶

Get strategy description.

Return type:: str

class management.util.startup_strategies.RestorePhysicalHsmWizardIncompleteDekNotCachedStrategy[source]¶

Bases: StartupStrategy

Strategy: Physical HSM + Wizard incomplete + DEK not cached - NOT SUPPORTED.

execute(context)[source]¶

Raise error as Physical HSM is not yet supported.

Parameters:: context (StartupContext)
Return type:: None

get_description()[source]¶

Get strategy description.

Return type:: str

class management.util.startup_strategies.StartupStrategySelector[source]¶

Selector for determining the appropriate startup strategy.

static select_restore_strategy(context)[source]¶

Select the appropriate restore strategy based on context.

Parameters:: context (StartupContext) – The startup context with all relevant information.
Returns:: The appropriate StartupStrategy instance.
Return type:: StartupStrategy

static _log_strategy_selection(context)[source]¶

Log the current configuration for strategy selection.

Parameters:: context (StartupContext)
Return type:: None

static _select_software_strategy(context)[source]¶

Select strategy for SOFTWARE storage.

Parameters:: context (StartupContext)
Return type:: StartupStrategy

static _select_softhsm_strategy(context)[source]¶

Select strategy for SOFTHSM storage.

Parameters:: context (StartupContext)
Return type:: StartupStrategy

static _select_physical_hsm_strategy(context)[source]¶

Select strategy for PHYSICAL_HSM storage.

Parameters:: context (StartupContext)
Return type:: StartupStrategy

static select_version_strategy(context, app_version)[source]¶

Select the appropriate version management strategy.

Parameters:

context (StartupContext) – The startup context with version information.
app_version (management.models.AppVersion) – The AppVersion model instance.

Returns:

The appropriate StartupStrategy instance.

Raises:

RuntimeError – If version downgrade is detected.

Return type:

StartupStrategy

static select_startup_strategy(*, db_initialized, has_version, context=None, app_version=None)[source]¶

Select the top-level startup strategy.

Parameters:

db_initialized (bool) – Whether the database is initialized.
has_version (bool) – Whether an app version record exists.
context (StartupContext | None) – The startup context (required if db is initialized).
app_version (management.models.AppVersion | None) – The AppVersion model instance (required if db is initialized).

Returns:

The appropriate StartupStrategy instance.

Return type:

StartupStrategy