SCAutolib.models.CA

This module implements classes that represent Certificate Authorities (CA) within the SCAutolib framework. It provides a foundational BaseCA class and specialized subclasses for LocalCA (local OpenSSL-based CAs), CustomCA (for physical cards), and IPAServerCA (for FreeIPA integrated CAs). These classes encapsulate CA-specific attributes and methods for operations such as certificate requests, signing, revocation, and managing the system’s CA trust store (sssd_auth_ca_db.pem).

Classes

class BaseCA[source]

A foundational class serving as an interface and base implementation for different types of Certificate Authorities (CAs) within SCAutolib. It defines common properties like certificate and key paths, and provides shared methods for CA-related operations, especially managing the file used by the System Security Services Daemon (SSSD) to store a list of Certificate Authority (CA) certificates (sssd_auth_ca_db.pem).

property cert

Returns the path to the CA’s certificate file.

Returns:: A pathlib.Path object pointing to the CA certificate.
Return type:: pathlib.Path

static load(json_file)[source]

Loads a CA object from a JSON file. It reads the JSON content, determines the CA type, and then instantiates the appropriate CA subclass with the loaded attributes.

Parameters:: json_file (pathlib.Path) – The pathlib.Path object pointing to the JSON file containing the serialized CA data.
Returns:: An instance of the specific CA class loaded with data from the JSON file.
Return type:: SCAutolib.models.CA.BaseCA
Raises:: SCAutolibException – If the CA object has an unknown type in the JSON file, or if the data is invalid for IPA CA initialization.

request_cert(csr, username, cert_out)[source]

Requests a certificate from the CA for a given username using a CSR (Certificate Signing Request). The signed certificate is then duplicated to the specified output path. This method is a placeholder in BaseCA and its implementation varies depending on the specific CA type (e.g., local, IPA).

Parameters:

csr (str) – The path to the CSR file.
username (str) – The subject name for the certificate.
cert_out (pathlib.Path) – The path where the signed certificate should be stored.

Returns:

The path where the certificate is stored.

Return type:

pathlib.Path

restore_ca_db()[source]

Restores the sssd_auth_ca_db.pem file to its state before it was modified by this CA object. It uses the backed-up original file for restoration. If no backup exists, it will simply remove the current sssd_auth_ca_db.pem if it’s present.

Returns:: None
Return type:: None

revoke_cert(cert)[source]

Revokes a given certificate. This method is a placeholder in BaseCA and its implementation varies depending on the specific CA type (e.g., local, IPA).

Parameters:: cert (pathlib.Path) – The pathlib.Path object to the certificate to be revoked.
Returns:: None
Return type:: None

setup()[source]

Configures the Certificate Authority. This method is a placeholder in BaseCA and its implementation varies depending on the specific CA type (e.g., local, IPA).

Returns:: None
Return type:: None

sign_cert()[source]

Signs a certificate. This method is a placeholder in BaseCA and its implementation varies depending on the specific CA type (e.g., local, IPA).

Returns:: None
Return type:: None

update_ca_db()[source]

Updates the system’s sssd_auth_ca_db.pem file with the CA’s certificate defined in this CA object. It backs up the original sssd_auth_ca_db.pem if it exists and ensures the CA certificate is added if not already present. SELinux context is restored on the database file after modification.

Returns:: None
Return type:: None

class CustomCA(card)[source]

Represents a custom Certificate Authority (CA), typically used for physical smart cards which might have pre-existing or read-only root CA certificates. This class provides methods for integrating such external CA certificates into the system.

TODO:: As of the provided code, this class is noted as not yet fully

tested or functional.

Initializes a CustomCA object from provided card data. It sets up the CA’s name, certificate path, and dump file location based on the card’s information.

Parameters:: card_data (dict) – A dictionary containing details about the card, including the CA’s name and certificate data (e.g., card["ca_name"], card["ca_cert"]).
Returns:: None
Return type:: None

setup()[source]

Sets up the CustomCA by creating its root directory and copying the provided CA certificate content into a PEM file within that directory.

Returns:: None
Return type:: None
Raises:: SCAutolibException – If the CA certificate content is not provided in self.ca_cert.

to_dict()[source]

Customizes the serialization of the CustomCA object to a dictionary format suitable for JSON storage. It converts pathlib.Path objects to their string representations.

Returns:: A dictionary containing all serializable attributes of the CustomCA instance.
Return type:: dict

class IPAServerCA(ip_addr, server_hostname, domain, admin_passwd, root_passwd, client_hostname, realm=None)[source]

Represents an IPA (Identity Management for Linux) server with its integrated Certificate Authority. This class facilitates communication with the IPA server, primarily using python_freeipa.client_meta.ClientMeta for administrative tasks. It handles IPA client setup on the current system for smart card authentication, including fetching and executing the necessary setup scripts from the IPA server.

Initializes an IPAServerCA object, setting up attributes for the IPA server and client. It also performs initial network configurations (adding to /etc/hosts) and establishes a logged-in ClientMeta instance for API interactions.

Parameters:

ip_addr (str) – The IP address of the IPA server.
server_hostname (str) – The hostname of the IPA server.
domain (str) – The domain name of the IPA server.
admin_passwd (str) – The password for the IPA admin user.
root_passwd (str) – The root user password on the IPA server (for SSH access to fetch scripts).
client_hostname (str) – The desired hostname for the client system that will be joined to IPA.
realm (str, optional) – The Kerberos realm. If None, the domain in uppercase will be used as the realm.

Returns:

None

Return type:

None

_add_to_hosts()[source]

Adds the IPA server’s IP address and hostname to the /etc/hosts file if the entry does not already exist.

Returns:: None
Return type:: None

_add_to_resolv()[source]

Adds the IPA server’s IP address as the primary nameserver in /etc/resolv.conf. It checks if the nameserver is already present to avoid duplication.

Returns:: None
Return type:: None

_get_sc_setup_script()[source]

Fetches the smart card setup script for IPA client from the IPA server via SSH. This script is generated on the server-side and is then saved to a predefined local path for execution. It authenticates to the IPA server as admin and then as root via SSH.

Returns:: None
Return type:: None
Raises:: SCAutolibException – If the script is not correctly copied or if SSH connection/command execution fails.

_meta_client_login()[source]

Establishes a connection and logs in to the IPA server as the admin user using python_freeipa.client_meta.ClientMeta. The connection does not use SSL verification.

Returns:: None
Return type:: None

_set_hostname()[source]

Sets the hostname of the current system to the specified IPA client hostname using hostnamectl.

Returns:: None
Return type:: None

add_user(user)[source]

Adds a given user to the IPA server. This method wraps the python_freeipa.client_meta.ClientMeta.user_add function, extracting necessary user fields for the IPA API call. For simplicity, givenname, uid, sn, and cn are set to the username.

Parameters:: user_obj (SCAutolib.models.user.User) – The user object to be added to the IPA server. Expected to have username and password attributes.
Returns:: None
Return type:: None

cleanup()[source]

Removes the IPA client from the system and also attempts to remove the corresponding host entry from the IPA server. It executes the ipa-client-install --uninstall command on the client.

Returns:: None
Return type:: None
Raises:: subprocess.CalledProcessError – If ipa-client-install --uninstall fails with an unexpected return code.

del_user(user)[source]

Removes a user from the IPA server. This method wraps the python_freeipa.client_meta.ClientMeta.user_del function.

Parameters:: user_obj (SCAutolib.models.user.User) – The user object to be deleted from the IPA server. Expected to have a username attribute.
Returns:: None
Return type:: None

property domain

Returns the domain name of the IPA server.

Returns:: The IPA server’s domain as a string.
Return type:: str

property ipa_server_hostname

Returns the hostname of the IPA server this object is configured to interact with.

Returns:: The IPA server’s hostname as a string.
Return type:: str

property is_installed

Checks if the IPA client is installed on the current system. This is determined by the existence of the /etc/ipa directory and the ca.crt file within it, which is provided by the IPA server.

Returns:: True if the IPA client is detected as installed; False otherwise.
Return type:: bool

request_cert(csr, username, cert_out)[source]

Requests a certificate from the IPA CA for a given username using a CSR (Certificate Signing Request). This method wraps the python_freeipa.client_meta.ClientMeta.cert_request function, extracts the certificate from the response, and saves it in PEM format to the specified output path.

Parameters:

csr (pathlib.Path) – The pathlib.Path object to the CSR file.
username (str) – The principal (subject) name for the certificate.
cert_out (pathlib.Path) – The pathlib.Path object where the certificate should be stored. Can be a directory or a file. If it is directory then the file will be saved there with name <username>.pem. If it’s a file without a .pem extension, .pem will be appended.

Returns:

A pathlib.Path object to the location of the PEM certificate file.

Return type:

pathlib.Path

revoke_cert(cert_path)[source]

Revokes a given certificate on the IPA server. This method wraps the python_freeipa.client_meta.ClientMeta.cert_revoke function and extracts the serial number of the certificate from the provided PEM file for revocation.

Parameters:: cert_path (pathlib.Path) – The pathlib.Path object to the certificate file in PEM format to be revoked.
Returns:: The serial number of the revoked certificate.
Return type:: int

setup()[source]

Configures the IPA client on the current host to join the IPA server. This involves setting up /etc/resolv.conf, setting the hostname, installing the IPA client package, and running a specific script (fetched from the IPA server) to configure smart card login with IPA. It also adjusts the IPA’s global password policy.

Returns:: None
Return type:: None
Raises:: Exception – If the IPA client installation fails.

to_dict()[source]

Customizes the serialization of the IPAServerCA object to a dictionary format suitable for JSON storage. It excludes the meta_client attribute as it is not serializable.

Returns:: A dictionary containing all serializable attributes of the IPAServerCA instance.
Return type:: dict

class LocalCA(root_dir=None, cnf=None)[source]

Represents a local Certificate Authority (CA) that is created and managed directly on the system, typically used as a CA for virtual smart cards. It extends BaseCA and provides specific implementations for setting up the CA’s directory structure, generating self-signed certificates, and managing CRLs (Certificate Revocation Lists) using OpenSSL.

Initializes a LocalCA object. It sets up paths for the CA’s root directory, configuration files, certificate, and key, but the actual file system setup is performed by the setup() method.

Parameters:

root_dir (pathlib.Path, optional) – The pathlib.Path object to the root directory where the CA files will be stored. Defaults to /etc/SCAutolib/ca.
cnf (SCAutolib.models.file.OpensslCnf, optional) – An OpensslCnf object representing the OpenSSL CNF file used for the CA.

Returns:

None

Return type:

None

Raises:

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

cleanup()[source]

Removes the entire root directory of the local CA, including all its generated files, certificates, and keys. It also deletes the associated JSON dump file.

Returns:: None
Return type:: None

property cnf

Returns the OpenSSL CNF object associated with this local CA.

Returns:: An OpensslCnf object.
Return type:: SCAutolib.models.file.OpensslCnf

property is_installed

Checks if the local CA is fully installed on the system. This involves verifying the existence of the root directory, CA certificate, private key, CNF file, and other required files, as well as checking if the CA certificate is present in sssd_auth_ca_db.pem.

Returns:: True if the local CA is completely installed and configured; False otherwise.
Return type:: bool

request_cert(csr, username, cert_out=None)[source]

Creates and signs a certificate from a given CSR (Certificate Signing Request) using the local CA’s private key. The signed certificate is stored in a predefined location (e.g., <root ca directory>/certs/<username>.pem) or a specified output path.

Parameters:

csr (pathlib.Path) – The pathlib.Path object pointing to the CSR file.
username (str) – The subject name to be included in the certificate.
cert_out (pathlib.Path, optional) – An optional pathlib.Path object specifying where the signed certificate should be copied. It can be a directory or a file. If a file, .pem extension is ensured. If None, the certificate is created in the default directory.

Returns:

The pathlib.Path object to the location of the signed certificate.

Return type:

pathlib.Path

revoke_cert(cert)[source]

Revokes a given certificate using the local CA. It updates the CA’s CRL (Certificate Revocation List) after revocation.

Parameters:: cert (pathlib.Path) – The pathlib.Path object to the certificate file to be revoked.
Returns:: None
Return type:: None

setup()[source]

Configures the local CA by creating its required directory and file structure. It generates a self-signed root certificate and private key using OpenSSL, and initializes the CRL (Certificate Revocation List).

Returns:: None
Return type:: None
Raises:: SCAutolibException – If the CA’s CNF file is not set or does not exist.

to_dict()[source]

Customizes the serialization of the LocalCA object to a dictionary format suitable for storing as JSON. It converts pathlib.Path objects to strings.

Returns:: A dictionary containing all serializable attributes of the LocalCA instance.
Return type:: dict