signstar_yubihsm2/automation/
command.rs

1//! Scenario commands.
2
3use std::path::PathBuf;
4
5#[cfg(feature = "serde")]
6use serde::{Deserialize, Serialize};
7use yubihsm::command::Code;
8
9use crate::object::{Capabilities, Id, KeyInfo, ObjectId};
10
11/// Authentication data: login and a location of the passphrase file.
12#[derive(Debug)]
13#[cfg_attr(feature = "serde", derive(Deserialize, Serialize))]
14pub struct Auth {
15    /// The identifier of the authentication key to use.
16    pub user: Id,
17
18    /// The file containing passphrase of the authenticating user.
19    pub passphrase_file: PathBuf,
20}
21
22/// Indicates the setting of the auditing.
23#[derive(Clone, Copy, Debug)]
24#[cfg_attr(feature = "serde", derive(Deserialize, Serialize))]
25#[cfg_attr(feature = "serde", serde(rename_all = "lowercase"))]
26pub enum AuditOption {
27    /// Auditing is enabled but can be disabled.
28    On,
29
30    /// Auditing is disabled.
31    Off,
32
33    /// Auditing is permanently enabled and cannot be disabled.
34    Fix,
35}
36
37impl From<AuditOption> for yubihsm::AuditOption {
38    fn from(value: AuditOption) -> Self {
39        match value {
40            AuditOption::On => Self::On,
41            AuditOption::Off => Self::Off,
42            AuditOption::Fix => Self::Fix,
43        }
44    }
45}
46
47/// A single command that is atomically executed against a YubiHSM2.
48#[derive(Debug)]
49#[cfg_attr(feature = "serde", derive(Deserialize, Serialize))]
50pub enum Command {
51    /// Query the device state.
52    Info,
53
54    /// Reset the device to factory settings and reconnect afterwards.
55    ///
56    /// Note that this is a destructive operation and the authenticating user will need to have
57    /// appropriate capabilities.
58    Reset,
59
60    /// Query the command log of the device and print it to standard output.
61    GetLog,
62
63    /// Authenticate against the device.
64    ///
65    /// This command *must* be used as a first command in the scenario file as it is not possible to
66    /// connect to the device without any credentials.
67    Auth(Auth),
68
69    /// Change audit settings.
70    ///
71    /// This mode prevents the device from performing additional operations when the Logs and Error
72    /// Codes is full.
73    ///
74    /// See [Force Audit](https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-core-concepts.html#force-audit) for more details.
75    ForceAudit(AuditOption),
76
77    /// Changes command audit settings.
78    ///
79    /// This is used to manage auditing options for specific commands. By default all commands are
80    /// logged.
81    ///
82    /// See [Force Audit](https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-core-concepts.html#command-audit) for more details.
83    #[allow(clippy::enum_variant_names)]
84    CommandAudit {
85        /// Command of which the setting should be changed.
86        command: Code,
87
88        /// New setting value.
89        setting: AuditOption,
90    },
91
92    /// Put authentication key on the device.
93    ///
94    /// This command is used to append new authentication keys.
95    PutAuthKey {
96        /// The key identity and capabilities.
97        #[cfg_attr(feature = "serde", serde(flatten))]
98        info: KeyInfo,
99
100        /// Additional delegated capabilities which would apply to objects that are created or
101        /// imported.
102        delegated_caps: Capabilities,
103
104        /// The file containing passphrase of the authenticating user.
105        passphrase_file: PathBuf,
106    },
107
108    /// Generates new `ed25519` signing key on the device.
109    GenerateKey {
110        /// The key identity and capabilities.
111        #[cfg_attr(feature = "serde", serde(flatten))]
112        info: KeyInfo,
113    },
114
115    /// Signs data using provided `ed25519` key.
116    SignEd25519 {
117        /// The key to be used for signing.
118        key_id: Id,
119
120        /// Raw data blob which should be signed.
121        data: Vec<u8>,
122    },
123
124    /// Puts new wrapping key on the device.
125    ///
126    /// This command is used to append new wrapping keys which serve as encryption keys for other
127    /// objects.
128    PutWrapKey {
129        /// The key identity and capabilities.
130        #[cfg_attr(feature = "serde", serde(flatten))]
131        info: KeyInfo,
132
133        /// Additional delegated capabilities which would apply to objects that are created or
134        /// imported.
135        delegated_caps: Capabilities,
136
137        /// The file containing raw value of the wrapping key.
138        passphrase_file: PathBuf,
139    },
140
141    /// Export object under wrap (encrypted).
142    ExportWrapped {
143        /// Wrapping key which should encrypt the exported object.
144        wrap_key_id: Id,
145
146        /// Object that will be exported.
147        #[cfg_attr(feature = "serde", serde(flatten))]
148        object: ObjectId,
149
150        /// Output file which will contain the exported object encrypted with the wrapping key.
151        wrapped_file: PathBuf,
152    },
153
154    /// Imports objects under wrap (encrypted).
155    ImportWrapped {
156        /// Wrapping key which would decrypt the imported object.
157        wrap_key_id: Id,
158
159        /// Input file which contains the imported object encrypted with the wrapping key.
160        wrapped_file: PathBuf,
161    },
162
163    /// Permanently remove an object from the device.
164    Delete(ObjectId),
165
166    /// Query data about the object and print it to standard output.
167    GetInfo(ObjectId),
168}
signstar_yubihsm2/automation/command.rs

signstar_yubihsm2/automation/
command.rs
