More checks & documentation, and fix some markup nits.

Sponsored by:	DARPA, NAI Labs


git-svn-id: svn+ssh://svn.openpam.org/svn/openpam/trunk@115 185d5e19-27fe-0310-9dcf-9bff6b9f3609

lib/pam_acct_mgmt.c

@@ -31,7 +31,7 @@
  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  * SUCH DAMAGE.
  *
- * $P4: //depot/projects/openpam/lib/pam_acct_mgmt.c#7 $
+ * $P4: //depot/projects/openpam/lib/pam_acct_mgmt.c#8 $
  */
 
 #include <sys/param.h>
@@ -62,3 +62,19 @@ pam_acct_mgmt(pam_handle_t *pamh,
  *	=pam_sm_acct_mgmt
  *	!PAM_IGNORE
  */
+
+/**
+ * The =pam_acct_mgmt function verifies and enforces account restrictions
+ * after the user has been authenticated.
+ *
+ * The =flags argument is the binary or of zero or more of the following
+ * values:
+ *
+ *	=PAM_SILENT:
+ *		Do not emit any messages.
+ *	=PAM_DISALLOW_NULL_AUTHTOK:
+ *		Fail if the user's authentication token is null.
+ *
+ * If any other bits are set, =pam_authenticate will return
+ * =PAM_SYMBOL_ERR.
+ */

lib/pam_authenticate.c

@@ -31,7 +31,7 @@
  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  * SUCH DAMAGE.
  *
- * $P4: //depot/projects/openpam/lib/pam_authenticate.c#9 $
+ * $P4: //depot/projects/openpam/lib/pam_authenticate.c#10 $
  */
 
 #include <sys/param.h>
@@ -66,6 +66,7 @@ pam_authenticate(pam_handle_t *pamh,
  *	=openpam_dispatch
  *	=pam_sm_authenticate
  *	!PAM_IGNORE
+ *	PAM_SYMBOL_ERR
  */
 
 /**
@@ -79,8 +80,11 @@ pam_authenticate(pam_handle_t *pamh,
  * The =flags argument is the binary or of zero or more of the following
  * values:
  *
- *	=PAM_SILENT
+ *	=PAM_SILENT:
  *		Do not emit any messages.
- *	=PAM_DISALLOW_NULL_AUTHTOK
+ *	=PAM_DISALLOW_NULL_AUTHTOK:
  *		Fail if the user's authentication token is null.
+ *
+ * If any other bits are set, =pam_authenticate will return
+ * =PAM_SYMBOL_ERR.
  */

lib/pam_chauthtok.c

@@ -31,7 +31,7 @@
  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  * SUCH DAMAGE.
  *
- * $P4: //depot/projects/openpam/lib/pam_chauthtok.c#10 $
+ * $P4: //depot/projects/openpam/lib/pam_chauthtok.c#11 $
  */
 
 #include <sys/param.h>
@@ -82,8 +82,10 @@ pam_chauthtok(pam_handle_t *pamh,
  * The =flags argument is the binary or of zero or more of the following
  * values:
  *
- *	=PAM_SILENT
+ *	=PAM_SILENT:
  *		Do not emit any messages.
- *	=PAM_CHANGE_EXPIRED_AUTHTOK
+ *	=PAM_CHANGE_EXPIRED_AUTHTOK:
  *		Change only those authentication tokens that have expired.
+ *
+ * If any other bits are set, =pam_chauthtok will return =PAM_SYMBOL_ERR.
  */

lib/pam_close_session.c

@@ -31,7 +31,7 @@
  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  * SUCH DAMAGE.
  *
- * $P4: //depot/projects/openpam/lib/pam_close_session.c#7 $
+ * $P4: //depot/projects/openpam/lib/pam_close_session.c#8 $
  */
 
 #include <sys/param.h>
@@ -52,6 +52,8 @@ pam_close_session(pam_handle_t *pamh,
 	int flags)
 {
 
+	if (flags & ~(PAM_SILENT))
+		return (PAM_SYMBOL_ERR);
 	return (openpam_dispatch(pamh, PAM_SM_CLOSE_SESSION, flags));
 }
 
@@ -61,4 +63,19 @@ pam_close_session(pam_handle_t *pamh,
  *	=openpam_dispatch
  *	=pam_sm_close_session
  *	!PAM_IGNORE
+ *	PAM_SYMBOL_ERR
+ */
+
+/**
+ * The =pam_close_session function tears down the user session previously
+ * set up by =pam_open_session.
+ *
+ * The =flags argument is the binary or of zero or more of the following
+ * values:
+ *
+ *	=PAM_SILENT:
+ *		Do not emit any messages.
+ *
+ * If any other bits are set, =pam_close_session will return
+ * =PAM_SYMBOL_ERR.
  */

lib/pam_open_session.c

@@ -31,7 +31,7 @@
  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  * SUCH DAMAGE.
  *
- * $P4: //depot/projects/openpam/lib/pam_open_session.c#7 $
+ * $P4: //depot/projects/openpam/lib/pam_open_session.c#8 $
  */
 
 #include <sys/param.h>
@@ -52,6 +52,8 @@ pam_open_session(pam_handle_t *pamh,
 	int flags)
 {
 
+	if (flags & ~(PAM_SILENT))
+		return (PAM_SYMBOL_ERR);
 	return (openpam_dispatch(pamh, PAM_SM_OPEN_SESSION, flags));
 }
 
@@ -61,4 +63,20 @@ pam_open_session(pam_handle_t *pamh,
  *	=openpam_dispatch
  *	=pam_sm_open_session
  *	!PAM_IGNORE
+ *	PAM_SYMBOL_ERR
+ */
+
+/**
+ * The =pam_open_session sets up a user session for a previously
+ * authenticated user.  The session should later be torn down by a call to
+ * =pam_close_session.
+ *
+ * The =flags argument is the binary or of zero or more of the following
+ * values:
+ *
+ *	=PAM_SILENT:
+ *		Do not emit any messages.
+ *
+ * If any other bits are set, =pam_open_session will return
+ * =PAM_SYMBOL_ERR.
  */

lib/pam_setcred.c

@@ -31,7 +31,7 @@
  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  * SUCH DAMAGE.
  *
- * $P4: //depot/projects/openpam/lib/pam_setcred.c#8 $
+ * $P4: //depot/projects/openpam/lib/pam_setcred.c#9 $
  */
 
 #include <sys/param.h>
@@ -52,6 +52,10 @@ pam_setcred(pam_handle_t *pamh,
 	int flags)
 {
 
+	if (flags & ~(PAM_SILENT|PAM_ESTABLISH_CRED|PAM_DELETE_CRED|
+		PAM_REINITIALIZE_CRED|PAM_REFRESH_CRED))
+		return (PAM_SYMBOL_ERR);
+	/* XXX enforce exclusivity */
 	return (openpam_dispatch(pamh, PAM_SM_SETCRED, flags));
 }
 
@@ -61,18 +65,27 @@ pam_setcred(pam_handle_t *pamh,
  *	=openpam_dispatch
  *	=pam_sm_setcred
  *	!PAM_IGNORE
+ *	PAM_SYMBOL_ERR
  */
 
 /**
  * The =pam_setcred function manages the application's credentials.
- * The operation to perform is specified by the =flags argument:
  *
- *	PAM_ESTABLISH_CRED:
+ * The =flags argument is the binary or of zero or more of the following
+ * values:
+ *
+ *	=PAM_SILENT:
+ *		Do not emit any messages.
+ *	=PAM_ESTABLISH_CRED:
  *		Establish the credentials of the target user.
- *	PAM_DELETE_CRED:
+ *	=PAM_DELETE_CRED:
  *		Revoke all established credentials.
- *	PAM_REINITIALIZE_CRED:
+ *	=PAM_REINITIALIZE_CRED:
  *		Fully reinitialise credentials.
- *	PAM_REFRESH_CRED:
+ *	=PAM_REFRESH_CRED:
  *		Refresh credentials.
+ *
+ * The latter four are mutually exclusive.
+ *
+ * If any other bits are set, =pam_setcred will return =PAM_SYMBOL_ERR.
  */