nexum-apdu is a comprehensive toolkit for smart card communication in Rust using the APDU (Application Protocol Data Unit) protocol. Whether you're building a payment terminal, identity verification system, or HSM integration, nexum-apdu provides the foundation for secure card communications.
Unlock the cryptographic conversations that smart cards are dying to have with nexum-apdu as your trusted interpreter.
The easiest way to get started is to add the core crate:
cargo add nexum-apdu-coreFor PC/SC reader support, add:
cargo add nexum-apdu-transport-pcscFor GlobalPlatform card management:
cargo add nexum-apdu-globalplatformFor APDU command/response pair macro support:
cargo add nexum-apdu-macrosuse nexum_apdu_core::prelude::*;
use nexum_apdu_transport_pcsc::{PcscDeviceManager, PcscConfig};
fn main() -> Result<(), Error> {
// Create a transport
let manager = PcscDeviceManager::new()?;
let readers = manager.list_readers()?;
let reader = readers.iter().find(|r| r.has_card()).expect("No card present");
let transport = manager.open_reader(reader.name())?;
// Create an executor with default processors (GET RESPONSE handler)
let mut executor = CardExecutor::new_with_defaults(transport);
// Create a SELECT command to select a payment application
let aid = [0xA0, 0x00, 0x00, 0x00, 0x03, 0x10, 0x10];
let select_cmd = Command::new_with_data(0x00, 0xA4, 0x04, 0x00, aid.to_vec());
// Execute the command
let response = executor.transmit(&select_cmd)?;
// Parse the response
if response.is_success() {
println!("Application selected successfully");
if let Some(data) = response.payload() {
println!("FCI: {}", hex::encode_upper(data));
}
} else {
println!("Failed to select application: {}", response.status());
}
Ok(())
}This repository contains the following crates:
nexum-apdu-core: Core traits and types for APDU operationsnexum-apdu-macros: Procedural macros for defining APDU commands and responsesnexum-apdu-transport-pcsc: PC/SC transport implementation for card readersnexum-apdu-globalplatform: GlobalPlatform card management functionality
- 🎯 Abstracted transport layer supporting different card reader types
- 🛡️ Secure channel support for GlobalPlatform SCP02 protocol
- 🧩 Modular architecture allowing use of only what you need
- 📦 Command processor pipeline for flexible transformations
- 📝 Declarative command definitions with the
apdu_pair!macro - 🔄 Response chaining support for handling complex responses
- 🧰 Comprehensive prelude for streamlined imports
For detailed documentation on each crate, please check their individual README files:
- nexum-apdu-core README - Core APDU abstractions and types
- nexum-apdu-macros README - Procedural macros for command/response definition
- nexum-apdu-transport-pcsc README - PC/SC transport implementation
- nexum-apdu-globalplatform README - GlobalPlatform operations
Check out these examples to see nexum-apdu in action:
- Connect to a reader - Basic card connection and communication
- List available readers - Enumerate connected card readers
- APDU shell - Interactive APDU command interpreter
- Monitor card events - Track card insertion/removal events
- Select an application by AID - Select applications using their AID
- Install a CAP file - Install Java Card applications
For more examples, see the examples directory in each crate.
nexum-apdu is built around three main architectural layers:
The CardTransport trait handles the low-level communication with cards, providing a clean abstraction over different physical transport mechanisms.
Command processors can transform, secure, or log APDU commands before they reach the transport layer, allowing for modular protocol implementations like secure channels.
Executors manage the complete command execution flow, combining transports and processors to provide a high-level interface for applications.
Licensed under the AGPL License or http://www.gnu.org/licenses/agpl-3.0.html.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in these crates by you shall be licensed as above, without any additional terms or conditions.