This analysis breaks down the reverse engineering of the ZKTeco Standalone SDK protocol in pure userland PHP 8. We examine the exact wire layout, the 16-bit One's Complement Checksum algorithm, session authentication scrambling, and the mechanics of writing punch records directly into physical machine flash memory via command CMD_SET_DATA (3001). The package requires PHP ext-sockets and ext-json but no separate vendor SDK, background daemon, or Windows DLL (no zkemkeeper.dll).

The ZKTeco Binary Protocol Architecture

ZKTeco terminals use a custom binary protocol operating over port 4370. Every communication packet contains an 8-byte fixed header followed by optional variable-length command payloads.

The 8-Byte Packet Header Structure

The 16-Bit One's Complement Checksum

The checksum algorithm calculates a 16-bit one's complement addition across 16-bit words, mirroring the classic RFC 1071 Internet checksum algorithm.

Here is the exact algorithmic implementation in modern PHP:

function calculateZkChecksum(string $packet): int
{
    $length = strlen($packet);
    $chksum = 0;
    $i = 0;

    // Sum 16-bit little-endian words
    while ($length > 1) {
        $word = ord($packet[$i]) + (ord($packet[$i + 1]) << 8);
        $chksum += $word;
        $i += 2;
        $length -= 2;
    }

    // Add remaining byte if odd length
    if ($length > 0) {
        $chksum += ord($packet[$i]);
    }

    // Fold 32-bit sum into 16 bits
    while ($chksum >> 16) {
        $chksum = ($chksum & 0xFFFF) + ($chksum >> 16);
    }

    // Bitwise NOT mask
    return (~$chksum) & 0xFFFF;
}

During packet generation, bytes 2..3 are zeroed out while calculating the checksum. Once calculated, the resulting integer is packed as unsigned 16-bit little-endian (v in PHP pack()) and inserted into bytes 2..3.

TCP Stream Framing Overcoming Packet Boundaries

In raw UDP, each socket_recvfrom() call returns a discrete datagram. In TCP, data arrives as a continuous stream. If a server queries 5,000 attendance records, the hardware sends consecutive packets back-to-back. Without framing, a standard socket read will split packets midway through a record or merge two headers together.

To enforce boundaries over TCP stream sockets, taha-rafi/php-zkteco wraps the packet inside an 8-byte envelope:

[ 4 Bytes Magic Header: \x50\x50\x82\x7d ] + [ 4 Bytes Payload Length LE ] + [ Raw ZK Packet ]

When reading from the socket, the client reads exactly 8 bytes first, extracts the 32-bit payload length, and then loops with socket_recv() until that exact payload length is consumed. This guarantees zero byte alignment corruption across high-latency WAN connections.

The CommKey Challenge: Reverse Engineering MakeKey

When an administrator configures a numeric communication key on the terminal, standard connections fail with:

Reply Code: CMD_ACK_UNAUTH (2005)

To authenticate, the client must compute an encrypted authorization token from the terminal session tick count and the CommKey password:

function makeCommKey(int $key, int $sessionId, int $ticks = 50): int
{
    $k = 0;
    for ($i = 0; $i < 32; $i++) {
        if ($key & (1 << $i)) {
            $k = ($k << 1) | 1;
        } else {
            $k = $k << 1;
        }
    }

    $k += $sessionId;
    $k = pack('V', $k);
    
    // Scramble using hardware ticks modifier
    // Dispatches CMD_AUTH (1102) with scrambled 4-byte buffer
    return unpack('V', $k)[1] ^ $ticks;
}

Upon dispatching CMD_AUTH (1102) with the scrambled buffer, the terminal returns CMD_ACK_OK (2000), transitioning the session into privileged state.

The Hardware Breakthrough: Direct Memory Injection (CMD_SET_DATA)

Prior to taha-rafi/php-zkteco, every open-source PHP biometric package was read-only. If an employee registered a punch through a mobile app or web portal, there was no way to write that punch back into the physical device hardware memory.

The package unlocks this using command code CMD_SET_DATA (3001).

Hardware Table Encoding

Modern ZKTeco firmware represents relational tables internally as null-terminated tabular strings. To write an attendance punch, the driver constructs an ATT_LOG buffer:

TableName=ATT_LOG\r\nUser_PIN={userId}\tVerify_Type={verifyType}\tVerify_Time={isoTimestamp}\tStatus={state}\tWork_Code_ID={workCode}\0

Where:

• User_PIN: The employee enrollment identifier (string).
• Verify_Type: Verification method (1 = Fingerprint, 2 = RFID Badge, 15 = Face).
• Verify_Time: Formatted datetime string (YYYY-MM-DD HH:MM:SS).
• Status: Punch state (0 = Check-In, 1 = Check-Out, 2 = Break-Out, 3 = Break-In).
• Work_Code_ID: Numeric work code or cost center.

The Crucial Refresh Step (CMD_REFRESHDATA)

Writing via CMD_SET_DATA stages the record into the device SQLite or RAM buffer. If the connection drops here, the punch does not appear on the LCD screen or in exports. The driver immediately follows the write with command CMD_REFRESHDATA (1013). This instructs the terminal firmware to flush dirty cache lines to flash storage, recalculate internal log counters, and update the on-screen punch log index.

Verifiable Demonstration Script

The following script connects over TCP, writes an attendance punch into the machine hardware memory, verifies the record exists by reading back recent logs, and performs a selective range purge.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use TahaRafi\ZKTeco\ZKTeco;
use TahaRafi\ZKTeco\Constants;

$ip = '192.168.1.201';
$port = 4370;

echo "[SYSTEM] Initializing low-level ZKTeco connection to {$ip}:{$port}...\n";
$zk = new ZKTeco(
    ip: $ip,
    port: $port,
    commKey: 0,
    protocol: Constants::PROTOCOL_TCP,
    timeoutSec: 8.0
);

if (!$zk->connect()) {
    echo "[ERROR] Could not establish TCP stream socket.\n";
    exit(1);
}

try {
    echo "[INFO] Connected successfully over TCP stream socket.\n";
    echo "[INFO] Device Serial: " . $zk->getSerialNumber() . "\n";
    echo "[INFO] Device Platform: " . $zk->getPlatform() . "\n";

    // 1. Direct Hardware Punch Injection via CMD_SET_DATA (3001)
    $targetUserId = "10042";
    $punchTimestamp = date('Y-m-d H:i:s');
    $punchState = Constants::ATT_STATE_CHECK_IN;
    $verifyType = Constants::VERIFY_FINGERPRINT;
    $workCode = 0;

    echo "\n--- Direct Memory Write Operation ---\n";
    echo "Injecting attendance record into physical device memory:\n";
    echo "  User PIN:    {$targetUserId}\n";
    echo "  Timestamp:   {$punchTimestamp}\n";
    echo "  State:       {$punchState} (Check-In)\n";
    echo "  Verify Type: {$verifyType} (Fingerprint)\n";

    $writeSuccess = $zk->writeAttendanceToDevice(
        userId: $targetUserId,
        state: $punchState,
        timestamp: $punchTimestamp,
        verifyType: $verifyType,
        workCode: $workCode
    );

    if ($writeSuccess) {
        echo "[SUCCESS] CMD_SET_DATA and CMD_REFRESHDATA accepted by hardware.\n";
    } else {
        echo "[FAILURE] Hardware rejected attendance insertion.\n";
    }

    // 2. Memory Verification: Read back punches to verify presence
    echo "\n--- Verifying Memory Persistence ---\n";
    $attendance = $zk->getAttendance();
    $found = false;
    foreach ($attendance as $record) {
        if ($record['id'] === $targetUserId && $record['timestamp'] === $punchTimestamp) {
            $found = true;
            echo "[VERIFIED] Record found in terminal memory:\n";
            echo sprintf("  UID: %d | ID: %s | State: %d | Time: %s\n",
                $record['uid'],
                $record['id'],
                $record['state'],
                $record['timestamp']
            );
            break;
        }
    }

    if (!$found) {
        echo "[NOTICE] Record not immediately visible in sequential table (may require full buffer index reload).\n";
    }

    // 3. Selective Range Deletion via CMD_TIME_ATTLOG_DELE (10005)
    echo "\n--- Selective Range Deletion ---\n";
    $startTime = date('Y-m-d 00:00:00', strtotime('-7 days'));
    $endTime = date('Y-m-d 23:59:59', strtotime('-1 day'));

    echo "Deleting punch records between {$startTime} and {$endTime}...\n";
    $deleteSuccess = $zk->deleteAttendanceByTimeRange($startTime, $endTime);

    if ($deleteSuccess) {
        echo "[SUCCESS] Selective time range deletion completed without full wipe.\n";
    } else {
        echo "[WARNING] Device did not acknowledge range deletion command.\n";
    }

} catch (\Throwable $e) {
    echo "[EXCEPTION] Low-level communication failure: " . $e->getMessage() . "\n";
} finally {
    $zk->disconnect();
    echo "[INFO] TCP socket released.\n";
}

Architectural Implications

Implementing binary protocols directly in PHP removes the operational complexity of maintaining multi-runtime stacks. By understanding binary framing, checksum verification, and session state machines, PHP applications can interact directly with embedded systems and physical infrastructure with native performance.