management.util.startup_strategies

Startup strategies for Trustpoint initialization and restoration.

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 handle_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.RecoverTlsCredentialStrategy[source]

Bases: TlsCredentialStrategy

Standard TLS credential generation using TlsServerCredentialGenerator.

handle_tls_credential(context)[source]

Recover TLS credentials from database and save to files.

Parameters:

context (StartupContext)

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]
handle_tls_credential(context)[source]

Generate TLS credentials and save to database and files.

Parameters:

context (StartupContext)

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:
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[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[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(tls_strategy=None)[source]

Bases: StartupStrategy

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

Parameters:

tls_strategy (TlsCredentialStrategy | None)

tls_strategy[source]
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

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

Bases: StartupStrategy

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

Parameters:

tls_strategy (TlsCredentialStrategy | None)

tls_strategy[source]
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

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 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