paysec-pinblock
ISO 9564 PIN-block functionality for payment-security applications.
The crate provides PIN modeling and PIN-block processing while keeping cryptographic operations separate from PIN-block format logic.
Supported functionality
The current implementation includes:
- ISO 9564 Format 3 PIN blocks
- ISO 9564 Format 4 PIN blocks
- PIN validation
- PAN processing and binding
- AES-based Format 4 enciphering and deciphering
- provider-independent cryptographic operations
- support for software and PKCS #11-backed AES providers
- zeroizing plaintext PIN storage
Installation
Using the RustCrypto software provider:
[]
= "0.4"
= "0.3.1"
= "0.3"
Using the PKCS #11 provider with an HSM or compatible token:
[]
= "0.3.1"
= "0.1"
Applications that need common cryptographic types or traits can also depend
directly on paysec-crypto.
ISO 9564 Format 4 example
The following example enciphers and then deciphers an ISO 9564 Format 4 PIN block using the RustCrypto provider:
use RustCryptoProvider;
use ;
let provider = new;
let key = decode
.unwrap;
let pin = "1234";
let pan = "1234567890123456789";
let random_seed = vec!;
let pin_block = encipher_pinblock_iso_4
.unwrap;
assert_eq!;
let recovered_pin = decipher_pinblock_iso_4
.unwrap;
assert_eq!;
Cryptographic providers
ISO 9564 Format 4 cryptographic processing is expressed through the
AesBlockCipher<K> capability defined by paysec-crypto.
The key representation is therefore provider-specific.
Software providers
Software providers such as paysec-crypto-rustcrypto and
paysec-crypto-soft-aes operate on raw AES key material supplied by the
application.
PKCS #11 provider
paysec-crypto-pkcs11 implements the required AES block capability for opaque
Pkcs11Key references.
This allows the AES key used for Format 4 enciphering and deciphering to remain as an existing PKCS #11 secret-key object rather than being supplied to the application as raw key bytes.
For example, the provider and key can be configured independently of the PIN-block operation:
use ;
let config = new;
let auth = user_pin;
let provider = connect?;
let key = by_id;
The resulting provider and key can be passed to the same Format 4 API used
with software providers.
The PKCS #11 provider uses the token's AES primitive internally and does not read the persistent AES key value into the application.
Actual support depends on the selected PKCS #11 token and its configured key attributes.
PIN handling
Decoded or deciphered plaintext PINs are represented by Pin.
Pin:
- accepts 4 to 12 ASCII decimal digits
- redacts its contents from
Debug - zeroizes its owned memory when dropped
- requires explicit access through
expose_secret()
Temporary plaintext buffers used internally in sensitive processing paths are also zeroized where practical.
These protections reduce accidental disclosure and residual process-memory contents, but they do not guarantee that secret values have never existed elsewhere in memory.
Randomness
ISO 9564 Format 4 PIN-field construction requires caller-supplied random data.
The crate deliberately does not select a random-number generator internally. This supports deterministic standards testing and leaves entropy generation under application or provider control.
Production applications are responsible for supplying randomness appropriate for their security requirements.
A PKCS #11-backed application can, for example, obtain random bytes from a
provider implementing RandomBytes, but randomness remains an explicit input
to the PIN-block API rather than being generated internally by this crate.
Security
PINs and plaintext PIN-block data are sensitive payment-authentication data. Applications must apply the operational and security controls required by their environment.
When a software cryptographic provider is used, AES key material is generally present in application memory.
When paysec-crypto-pkcs11 is used, the persistent AES key can remain inside
the selected PKCS #11 token and be referenced through an opaque Pkcs11Key.
This does not make the entire PIN-block operation HSM-contained. PIN values, PAN data, Format 4 intermediate data, caller-supplied randomness, and the resulting encrypted PIN block are processed by the application as required by the current API.
Whether a PKCS #11 key is actually non-exportable depends on the token, key
attributes, and provisioning process. Use of Pkcs11Provider alone does not
establish that a key was securely generated or configured as
non-extractable.
Using this crate does not by itself establish PCI or ISO compliance.
For the complete project overview, see the
paysec repository.