.\" Copyright (c) 2003-2012
.\" Distributed Systems Software.  All rights reserved.
.\" See the file LICENSE for redistribution information.
.\" $Id: copyright-nr 2564 2012-03-02 00:17:08Z brachman $
'\" t
.\"     Title: dacspasswd
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 02/19/2019
.\"    Manual: DACS Commands Manual
.\"    Source: DACS 1.4.40
.\"  Language: English
.\"
.TH "DACSPASSWD" "1" "02/19/2019" "DACS 1.4.40" "DACS Commands Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
dacspasswd \- manage \fBDACS\fR accounts
.SH "SYNOPSIS"
.HP \w'\fBdacspasswd\fR\ 'u
\fBdacspasswd\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR] [\fB\-p\ \fR\fB\fIpassword\fR\fR] [\fB\-pf\ \fR\fB\fIfile\fR\fR] [\fB\-simple\fR] [\fB\-vfs\ \fR\fB\fIvfs_uri\fR\fR]
.br
[\fIop\-spec\fR] [\fB\-\-\fR] [\fIusername\fR]
.SH "DESCRIPTION"
.PP
This program is part of the
\fBDACS\fR
suite\&.
.PP
The
\fBdacspasswd\fR
command manages accounts that are used by the
\m[blue]\fBlocal_passwd_authenticate\fR\m[]\&\s-2\u[2]\d\s+2
and
\m[blue]\fBlocal_simple_authenticate\fR\m[]\&\s-2\u[3]\d\s+2, authentication modules\&. This utility serves a similar purpose for these authentication modules that
\fBApache\*(Aqs\fR
\m[blue]\fBhtpasswd(1)\fR\m[]\&\s-2\u[4]\d\s+2
command does for its
\m[blue]\fBmod_auth_basic\fR\m[]\&\s-2\u[5]\d\s+2
and
\m[blue]\fBmod_authn_dbm\fR\m[]\&\s-2\u[6]\d\s+2
modules\&.
.PP
Apart from their use by
\fBlocal_passwd_authenticate\fR
and
\fBlocal_simple_authenticate\fR,
\fIthese accounts are completely separate from any other accounts and passwords\fR\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
Only lowercase usernames are permitted for these accounts\&.
.sp .5v
.RE
.PP
The command allows arbitrary data to be associated with each account\&. This "private" data is opaque to
\fBDACS\fR
and is not used by
\fBDACS\fR\&. 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:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
the last time a password was changed;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
hashes of previous password values (so that they are not reused);
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
a note that the account\*(Aqs password must be changed;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
a password reminder question and answer;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
information for mutual authentication, such as a small image provided by the user that is displayed at login time;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
an encrypted representation of the password for recovery purposes (when absolutely necessary)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
several security questions (with answers), one of which might be selected at random and presented to the user at login time; or
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
user preferences\&.
.RE
.sp
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\&.
.PP
Passwords are accessed using the
\fBDACS\fR
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\&.
.PP
Use
\m[blue]\fBdacsauth(1)\fR\m[]\&\s-2\u[7]\d\s+2
to validate (test) a password\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
.PP
The password digest algorithm used depends on the
\m[blue]\fBPASSWORD_DIGEST\fR\m[]\&\s-2\u[8]\d\s+2
directive in effect\&. The
\m[blue]\fBPASSWORD_SALT_PREFIX\fR\m[]\&\s-2\u[9]\d\s+2
directive is also used\&.
.PP
Apart from using an authentication method stronger than one based on passwords, current best practice is to use a key derivation function like
\fBscrypt\fR
rather than a cryptographic digest for the
\m[blue]\fBPASSWORD_DIGEST\fR\m[]\&\s-2\u[8]\d\s+2\&. 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\&.
.PP
\fIPlaintext passwords are not stored by\fR
\fBdacspasswd\fR\&. 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)\&.
.PP
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
\m[blue]\fBrainbow tables\fR\m[]\&\s-2\u[10]\d\s+2)\&.
.PP
Only a
\fBDACS\fR
administrator should be able to successfully run this program from the command line\&. Because
\fBDACS\fR
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
\m[blue]\fBdacs_passwd(8)\fR\m[]\&\s-2\u[11]\d\s+2
web service\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
Even if the password file is stored as a plain text file, it is probably best to modify it only through this program or
\fBdacs_passwd\fR\&. Corrupting a password file entry may prevent signing on to the corresponding account or even all accounts that require the password file\&.
.PP
It is good administrative practice to store accounts with passwords separately from those without\&.
.sp .5v
.RE
.PP
This program is also available as a
\fBDACS\fR
web service,
\m[blue]\fBdacs_passwd(8)\fR\m[]\&\s-2\u[11]\d\s+2\&.
.SH "OPTIONS"
.PP
By default, the program will prompt for a new password if one is required by the selected operation\&.
.PP
The
\fBdacspasswd\fR
command recognizes these command line flags:
.PP
\fB\-p \fR\fB\fIpassword\fR\fR
.RS 4
Specify the password\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
A password given on the command line may be visible to other users on the same system\&.
.sp .5v
.RE
.RE
.PP
\fB\-pdd\fR
.RS 4
Delete the private data associated with
\fIusername\fR\&.
.RE
.PP
\fB\-pdg\fR
.RS 4
Get the private data associated with
\fIusername\fR
and print it to the standard output\&.
.RE
.PP
\fB\-pds \fR\fB\fIstring\fR\fR
.RS 4
Set (or replace)
\fIstring\fR
as private data associated with
\fIusername\fR\&.
.RE
.PP
\fB\-pdsf \fR\fB\fIfile\fR\fR
.RS 4
Set (or replace) the private data associated with
\fIusername\fR, reading it from
\fIfile\fR\&. If
\fIfile\fR
is "\-", then the data is read from the standard input\&. This flag and
\fB\-pf\fR
cannot both be used to read from the standard input\&.
.RE
.PP
\fB\-pf \fR\fB\fIfile\fR\fR
.RS 4
Read the password to use from
\fIfile\fR\&. If
\fIfile\fR
is "\-", then the password is read from the standard input without prompting\&. This flag and
\fB\-pdsf\fR
cannot both be used to read from the standard input\&.
.RE
.PP
\fB\-simple\fR
.RS 4
Use the
simple
item type expected by
\fBlocal_simple_authenticate\fR
instead of the default\&. The program will not prompt for passwords because these accounts do not use them\&.
.RE
.PP
\fB\-vfs\fR \fIvfs_uri\fR
.RS 4
Add
\fIvfs_uri\fR
as a
\m[blue]\fBVFS\fR\m[]\&\s-2\u[12]\d\s+2
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
\m[blue]\fBdacsauth(1)\fR\m[]\&\s-2\u[7]\d\s+2\&.
.RE
.PP
\fB\fIop\-spec\fR\fR
.RS 4
The following operations are recognized\&. The
\fB\-enable\fR,
\fB\-disable\fR,
\fB\-pdd\fR,
\fB\-pds\fR, and
\fB\-pdsf\fR
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)\&.
.PP
\fB\-a\fR
.br
\fB\-add\fR
.RS 4
Add
\fIusername\fR
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\&.
.RE
.PP
\fB\-d\fR
.br
\fB\-del\fR
.br
\fB\-delete\fR
.RS 4
Delete
\fIusername\fR
from the password file\&.
.RE
.PP
\fB\-dis\fR
.br
\fB\-disable\fR
.RS 4
Disable the account for
\fIusername\fR
so that authentication modules will not accept any password\&. If used with
\fB\-a\fR,
\fB\-s\fR, or
\fB\-u\fR, the account will also be disabled\&. The username may subsequently be enabled\&.
.RE
.PP
\fB\-en\fR
.br
\fB\-ena\fR
.br
\fB\-enable\fR
.RS 4
Re\-enable the account for
\fIusername\fR, which is currently disabled\&. The authentication modules will once again accept the password\&. If used with
\fB\-a\fR,
\fB\-s\fR, or
\fB\-u\fR, the account will also be enabled\&.
.RE
.PP
\fB\-g\fR
.br
\fB\-get\fR
.RS 4
Get the digest string for
\fIusername\fR
and print it to the standard output\&. A script can validate a password by passing this digest string to
\m[blue]\fBpassword()\fR\m[]\&\s-2\u[13]\d\s+2
along with the password obtained from the user\&.
.RE
.PP
\fB\-l\fR
.br
\fB\-list\fR
.br
\fB\-long\fR
.br
\fB\-longlist\fR
.RS 4
List
\fIusername\fR
if it appears in the password file\&. If no
\fIusername\fR
is provided, list all usernames\&. A disabled account is indicated by a \*(Aq*\*(Aq (which is not a valid character in a username)\&. The
\fB\-long\fR
and
\fB\-longlist\fR
variants display additional detail about each entry, such as the digest algorithm used\&.
.RE
.PP
\fB\-s\fR
.br
\fB\-set\fR
.RS 4
Set or reset the password for
\fIusername\fR, which must already exist in the password file\&. The enabled/disabled status is preserved unless overridden by a flag\&.
.RE
.PP
\fB\-regen\fR
.br
\fB\-regenerate\fR
.RS 4
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
\fBDACS\fR, it will be updated in the output file to the extent possible\&. The output file should be carefully examined and tested before being used\&.
.RE
.PP
\fB\-test\fR \fItest\-op\fR
.RS 4
Test an entry for one of several attributes and report the outcome through the program\*(Aqs exit status\&. The
\fItest\-op\fR
is one of the following keywords or abbreviated keywords:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIenabled\fR,
\fIena\fR,
\fIen\fR
.sp
Return an exit status of
0
if an account for
\fIusername\fR
exists
\fIand\fR
is enabled, or
1
if it does not exist or is disabled\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIexists\fR,
\fIex\fR
.sp
Return an exit status of
0
if an account for
\fIusername\fR
exists, or
1
if it does not exist\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIdata\fR
.sp
Return an exit status of
0
if an account for
\fIusername\fR
exists
\fIand\fR
has private data, or
1
if it does not exist or does not have private data\&. If an entry\*(Aqs private data is the empty string, it is considered to have private data\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIdisabled\fR,
\fIdis\fR
.sp
Return an exit status of
0
if an account for
\fIusername\fR
exists
\fIand\fR
is disabled, or
1
if it does not exist or is enabled\&.
.RE
.sp
.RE
.PP
\fB\-u\fR
.br
\fB\-up\fR
.br
\fB\-update\fR
.RS 4
Add
\fIusername\fR
to the password file or update an existing entry for
\fIusername\fR\&. 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\&.
.RE
.sp
.RE
.PP
\fB\-\-\fR
.RS 4
This flag signals the end of the flag arguments; a
\fIusername\fR
may follow, possibly beginning with a "\fB\-\fR" character\&.
.RE
.PP
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
\m[blue]\fBPASSWORD_CONSTRAINTS\fR\m[]\&\s-2\u[14]\d\s+2
directive that is configured\&.
.SH "EXAMPLES"
.PP
To list all of the accounts configured for the jurisdiction named
EXAMPLE:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacspasswd \-uj EXAMPLE \-list
auggie
bobo*
booboo
jj
.fi
.if n \{\
.RE
.\}
.sp
Note that the account for username
bobo
has been disabled\&.
.PP
To re\-enable
bobo\*(Aqs
account:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacspasswd \-uj EXAMPLE \-ena bobo
.fi
.if n \{\
.RE
.\}
.PP
To test if
bobo\*(Aqs
account is enabled:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacspasswd \-uj EXAMPLE \-test ena bobo
% echo $status
0
.fi
.if n \{\
.RE
.\}
.PP
To test if there are accounts for usernames
booboo
and
bob:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacspasswd \-uj EXAMPLE \-test exists booboo
% echo $status
0
% dacspasswd \-uj EXAMPLE \-test exists bob
% echo $status
1
.fi
.if n \{\
.RE
.\}
.PP
To reset the password for username
bobo
interactively:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacspasswd \-uj EXAMPLE \-set bobo
New password for bobo?
Re\-type new password for bobo?
.fi
.if n \{\
.RE
.\}
.sp
Note that the password text is not displayed\&.
.PP
To reset the password for username
bobo
using the program\*(Aqs standard input:
.sp
.if n \{\
.RS 4
.\}
.nf
% echo $newpasswd | dacspasswd \-uj EXAMPLE \-set \-pf \- bobo
.fi
.if n \{\
.RE
.\}
.PP
To create a new, disabled account for username
bob
and store the private data "On vacation":
.sp
.if n \{\
.RS 4
.\}
.nf
% dacspasswd \-uj EXAMPLE \-add \-pf \&./pwfile \-dis \-pds "On vacation" bob
.fi
.if n \{\
.RE
.\}
.sp
The password is read from the file
\&./pwfile\&.
.PP
To get the private data for username
bob:
.sp
.if n \{\
.RS 4
.\}
.nf
% set x=`dacspasswd \-uj EXAMPLE \-pdg bob`
% echo "$x"
On vacation
.fi
.if n \{\
.RE
.\}
.PP
To regenerate the current password file:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacspasswd \-uj EXAMPLE \-q \-vfs "[newpasswds]dacs\-kwv\-fs:/usr/local/dacs/tmp/newpasswd?field_sep=:" \-regen
.fi
.if n \{\
.RE
.\}
.sp
.SH "DIAGNOSTICS"
.PP
The program exits
0
if everything was fine, and non\-zero otherwise\&. A "false" outcome from the
\fB\-test\fR
operation is reflected by an exit status of
1\&. An error condition is indicated by an exit status of
2\&.
.SH "BUGS"
.PP
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\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBdacs_passwd(8)\fR\m[]\&\s-2\u[11]\d\s+2,
\m[blue]\fBdacsauth(1)\fR\m[]\&\s-2\u[7]\d\s+2,
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[15]\d\s+2,
\m[blue]\fBdacs_admin(8)\fR\m[]\&\s-2\u[16]\d\s+2,
\m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[17]\d\s+2
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[18]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2017 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[19]\d\s+2
file that accompanies the distribution for licensing information\&.
.SH "NOTES"
.IP " 1." 4
dacsoptions
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#dacsoptions
.RE
.IP " 2." 4
local_passwd_authenticate
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#local_passwd_authenticate
.RE
.IP " 3." 4
local_simple_authenticate
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#local_simple_authenticate
.RE
.IP " 4." 4
htpasswd(1)
.RS 4
\%http://httpd.apache.org/docs/2.4/programs/htpasswd.html
.RE
.IP " 5." 4
mod_auth_basic
.RS 4
\%http://httpd.apache.org/docs-2.4/mod/mod_auth_basic.html
.RE
.IP " 6." 4
mod_authn_dbm
.RS 4
\%http://httpd.apache.org/docs-2.4/mod/mod_authn_dbm.html
.RE
.IP " 7." 4
dacsauth(1)
.RS 4
\%http://dacs.dss.ca/man/dacsauth.1.html
.RE
.IP " 8." 4
PASSWORD_DIGEST
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#PASSWORD_DIGEST
.RE
.IP " 9." 4
PASSWORD_SALT_PREFIX
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#PASSWORD_SALT_PREFIX
.RE
.IP "10." 4
rainbow tables
.RS 4
\%http://en.wikipedia.org/wiki/Rainbow_table
.RE
.IP "11." 4
dacs_passwd(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_passwd.8.html
.RE
.IP "12." 4
VFS
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#VFS
.RE
.IP "13." 4
password()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#password
.RE
.IP "14." 4
PASSWORD_CONSTRAINTS
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#PASSWORD_CONSTRAINTS
.RE
.IP "15." 4
dacs_authenticate(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html
.RE
.IP "16." 4
dacs_admin(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_admin.8.html
.RE
.IP "17." 4
dacs.conf(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html
.RE
.IP "18." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "19." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE