Add Device::build_aes_key method

This patch adds the build_aes_key method to the Device trait that uses
the NK_build_aes_key function to build new AES keys on the device.  This
effectively resets the password safe and the encrypted storage.  It is
unclear whether other data (e. g. the one-time passwords) are affected
too.

1 files changed, 31 insertions, 0 deletions

diff --git a/src/device.rs b/src/device.rs
index 8702405..bc48cd2 100644
--- a/src/device.rs
+++ b/src/device.rs
@@ -540,6 +540,37 @@ pub trait Device: Authenticate + GetPasswordSafe + GenerateOtp {
         let admin_pin_string = get_cstring(admin_pin)?;
         unsafe { get_command_result(nitrokey_sys::NK_factory_reset(admin_pin_string.as_ptr())) }
     }
+
+    /// Builds a new AES key on the Nitrokey.
+    ///
+    /// The AES key is used to encrypt the password safe and the encrypted volume.  You may need
+    /// to call this method after a factory reset using `gpg --card-edit`.  You can also use it to
+    /// destory the data stored in the password safe or on the encrypted volume.
+    ///
+    /// # Errors
+    ///
+    /// - [`InvalidString`][] if the provided password contains a null byte
+    /// - [`WrongPassword`][] if the admin password is wrong
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// use nitrokey::Device;
+    /// # use nitrokey::CommandError;
+    ///
+    /// # fn try_main() -> Result<(), CommandError> {
+    /// let device = nitrokey::connect()?;
+    /// match device.build_aes_key("12345678") {
+    ///     Ok(()) => println!("New AES keys have been built."),
+    ///     Err(err) => println!("Could not build new AES keys: {}", err),
+    /// };
+    /// #     Ok(())
+    /// # }
+    /// ```
+    fn build_aes_key(&self, admin_pin: &str) -> Result<(), CommandError> {
+        let admin_pin_string = get_cstring(admin_pin)?;
+        unsafe { get_command_result(nitrokey_sys::NK_build_aes_key(admin_pin_string.as_ptr())) }
+    }
 }
 
 /// Connects to a Nitrokey device.  This method can be used to connect to any connected device,