(C) Copyright IBM Corp. 1992 REMOTE PASSWORD ADMINISTRATION UTILITY For Client-to-Server-to-Host Password Updates This is for EXTENDED SERVICES 1.0 (ES 1.0) PURPOSE: This utility is intended for use with the OS/2 Database Manager, while running a Server and Client(s) arrangement without the use of the OS/2 LAN Server program. The problem to be solved is: how does a user on a client machine update the password access on the server, for a particular user-id. In addition, if a host session(s) is provided and active on the server, how does a user on a client machine update the password access on the host session(s). The problem is physical access to the server is very difficult or virtually impossible, due to distance or security access. This utility allows a user on a client machine to update the password access on the server, for a particular user-id. In addition, if a host session(s) is provided and active on the server, this utility allows a user on a client machine to update the password access on the host session(s), all without having physical access to the server. ASSUMPTIONS: 1. Both the Client and Server are running OS/2. (Support for a DOS or DOS-Windows client is tbd.) 2. The OS/2 Database Manager Server and Client have been installed, and are running. 3. If RACF Host password updates are desired, the OS/2 Communications Manager has been installed, and 3270 or 5250 terminal emulator sessions have been configured. 4. The same userid is being used for: the server logon, and all host sessions (if any). 5. The same password is being used for: the server logon, and all host sessions (if any). INSTALLATION: SERVER: 1. User must create a directory with the following name and location. This is mandatory, and has no relation to where the database(s) may actually reside. C:\DBMRPWA (this stands for DataBase Manager Remote PassWord Administration) 2. The user then inserts the Utility diskette in to drive A: and does a copy a:*.* c:\dbmrpwa What has been copied into this directory: a. HOST.DIR (required name - contents explained below). b. VM1.RSP (a sample, contents explained below). c. VM2.RSP (a sample, contents explained below). d. MVS.RSP (a sample, contents explained below). e. DBMRPWAS.DLL (this is the code that executes on the server). f. DBMRPWA.EXE (used on the Client; used by the Database Administrator to test the setup code on the Server.) g. READ.ME (the file you are reading now). 3. User alters the CONFIG.SYS by adding the following to an existing LIBPATH= statement (or creates a new LIBPATH= statement): LIBPATH=C:\DBMRPWA; or LIBPATH=(stuff already there);C:\DBMRPWA; NOTE: don't forget the semicolon (;) preceeding the directory's path name. 4. The user must now perform a shutdown of the system and then restart (ctrl-alt-del) in order for the updated CONFIG.SYS to take effect. NOTE: if you have an existing LIBPATH= statement in your CONFIG.SYS file, the shutdown can be avoided by doing the following: a. Examine the existing LIBPATH= statement and pick a subdirectory from the list. We are going to copy our executable file into this subdirectory. b. Go back to step 2 and copy DBMRPWAS.DLL into the subdirectory you just selected. c. Type the name of this subdirectory in the following blank area: ALTERNATE SUBDIRECTORY IS:___________________________. d. Rename this file OLDREAD.DOC and save it back. Future upgrades will be copied into this subdirectory, and you will want to remember where you copied DBMRPWAS.DLL so that you may replace it with the updated code. e. Don't remove C:\DBMRPWA subdirectory! Our code still requires that it be present. (thanks). 5. Now is the time to consider the contents of the 3 files discussed in step 2 above. All 3 files are plain, flat ASCII files that can be edited by the same editor you are using for this READ.ME file. a. HOST.DIR is used if you are running VM or MVS or OS/400 host sessions. These are the host sessions running on the 3270 or 5250 terminal emulators. The contents should be as follows: - If no host connections: file is blank, or file does not exist (you erase it). - If any host connection: file contains at least one line as shown below. - For each additional userid and/or session id, file contains additional line(s) as shown here: (userid),(session-id),(time-out-1),(time-out-2),(response-file) Where userid = both the Server Userid and the Host userid(s) (must be the same). session-id = the nickname for the host session: A, B, C, D, E (there are only 5 sessions allowed in Comm. Manager) time-out-1 = When-Say time out (non-zero, in seconds), refer to the appendix below for a more detailed explanation of this time out. time-out-2 = If/For-Say time out (non-zero, in seconds) refer to the appendix below for a more detailed explanation of this time out. response-file = file that contains keystrokes to effect a password change on the host. Refer to the appendix below for a more detailed explanation of this file. NOTE: do not use a path as part of the name; the file must be in C:\DBMRPWA, so we do not check for path. For example: WANGLER, A, 30, 5, vm1.rsp WANGLER, B, 30, 5, vm2.rsp NOTE: there are up to 5 sessions available through Communications Manager configuration. While this allows 5 different hosts to be accessed simultaneously, it also allows 5 different sessions to the same host. So, if there are a large number of Clients likely to update passwords at the same time, on the same host, then the available sessions ids could be distributed evenly amongst the clients. For example: 10 clients would mean that 1 session id could be shared per 2 Clients. This would likely improve over-all response time; however, having all Clients using the same session id would certainly still work (the password updates would all take place serially, of course, and take longer to accomplish). b. VM1.RSP and VM2.RSP and MVS.RSP are simple examples. They can be named anyway desired (as long as the entry in HOST.DIR is updated to have the correct file name). There is at least one response file. Usually, each type of host requires a unique response file, usually due to differences in what an operator must key to logon and update the password. Many userids, for the same host, can have a single response file. For example, if there is only one host (VM1) but there are 30 userids, all 30 entries in the HOST.DIR could use the same response file. Please see the Appendix for a complete explanation of how this file can be keyed. 6. As part of the installation, all the users from a given client must have connect authority to the same database residing at the server. All the clients may share a database in common, or each client may have a unique database, as long as all the users at each client have connect authority to the same database residing at the server. One way to do this is to create a new database on the server, and catalog it at each client. This will automatically give all current and future users, on each client, access to the new database (default for a database is to be PUBLIC, or open to all users). This costs over a megabyte of hardfile space to be used on the server, however. To do this, from the OS/2 command line, the following may be executed: a. startdbm b. logon userid /p:password c. dbm create database dbmrpwa on c (where c is drive c: or any other convenient drive). An alternative method is to identify an existing database, on the server, that is accessible to all users at a given client, and catalog this database at a given client with an alias that must conform to the following naming convention: DBMRPWA#, where # can be any alphabetic or numeric. In fact, each client can use a different database, as long as it is aliased correctly and is accessible to all users. (See CLIENT INSTALLATION for how to do the cataloging and aliasing.) 7. Testing at the server can be done to confirm the contents of all the editable files (see:TESTING AT THE SERVER below). To do this, catalog a local database as follows: dbm catalog database as DBMRPWA0 INSTALLATION: CLIENT: 1. User should select (or create) a directory that is in the PATH statement of the CONFIG.SYS file. We suggest SQLLIB directory, for example. 2. The user then inserts the Utility diskette in to drive A: and does a copy a:DBMRPWA.EXE into the selected directory. 3. The user now must catalog the server's database so that the Client may access this database remotely. We can use the 'dbm command line interface' to do this. At the OS/2 command line, type the following: dbm catalog database as DBMRPWA0 at node WORK1 Here, the items in uppercase are examples of the ALIAS (DBMRPWA0) and the Workstation name (WORK1). The Workstation name ()is, of course, the name given to the Server during its installation. The ALIAS name should be chosen so it is unique at that Client. The alias used must conform to the following naming convention: DBMRPWA#, where # can be any alphabetic or numeric. If 2 or more servers are set up for this utility, then all the servers Workstations must be cataloged (at each client, don't forget). A unique ALIAS must be used every time. In the example above, we have a Workstation named WORK1; we can also have 2 other Workstations named WORK2 and WORK3. Here are the catalog SQL statements for all three: CLIENT #1: dbm catalog database SAMPLE as DBMRPWA0 at node WORK1 dbm catalog database PAYROLL as DBMRPWA1 at node WORK2 dbm catalog database DBMRPWA as DBMRPWA2 at node WORK3 Each client may re-use the same set of ALIAS names, so: CLIENT #2: dbm catalog database ACCOUNTS as DBMRPWA0 at node WORK1 dbm catalog database DBMRPWA as DBMRPWA1 at node WORK2 dbm catalog database DBMRPWA as DBMRPWA2 at node WORK3 TESTING AT THE SERVER: 1. The contents of the editable files (HOST.DIR, and VM1.RSP, etc) may be confirmed by executing the DBMRPWA.EXE at the server, from the subdirectory C:\DBMRPWA. Execution will be the same as for the client, as described below. Except, when filling in the Utility popup, set Workstation = LOCAL. Some items to confirm: do I have any host sessions? If not, is the HOST.DIR blank? If so, did I add 1 line for each userid and/or host to the HOST.DIR file? Are the time-outs long enough? Do the response files execute the way I expected them to? EXECUTION: SERVER: 1. Confirm that the userid that will be used by the client exists, that it is the same as the Host logon id(s), and that all of these now have the same password. Also, be sure that each host session referenced by HOST.DIR has been started by Commo Manager (ie: logon can be done by DBMRPWA). EXECUTION: CLIENT: 1. User must execute the dbmrpwa.exe file: >dbmrpwa 2. At this point, the popup appears, into which the operator can enter the old and new passwords, the userid, and the workstation (Server) name: - DB MGR Remote Password Administration USER ID: ________________________ CURRENT PASSWORD: ________________________ NEW PASSWORD: ________________________ NEW PASSWORD TWICE: ________________________ REMOTE WORKSTATION: ________________________ CHANGE QUIT APPENDIX: RESPONSE FILES EXPLAINED Here are the contents of the example files: VM1.RSP: / This is an example response file for changing an VM1 password. When "MSG10" Say "VM1 #U@E" For "not in CP" Say "logoff@E" Return "invalid user id #"#U#"." When "password" Say "#P/#N/#N@E" / this line changes the password For "incorrect" Say "logoff@E" Return "Invalid password #"#P#"." For "INVALID" Say "logoff@E" Return "Invalid new password #"#N#"." If "SYSNEWS" Say "@3" If "HOLDING" Say "@C" If "MORE" Say "@C" When "PROFS" Say "logoff@E" VM2.RSP: / This is an example response file for changing an VM2 password. When "MSG10" Say "VM2 #U@E" For "not in CP" Say "logoff@E" Return "invalid user id #"#U#"." When "password" Say "#P/#N/#N@E" / this line changes the password For "incorrect" Say "logoff@E" Return "Invalid password #"#P#"." For "INVALID" Say "logoff@E" Return "Invalid new password #"#N#"." If "SYSNEWS" Say "@3" If "HOLDING" Say "@C" If "MORE" Say "@C" When "Ready;" Say "logoff@E" MVS.RSP: / This is an example response file for changing an MVS password. When "access code:" Say "TSO4@E" When "USERID -" Say "#U@E" When "Password" Say "#P#T#N@E" / these two lines When "verification" Say "#N@E" / change the password When "***" Say "@E" When "OPTION" Say "x@E" When "READY" Say "logoff@E" 1. SYNTAX - how to construct the statements ORDER DEPENDENCE The entries in the response files are order dependent. This means that the statements execute in the order in which they appear. TIME-OUTS EXPLAINED Each statement has a time-out value associated with it. If the first clause of the statement is not satisfied within the time-out value specified (in the HOST.DIR) then a time-out action occurs. For the 'WHEN' clauses, a time-out causes an exit from the response file; for the 'IF' and 'FOR' clauses, a time-out causes control to be passed to the next statement. SPANNING MULTIPLE LINES Also, the entries in the response file may span mutiple lines, since there are no optional parts to them. However, each keyword/string pair must appear on the same line. For example: For "INVALID" Say "logoff@E" Return "Invalid new password #"#N#"." is the same as / this is a check for invalid password For "INVALID" / check for an invalid password Say "logoff@E" / logoff if we find an invalid password Return "Invalid new password #"#N#"." /tell the client what happened 2. COMMENTS As illustrated above, comments begin with a slash and continue to the end of the line. The comment may be on a line by itself, or at the end of a line of code. 3. SEMANTICS - how to read the statements RESERVED KEYWORDS The following reserved keywords are case independent (can be in any case, or mixed case): When, Say, If, For, Return. THE STRINGS The strings ("yyyy") must occur exactly as they are typed. WHEN-SAY STATEMENT When "xxxx" Say "yyyy" [This means that a required/expected event has a given response.] [Example: When "password" Say "#P/#N/#N@E" means that we will wait for (time-out 1) seconds for the phrase "password" to appear next on the display screen. If it does, then we respond back to the host with the string for a password change (old/new/new) followed by the enter key. We can then pass control on to the next line in this response file. If the phrase "password" doesn't appear within 30 seconds, then we exit from the response file and terminate execution of the utility. An error message to this effect will be returned to the Client's display.] IF-SAY STATEMENT If "xxxx" Say "yyyy" [This means that an optional event has a given response.] [Example: If "HOLDING" Say "@C" means that we will wait for (time-out 2) seconds for the phrase "HOLDING" to appear next on the display screen. If it does, then we respond with the CLEAR key and pass control on to the next line in this response file. If the phrase "HOLDING" doesn't appear within (time-out 2) seconds, then we pass control on to the next line in this response file. No error condition is said to occur, and no notice of this will be sent to either the Server or the Client. FOR-SAY-RETURN STATEMENT For "xxxx" Say "yyyy" Return "zzz" [This means that a possible error has a given response, and the Return string appears at the client's display screen.] [Example: For "INVALID" Say "logoff@E" Return "Invalid new password #"#N#"." means that we will wait for (time-out 2) seconds for the phrase "INVALID" to appear next on the display screen. If it does, then we respond with the phrase "logoff" plus the ENTER key, to the host. We pass the Return string "Invalid new password "new password". back to the Client's display. We then exit from the response file and terminate execution of the utility. If the phrase "INVALID" doesn't appear within (time-out 2) seconds, then we pass control on to the next line in this response file. No error condition is said to occur, and no notice of this will be sent to either the Server or the Client. 3. HOW TO WRITE THE STRINGS The strings are encoded as follows: STRING SUBSTITUTION: #P = current password string from the CLIENT (as typed) #N = new password string from the CLIENT (as typed) #U = userid string from the CLIENT (as typed) ## = '#' #" = ' " ' #T = a conditional @T (tab right) is executed if preceediing string was less than 8 characters. (This is for optional field advancing: Say "#P#T#N#T#U" as the input to a 3 field menu. If #P is only 3 characters long, then a @T must be executed to advance to the next field; but if #P is exactly 8 characters long, then the cursor will automatically advance to the next field. Thus, it is conditional on whether the preceeding string is less than 8 characters. KEY STROKES: @T = tab right; field advance. @B = back tab; tab left. @E = enter @C = clear @q = end @0 = home @1 - @9 = F1 - F9 @a - @o = F10 - F24 4. DISCLAIMER: Data encryption is not being performed when transmitting passwords from the DBM client to the DBM server or hosts. Some users may determine this to be an unacceptable security exposure, and thus may choose not to use this facility.