diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index bbb82d4a..1f43ada2 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/cryptoki/examples/README.md b/cryptoki/examples/README.md new file mode 100644 index 00000000..02a92b81 --- /dev/null +++ b/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. + diff --git a/cryptoki/examples/generate_key_pair.rs b/cryptoki/examples/generate_key_pair.rs index e54f7b4f..7fdf066f 100644 --- a/cryptoki/examples/generate_key_pair.rs +++ b/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 { diff --git a/cryptoki/examples/thread_local_session.rs b/cryptoki/examples/thread_local_session.rs index 812d87ad..001410e7 100644 --- a/cryptoki/examples/thread_local_session.rs +++ b/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 = OnceLock::new();