From af973ad47adf81e4edb9a92ab540c0613d156fbd Mon Sep 17 00:00:00 2001 From: "Andrew G. Morgan" Date: Fri, 10 May 2002 06:00:12 +0000 Subject: Relevant BUGIDs: 527965 Purpose of commit: documentation Commit summary: --------------- module developers guide changes wrt the conversation function from Jenn Vesperman. --- CHANGELOG | 7 ++++--- doc/pam_modules.sgml | 59 +++++++++++++++++++++++++++++----------------------- 2 files changed, 37 insertions(+), 29 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index 394d106b..0a006520 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -55,9 +55,10 @@ bug report - outstanding bugs are listed here: 0.76: please submit patches for this section with actual code/doc patches! -* documentation: suggestions regarding PAM environment variables from - Jenn Vesperman, plus some updatens to the libpam_misc description - (Bug 527821 - agmorgan) +* documentation: (a few of mine in passing) and app documentation + suggestions regarding PAM environment variables and module + documentation changes regarding the conversation function from Jenn + Vesperman (Bug 527821, 527965 - agmorgan) * documentation: pam_time.sgml typo fixed, pam_motd exists now, correct Red Hat comment about config files (Bugs 554274, 554261, 554182 - agmorgan) diff --git a/doc/pam_modules.sgml b/doc/pam_modules.sgml index babccb06..c986e0a9 100644 --- a/doc/pam_modules.sgml +++ b/doc/pam_modules.sgml @@ -49,7 +49,7 @@ DAMAGE. The Linux-PAM Module Writers' Guide <author>Andrew G. Morgan, <tt>morgan@kernel.org</tt> -<date>DRAFT v0.76 2001/12/08 +<date>DRAFT v0.76 2002/05/09 <abstract> This manual documents what a programmer needs to know in order to write a module that conforms to the <bf/Linux-PAM/ standard. It also @@ -293,34 +293,38 @@ structure. Should a module require that a change is made to the this <p> Following the call <tt>pam_get_item(pamh,PAM_CONV,&item)</tt>, the -pointer <tt/item/ points to a <em/conversation/-function that provides -limited but direct access to the application. The purpose of this -function is to allow the module to prompt the user for their password -and pass other information in a manner consistent with the -application. For example, an X-windows based program might pop up a -dialog box to report a login failure. Just as the application should -not be concerned with the method of authentication, so the module -should not dictate the manner in which input (output) is -obtained from (presented to) to the user. - -<p> -The reader is strongly urged to read the more complete description of +pointer <tt/item/ points to a structure containing an a pointer to a +<em/conversation/-function that provides limited but direct access to +the application. The purpose of this function is to allow the module +to prompt the user for their password and pass other information in a +manner consistent with the application. For example, an X-windows +based program might pop up a dialog box to report a login +failure. Just as the application should not be concerned with the +method of authentication, so the module should not dictate the manner +in which input (output) is obtained from (presented to) to the user. + +<p> +<bf>The reader is strongly urged to read the more complete description of the <tt/pam_conv/ structure, written from the perspective of the application developer, in the <bf/Linux-PAM/ Application Developers' -Guide. +Guide.</bf> + +<p> +The return values for this function are listed in the +<bf>Linux-PAM</bf> Application Developers' Guide. <p> The <tt/pam_response/ structure returned after a call to the <tt/pam_conv/ function must be <tt/free()/'d by the module. Since the call to the conversation function originates from the module, it is -clear that either this <tt/pam_response/ structure could be either -statically or dynamically (using <tt/malloc()/ etc.) allocated within -the application. Repeated calls to the conversation function would -likely overwrite static memory, so it is required that for a -successful return from the conversation function the memory for the -response structure is dynamically allocated by the application with -one of the <tt/malloc()/ family of commands and <em/must/ be -<tt/free()/'d by the module. +clear that this <tt/pam_response/ structure could be either statically +or dynamically (using <tt/malloc()/ etc.) allocated within the +application. Repeated calls to the conversation function would likely +overwrite static memory, so it is required that for a successful +return from the conversation function the memory for the response +structure is dynamically allocated by the application with one of the +<tt/malloc()/ family of commands and <em/must/ be <tt/free()/'d by the +module. <p> If the <tt/pam_conv/ mechanism is used to enter authentication tokens, @@ -330,9 +334,12 @@ has been stored (by one of these methods or another one), the memory returned by the application should be overwritten with <tt/0/'s, and then <tt/free()/'d. -<p> -The return values for this function are listed in the -<bf>Linux-PAM</bf> Application Developers' Guide. +There is a handy macro <tt/_pam_drop_reply()/ to be found in +<tt><security/_pam_macros.h></tt> that can be used to +conveniently cleanup a <tt/pam_response/ structure. (Note, this +include file is specific to the Linux-PAM sources, and whilst it will +work with Sun derived PAM implementations, it is not generally +distributed by Sun.) <sect2>Getting the name of a user<label id="pam-get-user"> @@ -1443,7 +1450,7 @@ credited for all the good work they have done. <sect>Copyright information for this document <p> -Copyright (c) Andrew G. Morgan 1996-9,2000-1. All rights reserved. +Copyright (c) Andrew G. Morgan 1996-2002. All rights reserved. <newline> Email: <tt><morgan@kernel.org></tt> -- cgit v1.2.3