authenticatex 子例程

用途

验证用户的名称和密码。

库

安全性库 (libc.a)

语法

#include <usersec.h>

int authenticatex (UserName, Response, Reenter, Message, State)
char *UserName;
char *Response;
int *Reenter;
char **Message;
void **State;

描述

authenticatex 子例程维护用户必须满足才能向系统认证的需求。这是一个可重新计算的接口，用于提示输入用户的名称和密码。用户必须在 Message 参数发出的提示符处提供字符串。 Response 参数返回用户对 authenticatex 子例程的响应。调用程序不会假设用户为认证而必须满足的提示消息数。 authenticatex 子例程在 State 参数中维护有关认证过程的每个部分的结果的信息。此参数可以与 chpassx， loginrestrictionsx 和 passwdexpiredx 子例程共享。用于认证用户以创建新会话的库例程的正确顺序是:

调用 loginrestrictionsx 子例程以确定哪些管理域允许用户登录。
调用 authenticatex 子例程以使用那些授予登录访问权的管理域来执行认证。
调用 passwdexpiredx 子例程以确定认证过程中使用的任何密码是否已到期，必须更改这些密码才能授予用户访问权。
如果 passwdexpiredx 子例程指示一个或多个密码已到期并且必须由用户更改，请调用 chpassx 子例程以更新用于认证过程的所有密码。

Reenter 参数保持非零值，直到用户不正确地满足所有提示消息或应答。当 Reenter 参数为 0 时，返回码指示认证是通过还是失败。在初始调用时， Reenter 参数的值必须为 0。在后续调用时，必须将 Reenter 参数的非零值传递到 authenticatex 子例程。可以通过使用 Reenter 参数的 0 值调用 authenticatex 子例程或使用 UserName的其他值来开始新的认证。

State 参数包含有关认证过程的信息。先前调用 loginrestrictionsx 的 State 参数可用于控制认证的执行方式。不允许用户登录的管理域会导致在认证期间忽略这些管理域，即使用户具有正确的认证信息也是如此。

authenticatex 子例程确定用户可以尝试的认证域。子例程对用户使用 SYSTEM 属性。 SYSTEM 行中显示的每个标记都对应于可动态装入和处理的方法。同样，系统可以提供多个或备用认证路径。

authenticatex 子例程维护有关呈现给用户的下一条提示消息的内部状态信息。如果在为用户完成所有提示之前，调用程序提供不同的用户名，那么将重置内部状态信息并重新开始提示消息。 authenticatex 子例程要求初始化 State 参数以在更改用户名时引用空值，或者为新用户提供先前调用 loginrestrictionsx 的 State 参数。

如果用户没有定义的密码，或者 SYSTEM 语法明确指定不需要认证，那么用户无需响应任何提示消息。否则，始终会初始提示用户提供密码。

最初可以使用 Response 参数中的 cleartext 密码来调用 authenticatex 子例程。如果用户在初始调用期间提供了密码，但没有密码，那么认证将失败。如果用户希望 authenticatex 子例程提供提示消息，那么 Response 参数是初始调用时的空指针。

authenticatex 子例程设置由名称解析子例程 (例如 getpwnam 子例程) 使用的 AUTHSTATE 环境变量。此环境变量指示用户向其认证的第一个注册表。 AUTHSTATE 环境变量的值包括 DCE， compat和 SYSTEM 语法中显示的令牌名称。如果调用了 cron 守护程序或其他不需要认证的实用程序，那么可以存在空值。

参数

项	描述
消息	指向 authenticatex 子例程为其分配内存并填充的指针。此字符串适用于打印和发出提示消息 (如果 Reenter 参数是非零值)。它还会发出参考消息，例如用户认证失败的原因 (如果 Reenter 参数为 0)。调用应用程序负责释放此内存。
重新输入	指向指示 authenticatex 子例程是否已完成处理的整数值。如果 Reenter 参数引用的整数是非零值，那么 authenticatex 子例程期望用户满足 Message 参数提供的提示消息。如果 Reenter 参数引用的整数是 0 ，那么 authenticatex 子例程已完成处理。当初始调用 authenticatex 函数时， Reenter 引用的整数的初始值必须为 0 ，并且在 authenticationx 子例程完成处理之前不得由调用应用程序修改。
Response	指定包含用户对认证提示的响应的字符串。
状态	指向 authenticatex 子例程为其分配内存并填充的指针。 State 参数也可以是先前调用 loginrestrictionsx 子例程的结果。此参数包含有关用户的 SYSTEM 属性中每个术语的认证过程结果的信息。当不再需要对 passwdexpiredx 或 chpassx 子例程进行后续调用时，调用应用程序负责释放此内存。
UserName	指向要认证的用户的名称。

返回值

成功完成时， authenticatex 子例程将返回值 0。如果此子例程失败，那么它将返回值 1。

错误代码

如果下列其中一个值为 true ，那么 authenticatex 子例程将失败:

项	描述
EINVAL	参数无效。
ENOENT	用户对于系统是未知的。
ENOMEM	内存分配 (malloc) 失败。
ESAD	认证被拒绝。

注: 可以在该模块的文档中找到有关可装入认证模块行为的其他信息。