Signed QR labels for asset audits in Laravel: an HMAC in the payload and a phone camera scanner
Osol is an asset and custody management system used by companies in Saudi Arabia. Once a year, or more often, each company counts its assets. Staff walk the floors with a phone, scan the label on each laptop, chair and p
Osol is an asset and custody management system used by companies in Saudi Arabia. Once a year, or more often, each company counts its assets. Staff walk the floors with a phone, scan the label on each laptop, chair and printer, and the system marks it as found. This post shows how we sign the QR labels so a scan can be trusted, and how the scanner page works on a phone browser.
The problem with a plain ID in the QR code
If the QR code holds only the asset ID, anyone with a label printer can make a label for any ID, stick it on the wrong item, and the audit reports it as found. Our IDs are ULIDs, so they are hard to guess, but they show up in URLs, exports and emails.
We wanted a label that only our server can make, with no extra table and no network call when we print.
The payload
Each QR code holds a small JSON object: the asset ID and a short HMAC of that ID.
public function getQrCode()
{
$hash = hash_hmac('sha256', $this->getKey(), config('app.key'));
$payload = json_encode([
'id' => $this->getKey(),
'h' => substr($hash, 0, 24),
]);
return QrCode::size(150)->generate($payload);
}
The secret is the application key, which never leaves the server. We keep the first 24 hex characters (96 bits) of the hash. That is far too many to guess, and the payload stays small, so the QR code stays readable on a small sticker.
The label printer service adds a type field (asset or consumable) and prints with error correction level H. Labels on furniture get scratched; level H still reads with part of the code damaged.
Checking a scan
On the server, the scanner recomputes the hash and compares it in constant time:
if (str_starts_with($code, '{')) {
$data = json_decode($code, true);
$expectedHash = substr(
hash_hmac('sha256', $data['id'], config('app.key')),
0,
24
);
if (hash_equals($expectedHash, $data['h']) && ($asset = Asset::find($data['id']))) {
return $asset;
}
}
hash_equals matters here. A plain === can leak, through timing, how many characters matched.
Not every asset has a QR label. Some labels are EAN-13 barcodes, which the same method checks before the QR code. Some assets are found by serial number or RFID tag, which it tries last:
return Asset::query()
->where('serial', $code)
->orWhere('rfid_tag', $code)
->first();
Three checks before a scan counts
Finding the asset is not enough. Each scan passes three checks, and each failure shows its own message to the auditor:
- Found. The code matches an asset.
- In scope. The asset belongs to a group and location that this audit covers. An auditor counting the second floor should not count a laptop from the warehouse.
- Not counted yet. The asset has no scan in this audit.
A valid scan writes an inventory record with the time, the auditor and the scan mode, then updates the asset's last audit fields. When no asset in scope is still pending, the audit closes itself.
The scanner page
Each auditor gets a personal link with a token. The page is a Livewire component, and the camera part uses html5-qrcode:
await this.scanner.start(
{ facingMode: 'environment' },
{ fps: 10, qrbox: { width: 250, height: 250 }, aspectRatio: 1.0 },
(decodedText) => this.onScanSuccess(decodedText),
() => {}
);
Details that matter on a phone:
- Debounce. The camera reads the same code many times a second. The page ignores new reads while one is being processed, and for one second after.
- Feedback without looking. The phone vibrates on each read. Auditors hold the phone at the label, not at their face.
- Camera denied is normal. Some company phones block the camera, and some auditors refuse the prompt. The page falls back to manual mode, where a USB or Bluetooth barcode scanner types into a text field. The server handles both modes the same way.
- Empty error callback. html5-qrcode calls the error callback for every frame with no code in it. Logging those floods the console.
What a signed label does not do
The HMAC proves that our server made the label. It does not prove that the label is on the right item. A real label moved from one laptop to another still scans. The audit shows that case in other ways: a second scan of the same label is rejected as already counted, a label from another location fails the scope check, and the laptop with no label stays pending.
ملخص بالعربية: يشرح هذا المقال كيف يوقع نظام إدارة الأصول والعهد رموز QR على ملصقات الأصول. ويمنع ذلك قبول ملصق مزيف أثناء الجرد. يحتوي كل رمز على معرف الأصل وجزء من توقيع HMAC. ويتحقق الخادم من هذا الجزء عند كل مسح. ويوضح المقال أيضا صفحة المسح بكاميرا الجوال، والتحويل إلى الإدخال اليدوي عند منع الكاميرا.
Written by the engineering team at Renewable Systems in Riyadh, the makers of Osol.
Originally published by Dev.to Security. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.