Production Kit for SYS$ACM-Enabled LOGINOUT and LDAP ACME Agent =============================================================== Production versions of LOGINOUT.EXE and SETP0.EXE (SET PASSWORD) images are available that utilize the SYS$ACM system service for user authentication and password changes. When these images are used, login and password change requests are sent to the SYS$ACM service and handled by the ACME_SERVER process's authentication agents. A production version of an LDAP ACME agent is also available that provides "standard" LDAP authentication for user login and password-change operations using a LDAP version 3 compliant directory server. Kit Contents ------------ (SYS$ACM-Enabled LOGINOUT.EXE and SETP0.EXE (SET PASSWORD) Images) Note: These are supported images for use in a production environment. - PCSI kit containing modified versions of LOGINOUT.EXE and SETP0.EXE - PCSI kit containing the LDAP ACME agent kit (Optional ACME agent SDK components (for writing custom ACME agents) Note: These are unsupported components for evaluating custom ACME agents. - ACME Developer's Guide (PDF version) - Examples C source code for an ACME agent and associated persona extension SYS$ACM-Enabled LOGINOUT.EXE and SETP0.EXE (SET PASSWORD) Images ================================================================ ***** Important Notes ***** The PCSI patch kits that provide modified versions of LOGINOUT.EXE and SETP0.EXE, and the LDAP ACME agent, must only be installed on the version of OpenVMS Alpha or I64 that shipped these kits. The SYS$SINGLE_SIGNON logical name used to control operations with the standard LOGINOUT.EXE image have no effect with the new LOGINOUT.EXE and SYS$ACM. The new features are controlled by UAF flags and the SECURITY_POLICY system parameter as described in the OpenVMS Guide to System Security (see section "Authentication and Credentials Management Extensions (ACME) Subsystem" of Chapter 7). Installing the ACMELOGIN and LDAP ACME PCSI Kits ------------------------------------------------ The ACMELOGIN kit is provided to install versions of LOGINOUT.EXE and SETP0.EXE that are modified to use the SYS$ACM system service. Since these images use SYS$ACM, they will use the authentication policies provided by the ACME agents that have been configured on your system including user-defined agents. All components are contained in the BACKUP saveset SYS$UPDATE:ACME_DEV_KITS.BCK. You must restore the PCSI kits to your default directory using BACKUP and then install the kits. *** Step 1 (restore PCSI kits): $ BACKUP SYS$UPDATE:ACME_DEV_KITS.BCK/SAVE *.* There are six PCSI kits (3 for Alpha and 3 for I64): DEC-AXPVMS-V83_ACMELOGIN-V0101--4.PCSI (ACMELOGIN V1.1 patch kit Alpha) HP-I64VMS-V83_ACMELOGIN-V0101--4.PCSI (ACMELOGIN V1.1 patch kit I64) DEC-AXPVMS-V83_LOGIN-V0101--4.PCSI (LOGIN V1.1 patch kit Alpha) HP-I64VMS-V83_LOGIN-V0101--4.PCSI (LOGIN V1.1 patch kit I64) DEC-AXPVMS-V83_ACMELDAP_STD-V0102--4.PCSI (ACMELDAP-STD V1.2 patch kit Alpha) HP-I64VMS-V83_ACMELDAP_STD-V0102--4.PCSI (ACMELDAP-STD V1.2 patch kit I64) The ACMELOGIN kit contains modified versions of LOGINOUT.EXE and SETP0.EXE that use the SYS$ACM system service to perform authentication and password changes. The LOGIN kit contains the original LOGINOUT.EXE and SETP0.EXE images that were shipped with this release. You can install this kit to restore the original versions of these files if you've previously installed the ACMELOGIN kit for development and testing. The ACMELDAP_STD kit contains an LDAP ACME agent that provides "standard" LDAP authentication for user login and password-change operations using an LDAPv3-compliant directory server. Please refer to the SYS$HELP:LDAPACME$README-STD.TXT file in the ACMELDAP_STD kit for complete information on installing and configuring the LDAP ACME agent. (Obsolete Kit) HP-I64VMS-V83_ACMELDAP-V0100--4.PCSI (ACMELDAP V1.0 patch kit Alpha - obsolete) DEC-AXPVMS-V83_ACMELDAP-V0100--4.PCSI (ACMELDAP V1.0 patch kit I64 - obsolete) This ACMELDAP kit offered a way to centralize password-related SYSUAF fields using an LDAP directory. The ACMELDAP kit is OBSOLETE. *** Step 2 (install PCSI kits): Use the Polycenter Software Installation Utility from a privileged account to install these kits: $ PRODUCT INSTALL V83_ACMELOGIN ! Modified images or $ PRODUCT INSTALL V83_LOGIN ! Original images or $ PRODUCT INSTALL V83_ACMELDAP_STD ! LDAP ACME agent A reboot is required after installing the ACMELDAP_STD kit in order to load the LDAP persona extension loadable image. Optional ACME agent SDK components (for writing custom ACME agents) =================================================================== The remainder of this document contains information for writing a custom ACME agent. Note: This portion of the document is not needed if you only wish to run the new LOGINOUT.EXE and SETP0.EXE images with the standard LDAP ACME agent. Building the ACME Agent and Persona Extension Examples ------------------------------------------------------ Source code for the ACME agent and persona extension examples is located in SYS$EXAMPLES. The DEC C compiler is required to build these examples. Instructions for building the example ACME agent and persona extension can be found in SYS$EXAMPLES:ACME_EXAMPLE_README.TXT. ACMEUTIL Utility ---------------- The ACMEUTIL utility is a useful tool for testing ACME agent behavior before installing the ACMELOGIN kit. ACMEUTIL is a SYS$ACM program that supports dialogue and non-dialogue mode operation and provides a trace facility for debugging. ACMEUTIL is located in SYS$EXAMPLES and must be built from source code using the ACMEUTIL.COM procedure. The ACMEUTIL_SETUP.COM file installs the DCL command line definitions for ACMEUTIL (see comments for entire DCL syntax). Once built, you can use the utility as follows: $ acme auth/dialog=(input,noecho)/trace Dialogue flags = 00000003 Queuing AUTHENTICATION Request Request completed Service status = 1 ACMESB structure at address 7AE1A688 ...l_status 074A8640 ...l_secondary_status 074A8640 ...l_acme_id 00000000 ...l_acme_status 00000000 . . . Note: The ACMEUTIL utility does not alter the "noecho" terminal attribute, so prompts for passwords and other items marked for noecho will be echoed at the terminal. Known Problems: 1. The example ACME agent and persona extension do not currently support SET PASSWORD or the SYS$ACM ACME$_FC_CHANGE_PASSWORD function. 2. The DECwindows login interface is partially operational. Some password exception handling functions during DECwindows login are not completely functional during generated password processing and password history validation. "ACME Developer's Guide" Errata: 1. Page 2-1 (ommissions) Unless otherwise indicated, all pass-by-reference arguments and address pointers within data structures are 32-bit addresses. Use the CC/VAXC compiler switch to have the ACME agent header files generate the convenient field references to ACME data structures. The VMS ACME agent is required for a complete operational environment. If you start the ACME_SERVER process manually using SET SERVER ACME commands, you must configure the VMS ACME in order to grant persona- based credentials. Use the following commands to start the ACME_SERVER and configure ACME agents: $ SET SERVER ACME/START/LOG $ SET SERVER ACME/CONFIG=(NAME=VMS,CRED=VMS) $ SET SERVER ACME/CONFIG=(NAME=[,CRED=]) $ SET SERVER ACME/ENABLE 2. Table 4-1, WQE Extensions LOGON_STATS_DOI Set by an agent. Used to load the DOI-specific portion of the ACME$_LOGON_INFORMATION item code. Set using ACME$CB_SET_LOGON_STATS_DOI. 3. Page 9-1, ACME Callback Routines Callback routines that specify a return code of ACME$_NORMAL may also return SS$_NORMAL under certain situations. 4. Page 9-16 and 9-18, ACME$CB_ALLOCATE_ACME_VM and ACME$CB_ALLOCATE_WQE_VM The 'segment_address' argument is the address of a longword to receive the address of the memory allocated by this procedure. 5. Page 11-3, Persona Extension Modify Routine The persona extension's modify routine must support the ISS$_DOI item code unless the extension's DOI field was already loaded by the ACME agent which created the extension's contents and provided it to SYS$ACM using the ACME$CB_ISSUE_CREDENTIALS callback. ISS$_DOI represents a quadword integer whose low-order longword contains the identifier of the creating ACME agent. The high-order longword is ignored. 6. Page 9-28, ACME$CB_ISSUE_CREDENTIALS callback routine ACME$CB_ISSUE_CREDENTIALS() restricts the credentials size to a maximum of 8192 and returns ACME$_INVPARAMETER for any larger specified size. Reporting Problems and Feedback ------------------------------- Send problem reports and feedback on the ACME Agent SDK to the following e-mail address: