Tutorial

Securing Biometric Data in Transit: Encryption, Signatures, and Compliance

How to protect biometric attendance data from device to cloud to your application — with TLS, HMAC signatures, and compliance-ready architecture.

PunchConnect Team·Mar 28, 2026·5 min read

Introduction

A fingerprint template leaks. Unlike a password, you can't reset it. Your employees' biometric data is irrevocable — and that makes securing it non-negotiable.

Biometric attendance data includes fingerprint templates, face recognition vectors, employee IDs, and timestamps. In most jurisdictions, this qualifies as sensitive personal data. GDPR (EU), LGPD (Brazil), POPIA (South Africa), PDPA (Thailand) — they all demand encryption in transit, access controls, and audit trails.

This guide covers the full security chain: device to cloud, cloud to your application, and everything in between.

The Threat Model

Before we talk solutions, let's understand what we're defending against. Biometric attendance systems face three primary attack surfaces:

Layer 1: Device-to-Cloud Encryption (TLS 1.3)

All communication between biometric devices and PunchConnect is encrypted using TLS 1.3 — the latest transport layer security protocol. This means:

- No plaintext data ever leaves the device over the network
- Certificate pinning prevents man-in-the-middle attacks
- Forward secrecy ensures that even if a key is compromised, past sessions remain encrypted

You don't need to configure this. When you register a device in the PunchConnect dashboard, the encrypted connection is established automatically. The device connects outbound on port 443 (HTTPS) — no special firewall rules, no VPN, no static IP required.

What Gets Encrypted

Every piece of data that moves between a device and PunchConnect is encrypted:

- Attendance records (employee ID, timestamp, verification type)
- Employee templates (fingerprint, face, card data)
- Device commands (restart, sync, configuration updates)
- Device status reports (online/offline, firmware version)

Layer 2: Webhook Signature Verification (HMAC-SHA256)

When PunchConnect delivers attendance data to your application via webhook, how do you know it's really from PunchConnect? An attacker who discovers your webhook endpoint could send fake attendance events.

The answer: every webhook includes a cryptographic signature.

Python: Verify Webhook Signature

python

import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_your_signing_secret"

def verify_signature(payload: bytes, signature: str) -> bool:
    """Verify PunchConnect webhook signature."""
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

@app.route("/webhooks/attendance", methods=["POST"])
def handle_attendance():
    signature = request.headers.get("X-PunchConnect-Signature", "")
    
    if not verify_signature(request.data, signature):
        # Log the attempt — this could be an attack
        app.logger.warning(
            f"Invalid webhook signature from {request.remote_addr}"
        )
        return jsonify({"error": "Invalid signature"}), 401
    
    event = request.json
    
    # Safe to process — signature verified
    employee_id = event["data"]["employee_id"]
    timestamp = event["data"]["timestamp"]
    device_id = event["data"]["device_id"]
    
    print(f"Verified punch: {employee_id} at {timestamp} on {device_id}")
    
    return jsonify({"received": True}), 200

if __name__ == "__main__":
    app.run(port=3000, ssl_context="adhoc")  # HTTPS required

Node.js: Verify Webhook Signature

Critical: Always use hmac.compare_digest (Python) or crypto.timingSafeEqual (Node.js) instead of ===. Simple string comparison is vulnerable to timing attacks.

javascript

const crypto = require('crypto');
const express = require('express');
const app = express();

app.use(express.json({ verify: (req, res, buf) => { req.rawBody = buf; } }));

const WEBHOOK_SECRET = process.env.PUNCHCONNECT_WEBHOOK_SECRET;

function verifySignature(payload, signature) {
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

app.post('/webhooks/attendance', (req, res) => {
  const signature = req.headers['x-punchconnect-signature'];

  if (!signature || !verifySignature(req.rawBody, signature)) {
    console.warn(`⚠️ Invalid signature from ${req.ip}`);
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { data } = req.body;
  console.log(`✅ Verified: ${data.employee_id} at ${data.timestamp}`);

  res.status(200).json({ received: true });
});

app.listen(3000, () => console.log('Secure webhook listener on :3000'));

Layer 3: Data at Rest (AES-256)

All data stored in PunchConnect's infrastructure is encrypted using AES-256:

- Attendance records
- Employee biometric templates
- Device configurations
- Webhook delivery logs
- Database backups

Access to encrypted data requires rotating credentials managed by automated systems. No human has direct database access in production.

HTTPS-Only Webhook Delivery

PunchConnect will not deliver webhooks to plain HTTP endpoints in production mode. Your webhook URL must use HTTPS with a valid TLS certificate.

For local development, use a tunneling service like ngrok:

```bash
# Start a secure tunnel for local testing
ngrok http 3000

# Use the HTTPS URL from ngrok
# https://abc123.ngrok.io/webhooks/attendance
```

bash

# ✅ This works
curl -X POST https://api.punchconnect.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/attendance",
    "events": ["attendance.punch"],
    "secret": "whsec_your_signing_secret"
  }'

# ❌ This will be rejected
# "url": "http://your-app.com/webhooks/attendance"
# Error: "Webhook URL must use HTTPS"

Replay Attack Prevention

Even with valid signatures, an attacker could capture a legitimate webhook and replay it. Protect against this with timestamp validation and idempotency checks:

python

from datetime import datetime, timezone, timedelta

MAX_WEBHOOK_AGE = timedelta(minutes=5)

@app.route("/webhooks/attendance", methods=["POST"])
def handle_attendance():
    # Step 1: Verify signature (from above)
    if not verify_signature(request.data, request.headers.get("X-PunchConnect-Signature", "")):
        return jsonify({"error": "Invalid signature"}), 401
    
    event = request.json
    
    # Step 2: Check timestamp freshness
    event_time = datetime.fromisoformat(event["timestamp"])
    age = datetime.now(timezone.utc) - event_time
    if age > MAX_WEBHOOK_AGE:
        app.logger.warning(f"Stale webhook rejected: {age} old")
        return jsonify({"error": "Webhook too old"}), 400
    
    # Step 3: Idempotency — reject duplicate event IDs
    event_id = event["event_id"]
    if redis_client.exists(f"webhook:{event_id}"):
        return jsonify({"status": "already_processed"}), 200
    
    redis_client.setex(f"webhook:{event_id}", 86400, "1")  # TTL: 24h
    
    # Step 4: Process the event
    process_attendance(event["data"])
    
    return jsonify({"received": True}), 200

API Key Security Best Practices

Your PunchConnect API key is the gateway to your attendance data. Treat it like a database password.

Key rotation checklist:

1. Generate a new API key in the PunchConnect dashboard
2. Update your application's environment variables
3. Deploy with the new key
4. Verify webhooks are still being delivered
5. Revoke the old key
6. Log the rotation date

python

# ❌ NEVER do this
API_KEY = "pk_live_abc123"  # Hardcoded in source

# ✅ Load from environment
import os
API_KEY = os.environ["PUNCHCONNECT_API_KEY"]

# ✅ Or from a secrets manager
from your_secrets_lib import get_secret
API_KEY = get_secret("punchconnect/api-key")

Compliance Checklist by Regulation

| Requirement | GDPR (EU) | LGPD (Brazil) | POPIA (S. Africa) | PunchConnect |
|-------------|-----------|---------------|-------------------|--------------|
| Encryption in transit | Required | Required | Required | ✅ TLS 1.3 |
| Encryption at rest | Required | Required | Required | ✅ AES-256 |
| Access controls | Required | Required | Required | ✅ API keys + RBAC |
| Audit trail | Required | Required | Required | ✅ Webhook logs |
| Data minimization | Required | Required | Required | ✅ Templates only, no raw biometrics |
| Right to erasure | Article 17 | Article 18 | Section 24 | ✅ DELETE /employees/{id} |
| Breach notification | 72 hours | "Reasonable time" | "As soon as possible" | ✅ Status page + email alerts |

Delete Employee Data (Right to Erasure)

This removes:
- Employee record
- All biometric templates (fingerprint, face, card)
- Attendance history association
- Device-stored templates (pushed as delete command to all devices)

bash

# GDPR Article 17 / LGPD Article 18 — Right to erasure
curl -X DELETE https://api.punchconnect.com/v1/employees/EMP001 \
  -H "Authorization: Bearer YOUR_API_KEY"

Security Audit Checklist

Use this checklist when deploying PunchConnect in a security-sensitive environment:

- [ ] Webhook URL uses HTTPS with valid certificate
- [ ] Webhook signature verification implemented (HMAC-SHA256)
- [ ] Timestamp validation rejects webhooks older than 5 minutes
- [ ] Idempotency handling prevents duplicate event processing
- [ ] API keys stored in environment variables or secrets manager
- [ ] API key rotation scheduled (every 90 days recommended)
- [ ] Network access restricted — webhook endpoint only accepts PunchConnect IPs
- [ ] Logging captures all webhook deliveries and signature failures
- [ ] Employee deletion API tested for right-to-erasure compliance
- [ ] Data retention policy defined and automated

FAQ

Does PunchConnect store raw fingerprint images?

No. PunchConnect only stores fingerprint templates — mathematical representations of fingerprint features, not actual images. Templates cannot be reverse-engineered into fingerprint images. This is a critical distinction for GDPR and LGPD compliance.

What TLS version does PunchConnect use?

All connections use TLS 1.3 (the latest version). TLS 1.0 and 1.1 are not supported. TLS 1.2 is accepted as a fallback for older devices, but TLS 1.3 is negotiated by default.

How do I verify that my webhook endpoint is secure?

PunchConnect provides a webhook testing tool in the dashboard. Send a test event and verify: (1) your server receives it over HTTPS, (2) signature verification passes, and (3) you can reject events with tampered signatures. You can also test with cURL by sending a POST with an invalid signature to confirm your server rejects it.

Can I restrict API access to specific IP addresses?

Yes. In the PunchConnect dashboard, you can configure IP allowlists for your API keys. Only requests from whitelisted IPs will be accepted. This adds a network-level security layer on top of API key authentication.

What happens to data if I cancel my PunchConnect account?

All data is deleted within 30 days of account cancellation. You can export your data via the API before cancellation. After deletion, data cannot be recovered — this is by design, to comply with data minimization requirements.

---

Biometric data security isn't optional — it's a legal requirement in most markets. PunchConnect handles the heavy lifting: TLS 1.3 for transit, AES-256 for storage, HMAC-SHA256 for webhook integrity. Your job is to verify webhook signatures and store API keys securely. Everything else is handled.

Start your free 7-day trial — enterprise-grade security from day one, no credit card required.

Tutorial

Securing Biometric Data in Transit: Encryption, Signatures, and Compliance

Introduction

The Threat Model

Layer 1: Device-to-Cloud Encryption (TLS 1.3)

What Gets Encrypted

Layer 2: Webhook Signature Verification (HMAC-SHA256)

Python: Verify Webhook Signature

Node.js: Verify Webhook Signature

Layer 3: Data at Rest (AES-256)

HTTPS-Only Webhook Delivery

Replay Attack Prevention

API Key Security Best Practices

Compliance Checklist by Regulation

Delete Employee Data (Right to Erasure)

Security Audit Checklist

FAQ

Does PunchConnect store raw fingerprint images?

What TLS version does PunchConnect use?

How do I verify that my webhook endpoint is secure?

Can I restrict API access to specific IP addresses?

What happens to data if I cancel my PunchConnect account?

Related articles

How to Connect ZKTeco to Odoo: Cloud API Integration Guide

ZKTeco Webhook Integration: Real-Time Attendance Pipelines via REST API

Fingerprint Device API Integration: A Developer's Guide to Cloud Biometric Connectivity