Start documenting PAM support

diff --git a/contrib/slapd-modules/nssov/README b/contrib/slapd-modules/nssov/README
index e51c90d4b35671329ec15ad96407d11f900dbe8d..82c60493c41cbe5e78216d794ac95c61f84e9f5c 100644 (file)
--- a/contrib/slapd-modules/nssov/README
+++ b/contrib/slapd-modules/nssov/README
@@ -1,4 +1,4 @@
-Copyright 2008 Howard Chu, Symas Corp. All rights reserved.
+Copyright 2008-2009 Howard Chu, Symas Corp. All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted only as authorized by the OpenLDAP
@@ -11,7 +11,8 @@ top-level directory of the distribution or, alternatively, at
 This directory contains a slapd overlay, nssov, that handles
 NSS lookup requests through a local Unix Domain socket. It uses the
 same IPC protocol as Arthur de Jong's nss-ldapd, and a complete
-copy of the nss-ldapd source is included here.
+copy of the nss-ldapd source is included here. It also handles
+PAM requests.
 
 To use this code, you will need the client-side stub library from
 nss-ldapd (which resides in nss-ldapd/nss). You will not need the
@@ -38,7 +39,7 @@ use RFC2307bis.)
 The overlay may be configured with Service Search Descriptors (SSDs)
 for each NSS service that will be used. SSDs are configured using
 
-       nssov-svc <service> <url>
+       nssov-ssd <service> <url>
 
 where the <service> may be one of
        alias
@@ -80,3 +81,46 @@ of the config entry is
 
 which enables the passwd service, and uses the accountName attribute to
 fetch what is usually retrieved from the uid attribute.
+
+PAM authentication, account management, session management, and password
+management are supported.
+
+Authentication is performed using Simple Binds. Since all operations occur
+inside the slapd overlay, "fake" connections are used and they are
+inherently secure. Two methods of mapping the PAM username to an LDAP DN
+are provided:
+  the mapping can be accomplished using slapd's authz-regexp facility. In
+this case, a DN of the form
+       cn=<service>+uid=<user>,cn=<hostname>,cn=pam,cn=auth
+is fed into the regexp matcher. If a match is produced, the resulting DN
+is used.
+  otherwise, the NSS passwd map is invoked (which means it must already
+be configured).
+
+If no DN is found, the overlay returns PAM_USER_UNKNOWN. If the DN is
+found, and Password Policy is supported, then the Bind will use the
+Password Policy control and return expiration information to PAM.
+
+Account management also uses two methods. These methods depend on the
+ldapns.schema included with the nssov source.
+  The first is identical to the method used in PADL's pam_ldap module:
+host and authorizedService attributes may be looked up in the user's entry,
+and checked to determine access. Also a check may be performed to see if
+the user is a member of a particular group. This method is pretty
+inflexible and doesn't scale well to large networks of users, hosts,
+and services.
+  The second uses slapd's ACL engine to check if the user has "auth"
+privilege on an ipHost object whose name matches the current hostname, and
+whose authorizedService attribute matches the current service name. This
+method is preferred, since it allows authorization to be centralized in
+the ipHost entries instead of scattered across the entire user population.
+The ipHost entries must have an authorizedService attribute (e.g. by way
+of the authorizedServiceObject auxiliary class) to use this method.
+
+Session management: the overlay may optionally add a "logged in" attribute
+to a user's entry for successful logins, and delete the corresponding
+value upon logout. The attribute value is of the form
+       <service> <host> <generalizedTime>
+
+Password management: the overlay will perform a PasswordModify exop
+in the server for the given user.