Migrating off MD5 and SHA-1 safely

Inventorying where a retired hash is used, dual-hash transition periods, rehashing on write, schema and protocol changes, and a rollback plan that actually works.

Know what you are replacing

# find the usage sites before changing anything
grep -rIn --exclude-dir=.git -E "\b(MD5|SHA1|sha-1|sha1|md5)\b" . | head -50
grep -rIn "hashlib.new\|MessageDigest.getInstance\|crypto.createHash" . | head -50

# classify by datastore too: hashes already written to disk or a database
rg -n "md5|sha1" db/migrations/ config/ 2>/dev/null

Dual-hash transition

A big-bang switch breaks every stored value at once. The safe pattern is to store both digests, verify against either, and write the new one from now on.

import hashlib

def upgrade_checksum(record, data: bytes):
    """Store both digests during the transition window."""
    record.sha256 = hashlib.sha256(data).hexdigest()
    if record.md5 is None:
        record.md5 = hashlib.md5(data).hexdigest()      # legacy value, still readable
    return record

def verify(record, data: bytes) -> bool:
    if record.sha256:
        return hashlib.sha256(data).hexdigest() == record.sha256
    if record.md5:
        return hashlib.md5(data).hexdigest() == record.md5
    return False

• Add the new column as nullable so existing rows are unaffected and no backfill is needed to deploy.
• Backfill in batches, or lazily on read and write, whichever keeps the migration observable.
• Log the count of rows still relying on the old digest, and set an alert so the migration cannot stall silently.
• For protocols, negotiate: advertise both algorithms and accept either until the peer announces support for the new one.
• Announce an end date for the old algorithm internally, and remove the verification path on that date.

Rollback and verification

1. Keep the old digest column populated until the new one covers every row; never null it as part of the upgrade.
2. Deploy verification-with-fallback before writing any new digests, so a rollback cannot lock anyone out.
3. Test the rollback path explicitly: revert the writer, confirm the old reader still works, then re-deploy.
4. Verify a sample: recompute the new digest for random rows and compare with the stored value.
5. Only drop the legacy column after a full retention window with zero fallback reads.

def audit_sample(limit=1000):
    rows = db.sample_records(limit)
    mismatches = [r.id for r in rows if r.sha256 and
                  r.sha256 != hashlib.sha256(r.data).hexdigest()]
    stats.gauge("checksum.mismatches", len(mismatches))
    if mismatches:
        raise RuntimeError(f"{len(mismatches)} checksum mismatches: {mismatches[:5]}")

FAQ

Related

Password hashing: bcrypt, scrypt and Argon2 Salts, peppers and work factors

Last refreshed 2026-09-18.