Add support for the hidden volumes on a Nitrokey Storage

This patch introduces the methods enable_hidden_volume,
disable_hidden_volume and create_hidden_volume for the Storage struct to
support the hidden volumes on the Nitrokey Storage.  The enable and
create methods require that the encrypted storage has been enabled.
Contrary to authentication and password safe access, we do not enforce
this requirement in the API as file system operations could have
unwanted side effects and should not performed implicitly.

1 files changed, 134 insertions, 0 deletions

diff --git a/src/device.rs b/src/device.rs
index 78d0d82..31e14a9 100644
--- a/src/device.rs
+++ b/src/device.rs
@@ -878,6 +878,140 @@ impl Storage {
         unsafe { get_command_result(nitrokey_sys::NK_lock_encrypted_volume()) }
     }
 
+    /// Enables a hidden storage volume.
+    ///
+    /// This function will only succeed if the encrypted storage ([`enable_encrypted_volume`][]) or
+    /// another hidden volume has been enabled previously.  Once the hidden volume is enabled, it
+    /// is presented to the operating system as a block device and any previously opened encrypted
+    /// or hidden volumes are closed.  The API does not provide any information on the name or path
+    /// of this block device.
+    ///
+    /// Note that the encrypted and the hidden volumes operate on the same storage area, so using
+    /// both at the same time might lead to data loss.
+    ///
+    /// The hidden volume to unlock is selected based on the provided password.
+    ///
+    /// # Errors
+    ///
+    /// - [`AesDecryptionFailed`][] if the encrypted storage has not been opened before calling
+    ///   this method or the AES key has not been built
+    /// - [`InvalidString`][] if the provided password contains a null byte
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// # use nitrokey::CommandError;
+    ///
+    /// # fn try_main() -> Result<(), CommandError> {
+    /// let device = nitrokey::Storage::connect()?;
+    /// device.enable_encrypted_volume("123445")?;
+    /// match device.enable_hidden_volume("hidden-pw") {
+    ///     Ok(()) => println!("Enabled a hidden volume."),
+    ///     Err(err) => println!("Could not enable the hidden volume: {}", err),
+    /// };
+    /// #     Ok(())
+    /// # }
+    /// ```
+    ///
+    /// [`enable_encrypted_volume`]: #method.enable_encrypted_volume
+    /// [`AesDecryptionFailed`]: enum.CommandError.html#variant.AesDecryptionFailed
+    /// [`InvalidString`]: enum.CommandError.html#variant.InvalidString
+    pub fn enable_hidden_volume(&self, volume_password: &str) -> Result<(), CommandError> {
+        let volume_password = get_cstring(volume_password)?;
+        unsafe {
+            get_command_result(nitrokey_sys::NK_unlock_hidden_volume(
+                volume_password.as_ptr(),
+            ))
+        }
+    }
+
+    /// Disables a hidden storage volume.
+    ///
+    /// Once the volume is disabled, it can be no longer accessed as a block device.  If no hidden
+    /// volume has been enabled, this method still returns a success.
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// # use nitrokey::CommandError;
+    ///
+    /// fn use_volume() {}
+    ///
+    /// # fn try_main() -> Result<(), CommandError> {
+    /// let device = nitrokey::Storage::connect()?;
+    /// device.enable_encrypted_volume("123445")?;
+    /// match device.enable_hidden_volume("hidden-pw") {
+    ///     Ok(()) => {
+    ///         println!("Enabled the hidden volume.");
+    ///         use_volume();
+    ///         match device.disable_hidden_volume() {
+    ///             Ok(()) => println!("Disabled the hidden volume."),
+    ///             Err(err) => {
+    ///                 println!("Could not disable the hidden volume: {}", err);
+    ///             },
+    ///         };
+    ///     },
+    ///     Err(err) => println!("Could not enable the hidden volume: {}", err),
+    /// };
+    /// #     Ok(())
+    /// # }
+    /// ```
+    pub fn disable_hidden_volume(&self) -> Result<(), CommandError> {
+        unsafe { get_command_result(nitrokey_sys::NK_lock_hidden_volume()) }
+    }
+
+    /// Creates a hidden volume.
+    ///
+    /// The volume is crated in the given slot and in the given range of the available memory,
+    /// where `start` is the start position as a percentage of the available memory, and `end` is
+    /// the end position as a percentage of the available memory.  The volume will be protected by
+    /// the given password.
+    ///
+    /// Note that the encrypted and the hidden volumes operate on the same storage area, so using
+    /// both at the same time might lead to data loss.
+    ///
+    /// According to the libnitrokey documentation, this function only works if the encrypted
+    /// storage has been opened.
+    ///
+    /// # Errors
+    ///
+    /// - [`AesDecryptionFailed`][] if the encrypted storage has not been opened before calling
+    ///   this method or the AES key has not been built
+    /// - [`InvalidString`][] if the provided password contains a null byte
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// # use nitrokey::CommandError;
+    ///
+    /// # fn try_main() -> Result<(), CommandError> {
+    /// let device = nitrokey::Storage::connect()?;
+    /// device.enable_encrypted_volume("123445")?;
+    /// device.create_hidden_volume(0, 0, 100, "hidden-pw")?;
+    /// #     Ok(())
+    /// # }
+    /// ```
+    ///
+    /// [`AesDecryptionFailed`]: enum.CommandError.html#variant.AesDecryptionFailed
+    /// [`InvalidString`]: enum.CommandError.html#variant.InvalidString
+    pub fn create_hidden_volume(
+        &self,
+        slot: u8,
+        start: u8,
+        end: u8,
+        password: &str,
+    ) -> Result<(), CommandError> {
+        let password = get_cstring(password)?;
+        unsafe {
+            get_command_result(nitrokey_sys::NK_create_hidden_volume(
+                slot,
+                start,
+                end,
+                password.as_ptr(),
+            ))
+        }
+    }
+
     /// Returns the status of the connected storage device.
     ///
     /// # Example