Crate signstar_config

Expand description

§Signstar config

Configuration file handling for Signstar hosts.

§Documentation

https://signstar.archlinux.page/rustdoc/signstar_config/ for development version of the crate
https://docs.rs/signstar_config/latest/signstar_config/ for released versions of the crate

§Examples

§Administrative credentials

Administrative credentials on a Signstar host describe all required secrets to unlock, backup, restore and fully provision a NetHSM backend. They can be used from plaintext and systemd-creds encrypted files. Functions for interacting with configurations in default locations must be called by root.

§NetHSM

use signstar_config::{AdminCredentials, NetHsmAdminCredentials};
use signstar_crypto::AdministrativeSecretHandling;

// Load from plaintext file in default location
let creds = NetHsmAdminCredentials::load(AdministrativeSecretHandling::Plaintext)?;

// Load from systemd-creds encrypted file in default location
let creds = NetHsmAdminCredentials::load(AdministrativeSecretHandling::SystemdCreds)?;

// Store in plaintext file in default location
creds.store(AdministrativeSecretHandling::Plaintext)?;

// Store in systemd-creds encrypted file in default location
creds.store(AdministrativeSecretHandling::SystemdCreds)?;

§YubiHSM2

use signstar_config::{AdminCredentials, yubihsm2::admin_credentials::YubiHsm2AdminCredentials};
use signstar_crypto::AdministrativeSecretHandling;

// Load from plaintext file in default location
let creds = YubiHsm2AdminCredentials::load(AdministrativeSecretHandling::Plaintext)?;

// Load from systemd-creds encrypted file in default location
let creds = YubiHsm2AdminCredentials::load(AdministrativeSecretHandling::SystemdCreds)?;

// Store in plaintext file in default location
creds.store(AdministrativeSecretHandling::Plaintext)?;

// Store in systemd-creds encrypted file in default location
creds.store(AdministrativeSecretHandling::SystemdCreds)?;

§Creating secrets for non-administrative credentials

Non-administrative credentials on a Signstar host provide access to non-administrative users on a backend. They can be used in plaintext and systemd-creds encrypted files.

Assuming, that a Signstar configuration is present on the host, it is possible to create secrets for each backend user assigned to any of the configured system users. Functions for the creation of secrets must be called by root.

NOTE: For the creation of system users based on a Signstar config refer to signstar-configure-build.

use signstar_config::{
    config::{Config, UserBackendConnection, UserBackendConnectionFilter},
};
use signstar_crypto::AdministrativeSecretHandling;

// Load Signstar config from one of the default system locations.
let config = Config::from_system_path()?;

// Get the user backend connections for all non-administrative users.
let user_backend_connections = config.user_backend_connections(UserBackendConnectionFilter::NonAdmin);

// Create secrets for each system user and their backend users.
for user_backend_connection in user_backend_connections.iter() {
    user_backend_connection.create_non_admin_backend_user_secrets()?;
}

§Loading secrets for non-administrative users

Depending on user mapping in the Signstar config, a system user may have one or more NetHSM backend users assigned to it. The credentials for each NetHSM backend user can be loaded by each configured system user. Functions for the loading of secrets must be called by the system user that is assigned that particular secret.

use signstar_config::config::{Config, NonAdminBackendUserIdFilter, NonAdminBackendUserIdKind};

// Load Signstar config from one of the default system locations.
let config = Config::from_system_path()?;
// Get the user backend connection for the Unix user named "test".
let Some(user_backend_connection) = config.user_backend_connection(&"test".parse()?) else {
  panic!("No Unix user of that name is configured for any of the available backends.")
};

// Assuming the selected Unix user is supposed to be used for signing, get the credentials for its assigned user in the backend.
let credentials = user_backend_connection.load_non_admin_backend_user_secrets(NonAdminBackendUserIdFilter{ backend_user_id_kind: NonAdminBackendUserIdKind::Signing })?;

§Features

_containerized-integration-test: Integration tests that require a containerized test environment. NOTE: Unless you are developing this crate, you will very likely not want to use this feature.
_nethsm-integration-test: Integration tests that require a containerized NetHSM environment. NOTE: Unless you are developing this crate, you will very likely not want to use this feature.
_test-helpers: Enables the signstar_config::test module which provides utilities for test setups that may also be useful for other crates. NOTE: Unless you are developing this crate, you will very likely not want to use this feature.
_yubihsm2-mockhsm: Test environment and integration using a virtual YubiHSM2. NOTE: Unless you are developing this crate, you will very likely not want to use this feature. WARNING: This feature requires building in debug mode (see signstar#288)!
nethsm: Enables support for the NetHSM backend.
yubihsm2: Enables support for the YubiHSM2 backend.

§Contributing

Please refer to the contributing guidelines to learn how to contribute to this project.

§License

This project may be used under the terms of the Apache-2.0 or MIT license.

Changes to this project - unless stated otherwise - automatically fall under the terms of both of the aforementioned licenses.

Re-exports§

pub use admin_credentials::AdminCredentials;
pub use config::credentials::AuthorizedKeyEntry;
pub use config::credentials::SystemUserId;
pub use config::error::Error as ConfigError;
pub use error::Error;
pub use error::ErrorExitCode;
pub use nethsm::FilterUserKeys;
pub use nethsm::NetHsmMetricsUsers;
pub use nethsm::admin_credentials::NetHsmAdminCredentials;
pub use nethsm::backend::NetHsmBackend;
pub use nethsm::error::Error as NetHsmBackendError;

Modules§

admin_credentials: Administrative credentials handling for an HSM backend.
config: Configuration file handling for Signstar hosts.
error: Common, top-level error type for all components of signstar-config.
nethsm: Handling of users and keys in a NetHSM backend.
state: State handling and comparison.
test: Utilities used for test setups.
utils: Utilities for signstar-config.
yubihsm2: Handling of users and keys in a YubiHSM2 backend.