Safeguard Management Programming Manual

Transcription

1 Safeguard Management Programming Manual Part Number: Published: May 2017 Edition: L15.02, J06.03, H06.08, G06.29, and later L-series, J-series, H-series, and G-series RVUs.

2 2013, 2017 Hewlett Packard Enterprise Development LP Notices The information contained herein is subject to change without notice. The only warranties for Hewlett Packard Enterprise 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. Hewlett Packard Enterprise shall not be liable for technical or editorial errors or omissions contained herein. Confidential computer software. Valid license from Hewlett Packard Enterprise required for possession, use, or copying. Consistent with FAR and , 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. Links to third-party websites take you outside the Hewlett Packard Enterprise website. Hewlett Packard Enterprise has no control over and is not responsible for information outside the Hewlett Packard Enterprise website. Acknowledgments Microsoft and Windows are trademarks of the Microsoft group of companies Adobe and Acrobat are trademarks of Adobe Systems Incorporated. Intel, Itanium, Pentium, and Intel Inside, and the Intel Inside logo 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. Motif, OSF/1, UNIX, X/Open, and the "X" device are registered trademarks, and IT DialTone and The Open Group are trademarks of The Open Group in the U.S. and other countries. Open Software Foundation, OSF, the OSF logo, OSF/1, OSF/Motif, and Motif are trademarks of the Open Software Foundation, Inc. Warranty Java and Oracle are registered trademarks of Oracle and/or its affiliates. OSF MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THE OSF MATERIAL PROVIDED HEREIN, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. OSF shall not be liable for errors contained herein or for incidental consequential damages in connection with the furnishing, performance, or use of this material. 1990, 1991, 1992, 1993 Open Software Foundation, Inc. This documentation and the software to which it relates are derived in part from materials supplied by the following: 1987, 1988, 1989 Carnegie-Mellon University. 1989, 1990, 1991 Digital Equipment Corporation. 1985, 1988, 1989, 1990 Encore Computer Corporation Free Software Foundation, Inc. 1987, 1988, 1989, 1990, 1991 Hewlett Packard Enterprise Company. 1985, 1987, 1988, 1989, 1990, 1991, 1992 International Business Machines Corporation. 1988, 1989 Massachusetts Institute of Technology. 1988, 1989, 1990 Mentat Inc Microsoft Corporation. 1987, 1988, 1989, 1990, 1991, 1992 SecureWare, Inc. 1990, 1991 Siemens Nixdorf Informationssysteme AG. 1986, 1989, 1996, 1997 Sun Microsystems, Inc. 1989, 1990, 1991 Transarc Corporation. This software and documentation are based in part on the Fourth Berkeley Software Distribution under license from The Regents of the University of California. OSF acknowledges the following individuals and institutions for their role in its development: Kenneth C.R.C. Arnold, Gregory S. Couch, Conrad C. Huang,

3 Ed James, Symmetric Computer Systems, Robert Elz. 1980, 1981, 1982, 1983, 1985, 1986, 1987, 1988, 1989 Regents of the University of California. Export of the information contained in this publication may require authorization from the U.S. Department of Commerce.

4 Contents About This Document...10 Supported Release Version Updates (RVUs)...10 Intended Audience...10 New and Changed Information...10 Changes to manual Changes to manual Changes to manual Changes to manual...11 Changes to manual...11 Changes to manual...11 Related Documentation...12 Publishing History...12 Introduction...13 Objects Controlled by Safeguard...13 Safeguard Management Functions Safeguard Architecture and Interfaces...16 Management Programming for the Safeguard Subsystem Communicating With the Safeguard Subsystem...17 Event Messages...18 Commands That a Management Application Can Issue Communicating With the Subsystem Startup Considerations...20 Definition Files...21 Processes Addressed...22 Elements of SPI Messages Naming Guidelines for Applications...23 Common Syntax Elements for Data Communications Command Numbers...23 Object Types...23 Object Names...24 Event Numbers...27 Subjects of Event Messages Other Tokens Constructs Involving Multiple Tokens...28 Components of a Command...28 Components of a Response Components of an Event Message...28 SPI Programming Considerations Building the Command Buffer...29 Discontinuing a Command in Progress Receiving and Decoding the Response Buffer...30 Error Handling Contents

5 Security...30 Common Definitions...31 SPI Standard Definitions EMS Standard Definitions Data Communications Standard Definitions...34 Safeguard-Specific Standard Definitions...35 Selection Expressions SAFECOM WHERE CREATION-TIME selection options...36 SAFECOM WHERE GROUP selection options...36 Commands Commands by Object Type Command Descriptions ACTIVATE ALIAS Command...43 ACTIVATE PROTECTIONRECORD Command...45 ACTIVATE TERMINAL (LU) Command...47 ACTIVATE USER Command ADD ALIAS Command ADD AUDIT POOL (FILESET) Command...62 ADD EVENT-EXIT-PROCESS (PROC) Command ADD GROUP Command ADD PROTECTIONRECORD Command ADD REMOTEPASSWORD Command ADD TERMINAL (LU) Command ADD USER Command...83 ALTER ALIAS Command...94 ALTER AUDIT POOL Command ALTER EVENT-EXIT-PROCESS (PROC) Command ALTER GROUP Command ALTER PROTECTIONRECORD Command ALTER REMOTEPASSWORD Command ALTER SUBSYSTEM Command ALTER TERMINAL (LU) Command ALTER USER Command DELETE ALIAS Command DELETE AUDIT POOL Command DELETE EVENT-EXIT-PROCESS (PROC) Command DELETE PROTECTIONRECORD Command DELETE GROUP Command DELETE REMOTEPASSWORD Command DELETE TERMINAL (LU) Command DELETE USER Command GETVERSION Command INFO ALIAS Command INFO AUDIT POOL Command INFO EVENT-EXIT-PROCESS (PROC) Command INFO GROUP Command INFO PROTECTIONRECORD Command INFO REMOTEPASSWORD Command INFO SUBSYSTEM Command INFO TERMINAL (LU) Command INFO USER Command LISTOBJECTS Command Contents 5

6 LISTOBJECTS ALIAS Command LISTOBJECTS USER Command LISTOPENS Command LOAD PROTECTIONRECORD command NEXTFILE (SWITCH) Command RELEASE AUDIT FILE Command START TERMINAL (LU) Command STATUS ALIAS Command STATUS PROTECTIONRECORD Command STATUS SUBSYSTEM Command STATUS USER Command STOP Command SUSPEND ALIAS Command SUSPEND PROTECTIONRECORD Command SUSPEND TERMINAL (LU) Command SUSPEND USER Command Event Management Safeguard Subsystem Processes That Report Events Event Reporting and Management Strategy Event-Message Filters Example Elements of Event Messages for Safeguard Subsystems Common Syntax Elements Naming Rules and Guidelines for Applications Event Numbers Subjects of Event Messages Constructs Involving Multiple Tokens Definition Files Event-Message Buffers SPI Standard Definitions in Safeguard Event Messages EMS Standard Definitions in Safeguard Event Messages Safeguard Definitions Safeguard Event Messages Event-Message Descriptions ZSFG-EVT-BAD-TOS-VERSION ZSFG-EVT-CREATED-SFG-FILE ZSFG-EVT-NEWPROCESS ZSFG-EVT-STOPPED-PROCESS ZSFG-EVT-CONFIG-CHANGED ZSFG-EVT-AUDITFILESWITCH ZSFG-EVT-AUDITSTATES ZSFG-EVT-PENDINGAUDITSTATE ZSFG-EVT-CRITICALAUDITSTATE ZSFG-EVT-FILERELEASED ZSFG-EVT-FILERECYCLED ZSFG-EVT-BAD-SMON-NAME ZSFG-EVT-UNUSABLE-SFG-FILE ZSFG-EVT-PROC-FAILURE ZSFG-EVT-PROC-CHANGED ZSFG-EVT-PROC-KILL ZSFG-EVT-EXIT-REPLY-ERROR ZSFG-EVT-EXIT-REPLY-INV ZSFG-EVT-SMON-LOST-SMP ZSFG-EVT-CMON-MISSING Contents

7 ZSFG-EVT-VIRT-OBJFILE-DOWN ZSFG-EVT-FILE-LOCKED ZSFG-EVT-SEGALLOC-ERR ZSFG-EVT-POOLDEFINE-ERR ZSFG-EVT-POOLGETSPACE-ERR ZSFG-EVT-MAX-LIMIT-CON-UA-REQ ZSFG-EVT-MAX-CON-UA-REQ-EXCEED ZSFG-EVT-THRESHOLD-CON-UA-REQ ZSFG-EVT-CONUA-BELOW-THRESHOLD ZSFG-EVT-INSUFFICIENT-OBI-SIZE ZSFG-EVT-CONFIG-EXLVAL ZSFG-EVT-BAD-HELPER-NAME ZSFG-EVT-BAD-PSB ZSFG-EVT-PSB-UPDATE-COMPLETE ZSFG-EVT-HELPER-LOST-SMP Websites Support and other resources Accessing Hewlett Packard Enterprise Support Accessing updates Customer self repair Remote support Warranty information Regulatory information Documentation feedback Error Numbers and Error Lists Error-List Descriptions ZSFG-ERR-SMALLUSERIDFILE ZSFG-ERR-INTERNAL ZSFG-ERR-SUBJGROUPNUM ZSFG-ERR-SUBJGROUPNAME ZSFG-ERR-SQLOBJECT ZSFG-ERR-LICENSENONOBJ ZSFG-ERR-PROGIDNONOBJ ZSFG-ERR-MAX-ACL-EXCEEDED ZSFG-ERR-SYS-NOT-FOUND ZSFG-ERR-ORPHANED-ACL ZSFG-ERR-NONPERSIST ZSFG-ERR-PSWD-TOO-SOON ZSFG-ERR-PSWD-DUPLICATE ZSFG-ERR-PSWD-TOO-SHORT ZSFG-ERR-VOL-NONEXISTENT ZSFG-ERR-AUDITFILE-MISSING ZSFG-ERR-AUDITFILE-FOREIGN ZSFG-ERR-AUDITFILE-RLSED ZSFG-ERR-AUDITPOOL-FULL ZSFG-ERR-AUDITPOOL-MISSING ZSFG-ERR-AUDITPOOL-NOTCURRENT ZSFG-ERR-AUDITPOOL-CURRENT ZSFG-ERR-AUDITPOOL-NEXT ZSFG-ERR-AUDITPOOL-DIRTY Contents 7

8 8 Contents ZSFG-ERR-LU-INUSE ZSFG-ERR-MAX-LUS-DEFINED ZSFG-ERR-CANT-START-CI ZSFG-ERR-ALIASGUARDIANID ZSFG-ERR-ALIASGUARDNAME ZSFG-ERR-ORPHANEDALIAS ZSFG-ERR-GUARDALIASNAME ZSFG-ERR-SEEP-AUTHN-BUSY ZSFG-ERR-SEEP-AUTHZ-BUSY ZSFG-ERR-SEEP-PSWD-BUSY ZSFG-ERR-GROUP-MEMBERS ZSFG-ERR-GROUP-DERIVED ZSFG-ERR-GROUP-PRIMARY ZSFG-ERR-GROUP-MAX ZSFG-ERR-GROUP-ID-NOTFOUND ZSFG-ERR-GROUP-NAME-NOTFOUND ZSFG-ERR-PRI-GROUP-NOTFOUND ZSFG-ERR-GROUP-ID-EXISTS ZSFG-ERR-GROUP-NAME-EXISTS ZSFG-ERR-CANT-START-PROCESS ZSFG-ERR-MAX-PROC-EXCEEDED ZSFG-ERR-PROGFILE-NULL ZSFG-ERR-PROGFILE-REQUIRED ZSFG-ERR-PROC-ENABLED ZSFG-ERR-PSWD-QUAL-DENIED ZSFG-ERR-PSWD-QUAL-REJECT ZSFG-ERR-GROUP-SECVIOL ZSFG-ERR-MEMBER-UPDATE ZSFG-ERR-NO-MEMBER-UPDATE ZSFG-ERR-SEL-CMPR-INV ZSFG-ERR-USERID-EXISTS ZSFG-ERR-SEEP-ALREADY-DEFINED ZSFG-ERR-OWNER-NOTSPECIFIED ZSFG-ERR-WARNMODE-OBJTYPE ZSFG-ERR-PAT-BAD-VOLNAME ZSFG-ERR-PAT-MISSING-ALL ZSFG-ERR-PAT-BAD-PATNAME ZSFG-ERR-MAX-CONUAREQ-EXCEEDED ZSFG-ERR-TRUSTNONOBJ ZSFG-ERR-MAX-OWN-EXCEEDED ZSFG-ERR-OWNER-LIST-INV-OWNER ZSFG-ERR-DESC-TEXTDATA-INVALID ZSFG-ERR-OBJECTFCB-DIR-FULL ZSFG-ERR-PATOBJECTFCB-DIR-FULL ZSFG-ERR-ACL-AUTHORITY-INVALID ZSFG-ERR-SECURITY-GROUP-INV ZSFG-ERR-PSWD-MINLEN-GT-MAXLEN ZSFG-ERR-PSWD-MINLEN-DES-CLR ZSFG-ERR-PSWD-MAXLEN-TOO-BIG ZSFG-ERR-PSWD-MAXLEN-TOO-SMALL ZSFG-ERR-PSWD-ATTRIB-NEED-HMAC ZSFG-ERR-PSWD-MAXLEN-LESS-MINLEN ZSFG-ERR-PSWD-LONG ZSFG-ERR-COMP-MODE ZSFG-ERR-PSWD-QUAL-NEED-HMAC ZSFG-ERR-PSWD-SPACE-NEED-CMOFF ZSFG-ERR-PSWD-MIN-QUAL...355

9 ZSFG-ERR-PSWD-INVALID-PASS ZSFG-ERR-PSWD-EMBEDDED-SPACE ZSFG-ERR-PSWD-CRIT-FAIL ZSFG-ERR-PSWD-DUPLICATE-TKN ZSFG-ERR-PRIVLGNNONOBJ ZSFG-ERR-AUDEXCLUDE-MAX-EXCEED ZSFG-ERR-AUDEXCLUDE-NEED-BOTH ZSFG-ERR-AUDEXCLUDE-MISMATCH ZSFG-ERR-GROUP-NUMBER-RESTRICT ZSFG-ERR-GROUP-NAME-RESTRICTED ZSFG-ERR-GROUP-NUMBER-RESERVED ZSFG-ERR-GROUP-MEMBER-RESTRICT ZSFG-ERR-CHECK-PROC-MAX-EXCEED ZSFG-ERR-CHECK-PROC-INVALID ZSFG-ERR-DISKOWNCHGPROGNOSET ZSFG-ERR-DISKFILEOWNCHG ZSFG-ERR-SQLMX-OBJ-OWNER ZSFG-ERR-SQLMX-OWNERSHIP-UNKNW ZSFG-ERR-INVALONSQLMP Safeguard Errors Example of Sharing a Binary Description Field Glossary Contents 9

10 About This Document This manual describes the token-oriented programmatic interface for the Safeguard subsystem. This interface is based on the Subsystem Programmatic Interface (SPI). Supported Release Version Updates (RVUs) This manual supports L15.02 and all subsequent L-series RVUs, J06.03 and all subsequent J-series RVUs, H06.08 and all subsequent H-series RVUs, and G06.29 and all subsequent G-series RVUs, until otherwise indicated by its replacement publications. Additionally, all considerations for H-series throughout this manual will hold true for J-series also, unless mentioned otherwise. Intended Audience This manual is intended for: TAL, C, Pascal, COBOL, or TACL programmers writing applications that use the programmatic interface to communicate with the Safeguard subsystem. Security administrators and others who need detailed information about Safeguard programmatic commands. Readers of this manual should be familiar with the system architecture of HPE NonStop servers, the operating system, the Safeguard subsystem, and SPI, as described in the SPI Programming Manual. If you are writing an application, you should also be familiar with the requester-server approach to application programming and the language (TAL, C, Pascal, COBOL, or TACL) you are using to write the application. You should also have a reading knowledge of the HPE Data Definition Language (DDL). New and Changed Information Changes to manual Added J06.21 RVU applicability in the manual. Changes to manual Updated the following sections ADD GROUP Command on page 68 ADD PROTECTIONRECORD Command on page 72 ALTER GROUP Command on page 106 ALTER PROTECTIONRECORD Command on page 109 INFO ALIAS Command on page 164 INFO USER Command on page 188 Error-List Descriptions on page 299 Added the following: LOAD PROTECTIONRECORD command on page 202 ZSFG-ERR-INVALONSQLMP on page 367 Changes to manual Updated the DELETE USER Command on page 160 to introduce CHECK-SQLMX-OWNERSHIP. Updated Error-Handling Notes on page 161 to introduce tokens for SQL/MX. Added ZSFG-ERR-SQLMX-OBJ-OWNER on page 366 and ZSFG-ERR-SQLMX-OWNERSHIP-UNKNW on page About This Document

11 Changes to manual Updated Error Handling Notes section for the following commands by adding error tokens and descriptions: ADD ALIAS Command on page 51 ADD USER Command on page 83 ALTER ALIAS Command on page 94 ALTER USER Command on page 141 Replaced the token name ZCOM-ERR-SEL-CMPR-INV with ZSFG-ERR-SEL-CMPR-INV in the Error Handling Notes section for the following commands: ACTIVATE ALIAS Command on page 43 ACTIVATE USER Command on page 49 DELETE ALIAS Command on page 148 DELETE USER Command on page 160 INFO ALIAS Command on page 164 INFO USER Command on page 188 LISTOBJECTS ALIAS Command on page 195 LISTOBJECTS USER Command on page 197 STATUS ALIAS Command on page 208 STATUS USER Command on page 214 SUSPEND ALIAS Command on page 217 SUSPEND USER Command on page 221 Replaced the token name ZCOM-ERR-ORPHANEDALIAS with ZSFG-ERR-ORPHANEDALIAS in the Error Handling Notes section in DELETE USER Command on page 160. Replaced the token name ZCOM-ERR-LUSER-GUARDIANID with ZSFG-ERR-ALIASGUARDIANID in the Error Handling Notes section in ALTER ALIAS Command on page 94. Changes to manual Updated the section ALTER SUBSYSTEM Command on page 116. Added the token ZSFG-TKN-PROMPT-BEFORE-STOP in Command-Specific Tokens in the Command Buffer on page 119. Updated the section INFO SUBSYSTEM Command on page 182. Updated the error token name ZSFG-ERR-DESC-TEXTDATA-INVALID in the following sections: ADD ALIAS Command on page 51 ADD USER Command on page 83 ALTER ALIAS Command on page 94 ALTER USER Command on page 141 Changes to manual Updated the section ADD EVENT-EXIT-PROCESS (PROC) Command on page 64. Updated the section ALTER EVENT-EXIT-PROCESS (PROC) Command on page 103. Updated the section INFO EVENT-EXIT-PROCESS (PROC) Command on page 171. Added an event message to Safeguard Event Messages on page 232. Added the event message ZSFG-EVT-HELPER-LOST-SMP on page 293. Updated the section Error-List Descriptions on page 299. Added error tokens on the following pages: ZSFG-ERR-DISKOWNCHGPROGNOSET on page 365. ZSFG-ERR-DISKFILEOWNCHG on page 366. Changes to manual 11

12 Related Documentation While using this manual, you might need to refer to some or all of the following manuals: EMS Manual Data Definition Language (DDL) Reference Manual SPI Programming Manual Dynamic System Configuration (DSC) Manual Introduction to Distributed System Management Safeguard Reference Manual Safeguard User's Guide Guardian Procedure Calls Reference Manual Guardian Procedure Errors and Messages Manual Publishing History Part Number Product Version Published Safeguard G07, H05, L01 May Safeguard G07, H05, L01 March Safeguard G07, H05, L01 February Safeguard G07, H05 February Safeguard G07, H05 August Safeguard G07, H05 February Related Documentation

13 Introduction This manual describes the token-oriented programmatic interface to the Safeguard software. The Safeguard software is a group of programs that supplements the security features of the operating system. It is a powerful tool that provides a comprehensive security system using authentication, authorization, and auditing: Authentication: Allows you to verify a user name and password when a user requests access to the system. Authorization: Allows you to check access control lists to determine whether a user has authority to access an object. Auditing: Allows you to record attempts to authenticate users, to access system objects, or to access security records. For more information about the Safeguard software, see the Safeguard User's Guide and the Safeguard Reference Manual. Objects Controlled by Safeguard Objects and subjects controlled by the Safeguard software include: Disk files Devices and subdevices Terminals Users and aliases Volumes and subvolumes Processes and subprocesses Audit pools User groups The Safeguard software also controls various user security requirements, such as access to protected disk files and user authentication attempts. Safeguard Management Functions Safeguard Subsystem Management Commands on page 13 lists the Subsystem Control Point (SCP) ZCOM commands. Table 1: Safeguard Subsystem Management Commands Command (zcom-cmd- ) Object Type (zcom-obj-) Description (SAFECOM command) activate user Thaws user authentication records. alias prot LU Thaws user alias authentication records. Thaws object protection records. Thaws a terminal definition. add user Adds user authentication records. alias Adds user alias authentication records. Table Continued Introduction 13

14 Command (zcom-cmd- ) Object Type (zcom-obj-) Description (SAFECOM command) group prot rmtpassw fileset LU proc Adds group definition records. Adds object protection records. Adds remote passwords. Adds an audit pool. Adds a terminal definition. Adds an event-exit configuration record. alter user Alters user authentication records. alias group prot rmtpassw subsystem fileset LU proc Alters user alias authentication records. Alters group definition records. Alters object protection records. Alters remote passwords. Alters the Safeguard configuration. Alters an audit pool. Alters a terminal definition. Alters an event-exit configuration record. delete user Deletes user authentication records. alias group prot rmtpassw fileset LU proc Deletes user alias authentication records. Deletes group definition records. Deletes object protection records. Deletes remote passwords. Deletes an audit pool. Deletes a terminal definition. Deletes an event-exit configuration record. getversion null Obtains Safeguard version string. info user Retrieves attributes of a user. Table Continued 14 Introduction

15 Command (zcom-cmd- ) Object Type (zcom-obj-) Description (SAFECOM command) alias group prot rmtpassw subsystem fileset LU proc Retrieves attributes of an alias. Retrieves group definition records Retrieves attributes of protection records. Retrieves attributes of remote passwords. Retrieves attributes of the Safeguard subsystem. Retrieves attributes of an audit pool. Retrieves attributes of a terminal definition. Retrieves attributes of an event-exit configuration. listobjects null Lists all object names and types. user alias group prot rmtpassw fileset LU proc Lists users. Lists aliases. Lists groups. Lists object protection records. Lists remote passwords. Lists audit pools. Lists terminal definitions. Lists event-exit configuration records. listopens subsystem Lists all openers of $ZSMP. release fileset Releases an audit pool. status user Obtains information about status of user authentication records. alias prot subsystem Obtains information about status of alias authentication records. Obtains information about status of protection records. Obtains information about status of the Safeguard subsystem. Table Continued Introduction 15

16 Command (zcom-cmd- ) Object Type (zcom-obj-) Description (SAFECOM command) stop subsystem Stops the Safeguard subsystem. suspend user Freezes user authentication records. alias prot LU Freezes user alias authentication records. Freezes object protection records. Freezes a terminal definition. switch fileset Closes the current audit file and opens the next audit file. Safeguard Architecture and Interfaces The Safeguard software consists of a number of processes and security database files. The processes cooperate to manage the contents of the security database, to authenticate users, and to authorize all attempts to access protected objects. These Safeguard components reside on every system on which the Safeguard software is installed: The subject database, which contains a user-authentication record for every user authorized to use the system. The object database, which contains object-authorization records for every disk file, disk volume, disk subvolume, device, subdevice, process, subprocess, and OBJECTTYPE placed under the protection of the Safeguard software. The pattern database, which contains object-authorization records for patterns which control diskfiles, volumes, and subvolumes. No OBJECTTYPE is placed in the database. The Security Monitor (SMON), which authorizes all attempts to access protected objects. A separate SMON process runs in each CPU in a system protected by the Safeguard software. Each SMON process is named in the following format:$zsnn, where nn = CPU number. The Security Manager Process (SMP), which is responsible for managing all changes to the subject and object databases and for authenticating users. This process is named $ZSMP. The Safeguard command interpreter (SAFECOM), which allows you to communicate with the Safeguard software. The SAFECOM command interpreter accepts commands in three different modes: interactive, execute-andquit, and batch. Interactive mode allows you to enter any number of commands and verify the results before proceeding. Execute-and-quit mode allows you to execute commands one at a time. It is most useful for entering one or two commands. Batch mode allows you to execute a series of SAFECOM commands stored in a disk file. SAFECOM allows users to communicate with the Safeguard software. This manual describes the Subsystem Programmatic Interface (SPI) for the Safeguard software. SPI is token-based, or message-based, and allows programs to communicate with the Safeguard software. 16 Safeguard Architecture and Interfaces

17 Management Programming for the Safeguard Subsystem As the previous section describes, there are interactive and programmatic interfaces to the Safeguard subsystem. In some situations, the programmatic interfaces are preferable to the interactive interfaces: It is efficient to transfer as many routine network-management tasks as possible to programs running on the network itself, freeing operators and other network-management personnel to do other work. Information obtained through the programmatic interfaces can be used directly by a management application to control its actions, produce reports, and so forth. A management application that uses the control-and-inquiry and event-management interfaces can perform tasks that once required the use of two or three interactive interfaces. Such an application can also communicate with multiple subsystems. In addition, writing your own management applications allows you to tailor them to the needs and configuration of your network. For example, you could write a management application that uses the control-and-inquiry interface that determines the number of errors occurring on all lines in a network and stops lines that have too many errors. A management application could monitor the events occurring in the subsystem and react to the notification that a line is going down by starting another line. Management applications can communicate with other subsystems as well as with the Safeguard subsystem. For example, you could write an application that uses a given subsystem to bring up a line to a remote system and that uses the PATHWAY subsystem to restart terminals on the remote system. A management application uses the programmatic control-and-inquiry interface to the Safeguard subsystem by sending commands to and receiving responses from $ZSMP. Management applications use the Event Management Service (EMS) to retrieve event messages generated by the Safeguard subsystem by sending commands to and receiving responses from an EMS distributor process. Communicating With the Safeguard Subsystem Control-and-inquiry communication with the Safeguard subsystem is accomplished through $ZSMP, as Figure 1: Safeguard Management Programming Interface on page 18 shows. A management application calls SPI procedures to build a message and then sends the message to the Safeguard manager process, $ZSMP. These basic tasks are involved in communicating with the Safeguard subsystem: 1. Establishing communication with $ZSMP 2. Calling SPI procedures to build the desired message 3. Sending the message 4. Receiving the response to the message 5. Checking for error codes and handling any errors 6. Decoding the response 7. Taking appropriate action and returning to Step 2, if necessary 8. Terminating communication with $ZSMP If the management application also communicates with a human operator, the preceding scenario would also incorporate that interchange. For more information regarding communicating with the Safeguard subsystem, see the SPI Programming Manual and the SPI Common Extensions Manual. Management Programming for the Safeguard Subsystem 17

18 Figure 1: Safeguard Management Programming Interface Event Messages In addition to sending commands and receiving responses, a management application can obtain notification of events that occur in the Safeguard subsystem. This notification is in the form of event messages issued by the Safeguard subsystem. An event message describes an event such as a hardware or software error or the completion of an operation. An application can monitor these event messages to handle unexpected situations or to keep track of the current status of the system and the network. Event Management on page 224 describes the event messages that the Safeguard subsystem can be issue. For more information about obtaining event messages, see the EMS Manual. Commands That a Management Application Can Issue Safeguard Programmatic Commands on page 18 lists and briefly describes the commands that a management application can send to the Safeguard subsystem. For more information, see Commands on page 41. Table 2: Safeguard Programmatic Commands Command ACTIVATE ADD ALTER DELETE GETVERSION Action Thaws an object Defines an object to the subsystem Changes the values of an object's attributes Removes an object definition from the subsystem Returns an object's version information Table Continued 18 Event Messages

19 Command INFO LISTOBJECTS LISTOPENS NEXTFILE RELEASE START STATUS STOP SUSPEND Action Returns an object's current attribute values Returns the object name and object type of designated objects Returns the process IDs of an object's openers Closes the active audit file and opens the next in sequence Marks the specified audit files in the active audit trail as reusable Starts a terminal Returns the current status of an object Stops the operation of an object Freezes an object Management Programming for the Safeguard Subsystem 19

20 Communicating With the Subsystem This section describes how an application communicates with the Safeguard subsystem through the Subsystem Control Point (SCP) or directly with the Safeguard manager process $ZSMP. The Safeguard subsystem does not receive event messages, but it does generate them. Event Management on page 224 discusses event messages. For more information about the SCP, see the SPI Common Extensions Manual. Startup Considerations $ZSMP is the Safeguard process to which you send commands for managing the Safeguard software and from which you receive responses. The local super ID starts $ZSMP with a command interpreter RUN command. NOTE: The SMP process must be named as $ZSMP. For example, if the Safeguard object files were stored on the $SYSTEM.SYS05 subvolume, the local super ID could start $ZSMP with the following TACL RUN command: 2>RUN $SYSTEM.SYS05.OSMP /NAME $ZSMP, NOWAIT,CPU 3/4 A backup SMP process must be specified in the RUN command. Otherwise the SMP runs with no backup. When $ZSMP is running, it automatically creates these files, if it does not already exist: $SYSTEM.SAFE.GUARD $SYSTEM.SAFE.OTHER $SYSTEM.SAFE.CONFIG $SYSTEM.SAFE.CONFIGP 1 $SYSTEM.SAFE.CONFIGA Contains object-authorization records for all disk objects (volumes, subvolumes, and disk files) on $SYSTEM. Contains object-authorization records for all local system objects other than disks (devices, subdevices, processes, subprocesses, and OBJECTTYPEs). Contains the attributes that determine the Safeguard configuration. Contains password configuration information. Contains audit configuration information. 1 Supported only on systems running G06.29 and later G-series RVUs and H06.06 and later H-series RVUs. $ZSMP also starts the Security Monitor (SMON) processes. It uses the convention $ZSnn for the SMON process names, where nn is the CPU number. The SMP starts all the SMON processes with a priority of 199. The Safeguard software also creates audit files when they are needed. NOTE: The Safeguard SPI allows for, but does not require, the use of the Subsystem Control Point (SCP) process as the gateway to the programmatic interface. Thus, Safeguard SPI follows SCP implementation standards and uses the SCP ZCOM enumerated values for commands, object types, and some common errors. 20 Communicating With the Subsystem

21 Definition Files A Safeguard management application program must refer to several definition files. These files are defined for SPI, the Event Management System (EMS), the Subsystem Control Point (SCP), data-communications subsystems, and the Safeguard subsystem. The standard data types, token codes, token maps, token structures, constants, values, and other definitions used with SPI are contained in these files. HPE provides the SPI standard definitions in files of source declarations in DDL and in the programming languages that support Distributed Systems Management (DSM): TAL, C, Pascal, COBOL, and TACL. They consist of six definition files one in each language plus the DDL definition file. Similarly, each subsystem or management process (including SCP) supports a programmatic command interface based on SPI that reports events through EMS, or that defines SPI error lists, also provides six definition files one per language plus the DDL definition file. For SPI and for each subsystem, the files for all the programming languages are generated by the DDL compiler from the DDL file. To use definitions from a particular source, your Safeguard management application program must load the definition file associated with the source command in the appropriate programming language. The definitions in a TAL, C, Pascal, or COBOL definition file are grouped into sections, so that only definitions that are needed are included in the application. For TACL, the entire definition file must be used. For more information about, how definition files are accessed by application, see the SPI Programming Manual. Writers of Safeguard management applications that use SPI must use the programming language version of each definition file: The ZSPI file, which contains the standard SPI definitions. The ZEMS file, which contains the standard EMS definitions (if your application retrieves event messages). The ZCOM file, which contains the standard data communications definitions. The ZSFG file, which contains definitions for the Safeguard software. (The ZSFG files may contain some definitions that are currently not implemented.) The ZCMK file, which contains some common definitions. The definition file for any other subsystems with which your Safeguard management application communicates. Other definition files used by a particular subsystem if your application needs them. An example of this type of file would be one defining tokens in pass-through error lists if the application examines these error lists. Include these definition files in your program using a mechanism appropriate to the programming language:? SOURCE compiler directives in TAL, COPY statements in COBOL, or LOAD commands in TACL. Language SPI Definitions EMS Definitions Data CommunicationsD efinitions TAL ZSPIDEF.ZSPITAL ZSPIDEF.ZEMSTAL ZSPIDEF.ZCOMTA L Safeguard Definitions ZSPIDEF.ZSFGTAL C ZSPIDEF.ZSPIC ZSPIDEF.ZEMSC ZSPIDEF.ZCOMC ZSPIDEF.ZSFGC Pascal ZSPIDEF.ZSPIPAS ZSPIDEF.ZEMSPA S ZSPIDEF.ZCOMPA S ZSPIDEF.ZSFGPAS Table Continued Definition Files 21

22 Language SPI Definitions EMS Definitions Data CommunicationsD efinitions Safeguard Definitions COBOL ZSPIDEF.ZSPICOB ZSPIDEF.ZEMSCO B ZSPIDEF.ZCOMCO B ZSPIDEF.ZSFGCO B TACL ZSPIDEF.ZSPITAC L ZSPIDEF.ZEMSTA CL ZSPIDEF.ZCOMTA CL ZSPIDEF.ZSFGTAC L Processes Addressed You can use two processes to communicate with the Safeguard SPI: Via SCP: OPEN $ZNET.#ZSPI Directly: OPEN $ZSMP.#ZSPI In the first case, you address SPI commands to the SCP. In the second case, you communicate directly with the SMP. 22 Processes Addressed

23 Elements of SPI Messages You can use the Subsystem Programmatic Interface (SPI) for sending commands to and decoding responses from the Safeguard subsystem and for obtaining event messages issued by the Safeguard subsystem (through EMS.) For the procedures used by an application to perform these tasks, see the SPI Programming Manual. For a description of using SPI messages to communicate with the Safeguard subsystem through SCP, see the SPI Common Extensions Manual. The commands, responses, and event messages that are sent to and received from the Safeguard subsystem are made up of special codes called tokens. Each token contains its own identification and specific information, such as the command number of a command or one element of an event message. Tokens can be single values or structures consisting of several values. Some tokens, called header tokens, are present in every command, response, or event message. This manual does not give a complete explanation of tokens. It provides subsystem-specific information about the tokens used to communicate with the Safeguard subsystem. For more information about tokens, see the SPI Programming Manual. For information about tokens common to all data communications subsystems, see the SPI Common Extensions Manual. This manual uses the Data Definition Language (DDL) to describe all tokens. For more information about DDL, see the SPI Programming Manual. Naming Guidelines for Applications By convention, HPE uses names beginning with the letter Z for all definitions and all component fields of structures in its definition files. To avoid conflicts with names defined by HPE, do not begin any of your own names with an uppercase or lowercase Z. Common Syntax Elements for Data Communications The rest of this section contains subsystem-specific information about elements of commands, responses, and event messages. For more information, see the SPI Common Extensions Manual. Command Numbers In the Safeguard subsystem, command numbers are represented by symbolic names of the form ZCOM- CMD-name, where name represents the value that identifies the command. ZSPI-TKN-COMMAND is a header token whose value is set to ZCOM-CMD-name using SSINIT. The Safeguard subsystem supports the following commands: ACTIVATE GETVERSION RELEASE SWITCH ADD INFO SELECT SUSPEND ALTER LISTOBJECTS STATUS DELETE LISTOPENS STOP For more information about these commands, see Commands on page 41. Object Types Every header also contains a token ZSPI-TKN-object-type, whose value is set to ZCOM-OBJ-objecttype using SSINIT. Elements of SPI Messages 23

24 In the Safeguard subsystem, object types are represented by symbolic names of the form ZCOM-OBJtype, where type identifies the object type. The Safeguard subsystem supports the following object types: SUBSYSTEM USER ALIAS GROUP REMOTEPASSWORD PROTECTIONRECORD NULL FILESET PROCESS LU The kinds of objects the Safeguard subsystem manages are described in Introduction on page 13. For the object types the Safeguard subsystem supports, see Common Definitions on page 31. Object Names Users Most Safeguard commands and responses contain object-name tokens that, combined with the object-type information, designate the objects affected by the command. The Safeguard subsystem is an unnamed object. In the management-programming interface to the Safeguard subsystem, object names have one of four formats: Users Remote passwords Protection records Wild cards User objects are identified in one of three ways: By their group name.member name By their group number,member number (ASCII character string) By their user ID in integer form. The integer user ID must be prefixed with the special delimiter two byte character string "==". The object name length is four bytes. TAL examples:! the first word of the object name is the length INT.objectName[ 0:9 ];! user object name in the form <group>.<user> object name[1] ':=' "SOFTWARE.GREG"; object name[0] := 13;! user object name in the form <group number>, <member number> 24 Object Names

25 object name[1] ':=' "1,174"; object name[0] := 5; Remote Passwords Remote passwords are identified by a user name or alias concatenated with a system name. Examples of remote passwords are SOFTWARE.GREG\FOXII and ALIAS:GregJ\FOXII. (For more information, see ADD REMOTEPASSWORD Command on page 79.) Protection Records Protection records are identified by a dollar sign followed by the name of the object they are protecting. These objects can be volumes, subvolumes, disk files, processes, subprocesses, devices, subdevices, or the special object type. Some examples of protection records are $RELEASE, $DATA.TNDM.PAYROLL, and $SNAX.#LU1. When an object is defined to the operating system, the Safeguard software can determine the type of protection record. When the object has not been defined to the operating system, you need to specify the type of protection record by prefixing the protection record name with an object type descriptor: VOLUME SUBVOLUME DISKFILE DISKFILE-PATTERN PROCESS SUBPROCESS DEVICE SUBDEVICE OBJECTTYPE (used for objecttypes and security groups) SAVEDDISKPATTERN (used for SAVED-DISKFILE-PATTERN objecttype) Some examples of names using the object type descriptor are DEVICE.$TAPE, PROCESS.$NULL, SUBDEVICE.$SNAX.#LU1, and SAVEDDISKPATTERN.$TAPE*.TEST*.*. You can use the object type descriptor with wild-card names. Some examples would be DISKFILE.*, OBJECTTYPE.*, and PROCESS.*. Using these examples, you can direct a command to a specific type of protection record; for example ALTER PROCESS.* or INFO DISKFILE.*. If you want SPI commands to be exclusive to diskfile patterns, you must use the object type descriptor. If the object name specified does not have a type descriptor, and is in the diskfile format, and is wild carded, then both diskfiles and diskfile patterns that match the object name will be operated on. To illustrate, these protection records exist on a system: $DATA2.JATER.TEST (Diskfile) $DATA2.J*.T* (Diskfile Pattern) $DATA1.JATER.TEST (Diskfile) $DATA1.JA???.TEST (Diskfile Pattern) $DATA.JATER.TEST (Diskfile) $DATA.JATE?.T* (Diskfile Pattern) The INFO PROTECTIONRECORD commands return the following records: INFO $DATA.JATER.TEST Remote Passwords 25

26 returns the Diskfile $DATA.JATER.TEST. INFO DISKFILE.$DATA.JATER.TEST returns the Diskfile $DATA.JATER.TEST. INFO *$DATA*.*.T* returns the three diskfile and three diskfile patterns: $DATA2.JATER.TEST $DATA2.J*.T* $DATA1.JATER.TEST $DATA1.JA???.TEST $DATA.JATER.TEST $DATA.JATE?.T* INFO DISKFILE.*$DATA*.*.T* returns the three diskfiles: DISKFILE.$DATA2.JATER.TEST DISKFILE.$DATA1.JATER.TEST DISKFILE.$DATA.JATER.TEST INFO DISKFILE-PATTERN.$DATA.JATE?.T* returns the diskfile pattern $DATA.JATE?.T*. INFO DISKFILE-PATTERN.*$DATA*.J*.T* (with the ZCOM-TKN-SUB token specified to ZCOM-VAL-SUB-ALL)returns the three diskfile patterns: $DATA2.J*.T* $DATA1.JA???.TEST $DATA.JATE?.T* For more information on diskfile patterns, see the Safeguard User s Guide. Wild Cards Diskfile-Pattern Filenames The asterisk (*) and question mark (?) are treated as characters in the filename. Diskfile patterns must contain at least one wild-card character in either the subvolume or filename element of the filename. Wild cards are not allowed in the volume element of an exact match (non-search) diskfile-pattern filename. Examples of valid and invalid diskfile-pattern names: DISKFILE-PATTERN.$SYSTEM.*.* DISKFILE-PATTERN. $DATA.PROJECT.FILE DISKFILE-PATTERN.$DATA*.B*.C?? Valid diskfile-pattern filename Invalid diskfile-pattern filename (no wildcards in subvolume or filename) Invalid diskfile-pattern filename (wildcard in volume) Using Wild Cards as Search Characters An asterisk (*) matches zero or more characters. A question mark (?) matches one character. Any other character matches itself. However, case differences are ignored except for group and alias object names. 26 Wild Cards

27 Wild cards can be used in names in all commands except ADD commands. An exception is ADD commands for diskfile patterns must contain at least one wild-card character in either the subvolume or filename element of the filename, but the characters will be treated as exact characters, not search characters. The ZCOM-TKN-SUB must be used to indicate wild cards in a diskfile-pattern filename are to be treated as search characters. This token cannot be used with the ADD command. A "*" must be used to begin filenames that are wild carded in the volume element in order for the command to operate across all volumes that match the filename. For example: 1. INFO *$DATA*.*.T* returns the three diskfile and three diskfile patterns: $DATA2.JATER.TEST $DATA2.J*.T* $DATA1.JATER.TEST $DATA1.JA???.TEST $DATA.JATER.TEST $DATA.JATE?.T* 2. INFO $DATA*.*.T* returns only two of the six protection records that you might expect (There is no "*" specified prior to the filename.): Event Numbers $DATA.JATER.TEST $DATA.JATE?.T* Event numbers for event messages issued by the Safeguard subsystem are represented by symbolic names in the form ZSFG-EVT-name, where name identifies the event. For more information about the Safeguard event numbers and their associated event messages, see Event Management on page 224. Subjects of Event Messages The Safeguard subsystem reports events for the following objects: SUBSYSTEM PROCESS (event-exit process) NULL FILESET LU For Safeguard event numbers and their associated event messages, see Event Management on page 224. Other Tokens The Safeguard subsystem uses other tokens as command parameters, results in responses, and elements of event messages and error lists. Simple Tokens Simple tokens tokens whose values are single fields or fixed structures are identified by token codes. The token codes for the simple tokens used by the Safeguard subsystem are represented by symbolic names in the form ZSFG-TKN-name, where name identifies the token code. For example, the token code ZSFG-TKN- PASSWORD identifies a simple token that contains a password. Token Types The token types used by the Safeguard subsystem are represented by symbolic names in the form ZSPI- TYP-name, where name identifies the token type. For example, the token type ZSPI-TYP-CHAR8 Event Numbers 27

28 represents a string of eight ASCII characters. The Safeguard subsystem does not define any private token types. That is, no token types have names of the form ZSFG-TYP-name. Throughout this manual, when a simple token is described, its token type is given. Predefined Value Names The predefined values used by the Safeguard subsystem are represented by symbolic names in the form ZSFG-VAL-name, where name identifies the predefined value. For example, the predefined value ZSFG- VAL-BUFLEN represents the recommended buffer length. Extensible Structured Tokens Field Types Extensible structured tokens tokens whose values are extensible structures are identified by token maps. The token maps for the extensible structured tokens used by the Safeguard subsystem are represented by symbolic names in the form ZSFG-MAP-name, where name identifies the token map. For example, the token map ZSFG-MAP-ACCESS identifies an extensible structured token that contains an access control list entry. The ADD and ALTER commands contain extensible structured tokens. The responses to the Safeguard commands INFO and STATUS can also contain extensible structured tokens. Extensible structured tokens do not appear in any event message or error list issued by the Safeguard subsystem. Throughout this manual, when an extensible structured token is described, its DDL definition, including the definitions and types of all fields, is also given. All the field types used by the Safeguard subsystem are SPI standard field types, represented by symbolic names in the form ZSPI-DDL-name, where name identifies the field type. For example, the field type ZSPI- DDL-BOOLEAN represents the Boolean data type. Throughout this manual, when a field is described, its field type is given. Constructs Involving Multiple Tokens The Safeguard subsystem supports data lists and error lists as described in the SPI Programming Manual. Components of a Command For each Safeguard command and the tokens it contains, see Commands on page 41. For considerations about Safeguard command buffers, see SPI Programming Considerations on page 29, and the SPI Common Extensions Manual. Components of a Response For each Safeguard response and the tokens it contains, see Commands on page 41. For considerations about retrieving and decoding Safeguard response buffers, see SPI Programming Considerations on page 29. In responses to Safeguard commands that operate on objects, a response record always contains response information for the operation of the command on a single object. This topic is also discussed in the SPI Common Extensions Manual. Components of an Event Message For Safeguard event messages, the tokens each contains, and considerations for retrieving and decoding event messages, see Event Management on page 224. This topic is also discussed in the EMS Manual. 28 Predefined Value Names

29 SPI Programming Considerations The SPI Common Extensions Manual discusses general programming considerations for writing applications that use the Subsystem Programmatic Interface (SPI) to communicate with subsystems like the Safeguard subsystem. This section discusses SPI programming considerations specific to the Safeguard subsystem. Building the Command Buffer These programming considerations apply when an application builds the command buffer for a Safeguard command. The minimum buffer length in bytes for a Safeguard command is a predefined value with the symbolic name ZSFG-VAL-BUFLEN. The maximum buffer length in bytes for a Safeguard command is a predefined value with the symbolic name ZSFG-VAL-MAXBUFLEN. The Safeguard subsystem supports multiple commands in a single request message. In addition, most of the Safeguard commands accept multiple object names in one command, so one command can affect a number of objects. The maximum number of object names depends on the size of the command buffer. All the objects named in one command must be the same object type. The Safeguard subsystem does not support continuation of a command across multiple messages, but it does support the special case of receiving multiple reply messages using the context token, as described in the SPI Programming Manual. The command buffers for all Safeguard commands can contain extensible structured tokens. An extensible structured token appearing in a command should always be initialized by the SPI procedure SSNULL to insure that every field of the token is initialized to its null value. This action is important because an operation is performed if a field contains a value other than its null value. For example, in the ALTER USER command, if an extensible structured token contains a value other than its null value, that value is assigned to the attribute corresponding to that field. Using SSNULL is important even when every field of an extensible structured token will have a value assigned to it, so that the application continues to run even if it is compiled with new definition files that add new fields to the token. Only those tokens can appear more than once in a Safeguard command: ZSFG-MAP-ACCESS ZSFG-MAP-DEFAULT-ACCESS ZSFG-MAP-REMOVE-ACCESS ZSFG-MAP-REMOVE-DF-ACCESS ZSFG-MAP-REMOVE-OWNERS ZSFG-MAP-OWNERLIST ZSFG-TKN-AUDITFILENUMBER ZSFG-TKN-MEMBERNAME ZSFG-TKN-REMOVE-MEMBERNAME If any of the other tokens in a command appear more than once, the Safeguard subsystem returns the error ZCOM-ERR-TKN-DUP. Discontinuing a Command in Progress For a discussion of general programming considerations for discontinuing a command in progress, see the SPI Common Extensions Manual. The Safeguard subsystem supports the use of the token ZSPI-TKN-ALLOW-TYPE, which allows an application to specify, in a command operating on multiple objects, whether the Safeguard subsystem should continue immediately to the next object if it failed on the previous one. If no value is specified for this token, SPI Programming Considerations 29