Add pReserved and other PKCS#11 flags for C_Initialize

Signed-off-by: Alexandru Placinta <[email protected]>

Author: placintaalexandru

cryptoki/src/context/locking.rs

@@ -2,32 +2,157 @@
 // SPDX-License-Identifier: Apache-2.0
 //! Locking related type
 
-use cryptoki_sys::{CKF_OS_LOCKING_OK, CK_FLAGS};
+use cryptoki_sys::{
+    CKF_LIBRARY_CANT_CREATE_OS_THREADS, CKF_OS_LOCKING_OK, CK_CREATEMUTEX, CK_DESTROYMUTEX,
+    CK_FLAGS, CK_LOCKMUTEX, CK_UNLOCKMUTEX,
+};
 
-use std::ptr;
+use std::{
+    os::raw::c_void,
+    ptr::{self, NonNull},
+};
 
-/// Argument for the initialize function
+/// Provides function pointers for mutex-handling to ensure safe multi-threaded access.
 #[derive(Copy, Clone, Debug)]
-pub enum CInitializeArgs {
-    /// The library can use the native OS library for locking
+pub struct CustomMutexHandling {
+    create_mutex: CK_CREATEMUTEX,
+    destroy_mutex: CK_DESTROYMUTEX,
+    lock_mutex: CK_LOCKMUTEX,
+    unlock_mutex: CK_UNLOCKMUTEX,
+}
+
+impl CustomMutexHandling {
+    /// Create a new `CustomMutexHandling` with the given function pointers
+    /// to handle library's thread safety.
+    ///
+    /// # Safety
+    /// Considered unsafe due to user's ability to pass any function pointer.
+    pub unsafe fn new(
+        create_mutex: CK_CREATEMUTEX,
+        destroy_mutex: CK_DESTROYMUTEX,
+        lock_mutex: CK_LOCKMUTEX,
+        unlock_mutex: CK_UNLOCKMUTEX,
+    ) -> Self {
+        Self {
+            create_mutex,
+            destroy_mutex,
+            lock_mutex,
+            unlock_mutex,
+        }
+    }
+}
+
+/// Flags to set for the initialize function
+#[derive(Copy, Clone, Debug)]
+pub enum CInitializeFlags {
+    /// The library won’t be accessed from multiple threads simultaneously
+    None,
+    /// The library may not create its own threads
+    NoOsThreads,
+    /// The library can use the native OS library for locking or the custom
     OsThreads,
-    // TODO: add variants for custom mutexes here and no multithreading, safety implications for
-    // that.
+    /// The library needs to use the supplied function pointers
+    /// for mutex-handling to ensure safe multi-threaded access.
+    CustomMutexHandling(CustomMutexHandling),
+    /// The library needs to use either the native operating system primitives
+    /// or the supplied function pointers for mutex-handling to ensure safe
+    /// multi-threaded access
+    OsThreadsOrCustomMutexHandling(CustomMutexHandling),
+}
+
+#[derive(Copy, Clone, Debug)]
+/// Argument for the initialize function
+pub struct CInitializeArgs {
+    flags: CInitializeFlags,
+    p_reserved: Option<NonNull<c_void>>,
+}
+
+impl CInitializeArgs {
+    /// Create a new `CInitializeArgs` with the given flags
+    ///
+    /// # Examples
+    /// ```
+    /// use cryptoki::context::{CInitializeArgs, CInitializeFlags};
+    ///
+    /// let args = CInitializeArgs::new(CInitializeFlags::OsThreads);
+    /// ```
+    pub fn new(flags: CInitializeFlags) -> Self {
+        Self {
+            flags,
+            p_reserved: None,
+        }
+    }
+
+    /// Create a new `CInitializeArgs` with the given flags and reserved pointer.
+    ///
+    /// # Safety
+    /// Considered unsafe due to the user's ability to pass any pointer.
+    ///
+    /// The user is responsible for managing the memory behind the pointer.
+    pub unsafe fn new_with_reserved(flags: CInitializeFlags, p_reserved: *mut c_void) -> Self {
+        Self {
+            flags,
+            p_reserved: NonNull::new(p_reserved),
+        }
+    }
 }
 
 impl From<CInitializeArgs> for cryptoki_sys::CK_C_INITIALIZE_ARGS {
     fn from(c_initialize_args: CInitializeArgs) -> Self {
         let mut flags = CK_FLAGS::default();
-        match c_initialize_args {
-            CInitializeArgs::OsThreads => {
+        let p_reserved = c_initialize_args
+            .p_reserved
+            .map(|non_null| non_null.as_ptr())
+            .unwrap_or_else(ptr::null_mut);
+
+        match c_initialize_args.flags {
+            CInitializeFlags::None => Self {
+                CreateMutex: None,
+                DestroyMutex: None,
+                LockMutex: None,
+                UnlockMutex: None,
+                flags,
+                pReserved: p_reserved,
+            },
+            CInitializeFlags::NoOsThreads => {
+                flags |= CKF_LIBRARY_CANT_CREATE_OS_THREADS;
+                Self {
+                    flags,
+                    CreateMutex: None,
+                    DestroyMutex: None,
+                    LockMutex: None,
+                    UnlockMutex: None,
+                    pReserved: p_reserved,
+                }
+            }
+            CInitializeFlags::OsThreads => {
                 flags |= CKF_OS_LOCKING_OK;
                 Self {
                     flags,
                     CreateMutex: None,
                     DestroyMutex: None,
                     LockMutex: None,
                     UnlockMutex: None,
-                    pReserved: ptr::null_mut(),
+                    pReserved: p_reserved,
+                }
+            }
+            CInitializeFlags::CustomMutexHandling(custom_mutex_handling) => Self {
+                flags,
+                CreateMutex: custom_mutex_handling.create_mutex,
+                DestroyMutex: custom_mutex_handling.destroy_mutex,
+                LockMutex: custom_mutex_handling.lock_mutex,
+                UnlockMutex: custom_mutex_handling.unlock_mutex,
+                pReserved: p_reserved,
+            },
+            CInitializeFlags::OsThreadsOrCustomMutexHandling(custom_mutex_handling) => {
+                flags |= CKF_OS_LOCKING_OK;
+                Self {
+                    flags,
+                    CreateMutex: custom_mutex_handling.create_mutex,
+                    DestroyMutex: custom_mutex_handling.destroy_mutex,
+                    LockMutex: custom_mutex_handling.lock_mutex,
+                    UnlockMutex: custom_mutex_handling.unlock_mutex,
+                    pReserved: p_reserved,
                 }
             }
         }