---
title: "Environment Lock Explained"
slug: environment-lock
type: explanation
plugin: huxx-connect
summary: Why HuxxConnect pauses credential decryption when your site moves to a new server, and the four ways to unlock it again.
keywords: [environment lock, security, migration, credentials, authorized domains]
version_added: 1.2.5
version_updated: 1.2.5
level: intermediate
related: [encryption-tiers, configure-environment-lock, move-a-locked-site, unlock-credentials-remotely]
---

Environment Lock is a tamper seal on your credentials. When HuxxConnect stores encrypted credentials, it also records a fingerprint of the environment they were stored in. Every time the plugin runs, it re-takes the fingerprint and compares. If the fingerprints match, credentials decrypt as normal. If they don't — the site has moved, been cloned, or had its secrets rotated — HuxxConnect stops decrypting and shows **"Environment mismatch — credentials are locked."** in **HuxxConnect → Settings** until someone proves the move was legitimate.

The point is to make a stolen database dump less useful. A copied database restored onto an attacker's server is, from HuxxConnect's perspective, "the same site on a different server" — exactly the situation the lock refuses to serve.

## What the fingerprint is

The fingerprint is an HMAC-SHA256 of the WordPress authentication salts (`LOGGED_IN_KEY` and `LOGGED_IN_SALT` from `wp-config.php`), keyed with the active encryption key. Two properties follow:

1. **It changes when the server changes.** WordPress salts are unique per install, so restoring the database on a different install produces a mismatch.
2. **It can't be forged from the database alone.** Computing a valid fingerprint requires the salts *and* the encryption key. An attacker holding only a database dump can't fabricate a matching hash.

## What triggers a lock

Anything that changes the salts or the encryption key without going through the plugin:

- Migrating or cloning the site to another server or hosting account
- Restoring a database backup onto a fresh WordPress install
- Rotating the WordPress salts in `wp-config.php` (a common post-incident step)
- Removing the `HUXX_CONNECT_ENCRYPTION_KEY` constant on the Advanced tier

Editing APIs, updating the plugin, or changing domains alone do not trigger a lock — the fingerprint doesn't include the domain.

## What actually happens on a mismatch

A mismatch does not always end in a lock. HuxxConnect first checks whether it can resolve the situation on its own:

```mermaid
flowchart TD
    A[Fingerprint mismatch] --> B{Encryption tier?}
    B -->|Locked tier| C[Credentials already unrecoverable —<br>clear the lock, ask for re-entry]
    B -->|Advanced, constant present| D[Key proven via wp-config.php —<br>auto-unlock]
    B -->|Standard / other| E{Current domain<br>pre-authorized?}
    E -->|Yes| F[Auto-unlock and re-seal<br>for the new environment]
    E -->|No| G[LOCKED —<br>manual unlock required]
```

- **Locked tier** (key derived from the salts): after a migration the old key is gone with the old salts, so the lock protects nothing. HuxxConnect clears it and tells you to re-enter credentials. See [Encryption Tiers Explained](/docs/connect/explanation/encryption-tiers/).
- **Advanced tier with the constant present**: defining `HUXX_CONNECT_ENCRYPTION_KEY` in `wp-config.php` already proves filesystem access and possession of the key, so the plugin unlocks automatically.
- **Authorized domain**: if the site now runs on a domain you pre-authorized before the move, the plugin unlocks automatically and re-seals against the new environment. See [Configure Environment Lock](/docs/connect/how-to/configure-environment-lock/).
- Otherwise the site is locked, and one of the manual exits below is required.

## The exits

When credentials are locked, the **Unlock Credentials** section of the Settings page shows two method tiles — **wp-config Challenge** and **Passphrase** — plus a **Remote Unlock** tile with Pro. Re-entering credentials is the always-available fallback outside that section:

**Migration passphrase.** Before migrating, you generate a one-time passphrase on the source site (**Generate Migration Passphrase**). It is shown once, is valid for 72 hours, and only its HMAC is stored — the passphrase itself is never persisted. Entering it on the destination site unlocks credentials. Five failed attempts within 15 minutes triggers a temporary lockout. This is the primary planned-migration path — the full playbook is [Move a Site with Locked Credentials](/docs/connect/how-to/move-a-locked-site/).

**wp-config challenge.** If you didn't generate a passphrase (or it expired), you can prove server access instead: the plugin generates a challenge code, you add `define( 'HUXX_CONNECT_AUTHORIZE', '<code>' );` to `wp-config.php`, and click **Verify**. Someone who can edit `wp-config.php` legitimately controls the server, which is the trust the lock exists to verify. Note the limit: the challenge dismisses the lock, but if the encryption key itself is missing on this server, credentials still can't decrypt and must be re-entered.

**Re-entering credentials.** Always available — done on each API's own page rather than in the Unlock Credentials section (the Credential Health table points you there) — and the only option when the key is genuinely gone (Locked-tier migrations, or Advanced-tier moves where the constants were lost). The API configurations, endpoints, and settings all survive — only the encrypted credential values need to be typed in again.

**Remote Unlock** (Pro) is a fourth exit: the destination site verifies itself against the still-running source site instead of using a passphrase. See [Unlock credentials remotely](/docs/connect/how-to/unlock-credentials-remotely/).

## Why not just skip all this?

Because the alternative is worse in both directions. Decrypting credentials on any server that holds the database means a leaked backup is a leaked credential set. Never decrypting after a change means every legitimate migration destroys credentials. Environment Lock is the middle path: automatic where trust is already established (authorized domains, a present key constant), a short proof-of-legitimacy ceremony everywhere else.

## See it in practice

- [Configure Environment Lock](/docs/connect/how-to/configure-environment-lock/) — pre-authorize domains before a planned move
- [Move a Site with Locked Credentials](/docs/connect/how-to/move-a-locked-site/) — the step-by-step migration playbook
- [Choose an Encryption Tier](/docs/connect/how-to/choose-an-encryption-tier/) — how tier choice changes lock behavior
- [Unlock credentials remotely](/docs/connect/how-to/unlock-credentials-remotely/) — the Pro site-to-site unlock