3.1. 应用程序可以期望什么

3.1.1. PAMTransaction 的初始化

#include <security/pam_appl.h> 
   int pam_start( 
   service_name,  
   user,  
   pam_conversation,  
   pamh); 
 const char *service_name; 
 const char *user; 
 const struct pam_conv *pam_conversation; 
 pam_handle_t **pamh; 
   int pam_start_confdir( 
   service_name,  
   user,  
   pam_conversation,  
   confdir,  
   pamh); 
 const char *service_name; 
 const char *user; 
 const struct pam_conv *pam_conversation; 
 const char *confdir; 
 pam_handle_t **pamh;

3.1.1.1. DESCRIPTION

pam_start函数创建 PAM 上下文并启动 PAM 事务。它是应用程序需要调用的第一个 PAM 函数。事务状态完全包含在此句柄标识的结构内，因此可以并行处理多个事务。但是不可能对不同的事务使用相同的句柄，每个新的上下文都需要一个新的句柄。

成功返回(PAM_SUCCESS)之后，* pamh 的内容是一个句柄，其中包含用于后续调用 PAM 函数的 PAM 上下文。在错误的情况下， pamh *的内容未定义。

pam_start_confdir函数的行为类似于pam_start函数，但是它还允许设置* confdir 参数和目录路径，以覆盖服务策略文件的默认(/etc/pam.d)路径。如果 confdir *为 NULL，则该函数的工作方式与pam_start完全相同。

3.1.1.2. 返回值

3.1.2. 终止 PAMTransaction

#include <security/pam_appl.h> 
   int pam_end( 
   pamh,  
   pam_status); 
 pam_handle_t *pamh; 
 int pam_status;

3.1.2.1. DESCRIPTION

pam_end函数终止 PAM 事务，并且是应用程序在 PAM 上下文中应调用的最后一个函数。返回时，句柄* pamh *不再有效，与之关联的所有内存将无效。

3.1.2.2. 返回值

3.1.3. 设置 PAM 项目

#include <security/pam_modules.h> 
   int pam_set_item( 
   pamh,  
   item_type,  
   item); 
 pam_handle_t *pamh; 
 int item_type; 
 const void *item;

3.1.3.1. DESCRIPTION

pam_set_item功能允许应用程序和 PAM 服务模块访问和更新* item_type 的 PAM 信息。为此，将创建 item 参数指向的对象的副本。支持以下 item_type *：

通常，应用程序或模块将尝试提供经过最强身份验证的值(本地帐户先于远程帐户)。对该值的信任级别体现在与应用程序关联的实际身份验证堆栈中，因此最终位于系统 Management 员的酌处权。

以下附加项目特定于 Linux-PAM，不应在可移植应用程序中使用：

对于除* PAM_CONV 和 PAM_FAIL_DELAY 之外的所有* item_type ， item 是指向\ 终止的字符串的指针。对于 PAM_CONV， item 指向已初始化的 pam_conv 结构。对于 PAM_FAIL_DELAY， item *是函数指针：void (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr)

返回到应用程序之前，PAM_AUTHTOK 和 PAM_OLDAUTHTOK 都将被重置。这意味着应用程序无法访问身份验证令牌。

3.1.3.2. 返回值

3.1.4. 获取 PAM 项目

#include <security/pam_modules.h> 
   int pam_get_item( 
   pamh,  
   item_type,  
   item); 
 const pam_handle_t *pamh; 
 int item_type; 
 const void **item;

3.1.4.1. DESCRIPTION

pam_get_item功能允许应用程序和 PAM 服务模块访问和检索* item_type 的 PAM 信息。成功返回后， item 包含一个指向相应项目值的指针。注意，这是指向实际数据的指针，并且不应被 free()*编辑或覆盖！ * item_type *支持以下值：

通常，应用程序或模块将尝试提供经过最强身份验证的值(本地帐户先于远程帐户)。对该值的信任级别体现在与应用程序关联的实际身份验证堆栈中，因此最终位于系统 Management 员的酌处权。

以下附加项目特定于 Linux-PAM，不应在可移植应用程序中使用：

如果服务模块希望获取用户名，则不应使用此功能，而应执行对 pam_get_user(3)的调用。

仅服务模块有权读取身份验证令牌 PAM_AUTHTOK 和 PAM_OLDAUTHTOK。

3.1.4.2. 返回值

3.1.5. 描述 PAM 错误代码的字符串

#include <security/pam_appl.h> 
   const char *pam_strerror( 
   pamh,  
   errnum); 
 pam_handle_t *pamh; 
 int errnum;

3.1.5.1. DESCRIPTION

pam_strerror函数返回一个指针，该指针指向描述在参数* errnum *中传递的错误代码的字符串，可能使用当前语言环境的 LC_MESSAGES 部分来选择适当的语言。该字符串不得由应用程序修改。没有库函数将修改此字符串。

3.1.5.2. 返回值

此函数始终返回指向字符串的指针。

3.1.6. 请求失败延迟

#include <security/pam_appl.h> 
   int pam_fail_delay( 
   pamh,  
   usec); 
 pam_handle_t *pamh; 
 unsigned int usec;

3.1.6.1. DESCRIPTION

pam_fail_delay函数提供了一种机制，应用程序或模块可通过该机制建议* usec *微秒的最小延迟。该功能记录该功能请求的最长时间。如果 pam_authenticate(3)失败，则失败的返回到应用程序的时间将延迟大约此最长值随机分布的时间(最多 50％)。

与成功无关，当 PAM 服务模块将控制权返回给应用程序时，延迟时间重置为其默认值零。延迟发生在所有身份验证模块被调用之后，但是在控制返回给服务应用程序之前。

使用此功能时，程序员应检查其是否可用于：

#ifdef HAVE_PAM_FAIL_DELAY
    ....
#endif /* HAVE_PAM_FAIL_DELAY */

对于本质上是事件驱动的用单线程编写的应用程序，可能不希望产生此延迟。相反，应用程序可能希望以其他方式注册延迟。例如，在一个服务于来自单个事件循环的多个身份验证请求的单线程服务器中，应用程序可能想要简单地将给定连接标记为已阻止，直到应用程序计时器到期。因此，可以使用* PAM_FAIL_DELAY *项目更改延迟功能。可以分别使用 pam_get_item(3)和 pam_set_item(3)进行查询和设置。用于设置它的值应该是以下原型的函数指针：

void (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr);

参数是模块栈的* retval 返回码，libpam 请求的 usec_delay 微秒延迟以及应用程序与当前 pamh 关联的 appdata_ptr *。最后一个值是由应用程序在调用 pam_start(3)或显式使用 pam_set_item(3)时设置的。

请注意，默认情况下，PAM_FAIL_DELAY 项设置为 NULL。这表明，当身份验证失败并且建议了延迟时，PAM 应该执行如上所述的随机延迟。如果应用程序不希望 PAM 库在身份验证失败时执行任何延迟，则该应用程序必须定义一个不执行任何语句的自定义延迟函数，并将 PAM_FAIL_DELAY 项设置为指向此函数。

3.1.6.2. 返回值

3.1.7. 验证用户

#include <security/pam_appl.h> 
   int pam_authenticate( 
   pamh,  
   flags); 
 pam_handle_t *pamh; 
 int flags;

3.1.7.1. DESCRIPTION

pam_authenticate功能用于验证用户。要求用户根据身份验证服务提供身份验证令牌，通常这是密码，但也可以是指纹。

PAM 服务模块可以请求用户通过对话机制 Importing 其用户名(请参阅 pam_start(3)和 pam_conv(3))。通过身份验证的用户名将出现在 PAM 项 PAM_USER 中。可以通过调用 pam_get_item(3)来恢复该项目。

3.1.7.2. 返回值

3.1.8. 设置用户凭证

#include <security/pam_appl.h> 
   int pam_setcred( 
   pamh,  
   flags); 
 pam_handle_t *pamh; 
 int flags;

3.1.8.1. DESCRIPTION

pam_setcred功能用于构建，维护和删除用户的凭据。在对用户进行身份验证之后以及在为用户打开会话之前(使用 pam_open_session(3))，应调用它来设置凭据。会话关闭后，应删除凭据(使用 pam_close_session(3))。

凭证是用户拥有的东西。它是某些属性，例如* Kerberos 票证或补充组成员身份，这些属性构成给定用户的唯一性。在 Linux 系统上，用户的 UID 和 GID *也是凭据。但是，已经确定这些属性(以及用户所属的默认补充组)是应由应用程序而不是 PAM 直接设置的凭据。此类凭据应在调用此功能之前由应用程序构建。例如，应已执行 initgroups(2)(或等效操作)。

有效的* flags(可以与PAM_SILENT进行逻辑或运算)是：

3.1.8.2. 返回值

3.1.9. 帐户验证 Management

#include <security/pam_appl.h> 
   int pam_acct_mgmt( 
   pamh,  
   flags); 
 pam_handle_t *pamh; 
 int flags;

3.1.9.1. DESCRIPTION

pam_acct_mgmt函数用于确定用户帐户是否有效。它检查身份验证令牌和帐户到期并验证访问限制。通常在用户通过身份验证后调用。

3.1.9.2. 返回值

3.1.10. 更新身份验证令牌

#include <security/pam_appl.h> 
   int pam_chauthtok( 
   pamh,  
   flags); 
 pam_handle_t *pamh; 
 int flags;

3.1.10.1. DESCRIPTION

pam_chauthtok函数用于更改给定用户的身份验证令牌(如与句柄* pamh *关联的状态所示)。

3.1.10.2. 返回值

3.1.11. 开始 PAM 会话 Management

#include <security/pam_appl.h> 
   int pam_open_session( 
   pamh,  
   flags); 
 pam_handle_t *pamh; 
 int flags;

3.1.11.1. DESCRIPTION

pam_open_session函数为先前成功通过身份验证的用户设置用户会话。稍后应通过调用 pam_close_session(3)终止会话。

应该注意的是，有效的 uid，geteuid(2)。应具有足够的特权来执行诸如创建或安装用户主目录之类的任务。

flags 参数是二进制值或以下值的零个或多个：

3.1.11.2. 返回值

3.1.12. 终止 PAM 会话 Management

#include <security/pam_appl.h> 
   int pam_close_session( 
   pamh,  
   flags); 
 pam_handle_t *pamh; 
 int flags;

3.1.12.1. DESCRIPTION

pam_close_session函数用于指示已认证的会话已结束。该会话应已通过调用 pam_open_session(3)创建。

应该注意的是，有效的 uid，geteuid(2)。应具有足够的特权来执行诸如卸载用户主目录之类的任务。

flags 参数是二进制值或以下值的零个或多个：

3.1.12.2. 返回值

3.1.13. 设置或更改 PAM 环境变量

#include <security/pam_appl.h> 
   int pam_putenv( 
   pamh,  
   name_value); 
 pam_handle_t *pamh; 
 const char *name_value;

3.1.13.1. DESCRIPTION

pam_putenv函数用于添加或更改与* pamh *句柄关联的 PAM 环境变量的值。

pam_putenv()对* name_value *的副本进行操作，这意味着与 putenv(3)相比，应用程序负责释放数据。

3.1.13.2. 返回值

3.1.14. 获取一个 PAM 环境变量

#include <security/pam_appl.h> 
   const char *pam_getenv( 
   pamh,  
   name); 
 pam_handle_t *pamh; 
 const char *name;

3.1.14.1. DESCRIPTION

pam_getenv函数在与句柄* pamh 关联的 PAM 环境列表中搜索与 name *所指向的字符串匹配的项，并返回指向环境变量值的指针。该应用程序不允许释放数据。

3.1.14.2. 返回值

pam_getenv函数在失败时返回 NULL。

3.1.15. 获取 PAM 环境

#include <security/pam_appl.h> 
   char **pam_getenvlist( 
   pamh); 
 pam_handle_t *pamh;

3.1.15.1. DESCRIPTION

pam_getenvlist函数返回与句柄* pamh *关联的 PAM 环境的完整副本。 PAM 环境变量表示授予服务时已认证用户的常规环境变量的内容。

内存的格式是 malloc()的 char 指针数组，其最后一个元素设置为 NULL。该数组中的每个非 NULL 条目都指向一个 NUL 终止且 malloc()的 char 字符串，其形式为“ * name = value *”。

应该注意的是，此内存永远不会由 libpam 释放。一旦通过调用pam_getenvlist获得，调用应用程序有责任释放()该内存。

返回的数组的格式和内容是设计使然，而不是巧合，与 execle(3)函数调用的第三个参数所需的格式和内容相匹配。

3.1.15.2. 返回值

pam_getenvlist函数在失败时返回 NULL。

上一章 首页 下一章