ci: run examples on SoftHSM and added README.md for guidance on new examples

- run examples on SoftHSM during CI builds
- added README for guidance on how to write new examples

Author: keldonin

.github/workflows/ci.yml

@@ -107,6 +107,11 @@ jobs:
           - target: aarch64-unknown-linux-gnu
             runner: ubuntu-24.04-arm
     runs-on: ${{ matrix.runner }}
+    env:
+      TEST_PKCS11_MODULE: /usr/lib/softhsm/libsofthsm2.so
+      SOFTHSM2_CONF: /tmp/softhsm2.conf
+      RUSTFLAGS: "-D warnings"
+      RUST_BACKTRACE: 1
     steps:
       - uses: actions/checkout@v4
       - name: Setup Rust toolchain
@@ -134,12 +139,18 @@ jobs:
       - name: Check
         run: cargo check --target ${{ matrix.target }} --workspace --all-targets
       - name: Test script
-        env:
-          TEST_PKCS11_MODULE: /usr/lib/softhsm/libsofthsm2.so
-          SOFTHSM2_CONF: /tmp/softhsm2.conf
-          RUSTFLAGS: "-D warnings"
-          RUST_BACKTRACE: 1
         run: cargo test --target ${{ matrix.target }}
+      # "Run examples" assumes that:
+      #   - there is one example per file.
+      #   - the run does not take any arguments.
+      #   - the run is relatively fast.
+      #   - the return code is non-zero if the example fails.
+      - name: Run examples
+        run: |
+          EXAMPLES=$(ls cryptoki/examples/*.rs | sed 's/\.rs$//' | xargs -n 1 basename)
+          for example in $EXAMPLES; do
+            cargo run --target ${{ matrix.target }} --example "$example"
+          done
 
   build-windows:
     name: Build on Windows

cryptoki/examples/README.md

@@ -0,0 +1,21 @@
+# Writing new examples
+
+Examples are run during CI, so new examples must follow these rules:
+
+- Use the same test credentials as other examples and tests.
+- Keep each example to a single file (1 example = 1 file).
+- Do not expect command-line arguments.
+- Do not require environment variables other than `TEST_PKCS11_MODULE`.
+- Keep runtime relatively fast; verbose output is fine.
+- Ensure it runs on the MSRV.
+- Exit with status 0 on normal execution; any non-zero status is treated as an error.
+- Use `testresult::TestResult` as the return type of `main` for easier error handling.
+
+In addition, examples should be extensively documented and designed to be educative.
+
+Suggested best practices:
+
+- Reference the same SoftHSM setup used by CI; avoid introducing new credentials.
+- Clean up any tokens, keys, or objects created by the example. When possible, use session (i.e. non-persistent) objects.
+- Ensure the example works with SoftHSM2.
+

cryptoki/examples/generate_key_pair.rs

@@ -8,9 +8,9 @@ use cryptoki::types::AuthPin;
 use std::env;
 
 // The default user pin
-pub static USER_PIN: &str = "fedcba";
+pub static USER_PIN: &str = "fedcba123456";
 // The default SO pin
-pub static SO_PIN: &str = "abcdef";
+pub static SO_PIN: &str = "abcdef654321";
 
 fn main() -> testresult::TestResult {
     // initialize a new Pkcs11 object using the module from the env variable
@@ -24,10 +24,10 @@ fn main() -> testresult::TestResult {
     let slot = pkcs11.get_slots_with_token()?[0];
 
     // initialize a test token
-    let so_pin = AuthPin::new("abcdef".into());
+    let so_pin = AuthPin::new(SO_PIN.into());
     pkcs11.init_token(slot, &so_pin, "Test Token")?;
 
-    let user_pin = AuthPin::new("fedcba".into());
+    let user_pin = AuthPin::new(USER_PIN.into());
 
     // initialize user PIN
     {

cryptoki/examples/thread_local_session.rs

@@ -47,8 +47,10 @@ use cryptoki::object::Attribute;
 use cryptoki::session::{Session, UserType};
 use cryptoki::types::AuthPin;
 
-const USER_PIN: &str = "fedcba";
-const SO_PIN: &str = "abcdef";
+// The default user pin
+pub static USER_PIN: &str = "fedcba123456";
+// The default SO pin
+pub static SO_PIN: &str = "abcdef654321";
 
 // Global PKCS11 context shared across all threads using Arc for cheap cloning
 static PKCS11_CTX: OnceLock<Pkcs11> = OnceLock::new();