Skip to content

README.md

Latest commit

 

History

History
64 lines (48 loc) · 3.3 KB

README.md

File metadata and controls

64 lines (48 loc) · 3.3 KB
Raw

SimRS Language Bindings

Foreign-language bindings for the SimRS smart card simulator. All bindings in this directory wrap the same core C API and are licensed under the GNU Library General Public License v2.0 or later (LGPL-2.0-or-later), enabling use from proprietary applications via dynamic linking.

The SimRS core library (under crates/) remains GPL-2.0-or-later.

Available Bindings

Directory Language Mechanism Status
simrs-hle-capi C/C++ cdylib (.so/.dylib) + simrs.h (build-time generated) Stable
simrs-hle-rust Rust Safe re-export of simrs-hle under LGPL Stable
simrs-hle-python Python ctypes over cdylib, thread-safe by default Stable
simrs-hle-java Java/Kotlin JNI shim over cdylib, Kotlin extensions, tested via jbang + JUnit 5 Stable
simrs-hle-go Go cgo over cdylib with idiomatic Go wrapper Stable
simrs-hle-swift Swift Swift Package over cdylib via C module map Stable
simrs-hle-dotnet C#/.NET P/Invoke over cdylib, thread-safe by default Stable

Building

# Build the C shared library
cargo build --manifest-path exports/simrs-hle-capi/Cargo.toml --release

# The C header (simrs.h) is generated automatically during cargo build
# Find it at: exports/simrs-hle-capi/target/release/build/simrs-hle-capi-*/out/simrs.h

# Run Python bindings tests
cargo test --manifest-path exports/simrs-hle-python/Cargo.toml

Output Artifacts

After building simrs-hle-capi:

exports/simrs-hle-capi/
  target/release/build/.../out/simrs.h       # C header (generated by cbindgen)
  target/release/libsimrs_hle_capi.so        # Shared library (Linux)

API Surface

All bindings expose the same 8 functions:

Function Description
simrs_init Initialize with Milenage auth (Ki, K, OPc)
simrs_init_profile Initialize from TCA eUICC DER profile
simrs_reset Power-on reset, returns ATR
simrs_apdu Process one APDU command
simrs_snapshot_save Save SIM state
simrs_snapshot_restore Restore SIM state
simrs_snapshot_size Required snapshot buffer size
simrs_state_hash FNV-1a hash of current state

Thread Safety

The C API uses thread-local storage. Each OS thread gets its own independent SIM instance. The Python bindings handle this transparently with a dedicated worker thread per Sim instance (configurable via thread_safe parameter).