Privacy Tools Guide

If you’re building software that handles patient health information, you need to understand HIPAA compliance. The Health Insurance Portability and Accountability Act imposes strict requirements on how you store, transmit, and protect Protected Health Information (PHI). This guide covers the technical implementation details developers need to build HIPAA-compliant systems.

Understanding HIPAA for Software Companies

HIPAA applies to your software when it stores, processes, or transmits PHI on behalf of Covered Entities (healthcare providers, health plans, healthcare clearinghouses) or Business Associates. Even if you’re not directly in healthcare, if your software touches patient data, you likely qualify as a Business Associate.

Protected Health Information includes any individually identifiable health information, such as:

The key rule for software developers is the Security Rule, which mandates specific technical safeguards for electronic PHI (ePHI).

Technical Safeguards Every Developer Must Implement

1. Encryption at Rest and in Transit

All ePHI must be encrypted both at rest and during transmission. This is non-negotiable.

For data at rest, use AES-256 encryption. Most cloud providers offer server-side encryption, but you should implement application-level encryption for sensitive fields:

from cryptography.fernet import Fernet
import base64
import hashlib

def generate_key(master_key: str) -> bytes:
    """Generate encryption key from master key."""
    return base64.urlsafe_b64encode(
        hashlib.sha256(master_key.encode()).digest()
    )

def encrypt_phi(data: str, key: bytes) -> str:
    """Encrypt PHI field using Fernet symmetric encryption."""
    f = Fernet(key)
    return f.encrypt(data.encode()).decode()

def decrypt_phi(encrypted_data: str, key: bytes) -> str:
    """Decrypt PHI field."""
    f = Fernet(key)
    return f.decrypt(encrypted_data.encode()).decode()

For data in transit, enforce TLS 1.2 or higher. Configure your web server to use strong cipher suites:

# Nginx configuration for HIPAA compliance
server {
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384';
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;

    # Enforce HTTPS
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
}

2. Access Controls and Authentication

Implement role-based access control (RBAC) to ensure users access only the minimum necessary PHI. Every access to ePHI must be authenticated and logged.

from enum import Enum
from dataclasses import dataclass
from datetime import datetime

class Role(Enum):
    ADMIN = "admin"
    CLINICIAN = "clinician"
    BILLING = "billing"
    PATIENT = "patient"

@dataclass
class AccessPolicy:
    role: Role
    can_read: bool
    can_write: bool
    can_delete: bool
    allowed_fields: list[str]

# Define minimum necessary access policies
ACCESS_POLICIES = {
    Role.CLINICIAN: AccessPolicy(
        role=Role.CLINICIAN,
        can_read=True,
        can_write=True,
        can_delete=False,
        allowed_fields=["medical_history", "diagnoses", "prescriptions", "notes"]
    ),
    Role.BILLING: AccessPolicy(
        role=Role.BILLING,
        can_read=True,
        can_write=True,
        can_delete=False,
        allowed_fields=["insurance_id", "billing_address", "payment_history"]
    ),
    Role.PATIENT: AccessPolicy(
        role=Role.PATIENT,
        can_read=True,
        can_write=False,
        can_delete=False,
        allowed_fields=["own_records", "own_billing"]
    )
}

def check_access(user_role: Role, resource: str, action: str) -> bool:
    """Verify user has permission to access PHI resource."""
    policy = ACCESS_POLICIES.get(user_role)
    if not policy:
        return False

    if action == "read":
        return policy.can_read and resource in policy.allowed_fields
    elif action == "write":
        return policy.can_write and resource in policy.allowed_fields
    elif action == "delete":
        return policy.can_delete

    return False

Implement multi-factor authentication (MFA) for all users accessing systems with ePHI. This is a Required implementation specification under HIPAA.

3. Audit Logging Requirements

Every access, modification, or disclosure of ePHI must be logged. Your audit logs must capture:

import json
from datetime import datetime
from typing import Optional

class AuditLogger:
    def __init__(self, log_destination: str):
        self.log_destination = log_destination

    def log_phi_access(
        self,
        user_id: str,
        action: str,
        resource_type: str,
        resource_id: str,
        patient_id: Optional[str] = None,
        ip_address: Optional[str] = None
    ):
        """Log PHI access for HIPAA audit trail."""
        audit_entry = {
            "timestamp": datetime.utcnow().isoformat() + "Z",
            "user_id": user_id,
            "action": action,
            "resource_type": resource_type,
            "resource_id": resource_id,
            "patient_id": patient_id,
            "ip_address": ip_address,
            "event_type": "PHI_ACCESS"
        }

        # Write to immutable audit log (append-only storage)
        with open(self.log_destination, "a") as f:
            f.write(json.dumps(audit_entry) + "\n")

        return audit_entry

# Usage in your application
audit_logger = AuditLogger("/var/log/audit/phi-access.log")

def retrieve_patient_record(user_id: str, patient_id: str, ip: str):
    # Check access permissions first
    if not check_access(get_user_role(user_id), "medical_history", "read"):
        audit_logger.log_phi_access(
            user_id=user_id,
            action="DENIED",
            resource_type="patient_record",
            resource_id=patient_id,
            patient_id=patient_id,
            ip_address=ip
        )
        raise PermissionError("Access denied to patient record")

    # Log successful access
    audit_logger.log_phi_access(
        user_id=user_id,
        action="READ",
        resource_type="patient_record",
        resource_id=patient_id,
        patient_id=patient_id,
        ip_address=ip
    )

    return fetch_medical_record(patient_id)

Store audit logs separately from application data with stronger access controls. These logs must be retained for six years per HIPAA requirements.

Common HIPAA Pitfalls for Software Teams

Unencrypted backups: Ensure all database backups are encrypted. Attackers frequently target backup files as easier entry points than production systems.

Logging sensitive data: Never log PHI directly. Sanitize all logs to remove patient identifiers:

import re

def sanitize_for_logging(data: dict) -> dict:
    """Remove PHI from data before logging."""
    sensitive_fields = ["ssn", "date_of_birth", "medical_record_number",
                        "insurance_id", "patient_name", "address"]

    sanitized = data.copy()
    for field in sensitive_fields:
        if field in sanitized:
            sanitized[field] = "[REDACTED]"

    # Also check nested structures
    if "patient" in sanitized and isinstance(sanitized["patient"], dict):
        sanitized["patient"] = sanitize_for_logging(sanitized["patient"])

    return sanitized

Inadequate endpoint security: APIs processing PHI must require authentication and authorization on every endpoint. Never expose endpoints that return PHI without proper controls.

Third-party data sharing: If you use cloud services or third-party APIs, ensure you have Business Associate Agreements (BAAs) in place. Your software must enforce the same protections on data processed by vendors.

Breach Notification and Incident Response

Despite best efforts, breaches can occur. Implement an incident response plan that includes:

  1. Detection: Automated alerts for unusual access patterns
  2. Containment: Ability to quickly restrict access to affected systems
  3. Notification: Procedures for reporting breaches to HHS within 60 days
  4. Documentation: Complete records of the incident and response actions
class BreachNotifier:
    def __init__(self, hhs_portal_url: str, compliance_officer_email: str):
        self.hhs_portal = hhs_portal_url
        self.officer_email = compliance_officer_email

    def report_breach(self, breach_details: dict):
        """Prepare and submit breach notification to HHS."""
        notification = {
            "name_of_covered_entity": breach_details["company_name"],
            "date_of_breach": breach_details["discovery_date"],
            "types_of_phi_involved": breach_details["phi_types"],
            "number_of_affected_individuals": breach_details["affected_count"],
            "description": breach_details["description"]
        }

        # In production, this would submit to HHS portal
        # For now, prepare documentation
        with open(f"breach_report_{breach_details['id']}.json", "w") as f:
            json.dump(notification, f, indent=2)

        # Alert compliance officer immediately
        send_email(
            to=self.officer_email,
            subject=f"URGENT: Potential HIPAA Breach - {breach_details['id']}",
            body=f"Breach discovered at {breach_details['discovery_date']}"
        )

Moving Forward

Building HIPAA-compliant software requires attention to security fundamentals: encryption, access controls, and audit logging. The technical implementations above provide a foundation, but compliance is an ongoing process. Regular security audits, employee training, and staying updated on HHS guidance are essential.

Remember that HIPAA violations can result in significant fines—up to $1.5 million per violation category per year. Investing in proper security architecture from the start is far less expensive than dealing with breaches and compliance penalties later.

Built by theluckystrike — More at zovo.one

Explore Our Developer Guides

© 2026 theluckystrike Developer Guides