.\" Copyright (c) 2001 Mark R V Murray
.\" All rights reserved.
.\" Copyright (c) 2001 Networks Associates Technology, Inc.
.\" All rights reserved.
.\"
.\" This software was developed for the FreeBSD Project by ThinkSec AS and
.\" NAI Labs, the Security Research Division of Network Associates, Inc.
.\" under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the
.\" DARPA CHATS research program.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. The name of the author may not be used to endorse or promote
.\"    products derived from this software without specific prior written
.\"    permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd January 14, 2019
.Dt PAM_SSH 8
.Sh NAME
.Nm pam_ssh
.Nd authentication and session management with SSH private keys
.Sh SYNOPSIS
.Op Ar service-name
.Ar module-type
.Ar control-flag
.Pa pam_ssh
.Op Ar options
.Sh DESCRIPTION
The
SSH
authentication service module for PAM,
.Nm
provides functionality for two PAM categories:
authentication
and session management.
In terms of the
.Ar module-type
parameter, they are the
.Dq Li auth
and
.Dq Li session
features.
It also provides null functions for the remaining categories.
.Ss SSH Authentication Module
The
SSH
authentication component
verifies the identity of a user
by prompting the user for a passphrase and verifying that it can
decrypt at least one of the user's SSH login
(or authentication)
keys using that passphrase.
.Pp
The user's SSH login keys must be
either located or symbolically linked into
the per-user dedicated folder
.Pa ~/.ssh/login-keys.d/
in the user's home directory.
.Pp
The following options may be passed to the authentication module:
.\".Bl -tag -width ".Cm use_first_pass"
.Bl -tag -width Ds -compact
.It Cm debug
.Xr syslog 3
debugging information at
.Dv LOG_DEBUG
level.
.It Cm use_first_pass
If the authentication module
is not the first in the stack,
and a previous module
obtained the user's password,
that password is used
to decrypt the user's SSH login keys.
If this fails,
then the authentication module returns failure
without prompting the user for a passphrase.
.\"This option has no effect
.\"if the authentication module
.\"is the first in the stack,
.\"or if no previous modules
.\"obtained the user's password.
.It Cm try_first_pass
Similar to the
.Cm use_first_pass
option,
except that if the previously obtained password fails
to decrypt any of the SSH login keys,
then the user is prompted for an SSH passphrase.
.It Cm nullok
Allow SSH keys with no passphrase.
.El
.Pp
If neither
.Cm use_first_pass
nor
.Cm try_first_pass
is specified,
.Nm pam_ssh
will unconditionally ask for an SSH passphrase.
.Pp
The now deprecated name
.Cm allow_blank_passphrase
for
.Cm nullok
is kept for compatibility reasons.
.Ss SSH Session Management Module
The
SSH
session management component
initiates sessions by launching an SSH agent,
passing it any user's SSH login keys successfully decrypted
during the authentication phase and any additional user SSH session keys successfully decrypted,
and sets dedicated environment variables
accordingly;
the environment variable TMPDIR,
which can be set through the pam_tmpdir module for instance,
is also honoured by being passed to the SSH agent.
.Pp
The SSH
session management component
terminates the session by killing the previously launched SSH agent
by sending it a
.Dv SIGTERM .
.Pp
The traditional SSH keys
.Pa ~/.ssh/id_rsa ,
.Pa ~/.ssh/id_dsa ,
.Pa ~/.ssh/id_ecdsa ,
and
.Pa ~/.ssh/id_ed25519
are considered as the default SSH session keys.
Nonetheless,
extra user SSH session keys can be
either located or symbolically linked into
the per-user dedicated folder
.Pa ~/.ssh/session-keys.d/
in the user's home directory.
.Pp
Provided that they have been successfully decrypted,
the SSH session management passes
to the launched SSH agent
first the session SSH keys in lexical order,
second the login SSH keys in lexical order,
and finally the traditional SSH keys in the reverse order cited above.
Since the SSH agent keeps
in its memory
for each passed key its first position (but its last comment),
each SSH key rank can be easily overwritten
with an appropriate symbolic link placed
in
.Pa ~/.ssh/session-keys.d/
or
.Pa ~/.ssh/login-keys.d/ ;
this is especially true for the traditional SSH keys.
The involved lexical order is performed against the SSH key file basenames
(according to the C/POSIX locale character collation rules).
Because actually their basenames are passed as comments,
their effective order might be easily checked with an appropriate SSH agent helper as
.Xr ssh-add 3 .
As final remark,
keep in mind that the SSH agent may place itself
SSH keys with protocol 1 before
SSH keys with protocol 2.
.Pp
The following option may be passed to the session management module:
.\".Bl -tag -width ".Cm use_first_pass"
.Bl -tag -width Ds -compact
.It Cm debug
.Xr syslog 3
debugging information at
.Dv LOG_DEBUG
level.
.El
.Sh INFORMATION LEAKS
Be careful with the using the
.Cm try_first_pass
option when
.Nm pam_ssh
is the first authentication module
because it will then leak information about existing users
without login keys: such users will not be asked for a specific SSH
passphrase, whereas non-existing users and existing users with
login keys will be asked for a passphrase.
.Sh FILES
.Bl -tag -width Ds -compact
.It Pa ~/.ssh/
This directory is the default per-user location
for all user-specific SSH configuration
and SSH authentication information
as expected by
SSH
and its friends.
.Pp
.It Pa ~/.ssh/id_rsa
.It Pa ~/.ssh/id_dsa
.It Pa ~/.ssh/id_ecdsa
.It Pa ~/.ssh/id_ed25519
Contains the traditional private key for authentication.
These files contain sensitive data
and should be readable by the user but not accessible by others:
any traditional private key file that is accessible by others
is simply ignored.
While the SSH authentication component ignores
the traditional private keys,
the SSH session management component passes
any successfully decrypted traditional key
to the launched SSH agent.
.Pp
.It Pa ~/.ssh/login-keys.d/
This directory is the dedicated per-user location for
files or symbolic links to files
that
contains SSH private keys
considered
by the SSH authentication component.
.Nm pam_ssh
ignores
any private key file that is accessible by others
or that possesses .disabled or .frozen as suffix.
Each login key successfully decrypted is passed
by the SSH session management component
to the launched SSH agent.
.Pp
.It Pa ~/.ssh/session-keys.d/
This directory is the dedicated per-user location for
files or symbolic links to files
that contains (extra) SSH private keys
considered
only
by the SSH session management component.
.Nm pam_ssh
ignores
any private key file that is accessible by others
or that possesses .disabled or .frozen as suffix.
Each session key successfully decrypted is passed
to the launched SSH agent.
.Pp
.It Pa /var/log/auth.log
Usual log file for
.Xr syslog 3 .
.Pp
.It Pa /usr/share/pam-configs/ssh
.Nm pam_ssh
Debian package
supplied authentication profile
as managed by
.Xr pam-auth-update 8 .
.El
.Sh SEE ALSO
.Xr ssh 1 ,
.Xr ssh-agent 1 ,
.Xr ssh-add 1 ,
.Xr ssh-keygen 1 ,
.Xr syslog 3 ,
.Xr pam.conf 5 ,
.Xr pam.d 5 ,
.Xr pam 8 ,
.Xr pam-auth-update 8 ,
.Xr pam_tmp
.Sh AUTHORS
.Pp
.An -nosplit
.An "Andrew J. Korty" <ajk@iu.edu>
wrote
.Nm .
.An "Dag-Erling Smorgrav"
wrote the original OpenPAM support code.
.An "Mark R V Murray"
wrote the original version of this manual page.
.An "Jens Peter Secher"
introduced the login-key concept.
Refreshed for Debian by
.An "Jerome Benoit" <calculus@rezozer.net>.
.Nm
is currently maintained by
.An "Wolfgang Rosenauer".
.\" eof