<sect2>Setting PAM environment variables
<label id="pam-putenv-section">
+<p>
+The <tt/libpam/ library associates with each PAM-handle (<tt/pamh/), a
+set of <it/PAM environment variables/. These variables are intended to
+hold the session environment variables that the user will inherit when
+the session is granted and the authenticated user obtains access to
+the requested service. For example, when <tt/login/ has finally given
+the user a shell, the environment (as viewed with the command
+<tt/env/) will be what <tt/libpam/ was maintaining as the PAM
+environment for that service application. Note, these variables are not
+the environment variables of the <tt/login/ application. This is
+principally for two reasons: <tt/login/ may want to have an
+environment that cannot be seen or manipulated by a user; and
+<tt/login/ (or whatever the serving application is) may be maintaining
+a number of parallel sessions, via different <tt/pamh/ values, at the
+same time and a single environment may not be appropriately shared
+between each of these. The PAM environment may contain variables
+seeded by the applicant user's client program, for example, and as
+such it is not appropriate for one applicant to interfere with the
+environment of another applicant.
+
<p>
<tscreen>
<verb>
</verb>
</tscreen>
-<p>
-<em>
-Warning, the environment support in <bf/Linux-PAM/ is based solely
-on a six-line email from the developers at Sun. Its interface is
-likely to be generally correct, however, the details are likely to be
-changed as more information becomes available.
-</em>
-
<p>
Obtain the value of the indicated <bf/Linux-PAM/ environment
variable. On error, internal failure or the unavailability of the
</tscreen>
<p>
-<em>
-Warning, the environment support in <bf/Linux-PAM/ is based solely
-on a six line email from the developers at Sun. Its interface is
-likely to be generally correct, however, the details are likely to be
-changed as more information becomes available.
-</em>
+The PAM environment variables (see section <ref
+id="pam-putenv-section" name="above">) are a complete set of enviroment
+variables that are associated with a PAM-handle (<tt/pamh/). They
+represent the contents of the <it/regular/ environment variables of
+the authenticated user when service is granted.
<p>
-This function returns a pointer to the complete <tt/Linux-PAM/
-environment. It is a pointer to a <em/read-only/ list of
-<em/read-only/ environment variables. It should be noted that this
-memory will become invalid after a call to <tt/pam_end()/ (see the
-section <ref id="pam-end-section" name="above">). If application
-wishes to make use of this list after such a call, it should first
-make a copy of all the set variables. (A function that performs such a
-transcription is to be found in <tt/libpam_misc/.)
+Th function, <tt>pam_getenvlist()</tt> returns a pointer to a complete,
+<tt/malloc()/'d, copy of the PAM environment. It is a pointer to a
+duplicated list of environment variables. It should be noted that
+this memory will never be <tt/free()'d/ by <tt/libpam/. Once obtained
+by a call to <tt/pam_getenvlist()/, <bf>it is the responsibility of
+the calling application</bf> to <tt/free()/ this memory.
+
+<p>
+The format of the memory is a <tt/malloc()/'d array of <tt/char */
+pointers, the last element of which is set to <tt/NULL/. Each of the
+non-<tt/NULL/ entries in this array point to a <tt/NUL/ terminated and
+<tt/malloc()/'d <tt/char/ string of the form:
+<tt/"/<it/name/<tt/=/<it/value/<tt/"/.
+
+<p>
+It is by design, and not a coincidence, that the format and contents
+of the returned array matches that required for the third argument of
+the <tt/execle(3)/ function call.
<sect1>What is expected of an application
not referred to in the defining DCE-RFC (see <ref id="bibliography"
name="the bibliography">) below.
-<sect1>Functions supplied
+<sect1>Macros supplied
-<sect2>Safe string duplication
+<sect2>Safe duplication of strings
<p>
<tscreen>
<verb>
-extern char *xstrdup(const char *s)
+x_strdup(const char *s)
</verb>
</tscreen>
-Return a duplicate copy of the <tt/NUL/ terminated string,
-<tt/s/. <tt/NULL/ is returned if there is insufficient memory
-available for the duplicate or if <tt/s=NULL/.
+
+<p>
+This macro is a replacement for the <tt/xstrdup()/ function that was
+present in earlier versions of the library and which clashed horribly
+with a number of applications. It returns a duplicate copy of the
+<tt/NUL/ terminated string, <tt/s/. <tt/NULL/ is returned if there is
+insufficient memory available for the duplicate or if <tt/s/ is
+<tt/NULL/ to begin with.
+
+<sect1>Functions supplied
<sect2>A text based conversation function
variable indicates whether the conversation has timed out. A value of
<tt/1/ indicates the time-out occurred.
-<tag><tt>extern int (*pam_binary_handler_fn)(const union pam_u_packet_p send,
- union pam_u_packet_p *receive);</tt></tag>
+</descrip>
+
+<p>
+The following two function pointers are available for supporting binary
+prompts in the conversation function. They are optimized for the
+current incarnation of the <tt/libpamc/ library and are subject to
+change.
+<descrip>
+<tag><tt>extern int (*pam_binary_handler_fn)(void *appdata, pamc_bp_t
+*prompt_p);</tt></tag>
This function pointer is initialized to <tt/NULL/ but can be filled
with a function that provides machine-machine (hidden) message
such as RSA or Diffie-Hellman key exchanges. (This is still under
development.)
+<tag><tt>extern int (*pam_binary_handler_free)(void *appdata,
+pamc_bp_t *delete_me);</tt></tag>
+
+This function pointer is initialized to <tt/PAM_BP_RENEW(delete_me, 0,
+0)/, but can be redefined as desired by the application.
+
</descrip>
<sect2>Transcribing an environment to that of Linux-PAM
<em/uploads/ its contents to the <bf/Linux-PAM/ environment. Success
is indicated by <tt/PAM_SUCCESS/.
-<sect2>Saving the Linux-PAM environment for later use
-<p>
-<tscreen>
-<verb>
-extern char **pam_misc_copy_env(pam_handle_t *pamh);
-</verb>
-</tscreen>
-
-This function returns a pointer to a list of environment variables
-that are a direct copy of the <bf/Linux-PAM/ environment. The memory
-associated with these variables are the responsibility of the
-application and should be liberated with a call to
-<tt/pam_misc_drop_env()/.
-
<sect2>Liberating a locally saved environment
<p>
<tscreen>
</verb>
</tscreen>
-This function is defined to complement the <tt/pam_misc_copy_env()/
+This function is defined to complement the <tt/pam_getenvlist()/
function. It liberates the memory associated with <tt/env/,
<em/overwriting/ with <tt/0/ all memory before <tt/free()/ing it.
projects / linux-pam / commitdiff