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 .\" $DragonFly: src/lib/libpam/libpam/Attic/pam_set_item.3,v 1.2 2003/06/17 04:26:50 dillon Exp $
  35 .\"
  36 .Dd November 27, 2001
  37 .Dt PAM_SET_ITEM 3
  38 .Os
  39 .Sh NAME
  40 .Nm pam_set_item ,
  41 .Nm pam_get_item
  42 .Nd setting authentication parameters
  43 .Sh LIBRARY
  44 .Lb libpam
  45 .Sh SYNOPSIS
  46 .In security/pam_modules.h
  47 .Ft int
  48 .Fn pam_set_item "pam_handle_t *pamh" "int type" "const void *item"
  49 .Ft int
  50 .Fn pam_get_item "const pam_handle_t *pamh" "int type" "const void **item"
  51 .Sh DESCRIPTION
  52 The
  53 .Fn pam_set_item
  54 and
  55 .Fn pam_get_item
  56 allow applications and modules to store and retrieve a variety of
  57 authentication parameters, or
  58 .Dq items .
  59 Each item is identified by an integer constant.
  60 The following items are defined:
  61 .Bl -tag -width ".Dv PAM_USER_PROMPT"
  62 .It Dv PAM_SERVICE
  63 (string)
  64 The name of the requesting service.
  65 .It Dv PAM_USER
  66 (string)
  67 The name of the user the application wants to authenticate.
  68 .It Dv PAM_USER_PROMPT
  69 (string)
  70 The string which will be used to prompt the user for an authentication
  71 token.
  72 .It Dv PAM_TTY
  73 (string)
  74 The name of the current terminal (for terminal-oriented applications)
  75 or display (for X11 applications).
  76 .It Dv PAM_RUSER
  77 (string)
  78 The name of the requesting user.
  79 .It Dv PAM_RHOST
  80 (string)
  81 The name of the host the requesting user is logging in from.
  82 .It Dv PAM_AUTHTOK
  83 (opaque)
  84 The current authentication token.
  85 This item is only accessible from PAM modules.
  86 .It Dv PAM_OLDAUTHTOK
  87 (opaque)
  88 The expired authentication token.
  89 This item is only accessible from PAM modules.
  90 .It Dv PAM_CONV
  91 .Pq Vt "struct pam_conv"
  92 The current conversation function.
  93 The
  94 .Vt pam_conv
  95 structure is defined as follows:
  96 .Bd -literal
  97 struct pam_conv {
  98     int (*conv)(int num_msg,
  99         const struct pam_message **msg,
 100         struct pam_response **resp,
 101         void *appdata_ptr);
 102     void *appdata_ptr;
 103 };
 104 .Ed
 105 .It Dv PAM_FAIL_DELAY
 106 .Pq Vt delay_fn
 107 A pointer to a callback function that should be called when a module
 108 wants to introduce a delay after a failed authentication to discourage
 109 brute-force attacks.
 110 .El
 111 .Sh RETURN VALUES
 112 The
 113 .Fn pam_set_item
 114 and
 115 .Fn pam_get_item
 116 functions return one of the following values:
 117 .Bl -tag -width ".Dv PAM_SYSTEM_ERR"
 118 .It Dv PAM_SUCCESS
 119 The operation succeeded.
 120 .It Dv PAM_SYSTEM_ERR
 121 The
 122 .Fa pamh
 123 argument was invalid.
 124 .It Dv PAM_BUF_ERR
 125 A call to
 126 .Xr malloc 3
 127 failed, or the
 128 .Fa item
 129 argument to
 130 .Fn pam_get_item
 131 was
 132 .Dv NULL .
 133 .It Dv PAM_BAD_ITEM
 134 The specified
 135 .Fa item
 136 does not exist or is not accessible to the caller.
 137 .El
 138 .Pp
 139 The
 140 .Xr pam_strerror 3
 141 function can be used to translate these return codes to descriptive
 142 messages.
 143 .Sh SEE ALSO
 144 .Xr pam_start 3 ,
 145 .Xr pam_strerror 3 ,
 146 .Xr pam 8
 147 .Sh STANDARDS
 148 .Rs
 149 .%T "DCE-RFC 86.0"
 150 .%D "October 1995"
 151 .Re
 152 .Pp
 153 Note: the
 154 .Dv PAM_USER_PROMPT
 155 and
 156 .Dv PAM_FAIL_DELAY
 157 items are non-standard extensions.