lib/libpam/libpam/pam_set_item.3

   1 .\"-
   2 .\" Copyright (c) 2001 Networks Associates Technologies, Inc.
   3 .\" All rights reserved.
   4 .\"
   5 .\" This software was developed for the FreeBSD Project by ThinkSec AS and
   6 .\" NAI Labs, the Security Research Division of Network Associates, Inc.
   7 .\" under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the
   8 .\" DARPA CHATS research program.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. The name of the author may not be used to endorse or promote products
  19 .\"    derived from this software without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\" $FreeBSD: src/lib/libpam/libpam/pam_set_item.3,v 1.2.2.2 2002/01/09 14:35:51 ru Exp $
  34 .\"
  35 .Dd November 27, 2001
  36 .Dt PAM_SET_ITEM 3
  37 .Os
  38 .Sh NAME
  39 .Nm pam_set_item ,
  40 .Nm pam_get_item
  41 .Nd setting authentication parameters
  42 .Sh LIBRARY
  43 .Lb libpam
  44 .Sh SYNOPSIS
  45 .In security/pam_modules.h
  46 .Ft int
  47 .Fn pam_set_item "pam_handle_t *pamh" "int type" "const void *item"
  48 .Ft int
  49 .Fn pam_get_item "const pam_handle_t *pamh" "int type" "const void **item"
  50 .Sh DESCRIPTION
  51 The
  52 .Fn pam_set_item
  53 and
  54 .Fn pam_get_item
  55 allow applications and modules to store and retrieve a variety of
  56 authentication parameters, or
  57 .Dq items .
  58 Each item is identified by an integer constant.
  59 The following items are defined:
  60 .Bl -tag -width ".Dv PAM_USER_PROMPT"
  61 .It Dv PAM_SERVICE
  62 (string)
  63 The name of the requesting service.
  64 .It Dv PAM_USER
  65 (string)
  66 The name of the user the application wants to authenticate.
  67 .It Dv PAM_USER_PROMPT
  68 (string)
  69 The string which will be used to prompt the user for an authentication
  70 token.
  71 .It Dv PAM_TTY
  72 (string)
  73 The name of the current terminal (for terminal-oriented applications)
  74 or display (for X11 applications).
  75 .It Dv PAM_RUSER
  76 (string)
  77 The name of the requesting user.
  78 .It Dv PAM_RHOST
  79 (string)
  80 The name of the host the requesting user is logging in from.
  81 .It Dv PAM_AUTHTOK
  82 (opaque)
  83 The current authentication token.
  84 This item is only accessible from PAM modules.
  85 .It Dv PAM_OLDAUTHTOK
  86 (opaque)
  87 The expired authentication token.
  88 This item is only accessible from PAM modules.
  89 .It Dv PAM_CONV
  90 .Pq Vt "struct pam_conv"
  91 The current conversation function.
  92 The
  93 .Vt pam_conv
  94 structure is defined as follows:
  95 .Bd -literal
  96 struct pam_conv {
  97     int (*conv)(int num_msg,
  98         const struct pam_message **msg,
  99         struct pam_response **resp,
 100         void *appdata_ptr);
 101     void *appdata_ptr;
 102 };
 103 .Ed
 104 .It Dv PAM_FAIL_DELAY
 105 .Pq Vt delay_fn
 106 A pointer to a callback function that should be called when a module
 107 wants to introduce a delay after a failed authentication to discourage
 108 brute-force attacks.
 109 .El
 110 .Sh RETURN VALUES
 111 The
 112 .Fn pam_set_item
 113 and
 114 .Fn pam_get_item
 115 functions return one of the following values:
 116 .Bl -tag -width ".Dv PAM_SYSTEM_ERR"
 117 .It Dv PAM_SUCCESS
 118 The operation succeeded.
 119 .It Dv PAM_SYSTEM_ERR
 120 The
 121 .Fa pamh
 122 argument was invalid.
 123 .It Dv PAM_BUF_ERR
 124 A call to
 125 .Xr malloc 3
 126 failed, or the
 127 .Fa item
 128 argument to
 129 .Fn pam_get_item
 130 was
 131 .Dv NULL .
 132 .It Dv PAM_BAD_ITEM
 133 The specified
 134 .Fa item
 135 does not exist or is not accessible to the caller.
 136 .El
 137 .Pp
 138 The
 139 .Xr pam_strerror 3
 140 function can be used to translate these return codes to descriptive
 141 messages.
 142 .Sh SEE ALSO
 143 .Xr pam_start 3 ,
 144 .Xr pam_strerror 3 ,
 145 .Xr pam 8
 146 .Sh STANDARDS
 147 .Rs
 148 .%T "DCE-RFC 86.0"
 149 .%D "October 1995"
 150 .Re
 151 .Pp
 152 Note: the
 153 .Dv PAM_USER_PROMPT
 154 and
 155 .Dv PAM_FAIL_DELAY
 156 items are non-standard extensions.