client: document wiegand layer and improve online tests

Add inline comments throughout wiegand_formatutils and callers to explain
sentinel-bit stripping, HID transport framing, and the normalization contract
between input modes and downstream consumers.

Replace sim-only LF HID online tests with T55xx clone+readback flows and add
a full encode/decode roundtrip harness for hf mf encodehid, including sector
restore/cleanup and an optional --manual flag for external reader verification.
This commit is contained in:
CinderSocket committed 2026-03-17 16:45:14 -07:00
1 parent 2c403e157d
commit 6639009681
5 files changed
+276 -18

No files matched your search

+6
View File
@@ -10045,6 +10045,8 @@ static int CmdHF14AMfValue(const char *Cmd) {
return PM3_SUCCESS;
}
// Encode the normalized Wiegand payload into the sentinel-prefixed byte layout stored in
// the HID-specific MIFARE payload block.
static int hfmf_encodehid_pack_block5(const char *binstr, uint8_t *block) {
if (binstr == NULL || block == NULL) {
return PM3_EINVARG;
@@ -10057,6 +10059,8 @@ static int hfmf_encodehid_pack_block5(const char *binstr, uint8_t *block) {
return PM3_EINVARG;
}
// MIFARE block 5 stores the Wiegand payload with the same sentinel-prefixed layout
// expected by existing HID cards: one leading 1 followed by the logical payload bits.
bits_with_sentinel[0] = '1';
memcpy(bits_with_sentinel + 1, binstr, binlen + 1);
@@ -10182,6 +10186,8 @@ static int CmdHFMFHidEncode(const char *Cmd) {
return res;
}
// Unlike LF HID transport, block 5 only needs the normalized bitstring. Raw/new/formatted
// inputs all converge here after the shared Wiegand layer has stripped transport framing.
if (hfmf_encodehid_pack_block5(input.binstr, card_blocks + (MFBLOCK_SIZE * 4)) != PM3_SUCCESS) {
PrintAndLogEx(ERR, "Encoded Wiegand payload is too large to fit in the MIFARE payload");
return PM3_EINVARG;
+8
View File
@@ -59,7 +59,11 @@ typedef struct {
int new_pacs_len;
} lf_hid_cli_input_t;
// Enforce the narrower LF HID transport limits after the shared Wiegand layer has
// normalized whichever user-facing input mode was selected.
static int lf_hid_validate_packed_transport(const wiegand_input_t *input, const char *command_name) {
// The shared Wiegand layer can normalize credentials that are wider than the LF HID
// transport. Reject only when this specific command needs a packed HID frame.
if (input->packed_valid == false) {
PrintAndLogEx(ERR, "Credential encoded successfully, but %" PRIuMAX "-bit Wiegand data cannot be represented as a packed HID credential", (uintmax_t)input->bin_len);
PrintAndLogEx(ERR, "Packed HID encoding supports up to 84 Wiegand bits");
@@ -80,6 +84,8 @@ static int lf_hid_validate_packed_transport(const wiegand_input_t *input, const
return PM3_SUCCESS;
}
// Resolve the CLI's mutually exclusive HID input modes into one normalized representation
// that downstream sim/clone code can consume without caring about the original encoding.
static int lf_hid_resolve_input(const lf_hid_cli_input_t *cli, wiegand_input_t *input, int *format_idx) {
int input_modes = 0;
input_modes += (cli->raw_len > 0);
@@ -101,6 +107,8 @@ static int lf_hid_resolve_input(const lf_hid_cli_input_t *cli, wiegand_input_t *
return PM3_EINVARG;
}
// Normalize every accepted CLI form into the same wiegand_input_t so sim/clone can
// share validation and transport handling regardless of where the credential came from.
if (cli->raw_len) {
return wiegand_pack_from_raw_hid(cli->raw, cli->raw_len, input);
}
+10 -2
View File
@@ -244,6 +244,8 @@ bool wiegand_raw_to_binstr(const uint8_t *raw, size_t raw_len, char *binstr, siz
bytes_2_binstr(binstr, raw, raw_len);
// Raw HID transport embeds a leading sentinel/start bit before the actual Wiegand payload.
// Strip that prefix so every caller downstream sees only the logical payload bits.
char *sentinel = strchr(binstr, '1');
if (sentinel == NULL || sentinel[1] == '\0') {
return false;
@@ -271,6 +273,7 @@ bool wiegand_new_pacs_to_binstr(const uint8_t *pacs, size_t pacs_len, char *bins
bytes_2_binstr(binstr, pacs + 1, payload_len);
// The first PACS byte stores how many zero padding bits were added to the final octet.
size_t trimmed_len = strlen(binstr);
if (pacs[0] >= trimmed_len) {
return false;
@@ -289,6 +292,7 @@ int wiegand_pack_bin_with_hid_header(const char *binstr, wiegand_message_t *pack
uint8_t hex[12] = {0};
BitstreamOut_t bout = {hex, 0, 0};
// HID transport stores the payload right-aligned behind a sentinel bit inside a 96-bit frame.
for (size_t i = 0; i < (96 - bin_len - 1); i++) {
pushBit(&bout, 0);
}
@@ -359,6 +363,8 @@ int wiegand_pack_from_plain_bin(const char *binstr, wiegand_input_t *input) {
return res;
}
// Plain binary input is still useful to non-HID callers above 84 bits, even though it
// can no longer be repacked into the legacy HID transport words.
if (input->bin_len > 84) {
input->packed_valid = false;
return PM3_SUCCESS;
@@ -375,6 +381,7 @@ int wiegand_pack_from_new_pacs(const uint8_t *pacs, size_t pacs_len, wiegand_inp
return res;
}
// New PACS can represent longer credentials than packed HID transport can carry.
if (input->bin_len > 84) {
input->packed_valid = false;
return PM3_SUCCESS;
@@ -422,8 +429,9 @@ int wiegand_pack_from_raw_hid(const uint8_t *raw, size_t raw_len, wiegand_input_
memcpy(aligned + (sizeof(aligned) - raw_len), raw, raw_len);
input->packed = initialize_message_object(bytes_to_num(aligned, 4), bytes_to_num(aligned + 4, 4), bytes_to_num(aligned + 8, 4), 0);
// Raw HID input preserves legacy behavior: transport words are populated, but
// packed Wiegand length is left unset because this path does not repack data.
// Raw HID input preserves legacy behavior by keeping the transport words exactly as
// provided. The packed length is then derived from the embedded HID header bits
// instead of being recomputed by repacking the normalized payload bitstring.
input->packed_valid = true;
return PM3_SUCCESS;
}
+24 -2
View File
@@ -45,8 +45,8 @@ typedef struct {
typedef struct {
size_t bin_len;
char binstr[145];
bool packed_valid;
wiegand_message_t packed;
bool packed_valid; // False when the input has a valid bitstring but no packed HID transport form.
wiegand_message_t packed; // HID transport words used by LF/HID-oriented callers.
} wiegand_input_t;
uint8_t get_bit_by_position(const wiegand_message_t *data, uint8_t pos);
@@ -62,16 +62,38 @@ wiegand_message_t initialize_message_object(uint32_t top, uint32_t mid, uint32_t
uint8_t get_length_from_header(const wiegand_message_t *data);
bool add_HID_header(wiegand_message_t *data);
// Render a packed Wiegand message as a plain payload bitstring without HID transport framing.
bool wiegand_message_to_binstr(const wiegand_message_t *packed, char *binstr, size_t binstr_size);
// Decode raw HID transport bytes into a plain Wiegand payload bitstring.
bool wiegand_raw_to_binstr(const uint8_t *raw, size_t raw_len, char *binstr, size_t binstr_size);
// Decode the ASN.1 PACS form emitted by `wiegand encode --new` into a plain payload bitstring.
bool wiegand_new_pacs_to_binstr(const uint8_t *pacs, size_t pacs_len, char *binstr, size_t binstr_size);
// Validate and store a caller-provided binary Wiegand payload without attempting transport packing.
int wiegand_set_plain_binstr(const char *binstr, wiegand_input_t *input);
// Decode ASN.1 PACS input into the normalized binary representation used by downstream callers.
int wiegand_set_new_pacs_binstr(const uint8_t *pacs, size_t pacs_len, wiegand_input_t *input);
// Build HID transport words from a plain Wiegand payload, including sentinel placement and headers.
int wiegand_pack_bin_with_hid_header(const char *binstr, wiegand_message_t *packed);
// Encode a card-format struct through the existing HID formatter and return packed transport words.
int wiegand_pack_formatted(int format_idx, wiegand_card_t *card, bool preamble, wiegand_message_t *packed);
// Normalize ASN.1 PACS input and, when possible, also derive HID transport words for LF/HID callers.
int wiegand_pack_from_new_pacs(const uint8_t *pacs, size_t pacs_len, wiegand_input_t *input);
// Normalize plain binary input and, when possible, also derive HID transport words for LF/HID callers.
int wiegand_pack_from_plain_bin(const char *binstr, wiegand_input_t *input);
// Normalize formatted card data into both payload bits and packed transport words.
int wiegand_pack_from_formatted(int format_idx, wiegand_card_t *card, bool preamble, wiegand_input_t *input);
// Preserve legacy raw HID transport input while also exposing the decoded payload bitstring.
int wiegand_pack_from_raw_hid(const uint8_t *raw, size_t raw_len, wiegand_input_t *input);
#endif