Crate signstar_host 

Signstar Host

Libraries and executables for Signstar hosts.

A Signstar host is a Linux host, that has several regular users configured, which allow access to specific credentials on an HSM backend.

Documentation

• https://signstar.archlinux.page/rustdoc/signstar_host/ for development version of the crate
• https://docs.rs/signstar-host/latest/signstar_host/ for released versions of the crate

Executables

Several executables are available with the cli feature.

Unless noted otherwise, none of them take any arguments or input and only allow for their verbosity level to be adjusted.

signstar-configure

The executable signstar-configure configures a Signstar host during runtime.

It relies on the system’s Signstar configuration file to handle and optionally configure the administrative credentials which are then used to configure

• the available HSM backends (e.g. NetHSM and/or YubiHSM2)
• the specific backend credentials for real users on the host

The executable is meant to be run as root on a Signstar host in regular intervals:

signstar-configure

For this purpose, a systemd service and timer unit (see systemd.service and systemd.timer, respectively) are made available in the resources/systemd/ directory.

signstar-configure-build

The executable signstar-configure-build configures a Signstar system during build of an image for a Signstar host.

It relies on the system’s Signstar configuration file to create system users and their integration.

Based on configured user mappings in the configuration file, signstar-configure-build:

• creates unlocked system users
  • with a random passphrase
  • with a home directory below /var/lib/signstar/home/ (but without creating it)
• adds tmpfiles.d integration for each user, so that their home directory is created automatically
• adds a dedicated authorized_keys file and sshd_config drop-in configuration, which defines a ForceCommand option to enforce specific commands for each configured user with SSH access

The executable is meant to be run as root during build of an image for a Signstar host:

signstar-configure-build

signstar-download-key-certificates

The executable signstar-download-key-certificates returns key certificates stored in HSM backends of a Signstar host.

Currently, only OpenPGP certificates are returned. However, the response format is designed with extensibility in mind and other technologies can be integrated in the future.

The executable is meant to be run as a non-root user, which is setup for access to all key certificates in an HSM backend:

signstar-download-key-certificates | jq --raw-output '.certs[0]'

signstar-sign

The executable signstar-sign accepts a signing request and returns a signing response for it using HSM backends of a Signstar host.

A signing response contains digital signatures in protocol-specific framing.

Currently, only OpenPGP signatures are supported. However, both the signing request and signing response format are designed with extensibility in mind and other technologies can be integrated in the future.

The executable is meant to be run as a non-root user, which is setup for access to a single signing key in an HSM backend:

signstar-sign < ../fixtures/request/sample-request.json | jq --raw-output .signature | rsop dearmor | rpacket dump

The above example takes a JSON signing request, and produces a JSON signing response. Here, the response’s signature field contains an armored OpenPGP signature, which is de-armored and then inspected.

Examples

Library

The crate can be used as a library as well.

signstar_host::configure

Synchronization of backends depends on the system’s Signstar configuration file, the available HSM backends and administrative credentials.

use signstar_host::configure::HostConfiguration;
use signstar_config::config::Config;

// NOTE: You can rely on the `signstar_configure::load_config` helper function to load the system's Signstar config.
let config = Config::from_file_path("../fixtures/config/yubihsm2_mockhsm_backend/admin-plaintext-non-admin-plaintext.yaml")?;
let backend = HostConfiguration::new(&config);
backend.sync()?;;

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.
• _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.
• nethsm: Enables support for the NetHSM backend (default).
• yubihsm2: Enables support for the YubiHSM2 backend (default)

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.

Modules

config

Configuration handling.

configure

Configuration of Signstar hosts during runtime.

configure_build

Configuration of Signstar hosts during image build time.

download_key_certificates

Retrieval of key certificates from Signstar hosts.

error 🔒

Error handling.

sign

Retrieval of signatures for signing requests on Signstar hosts.

Enums

Error

An error that may occur when using Signstar hosts.