Template Version: @(#)onepager.txt 1.35 07/11/07 SMI Copyright 2008 Sun Microsystems 1. Introduction 1.1. Project/Component Working Name: Authorisation based login control: pam_auths 1.2. Name of Document Author/Supplier: Bart Blanquart, Darren Moffat 1.3. Date of This Document: 2008-12-4 1.3.1. Date this project was conceived: 2008-09 2. Project Summary 2.1. Project Description: pam_auths checks for the authorizations 3. Business Summary 3.1. Problem Area: The module provides a simple way of controlling access using authorizations, thereby offering a nameservice-shareable repository and a unified administrative model for controlling user rights. 3.2. Market/Requester: RBAC users. 4. Technical Description: 4.1. Details: pam_auths.so.1 when called in pam_acct_mgmt will check if the user who is being authenticated has the necessary authorizations. The authorizations the module will check for can be: - default solaris.login authorizations and optionally - specified in the auths= option OR - specified in the login_policy_profile= option OR - specified in policy.conf(4) LOGIN_POLICY_PROFILE= The solaris.login authorizations are checked for if the relevant pam_data items are present. +----------------------------+-----------------------------------+ | Data item | Required authorization | +----------------------------+-----------------------------------+ | PAM_RHOST= | solaris.login.remote | +----------------------------+-----------------------------------+ | PAM_TTY=/dev/console | solaris.login.console | +----------------------------+-----------------------------------+ | PAM_TTY= | solaris.login.local | +----------------------------+-----------------------------------+ If no module options are specified, LOGIN_POLICY_PROFILE is unset and none of the above items are set the module returns PAM_IGNORE. The solaris.login authorizations are granted to all accounts via "Basic Solaris User", so the behaviour of the system remains the same in default configurations. If no options are specified and LOGIN_POLICY_PROFILE is set to point to a policy profile (prof_attr(4)) any of the authorizations in that profile are sufficient for the module to return success, assuming the solaris.login checks succeeded or were unnecessary (both PAM_RHOST and PAM_TTY absent). (While at this point there is nothing fundamentally different between a "rights profile" as assigned to users and a "policy profile" as specified as argument here they are conceptually different: the first assigns all rights and auths it contains, while the latter is used to check for any of the auths -- hence the difference in terminology.) If auths= is specified any of the authorizations listed are sufficient for the module to return success, assuming the solaris.login checks succeeded or were unnecessary. If the login_policy_profile= option is specified any one of the authorizations in the profile is needed for the module to return success, assuming the solaris.login checks succeeded or were unnecessary. If either auths= or login_policy_profile= are specified the policy.conf(4) parameter is ignored: it only functions as a mechanism for providing a generic (fallback) configuration. If both auths= and login_policy_profile= are specified the module returns PAM_SERVICE_ERR. In any of the ways of specifying authorizations or policy profiles to the module it is possible to use tokens that will be substituted at run time. This run-time substitution permits a single configuration option (policy.conf(4)'s LOGIN_POLICY_PROFILE=) to point to per-host or per- domain policy profiles, permitting login authorization policies to be set via the nameservice. The substitutable tokens are: %d is replaced by the DNS domain name. %D is replaced by the reverse order DNS domain, listing the top-level domain first, domain second and so on (e.g. a domain name of "east.sun.com" would become com.sun.east) %h is replaced by the hostname, as returned by gethostname(3C) %f is replaced by the fully qualified host name without the trailing dot (so using %f is equivalent to specifying %h.%d) %F is replaced by the reverse order fully qualified host name, without trailing or leading dot (e.g. host.east.sun.com. would become com.sun.east.host). %k is replaced by the Kerberos Realm name. %K is replaced by the reverse order Kerberos Realm name. %n is replaced by the NIS/NIS+ domain name. %N is replaced by the reverse order NIS/NIS+ domain name. If the domain name contains no dots this is equivalent to %n. The tokens to be substituted consist of "%" followed by a single letter. The "%" sign was not listed as a reserved symbol in auth_attr(4), so as part of this case it would need to be added to that man page. Considering, however, that we permit only "%?" and then only as a component (i.e. bordered on both sides by a dot) this is not expected to cause issues in existing deployments, as the likelihood of existing (third party) authorization names of that form is small. Any authorization (specified in auths=, login_policy_profile=, or LOGIN_POLICY_PROFILE) can also contain the "*" character, which permits the easy (and future-proof) specification of a whole set of authorizations: for example where you would have an auth structure like: com.xyzcompany.systems..admin com.xyzcompany.systems..secadmin com.xyzcompany.systems..auditor com.xyzcompany.systems..user specifying "auths=com.xyzcompany.systems.%h.*" would be sufficient to grant login access to the system. The implementation could be done by calling getauthnam(3SECDB) to iterate over "com.xyzcompany.systems.%h.*" and chkauthattr(3SECDB) against each entry that returns. This does assume that auth_attr(4) lists all authorizations that may have been granted, something that is not currently enforced. Addressing that limitation is beyond the scope of this project. 4.2. Bug/RFE Number(s): 6754641 4.3. In Scope: Documented functionality. 4.4. Out of Scope: A networked policy.conf replacement, that would offer an alternative way of providing per-host policy settings. Negative authorizations, permitting the removal of authorizations from specific accounts (so that the root account could be granted solaris.* while taking away solaris.login.remote and solaris.login.local). Ensuring any authorization used in prof_attr(4) or user_attr(4) is also listed in auth_attr(4). 4.5. Interfaces: +--------------------------------------+---------------+---------+ | Interface | Taxonomy | Comment | +--------------------------------------+---------------+---------+ | TBD | Uncommitted | Package | +--------------------------------------+---------------+---------+ | /usr/lib/security/pam_auths.so.1 | Committed | | +--------------------------------------+---------------+---------+ | /usr/lib/security/pam_auths.so.1 | | | | login_policy_profile= | Committed | Option | | auths= | Committed | Option | | wildcard arguments | Committed | | +--------------------------------------+---------------+---------+ | policy.conf keyword | Committed | Keyword | +--------------------------------------+---------------+---------+ | PAM config snippets | | | | (cf. PSARC/2005/275) | | | | Names | Committed |Unchanged| | Semantics* | Committed |Unchanged| | Contents | Uncommitted |Unchanged| +--------------------------------------+---------------+---------+ * The overall semantics change in that the checks for solaris.login.* authorizations are added, but as those authorizations are granted to all users via the "Basic Solaris User" rights profile the behaviour remains the same. Release Binding: patch 4.6. Doc Impact: pam_auths(5) user_attr(5) (See also) auth_attr(5) (See also, fact auths need to be listed to be considered) prof_attr(5) (Rights profiles vs. policy profiles) policy.conf(5) (LOGIN_POLICY_PROFILE, See also) 4.7. Admin/Config Impact: An extra level of control is offered, building on the existing authorizations infrastructure, but existing configurations will not be affected. 4.8. HA Impact: N/A 4.9. I18N/L10N Impact: None (no direct end-user interaction) 4.10. Packaging & Delivery: The project delivers one additional PAM module and modifies (replaces) some of the shipped PAM snippets. pam.conf need not be modified nor would local PAM snippets be changed. 4.11. Security Impact: It's a PAM module that would get added to the default stacks (snippets). 4.12. Dependencies: As this module would be listed in PAM snippets it relies on PSARC 2005/275 Per-user PAM configuration. If PSARC 2005/275 does not integrate this project would update pam.conf instead. 5. Reference Documents: 6. Resources and Schedule: 6.5. ARC review type: FastTrack 6.6. ARC Exposure: Open Standards, Environments, and Macros pam_auths(5) NAME pam_auths - PAM account management module SYNOPSIS pam_auths.so.1 DESCRIPTION The pam_auths module implements pam_sm_acct_mgmt(3PAM), which provides functionality to the PAM account management stack. The module provides functions to validate that the user has the necessary authorizations to access the system. Users logging in on the console must have the solaris.login.console authorization, while users logging in locally must have been granted the solaris.login.local auth- orization. A user logging in over the network must have the solaris.login.remote authorization. Additional required authorizations can be specified via module options. A user with any of the listed authorizations as well as the appropriate solaris.login authorization will be granted access. If no options are specified the module will read policy.conf(4) and use the value specified in LOGIN_POLICY_PROFILE= as though it was passed as a login_policy_profile= option. The following options may be passed to the module: auths= A comma-separated list of authorizations, each one of which would be sufficient to permit access. login_policy_profile= A policy profile as defined in prof_attr(4), each of the authorizations in which would be sufficient to permit access. debug Provide syslog(3C) debugging information at the LOG_AUTH | LOG_DEBUG level. The argument to auths is a comma-separated list of authorization names chosen from those names defined in the auth_attr(4) database. Wildcards may be specified as well as substitution tokens, described below. Any one authorization listed is sufficient to be granted access. The argument to policy_profile is the name of a single policy profile as defined in prof_attr(4). Any authorization in the profile (or in an included profile) is sufficient to be granted access. In the profile name no wildcards may be specified, though substitution tokens can be used. Authorization names listed in the profile can contain substitution tokens and the wildcard symbol, as though they were specified as an argument to the auths option. The same token substitution will be applied to the name of the policy profile specified in the policy.conf(4) LOGIN_POLICY_PROFILE keyword. If multiple authorizations are required to be granted access to the system the module should be specified multiple times in the appropriate pam stack. See EXAMPLES for an example or pam.conf(4) for more details about stacking PAM modules. To allow a single PAM configuration to be used on multiple systems in a network authorization or profile names can contain tokens that will be substituted when the module is invoked. The following substitutions will be applied: %d is replaced by the DNS domain name. %D is replaced by the reverse order DNS domain, listing the top-level domain first, domain second and so on (e.g. a domain name of "east.sun.com" would become com.sun.east) %h is replaced by the hostname, as returned by gethostname(3C) %f is replaced by the fully qualified host name without the trailing dot (so using %f is equivalent to specifying %h.%d) %F is replaced by the reverse order fully qualified host name, without trailing or leading dot (e.g. host.east.sun.com. would become com.sun.east.host). %k is replaced by the Kerberos Realm name. %K is replaced by the reverse order Kerberos Realm name. %n is replaced by the NIS/NIS+ domain name. %N is replaced by the reverse order NIS/NIS+ domain name. If the domain name contains no dots this is equivalent to %n. Reverse order names are provided to allow organizations that use the recommended naming scheme for authorizations (see auth_attr(4)) or a variation based on one of the other name service schemes. Reversing a name is done by splitting the name in components, where each component is separated by a dot and reversing the order of the components. Only individual components in an authorization name will be substituted, so any of the above tokes can only appear as a prefix (at the beginning of an authorization name, followed by a dot and the remainder of the authorization name), a suffix (at the end of an authorization name, preceded by a dot and followed by either a comma or space), or as an infix component (between two dots). ERRORS The following error values are returned: PAM_SERVICE_ERR An invalid set of module options was given in the pam.conf(4) for this module. PAM_BUF_ERR A memory buffer error occurred. PAM_IGNORE The module is ignored, as it is not par- ticipating in the result. PAM_PERM_DENIED The user lacks the necessary authorization(s) to log in on this host. PAM_SUCCESS The account is valid for use at this time. PAM_USER_UNKNOWN No account is present for the user EXAMPLES Example 1 Using the pam_auths.so.1 Module The following are sample entries from pam.conf(4). These entries demonstrate the use of the pam_authorizes.so.1 module: other account required pam_auths.so.1 This entry, if no LOGIN_POLICY_PROFILE keyword is specified in policy.conf(4), requires anyone logging in to have been granted the solaris.login.console authorization when logging in on the console, the solaris.login.local authorization when logging in on a virtual terminal, a terminal or a Sun Ray. A user logging in remotely would need to have been granted the solaris.login.remote authorization. Example 2 Using a default policy other account required pam_auths.so.1 This entry, with LOGIN_POLICY_PROFILE=com.xyzcompany.servers.login in policy.conf(4), requires anyone logging in to have been granted the solaris.login.console authorization when logging in on the console, the solaris.login.local authorization when logging in on a virtual terminal, a terminal or a Sun Ray. A user logging in remotely would need to have been granted the solaris.login.remote authorization. Any user logging in would need to have been granted the com.xyzcompany.servers.login authorization, in addition to the solaris.login authorization listed above. Example 3 Requiring An Additional Authorization other account required pam_auths.so.1 auths=com.xyzcompany.network.hostname This entry would require a user to have the appropiate solaris.login. authorization, as described in the example above but to also have the com.xyzcompany.network.hostname authorization. Example 4 Using Token Substitution other account required pam_auths.so.1 auths=%D.network.%h This entry would require a user to have the appropriate solaris.login. authorization, as described in Example 1 above, but to also have an additional authorization. The name of the authorization required is determined when it is invoked, so depends on the configuration of the host on which it is installed. On a host with the fully qualified hostname "sample.companyxyz.com" the authorization required would be "com.companyxyz.network.sample". Example 5 Requiring Multiple Authorizations other account required pam_auths.so.1 auths=com.xyzcompany.access.server other account required pam_auths.so.1 auths=com.xyzcompany.access.dmz,com.xyzcompany.access.sensitive other account required pam_auths.so.1 auths=com.xyzcompany.access.dns These entries would require anyone logging in to have been granted three authorizations: com.xyzcompany.access.server, com.xyzcompany.access.dns and either com.xyzcompany.access.dmz or com.xyzcompany.access.sensitive. Example 6 Requiring Specific Authorizations for Console and Remote Logins sshd-pubkey account required pam_auths.so.1 auths=com.xyzcompany.access.server.network sshd-kbdint account required pam_auths.so.1 auths=com.xyzcompany.access.server.network ... login account required pam_auths.so.1 auths=com.xyzcompany.access.server.console These entries would require that a user logging in over the network via Secure Shell (see sshd(1m)) has the com.xyzcompany.access.server.network authorizations. If other mechanisms exist to log in on the system over the network the relevant PAM stacks would need to be similarly configured. The second part of this example specifies that a user would need to have been granted the authorization com.xyzcompany.access.server.console in order to be able to log in on the console of the system. In both instances the user would also need the solaris.login authorizations, as described in Example 1, above. Example 7 Specifying a host-specific policy using LOGIN_POLICY_PROFILE and substitution tokens Using the default PAM configuration but specifying LOGIN_POLICY_PROFILE=%F.login would require any user logging in from having a host-specific authorization, of the form com.xyzcompany.hostname.login as well as the solaris.login authorizations. ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Interface Stability | Committed | |_____________________________|_____________________________| | MT-Level | MT-Safe with exceptions | |_____________________________|_____________________________| The interfaces in libpam(3LIB) are MT-Safe only if each thread within the multithreaded application uses its own PAM handle. SEE ALSO pam(3PAM), pam_authenticate(3PAM), pam_sm_acct_mgmt(3PAM), syslog(3C), libpam(3LIB), nsswitch.conf(4), pam.conf(4), attributes(5), policy.conf(4), auth_attr(4), prof_attr(4), user_attr(4)