SCAutolib.models.card

This module implements classes for interacting with different types of smart cards used within the SCAutolib library. These include VirtualCard (software-emulated smart cards), PhysicalCard (real smart cards in standard readers), and potentially cards connected via specialized hardware like Removinator. The module provides a common Card interface and specialized methods for operations like inserting/removing cards, and enrolling (uploading keys and certificates).

Classes

class Card[source]

An interface class for different types of smart cards. It defines common attributes and abstract methods that child classes are expected to implement based on the specific card type. It also includes a static method for loading card objects from JSON dump files.

_set_uri()[source]

Sets the URI for the given smart card by matching it from the output of the p11tool --list-token-urls command using a regular expression (self._pattern). An exception is raised if no URI is matched, or if multiple URIs are found.

Returns:: None
Return type:: None
Raises:: SCAutolibException – If a matching URI is not found or if multiple matching URIs are detected.

enroll()[source]

Enrolls the card, typically by uploading a certificate and a key onto it. This is an abstract method that must be implemented by concrete card type subclasses.

Returns:: None
Return type:: None

insert()[source]

Inserts the smart card. This is an abstract method that must be implemented by concrete card type subclasses.

Returns:: None
Return type:: None

static load(json_file)[source]

Loads a Card object from a specified JSON dump file. It reads the JSON content, determines the card type, and then instantiates the appropriate card subclass with the loaded data.

Parameters:: json_file (pathlib.Path) – The pathlib.Path object pointing to the JSON file containing the serialized card data.
Returns:: An instance of the specific card class loaded with data from the JSON file.
Return type:: SCAutolib.models.card.Card
Raises:: SCAutolibException – If an unknown card type is encountered in the JSON data.

remove()[source]

Removes the smart card. This is an abstract method that must be implemented by concrete card type subclasses.

Returns:: None
Return type:: None

class PhysicalCard(card_data=None, card_dir=None)[source]

Represents a physical smart card. This class is intended to provide methods for manipulating physical cards, potentially connected via specialized hardware like a Removinator.

Note: As of the provided code, this class is noted as ‘Work In Progress’ and not yet fully tested. Needs to be implemented with removinator.

Initializes a PhysicalCard object. It sets up card attributes based on provided data and verifies the card’s root directory exists.

Parameters:

card_data (dict, optional) – A dictionary containing details about the physical card.
card_dir (pathlib.Path, optional) – The pathlib.Path object to the card’s root directory.

Returns:

None

Return type:

None

Raises:

FileNotFoundError – If the specified card_dir does not exist upon initialization.

insert()[source]

Inserts the physical card. Note: This method is a placeholder and needs to be implemented to interact with Removinator.

Returns:: None
Return type:: None

remove()[source]

Removes the physical card. Note: This method is a placeholder and needs to be implemented to interact with Removinator.

Returns:: None
Return type:: None

to_dict()[source]

Converts the PhysicalCard object’s attributes into a dictionary suitable for JSON serialization.

Returns:: A dictionary representation of the physical card object’s attributes.
Return type:: dict

property user

Returns the cardholder’s username associated with this physical card.

Returns:: The cardholder’s username.
Return type:: str

class VirtualCard(card_data, softhsm2_conf=None, card_dir=None, key=None, cert=None)[source]

Represents a virtual smart card, which is implemented as a systemd service on the system. This class provides methods for managing the lifecycle of a virtual smart card, including its creation, insertion (starting the service), removal (stopping the service), and enrollment (uploading keys and certificates to its NSS database via SoftHSM2). It is designed to be used as a context manager.

Initializes a VirtualCard object. It sets up card-specific attributes and paths for its files, service, and NSS database. The card’s root directory must exist prior to calling any methods that interact with it.

Parameters:

card_data (dict) – A dictionary containing details about the card, such as pin, cardholder, name, etc.
softhsm2_conf (pathlib.Path, optional) – The pathlib.Path object to the SoftHSM2 configuration file used by this virtual card.
card_dir (pathlib.Path, optional) – The pathlib.Path object to the card’s root directory where its files will be saved.
key (pathlib.Path, optional) – The pathlib.Path object to the private key file. If it exists, it will be used with the card.
cert (pathlib.Path, optional) – The pathlib.Path object to the certificate file. If it exists, it will be used with the card.

Returns:

None

Return type:

None

Raises:

FileNotFoundError – If the specified card_dir does not exist upon initialization.

create()[source]

Creates the necessary components for a virtual smart card, including initializing a SoftHSM2 token, setting up its NSS database, and creating the corresponding systemd service file.

Returns:: The VirtualCard instance.
Return type:: SCAutolib.models.card.VirtualCard
Raises:: FileNotFoundError – If the SoftHSM2 configuration file is not found.

delete()[source]

Deletes the virtual card, including its dedicated directory (which contains certificates, SoftHSM2 token data, and NSS database), and removes its systemd service file.

Returns:: None
Return type:: None

enroll()[source]

Uploads a certificate and private key to the virtual smart card’s internal NSS database via pkcs11-tool and SoftHSM2. After enrollment, the card is temporarily inserted to set its URI.

Returns:: None
Return type:: None

gen_csr()[source]

Generates a user-specific CSR (Certificate Signing Request) file using OpenSSL, based on a template CNF file and the user’s private key. This CSR is then sent to a CA for certificate generation.

Returns:: The pathlib.Path object to the generated CSR file.
Return type:: pathlib.Path
Raises:: SCAutolibException – If the private key is not set when attempting to generate a CSR for an IPA user.

insert()[source]

Inserts the virtual smart card by starting its corresponding systemd service. A short delay is included to prevent errors with fast service restarts.

Returns:: The subprocess.CompletedProcess object from the systemctl command.
Return type:: subprocess.CompletedProcess

remove()[source]

Removes the virtual smart card by stopping its systemd service. A short delay is included to prevent errors with fast service restarts.

Returns:: The subprocess.CompletedProcess object from the systemctl command.
Return type:: subprocess.CompletedProcess

property service_location

Returns the pathlib.Path object to the systemd service file location for this virtual smart card.

Returns:: The service file path.
Return type:: pathlib.Path

property softhsm2_conf

Returns the path to the SoftHSM2 configuration file used by this virtual card.

Returns:: A pathlib.Path object to the SoftHSM2 configuration file.
Return type:: pathlib.Path

to_dict()[source]

Converts the VirtualCard object’s attributes into a dictionary suitable for JSON serialization. It converts pathlib.Path objects to string representations for compatibility.

Returns:: A dictionary representation of the virtual card object’s attributes.
Return type:: dict