Thales Key Block Format: Header, TLV & TR-31 Comparison

Thales key blocks are a proprietary format used by Thales payShield HSMs to securely store and transport cryptographic keys. While TR-31 is the industry standard, Thales key blocks remain widely deployed. This guide explains the format structure, header layout, and how it differs from TR-31.

What is a Thales Key Block?

A Thales key block is a structured container that wraps a cryptographic key with metadata, integrity checks, and encryption. It provides:

• Key encryption under LMK variants
• Key type identification
• Integrity verification
• Format versioning

Where Thales Key Blocks Are Used

• Thales payShield 10K and older models
• Payment processing networks
• ATM key management
• Inter-bank key exchange
• Legacy payment infrastructure

Thales Key Block Structure

A Thales key block has a specific layout:

+------------------+
| Header           |  2 bytes: version + key type
+------------------+
| Key Length       |  2 bytes: length of encrypted key
+------------------+
| Encrypted Key    |  Variable: key under LMK variant
+------------------+
| KCV              |  3 bytes: Key Check Value
+------------------+
| Padding          |  Optional: for alignment
+------------------+

Header Format

The header identifies the key block format and key type:

Key Type Codes

Header Deep Dive

Version Byte

The version byte indicates the format version:

Key Length Encoding

Key length is encoded as 2 bytes, big-endian:

0x0010 = 16 bytes (double-length key)
0x0018 = 24 bytes (triple-length key)

Encrypted Key Section

The encrypted key is the core of the key block.

LMK Variant Encryption

Keys are encrypted under LMK variants:

Encrypted Key = E(LMK XOR variant, plaintext_key)

Different key types use different variants (see our Thales LMK guide).

Key Padding

Keys may be padded to meet alignment requirements:

• DES keys: 8-byte aligned
• AES keys: 16-byte aligned

Key Check Value (KCV)

The KCV at the end of the key block serves as an integrity check.

KCV Calculation

Standard method:

KCV = First 3 bytes of E(Key, 0000000000000000)

KCV Purpose

• Verify key integrity after import
• Confirm keys match during exchange
• Detect corruption during transmission

TLV Structure

Some Thales key blocks use a Tag-Length-Value (TLV) structure for extended attributes.

TLV Format

Tag (1-2 bytes) | Length (1-2 bytes) | Value (variable)

Common Tags

Thales Key Block vs TR-31

Understanding the differences is important for migration and interoperability.

Format Comparison

Attribute Comparison

Migration Considerations

When migrating from Thales to TR-31:

1. Map key type codes to TR-31 usage codes
2. Add algorithm attributes
3. Set exportability flags
4. Regenerate key blocks in TR-31 format
5. Verify KCVs after conversion

Practical Scenarios

Key Import

Importing a Thales key block:

1. Parse header to get key type
2. Extract encrypted key
3. Decrypt under appropriate LMK variant
4. Re-encrypt for storage
5. Verify KCV

Key Export

Exporting a key as Thales key block:

1. Get key type from request
2. Decrypt key from storage
3. Encrypt under target LMK variant
4. Build header with key type
5. Calculate KCV
6. Assemble key block

Key Exchange

Exchanging Thales key blocks between HSMs:

1. Export key block from source HSM
2. Transmit key block (secure channel)
3. Import into destination HSM
4. Destination verifies KCV
5. Both sides now have same key

Common Issues

Version Mismatch

If importing fails:

• Check version byte compatibility
• Ensure HSM supports the version
• May need to downgrade format

Key Type Confusion

Wrong key type causes:

• Decryption failure (wrong variant)
• KCV mismatch
• Operational errors

Length Errors

Common length issues:

• Wrong endianness
• Including/excluding padding
• Header length miscount

Best Practices

1. Always verify KCV after key import
2. Document key types used in your system
3. Use consistent format across HSMs
4. Plan migration to TR-31 for future-proofing
5. Test key exchange before production

Try It Yourself

Use our Thales Key Block tool to:

• Parse Thales key block headers
• Extract key type and length
• Understand TLV structure
• Compare with TR-31 format

The tool runs entirely in your browser — no data leaves your device.