ACME Developer’s Readme ======================= Copyright (c) 2012 Hewlett-Packard Company, L.P Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under Vendor’s standard commercial license. The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein. Microsoft and Windows are U.S. registered trademarks of Microsoft Corporation. Intel and Itanium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. UNIX is a registered trademark of The Open Group. Table of Contents ================= 1.0 Abstract 2.0 Revision History 3.0 Kit Details 4.0 References 5.0 Read before installation 6.0 Installing the sys$acm (ACMELOGIN) enabled login and LDAP ACME PCSI Kits 7.0 Removing LOGINPLUS and ACMELDAP PCSI Kits 8.0 Optional ACME agent SDK components 8.1 Building the ACME Agent and Persona Extension Examples 8.2 ACMEUTIL Utility 1.0 Abstract ============ LOGINPLUS kit has two variants of LOGINOUT.EXE and SETP0.EXE images: - The traditional non sys$acm (LOGIN) enabled variant - The sys$acm (ACMELOGIN) enabled variant that supports external authentication Earlier both the variants were shipped in two different kits, which is the ACMELOGIN and LOGIN patch kit. The LOGINPLUS kit obsoletes both these kits. The LOGINPLUS kit provides options to install any of the specific variant and has intelligence built in to detect the variant installed. When sys$acm (ACMELOGIN) enabled variant 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. Since these images use SYS$ACM, they will use the authentication policies provided by the ACME agents that have been configured on your system. Production version of an LDAP ACME agent is also available on OpenVMS Alpha or Integrity Version 8.3 and above that provides "standard" LDAP authentication for user login and password-change operations using an LDAPv3--compliant directory server. Production version of a Kerberos ACME agent is also available on OpenVMS Alpha or Integrity Version 8.3 and above that provides "standard" Kerberos authentication for user login and password-change operations. 2.0 Revision History ==================== Date Modification ---- ------------ 05-MAR-2007 New version of V831H1_ACMELDAP_STD kit (version 1.3) to support Active Directory password changes. 22-JAN-2009 Remove LOGIN kits and Alpha kits to make kit I64 only, LOGIN, ALPHA and I64 ACMELDAP kits now ship as separate kits. 4-Feb-2010 Updated to accommodate the OpenVMS Version 8.4 enhancements 26-May-2010 Correction to document, to download patch kits ACMELDAP_STD kit from the ITRC patch locations. 27-Jun-2011 Change in LOGIN kit packaging and installation. New kit named LOGINPLUS introduced for both LOGIN & ACMELOGIN images. 14-May-2012 Change in the installation of ACME LDAP agent. New ACMELDAP and LOGINPLUS kits obsoletes the earlier ACMELDAP_STD, ACMELDAP_ST, ACMELOGIN, LOGIN kits, and also the SYS$UPDATE:ACME_DEV_KITS.BCK file. 3.0 Kit details =============== LOGINPLUS kit contains both ACMELOGIN and LOGIN images. This kit obsoletes the earlier ACMELOGIN and LOGIN patch kit provided either through SYS$UPDATE:ACME_DEV_KITS.BCK or through direct patch download. 4.0 References ============== - ACME Developer's Guide (PDF version available at SYS$HELP:ACME_DEV_GUIDE.PDF). This guide is useful, if you are writing a new ACME agent. - OpenVMS Guide to System security (Provided with the OS documentation set) - You can refer the sections, "Enabling External Authentication" and "Authentication and Credentials Management Extensions (ACME) Subsystem" - HP OpenVMS System Services Reference Manual (Refer to SYS$ACM system service) - ACME LDAP documentation at SYS$HELP:ACMELDAP_STD_CONFIG_INSTALL.PDF or SYS$HELP:ACMELDAP_STD_CONFIG_INSTALL.TXT - Kerberos agent related information is available at http://h71000.www7.hp.com/openvms/products/kerberos - ACMEUTIL Utility (Provided in sys$examples:) - Examples in C source code for an ACME agent and associated persona extension Note: The ACMEUTIL and the example ACME agent are unsupported components for evaluating custom ACME agents. 5.0 Read before installing ========================== - The SYS$SINGLE_SIGNON logical name used to control operations with the standard non-sys$acm enabled 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 "Enabling External Authentication" and "Authentication and Credentials Management Extensions (ACME) Subsystem" of Chapter 7). - To know more about the difference between the sys$acm and non-sys$acm enabled LOGINOUT.EXE and SETP0.EXE images, external authentication, and ACME, see the latest OpenVMS Guide to System Security provided with OpenVMS documentation set (see section "Enabling External Authentication" and "Authentication and Credentials Management Extensions (ACME) Subsystem" of Chapter 7). 6.0 Installing the SYS$ACM (ACMELOGIN) enabled LOGIN and ACME LDAP PCSI kits ============================================================================ To install the SYS$ACM enabled LOGIN (previously known as ACMELOGIN) and ACMELDAP kits: 1. Download the appropriate LOGINPLUS kit from HP patch website: HP-I64VMS-_LOGINPLUS-VXXXX--4.PCSI or DEC-AXPVMS-_LOGINPLUS-VXXXX--4.PCSI Where is the version of the OpenVMS operating system version and "XXXX" is the version of LOGINPLUS kit. For example, VMS84I_LOGINPLUS_V0100. The LOGINPLUS kit contains the SYS$ACM (ACMELOGIN) and non-SYS$ACM (LOGIN) enabled login images. Earlier both the SYS$ACM (ACMELOGIN) and non-SYS$ACM (LOGIN) enabled login images were provided as separate kits. Now, these images are integrated as LOGINPLUS kit, with extra intelligence added to detect the type of images. Going forward, the LOGINPLUS kit will be integrated into the OpenVMS update kit. 2. Download the appropriate ACMELDAP kit from HP patch website: - VMS83A_ACMELDAP-V0500 or later for OpenVMS V8.3 Alpha - VMS83I_ACMELDAP-V0500 or later for OpenVMS V8.3 Integrity servers - VMS831H1I_ACMELDAP-V0300 or later for OpenVMS V8.3-1H1 Integrity servers - On OpenVMS Version 8.4 or later the files are already part of the Operating system. However, bug fixes and enhancements might be provided as ACMELDAP patch kit. Going forward, the ACMELDAP kit will be integrated into the OpenVMS update kit. Changes in installation method ============================== The above version of ACMELDAP patch kits on OpenVMS V8.3 Alpha and Integrity servers and OpenVMS V8.3-1H1 Integrity servers, supersedes the earlier ACMELDAP, ACMELDAP_STD (for OpenVMS V8.3), and ACMELDAP_ST (for OpenVMS V8.3-1H1) patch kits. The ACMELDAP_STD/ACMELDAP_ST patch kits was provided as a part of [SYSUPD]ACME_DEV_KITS.BCK after installing the earlier version of ACMELDAP patch kit. Going forward, the SYS$UPDATE:ACME_DEV_KITS.BCK will be obsolete. After you install the new ACMELDAP kit an additional step of extracting [SYSUPD]ACME_DEV_KITS.BCK and installing ACMELDAP_STD or ACMELDAP_ST patch kits is not required. 3. To install SYS$ACM (ACMELOGIN) enabled LOGINOUT.EXE and SETP0.EXE, use the following command: $ PRODUCT INSTALL/SAVE LOGINPLUS The installation procedure detects if sys$acm or non-sys$acm enabled login is installed on your system. If non-sys$acm enabled login is installed on the system, answer "NO" to the following question: ***************************************************** Currently LOGIN KIT installed on your system Answer YES to install LOGIN Answer NO to install ACMELOGIN ***************************************************** Do you wish to install updated LOGIN [YES] ?: NO Do you wish to install updated ACMELOGIN [YES] ?: YES If sys$acm enabled login is installed on the system, answer "YES" to the following question: ***************************************************** Currently ACMELOGIN KIT installed on your system Answer YES to install ACMELOGIN Answer NO to install LOGIN ***************************************************** Do you wish to install updated ACMELOGIN [YES] ?: YES 4. To check the image identification, use the following commands: $ ANALYZE/IMAGE/INTER SYS$COMMON:[SYSEXE]LOGINOUT.EXE $ ANALYZE/IMAGE/INTER SYS$COMMON:[SYSEXE]SETP0.EXE You must get LOGIN98 as a part of the "Image file identification:" field, for the sys$acm (ACMELOGIN) enabled images. HP recommends that you use any user account to login to the system and test the LOGINPLUS kit after installation. 5. If you need to perform user authentication by looking up against an LDAP directory server, you must install the ACMELDAP kit on OpenVMS Version 8.3 or 8.3-1H1. To do so, use the following command: $ PRODUCT INSTALL/SAVE ACMELDAP After installation, for information on setting up the LDAP persona extension and configuring the LDAP ACME agent, see the documentation of the LDAP ACME agent at SYS$HELP:ACMELDAP_STD_CONFIG_INSTALL.PDF or SYS$HELP:ACMELDAP_STD_CONFIG_INSTALL.TXT. 7.0 Removing LOGINPLUS and ACMELDAP PCSI Kits ================================================== The LOGINPLUS and ACMELDAP kits can be removed using the PRODUCT UNDO PATCH command. If other patch kits have been installed after the installation of the LOGINPLUS or ACMELDAP kit, those kits will have to be removed before removing the LOGINPLUS or ACMELDAP kit. Another way to removing the sys$acm(ACMELOGIN) enabled images of LOGINOUT.EXE and SETP0.EXE (provided with LOGINPLUS kit), is to install the LOGINPLUS patch kit again. To do this answer NO to the below question when installing the LOGINPLUS patch kit again ***************************************************** Currently ACMELOGIN KIT installed on your system Answer YES to install ACMELOGIN Answer NO to install LOGIN ***************************************************** Do you wish to install updated ACMELOGIN [YES] ?: NO Do you wish to install updated LOGIN [YES] ?: YES Note that, after installing the LOGINPLUS patch kit for non-sys$acm enabled login, you will not be able to login into the system using LDAP authentication. However, the LDAP ACME or any other ACME agent might still be configured and you have to explicitly edit the SYS$MANAGER:ACME$START.COM and comment specific lines relevant to the ACME agent from this file. 8.0 Optional ACME agent SDK components ====================================== This section of the document includes information for writing a custom ACME agent using optional ACME agent SDK components. You may ignore this section of the document if you are running the sys$acm enabled LOGINOUT.EXE and SETP0.EXE images with the standard LDAP ACME agent or other standard ACME agents. 8.1 Building the ACME Agent and Persona Extension examples ========================================================== Source code for the ACME agent and persona extension examples is available in SYS$EXAMPLES. The DEC C compiler is required to build these examples. Instructions for building the ACME agent and persona extension examples are provided in SYS$EXAMPLES:ACME_EXAMPLE_README.TXT. 8.2 ACMEUTIL utility ==================== The ACMEUTIL utility is a useful tool for testing ACME agent behavior before installing the LOGINPLUS(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 the 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 AUTHORIZE/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 change the "noecho" terminal attribute. Therefore, prompts for passwords and other items marked for "noecho" will be echoed at the terminal.