Expose Pkcs11Impl and add new_unchecked

Signed-off-by: Wiktor Kwapisiewicz <wiktor@metacode.biz>

Author: wiktor-k

cryptoki/src/context/mod.rs

@@ -49,8 +49,12 @@ enum FunctionList {
     V3_2(cryptoki_sys::CK_FUNCTION_LIST_3_2),
 }
 
-// Implementation of Pkcs11 class that can be enclosed in a single Arc
-pub(crate) struct Pkcs11Impl {
+/// Implementation of Pkcs11 class that can be enclosed in a single [`std::sync::Arc`].
+///
+/// This object never finalizes the underlying PKCS#11 implementation.
+/// For most cases it is advisable to use [`Pkcs11`][`crate::context::Pkcs11`] object instead, which implements proper lifecycle functions.
+/// For advanced use cases, where the PKCS#11 lifecycle is managed externally use [`Pkcs11Impl::new_unchecked`].
+pub struct Pkcs11Impl {
     // Even if this field is never read, it is needed for the pointers in function_list to remain
     // valid.
     _pkcs11_lib: cryptoki_sys::Pkcs11,
@@ -74,9 +78,67 @@ impl Pkcs11Impl {
             FunctionList::V3_2(l) => l,
         }
     }
+
+    /// Initializes Pkcs11 using raw Pkcs11 object.
+    ///
+    /// The caller is responsible for ensuring the validity of `pkcs11_lib` object and managing its lifecycle (e.g. calling `finalize`).
+    /// For most use cases it is advisable to use [`crate::context::Pkcs11`] instead.
+    ///
+    /// # Safety
+    ///
+    /// `pkcs11_lib` must point to a valid Pkcs11 object.
+    pub unsafe fn new_unchecked(pkcs11_lib: cryptoki_sys::Pkcs11) -> Result<Self> {
+        /* First try the 3.* API to get default interface. It might have some more functions than
+         * the 2.40 API */
+        let mut interface: *mut cryptoki_sys::CK_INTERFACE = ptr::null_mut();
+        if pkcs11_lib.C_GetInterface.is_ok() {
+            Rv::from(pkcs11_lib.C_GetInterface(
+                ptr::null_mut(),
+                ptr::null_mut(),
+                &mut interface,
+                0,
+            ))
+            .into_result(Function::GetInterface)?;
+            if !interface.is_null() {
+                let ifce: cryptoki_sys::CK_INTERFACE = *interface;
+
+                let list_ptr: *mut cryptoki_sys::CK_FUNCTION_LIST =
+                    ifce.pFunctionList as *mut cryptoki_sys::CK_FUNCTION_LIST;
+                let list: cryptoki_sys::CK_FUNCTION_LIST = *list_ptr;
+                if list.version.major >= 3 {
+                    if list.version.minor >= 2 {
+                        let list32_ptr: *mut cryptoki_sys::CK_FUNCTION_LIST_3_2 =
+                            ifce.pFunctionList as *mut cryptoki_sys::CK_FUNCTION_LIST_3_2;
+                        return Ok(Pkcs11Impl {
+                            _pkcs11_lib: pkcs11_lib,
+                            function_list: FunctionList::V3_2(*list32_ptr),
+                        });
+                    }
+                    let list30_ptr: *mut cryptoki_sys::CK_FUNCTION_LIST_3_0 =
+                        ifce.pFunctionList as *mut cryptoki_sys::CK_FUNCTION_LIST_3_0;
+                    return Ok(Pkcs11Impl {
+                        _pkcs11_lib: pkcs11_lib,
+                        function_list: FunctionList::V3_0(v30tov32(*list30_ptr)),
+                    });
+                }
+                /* fall back to the 2.* API */
+            }
+        }
+
+        let mut list_ptr: *mut cryptoki_sys::CK_FUNCTION_LIST = ptr::null_mut();
+        Rv::from(pkcs11_lib.C_GetFunctionList(&mut list_ptr))
+            .into_result(Function::GetFunctionList)?;
+
+        Ok(Pkcs11Impl {
+            _pkcs11_lib: pkcs11_lib,
+            function_list: FunctionList::V2(v2tov3(*list_ptr)),
+        })
+    }
 }
 
 /// Main PKCS11 context. Should usually be unique per application.
+///
+/// After this object goes out of scope the `Finalize` function of the PKCS#11 implementation will be called.
 #[derive(Debug)]
 pub struct Pkcs11 {
     pub(crate) impl_: Pkcs11Impl,
@@ -117,7 +179,10 @@ impl Pkcs11 {
         unsafe {
             let pkcs11_lib =
                 cryptoki_sys::Pkcs11::new(filename.as_ref()).map_err(Error::LibraryLoading)?;
-            Self::_new(pkcs11_lib)
+            Ok(Self {
+                impl_: Pkcs11Impl::new_unchecked(pkcs11_lib)?,
+                initialized: RwLock::new(false),
+            })
         }
     }
 
@@ -129,67 +194,13 @@ impl Pkcs11 {
             #[cfg(windows)]
             let this_lib = libloading::os::windows::Library::this()?;
             let pkcs11_lib = cryptoki_sys::Pkcs11::from_library(this_lib)?;
-            Self::_new(pkcs11_lib)
+            Ok(Self {
+                impl_: Pkcs11Impl::new_unchecked(pkcs11_lib)?,
+                initialized: RwLock::new(false),
+            })
         }
     }
 
-    unsafe fn _new(pkcs11_lib: cryptoki_sys::Pkcs11) -> Result<Self> {
-        /* First try the 3.* API to get default interface. It might have some more functions than
-         * the 2.40 API */
-        let mut interface: *mut cryptoki_sys::CK_INTERFACE = ptr::null_mut();
-        if pkcs11_lib.C_GetInterface.is_ok() {
-            Rv::from(pkcs11_lib.C_GetInterface(
-                ptr::null_mut(),
-                ptr::null_mut(),
-                &mut interface,
-                0,
-            ))
-            .into_result(Function::GetInterface)?;
-            if !interface.is_null() {
-                let ifce: cryptoki_sys::CK_INTERFACE = *interface;
-
-                let list_ptr: *mut cryptoki_sys::CK_FUNCTION_LIST =
-                    ifce.pFunctionList as *mut cryptoki_sys::CK_FUNCTION_LIST;
-                let list: cryptoki_sys::CK_FUNCTION_LIST = *list_ptr;
-                if list.version.major >= 3 {
-                    if list.version.minor >= 2 {
-                        let list32_ptr: *mut cryptoki_sys::CK_FUNCTION_LIST_3_2 =
-                            ifce.pFunctionList as *mut cryptoki_sys::CK_FUNCTION_LIST_3_2;
-                        return Ok(Pkcs11 {
-                            impl_: Pkcs11Impl {
-                                _pkcs11_lib: pkcs11_lib,
-                                function_list: FunctionList::V3_2(*list32_ptr),
-                            },
-                            initialized: RwLock::new(false),
-                        });
-                    }
-                    let list30_ptr: *mut cryptoki_sys::CK_FUNCTION_LIST_3_0 =
-                        ifce.pFunctionList as *mut cryptoki_sys::CK_FUNCTION_LIST_3_0;
-                    return Ok(Pkcs11 {
-                        impl_: Pkcs11Impl {
-                            _pkcs11_lib: pkcs11_lib,
-                            function_list: FunctionList::V3_0(v30tov32(*list30_ptr)),
-                        },
-                        initialized: RwLock::new(false),
-                    });
-                }
-                /* fall back to the 2.* API */
-            }
-        }
-
-        let mut list_ptr: *mut cryptoki_sys::CK_FUNCTION_LIST = ptr::null_mut();
-        Rv::from(pkcs11_lib.C_GetFunctionList(&mut list_ptr))
-            .into_result(Function::GetFunctionList)?;
-
-        Ok(Pkcs11 {
-            impl_: Pkcs11Impl {
-                _pkcs11_lib: pkcs11_lib,
-                function_list: FunctionList::V2(v2tov3(*list_ptr)),
-            },
-            initialized: RwLock::new(false),
-        })
-    }
-
     /// Initialize the PKCS11 library
     pub fn initialize(&self, init_args: CInitializeArgs) -> Result<()> {
         let mut init_lock = self.initialized.write().expect("lock not to be poisoned");

cryptoki/src/session/mod.rs

@@ -80,7 +80,7 @@ impl<'a> Session<'a> {
     }
 
     pub(crate) fn client(&self) -> &Pkcs11 {
-        &self.client
+        self.client
     }
 }