README

                           PAM module transient_token
                         ------------------------------

Transient_token is a PAM module for Linux to provide a token that can be
requested by a user that can then be used to authenticate once within a
short period.


Installation and usage
----------------------

To install:

    make
    sudo make install

To set up, add "pam_transient_token.so" as the auth method in the
appropriate files in /etc/pam.d.  If you want to be able to specify a
password that matches either the user's normal Unix password or a
transient_token then use unix-or-token-auth as the include instead of
common-auth.

To use, run get_transient_token.  It will print out a token and then go
into the background and wait for 60 seconds (by default) for an
authentication request from PAM before exiting.  The token looks like
this:

    TTK<uid>:<pid>:<base64-auth-string>

For example:

    TTK1000:13551:ZvGpYyBawL0ZXo/HjdYm/qBc0c/UE8Ds

Authentication is performed by the PAM module connecting to the Unix
domain socket given by the path "/tmp/transient-token-<uid>-<pid>" (by
default) and checking that it corresponds to the given user id and
process id; it then writes the Base64 auth string to the socket and
expects to receive the response "PASS" rather than "FAIL".

The token is never saved anywhere and is no longer valid after
get_transient_token exits.


Motivation
----------

This is expected to be useful occasionally for scripted authentication.
It is unlikely to be useful for passwords that need to be typed
manually: for that, see Markus Kuhn's one-time password login PAM module
at <https://www.cl.cam.ac.uk/~mgk25/otpw.html>.

For example, we can use this to use the authentication provided by ssh
keys to obtain a token to use for another login that doesn't support ssh
key authentication.

The remote desktop protocol (RDP) doesn't support ssh key
authentication.  So to log in to a remote server that is running both
sshd and xrdp (and with /etc/pam.d/xrdp-sesman modified appropriately)
you could log in over ssh and run

    get_transient_token

to get a token, and then use it on the command line to run xfreerdp:

    xfreerdp /v:server /u:ben /p:"$token"

That isn't very useful in itself but you can chain these commands
together to log in using ssh credentials:

    # edit as appropriate
    SERVER=server
    REMUSER=`whoami`
    REMPORT=3389

    # direct rdp connection
    ssh $SERVER \
        -x \
        get_transient_token \
    | (read TOKEN ; \
       xfreerdp /v:$SERVER:$REMPORT /u:$REMUSER /p:"$TOKEN")

    # rdp via ssh tunnel
    ssh $SERVER \
        -x \
        -L localhost:12345:localhost:$REMPORT \
        'get_transient_token ; sleep 10' \
    | (read TOKEN ; \
       xfreerdp /v:localhost:12345 /u:$REMUSER /p:"$TOKEN")


Security design
---------------

We assume that it is safe for PAM to delegate an authentication request
to a process running as a given user.  We are therefore not concerned
about the user setting up an "imposter" program at the other end of the
socket.  So the PAM module can send the token to get_transient_token to
authenticate.

In this implementation, the user being authenticated must be the same as
the user running the delegated authentication process.  (That is not
necessary in general.  For example, with some changes, a given user
could be trusted to generate tokens to authenticate any other user.)

The uid check provided by the Unix Domain Socket is required to verify
the uid is at the other end of the socket.  (The pid check is for
validation but not necessary.)