Skip to content

Secrets Management

Campus WoL uses several cryptographic keys and credentials to operate securely. This page explains what each secret is, how it is stored, and the practices that keep them safe.

JWT Secret

The JWT secret is the key used to sign and verify authentication tokens. Every time a user logs in, the server creates a JWT signed with this key. On every subsequent request, the server uses the same key to verify that the token has not been tampered with.

The JWT secret is loaded from the JWT_SECRET environment variable, or from a file path if configured. It is never hardcoded in the application source code. If the secret is compromised, an attacker could forge valid authentication tokens for any user, so it must be kept confidential.

What happens if the JWT secret changes?

If the JWT secret is rotated (changed), all existing sessions are immediately invalidated because their tokens were signed with the old key. Every user will need to log in again. This is by design -- it provides a clean way to force all sessions to end if a compromise is suspected.

Admin Password

The default administrator password is set during deployment, typically through a .env file or environment variable. The plaintext password exists only in this configuration file. Once the application starts, it hashes the password using Argon2id and stores only the hash in the database.

After initial setup, the plaintext password in the .env file is no longer read on subsequent starts (unless the administrator account is being reset). The application only ever compares login attempts against the stored Argon2id hash.

SNMP Encryption

Campus WoL supports SNMP-based device management for devices like BenQ displays. SNMP credentials stored in the database are encrypted at rest using a separate Fernet encryption key.

The SNMP encryption key is loaded from the file path specified in the SNMP_ENCRYPTION_KEY_FILE environment variable. If this file does not exist when the application starts, a new key is auto-generated and written to the specified path with 0600 permissions (readable only by the file owner).

What is Fernet encryption?

Fernet is a symmetric encryption scheme that guarantees data cannot be read or tampered with without the key. It uses AES-128-CBC for encryption and HMAC-SHA256 for authentication. When Campus WoL stores SNMP credentials in the database, they are encrypted with the Fernet key first -- even if the database is compromised, the credentials cannot be read without the separate encryption key file.

Key Separation

The SNMP encryption key is completely independent of the JWT secret. Compromising one key does not compromise the other. This separation limits the blast radius of a key compromise:

  • A leaked JWT secret allows forging authentication tokens, but does not expose SNMP credentials
  • A leaked SNMP encryption key allows decrypting stored SNMP credentials, but does not allow forging authentication tokens

Each key serves a single purpose, and they are stored in separate locations.

Environment File Security

The .env file contains sensitive configuration values including the JWT secret, admin password, and paths to key files. This file should be protected with appropriate filesystem permissions:

  • Set the file to be readable only by the application user (e.g., chmod 600 .env)
  • Do not commit the .env file to version control
  • Do not share the .env file contents over unencrypted channels

Why does the .env file matter?

The .env file is the single location where plaintext secrets exist on disk. If an attacker gains read access to this file, they have everything they need to forge tokens and decrypt stored credentials. Restricting its permissions to the application user (and ensuring it is never committed to a repository or shared in a chat message) is one of the most important operational security measures for a Campus WoL deployment.

Summary of Secrets

Secret Storage Purpose
JWT_SECRET Environment variable or file Signs and verifies authentication tokens
Admin password .env file (plaintext), database (Argon2id hash) Initial administrator credentials
SNMP_ENCRYPTION_KEY_FILE File on disk (0600 permissions) Encrypts SNMP credentials at rest

Next Steps