.\" 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: pamd
.\"    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 "PAMD" "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"
pamd \- PAM transaction server
.SH "SYNOPSIS"
.HP \w'\fBpamd\fR\ 'u
\fBpamd\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR] [\fB\-daemon\fR] [\fB\-fork\fR] [\fB\-h\ \fR\fB\fIhostname\fR\fR] [\fB\-http\fR] [\fB\-inetd\fR] [\fB\-nofork\fR]
.br
[\fB\-p\ \fR\fB\fIportnum\fR\fR] [\fB\-policy\ \fR\fB\fIname\fR\fR] [\fB\-secure\fR] [\fB\-unsecure\fR]
.SH "DESCRIPTION"
.PP
This program is part of the
\fBDACS\fR
suite\&.
.PP
The
\fBpamd\fR
server is required by the
\m[blue]\fBlocal_pam_authenticate\fR\m[]\&\s-2\u[2]\d\s+2
authentication module\&. It acts as a proxy for
\fBlocal_pam_authenticate\fR, calling PAM functions on its behalf\&. The
\fBpamd\fR
server may be started from
\m[blue]\fBinetd(8)\fR\m[]\&\s-2\u[3]\d\s+2
or from the command line, but it must be running for
\fBDACS\fR
to perform PAM\-based authentication\&.
.PP
Each
\fBpamd\fR
process is involved in an arbitrarily long "conversation" or "transaction" with one or more executions of
\fBlocal_pam_authenticate\fR\&. For instance,
\fBpamd\*(Aqs\fR
initial response to
\fBlocal_pam_authenticate\fR
might be that it requires an account name; upon receiving the account name from
\fBlocal_pam_authenticate\fR,
\fBpamd\*(Aqs\fR
response might be that it requires the password for the account; and upon receiving the password,
\fBpamd\fR
would indicate success or failure, depending on whether an acceptable username/password pair was received\&. The eventual outcome of a transaction is that authentication succeeds, fails, or could not be completed because an error occurs\&.
.PP
\fBpamd\fR
must be run on the host where
\m[blue]\fBpam(3)\fR\m[]\&\s-2\u[4]\d\s+2
processing is being performed, which is not necessarily the same host where
\fBlocal_pam_authenticate\fR
is executed\&.
.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
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBpamd\fR
will usually be run as
root
so that it can access the files it needs to perform authentication\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBpamd\fR
is not a
\fBDACS\fR
web service and is not protected by
\fBDACS\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The protocol between
\fBpamd\fR
and its client may include sensitive material, such as passwords\&. If both programs are run on the same host, this is probably not an issue\&. If there is any possibility of eavesdropping etc\&. by an attacker, however, communication should be secured through an SSL/TLS wrapper\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBpamd\fR
should probably not be run on a world\-accessible server, since it would offer a way for attackers to try to guess passwords\&.
.RE
.sp .5v
.RE
.PP
The operating system\*(Aqs PAM policy file is consulted \- see
\m[blue]\fBpam\&.conf(5)\fR\m[]\&\s-2\u[5]\d\s+2\&. The default PAM service name is "dacs" (see
\m[blue]\fBpam_start(3)\fR\m[]\&\s-2\u[6]\d\s+2), which may be used by PAM to locate the appropriate policy file\&. A different policy name can be specified using the
\fB\-policy\fR
flag\&.
.PP
The prompts that passed from PAM to
\fBpamd\fR
to
\fBlocal_pam_authenticate\fR
to
\fBdacs_authenticate\fR
(or
\fBdacsauth\fR) are simply displayed to the user\&. The user must understand what the prompts mean (e\&.g\&., that "Login:" means to provide a Unix account name)\&.
.PP
\fBpamd\fR
can be used by non\-\fBDACS\fR
applications\&. The protocol, though simple, is not yet documented other than within the source code\&. A program called
\fBpamd\-client\fR
is available for testing and debugging
\fBpamd\fR; it is built when PAM support is required, but is neither installed nor documented (see the source code for basic instructions)\&.
.SH "OPTIONS"
.PP
In addition to the standard
\m[blue]\fB\fIdacsoptions\fR\fR\m[]\&\s-2\u[1]\d\s+2,
\fBpamd\fR
recognizes these command line flags:
.PP
\fB\-daemon\fR
.RS 4
Wait for a connection, then service the request\&. Mutually exclusive with
\fB\-inetd\fR\&.
.RE
.PP
\fB\-fork\fR
.RS 4
Create a new process to service each request\&. It implies the
\fB\-daemon\fR
flag\&.
.RE
.PP
\fB\-h \fR\fB\fIhostname\fR\fR
.RS 4
If
\fBpamd\fR
is running on a host with multiple IP addresses, this specifies the hostname (or IP address) to listen to for incoming requests\&. If not provided, the
\m[blue]\fBPAMD_HOST\fR\m[]\&\s-2\u[7]\d\s+2
directive will be consulted; if unavailable,
\m[blue]\fBgethostname(3)\fR\m[]\&\s-2\u[8]\d\s+2
will be used\&.
.RE
.PP
\fB\-http\fR
.RS 4
This flag is reserved for future use\&.
.RE
.PP
\fB\-inetd\fR
.RS 4
The server assumes it has been started by
\m[blue]\fBinetd(8)\fR\m[]\&\s-2\u[3]\d\s+2
and therefore does not wait for a connection\&. It exits after servicing the request\&. This is the default behaviour and preferred way to configure
\fBpamd\fR\&. This mode of operation assumes that an entry has been added to
\m[blue]\fBinetd\&.conf(5)\fR\m[]\&\s-2\u[9]\d\s+2
that looks much like this:
.sp
.if n \{\
.RS 4
.\}
.nf
dacs\-pamd stream tcp nowait root /usr/local/dacs/sbin/pamd pamd \-uj EXAMPLE \-inetd
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
\fB\-nofork\fR
.RS 4
This flag, which implies the
\fB\-daemon\fR, causes the
\fBpamd\fR
server to exit after servicing one request (which is useful when debugging)\&. This is the default behaviour of
\fB\-daemon\fR
mode\&.
.RE
.PP
\fB\-p \fR\fB\fIportnum\fR\fR
.RS 4
This specifies the port number to listen to, overriding any
\m[blue]\fBPAMD_PORT\fR\m[]\&\s-2\u[10]\d\s+2
directive in effect\&. It can also be a service name\&. Any otherwise unassigned port number on the system from
49152
through
65535
(i\&.e\&., one in the dynamic and/or private range) ought to be acceptable\&.
.sp
If neither this flag nor a
PAMD_PORT
directive is provided, the program will try to find the port associated with the
dacs\-pamd
service name in
\m[blue]\fBservices(5)\fR\m[]\&\s-2\u[11]\d\s+2\&. For example:
.sp
.if n \{\
.RS 4
.\}
.nf
dacs\-pamd       17000/tcp  # DACS pamd
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
\fB\-policy \fR\fB\fIname\fR\fR
.RS 4
Use
\fIname\fR
as the PAM policy name instead of the default\&.
.RE
.PP
\fB\-secure\fR
.RS 4
The client must supply valid
\fBDACS\fR
administrative credentials encapsulated within a
\fBDACS\fR
cookie\&. This is the default\&.
.RE
.PP
\fB\-unsecure\fR
.RS 4
Administrative credentials are not required, but if they are provided they must be valid\&. This should probably be used only when testing or if client identification is not an issue or has been addressed in some other way\&.
.RE
.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
When the
\fB\-secure\fR
flag is in effect,
\fBpamd\fR
must be associated with a jurisdiction\&. Therefore, the
\fBDACS\fR
configuration files are read and the jurisdiction must be specified on the command line (e\&.g\&., using the
\fB\-uj\fR
flag)\&.
.sp .5v
.RE
.SH "EXAMPLE"
.PP
For testing purposes, or to better understand how
\fBpamd\fR
works, you can run it manually and interact with it using
\m[blue]\fBtelnet(1)\fR\m[]\&\s-2\u[12]\d\s+2, for example, which takes the place of
\fBlocal_pam_authenticate\fR\&. You must have PAM authentication configured on the host where you run
\fBpamd\fR
and you will probably need to run it as
root\&. This is best done using two windows; start
\fBpamd\fR
in the first window and then
\fBtelnet\fR
to it from the second window\&.
.PP
An interaction to perform username/password authentication will look something like the following (substitute your jurisdiction\*(Aqs name for
myjur, your jurisdiction\*(Aqs domain name or IP address for
myjur\&.example\&.com, and use a username and password pair that is recognized on your system)\&. The first
\fBtelnet\fR
connection receives a prompt for a username (labeled "Login:" and assigned the variable name
\fIAUTH_PROMPT_VAR1\fR) from
\fBpamd\fR, a transaction identifier (\fITRANSID\fR) "10\&.0\&.0\&.124:56372:66664:53983facb39881b2" for this session, and port number to use for subsequent operations belonging to this transaction (62475)\&. The second
\fBtelnet\fR
connection provides the
\fITRANSID\fR
and username (AUTH_PROMPT_VAR1="auggie"), and receives a prompt for a password ("Password:", assigned the variable name
\fIAUTH_PROMPT_VAR2\fR)\&. The third
\fBtelnet\fR
connection provides the
\fITRANSID\fR
and the password (AUTH_PROMPT_VAR2="doggy"), and receives the result of authentication ("Success")\&.
.sp
.if n \{\
.RS 4
.\}
.nf
# \&./pamd \-uj myjur \-ll debug \-daemon \-unsecure \-nofork
pamd[info]: Site config file is "/usr/local/dacs/federations/site\&.conf"
pamd[info]: Config file is "/usr/local/dacs/federations/dacs\&.conf"
pamd[info]: This is jurisdiction DSS::myjur
pamd[info]: Secure mode is off
pamd[debug]: Waiting for initial input block\&.\&.\&.
pamd[debug]: No username
pamd[debug]: Calling pam_authenticate
pamd[debug]: pamd_conv: reply to port 62475
pamd[debug]: TRANSID is "10\&.0\&.0\&.124:56372:66664:53983facb39881b2"
pamd[debug]:   type="text"
pamd[debug]:   label="Login:"
pamd[debug]:   varname="AUTH_PROMPT_VAR1"
pamd[debug]: pamd_conv: waiting 60 seconds for reply
pamd[debug]: pamd_conv: received connection
pamd[debug]: Reading reply\&.\&.\&.
pamd[debug]: pamd_conv: reply to port 62475
pamd[debug]: TRANSID is "10\&.0\&.0\&.124:62475:66695:fc855a7d68e8b1eb"
pamd[debug]:   type="password"
pamd[debug]:   label="Password:"
pamd[debug]:   varname="AUTH_PROMPT_VAR2"
pamd[debug]: pamd_conv: waiting 60 seconds for reply
pamd[debug]: pamd_conv: received connection
pamd[debug]: Reading reply\&.\&.\&.
pamd[debug]: Success
pamd[debug]: result="ok"
pamd[debug]: username="auggie"
.fi
.if n \{\
.RE
.\}
.sp

.sp
.if n \{\
.RS 4
.\}
.nf
% telnet myjur\&.example\&.com 17000
Trying 10\&.0\&.0\&.124\&.\&.\&.
Connected to bsd6\&.dss\&.bc\&.ca\&.
Escape character is \*(Aq^]\*(Aq\&.

Connection closed by foreign host\&.
% telnet myjur\&.example\&.com 62475
Trying 10\&.0\&.0\&.124\&.\&.\&.
Connected to bsd6\&.dss\&.bc\&.ca\&.
Escape character is \*(Aq^]\*(Aq\&.
TRANSID="10\&.0\&.0\&.124:62475:66695:fc855a7d68e8b1eb"
AUTH_PROMPT_VAR1="auggie"

Connection closed by foreign host\&.
% telnet myjur\&.example\&.com 62475
Trying 10\&.0\&.0\&.124\&.\&.\&.
Connected to bsd6\&.dss\&.bc\&.ca\&.
Escape character is \*(Aq^]\*(Aq\&.
TRANSID="10\&.0\&.0\&.124:62475:66695:fc855a7d68e8b1eb"
AUTH_PROMPT_VAR2="doggy"

result="ok"
username="auggie"
Connection closed by foreign host\&.
.fi
.if n \{\
.RE
.\}
.sp
.SH "DIAGNOSTICS"
.PP
The program exits
0
if everything was fine,
1
if an error occurred\&.
.SH "BUGS"
.PP
The
\fB\-daemon\fR
flag should cause the process to detach and put itself in the background unless overridden by another flag; at present it must be started in the background "manually"\&.
.PP
The
\fB\-http\fR
flag, which would allow a
\fBpamd\fR
session to be started with a web service request, is not implemented\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[13]\d\s+2,
\m[blue]\fBdacsauth(1)\fR\m[]\&\s-2\u[14]\d\s+2,
\m[blue]\fBpam(3)\fR\m[]\&\s-2\u[15]\d\s+2,
\m[blue]\fBX/Open Single Sign\-On Service (XSSO) preliminary specification\fR\m[]\&\s-2\u[16]\d\s+2
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[17]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2018 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[18]\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_pam_authenticate
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#local_pam_authenticate
.RE
.IP " 3." 4
inetd(8)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=inetd&apropos=0&sektion=8&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP " 4." 4
pam(3)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=pam&apropos=0&sektion=0&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP " 5." 4
pam.conf(5)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=pam.conf&apropos=0&sektion=5&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP " 6." 4
pam_start(3)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=pam_start&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP " 7." 4
PAMD_HOST
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#PAMD_HOST
.RE
.IP " 8." 4
gethostname(3)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=gethostname&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP " 9." 4
inetd.conf(5)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=inetd.conf&apropos=0&sektion=5&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "10." 4
PAMD_PORT
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#PAMD_PORT
.RE
.IP "11." 4
services(5)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=services&apropos=0&sektion=5&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "12." 4
telnet(1)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=telnet&apropos=0&sektion=1&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "13." 4
dacs_authenticate(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html
.RE
.IP "14." 4
dacsauth(1)
.RS 4
\%http://dacs.dss.ca/man/dacsauth.1.html
.RE
.IP "15." 4
pam(3)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=pam&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "16." 4
X/Open Single Sign-On Service (XSSO) preliminary specification
.RS 4
\%http://www.opengroup.org/pubs/catalog/p702.htm
.RE
.IP "17." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "18." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE