1 files changed, 99 insertions, 0 deletions
diff --git a/src/misc.rs b/src/misc.rs
new file mode 100644
index 0000000..42f8639
--- /dev/null
+++ b/src/misc.rs
@@ -0,0 +1,99 @@
+use device::{Admin, Device, User};
+use util::CommandError;
+
+/// Provides methods to authenticate as a user or as an admin using a PIN.  The authenticated
+/// methods will consume the current device instance.  On success, they return the authenticated
+/// device.  Otherwise, they return the current unauthenticated device and the error code.
+pub trait Authenticate {
+    /// Performs user authentication.  This method consumes the device.  If
+    /// successful, an authenticated device is returned.  Otherwise, the
+    /// current unauthenticated device and the error are returned.
+    ///
+    /// This method generates a random temporary password that is used for all
+    /// operations that require user access.
+    ///
+    /// # Errors
+    ///
+    /// - [`InvalidString`][] if the provided user password contains a null byte
+    /// - [`RngError`][] if the generation of the temporary password failed
+    /// - [`WrongPassword`][] if the provided user password is wrong
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// use nitrokey::{Authenticate, DeviceWrapper, User};
+    /// # use nitrokey::CommandError;
+    ///
+    /// fn perform_user_task(device: &User<DeviceWrapper>) {}
+    /// fn perform_other_task(device: &DeviceWrapper) {}
+    ///
+    /// # fn try_main() -> Result<(), CommandError> {
+    /// let device = nitrokey::connect()?;
+    /// let device = match device.authenticate_user("123456") {
+    ///     Ok(user) => {
+    ///         perform_user_task(&user);
+    ///         user.device()
+    ///     },
+    ///     Err((device, err)) => {
+    ///         println!("Could not authenticate as user: {:?}", err);
+    ///         device
+    ///     },
+    /// };
+    /// perform_other_task(&device);
+    /// #     Ok(())
+    /// # }
+    /// ```
+    ///
+    /// [`InvalidString`]: enum.CommandError.html#variant.InvalidString
+    /// [`RngError`]: enum.CommandError.html#variant.RngError
+    /// [`WrongPassword`]: enum.CommandError.html#variant.WrongPassword
+    fn authenticate_user(self, password: &str) -> Result<User<Self>, (Self, CommandError)>
+    where
+        Self: Device + Sized;
+
+    /// Performs admin authentication.  This method consumes the device.  If
+    /// successful, an authenticated device is returned.  Otherwise, the
+    /// current unauthenticated device and the error are returned.
+    ///
+    /// This method generates a random temporary password that is used for all
+    /// operations that require admin access.
+    ///
+    /// # Errors
+    ///
+    /// - [`InvalidString`][] if the provided admin password contains a null byte
+    /// - [`RngError`][] if the generation of the temporary password failed
+    /// - [`WrongPassword`][] if the provided admin password is wrong
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// use nitrokey::{Authenticate, Admin, DeviceWrapper};
+    /// # use nitrokey::CommandError;
+    ///
+    /// fn perform_admin_task(device: &Admin<DeviceWrapper>) {}
+    /// fn perform_other_task(device: &DeviceWrapper) {}
+    ///
+    /// # fn try_main() -> Result<(), CommandError> {
+    /// let device = nitrokey::connect()?;
+    /// let device = match device.authenticate_admin("123456") {
+    ///     Ok(admin) => {
+    ///         perform_admin_task(&admin);
+    ///         admin.device()
+    ///     },
+    ///     Err((device, err)) => {
+    ///         println!("Could not authenticate as admin: {:?}", err);
+    ///         device
+    ///     },
+    /// };
+    /// perform_other_task(&device);
+    /// #     Ok(())
+    /// # }
+    /// ```
+    ///
+    /// [`InvalidString`]: enum.CommandError.html#variant.InvalidString
+    /// [`RngError`]: enum.CommandError.html#variant.RngError
+    /// [`WrongPassword`]: enum.CommandError.html#variant.WrongPassword
+    fn authenticate_admin(self, password: &str) -> Result<Admin<Self>, (Self, CommandError)>
+    where
+        Self: Device + Sized;
+}