Add an example to find_objects

Closes: #143
Co-authored-by: Wiktor Kwapisiewicz <wiktor@metacode.biz>
Signed-off-by: Dan Dumont <dan.dumont@hcl.com>
Signed-off-by: Wiktor Kwapisiewicz <wiktor@metacode.biz>

Author: 2 people

Cargo.lock

@@ -25,7 +25,7 @@ secrecy = "0.8.0"
 num-traits = "0.2.14"
 hex = "0.4.3"
 serial_test = "0.5.1"
-testresult = "0.2.0"
+testresult = "0.4.1"
 
 [features]
 psa-crypto-conversions = ["psa-crypto"]

cryptoki/Cargo.toml

@@ -41,6 +41,25 @@ impl Pkcs11 {
     /// For a Read-Write session, use `open_rw_session`
     ///
     /// Note: No callback is set when opening the session.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # fn main() -> testresult::TestResult {
+    /// use cryptoki::session::Session;
+    /// use cryptoki::context::Pkcs11;
+    ///
+    /// let mut client = Pkcs11::new(
+    ///     std::env::var("PKCS11_SOFTHSM2_MODULE")
+    ///        .unwrap_or_else(|_| "/usr/local/lib/softhsm/libsofthsm2.so".to_string()),
+    /// )?;
+    /// client.initialize(cryptoki::context::CInitializeArgs::OsThreads)?;
+    ///
+    /// // Use the first slot
+    /// let slot = client.get_all_slots()?[0];
+    /// let session = client.open_ro_session(slot)?;
+    /// # let _ = session; Ok(()) }
+    /// ```
     pub fn open_ro_session(&self, slot_id: Slot) -> Result<Session> {
         self.open_session(slot_id, false)
     }

cryptoki/src/context/session_management.rs

@@ -15,6 +15,41 @@ const MAX_OBJECT_COUNT: usize = 10;
 
 impl Session {
     /// Search for session objects matching a template
+    ///
+    /// # Arguments
+    /// * `template` - A [Attribute] of search parameters that will be used
+    ///                 to find objects.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # fn main() -> testresult::TestResult {
+    /// # use cryptoki::session::Session;
+    /// # use cryptoki::context::Pkcs11;
+    /// # use cryptoki::object::{Attribute, AttributeType, CertificateType, ObjectClass, ObjectHandle};
+    /// #
+    /// # let mut client = Pkcs11::new(
+    /// #    std::env::var("PKCS11_SOFTHSM2_MODULE")
+    /// #       .unwrap_or_else(|_| "/usr/local/lib/softhsm/libsofthsm2.so".to_string()),
+    /// # )?;
+    /// # client.initialize(cryptoki::context::CInitializeArgs::OsThreads)?;
+    /// #
+    /// # // Use the first slot
+    /// # let slot = client.get_all_slots()?[0];
+    /// # let session = client.open_ro_session(slot)?;
+    /// #
+    /// // Get handles to all of the x509 certificates on the card
+    /// let search = vec![Attribute::Class(ObjectClass::CERTIFICATE), Attribute::CertificateType(CertificateType::X_509)];
+    /// for handle in session.find_objects(&search)? {
+    ///     // each cert: get the "value" which will be the raw certificate data
+    ///     for value in session.get_attributes(handle, &[AttributeType::Value])? {
+    ///        if let Attribute::Value(value) = value {
+    ///            println!("Certificate value: {value:?}");
+    ///        }
+    ///     }
+    /// }
+    /// # Ok(()) }
+    /// ```
     pub fn find_objects(&self, template: &[Attribute]) -> Result<Vec<ObjectHandle>> {
         let mut template: Vec<CK_ATTRIBUTE> = template.iter().map(|attr| attr.into()).collect();