htpasswd

Create/overwrite htpasswd file

$ htpasswd -c [path/to/file] [username]

$ htpasswd [path/to/file] [username]

$ htpasswd -b [path/to/file] [username] [password]

$ htpasswd -D [path/to/file] [username]

$ htpasswd -v [path/to/file] [username]

$ htpasswd -nbm [username] [password]

htpasswd [options] passwdfile [username [password]]

-c
    Create a new passwdfile. If the file already exists, it will be truncated and overwritten. This option must be used only when creating a new file.

-n
    Do not update the passwdfile; instead, output the results to standard output. This is useful for scripting or testing.

-m
    Force the use of MD5 encryption for passwords. MD5 was historically a common default, but is now considered less secure.

-B
    Force the use of BCrypt encryption for passwords. BCrypt is a strong, adaptive hashing algorithm and is generally recommended for new password entries due to its resistance to brute-force attacks.

-C cost
    Set the computing cost factor for BCrypt (logarithmic scale, typical values 5-12). Higher values increase security but require more CPU time for hashing.

-s
    Force the use of SHA encryption for passwords. SHA is also an older hashing method.

-d
    Force the use of CRYPT encryption for passwords. This is the weakest and least secure method, often relying on traditional UNIX crypt(3).

-p
    Do not encrypt the password; store it as plain text. This option is highly insecure and should never be used in production environments.

-b
    Enable batch mode. The password is provided directly on the command line as the third argument. Avoid using this for security-critical passwords as it exposes the password in command history.

-i
    Read the password interactively from standard input. This overrides the -b option and is generally safer than -b.

-D
    Delete the specified username from the passwdfile.

-v
    Verify the provided password against the hash stored for the username in the passwdfile. Outputs success or failure.

-x
    Read usernames to be deleted from standard input. Each username should be on a new line.

The htpasswd command is a utility used to create and update flat-files containing usernames and encrypted passwords for HTTP Basic Authentication. These files are primarily utilized by the Apache HTTP Server to protect directories or resources, requiring clients to provide credentials before access.

When executed, htpasswd prompts for a new password (unless in batch mode), encrypts it using a specified algorithm (such as MD5, SHA, BCrypt, or the older CRYPT method), and stores the username and encrypted password in the designated file. It can add new users, update existing user passwords, or delete users.

While straightforward and easy to implement for small-scale authentication needs, it's crucial to understand that htpasswd relies on storing password hashes in a simple file. For enhanced security, especially for sensitive data or large user bases, more robust authentication mechanisms like database-backed systems or external identity providers are generally recommended. However, for quick protection of specific web resources, htpasswd remains a widely used and effective tool.

The passwdfile generated by htpasswd is a flat-file database of user credentials. It is absolutely critical that this file is not accessible directly via the web server. It should be placed outside the web document root (e.g., in /etc/apache2/passwd/) or its access should be explicitly denied by Apache configuration.

While htpasswd offers various hashing algorithms, older methods like CRYPT and MD5 are considered weak against modern cracking techniques; BCrypt is the recommended choice for new entries. Storing passwords in plain text (using -p) is an extreme security risk and must be avoided.

htpasswd is not designed for concurrent writes from multiple processes; simultaneous modifications can lead to file corruption. It's best suited for single-user management or scripted updates.

htpasswd is specifically designed for use with Apache's mod_auth_basic (or similar modules) to implement HTTP Basic Authentication. This method transmits credentials (username and password) over the network, typically encoded in Base64. For sensitive data, it is crucial to use HTTPS (SSL/TLS) to encrypt the communication channel and prevent credentials from being intercepted in plain text.

The passwdfile should have strict file permissions, typically readable only by the Apache user (e.g., www-data or apache) and root. It should be placed outside the web server's document root (e.g., in /etc/apache2/passwd/ or a similar secure location) to prevent direct access via a web browser. Incorrect permissions or location are common security vulnerabilities.

The htpasswd utility has been an integral part of the Apache HTTP Server project since its inception in the mid-1990s. Its primary role has always been to provide a simple, file-based mechanism for HTTP Basic Authentication. Over the years, its development has largely focused on enhancing security by incorporating stronger password hashing algorithms.

Initially, it primarily supported the weak CRYPT algorithm (derived from UNIX crypt(3)). Later versions introduced MD5 and SHA for improved security. More recently, support for BCrypt was added, addressing the need for a more robust, adaptive hashing function resistant to brute-force attacks. This evolution reflects the ongoing effort to balance ease of use with the increasing demands of cybersecurity.

httpd(8), apachectl(8), auth_basic_module(8), crypt(3)