Add documentation.

Sponsored by:	DARPA, NAI Labs


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

lib/openpam_nullconv.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/openpam_nullconv.c#1 $
+ * $P4: //depot/projects/openpam/lib/openpam_nullconv.c#2 $
  */
 
 #include <sys/types.h>
@@ -66,3 +66,19 @@ openpam_nullconv(int n,
  *
  *	PAM_CONV_ERR
  */
+
+/**
+ * The =openpam_nullconv function is a null conversation function suitable
+ * for applications that want to use PAM but don't support interactive
+ * dialog with the user.  Such applications should set =PAM_AUTHTOK to
+ * whatever authentication token they've obtained on their own before
+ * calling =pam_authenticate and / or =pam_chauthtok, and their PAM
+ * configuration should specify the ;use_first_pass option for all modules
+ * that require access to the authentication token, to make sure they use
+ * =PAM_AUTHTOK rather than try to query the user.
+ *
+ * >openpam_ttyconv
+ * >pam_prompt
+ * >pam_set_item
+ * >pam_vprompt
+ */

lib/openpam_ttyconv.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/openpam_ttyconv.c#10 $
+ * $P4: //depot/projects/openpam/lib/openpam_ttyconv.c#11 $
  */
 
 #include <sys/types.h>
@@ -192,3 +192,17 @@ openpam_ttyconv(int n,
  *	PAM_BUF_ERR
  *	PAM_CONV_ERR
  */
+
+/**
+ * The =openpam_ttyconv function is a standard conversation function
+ * suitable for use on TTY devices.  It should be adequate for the needs
+ * of most text-based interactive programs.
+ *
+ * The =openpam_ttyconv function allows the application to specify a
+ * timeout for user input by setting the global variable
+ * :openpam_ttyconv_timeout to the length of the timeout in seconds.
+ *
+ * >openpam_nullconv
+ * >pam_prompt
+ * >pam_vprompt
+ */