SCAutolib.controller

This module defines the Controller class, which serves as the central orchestrator for SCAutolib’s operations.

It bridges the gap between the CLI (View) or automated test scripts and the underlying Model components (like CAs, users, and cards). The Controller is responsible for high-level logic, including system preparation, CA configuration, user and smart card setup, and overall cleanup. It manages the flow of actions, validates configurations, and handles the persistence of critical object states.

Classes

class Controller(config=None, params=None)[source]

The Controller class acts as the central logic unit within SCAutolib, orchestrating complex workflows involving system setup, CA management, user creation, and smart card enrollment. It initializes and manages various model objects (e.g., Authselect, SSSDConf, CA’s, User’s, Card’s) and executes their methods in a coordinated manner to achieve desired system states for smart card testing.

Initializes the Controller, parsing and validating the input configuration file. If values are missing from the configuration, it checks if they are provided via CLI parameters. It also sets up necessary dump and backup directories and initializes related model objects (CAs) from previous runs if their dump files exist.

Parameters:

config (pathlib.Path or str, optional) – Path to the JSON configuration file containing metadata for testing setup.
params (dict, optional) – A dictionary of parameters typically originating from CLI arguments, used to supplement or override values from the configuration file.

Returns:

None

static _general_steps_for_ipa()[source]

Performs general system preparation steps for installing an IPA client. This includes enabling DNF modules for RHEL 8 and determining the correct IPA client package name based on the distribution.

Returns:: A list of strings, where each string is the name of an IPA client-related package to be installed.
Return type:: list

static _general_steps_for_virtual_sc()[source]

Performs general system preparation steps specifically for virtual smart cards. This involves configuring the pcscd service and opensc.module to ensure correct interaction with virtual cards. It also adds the virt_cacard COPR repository (for Fedora) and cleans SSSD caches.

Returns:: None

static _validate_configuration(conf, params=None)[source]

Validates the schema of the provided configuration dictionary against predefined schemas for CAs, users, and cards. It also accounts for CLI parameters that might override or supplement configuration file values.

Parameters:

conf (dict) – The configuration data, typically loaded from a JSON file, to be validated.
params (dict, optional) – A dictionary of parameters (e.g., from CLI arguments) that might provide missing values or override existing ones in the conf dictionary.

Returns:

A dictionary containing the validated and potentially adjusted configuration values.

Return type:

dict

Raises:

schema.SchemaError – If the configuration does not conform to the defined schemas.

cleanup()[source]

Cleans up all system configurations and changes made by SCAutolib’s prepare command. This includes restoring SSSD configuration, deleting created users (except ‘root’), removing smart cards and their associated directories, and cleaning up both local and IPA client CA setups. It also clears OpenSC and SSSD caches.

Returns:: None

property conf_path

Returns the absolute path to the configuration file loaded by the Controller.

Returns:: A pathlib.Path object representing the absolute path of the loaded configuration file.
Return type:: pathlib.Path

enroll_card(card)[source]

Enrolls a virtual smart card by generating a private key (if missing), requesting a certificate from the corresponding CA (local or IPA), and then uploading the key and certificate to the virtual card’s token. The card’s URI is also set during this process.

Parameters:: card (SCAutolib.models.card.VirtualCard) – The VirtualCard object to be enrolled.
Returns:: None
Raises:: SCAutolibException – If the card object is not properly initialized.

get_user_dict(name)[source]

Retrieves a user’s configuration dictionary from the loaded configuration file based on the provided username.

Parameters:: name (str) – The name of the user to search for in the configuration.
Returns:: A dictionary containing the user’s configuration details.
Return type:: dict
Raises:: SCAutolibMissingUserConfig – If a user with the specified name is not found in the configuration file.

init_ca(local=False)[source]

Initializes a Certificate Authority (CA) object based on its type (local or IPA). It loads the CA configuration from its respective dump file and ensures the CA certificate exists.

Parameters:: local (bool) – If True, a local CA is initialized. If False, an IPA server CA is initialized.
Returns:: None
Raises:: SCAutolibMissingCA – If the CA certificate is not found (for local CA) or if the IPA server CA is not installed (for IPA CA).

link_user_to_card(card)[source]

Links a Card object to its corresponding User object based on the cardholder attribute of the card. It iterates through the Controller’s loaded users to find a match.

Parameters:: card (SCAutolib.models.card.Card) – The Card object for which to find the associated user.
Returns:: The User object that matches the card’s cardholder.
Return type:: SCAutolib.models.user.User

prepare(force, gdm, install_missing, graphical)[source]

Prepares the entire system for smart card testing based on the loaded configuration and provided CLI options. This method orchestrates the complex configuration of the system under test, including setting up Certificate Authorities (CAs), creating users, and configuring smart cards.

Parameters:

force (bool) – If True, existing objects, files, users, or services will be erased or overwritten if they already exist. Its exact meaning can vary slightly for different internal methods.
install_missing (bool) – If True, all detected missing prerequisite packages will be automatically installed.
gdm (bool) – If True, the GDM (GNOME Display Manager) package will be installed as part of system preparation.
graphical (bool) – If True, dependencies specifically required for GUI testing will be installed.

Returns:

None

Raises:

SCAutolibWrongConfig – If a required CA section is missing in the configuration.

prepare_softhsm_config(card_dir=None)[source]

Prepares the softhsm2.conf file specifically for a virtual card. This involves creating the configuration file based on a template and saving it in the specified card directory.

Parameters:: card_dir (pathlib.Path, optional) – The pathlib.Path object to the directory where the softhsm2.conf file should be saved.
Returns:: An initialized SoftHSM2Conf object.
Return type:: SCAutolib.models.file.SoftHSM2Conf

prepare_user_cnf(card)[source]

Prepares an OpenSSL configuration file ({cardholder}.cnf) specifically for a virtual card’s user. This CNF file is used for generating Certificate Signing Requests (CSRs) for the user’s certificate.

Parameters:: card (SCAutolib.models.card.VirtualCard) – The VirtualCard object for which to prepare the user CNF.
Returns:: The pathlib.Path object to the created user OpenSSL CNF file.
Return type:: pathlib.Path

revoke_certs(card)[source]

Revokes the certificate associated with a virtual card. The revocation is performed by the appropriate Certificate Authority (local or IPA) based on the user’s type.

Parameters:: card (SCAutolib.models.card.VirtualCard) – The VirtualCard object whose certificate needs to be revoked.
Returns:: None

setup_card(card_dict, force=False)[source]

Creates and initializes a Card object (either PhysicalCard or VirtualCard) based on the provided card dictionary. For virtual cards, this includes preparing SoftHSM2 configuration and OpenSSL CNF files, linking the card to its user, and creating the SoftHSM2 token and virt_cacard systemd service.

Parameters:

card_dict (dict) – A dictionary containing the attributes of the card to be created, such as ‘name’, ‘pin’, ‘card_type’, etc.
force (bool) – If True, and the card’s directory already exists, it will be removed before creating the new card. For virtual cards, it also triggers revocation of existing certificates.

Returns:

The created Card object.

Return type:

SCAutolib.models.card.Card

Raises:

NotImplementedError – If a card type other than ‘physical’ or ‘virtual’ is specified.

setup_custom_ca(card_data)[source]

Sets up a custom Certificate Authority (CA) based on provided card data. This is typically used for physical cards where root CA certificates might be provided externally and cannot be changed (like precreated physical cards). It creates the CA object, performs its setup, and then dumps its state to a JSON file.

Parameters:: card_data (dict) – A dictionary containing details about the card, which includes information about its associated CA.
Returns:: None
Raises:: FileNotFoundError – If the CA certificate file is not found after setup.

setup_graphical(install_missing, gdm)[source]

Configures the system specifically for GUI testing. This involves installing necessary graphical user interface (GUI) packages and ensuring the environment is ready for GUI automation.

Parameters:

install_missing (bool) – If True, all detected missing prerequisite packages will be automatically installed.
gdm (bool) – If True, the GDM (GNOME Display Manager) package will be installed as part of system preparation.

Returns:

None

Raises:

SCAutolibException – If required packages are missing and install_missing is False.

setup_ipa_client(force=False)[source]

Configures an IPA (Identity Management for Linux) client on the current host to communicate with a given IPA server. The IPA server is expected to be already operational. If an IPA client is already installed, it can be optionally removed before reconfiguration.

Parameters:: force (bool) – If True and an IPA Client is already configured, the existing installation will be uninstalled before setting up the new client.
Returns:: None
Raises:: SCAutolibWrongConfig – If the ‘ipa’ section is not found in the configuration file.

setup_local_ca(force=False)[source]

Configures a local Certificate Authority (CA) based on the settings from the configuration file. It ensures the necessary directory and file structures are created and the CA’s self-signed root certificate is generated. It also updates the system’s sssd_auth_ca_db.pem with the CA’s certificate.

Parameters:: force (bool) – If True, any existing local CA in the specified directory will be removed before creating the new one.
Returns:: None
Raises:: SCAutolibWrongConfig – If the ‘local_ca’ section is not found in the configuration file.

setup_system(install_missing, gdm, graphical)[source]

Performs general system setup, including the installation of necessary packages, SSSD configuration, and specific configurations for virtual smart cards based on the requirements defined in the configuration file.

Parameters:

install_missing (bool) – If True, all detected missing prerequisite packages will be automatically installed.
gdm (bool) – If True, the GDM (GNOME Display Manager) package will be installed as part of system preparation.
graphical (bool) – If True, dependencies specifically required for GUI testing will be installed.

Returns:

None

Raises:

SCAutolibException – If required packages are missing and install_missing is False.

setup_user(user_dict, force=False)[source]

Configures a user on the specified system (either a local machine or an IPA server) based on the provided user dictionary.

Parameters:

user_dict (dict) – A dictionary containing the user’s attributes such as ‘name’, ‘passwd’, and ‘user_type’.
force (bool) – If True, the user (and associated card directory if applicable) will be re-created, deleting any existing user with the same name.

Returns:

The created or configured User object.

Return type:

SCAutolib.models.user.User

Raises:

SCAutolibException – If an IPA user is to be configured but no IPA client is currently configured on the system.