JMIX-RS

A Rust library for creating, validating, and working with JMIX (JSON Medical Interchange) packages. JMIX enables secure exchange of medical imaging data and metadata with built-in encryption, digital signatures, and integrity verification.

Features

• 🏗️ High-level builder API for creating JMIX envelopes
• 🏥 DICOM file processing and metadata extraction
• 🔐 End-to-end encryption using AES-256-GCM with Curve25519 ECDH
• ✍️ Digital signatures with Ed25519 (JWS standard)
• 🔍 JSON Schema validation with configurable schema directory
• ✅ Integrity verification using deterministic SHA-256 payload hashing
• 🛡️ Cryptographic assertions for sender/receiver identity verification
• 📦 Package validation API with comprehensive error reporting

Installation

Add to your Cargo.toml:

[dependencies]
jmix-rs = "0.3.2"

Quick Start

Basic JMIX Envelope

Create a simple JMIX envelope from DICOM files:

use jmix_rs::{builder::JmixBuilder, config::Config};

let builder = JmixBuilder::new();
let config = Config::from_file("config.json")?;
let (envelope, files) = builder.build_from_dicom("path/to/dicom", &config)?;

With Security Features

Create an envelope with encryption and digital signatures:

use jmix_rs::builder::JmixBuilder;

// Builder with complete security features
let builder = JmixBuilder::with_complete_security()?;
let (envelope, files) = builder.build_from_dicom("path/to/dicom", &config)?;

// Save to files
let saved_files = builder.save_to_files(&envelope, &files, "./tmp/output")?;

DICOM Processing

Extract metadata from DICOM files:

use jmix_rs::dicom::DicomProcessor;

let processor = DicomProcessor::new();
let metadata = processor.process_dicom_folder("path/to/dicom", None)?;
println!("Extracted {} instances", metadata.instance_count);

Configuration

Create a configuration file for your JMIX envelope:

{
  "version": "1.0",
  "sender": {
    "name": "Healthcare Provider",
    "id": "org:provider.123",
    "contact": "admin@provider.com"
  },
  "patient": {
    "name": "John Doe",
    "id": "PAT12345",
    "dob": "1985-03-15"
  }
}

API Overview

Core Types

use jmix_rs::{
    builder::JmixBuilder,
    config::Config,
    types::{Envelope, Manifest, Metadata, Audit, Files},
    dicom::DicomProcessor,
    validation::ValidationConfig,
    package_validation::{validate_package, ValidationOptions}
};

Builder API

The JmixBuilder provides a high-level API for creating JMIX envelopes:

// Basic builder
let builder = JmixBuilder::new();

// With encryption only
let builder = JmixBuilder::with_encryption(recipient_public_key)?;

// With signatures only  
let builder = JmixBuilder::with_jws_signing()?;

// With complete security (encryption + signatures + assertions)
let builder = JmixBuilder::with_complete_security()?;

Validation API

Validate existing JMIX packages:

use jmix_rs::package_validation::{validate_package, ValidationOptions};

let options = ValidationOptions {
    validate_schema: true,
    schema_dir: Some("../jmix/schemas".to_string()),
    verify_assertions: true,
    recipient_secret_key_path: Some("./tmp/key.pem".to_string()),
};

let report = validate_package("./tmp/package.jmix", &options)?;
println!("Validation result: {:?}", report);

Error Handling

use jmix_rs::error::JmixError;

match result {
    Ok(envelope) => println!("Success!"),
    Err(JmixError::Validation(e)) => eprintln!("Schema validation error: {}", e),
    Err(JmixError::Dicom(e)) => eprintln!("DICOM processing error: {}", e),
    Err(JmixError::Encryption(e)) => eprintln!("Encryption error: {}", e),
    Err(JmixError::Jws(e)) => eprintln!("Signing error: {}", e),
    Err(JmixError::Assertion(e)) => eprintln!("Assertion error: {}", e),
    Err(e) => eprintln!("Other error: {}", e),
}

Performance Optimization

For large DICOM datasets, you can use performance flags to optimize processing:

// Skip SHA-256 hashing for faster processing
let (envelope, files) = builder.build_from_dicom_with_options(
    &dicom_path,
    &config,
    true,  // skip_hashing
    false  // skip_listing
)?;

// Skip both hashing and file listing for maximum speed
let (envelope, files) = builder.build_from_dicom_with_options(
    &dicom_path,
    &config,
    true,  // skip_hashing
    true   // skip_listing
)?;

// Save with same performance flags
builder.save_to_files_with_options(
    &envelope,
    &files,
    &output_dir,
    true,  // skip_hashing
    true   // skip_listing
)?;

See Performance Optimization Guide for detailed information.

Schema Validation

Configure JSON Schema validation for JMIX packages:

use jmix_rs::validation::ValidationConfig;

// Configure schema directory
let validation_config = ValidationConfig::new(
    Some("../jmix/schemas".to_string())
)?;

// Validate envelope components
validation_config.validate_manifest(&envelope.manifest)?;
validation_config.validate_metadata(&envelope.metadata)?;
validation_config.validate_audit(&envelope.audit)?;

Schema resolution order:

1. ValidationConfig::new(Some(path)) - Explicit path
2. JMIX_SCHEMA_DIR environment variable
3. ../jmix/schemas (default)

Technical Details

Cryptographic Features

• AES-256-GCM: Authenticated encryption with 256-bit keys
• Curve25519: Elliptic curve Diffie-Hellman key exchange
• Ed25519: Elliptic curve digital signatures (JWS standard)
• SHA-256: Deterministic payload hashing for integrity verification
• Ephemeral keys: Base64-encoded ephemeral public key, IV, and auth tag

Payload Hashing

JMIX-RS uses deterministic SHA-256 payload hashing:

• Unencrypted: Hash computed over payload/ directory contents
• Encrypted: Hash computed over plaintext TAR before encryption
• Format: sha256:<hex> stored in manifest.security.payload_hash

CLI Tool

The library includes a command-line tool for validating and working with JMIX packages:

Installation

# Install from crates.io
cargo install jmix-rs

# Or build from source
cargo build --release
# Binary at: target/release/jmix

Usage

# Validate a JMIX package
jmix validate ./tmp/package.jmix

# Validate with schema checking
jmix validate ./tmp/package.jmix --validate-schema

# Decrypt an encrypted package
jmix decrypt ./tmp/encrypted.jmix --key ./tmp/key.pem --out ./tmp/output

# JSON output for automation
jmix validate ./tmp/package.jmix --json

For detailed CLI documentation, run jmix --help.

Learn More

• 📖 Developer Guide - Contributing and development setup
• ⚡ Performance Optimization - Large dataset handling
• 🧪 Testing Guide - Test suite documentation
• 📋 Changelog - Release history and changes
• 📚 API Documentation - Rust library docs

License

This project is licensed under the Apache 2.0 License.