enigma-bbs/docs/configuration/security.md

layout	title
page	Security

Security

Unlike in the golden era of BBSing, modern Internet-connected systems are prone to hacking attempts, eavesdropping, etc. While plain-text passwords, insecure data over Plain Old Telephone Service (POTS), and so on was good enough then, modern systems must employ protections against attacks. ENiGMA½ comes with many security features that help keep the system and your users secure — not limited to:

• Passwords are never stored in plain-text, but instead are stored using Password-Based Key Derivation Function 2 (PBKDF2). Even the system operator can never know your password!
• Alternatives to insecure Telnet logins are built in: SSH and secure WebSockets for example.
• A built in web server with TLS support (aka HTTPS).
• Optional Two-Factor Authentication (2FA) via One-Time-Password (OTP) for users, supporting Google Authenticator, Time-Based One-Time Password Algorithm (TOTP, RFC-6238), and HMAC-Based One-Time Password Algorithm (HOTP, RFC-4266).

Two-Factor Authentication via One-Time Password

Enabling Two-Factor Authentication via One-Time-Password (2FA/OTP) on an account adds an extra layer of security ("something a user has") in addition to their password ("something a user knows"). Providing 2FA/OTP to your users has some prerequisites:

• A configured email gateway such that the system can send out emails.
• One or more secure servers enabled such as SSH or secure WebSockets (that is, WebSockets over a secure connection such as TLS).
• The web server enabled and exposed over TLS (HTTPS).

ℹ️ For WebSockets and the web server, ENiGMA½ may listen on insecure channels if behind a secure web proxy.

User Registration Flow

Due to the nature of 2FA/OTP, even if enabled on your system, users must opt-in and enable this feature on their account. Users must also have a valid email address such that a registration link can be sent to them. To opt-in, a process similar to the following is taken:

1. Navigate to the 2FA/OTP configuration menu and switches the feature to enabled.
2. Selects the "flavor" of 2FA/OTP: Google Authenticator, TOTP, or HOTP.
3. Confirms settings by saving.

After saving, a registration link will be mailed to the user. Clicking the link provides the following:

1. A secret for manual entry into a OTP device.
2. If applicable, a scannable QR code for easy device entry (e.g. Google Authenticator)
3. A confirmation prompt in which the user must enter a OTP code. If entered correctly, this validates everything is set up properly and 2FA/OTP will be enabled for the account. Future logins will now prompt the user for their OTP after they enter their standard password.

⚠️ Serving 2FA/OTP registration links over insecure (HTTP) can expose secrets intended for the user and is highly discouraged!

ℹ️ +ops can also manually enable or disable 2FA/OTP for a user using oputil, but this is generally discouraged.

ACS Checks

Various places throughout the system that implement ACS can make 2FA specific checks:

• AR#: Current users required authentication factor. AR2 for example means 2FA/OTP is required for this user.
• AF#: Current users active authentication factor. AF2 means the user is authenticated with some sort of 2FA (such as One-Time-Password).

See ACS for more information.

Example

The following example illustrates using an AR ACS check to require applicable users to go through an additional 2FA/OTP process during login:

login: {
    art: USERLOG
    next: [
        {
            //  users with AR2+ must first pass 2FA/OTP
            acs: AR2
            next: loginTwoFactorAuthOTP
        }
        {
            //  everyone else skips ahead
            next: fullLoginSequenceLoginArt
        }
    ]
    // ...
}