dacspasswd

DACSPASSWD(1)                 DACS Commands Manual                 DACSPASSWD(1)



NAME
       dacspasswd - manage DACS accounts

SYNOPSIS
       dacspasswd [dacsoptions[1]] [-p password] [-pf file] [-simple]
                  [-vfs vfs_uri]
                  [op-spec] [--] [username]

DESCRIPTION
       This program is part of the DACS suite.

       The dacspasswd command manages accounts that are used by the
       local_passwd_authenticate[2] and local_simple_authenticate[3],
       authentication modules. This utility serves a similar purpose for these
       authentication modules that Apache's htpasswd(1)[4] command does for its
       mod_auth_basic[5] and mod_authn_dbm[6] modules.

       Apart from their use by local_passwd_authenticate and
       local_simple_authenticate, these accounts are completely separate from
       any other accounts and passwords.

           Note
           Only lowercase usernames are permitted for these accounts.

       The command allows arbitrary data to be associated with each account.
       This "private" data is opaque to DACS and is not used by DACS. Custom,
       account-specific information can be stored, retrieved, and deleted. Data
       that is not printable text must be encoded. The information is
       automatically deleted when its account is removed. Using this feature,
       account administration programs might be developed to store:

       •   the last time a password was changed;

       •   hashes of previous password values (so that they are not reused);

       •   a note that the account's password must be changed;

       •   a password reminder question and answer;

       •   information for mutual authentication, such as a small image provided
           by the user that is displayed at login time;

       •   an encrypted representation of the password for recovery purposes
           (when absolutely necessary)

       •   several security questions (with answers), one of which might be
           selected at random and presented to the user at login time; or

       •   user preferences.

       Or instead, a pointer to any of this sort of information might be stored.
       There is no size limit for the data, but if relatively large amounts of
       data are being stored for a large number of accounts, the storage type
       should be chosen with care to ensure reasonable performance.

       Passwords are accessed using the DACS virtual filestore through the
       passwds or simple item types. Each record in the file is keyed on the
       username. The information associated with each key consists of several
       fields separated by a "|" character, and includes a digest algorithm
       identifier, salt, the computed digest, and optional application data.

       Use dacsauth(1)[7] to validate (test) a password.

           Security
           The password digest algorithm used depends on the PASSWORD_DIGEST[8]
           directive in effect. The PASSWORD_SALT_PREFIX[9] directive is also
           used.

           Apart from using an authentication method stronger than one based on
           passwords, current best practice is to use a key derivation function
           like scrypt rather than a cryptographic digest for the
           PASSWORD_DIGEST[8]. While in general doing so will provide additional
           protection if an attacker obtains the password file, it will not help
           if users are allowed to choose weak passwords.

           Plaintext passwords are not stored by dacspasswd. This makes it more
           difficult for an attacker that gains access to the password file to
           discover plaintext passwords, but also means that forgotten passwords
           cannot be recovered (except by exhaustive search, which ought to be
           impractical).

           The salted hash of the password is stored, assuming salting has not
           been disabled, rather than the hash of the password itself. This
           makes a stolen password file more difficult for an attacker to use
           (see rainbow tables[10]).

           Only a DACS administrator should be able to successfully run this
           program from the command line. Because DACS keys and configuration
           files, including the file used to store passwords, must be restricted
           to an administrator, this will normally be the case, but a careful
           administrator will set file permissions to deny access to all other
           users. An ordinary user is able to change his own password using the
           dacs_passwd(8)[11] web service.

           Tip
           Even if the password file is stored as a plain text file, it is
           probably best to modify it only through this program or dacs_passwd.
           Corrupting a password file entry may prevent signing on to the
           corresponding account or even all accounts that require the password
           file.

           It is good administrative practice to store accounts with passwords
           separately from those without.

       This program is also available as a DACS web service, dacs_passwd(8)[11].

OPTIONS
       By default, the program will prompt for a new password if one is required
       by the selected operation.

       The dacspasswd command recognizes these command line flags:

       -p password
           Specify the password.

               Security
               A password given on the command line may be visible to other
               users on the same system.

       -pdd
           Delete the private data associated with username.

       -pdg
           Get the private data associated with username and print it to the
           standard output.

       -pds string
           Set (or replace) string as private data associated with username.

       -pdsf file
           Set (or replace) the private data associated with username, reading
           it from file. If file is "-", then the data is read from the standard
           input. This flag and -pf cannot both be used to read from the
           standard input.

       -pf file
           Read the password to use from file. If file is "-", then the password
           is read from the standard input without prompting. This flag and
           -pdsf cannot both be used to read from the standard input.

       -simple
           Use the simple item type expected by local_simple_authenticate
           instead of the default. The program will not prompt for passwords
           because these accounts do not use them.

       -vfs vfs_uri
           Add vfs_uri as a VFS[12] configuration directive. By specifying the
           item type passwds, a location for the password file can be given,
           overriding any configuration file value. This is particularly useful
           in conjunction with dacsauth(1)[7].

       op-spec
           The following operations are recognized. The -enable, -disable, -pdd,
           -pds, and -pdsf are the only operations that can be combined with
           another operation (for example, you can disable an account and set
           its private data at the same time).

           -a
           -add
               Add username to the password file. The entry must not already
               exist. By default, the user will be prompted for the password,
               which must be retyped for confirmation. This is the default
               operation.

           -d
           -del
           -delete
               Delete username from the password file.

           -dis
           -disable
               Disable the account for username so that authentication modules
               will not accept any password. If used with -a, -s, or -u, the
               account will also be disabled. The username may subsequently be
               enabled.

           -en
           -ena
           -enable
               Re-enable the account for username, which is currently disabled.
               The authentication modules will once again accept the password.
               If used with -a, -s, or -u, the account will also be enabled.

           -g
           -get
               Get the digest string for username and print it to the standard
               output. A script can validate a password by passing this digest
               string to password()[13] along with the password obtained from
               the user.

           -l
           -list
           -long
           -longlist
               List username if it appears in the password file. If no username
               is provided, list all usernames. A disabled account is indicated
               by a '*' (which is not a valid character in a username). The
               -long and -longlist variants display additional detail about each
               entry, such as the digest algorithm used.

           -s
           -set
               Set or reset the password for username, which must already exist
               in the password file. The enabled/disabled status is preserved
               unless overridden by a flag.

           -regen
           -regenerate
               Read the current password file (item type passwds) and copy it to
               the item type newpasswds. This will normally create an exact
               copy, but if there are applicable formatting changes, they are
               automatically applied to the input; that is, if the format of the
               input file is older than the format preferred by the current
               version of DACS, it will be updated in the output file to the
               extent possible. The output file should be carefully examined and
               tested before being used.

           -test test-op
               Test an entry for one of several attributes and report the
               outcome through the program's exit status. The test-op is one of
               the following keywords or abbreviated keywords:

               •   enabled, ena, en

                   Return an exit status of 0 if an account for username exists
                   and is enabled, or 1 if it does not exist or is disabled.

               •   exists, ex

                   Return an exit status of 0 if an account for username exists,
                   or 1 if it does not exist.

               •   data

                   Return an exit status of 0 if an account for username exists
                   and has private data, or 1 if it does not exist or does not
                   have private data. If an entry's private data is the empty
                   string, it is considered to have private data.

               •   disabled, dis

                   Return an exit status of 0 if an account for username exists
                   and is disabled, or 1 if it does not exist or is enabled.


           -u
           -up
           -update
               Add username to the password file or update an existing entry for
               username. By default, the user will be prompted for the password,
               which must be retyped for confirmation. If the entry exists, the
               enabled/disabled status is preserved unless overridden by a flag.


       --
           This flag signals the end of the flag arguments; a username may
           follow, possibly beginning with a "-" character.

       Since only the administrator is allowed to use this command, no
       restrictions are imposed on the length or quality of the passwords that
       the administrator supplies; a warning message will be emitted, however,
       if the password is considered to be weak based on the
       PASSWORD_CONSTRAINTS[14] directive that is configured.

EXAMPLES
       To list all of the accounts configured for the jurisdiction named
       EXAMPLE:

           % dacspasswd -uj EXAMPLE -list
           auggie
           bobo*
           booboo
           jj

       Note that the account for username bobo has been disabled.

       To re-enable bobo's account:

           % dacspasswd -uj EXAMPLE -ena bobo

       To test if bobo's account is enabled:

           % dacspasswd -uj EXAMPLE -test ena bobo
           % echo $status
           0

       To test if there are accounts for usernames booboo and bob:

           % dacspasswd -uj EXAMPLE -test exists booboo
           % echo $status
           0
           % dacspasswd -uj EXAMPLE -test exists bob
           % echo $status
           1

       To reset the password for username bobo interactively:

           % dacspasswd -uj EXAMPLE -set bobo
           New password for bobo?
           Re-type new password for bobo?

       Note that the password text is not displayed.

       To reset the password for username bobo using the program's standard
       input:

           % echo $newpasswd | dacspasswd -uj EXAMPLE -set -pf - bobo

       To create a new, disabled account for username bob and store the private
       data "On vacation":

           % dacspasswd -uj EXAMPLE -add -pf ./pwfile -dis -pds "On vacation" bob

       The password is read from the file ./pwfile.

       To get the private data for username bob:

           % set x=`dacspasswd -uj EXAMPLE -pdg bob`
           % echo "$x"
           On vacation

       To regenerate the current password file:

           % dacspasswd -uj EXAMPLE -q -vfs "[newpasswds]dacs-kwv-fs:/usr/local/dacs/tmp/newpasswd?field_sep=:" -regen


DIAGNOSTICS
       The program exits 0 if everything was fine, and non-zero otherwise. A
       "false" outcome from the -test operation is reflected by an exit status
       of 1. An error condition is indicated by an exit status of 2.

BUGS
       That password information is not represented externally as an XML
       document tends to haunt your humble narrator. The password file format is
       subject to change.

SEE ALSO
       dacs_passwd(8)[11], dacsauth(1)[7], dacs_authenticate(8)[15],
       dacs_admin(8)[16], dacs.conf(5)[17]

AUTHOR
       Distributed Systems Software (www.dss.ca[18])

COPYING
       Copyright © 2003-2017 Distributed Systems Software. See the LICENSE[19]
       file that accompanies the distribution for licensing information.

NOTES
        1. dacsoptions
           http://dacs.dss.ca/man/dacs.1.html#dacsoptions

        2. local_passwd_authenticate
           http://dacs.dss.ca/man/dacs_authenticate.8.html#local_passwd_authenticate

        3. local_simple_authenticate
           http://dacs.dss.ca/man/dacs_authenticate.8.html#local_simple_authenticate

        4. htpasswd(1)
           http://httpd.apache.org/docs/2.4/programs/htpasswd.html

        5. mod_auth_basic
           http://httpd.apache.org/docs-2.4/mod/mod_auth_basic.html

        6. mod_authn_dbm
           http://httpd.apache.org/docs-2.4/mod/mod_authn_dbm.html

        7. dacsauth(1)
           http://dacs.dss.ca/man/dacsauth.1.html

        8. PASSWORD_DIGEST
           http://dacs.dss.ca/man/dacs.conf.5.html#PASSWORD_DIGEST

        9. PASSWORD_SALT_PREFIX
           http://dacs.dss.ca/man/dacs.conf.5.html#PASSWORD_SALT_PREFIX

       10. rainbow tables
           http://en.wikipedia.org/wiki/Rainbow_table

       11. dacs_passwd(8)
           http://dacs.dss.ca/man/dacs_passwd.8.html

       12. VFS
           http://dacs.dss.ca/man/dacs.conf.5.html#VFS

       13. password()
           http://dacs.dss.ca/man/dacs.exprs.5.html#password

       14. PASSWORD_CONSTRAINTS
           http://dacs.dss.ca/man/dacs.conf.5.html#PASSWORD_CONSTRAINTS

       15. dacs_authenticate(8)
           http://dacs.dss.ca/man/dacs_authenticate.8.html

       16. dacs_admin(8)
           http://dacs.dss.ca/man/dacs_admin.8.html

       17. dacs.conf(5)
           http://dacs.dss.ca/man/dacs.conf.5.html

       18. www.dss.ca
           http://www.dss.ca

       19. LICENSE
           http://dacs.dss.ca/man/../misc/LICENSE



DACS 1.4.40                        02/19/2019                      DACSPASSWD(1)