nethsm/base/
impl_noauth.rs

1//! [`NetHsm`] functionality that requires no authentication.
2
3use log::debug;
4use nethsm_sdk_rs::{
5    apis::default_api::{health_alive_get, health_ready_get, health_state_get, info_get},
6    models::{InfoData, SystemState},
7};
8
9#[cfg(doc)]
10use crate::Credentials;
11use crate::{Error, NetHsm, nethsm_sdk::NetHsmApiError, user::NamespaceSupport};
12
13impl NetHsm {
14    /// Returns whether the NetHSM is in [`Unprovisioned`][`SystemState::Unprovisioned`] or
15    /// [`Locked`][`SystemState::Locked`] [state].
16    ///
17    /// For this call no [`Credentials`] are required and if any are configured, they are ignored.
18    ///
19    /// # Errors
20    ///
21    /// Returns an [`Error::Api`] if the information can not be retrieved or the NetHSM is in
22    /// [`Operational`][`SystemState::Operational`] [state].
23    ///
24    /// # Examples
25    ///
26    /// ```no_run
27    /// use nethsm::{Connection, ConnectionSecurity, NetHsm};
28    ///
29    /// # fn main() -> testresult::TestResult {
30    /// // no initial credentials are required
31    /// let nethsm = NetHsm::new(
32    ///     Connection::new(
33    ///         "https://example.org/api/v1".try_into()?,
34    ///         ConnectionSecurity::Unsafe,
35    ///     ),
36    ///     None,
37    ///     None,
38    ///     None,
39    /// )?;
40    ///
41    /// // check whether the NetHSM is locked or unprovisioned
42    /// assert!(nethsm.alive().is_ok());
43    /// # Ok(())
44    /// # }
45    /// ```
46    /// [state]: https://docs.nitrokey.com/nethsm/administration#state
47    pub fn alive(&self) -> Result<(), Error> {
48        debug!("Check whether the NetHSM at {} is alive", self.url.borrow());
49
50        self.validate_namespace_access(NamespaceSupport::Supported, None, None)?;
51        health_alive_get(&self.create_connection_config()).map_err(|error| {
52            Error::Api(format!(
53                "Retrieving alive status failed: {}",
54                NetHsmApiError::from(error)
55            ))
56        })?;
57        Ok(())
58    }
59
60    /// Returns whether the NetHSM is in [`Operational`][`SystemState::Operational`] [state].
61    ///
62    /// For this call no [`Credentials`] are required and if any are configured, they are ignored.
63    ///
64    /// # Errors
65    ///
66    /// Returns an [`Error::Api`] if the information can not be retrieved or the NetHSM is in
67    /// [`Unprovisioned`][`SystemState::Unprovisioned`] or [`Locked`][`SystemState::Locked`]
68    /// [state].
69    ///
70    /// # Examples
71    ///
72    /// ```no_run
73    /// use nethsm::{Connection, ConnectionSecurity, NetHsm};
74    ///
75    /// # fn main() -> testresult::TestResult {
76    /// // no initial credentials are required
77    /// let nethsm = NetHsm::new(
78    ///     Connection::new(
79    ///         "https://example.org/api/v1".try_into()?,
80    ///         ConnectionSecurity::Unsafe,
81    ///     ),
82    ///     None,
83    ///     None,
84    ///     None,
85    /// )?;
86    ///
87    /// // check whether the NetHSM is operational
88    /// assert!(nethsm.ready().is_ok());
89    /// # Ok(())
90    /// # }
91    /// ```
92    /// [state]: https://docs.nitrokey.com/nethsm/administration#state
93    pub fn ready(&self) -> Result<(), Error> {
94        debug!("Check whether the NetHSM at {} is ready", self.url.borrow());
95
96        self.validate_namespace_access(NamespaceSupport::Supported, None, None)?;
97        health_ready_get(&self.create_connection_config()).map_err(|error| {
98            Error::Api(format!(
99                "Retrieving ready status failed: {}",
100                NetHsmApiError::from(error)
101            ))
102        })?;
103        Ok(())
104    }
105
106    /// Returns the system [state] of the NetHSM.
107    ///
108    /// Returns a variant of [`SystemState`], which describes the [state] a NetHSM is currently in.
109    ///
110    /// For this call no [`Credentials`] are required and if any are configured, they are ignored.
111    ///
112    /// # Errors
113    ///
114    /// Returns an [`Error::Api`] if the [state] information can not be retrieved.
115    ///
116    /// # Examples
117    ///
118    /// ```no_run
119    /// use nethsm::{Connection, ConnectionSecurity, NetHsm};
120    ///
121    /// # fn main() -> testresult::TestResult {
122    /// // no initial credentials are required
123    /// let nethsm = NetHsm::new(
124    ///     Connection::new(
125    ///         "https://example.org/api/v1".try_into()?,
126    ///         ConnectionSecurity::Unsafe,
127    ///     ),
128    ///     None,
129    ///     None,
130    ///     None,
131    /// )?;
132    ///
133    /// // retrieve the state
134    /// println!("{:?}", nethsm.state()?);
135    /// # Ok(())
136    /// # }
137    /// ```
138    /// [state]: https://docs.nitrokey.com/nethsm/administration#state
139    pub fn state(&self) -> Result<SystemState, Error> {
140        debug!("Get the state of the NetHSM at {}", self.url.borrow());
141
142        self.validate_namespace_access(NamespaceSupport::Supported, None, None)?;
143        let health_state = health_state_get(&self.create_connection_config()).map_err(|error| {
144            Error::Api(format!(
145                "Retrieving state failed: {}",
146                NetHsmApiError::from(error)
147            ))
148        })?;
149        Ok(health_state.entity.state)
150    }
151
152    /// Returns [device information] for the NetHSM.
153    ///
154    /// Returns an [`InfoData`], which provides the [device information].
155    ///
156    /// For this call no [`Credentials`] are required and if any are configured, they are ignored.
157    ///
158    /// # Errors
159    ///
160    /// Returns an [`Error::Api`] if the NetHSM [device information] can not be retrieved.
161    ///
162    /// # Examples
163    ///
164    /// ```no_run
165    /// use nethsm::{Connection, ConnectionSecurity, NetHsm};
166    ///
167    /// # fn main() -> testresult::TestResult {
168    /// // no initial credentials are required
169    /// let nethsm = NetHsm::new(
170    ///     Connection::new(
171    ///         "https://example.org/api/v1".try_into()?,
172    ///         ConnectionSecurity::Unsafe,
173    ///     ),
174    ///     None,
175    ///     None,
176    ///     None,
177    /// )?;
178    ///
179    /// // retrieve the NetHSM info
180    /// println!("{:?}", nethsm.info()?);
181    /// # Ok(())
182    /// # }
183    /// ```
184    /// [device information]: https://docs.nitrokey.com/nethsm/administration#device-information
185    pub fn info(&self) -> Result<InfoData, Error> {
186        debug!("Get info about the NetHSM at {}", self.url.borrow());
187
188        self.validate_namespace_access(NamespaceSupport::Supported, None, None)?;
189        let info = info_get(&self.create_connection_config()).map_err(|error| {
190            Error::Api(format!(
191                "Retrieving device information failed: {}",
192                NetHsmApiError::from(error)
193            ))
194        })?;
195        Ok(info.entity)
196    }
197}
nethsm/base/impl_noauth.rs

nethsm/base/
impl_noauth.rs
