ACME Developer's Readme ======================= ************************************************************************* * * * Copyright 2015 VMS Software, Inc. * * * ************************************************************************* The information contained in this Readme file is subject to change without notice. The only warranties for VMS Software 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. VMS Software shall not be liable for technical or editorial errors or omissions contained herein. 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 7.0 Optional ACME agent SDK components 8.1 Building the ACME Agent and Persona Extension Examples 8.2 ACMEUTIL Utility Appendix Manually Switching Between ACME and UAF Login 1.0 Abstract ============ The current OpenVMS System Disk supplies 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 versions of OpenVMS shipped each variant in different kits, called the ACMELOGIN and LOGIN patch kit; later the LOGINPLUS kit was used to switch between them. Both of these methods have been replaced by a simple command file, SYS$MANAGER:SYS$LOGIN_SWITCH.COM When sys$acm-enabled (ACMELOGIN) 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. A 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. A 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. 23-Nov-2015 VMS Software Inc. version with ACME/UAF switch based on a command file. 3.0 Kit details =============== For VSI OpenVMS versions following V8.4-1H1, neither a LOGINPLUS kit nor ACME_DEV_KITS.BCK kit is supplied, because the default system disk contains both ACMELOGIN and LOGIN images. In addition, the default system disk contains a DCL procedure called SYS$LOGIN_SWITCH.COM which enables you to switch between ACME-based login and traditional UAF-based login. 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 ============================================================================ To install the SYS$ACM enabled LOGIN (previously known as ACMELOGIN) and ACMELDAP_STD kits: 6.1. To install SYS$ACM (ACMELOGIN) enabled LOGINOUT.EXE and SETP0.EXE, use the following command: $ @SYS$MANAGER:SYS$SWITCH_LOGIN.COM You will be told whether the ACME-enabled LOGIN or the UAF-based LOGIN is current in use on your system, will tell you which one it is about to switch to, and ask if you want to continue. If you answer "YES" to this question, the switch will proceed for the current system. 6.2. If the system you used to run SYS$LOGIN_SWITCH on uses a common system disk in a VMSCluster, you must issue the following commands on all cluster members using the same system disk: $ INSTALL REPLACE LOGINOUT $ INSTALL REPLACE SETP0 6.3. 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. VSI recommends that you login with any user account to login system to test the loginout replacement. 6.4. In case of problems: VMS$LOGIN_SWITCH will not attempt to make the switch if the previous configuration was non-standard. For example, if there was a loginout or setp0 image in SYS$SPECIFIC, or if either of these images are missing, VMS$LOGIN_SWITCH will abort and ask you manually to fix the problem. To manually install the correct loginout, see the Appendix of this document. 6.5. Removing ACME LOGIN. To revert to traditional (UAF) login, simply execute SYS$LOGIN_SWITCH again. The procedure should tell you that you are currently using ACME login and ask if you want to switch to UAF login. If you answer YES, the switch is done. Remember as above to INSTALL REPLACE LOGINOUT and SETP0 on other cluster members using the same system disk. Remember also that 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. 6.6. OpenVMS Upgrades If you upgrade to VSI OpenVMS V8.4-1H1 or later via any supported upgrade path, the upgrade procedure will automatically proved the correct version of LOGINOUT and SETP0 (either ACME-based or UAF-based) to match the version you are currently using. 7.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. 7.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. 7.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. APPENDIX: Manually Switching Between ACME and UAF LOGIN ======================================================= VSI does not recommend manual switching, but this section provides information in case the automatic switching procedure runs into a sitution that it can not handle. On VSI OpenVMS system disks (with versions after V8.4-1H1) in SYS$SYSTEM you will find four login-related images: LOGIN_ACME.EXE, LOGIN_UAF.EXE, SETP0_ACME.EXE, SETP0_UAF.EXE In order to switch to the ACME-based loginout say: $COPY SYS$SYSTEM:LOGIN_ACME.EXE SYS$COMMON:[SYSEXE]LOGINOUT.EXE; and $COPY SYS$SYSTEM:SETP0_ACME.EXE SYS$COMMON:[SYSEXE]SETP0.EXE; Be sure that there are no LOGINOUT or SETP0 images in SYS$SPECIFIC:[SYSEXE] and then say: $INSTALL REPLACE LOGINOUT $INSTALL REPLACE SETP0 on all members of the cluster using the system disk that you just changed. To switch back to UAF-based loginout, do the same procedure using LOGIN_UAF.EXE and SETP0_UAF.EXE You may purge old versions after all this is done, but VSI recommends leaving the older versions as an audit trail.