Skip to main content

Module ciphering

Module ciphering 

Source
Expand description

Service-specific glo-/ded-ciphering of xDLMS APDUs (IEC 62056-5-3, 5.7).

A ciphered APDU has the form

tag | length | SC | IC | [ciphertext] | [tag]

where the security header SC ‖ IC is the 1-octet security control byte and the 4-octet invocation counter. The initialization vector is system-title ‖ IC, the block cipher key is the (global or dedicated) encryption key EK, and — when authentication is applied — the additional authenticated data is SC ‖ AK (authenticated encryption) or SC ‖ AK ‖ plaintext (authentication only). The GCM tag is truncated to 12 octets (security suite 0, AES-GCM-128).

For GOST ciphering (Р 1323565.1), Kuznyechik CTR+CMAC is used with a 16-byte CMAC tag.

Validated against the authenticated-encryption test vector of IEC 62056-5-3 Annex E.5.

Modules§

ded
Ciphered-APDU tags for service-specific dedicated ciphering.
glo
Ciphered-APDU tags for service-specific global ciphering.
security_control
Bit masks of the security control byte (SC), IEC 62056-5-3 Table 27.

Structs§

SecurityContext
The security material and parameters for one ciphering operation.

Enums§

CipherError
Errors from ciphering / deciphering.

Constants§

GOST_SUITE_ID
GOST security suite identifier (Р 1323565.1, suite id = 0x0D).

Functions§

build_gmac_counter 🔒
Builds the 128-bit counter block for GOST GMAC. The counter is IV (12 bytes) || 0x00000001 (4 bytes).
build_gost_nonce 🔒
Builds a 16-byte nonce from the 12-byte IV (system_title ‖ IC). The GOST CTR mode uses a 128-bit block, so we extend the 96-bit IV with zeros to form the counter initial value.
gcm_decrypt 🔒
Decrypts ct and verifies the 12-octet tag, returning the plaintext.
gcm_decrypt_no_tag 🔒
Decrypts buf in place with encryption only (no tag verification): recompute the keystream by “encrypting” against an all-zero tag placeholder is not possible, so decrypt with a throwaway tag over empty AAD via GCM’s CTR core.
gcm_encrypt_in_place 🔒
Encrypts buf in place and returns the 12-octet authentication tag.
ghash_subkey 🔒
GHASH subkey derivation for CMAC (doubles the block in GF(2^128)).
gost_cmac_tag 🔒
Kuznyechik CMAC tag computation (16 bytes). Implements CMAC manually using Kuznyechik block cipher (GOST R 34.13-2015).
gost_ctr_decrypt 🔒
Kuznyechik CTR-mode decryption (same as encryption for CTR).
gost_ctr_encrypt 🔒
Kuznyechik CTR-mode encryption.
gost_gmac_decrypt
GOST GMAC decryption (CTR mode) for use with GMAC authentication.
gost_gmac_encrypt
GOST GMAC encryption (CTR mode) for use with GMAC authentication.
gost_gmac_protect
Protects an APDU using GOST GMAC (Kuznyechik GCM-like mode).
gost_gmac_tag
GOST GMAC: Kuznyechik in GCM-like mode (CTR + GHASH).
gost_gmac_unprotect
Removes GOST GMAC protection from an APDU. Rejects a replayed or reordered-backward invocation counter before any decryption is attempted; see unprotect.
gost_protect
GOST-authenticated encryption using Kuznyechik CTR+CMAC (Р 1323565.1).
gost_unprotect
Removes GOST ciphering from an APDU, returning (ciphered_tag, plaintext). Rejects a replayed or reordered-backward invocation counter before any decryption is attempted; see unprotect.
increment_counter 🔒
Increments a 128-bit counter in big-endian.
is_gost_suite
Checks if the security control byte indicates a GOST suite.
protect
Protects plaintext (a plain xDLMS APDU) and returns the ciphered APDU with the given ciphered_tag (see glo / ded).
push_length 🔒
Writes a BER length octet (short or long form).
read_length 🔒
unprotect
Removes protection from a ciphered APDU, returning (ciphered_tag, plaintext).
xor_blocks 🔒
XOR two 16-byte blocks.

Type Aliases§

Aes128Gcm12 🔒
AES-128-GCM with a 96-bit (12-octet) authentication tag.
Aes256Gcm12 🔒
AES-256-GCM with a 96-bit (12-octet) authentication tag.
KuznyechikCmac 🔒
Kuznyechik CMAC type (used internally).