Table of Contents
- Overview
- Prerequisites
- Installation
- Configuration
- AES Key Generation
- Testing AES Keys
- Encryption/Decryption Scripts
- Usage Examples
- Important Notes
- Troubleshooting
- Security Considerations
- Conclusion
Overview
This guide explains how to use AES keys with your SmartCard HSM (Identiv uTrust 3512) for encryption and decryption operations.
What This Guide Covers
Primary Use Cases:
- File Encryption/Decryption: Encrypt and decrypt files using AES keys stored on the SmartCard HSM. Files are transferred to the HSM token where encryption/decryption operations are performed, ensuring no sensitive data remains on the host system.
- Data Protection: Secure sensitive data with hardware-backed AES encryption
- Key Management: Generate, store, and manage AES keys on the HSM token
- Multi-Token Deployment: Export and import AES keys across multiple SmartCard HSM tokens
Supported Operations:
- AES-CBC encryption and decryption
- AES-CMAC message authentication
- Key wrapping and unwrapping
- Key derivation (SP800-56C)
What This Guide Does NOT Cover:
- RSA or ECC key operations (different guide)
- Key derivation for file encryption
- SSH key management (different use case)
- Certificate operations (separate topic)
Target Applications:
- Data at Rest Protection: Secure storage of sensitive files and databases with hardware-backed encryption
- Secure file storage and transmission
- Database encryption
- Application-level data protection
- Compliance requirements (FIPS, Common Criteria)
[WARNING] CRITICAL SECURITY WARNING: Before using AES keys on your SmartCard HSM, you must verify your firmware version. SmartCard HSM devices with firmware versions 3.1 and 3.2 have a critical bug that generates weak AES keys with little to no entropy. These keys must be considered broken and should not be used for any security operations. Read the advisory.
Required Action: SmartCard HSM and Nitrokey HSM2 - Update to firmware version 3.3 or later via the PKI-as-a-Service Portal before generating or using AES keys.
Note: RSA and ECC keys are not affected by this bug. Only AES key generation is impacted.
Prerequisites
Hardware Requirements
- SmartCard HSM (Identiv uTrust 3512) with firmware version 3.3 or later
- CCID-compatible card reader
- USB connection
Software Requirements
- Linux with PC/SC support
- SmartCard HSM PKCS#11 library (MANDATORY) - OpenSC PKCS#11 library cannot detect or use AES keys on the token
- OpenSC tools (pkcs11-tool)
- SmartCard Shell3 (for AES key generation)
Firmware Verification
Before proceeding, verify your SmartCard HSM firmware version:
pkcs11-tool --module "/home/user/bin/sc-hsm-embedded-2.12/lib/libsc-hsm-pkcs11.so" \
--show-info
Look for the firmware version in the output. If it shows version 3.1 or 3.2, you must update before using AES keys.
Installation
1. Install Development Tools
# Install development tools sudo dnf groupinstall "Development Tools" sudo dnf install autoconf automake libtool sudo dnf install pcsc-lite-devel
2. Download and Compile SmartCard HSM PKCS#11 Library
[WARNING] CRITICAL: The SmartCard HSM PKCS#11 library is MANDATORY for AES key operations. The standard OpenSC PKCS#11 library cannot detect or use AES keys stored on the SmartCard HSM token.
# Download from GitHub releases
cd /tmp
wget https://github.com/CardContact/sc-hsm-embedded/releases/download/v2.12/\
sc-hsm-embedded-2.12.tar.gz
tar -xzf sc-hsm-embedded-2.12.tar.gz
cd sc-hsm-embedded-2.12
# Configure and compile
autoreconf -fi
./configure --prefix=/home/user/bin/sc-hsm-embedded-2.12
make
make check
make install
Configuration
Environment Variables
# Set the module path export SC_HSM_MODULE="/home/user/bin/sc-hsm-embedded-2.12/lib/libsc-hsm-pkcs11.so" export HSM_SLOT=1
Token Detection
Verify your SmartCard HSM is detected using the SmartCard HSM PKCS#11 library (not OpenSC):
pkcs11-tool --module "/home/user/bin/sc-hsm-embedded-2.12/lib/libsc-hsm-pkcs11.so" \
--list-token-slots
Expected output:
Available slots: Slot 0 (0x1): Identiv uTrust 3512 SAM slot Token [CCID Interface] (55512030605) token label : [REDACTED]-HISEC-1 token manufacturer : CardContact (www.cardcontact.de) token model : SmartCard-HSM token flags : login required, rng, token initialized, PIN initialized
AES Key Generation
Important Note: AES Key Generation Method
AES keys on SmartCard HSM are generated and stored using SmartCard Shell3 software, not through direct PKCS#11 operations. The SmartCard Shell3 provides the interface for creating AES keys on the HSM token.
SmartCard Shell3 Requirements
- GUI Version: SmartCard Shell3 GUI (
scsh3gui) is the primary method for AES key generation - CLI Version: SmartCard Shell3 CLI (
scsh3) has known card detection issues (see separate documentation) - Key Management: Keys are created through the SmartCard Shell3 Key Manager interface
Key Generation Process
- Launch SmartCard Shell3 GUI:
cd /home/user/CardContact/scsh/scsh-3.18.55/ ./scsh3gui
- Authenticate to the HSM:
- Select your SmartCard HSM token
- Enter your User PIN when prompted
- Access Key Manager:
- Navigate to the Key Manager in the SmartCard Shell3 interface
- Right-click on the appropriate key domain (e.g., DKEK share)
- Generate AES Key (presumably on the DKEK share):
- Select "Generate Key" → "AES"
- Choose key size (128, 192, or 256 bits)
- Provide a label for the key
- Select algorithms (AES-CBC, AES-CMAC, etc.)
Exporting AES Keys for Multiple Tokens
If you need to use the same AES key across multiple SmartCard HSM tokens that share the same DKEK, you can export the key:
- In the SmartCard Shell3 GUI, click on the AES key object in the list (PIN required)
- Right-click on the key and select "Wrap Key (and Certificate)"
- Save the key as a
*.wkyfile - Import the
*.wkyfile on other tokens with the same DKEK share
Verifying Generated Keys
After generating AES keys via SmartCard Shell3, you can verify them using PKCS#11 tools, as shown below.
Testing AES Keys
List All AES Keys
Use the following script to list all AES keys on your token:
[WARNING] IMPORTANT: You may need to modify the following variables in the script to match your setup:
HSM_SLOT: The slot number where your SmartCard HSM is detectedSC_HSM_MODULE: Path to your SmartCard HSM PKCS#11 library
Save this script as list_aes_keys.sh:
#!/bin/bash
# list_aes_keys.sh
set -e
# Configuration
SC_HSM_MODULE="/home/user/bin/sc-hsm-embedded-2.12/lib/libsc-hsm-pkcs11.so"
HSM_SLOT=1
echo "=== AES Keys on SmartCard HSM ==="
echo "Library: $SC_HSM_MODULE"
echo "Slot: $HSM_SLOT"
echo
echo "Please enter your SmartCard HSM PIN when prompted:"
# List all secret key objects
echo "=== All Secret Key Objects ==="
pkcs11-tool --module "$SC_HSM_MODULE" \
--slot $HSM_SLOT \
--login \
--list-objects \
--type secrkey
echo
echo "=== Summary ==="
echo "The above shows all secret key objects on your SmartCard HSM token."
echo "Look for entries starting with 'Secret Key Object; AES' to find AES keys."
echo "Each AES key will show:"
echo "- Label (name)"
echo "- ID (unique identifier)"
echo "- Usage (encrypt, decrypt)"
echo "- Access (security attributes)"
echo
Usage:
chmod +x list_aes_keys.sh ./list_aes_keys.sh
Expected Output:
Secret Key Object; AES length 32 label: AES-1 ID: b20ba7e28e29c90f Usage: encrypt, decrypt Access: sensitive, always sensitive, never extractable, local Secret Key Object; AES length 32 label: AES-2 ID: 4eaa8024a063e8b6 Usage: encrypt, decrypt Access: sensitive, always sensitive, never extractable, local
Encryption/Decryption Scripts
Simple AES Encryption Test
Save this script as aes_encrypt_simple.sh:
#!/bin/bash
# aes_encrypt_simple.sh
set -e
# Configuration
# [WARNING] IMPORTANT: Modify these variables to match your setup
SC_HSM_MODULE="/home/user/bin/sc-hsm-embedded-2.12/lib/libsc-hsm-pkcs11.so"
HSM_SLOT=1
AES_KEY_ID="b20ba7e28e29c90f" # Use the ID from your AES key
echo "=== Simple AES-1 Encryption Test ==="
echo "Library: $SC_HSM_MODULE"
echo "Slot: $HSM_SLOT"
echo "Key ID: $AES_KEY_ID"
echo
# Create a test file with exactly 16 bytes (AES block size)
echo "Creating test data..."
echo -n "1234567890123456" > test_block.txt
echo "[INFO] Created test file with 16 bytes (AES block size)"
# Generate IV
echo "Generating IV..."
openssl rand -hex 16 > iv.txt
IV=$(cat iv.txt)
echo "[INFO] IV: $IV"
echo
echo "=== Attempting AES-CBC Encryption ==="
echo "Please enter your SmartCard HSM PIN when prompted:"
# Try encryption with the exact block size
pkcs11-tool --module "$SC_HSM_MODULE" \
--slot $HSM_SLOT \
--login \
--encrypt \
--mechanism AES-CBC \
--iv "$IV" \
--input-file test_block.txt \
--output-file test_block.enc \
--id "$AES_KEY_ID"
if [ $? -eq 0 ]; then
echo "[SUCCESS] Encryption completed!"
echo "[INFO] Encrypted file: test_block.enc"
echo "[INFO] IV saved to: iv.txt"
else
echo "[ERROR] Encryption failed"
fi
echo
echo "=== Test Complete ==="
Simple AES Decryption Test
Save this script as aes_decrypt_simple.sh:
#!/bin/bash
# aes_decrypt_simple.sh
set -e
# Configuration
# [WARNING] IMPORTANT: Modify these variables to match your setup
SC_HSM_MODULE="/home/user/bin/sc-hsm-embedded-2.12/lib/libsc-hsm-pkcs11.so"
HSM_SLOT=1
AES_KEY_ID="b20ba7e28e29c90f" # Use the ID from your AES key
echo "=== Simple AES-1 Decryption Test ==="
echo "Library: $SC_HSM_MODULE"
echo "Slot: $HSM_SLOT"
echo "Key ID: $AES_KEY_ID"
echo
# Check if encrypted file exists
if [ ! -f test_block.enc ]; then
echo "[ERROR] Encrypted file not found: test_block.enc"
echo "Please run aes_encrypt_simple.sh first"
exit 1
fi
# Check if IV file exists
if [ ! -f iv.txt ]; then
echo "[ERROR] IV file not found: iv.txt"
echo "Please run aes_encrypt_simple.sh first"
exit 1
fi
IV=$(cat iv.txt)
echo "[INFO] Using IV: $IV"
echo
echo "=== Attempting AES-CBC Decryption ==="
echo "Please enter your SmartCard HSM PIN when prompted:"
# Try decryption
pkcs11-tool --module "$SC_HSM_MODULE" \
--slot $HSM_SLOT \
--login \
--decrypt \
--mechanism AES-CBC \
--iv "$IV" \
--input-file test_block.enc \
--output-file test_block.dec \
--id "$AES_KEY_ID"
if [ $? -eq 0 ]; then
echo "[SUCCESS] Decryption completed!"
echo "[INFO] Decrypted file: test_block.dec"
# Verify decryption
if diff test_block.txt test_block.dec > /dev/null; then
echo "[SUCCESS] Decryption verified - files match!"
else
echo "[ERROR] Decryption failed - files don't match"
fi
else
echo "[ERROR] Decryption failed"
fi
echo
echo "=== Test Complete ==="
Complete AES Key Usage Script
Save this script as aes_encrypt_decrypt.sh:
#!/bin/bash
# Use the AES-1 key on SmartCard HSM for encryption/decryption
# The key was found with the new SmartCard HSM PKCS#11 library
set -e
# Configuration
# [WARNING] IMPORTANT: Modify these variables to match your setup
SC_HSM_MODULE="/home/user/bin/sc-hsm-embedded-2.12/lib/libsc-hsm-pkcs11.so"
HSM_SLOT=1
AES_KEY_LABEL="AES-1" # Use the label from your AES key
AES_KEY_ID="b20ba7e28e29c90f" # Use the ID from your AES key
echo "=== Using AES-1 Key on SmartCard HSM ==="
echo "Library: $SC_HSM_MODULE"
echo "Slot: $HSM_SLOT"
echo "Key Label: $AES_KEY_LABEL"
echo "Key ID: $AES_KEY_ID"
echo
# Function to encrypt a file using AES-1 key
encrypt_file() {
local input_file="$1"
local output_file="$2"
echo "=== Encrypting with AES-1 Key ==="
echo "Input: $input_file"
echo "Output: $output_file"
echo "Please enter your SmartCard HSM PIN when prompted:"
# Generate a random IV (16 bytes for AES)
echo "[INFO] Generating random IV..."
openssl rand -hex 16 > iv.txt
IV=$(cat iv.txt)
echo "[INFO] IV: $IV"
# Use AES-CBC encryption with the AES-1 key and IV
pkcs11-tool --module "$SC_HSM_MODULE" \
--slot $HSM_SLOT \
--login \
--encrypt \
--mechanism AES-CBC \
--iv "$IV" \
--input-file "$input_file" \
--output-file "$output_file" \
--id "$AES_KEY_ID"
if [ $? -eq 0 ]; then
echo "[SUCCESS] File encrypted successfully"
echo "[INFO] IV saved to iv.txt for decryption"
else
echo "[ERROR] Encryption failed"
rm -f iv.txt
return 1
fi
}
# Function to decrypt a file using AES-1 key
decrypt_file() {
local input_file="$1"
local output_file="$2"
local iv_file="${3:-iv.txt}"
echo "=== Decrypting with AES-1 Key ==="
echo "Input: $input_file"
echo "Output: $output_file"
echo "IV file: $iv_file"
echo "Please enter your SmartCard HSM PIN when prompted:"
if [ ! -f "$iv_file" ]; then
echo "[ERROR] IV file not found: $iv_file"
echo "Please provide the IV used for encryption"
return 1
fi
IV=$(cat "$iv_file")
echo "[INFO] Using IV: $IV"
# Use AES-CBC decryption with the AES-1 key and IV
pkcs11-tool --module "$SC_HSM_MODULE" \
--slot $HSM_SLOT \
--login \
--decrypt \
--mechanism AES-CBC \
--iv "$IV" \
--input-file "$input_file" \
--output-file "$output_file" \
--id "$AES_KEY_ID"
if [ $? -eq 0 ]; then
echo "[SUCCESS] File decrypted successfully"
else
echo "[ERROR] Decryption failed"
return 1
fi
}
# Function to test the AES-1 key with a simple operation
test_aes1_key() {
echo "=== Testing AES-1 Key ==="
echo "Please enter your SmartCard HSM PIN when prompted:"
# Try to get key info
pkcs11-tool --module "$SC_HSM_MODULE" \
--slot $HSM_SLOT \
--login \
--list-objects \
--type secrkey \
--id "$AES_KEY_ID"
}
# Function to show usage
show_usage() {
echo "Usage: $0 {encrypt|decrypt|test} [ ]"
echo
echo "Examples:"
echo " $0 test # Test AES-1 key"
echo " $0 encrypt test.txt test.txt.enc # Encrypt file"
echo " $0 decrypt test.txt.enc test.txt.dec [iv.txt] # Decrypt file"
echo
echo "The script uses the AES-1 key stored on your SmartCard HSM"
echo "for AES-CBC encryption/decryption operations."
}
# Main script logic
case "${1:-}" in
encrypt)
if [ $# -ne 3 ]; then
echo "[ERROR] Usage: $0 encrypt "
exit 1
fi
encrypt_file "$2" "$3"
;;
decrypt)
if [ $# -lt 3 ] || [ $# -gt 4 ]; then
echo "[ERROR] Usage: $0 decrypt [iv_file]"
exit 1
fi
decrypt_file "$2" "$3" "${4:-}"
;;
test)
test_aes1_key
;;
*)
show_usage
exit 1
;;
esac
echo
echo "=== Operation Complete ==="
Usage Examples
1. List AES Keys
./list_aes_keys.sh
2. Test Simple Encryption/Decryption
# Encrypt ./aes_encrypt_simple.sh # Decrypt ./aes_decrypt_simple.sh
3. Use Complete Script
# Test key ./aes_encrypt_decrypt.sh test # Encrypt file ./aes_encrypt_decrypt.sh encrypt myfile.txt myfile.txt.enc # Decrypt file ./aes_encrypt_decrypt.sh decrypt myfile.txt.enc myfile.txt.dec
Important Notes
Data Requirements
- Block Size: Data must be padded to AES block size (16 bytes)
- IV Required: CBC mode requires an Initialization Vector
- PIN Authentication: All operations require SmartCard HSM PIN
Security Features
- Hardware Protection: Keys never leave the HSM in plaintext
- PIN Protection: All operations require authentication
- Key Export: Keys can be exported only between tokens sharing the same DKEK share
Supported Operations
- AES-CBC Encryption/Decryption
- AES-CMAC Signing
- AES Key Generation (via SmartCard Shell3 GUI only)
Firmware Security Considerations
[WARNING] Critical HSM Firmware Bug (Versions 3.1-3.2):
- SmartCard HSM and Nitrokey HSM2 devices with firmware versions 3.1 and 3.2 generate weak AES keys. Read the advisory.
- These keys have little to no entropy and must be considered broken
- Impact: Only affects AES key generation, not RSA or ECC keys
- Solution: Be sure the tokens are running the latest firmware version. Check if newer version is available at PKI-as-a-Service-Portal, and install it before generating or using AES keys.
Update Process:
- Register an account at CardContact Developer Network (CDN)
- Create a firmware update request
- Select "Current token in reader" and submit
- Follow the portal instructions for the update process
- Important: All keys must be removed before firmware update
- After update, reinitialize the device and restore keys
Troubleshooting
Common Issues
- "CKR_FUNCTION_NOT_SUPPORTED"
- Ensure data is padded to 16-byte blocks
- Use exact block size for testing
- "CKR_USER_NOT_LOGGED_IN"
- Enter PIN when prompted
- Don't redirect output during PIN prompts
- "CKR_SLOT_ID_INVALID"
- Use slot 1 instead of slot 0
- Verify token is present
Security Considerations
Direct AES Storage vs Key Derivation
| Aspect | Direct AES Storage | HSM Key Derivation |
|---|---|---|
| Key Storage | AES key stored on HSM | Salt stored on disk, key derived on-demand |
| Intermediate Data | None | Salt file, derived key file |
| Cold Boot Vulnerability | Low (no temp files) | Medium (temp files on disk) |
| Performance | Fast (direct operations) | Slower (derivation + operation) |
| Flexibility | Fixed key | Variable key from passphrase |
Best Practices
- Authentication: Always authenticate before operations
- Data Padding: Ensure data fits AES block requirements
- IV Management: Use random IVs and store them securely
- Error Handling: Check return codes and handle failures
- Cleanup: Remove temporary files securely
Conclusion
This guide provides a complete workflow for using AES keys with your SmartCard HSM. The approach offers hardware-level security with direct AES operations, making it suitable for high-security applications where key protection is critical.
Technical Summary
- AES Key Generation: SmartCard Shell3 GUI required for key generation; PKCS#11 direct operations not supported
- Firmware Security: Version 3.3+ mandatory due to weak key generation vulnerability in versions 3.1-3.2
- Security Architecture: Hardware-protected AES keys with mandatory PIN authentication for all operations
- CLI Implementation: SmartCard Shell3 CLI exhibits card detection failures due to initialization sequence differences
- Firmware Update Protocol: Requires complete key removal and device reinitialization post-update
