From 0f68f20656d000110ae946d87bc2983046bcb31f Mon Sep 17 00:00:00 2001 From: Bryan Ashby Date: Fri, 14 Jun 2019 21:43:27 -0600 Subject: [PATCH] Documentation updates + Add Security doc * Update optuil doc --- core/oputil/oputil_help.js | 2 +- docs/admin/oputil.md | 225 +++++++++++++++++++++------------ docs/configuration/acs.md | 2 +- docs/configuration/security.md | 62 +++++++++ 4 files changed, 208 insertions(+), 83 deletions(-) create mode 100644 docs/configuration/security.md diff --git a/core/oputil/oputil_help.js b/core/oputil/oputil_help.js index fe76f4b7..62c47297 100644 --- a/core/oputil/oputil_help.js +++ b/core/oputil/oputil_help.js @@ -161,7 +161,7 @@ General Information: MessageBase : `usage: oputil.js mb [] -actions: +Actions: areafix CMD1 CMD2 ... ADDR Sends an AreaFix NetMail NetMail is sent to supplied address with the supplied command(s). Multi-part commands diff --git a/docs/admin/oputil.md b/docs/admin/oputil.md index e1164540..7190d268 100644 --- a/docs/admin/oputil.md +++ b/docs/admin/oputil.md @@ -9,17 +9,17 @@ Let's look the main help output as per this writing: ``` usage: oputil.js [--version] [--help] - [] + [] -global args: - -c, --config PATH specify config path (./config/) - -n, --no-prompt assume defaults/don't prompt for input where possible +Global arguments: + -c, --config PATH Specify config path (default is ./config/) + -n, --no-prompt Assume defaults (don't prompt for input where possible) -commands: - user user utilities - config config file management - fb file base management - mb message base management +Commands: + user User management + config Configuration management + fb File base management + mb Message base management ``` Commands break up operations by groups: @@ -41,21 +41,55 @@ Type `./oputil.js --help` for additional help on a particular command. The `user` command covers various user operations. ``` -usage: oputil.js user [] +usage: oputil.js user [] -actions: - info USERNAME display information about a user - pw USERNAME PASSWORD set a user's password - aliases: password, passwd - rm USERNAME permanently removes user from system - aliases: remove, delete, del - rename USERNAME NEWNAME rename a user - aliases: mv - activate USERNAME set status to active - deactivate USERNAME set status to inactive - disable USERNAME set status to disabled - lock USERNAME set status to locked - group USERNAME [+|-]GROUP adds (+) or removes (-) user from a group +Actions: + info USERNAME Display information about a user + + pw USERNAME PASSWORD Set a user's password + (passwd|password) + + rm USERNAME Permanently removes user from system + (del|delete|remove) + + rename USERNAME NEWNAME Rename a user + (mv) + + 2fa-otp USERNAME SPEC Enable 2FA/OTP for the user + (otp) + + The system supports various implementations of Two Factor Authentication (2FA) + One Time Password (OTP) authentication. + + Valid specs: + disable : Removes 2FA/OTP from the user + google : Google Authenticator + hotp : HMAC-Based One-Time Password Algorithm (RFC-4266) + totp : Time-Based One-Time Password Algorithm (RFC-6238) + + activate USERNAME Set a user's status to "active" + + deactivate USERNAME Set a user's status to "inactive" + + disable USERNAME Set a user's status to "disabled" + + lock USERNAME Set a user's status to "locked" + + group USERNAME [+|-]GROUP Adds (+) or removes (-) user from a group + +info arguments: + --security Include security information in output + +2fa-otp arguments: + --qr-type TYPE Specify QR code type + + Valid QR types: + ascii : Plain ASCII (default) + data : HTML data URL + img : HTML image tag + svg : SVG image + + --out PATH Path to write QR code to. defaults to stdout ``` | Action | Description | Examples | Aliases | @@ -64,25 +98,30 @@ actions: | `pw` | Set password | `./oputil.js user pw joeuser s3cr37` | `passwd`, `password` | | `rm` | Removes user | `./oputil.js user del joeuser` | `remove`, `del`, `delete` | | `rename` | Renames a user | `./oputil.js user rename joeuser joe` | `mv` | +| `2fa-otp` | Manage 2FA/OTP for a user | `./oputil.js user 2fa-otp joeuser googleAuth` | `otp` | `activate` | Activates user | `./oputil.js user activate joeuser` | N/A | | `deactivate` | Deactivates user | `./oputil.js user deactivate joeuser` | N/A | | `disable` | Disables user (user will not be able to login) | `./oputil.js user disable joeuser` | N/A | | `lock` | Locks the user account (prevents logins) | `./oputil.js user lock joeuser` | N/A | | `group` | Modifies users group membership | Add to group: `./oputil.js user group joeuser +derp`
Remove from group: `./oputil.js user group joeuser -derp` | N/A | +#### Manage 2FA/OTP +While `oputil.js` can be used to manage a user's 2FA/OTP, it is highly recommended to require users to opt-in themselves. See [Security](/docs/configuration/security.md) for details. + ## Configuration The `config` command allows sysops to perform various system configuration and maintenance tasks. ``` -usage: oputil.js config [] +usage: oputil.js config [] -actions: - new generate a new/initial configuration - cat cat current configuration to stdout +Actions: + new Generate a new / default configuration -cat args: - --no-color disable color - --no-comments strip any comments + cat Write current configuration to stdout + +cat arguments: + --no-color Disable color + --no-comments Strip any comments ``` | Action | Description | Examples | @@ -94,56 +133,75 @@ cat args: The `fb` command provides a powerful file base management interface. ``` -usage: oputil.js fb [] +usage: oputil.js fb [] -actions: - scan AREA_TAG[@STORAGE_TAG] scan specified area - may also contain optional GLOB as last parameter, - for example: scan some_area *.zip +Actions: + scan AREA_TAG[@STORAGE_TAG] Scan specified area - info CRITERIA display information about areas and/or files - matching CRITERIA. + May contain optional GLOB as last parameter. + Example: ./oputil.js fb scan d0pew4r3z *.zip - mv SRC [SRC...] DST move entry(s) from SRC to DST - SRC: FILENAME_WC|SHA|FILE_ID|AREA_TAG[@STORAGE_TAG] - DST: AREA_TAG[@STORAGE_TAG] + info CRITERIA Display information about areas and/or files - rm SRC [SRC...] remove entry(s) from the system matching SRC - SRC: FILENAME_WC|SHA|FILE_ID|AREA_TAG[@STORAGE_TAG] - desc CRITERIA sets a new file description for file base entry - matching CRITERIA. Launches an external editor using - $VISUAL, $EDITOR, or vim/notepad. - import-areas FILEGATE.ZXX import file base areas using FileGate RAID type format + mv SRC [SRC...] DST Move matching entry(s) + (move) -scan args: - --tags TAG1,TAG2,... specify tag(s) to assign to discovered entries + Source may be any of the following: + - Filename including '*' wildcards + - SHA-1 + - File ID + - Area tag with optional @storageTag suffix + Destination is area tag with optional @storageTag suffix - --desc-file [PATH] prefer file descriptions from supplied path over other - other sources such as FILE_ID.DIZ. Path must point to - a valid FILES.BBS or DESCRIPT.ION file. - --update attempt to update information for existing entries - --quick perform quick scan + rm SRC [SRC...] Remove entry(s) from the system + (del|delete|remove) -info args: - --show-desc display short description, if any + Source may be any of the following: + - Filename including '*' wildcards + - SHA-1 + - File ID + - Area tag with optional @storageTag suffix -remove args: - --phys-file also remove underlying physical file + desc CRITERIA Updates an file base entry's description -import-areas args: - --type TYPE sets import areas type. valid options are "zxx" or "na" - --create-dirs create backing storage directories + Launches an external editor using $VISUAL, $EDITOR, or vim/notepad. -general information: - AREA_TAG[@STORAGE_TAG] can specify an area tag and optionally, a storage specific tag - example: retro@bbs + import-areas FILEGATE.ZXX Import file base areas using FileGate RAID type format - CRITERIA file base entry criteria. in general, can be AREA_TAG, SHA, - FILE_ID, or FILENAME_WC. - - FILENAME_WC filename with * and ? wildcard support. may match 0:n entries - SHA full or partial SHA-256 - FILE_ID a file identifier. see file.sqlite3 +scan arguments: + --tags TAG1,TAG2,... Specify hashtag(s) to assign to discovered entries + + --desc-file [PATH] Prefer file descriptions from supplied input file + + If a file description can be found in the supplied input file, prefer that description + over other sources such related FILE_ID.DIZ. Path must point to a valid FILES.BBS or + DESCRIPT.ION file. + + --update Attempt to update information for existing entries + --full-scan Perform a full scan (default is quick) + +info arguments: + --show-desc Display short description, if any + +remove arguments: + --phys-file Also remove underlying physical file + +import-areas arguments: + --type TYPE Sets import areas type + + Valid types are are "zxx" or "na". + + --create-dirs Also create backing storage directories + +General Information: + Generally an area tag can also include an optional storage tag. For example, the + area of 'bbswarez' stored using 'bbswarez_main': bbswarez@bbswarez_main + + When performing an initial import of a large area or storage backing, --full-scan + is the best option. If re-scanning an area for updates a standard / quick scan is + generally good enough. + + File ID's are those found in file.sqlite3. ``` #### Scan File Area @@ -152,7 +210,8 @@ The `scan` action can (re)scan a file area for new entries as well as update (`- ##### Examples Performing a quick scan of a specific area's storage location ("retro_warez", "retro_warez_games) matching only *.zip extensions: ```bash -$ ./oputil.js fb scan --quick retro_warez@retro_warez_games *.zip` +# note that we must quote the wildcard to prevent shell expansion +$ ./oputil.js fb scan --quick retro_warez@retro_warez_games "*.zip"` ``` Update all entries in the "artscene" area supplying the file tags "artscene", and "textmode". @@ -221,19 +280,23 @@ The above command will process FILEGATE.ZXX creating areas and backing directori The `mb` command provides various Message Base related tools: ``` -usage: oputil.js mb [] +usage: oputil.js mb [] -actions: - areafix CMD1 CMD2 ... ADDR sends an AreaFix NetMail to ADDR with the supplied command(s) - one or more commands may be supplied. commands that are multi - part such as "%COMPRESS ZIP" should be quoted. - import-areas PATH import areas using fidonet *.NA or AREAS.BBS file from PATH +Actions: + areafix CMD1 CMD2 ... ADDR Sends an AreaFix NetMail -import-areas args: - --conf CONF_TAG conference tag in which to import areas - --network NETWORK network name/key to associate FTN areas - --uplinks UL1,UL2,... one or more comma separated uplinks - --type TYPE area import type. valid options are "bbs" and "na" + NetMail is sent to supplied address with the supplied command(s). Multi-part commands + such as "%COMPRESS ZIP" should be quoted. + + import-areas PATH Import areas using FidoNet *.NA or AREAS.BBS file + +import-areas arguments: + --conf CONF_TAG Conference tag in which to import areas + --network NETWORK Network name/key to associate FTN areas + --uplinks UL1,UL2,... One or more uplinks (comma separated) + --type TYPE Area import type + + Valid types are "bbs" and "na" ``` | Action | Description | Examples | diff --git a/docs/configuration/acs.md b/docs/configuration/acs.md index 64d67648..dd57ce22 100644 --- a/docs/configuration/acs.md +++ b/docs/configuration/acs.md @@ -38,7 +38,7 @@ The following are ACS codes available as of this writing: | ACachievementCount | User has >= _achievementCount_ achievements | | APachievementPoints | User has >= _achievementPoints_ achievement points | | AFauthFactor | User's current *Authentication Factor* is >= _authFactor_. Authentication factor 1 refers to username + password (or PubKey) while factor 2 refers to 2FA such as One-Time-Password authentication. | -| ARauthFactorReq | Current users **requires** an Authentication Factor >= _authFactorReq_ | +| ARauthFactorReq | Current user **requires** an Authentication Factor >= _authFactorReq_ | ## ACS Strings ACS strings are one or more ACS codes in addition to some basic language semantics. diff --git a/docs/configuration/security.md b/docs/configuration/security.md new file mode 100644 index 00000000..ff2a568f --- /dev/null +++ b/docs/configuration/security.md @@ -0,0 +1,62 @@ +--- +layout: page +title: 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)](https://en.wikipedia.org/wiki/Plain_old_telephone_service), 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)](https://en.wikipedia.org/wiki/PBKDF2). Even the system operator can _never_ know your password! +* Alternatives to insecure Telnet logins are built in: [SSH](https://en.wikipedia.org/wiki/Secure_Shell) and secure [WebSockets](https://en.wikipedia.org/wiki/WebSocket) for example. +* A built in web server with [TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) support (aka HTTPS). +* Optional [Two-Factor Authentication (2FA)](https://en.wikipedia.org/wiki/Multi-factor_authentication) via [One-Time-Password (OTP)](https://en.wikipedia.org/wiki/One-time_password) for users, supporting [Google Authenticator](http://google-authenticator.com/), [Time-Based One-Time Password Algorithm (TOTP, RFC-6238)](https://tools.ietf.org/html/rfc6238), and [HMAC-Based One-Time Password Algorithm (HOTP, RFC-4266)](https://tools.ietf.org/html/rfc4226). + +## 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](/docs/configuration/email.md) such that the system can send out emails. +* One or more secure servers enabled such as [SSH](/docs/servers/ssh.md) or secure [WebSockets](/docs/servers/websocket.md) (that is, WebSockets over a secure connection such as TLS). +* The [web server](/docs/servers/web-server.md) enabled and exposed over TLS (HTTPS). + +:information_source: 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. + +:warning: Serving 2FA/OTP registration links over insecure (HTTP) can expose secrets intended for the user and is **highly** discouraged! + +:information_source: +ops can also manually enable or disable 2FA/OTP for a user using [oputil](/docs/admin/oputil.md), but this is generally discouraged. + +### ACS Checks +Various places throughout the system that implement [ACS](/docs/configuration/acs.md) 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](/docs/configuration/acs.md) 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: + +```hjson +login: { + art: USERLOG + next: [ + { + // users with AR2+ must first pass 2FA/OTP + acs: AR2 + next: loginTwoFactorAuthOTP + } + { + // everyone else skips ahead + next: fullLoginSequenceLoginArt + } + ] + // ... +} +``` \ No newline at end of file