pamd

PAMD(8)                     DACS Web Services Manual                     PAMD(8)



NAME
       pamd - PAM transaction server

SYNOPSIS
       pamd [dacsoptions[1]] [-daemon] [-fork] [-h hostname] [-http] [-inetd]
            [-nofork]
            [-p portnum] [-policy name] [-secure] [-unsecure]

DESCRIPTION
       This program is part of the DACS suite.

       The pamd server is required by the local_pam_authenticate[2]
       authentication module. It acts as a proxy for local_pam_authenticate,
       calling PAM functions on its behalf. The pamd server may be started from
       inetd(8)[3] or from the command line, but it must be running for DACS to
       perform PAM-based authentication.

       Each pamd process is involved in an arbitrarily long "conversation" or
       "transaction" with one or more executions of local_pam_authenticate. For
       instance, pamd's initial response to local_pam_authenticate might be that
       it requires an account name; upon receiving the account name from
       local_pam_authenticate, pamd's response might be that it requires the
       password for the account; and upon receiving the password, pamd 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.

       pamd must be run on the host where pam(3)[4] processing is being
       performed, which is not necessarily the same host where
       local_pam_authenticate is executed.

           Securitypamd will usually be run as root so that it can access the files
               it needs to perform authentication.

           •   pamd is not a DACS web service and is not protected by DACS.

           •   The protocol between pamd 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.

           •   pamd should probably not be run on a world-accessible server,
               since it would offer a way for attackers to try to guess
               passwords.

       The operating system's PAM policy file is consulted - see pam.conf(5)[5].
       The default PAM service name is "dacs" (see pam_start(3)[6]), which may
       be used by PAM to locate the appropriate policy file. A different policy
       name can be specified using the -policy flag.

       The prompts that passed from PAM to pamd to local_pam_authenticate to
       dacs_authenticate (or dacsauth) 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).

       pamd can be used by non-DACS applications. The protocol, though simple,
       is not yet documented other than within the source code. A program called
       pamd-client is available for testing and debugging pamd; it is built when
       PAM support is required, but is neither installed nor documented (see the
       source code for basic instructions).

OPTIONS
       In addition to the standard dacsoptions[1], pamd recognizes these command
       line flags:

       -daemon
           Wait for a connection, then service the request. Mutually exclusive
           with -inetd.

       -fork
           Create a new process to service each request. It implies the -daemon
           flag.

       -h hostname
           If pamd 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 PAMD_HOST[7] directive will be
           consulted; if unavailable, gethostname(3)[8] will be used.

       -http
           This flag is reserved for future use.

       -inetd
           The server assumes it has been started by inetd(8)[3] and therefore
           does not wait for a connection. It exits after servicing the request.
           This is the default behaviour and preferred way to configure pamd.
           This mode of operation assumes that an entry has been added to
           inetd.conf(5)[9] that looks much like this:

               dacs-pamd stream tcp nowait root /usr/local/dacs/sbin/pamd pamd -uj EXAMPLE -inetd


       -nofork
           This flag, which implies the -daemon, causes the pamd server to exit
           after servicing one request (which is useful when debugging). This is
           the default behaviour of -daemon mode.

       -p portnum
           This specifies the port number to listen to, overriding any
           PAMD_PORT[10] 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.

           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 services(5)[11]. For example:

               dacs-pamd       17000/tcp  # DACS pamd


       -policy name
           Use name as the PAM policy name instead of the default.

       -secure
           The client must supply valid DACS administrative credentials
           encapsulated within a DACS cookie. This is the default.

       -unsecure
           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.

           Note
           When the -secure flag is in effect, pamd must be associated with a
           jurisdiction. Therefore, the DACS configuration files are read and
           the jurisdiction must be specified on the command line (e.g., using
           the -uj flag).

EXAMPLE
       For testing purposes, or to better understand how pamd works, you can run
       it manually and interact with it using telnet(1)[12], for example, which
       takes the place of local_pam_authenticate. You must have PAM
       authentication configured on the host where you run pamd and you will
       probably need to run it as root. This is best done using two windows;
       start pamd in the first window and then telnet to it from the second
       window.

       An interaction to perform username/password authentication will look
       something like the following (substitute your jurisdiction's name for
       myjur, your jurisdiction's domain name or IP address for
       myjur.example.com, and use a username and password pair that is
       recognized on your system). The first telnet connection receives a prompt
       for a username (labeled "Login:" and assigned the variable name
       AUTH_PROMPT_VAR1) from pamd, a transaction identifier (TRANSID)
       "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 telnet connection provides the TRANSID and username
       (AUTH_PROMPT_VAR1="auggie"), and receives a prompt for a password
       ("Password:", assigned the variable name AUTH_PROMPT_VAR2). The third
       telnet connection provides the TRANSID and the password
       (AUTH_PROMPT_VAR2="doggy"), and receives the result of authentication
       ("Success").

           # ./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"



           % telnet myjur.example.com 17000
           Trying 10.0.0.124...
           Connected to bsd6.dss.bc.ca.
           Escape character is '^]'.

           Connection closed by foreign host.
           % telnet myjur.example.com 62475
           Trying 10.0.0.124...
           Connected to bsd6.dss.bc.ca.
           Escape character is '^]'.
           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 '^]'.
           TRANSID="10.0.0.124:62475:66695:fc855a7d68e8b1eb"
           AUTH_PROMPT_VAR2="doggy"

           result="ok"
           username="auggie"
           Connection closed by foreign host.


DIAGNOSTICS
       The program exits 0 if everything was fine, 1 if an error occurred.

BUGS
       The -daemon 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".

       The -http flag, which would allow a pamd session to be started with a web
       service request, is not implemented.

SEE ALSO
       dacs_authenticate(8)[13], dacsauth(1)[14], pam(3)[15], X/Open Single
       Sign-On Service (XSSO) preliminary specification[16]

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

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

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

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

        3. inetd(8)
           https://www.freebsd.org/cgi/man.cgi?query=inetd&apropos=0&sektion=8&manpath=FreeBSD+10.3-RELEASE&format=html

        4. pam(3)
           https://www.freebsd.org/cgi/man.cgi?query=pam&apropos=0&sektion=0&manpath=FreeBSD+10.3-RELEASE&format=html

        5. pam.conf(5)
           https://www.freebsd.org/cgi/man.cgi?query=pam.conf&apropos=0&sektion=5&manpath=FreeBSD+10.3-RELEASE&format=html

        6. pam_start(3)
           https://www.freebsd.org/cgi/man.cgi?query=pam_start&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html

        7. PAMD_HOST
           http://dacs.dss.ca/man/dacs.conf.5.html#PAMD_HOST

        8. gethostname(3)
           https://www.freebsd.org/cgi/man.cgi?query=gethostname&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html

        9. inetd.conf(5)
           https://www.freebsd.org/cgi/man.cgi?query=inetd.conf&apropos=0&sektion=5&manpath=FreeBSD+10.3-RELEASE&format=html

       10. PAMD_PORT
           http://dacs.dss.ca/man/dacs.conf.5.html#PAMD_PORT

       11. services(5)
           https://www.freebsd.org/cgi/man.cgi?query=services&apropos=0&sektion=5&manpath=FreeBSD+10.3-RELEASE&format=html

       12. telnet(1)
           https://www.freebsd.org/cgi/man.cgi?query=telnet&apropos=0&sektion=1&manpath=FreeBSD+10.3-RELEASE&format=html

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

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

       15. pam(3)
           https://www.freebsd.org/cgi/man.cgi?query=pam&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html

       16. X/Open Single Sign-On Service (XSSO) preliminary specification
           http://www.opengroup.org/pubs/catalog/p702.htm

       17. www.dss.ca
           http://www.dss.ca

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



DACS 1.4.40                        02/19/2019                            PAMD(8)