pam_ssh_auth_info - Man Page

test SSH authentication information

Synopsis

pam_ssh_auth_info.so [flag...] [pattern[=pattern]...]

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 PAM_IGNORE).

Options

The following flags are supported:

all_of: All of the patterns must match. If zero patterns are given as module arguments, authentication will succeed if SSH authentication information is available. This is the default.
any_of: At least one of the patterns must match. If zero patterns are given as module arguments, authentication will fail if SSH authentication information is available.
debug: Log debugging messages to syslog.
disable=service[:service[...]]: Disable pattern matching for the services listed in the colon separator service list.
enable=service[:service[...]]: Enable pattern matching only for the services listed in the colon separator service list.
none_of: None of the patterns may match. If zero patterns are given as module arguments, authentication will succeed if SSH authentication information is available.
quiet: Do not log failure or success messages to syslog.
quiet_fail: Do not log failure messages to syslog.
quiet_success: Do not log success messages to syslog.
recursion_limit=limit: Change the recursion limit. This affects extended patterns and * wildcard patterns.

Patterns

Any character byte that appears in a pattern, other than the extended patterns and the special pattern characters described below, matches itself.

The special pattern characters have the following meanings:

*

Matches any number of (including zero) word character bytes but not a word separator (space).

=

Matches equal-sign (=) or a word separator (space).

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.

?

Matches any word character byte but not a word separator (space).

[

A pair of brackets introduces a character byte class. A character byte class ([...]) matches any word character byte in the class. A complemented character byte class ([!...]) matches any word character byte not in the class. Neither matches a word separator (space). A class may contain character bytes ([abcde]) and character byte ranges ([a-e]).

\

Preserves the literal meaning of the following character byte.

The extended patterns have the following meanings:

?(pattern|pattern|...): Matches zero or one occurence of the given patterns. Does not match a word separator (space).
*(pattern|pattern|...): Matches zero or more occurences of the given patterns. Does not match a word separator (space).
+(pattern|pattern|...): Matches one or more occurences of the given patterns. Does not match a word separator (space).
@(pattern|pattern|...): Matches one of the given patterns. Does not match a word separator (space).
!(pattern|pattern|...): Matches anything except one occurence of the given patterns. Does not match a word separator (space).

SSH authentication information consists of lines having a format like

method[/submethod] [key-type key-data] [info-word]...

SSH authentication information matches a pattern if on any such line all the words or the initial words match the pattern.

Module Services Provided

All module types (account, auth, password and session) are provided. That said, the auth type is still undoubtedly the most useful one.

Return Values

PAM_AUTH_ERR: Pattern requirements are not met. SSH authentication information does not match all of or any of the patterns (see the all_of and the any_of options) or matches some of the patterns (see the none_of option).
PAM_IGNORE: The pattern matching is disabled for the service (see the disable option) or not enabled for the service (see the enable option) or SSH authentication information is missing.
PAM_SUCCESS: Pattern requirements are met. SSH authentication information matches all of or any of the patterns (see the all_of and the any_of options) or matches none of the patterns (see the none_of option).

Examples

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):

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

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):

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

Require that there is at least one previous successfully completed FIDO authenticator algorithm based public key authentication (in which case the key type contains “sk-” and ends with “@openssh.com”). If multiple public key authentications are required, only one of them is required to be a FIDO authenticator algorithm based one.

auth  requisite  pam_ssh_auth_info.so quiet \
                     publickey=*sk-*@openssh.com

Require that there is at least one previous successfully completed FIDO authenticator algorithm based public key authentication (in which case the key type contains “sk-” and ends with “@openssh.com”) and at least one previous successfully completed non-FIDO public key authentication (in which case the key type does not contain “sk-” or does not end with “@openssh.com”).

auth  requisite  pam_ssh_auth_info.so quiet \
                     publickey=*sk-*@openssh.com \
                     publickey=!(*sk-*@openssh.com)

Environment

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.
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 ExposeAuthInfo server option is enabled. This may be a useful source for creating proper patterns.

Notes

In order to make this module useful, the following sshd_config(5) options should be set (either explicitly or via defaults):

AuthenticationMethods

Should contain comma-separated lists of authentication method names with keyboard-interactive, keyboard-interactive:pam or password 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

AuthenticationMethods publickey,keyboard-interactive

for mandatory public key authentication and mandatory PAM authentication using keyboard-interactive challenge-response authentication or

AuthenticationMethods publickey,keyboard-interactive keyboard-interactive

for optional public key authentication and mandatory PAM authentication using keyboard-interactive challenge-response authentication.

ChallengeResponseAuthentication, KbdInteractiveAuthentication, PasswordAuthentication, etc.

The relevant ones should be set to yes.

UsePAM

Should be set to yes.

pam_ssh_auth_info - Man Page

Synopsis

Description

Options

Patterns

Module Services Provided

Return Values

Examples

Environment

Notes

See Also

Author

Copyright

Info