rust-socksd/doc/authentication.md

Authentication Backends

rust-socksd supports multiple authentication backends to secure your SOCKS5 and HTTP proxy endpoints. When authentication is enabled globally (auth.enabled: true), SOCKS5 requests require username/password authentication, and HTTP requests require HTTP Basic Authentication (via the Proxy-Authorization header).

---

1. Simple (File-based) Backend

This backend stores credentials in a local YAML configuration file. Passwords are securely hashed using Argon2, Bcrypt, or Scrypt.

Configuration

auth:
  enabled: true
  type: simple
  user_config_file: "config/users.yml"

CLI User Management

You can manage this file dynamically using the user subcommand.

Initialize User Configuration

Create a new, empty user database file with a default hashing algorithm:

rust-socksd user --user-config config/users.yml init --hash-type argon2

Options for --hash-type: argon2 (default), bcrypt, scrypt

Add a New User

Add a user. You will be prompted for a password if you do not specify it on the command line:

rust-socksd user --user-config config/users.yml add myuser

Specify custom hash type per user:

rust-socksd user --user-config config/users.yml add myuser --hash-type bcrypt

List Configured Users

List all users, their status (enabled/disabled), creation time, and last modified time:

rust-socksd user --user-config config/users.yml list

Update Password

rust-socksd user --user-config config/users.yml update myuser

Enable / Disable a User

# Disable a user
rust-socksd user --user-config config/users.yml enable myuser false

# Enable a user
rust-socksd user --user-config config/users.yml enable myuser true

Remove a User

rust-socksd user --user-config config/users.yml remove myuser

---

2. PAM Backend

Integrates authentication with the Linux Pluggable Authentication Modules (PAM) subsystem. This allows proxying to authenticate using local system user accounts.

Note

Requires building rust-socksd with the pam-auth feature (enabled by default on Linux). The server process must also run with sufficient privileges (e.g., as root) or belong to the shadow group to read system user credentials.

Configuration

auth:
  enabled: true
  type: pam
  service: "socksd" # Refers to config file in /etc/pam.d/socksd

---

3. LDAP Backend

Authenticates users against an LDAP directory server (such as Active Directory or OpenLDAP).

Configuration

auth:
  enabled: true
  type: ldap
  url: "ldap://ldap.example.com:389"
  base_dn: "ou=users,dc=example,dc=com"
  # Optional: DN and password used to search for user entries (if anonymous binds are disabled)
  bind_dn: "cn=admin,dc=example,dc=com"
  bind_password: "admin_password"
  # User search query filter. '{}' is replaced by the logging-in username.
  user_filter: "(uid={})"

---

4. Database (SQL) Backend

Authenticates users by querying a database and verifying the password hash against secure algorithms. Supports MySQL/MariaDB and PostgreSQL.

Configuration

auth:
  enabled: true
  type: database
  db_type: "mysql" # or "postgres"
  url: "mysql://socksd_user:secret@localhost/socksd_db"
  # Query must return a single column containing the password hash
  query: "SELECT password_hash FROM users WHERE username = ?"
  # Hashing algorithm used in the database: argon2, bcrypt, or scrypt
  hash_type: "argon2"