pwdrestrict_method Subroutine

Purpose

Defines loadable password restriction methods.

Library

Syntax

int pwdrestrict_method (UserName, NewPassword, OldPassword, Message)
char * UserName;
char * NewPassword;
char * OldPassword;
char ** Message;

Description

The pwdrestrict_method subroutine extends the capability of the password restrictions software and lets an administrator enforce password restrictions that are not provided by the system software.

Whenever users change their passwords, the system software scans the pwdchecks attribute defined for that user for site specific restrictions. Since this attribute field can contain load module file names, for example, methods, it is possible for the administrator to write and install code that enforces site specific password restrictions.

The system evaluates the pwdchecks attribute's value field in a left to right order. For each method that the system encounters, the system loads and invokes that method. The system uses the load subroutine to load methods. It invokes the load subroutine with a Flags value of 1 and a LibraryPath value of /usr/lib. Once the method is loaded, the system invokes the method.

To create a loadable module, use the -e flag of the ld command. Note that the name pwdrestrict_method given in the syntax is a generic name. The actual subroutine name can be anything (within the compiler's name space) except main. What is important is, that for whatever name you choose, you must inform the ld command of the name so that the load subroutine uses that name as the entry point into the module. In the following example, the C compiler compiles the pwdrestrict.c file and pass -e pwdrestrict_method to the ld command to create the method called pwdrestrict:

cc -e pwdrestrict_method -o pwdrestrict pwdrestrict.c

The convention of all password restriction methods is to pass back messages to the invoking subroutine. Do not print messages to stdout or stderr. This feature allows the password restrictions software to work across network connections where stdout and stderr are not valid. Note that messages must be returned in dynamically allocated memory to the invoking program. The invoking program will deallocate the memory once it is done with the memory.

There are many caveats that go along with loadable subroutine modules:

  1. The values for NewPassword and OldPassword are the actual clear text passwords typed in by the user. If you copy these passwords into other parts of memory, clear those memory locations before returning back to the invoking program. This helps to prevent clear text passwords from showing up in core dumps. Also, do not copy these passwords into a file or anywhere else that another program can access. Clear text passwords should never exist outside of the process space.
  2. Do not modify the current settings of the process' signal handlers.
  3. Do not call any functions that will terminate the execution of the program (for example, the exit subroutine, the exec subroutine). Always return to the invoking program.
  4. The code must be thread-safe.
  5. The actual load module must be kept in a write protected environment. The load module and directory should be writable only by the root user.

One last note, all standard password restrictions are performed before any of the site specific methods are invoked. Thus, methods are the last restrictions to be enforced by the system.

Parameters

Item Description
UserName Specifies a "local" user name.
NewPassword Specifies the new password in clear text (not encrypted).This value may be a NULL pointer. Clear text passwords are always in 7 bit ASCII.
OldPassword Specifies the current password in clear text (not encrypted).This value may be a NULL pointer. Clear text passwords are always in 7 bit ASCII.
Message Specifies the address of a pointer to malloc'ed memory containing an NLS error message. The method is expected to supply the malloc'ed memory and the message.

Return Values

The method is expected to return the following values. The return values are listed in order of precedence.

Item Description
-1 Internal error. The method could not perform its password evaluation. The method must set the errno variable. The method must supply an error message in Message unless it can't allocate memory for the message. If it cannot allocate memory, then it must return the NULL pointer in Message.
1 Failure. The password change did not meet the requirements of the restriction. The password restriction was properly evaluated and the password change was not accepted. The method must supply an error message in Message. The errno variable is ignored. Note that composition failures are cumulative, thus, even though a failure condition is returned, trailing composition methods will be invoked.
0 Success. The password change met the requirements of the restriction. If necessary, the method may supply a message in Message; otherwise, return the NULL pointer. The errno variable is ignored.