pam_ssh_auth_info

NAME

pam_ssh_auth_info - test SSH authentication information

SYNOPSIS

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

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

AUTHOR

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

COPYRIGHT

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.

pam-ssh-auth-info

PAM authentication based on SSH authentication information