From 5f956b8e2a7f1fbf8e968154f55fadb71e8b521a Mon Sep 17 00:00:00 2001
From: Robin Krahl <robin.krahl@ireas.org>
Date: Thu, 24 May 2018 20:36:46 +0000
Subject: Introduce DeviceWrapper to abstract over devices

DeviceWrapper abstracts over the supported devices.  It implements the
traits that are implemented by all supported devices.  The previous
UnauthenticatedDevice is renamed to Pro to prepare Storage support.
connect_model is moved to Pro::connect.
---
 src/misc.rs | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 src/misc.rs

(limited to 'src/misc.rs')

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;
+}
-- 
cgit v1.2.1