.\" 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: dacs_passwd
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 08/23/2020
.\"    Manual: DACS Web Services Manual
.\"    Source: DACS 1.4.40
.\"  Language: English
.\"
.TH "DACS_PASSWD" "8" "08/23/2020" "DACS 1.4.40" "DACS Web Services 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"
dacs_passwd \- manage private \fBDACS\fR passwords
.SH "SYNOPSIS"
.HP \w'\fBdacs_passwd\fR\ 'u
\fBdacs_passwd\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR]
.SH "DESCRIPTION"
.PP
This program is part of the
\fBDACS\fR
suite\&.
.PP
The
\fBdacs_passwd\fR
web service is used to manage usernames and passwords recognized by
\m[blue]\fBlocal_passwd_authenticate\fR\m[]\&\s-2\u[2]\d\s+2, a
\fBDACS\fR
authentication module\&. This utility serves a similar purpose for
\fBlocal_passwd_authenticate\fR
that
\fBApache\fR\*(Aqs
\m[blue]\fBhtpasswd(1)\fR\m[]\&\s-2\u[3]\d\s+2
command does for its
\m[blue]\fBmod_authn_file\fR\m[]\&\s-2\u[4]\d\s+2
and
\m[blue]\fBmod_authn_dbm\fR\m[]\&\s-2\u[5]\d\s+2
modules\&. These accounts and passwords are used only by
\fBlocal_passwd_authenticate\fR
and are completely separate from any other accounts and passwords\&.
.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
Much of the functionality of this program is also available as a
\fBDACS\fR
utility,
\m[blue]\fBdacspasswd(1)\fR\m[]\&\s-2\u[6]\d\s+2, which operates on the same password files\&. Because
\m[blue]\fBdacs_admin(8)\fR\m[]\&\s-2\u[7]\d\s+2
provides the same functionality and more,
\fBdacs_passwd\fR
may be removed in a future release\&.
.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
\fBSecurity\fR
.ps -1
.br
.PP
This web service enforces several requirements over and above those specified by its access control rule\&. The
\fIUSERNAME\fR
argument must be syntactically valid and lowercase\&. The user must already be authenticated\&. To change his password, a (non\-admin) user must enter his current password\&.
.PP
The default
\fBDACS\fR
ACL restricts use of this web service to a
\fBDACS\fR
administrator and to users who are setting the password for their own
\fBDACS\fR
account at the receiving jurisdiction\&. Administrators should ensure that the ACL for
\fBdacs_passwd\fR
is correct for their environment\&.
.sp .5v
.RE
.SH "OPTIONS"
.SS "Web Service Arguments"
.PP
In addition to the
\m[blue]\fBstandard CGI arguments\fR\m[]\&\s-2\u[8]\d\s+2,
\fBdacs_passwd\fR
understands the following CGI arguments:
.PP
\fIOPERATION\fR
.RS 4
The following operations are supported:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIADD\fR
.sp
Like
\fISET\fR
but add or replace an entry for
\fIUSERNAME\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIDELETE\fR
.sp
Delete the account for
\fIUSERNAME\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIDISABLE\fR
.sp
Disable the account for
\fIUSERNAME\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIENABLE\fR
.sp
Enable the account for
\fIUSERNAME\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fILIST\fR
.sp
List
\fIUSERNAME\fR, if it exists, otherwise all usernames\&. A disabled account is indicated by a \*(Aq*\*(Aq (which is not a valid character in a username)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fISET\fR
.sp
Sets or resets a
\fBDACS\fR
password for
\fIUSERNAME\fR
to
\fINEW_PASSWORD\fR\&. The
\fICONFIRM_NEW_PASSWORD\fR
argument must also be given and be identical to
\fINEW_PASSWORD\fR\&. Unless the operation is performed by a
\fBDACS\fR
administrator (i\&.e\&., an
\m[blue]\fBADMIN_IDENTITY\fR\m[]\&\s-2\u[9]\d\s+2) or disabled by the
\m[blue]\fBPASSWORD_OPS_NEED_PASSWORD\fR\m[]\&\s-2\u[10]\d\s+2
directive, the current password for
\fIUSERNAME\fR
must be given as
\fIPASSWORD\fR\&.
.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
For users other than a
\fBDACS\fR
administrator, a password must meet certain requirements on its length and the character set from which it is comprised\&. Note that these requirements are only significant at the time a password is set or changed; existing passwords are unaffected by changes to the configuration directives\&. Please refer to the
\m[blue]\fBPASSWORD_CONSTRAINTS\fR\m[]\&\s-2\u[11]\d\s+2
directive\&.
.sp
Users should be made aware of security issues related to passwords, including better techniques for selecting passwords and keeping them private\&.
.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
\fBHow to choose better passwords\fR
.ps -1
.br
Most users can benefit from adopting a method for password selection similar to the one described in
\m[blue]\fBthis proposal\fR\m[]\&\s-2\u[12]\d\s+2\&. It suggests that users construct
\fIsite\-specific passwords\fR
from three separate components:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
\fIPIN\-1\fR, a short,
\fIrandom\fR
string that is common to all of the user\*(Aqs passwords,
\fIkept secret\fR, and unlikely to be in any dictionary;
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
\fISITE\fR, a string that is derived from a site\*(Aqs name (or domain name) using some simple and easy\-to\-remember procedure (e\&.g\&., using an obvious abbreviation or prefix, or the first four letters or consonents, perhaps mixing upper and lower case); and
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
\fIPIN\-2\fR, a short, site\-specific
\fIrandom\fR
string that is different for each of the user\*(Aqs passwords, and not likely to be in any dictionary\&.
.RE
.sp
\fIPIN\-1\fR
is memorized by the user\&. The other two components may be written down but must be kept in a relatively secure location (such as in the user\*(Aqs wallet or in a locked desk drawer)\&.
.sp
The user forms passwords by combining these three components in any order that is easy to remember, like:
.sp
.if n \{\
.RS 4
.\}
.nf
\fISITE\fR \fIPIN\-2\fR \fIPIN\-1\fR
.fi
.if n \{\
.RE
.\}
.sp
Following that ordering, for the site
www\&.example\&.net, a user might select the password "exampleRB8s#i8", where "example" (component 2,
\fISITE\fR) is derived from the site\*(Aqs domain name, "RB8s" is a random string used with this password only (component 3,
\fIPIN\-2\fR), and "#i8" is the user\*(Aqs secret
PIN
(component 1,
\fIPIN\-1\fR)\&. Because it is probably difficult to remember, the user might create a note with "www\&.example\&.net RB8s" written on it but
\fInot\fR
\fIPIN\-1\fR\&.
.sp
For
httpd\&.apache\&.org, the same user might select the password "httpd33ABB#i8"\&.
.sp
For the site
dacs\&.dss\&.ca, the user might select the password "dacsceIM#i8"\&.
.sp
Note that because the characters comprising
\fIPIN\-1\fR
must be acceptable in all sites\*(Aq passwords, and some sites accept a rather limited character set for their passwords, it may be necessary to restrict
\fIPIN\-1\fR
to the alphanumeric alphabet\&. The other two components can be chosen from whatever password characters are permitted by the particular site\&. As some sites unfortunately allow only relatively short passwords, it is preferable to shorten
\fISITE\fR
rather than either of the other two components\&.
.sp
Provided the basic rules are followed, a user can strengthen the method by making minor changes\&. As a simple example, one or more separating characters, also from a restricted character set, might be added before and after the middle component:
.sp
.if n \{\
.RS 4
.\}
.nf
\fISITE\fR Z \fIPIN\-2\fR Z \fIPIN\-1\fR
.fi
.if n \{\
.RE
.\}
.sp
In this example, a \*(AqZ\*(Aq is used as a separating character\&.
.sp
Since most people are not very good at it, the random strings should be chosen using a good\-quality random generator, such as the
\m[blue]\fBrandom()\fR\m[]\&\s-2\u[13]\d\s+2
function:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsexpr \-e "random(string, 4, \*(Aqa\-zA\-Z0\-9,\&./;@#\*(Aq)"
"y2FJ"
.fi
.if n \{\
.RE
.\}
.sp
Or, on
FreeBSD
or
macOS:
.sp
.if n \{\
.RS 4
.\}
.nf
% jot \-r \-c 20 33 126 | rs \-g 0 4
ib2Y
25$z
vI9Z
^KpZ
51b7
.fi
.if n \{\
.RE
.\}
.sp
In addition to being difficult to guess because of their random components and reasonably large character set, these passwords are different for each site; should one password be compromised, the others are not immediately available to an attacker\&. Similarly, the written strings cannot be immediately exploited if they are stolen or copied\&. The strength of the method can be increased by making either or both
PIN
components longer, chosen from a larger space of characters, or by inserting one or more characters between components\&. Software is available to help evaluate password strength (e\&.g\&.,
\m[blue]\fBHow Big is Your Haystack?\fR\m[]\&\s-2\u[14]\d\s+2), but avoid giving out the actual password you intend to use\&.
.sp .5v
.RE
.RE
.sp
.RE
.PP
\fIACCOUNT\fR
.RS 4
Either
PASSWD
(the default) or
SIMPLE, case insensitively, to select between the item types
passwds
and
simple, respectively\&. The requested item type must be configured (see
\m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[15]\d\s+2)\&.
.RE
.PP
\fIUSERNAME\fR
.RS 4
The
\fBDACS\fR
username of interest\&.
.RE
.PP
\fIFORMAT\fR
.RS 4
By default, output is emitted in HTML\&. Several varieties of XML output can be selected, however, using the
\fIFORMAT\fR
argument (please refer to
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[16]\d\s+2
and
\m[blue]\fBdacs_passwd\&.dtd\fR\m[]\&\s-2\u[17]\d\s+2)\&.
.RE
.SH "DIAGNOSTICS"
.PP
The program exits
0
if everything was fine,
1
if an error occurred\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBdacspasswd(1)\fR\m[]\&\s-2\u[6]\d\s+2,
\m[blue]\fBdacs_admin(8)\fR\m[]\&\s-2\u[7]\d\s+2,
\m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[18]\d\s+2
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[19]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2017 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[20]\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
htpasswd(1)
.RS 4
\%http://httpd.apache.org/docs/2.4/programs/htpasswd.html
.RE
.IP " 4." 4
mod_authn_file
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/mod_authn_file.html
.RE
.IP " 5." 4
mod_authn_dbm
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/mod_authn_dbm.html
.RE
.IP " 6." 4
dacspasswd(1)
.RS 4
\%http://dacs.dss.ca/man/dacspasswd.1.html
.RE
.IP " 7." 4
dacs_admin(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_admin.8.html
.RE
.IP " 8." 4
standard CGI arguments
.RS 4
\%http://dacs.dss.ca/man/dacs.services.8.html#standard_cgi_args
.RE
.IP " 9." 4
ADMIN_IDENTITY
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#ADMIN_IDENTITY
.RE
.IP "10." 4
PASSWORD_OPS_NEED_PASSWORD
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#PASSWORD_OPS_NEED_PASSWORD
.RE
.IP "11." 4
PASSWORD_CONSTRAINTS
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#PASSWORD_CONSTRAINTS
.RE
.IP "12." 4
this proposal
.RS 4
\%http://www.f-secure.com/weblog/archives/00001691.html
.RE
.IP "13." 4
random()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#random
.RE
.IP "14." 4
How Big is Your Haystack?
.RS 4
\%https://www.grc.com/haystack.htm
.RE
.IP "15." 4
dacs.conf(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#VFS
.RE
.IP "16." 4
dacs(1)
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html
.RE
.IP "17." 4
dacs_passwd.dtd
.RS 4
\%http://dacs.dss.ca/man/../dtd-xsd/dacs_passwd.dtd
.RE
.IP "18." 4
dacs.conf(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html
.RE
.IP "19." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "20." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE