Rotating Secrets

MyOsicam uses several long-lived secrets to protect sensitive data. This page describes what each secret does, when you should rotate it, and the procedure for doing so safely.

Secrets inventory

Secret	Where it lives	What it protects
PANEL_ENCRYPTION_KEY	config/.env on the panel host	Encrypts WebIF passwords and saved SSH server passwords stored in the database (AES-256-GCM).
Agent token (agent_token)	agents table in the panel DB	Authenticates each agent’s HMAC-signed requests to the panel. One token per registered agent.
Admin operator password	admin_operators table in the admin DB	Protects access to the admin operator console.
Panel license key	config/.env (PANEL_LICENSE_KEY)	Identifies your panel installation to the license server.

Rotating the panel encryption key

The PANEL_ENCRYPTION_KEY is a 64-character hex string (32 bytes) used to encrypt sensitive credential fields before they are stored in the database.

Caution

Rotating this key without first decrypting and re-encrypting the values it protects will make all stored WebIF passwords and saved server passwords permanently unreadable. Follow the procedure below carefully.

When to rotate

• After a suspected disclosure of the .env file.
• As part of a periodic security review (e.g., annually).
• When decommissioning a member of the operations team who had server access.

Procedure

1. Generate a new key:

   Generate a new 32-byte encryption key

   openssl rand -hex 32

   Copy the output — this is your new PANEL_ENCRYPTION_KEY.

2. Re-encrypt stored values with the new key. Before updating .env, use the old key to decrypt each encrypted field from the database, then re-encrypt with the new key. Confirmed encrypted columns (verified against dev.myosicam.us/app/ source):

   • oscam_installs.webif_password — WebIF passwords stored per install
   • saved_servers.ssh_credential_encrypted — saved SSH server credentials
   • email_settings.smtp_password — SMTP password (if configured)
   • email_settings.mailgun_api_key — Mailgun API key (if configured)
   • email_configurations.smtp_password and email_configurations.mailgun_api_key — if using the multi-configuration email model

   If none of those columns contain non-null values (you can check via a DB query), you can skip this step.

3. Update config/.env on the panel host, replacing the value of PANEL_ENCRYPTION_KEY with the new key:

   config/.env (excerpt)

   PANEL_ENCRYPTION_KEY=<new-64-char-hex-string>

4. Restart PHP-FPM to pick up the new value:

   sudo systemctl restart php8.3-fpm

5. Verify that WebIF credentials and saved server passwords are still accessible from the panel UI. If decryption fails, the panel shows the fields as blank — restore the old key and investigate before proceeding.

6. Update your backup to include the new .env file. See Backing Up the Panel.

Rotating an agent token

Each registered agent authenticates using an agent_token stored in the agents table. Tokens are established at registration time and are long-lived by design — they persist until the agent re-registers.

When to rotate

• After suspecting that an agent token was disclosed (e.g., a config file on the agent host was exposed).
• When decommissioning and reinstalling an agent.

Procedure

The simplest and most reliable way to rotate an agent’s token is to reinstall the agent:

1. In the panel, navigate to Agents in the sidebar.
2. Open the agent’s detail page.
3. Click Re-run Bootstrap (visible in the agent detail view for any agent).
4. The panel generates a fresh single-use install token.
5. Run the bootstrap command on the agent server. The agent re-registers with the new token and the old token is invalidated.

Note

The agent’s OScam instances and configuration data are preserved in the panel database — the re-registration updates the token but does not remove the agent’s discovery history.

Rotating the admin operator password

Admin operator accounts are managed by MyOsicam staff — the admin console (admin.myosicam.us) is a MyOsicam-operated property, not a customer-facing panel. If you need an admin operator password rotated (for example, after a suspected disclosure or a staff change), contact MyOsicam support to have the credential updated.

General rotation hygiene

• Store new secrets in a password manager or secrets vault before writing them to disk.
• Update your backup immediately after any rotation — see Backing Up the Panel.
• Do not reuse old secrets.
• Restrict access to config/.env to the web-server user only:

  chmod 640 <panel-root>/config/.env
  chown www-data:www-data <panel-root>/config/.env

Related pages

• Backing Up the Panel — ensure the new secrets are included in your backup.
• Agent Removal — cleanly decommission an agent rather than leaving stale tokens.
• Install the Agent — re-run the agent bootstrap flow.