pam_ssh_auth_info.8

\" Copyright © 2021 - 2023 Eero Häkkinen <Eero+pam-ssh-auth-info@Häkkinen.fi>
\"
\" This manual page is free software: you can redistribute it and/or modify
\" it under the terms of the GNU General Public License as published by
\" the Free Software Foundation, either version 3 of the License, or
\" (at your option) any later version.
\"
\" This manual page is distributed in the hope that it will be useful,
\" but WITHOUT ANY WARRANTY; without even the implied warranty of
\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
\" GNU General Public License for more details.
\"
\" You should have received a copy of the GNU General Public License
\" along with this manual page.  If not, see <http://www.gnu.org/licenses/>.
.if '\*[.T]'html' \{\
.HEAD "<link href=""groff.css"" rel=""stylesheet"" type=""text/css"" />"
.HEAD "<meta name=""viewport"" content=""width=device-width, initial-scale=1.0"" />"
.HX 0
.\}

.TH "pam_ssh_auth_info" "8" "2022-01-16"

.SH "NAME"
pam_ssh_auth_info \- test SSH authentication information

.SH "SYNOPSIS"
.B  pam_ssh_auth_info.so
.RI [ flag ...]
.RI [ pattern [= pattern ]...]

.SH "DESCRIPTION"
The pam_ssh_auth_info.so PAM module is designed
to succeed or fail authentication
based on SSH authentication information
consisting of a list of
successfully completed authentication methods and
public credentials (e.g. keys)
used to authenticate the user.
One use is to select whether to load other modules based on this test.

Normally,
the module should be given zero or more patterns as module arguments, and
authentication will succeed
if SSH authentication information matches all of the patterns
(or any of or none of the patterns depending on the options).
If there are no previous successfully completed authentication methods,
SSH authentication information
is not available but missing and
authentication will neither succeed nor fail
(the module will return \fBPAM_IGNORE\fR).

.SH "OPTIONS"
.PP
The following \fIflag\fRs are supported:
.TP
.B all_of
All of the \fIpattern\fRs must match.
If zero \fIpattern\fRs are given as module arguments,
authentication will succeed
if SSH authentication information is available.
This is the default.
.TP
.B any_of
At least one of the \fIpattern\fRs must match.
If zero \fIpattern\fRs are given as module arguments,
authentication will fail
if SSH authentication information is available.
.TP
.B debug
Log debugging messages to syslog.
.TP
.IR \fBdisable = service [: service [...]]
Disable pattern matching for the services
listed in the colon separator service list.
.TP
.IR \fBenable = service [: service [...]]
Enable pattern matching only for the services
listed in the colon separator service list.
.TP
.B none_of
None of the \fIpattern\fRs may match.
If zero \fIpattern\fRs are given as module arguments,
authentication will succeed
if SSH authentication information is available.
.TP
.B quiet
Do not log failure or success messages to syslog.
.TP
.B quiet_fail
Do not log failure messages to syslog.
.TP
.B quiet_success
Do not log success messages to syslog.
.TP
.IR \fBrecursion_limit = limit
Change the recursion limit.
This affects extended patterns and \fB*\fR wildcard patterns.

.SS "PATTERNS"
.PP
Any character byte that appears in a pattern,
other than
the extended patterns and
the special pattern characters
described below,
matches itself.
.PP
The special pattern characters have the following meanings:
.TP
.B *
Matches any number of (including zero) word character bytes
but not a word separator (space).
.TP
.B =
Matches equal-sign (\fB=\fR) or a word separator (space).
.IP
This
enables more natural looking patterns and
allows patterns to be written without spaces
avoiding the need for square bracket quoting in PAM configuration files.
.TP
.B ?
Matches any word character byte
but not a word separator (space).
.TP
.B [
A pair of brackets introduces a character byte class.
A character byte class (\fB[\fR...\fB]\fR)
matches any word character byte in the class.
A complemented character byte class (\fB[!\fR...\fB]\fR)
matches any word character byte not in the class.
Neither matches a word separator (space).
A class may contain
character bytes (\fB[abcde]\fR) and
character byte ranges (\fB[a-e]\fR).
.TP
.B \\\\
Preserves the literal meaning of the following character byte.
.PP
The extended patterns have the following meanings:
.TP
.BI "?(" pattern "|" pattern "|" \fR... ")"
Matches zero or one occurence of the given patterns.
Does not match a word separator (space).
.TP
.BI "*(" pattern "|" pattern "|" \fR... ")"
Matches zero or more occurences of the given patterns.
Does not match a word separator (space).
.TP
.BI "+(" pattern "|" pattern "|" \fR... ")"
Matches one or more occurences of the given patterns.
Does not match a word separator (space).
.TP
.BI "@(" pattern "|" pattern "|" \fR... ")"
Matches one of the given patterns.
Does not match a word separator (space).
.TP
.BI "!(" pattern "|" pattern "|" \fR... ")"
Matches anything except one occurence of the given patterns.
Does not match a word separator (space).
.PP
SSH authentication information consists of lines having a format like
.IP
.IR method "[/" submethod "] [" key-type " " key-data "] [" info-word "]..."
.PP
SSH authentication information matches a pattern
if on any such line all the words or the initial words
match the pattern.

.SH "MODULE SERVICES PROVIDED"
.PP
All module types
(\fBaccount\fR, \fBauth\fR, \fBpassword\fR and \fBsession\fR)
are provided.
That said,
the \fBauth\fR type is still undoubtedly the most useful one.

.SH "RETURN VALUES"
.TP
.B PAM_AUTH_ERR
Pattern requirements are not met.
SSH authentication information
does not match all of or any of the patterns
(see the \fBall_of\fR and the \fBany_of\fR options) or
matches some of the patterns
(see the \fBnone_of\fR option).
.TP
.B PAM_IGNORE
The pattern matching is
disabled for the service (see the \fBdisable\fR option) or
not enabled for the service (see the \fBenable\fR option) or
SSH authentication information is missing.
.TP
.B PAM_SUCCESS
Pattern requirements are met.
SSH authentication information
matches all of or any of the patterns
(see the \fBall_of\fR and the \fBany_of\fR options) or
matches none of the patterns
(see the \fBnone_of\fR option).

.SH EXAMPLES
.PP
Always load an OATH module rule
(to request and check a one-time password)
but load a password module rule
(to request and check the user password)
only
if there are
no previous successfully completed authentications
(in which case SSH authentication information is missing):
.IP
.EX
auth  requisite         oath-module.so option...
auth  [success=1        \\
       default=ignore]  pam_ssh_auth_info.so
auth  required          password-module.so try_first_pass option...
.EE
.PP
Load an OATH module rule
(to request and check a one-time password)
only
if there are
no previous successfully completed
FIDO authenticator algorithm based
public key authentications
(in which case SSH authentication information either
is missing or
does not match the pattern)
but always load a password module rule
(to request and check the user password):
.IP
.EX
auth  [success=1        \\
       ignore=ignore    \\
       auth_err=ignore  \\
       default=die]     pam_ssh_auth_info.so quiet \\
                            publickey=*sk-*@openssh.com
auth  requisite         oath-module.so option...
auth  required          password-module.so try_first_pass option...
.EE
.PP
Require that there is
at least one previous successfully completed
FIDO authenticator algorithm based
public key authentication
(in which case
the key type
contains \(lqsk-\(rq and
ends with \(lq@openssh.com\(rq).
If multiple public key authentications are required,
only one of them is required to be a FIDO authenticator algorithm based one.
.IP
.EX
auth  requisite  pam_ssh_auth_info.so quiet \\
                     publickey=*sk-*@openssh.com
.EE
.PP
Require that there is
at least one previous successfully completed
FIDO authenticator algorithm based
public key authentication
(in which case
the key type
contains \(lqsk-\(rq and
ends with \(lq@openssh.com\(rq) and
at least one previous successfully completed
non-FIDO
public key authentication
(in which case
the key type
does not contain \(lqsk-\(rq or
does not end with \(lq@openssh.com\(rq).
.IP
.EX
auth  requisite  pam_ssh_auth_info.so quiet \\
                     publickey=*sk-*@openssh.com \\
                     publickey=!(*sk-*@openssh.com)
.EE

.SH "ENVIRONMENT"
.TP
.B SSH_AUTH_INFO_0
SSH authentication information
consisting of a list of
successfully completed authentication methods and
public credentials (e.g. keys)
used to authenticate the user.
This environment variable
is visible to PAM modules but not to user sessions and
is provided by OpenSSH server since version 7.8p1.
.TP
.B SSH_USER_AUTH
A location of a file
containing
SSH authentication information
consisting of a list of
successfully completed authentication methods and
public credentials (e.g. keys)
used to authenticate the user.
This environment variable
is visible to user sessions but not to PAM modules and
is provided by OpenSSH server since version 7.8p1
if the \fBExposeAuthInfo\fR server option is enabled.
This may be a useful source
for creating proper patterns.

.SH "NOTES"
In order to make this module useful,
the following \fBsshd_config\fR(5) options should be set
(either explicitly or via defaults):
.TP
.BR AuthenticationMethods
Should contain comma-separated lists of authentication method names
with
\fBkeyboard-interactive\fR,
\fBkeyboard-interactive:pam\fR or
\fBpassword\fR
as the last list items
so that there are
successfully completed authentication methods and
public credentials (e.g. keys)
during the PAM authentication.
For example
.RS
.RS
.EX
.B "AuthenticationMethods publickey,keyboard-interactive"
.EE
.RE
for
mandatory public key authentication and
mandatory PAM authentication
using keyboard-interactive challenge-response authentication or
.RS
.EX
.B "AuthenticationMethods publickey,keyboard-interactive keyboard-interactive"
.EE
.RE
for
optional public key authentication and
mandatory PAM authentication
using keyboard-interactive challenge-response authentication.
.RE
.TP
.BR ChallengeResponseAuthentication ", " KbdInteractiveAuthentication ", " PasswordAuthentication ", etc."
The relevant ones should be set to \fByes\fR.
.TP
.BR UsePAM
Should be set to \fByes\fR.

.SH "SEE ALSO"
.BR pam (7),
.BR sshd_config (5)

.na
.UR https://github.Eero.xn--Hkkinen-5wa.fi/pam-ssh-auth-info/
Home Page for pam_ssh_auth_info
.UE

.SH "AUTHOR"
Eero Häkkinen <Eero+pam-ssh-auth-info@Häkkinen.fi>

.SH "COPYRIGHT"
Copyright © 2021 - 2022 Eero Häkkinen <Eero+pam-ssh-auth-info@Häkkinen.fi>

This manual page is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.