Tivoli SecureWay Security Manager

Transcription

1 Tivoli SecureWay Security Manager Programmer s Guide for TACF Version 3.7

2

3 Tivoli SecureWay Security Manager Programmer s Guide for TACF Version 3.7

4 Tivoli SecureWay Security Management Programmer s Guide for TACF (November 2000) Copyright Notice Copyright IBM Corporation 2000 All rights reserved. May only be used pursuant to a Tivoli Systems Software License Agreement, an IBM Software License Agreement, or Addendum for Tivoli Products to IBM Customer or License Agreement. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without prior written permission of IBM Corporation. IBM Corporation grants you limited permission to make hardcopy or other reproductions of any machine-readable documentation for your own use, provided that each such reproduction shall carry the IBM Corporation copyright notice. No other rights under copyright are granted without prior written permission of IBM Corporation. The document is not intended for production and is furnished as is without warranty of any kind. All warranties on this document are hereby disclaimed, including the warranties of merchantability and fitness for a particular purpose. U.S. Government Users Restricted Rights-Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corporation. Trademarks IBM, the IBM logo, Tivoli, the Tivoli logo, AIX, AS/400, Cross-Site, NetView, OS/2, OS/390, OS/400, Policy Director, RACF, RS/6000, S/390, SecureWay, Tivoli Certified, Tivoli Enterprise, Tivoli Ready, and TME are trademarks or registered trademarks of International Business Machines Corporation or Tivoli Systems Inc. in the United States, other countries, or both. Lotus is a registered trademark of Lotus Development Corporation. Microsoft, Windows, Windows NT, Windows 2000, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Novell, NetWare, NetWare Directory Services, and NDS are trademarks of Novell, Inc. TACF Copyright by MEMCO Software Ltd., U.S. patent pending. All rights reserved. Other company, product, and service names may be trademarks or service marks of others. Notices References in this publication to Tivoli Systems or IBM products, programs, or services do not imply that they will be available in all countries in which Tivoli Systems or IBM operates. Any reference to these products, programs, or services is not intended to imply that only Tivoli Systems or IBM products, programs, or services can be used. Subject to valid intellectual property or other legally protectable right of Tivoli Systems or IBM, any functionally equivalent product, program, or service can be used instead of the referenced product, program, or service. The evaluation and verification of operation in conjunction with other products, except those expressly designated by Tivoli Systems or IBM, are the responsibility of the user. Tivoli Systems or IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, New York , U.S.A.

5 Contents Preface... xi Who Should Read This Guide... xi Prerequisite and Related Documents... xi What This Guide Contains... xi Conventions Used in This Guide... xii Contacting Customer Support... xiii Platform-specific Information... xiv Other Info for Your Product.... xv Accessing Publications Online... xvi Ordering Publications... xvii Providing Feedback about Publications... xvii Contacting Customer Support... xvii Part I. -Authorizations API... 1 Chapter 1. Authorizations API Guide... 3 Checking the Access Authority for a User Process... 5 Example... 5 Files... 6 Application Servers... 6 Example... 7 Files... 8 Access Authorization User Authentication Managing Error Messages Compiling and Linking with the TACF Library Tivoli SecureWay Security Manager Programmer s Guide for TACF iii

6 Compiling an Application Linking Your Application with the TACF Authorization API Library 10 Chapter 2. Authorizations API Reference SEOSROUTE_ParseApiError SEOSROUTE_RequestAuth SEOSROUTE_VerifyCreate SEOSROUTE_VerifyDelete Part II. -Exits API Chapter 3. Exits API Guide Creating a New Exit Function TACF Events Events Linked to seosd Events linked to sepass User Information Compiling and Linking with the TACF api_authx Library Compiling an Application Linking Your Application with TACF System Design and Limits Modular Design Configuration Files System Calls Error Codes Return Codes Exits API Examples TACF Daemon Exits Password Utilities Exits iv Version 3.7

7 Chapter 4. Exits API Reference General Functions Database Interface Functions Shared Library Functions authxapi_registerexitfunction authxapi_unregisterexitfunction authxapi_isthereexitfunction authxapi_getobjectproperty authxapi_getobjectlistvalue authxapi_freelistvalues authxapi_getuserinfo Part III. -LogRoute API Chapter 5. LogRoute API Guide Customizing selogrd Predefined LogRoute API Functions Compiling and Linking with the TACF LogRoute Library Format of the Log File Example Notification Audit Log Records Chapter 6. LogRoute API Reference <driver>_register <driver>_unregister <driver>_registerdestination <driver>_unregisterdestination lograpi_interpretrecord Tivoli SecureWay Security Manager Programmer s Guide for TACF v

8 lograpi_registertargettype lograpi_unregistertargettype lograpi_makestringmessage LogrApiSenseFunc LogrApiSendFunc LogrApiFreeFunc servlog_isthereexit servlog_registerexit servlog_unregisterexit Part IV. -Administration API Chapter 7. Administration API Guide How the TACF Database Is Organized Database Layout Class Description File Properties Description File Objects Description File Properties Values File Lists in the TACF Database Connections of Users to Groups Connections of Resources to Resource Groups Access Control List (ACL) Entries Understanding ACEE Scope Limitations of the API Conventions Header Files Libraries vi Version 3.7

9 Compiling and Linking with the seadmapi Programming Notes Chapter 8. Administration API Reference Class Operations Console Operations Log Files Interface Miscellaneous Operations Object Operations Property Operations Query Operations Value Operations seadmapi_classgetequal seadmapi_classgetfirst seadmapi_classgetnext 117 seadmapi_getacee seadmapi_freeaceememory seadmapi_getmessage seadmapi_init seadmapi_isseossyscallloaded seadmapi_propgetequal seadmapi_propgetfirstinclass seadmapi_propgetnextinclass seadmapi_objgetequal seadmapi_objgetfirstinclass seadmapi_objgetnextinclass seadmapi_objgetgreaterequal seadmapi_objinclasslist seadmapi_freeobjlist seadmapi_fetchlistpropval seadmapi_fetchsinglepropval seadmapi_freelistpropval seadmapi_setsinglepropval seadmapi_killpdflist seadmapi_makepdflist Tivoli SecureWay Security Manager Programmer s Guide for TACF vii

10 seadmapi_getentity seadmapi_getexentity seadmapi_initentityruler seadmapi_killentitymem seadmapi_killexentitymem seadmapi_getgraceinfo seadmapi_oidtoname seadmapi_whoami seadmapi_getobjtype seadmapi_sendauditrecord seadmapi_sendstartupaudit seadmapi_sendshutdownaudit seadmapi_senduseraudit seadmapi_sendloginaudit seadmapi_sendgenraudit seadmapi_sendwatchdogaudit seadmapi_sendinetaudit seadmapi_sendadminaudit seadmapi_senderrorlog seadmapi_processcontrol seadmapi_constraceclear seadmapi_constracedisable seadmapi_constraceenable seadmapi_constracegetstatus seadmapi_constracetoggle seadmapi_consuidlogindisable seadmapi_consuidloginenable seadmapi_consuidlogingetstatus seadmapi_consalllogindisable seadmapi_consallloginenable seadmapi_consalllogingetstatus seadmapi_consruntimestatisticsget seadmapi_consmessagesend seadmapi_consshutdown seadmapi_reloadini seadmapi_whois sepass_replacepassword Chapter 9. Structures and Data Types Introduction viii Version 3.7

11 API_AUTH_RES Structure CLIENT_ACEE Structure LOGRAPI_FUNCS Structure LOGRECHDR Structure LOGRECORD Structure See Also PFSEOSEXITFUNC Data Type SEADMAPI_RTSTAT Structure SEGRACE_RES Structure SEOS_ACCESS Structure See Also SEOS_ACCS Data Type SEOS_ACL Structure SEOS_AUDITADMIN Structure SEOS_AUDITDOWN Structure SEOS_AUDITGENR Structure SEOS_AUDITINWARN Structure SEOS_AUDITLOGIN Structure SEOS_AUDITSTART Structure See Also SEOS_AUDITUSER Structure SEOS_AUDITWDWARN Structure SEOS_CID Data Type SEOS_EXITGENR Structure SEOS_EXITINET Structure SEOS_EXITLOGIN Structure SEOS_EXITPASS Structure Tivoli SecureWay Security Manager Programmer s Guide for TACF ix

12 SEOS_EXITRES Structure SEOS_GCONN Structure SEOS_OID Data Type SEOS_PACL Structure SEOS_PID Data Type SEOS_REQ_ERRORDESCP Structure SEOS_ROUTENTRY Structure SEOS_X_ACL Structure SEOS_X_GCONN Structure SEOS_X_OID Data Type SEOS_X_PACL Structure SEOSDB_CDF Structure SEOSDB_ENTDAT Structure SEOSDB_ODF Structure SEOSDB_PDF Structure Part V. Appendixes Index x Version 3.7

13 Preface Who Should Read This Guide Developers, administrators, and end users all can profit when the Tivoli Access Control Facility (TACF) APIs are effectively used: For developers, the APIs supply a simple, portable interface to TACF - a security package that provides robust security for their applications. For system administrators, the APIs supply a single security interface for both applications and the operating system. For end users, the APIs supply additional protection for their data. Note: Users of this guide should have some knowledge of the UNIX operating system and basic security principals. Prerequisite and Related Documents The following books are a prerequisite for this guide: Tivoli Security Management Release Notes Tivoli Security Management User s Guide Tivoli Security Management Reference Manual for TACF What This Guide Contains This guide contains the following parts: Part I: Authorizations API enables client applications request authorization for predefined or site-defined abstract resource classes using the authorization and auditing mechanisms provided by TACF. This API also includes the Authentication API. Part II: Exits API enables you to customize the TACF authorization mechanisms by complementing TACF authorization Tivoli SecureWay Security Manager Programmer s Guide for TACF xi

14 routines with your own authorization routines. You can also add a special notification function to the TACF daemon activities. For example, this API can be used to add site-specific requests for password quality verification in TACF. Part III: LogRoute API enables you to add your own alerts to the standard TACF audit log functions. You can also use the logroute daemon to add a guaranteed delivery of audit data or third party alert systems to other programs. Part IV: Administration API enables you to extract information from the TACF database. This API also permits applications to perform administrative tasks such as shutting down seosd - the TACF daemon - or to modify the ability to perform concurrent logins and so on. Sample programs are provided. Additional examples can be found in the apisamples subdirectory of the directory in which TACF is installed - usually /usr/seos. Each part includes Guide and Reference chapters. Guide chapters provide examples of the API and instructions on how to use it. Reference chapters provide tables listing API functions by category at the beginning of the chapter, followed by a detailed reference for each function. The last chapter of the book contains the structures and data types used by the variables of the API functions. Conventions Used in This Guide The guide uses several typeface conventions for special terms and actions. These conventions have the following meaning: Bold Italics Commands, keywords, file names, authorization roles, URLs, or other information that you must use literally appear like this, in bold. Names of windows, dialogs, and other controls also appear like this, inbold. Variables and values that you must provide appear xii Version 3.7

15 Monospace like this, in italics. Words and phrases that are emphasized also appear like this, in italics. Code examples, output, and system messages appear like this, in a monospace font. This guide uses the UNIX convention for specifying environment variables and for directory notation. When using the Windows NT command line, replace $variable with %variable% for environment variables and replace each forward slash (/) with a backslash (\) in directory paths. Note: When using the bash shell on a Windows NT system, you can use the UNIX conventions. Contacting Customer Support For support inside the United States, for this or any Tivoli product, contact Tivoli Customer Support in one of the following ways: Send to support@tivoli.com Call TIVOLI8 Navigate our Web site at For support outside the United States, refer to your Customer Support Handbook for phone numbers in your country. The Customer Support Handbook is available online at When you contact Tivoli Customer Support, be prepared to provide identification information for your company so that support personnel can assist you more readily. We are very interested in hearing from you about your experience with Tivoli products and documentation. We welcome your suggestions for improvements. If you have comments or suggestions about this documentation, please send to pubs@tivoli.com. Tivoli SecureWay Security Manager Programmer s Guide for TACF xiii

16 Platform-specific Information Attention: The table in this section is an example of platform-specific information. Modify this table or create your own here. The following table identifies the supported platform versions known at the time of publication. For more detailed and up-to-date information, please see the release notes. Platform AIX 4.x AS/400 Digital UNIX DG/UX HP-UX NCR NetWare OS/2 Supported Versions Managed Node, Endpoint: IBM RS/6000 series running AIX, Versions 4.1, 4.2, and 4.3 Endpoint: V3R2, V3R7, V4R1, and V4R2 Managed Node, Endpoint: Versions 4.0a and 4.0d. Endpoint: Versions 4.11 and 4.20 on the ix86 platform Managed Node, Endpoint: HP9000/700 and 800 series running HP-UX, Versions 10.01, 10.10, and Managed Node, Endpoint: NCR 3000 series running NCR UNIX SVR4 MP-RAS and PC Agent, Endpoint: IBM-compatible PCs 486 or higher running Novell NetWare, Versions 3.11, 3.12, 4.01, 4.1, and 4.11 TME 10 Desktop for Windows, PC Agent, Endpoint: IBM-compatible PCs 486 or higher running IBM OS/2, Versions 2.0, 2.1,Warp 3.0, and Warp 4.0 with Win-OS/2 xiv Version 3.7

17 Platform Pyramid Sequent SCO SGI Solaris Solaris Intel SunOS Windows Windows NT Supported Versions Endpoint: Pyramid MIServer-ES, Version 5.4MN Managed Node, Endpoint: Sequent DYNIX/ptx, Releases and Managed Node, Endpoint: SCO UnixWare 7, SCO UnixWare Versions and Managed Node, Endpoint: SGI IRIX, Versions 6.2 and 6.4 Managed Node, Endpoint: Sun SPARC series running Solaris, Versions 2.4, 2.5, 2.5.1, and 2.6 Managed Node, Endpoint: Solaris2-ix86, Versions and 2.6 Managed Node, Endpoint: Sun SPARC series running SunOS, Versions and TME 10 Desktop for Windows, PC Agent, Endpoint: IBM-compatible PCs 486 or higher running Microsoft Windows, Versions 3.1, 3.11, and Windows 95 TME 10 Desktop for Windows, PC Agent, Managed Node, Endpoint: IBM-compatible PCs 486 or higher running Microsoft Windows NT, Versions 3.51 SP5, 4.0, and 4.0 SP3. Other Info for Your Product If you have other product-specific sections to include in preface, include them here. Tivoli SecureWay Security Manager Programmer s Guide for TACF xv

18 Accessing Publications Online The Tivoli Customer Support Web site ( offers a guide to support services (the Customer Support Handbook); frequently asked questions (FAQs); and technical information, including release notes, user s guides, redbooks, and white papers. You can access Tivoli publications online at The documentation for some products is available in PDF and HTML formats. Translated documents are also available for some products. To access most of the documentation, you need an ID and a password. To obtain an ID for use on the support Web site, go to Resellers should refer to for more information about obtaining Tivoli technical documentation and support. Business Partners should refer to Ordering Publications on page xvii for more information about obtaining Tivoli technical documentation. Attention: The following note is an example of exceptional information. If your documentation requires similar, exceptional information, add it in the appropriate section (however, it is likely that your documentation does not require any additional notes or addenda). In all instances, remove this Attention element. Note: For NetView OS/390 customers, additional support is also available on the NETVIEW CFORUM (Customer Forum) through the IBMLink system. This forum is monitored by NetView developers who answer questions and provide guidance. When a problem with the code is found, you are asked to open an official problem management record (PMR) to get resolution. xvi Version 3.7

19 Ordering Publications Order Tivoli publications online at or by calling one of the following telephone numbers: U.S. customers: (800) Canadian customers: (800) Providing Feedback about Publications We are very interested in hearing about your experience with Tivoli products and documentation, and we welcome your suggestions for improvements. If you have comments or suggestions about our products and documentation, contact us in one of the following ways: Send to Fill out our customer feedback survey at Contacting Customer Support If you need support for this or any Tivoli product, contact Tivoli Customer Support in one of the following ways: Submit a problem management record (PMR) electronically from our Web site at For information about obtaining support through the Tivoli Customer Support Web site, go to Submit a PMR electronically through the IBMLink system. For information about IBMLink registration and access, refer to the IBM Web page at Send to support@tivoli.com. Customers in the U.S. can call TIVOLI8 ( ). Tivoli SecureWay Security Manager Programmer s Guide for TACF xvii

20 Customers outside the U.S. should refer to the Tivoli Customer Support Web site at for customer support telephone numbers. When you contact Tivoli Customer Support, be prepared to provide the customer number for your company so that support personnel can assist you more readily. xviii Version 3.7

21 I -Authorizations API The Authorizations API s main function is to protect abstract objects you define. Use this API to call the TACF authorization daemon from within your application to check whether a user is authorized to perform the requested action. You can use TACF to protect program entities such as database records, fields, reports, and dialog screens. The programmer can place TACF API function calls directly in the program to check authorization before performing tasks. Tivoli SecureWay Security Manager Programmer s Guide for TACF 1

22 2 Version 3.7

23 1 Authorizations API Guide 1. Authorizations API Guide TACF governs the access a user has to a resource. Each resource belongs to a class that identifies the type of the resource. For example, records or objects of the TERMINAL class are used to govern the ability of users to log in from a terminal. A user can access a specific resource only if the user has the permissions required to access the resource in the requested manner. For example, a user can log in from a terminal only if there exists in the TACF database a record that assigns the user READ access to the terminal. Note that the rule need not be an explicit assignment - the authority may also be assigned using group membership or default access settings. You can find important background information in your other books: To learn more about TACF resources, see the introduction to the Tivoli Access Control Facility section in the Tivoli SecureWay Security Manager User s Guide. To learn more about adding user-defined resources, see the TACF command language section and the TACF utilities section in the Tivoli SecureWay Security Manager Reference Manual for TACF. To learn more about the way TACF decides whether to grant a user access to a specific resource, see the section pertaining to access rules in the Tivoli SecureWay Security Manager User s Guide. Tivoli SecureWay Security Manager Programmer s Guide for TACF 3

24 The TACF function calls in the TACF Authorization API communicate with the TACF authorization daemon seosd on the local station. TACF supports the following types of processes: Multi User Servicing Address Space (MUSAS) applications that request authorization on behalf of other users. These applications are normally used for servers that provide services to other processes. The terms MUSAS and SERVER are synonymous. Stand-alone applications (i.e., non-server applications) that request authorizations for the user that is currently using the application. To use TACF to protect the resources of an application, you must perform the following steps: 1. Add a resource class to the TACF database. This resource class is used to protect the objects of your application. For more information on adding a new resource class to TACF, see the seclassadm command in the Tivoli SecureWay Security Manager Reference Manual for TACF. 2. Add records to the application s class in the TACF database. These records define rules for protecting your application s objects. 3. Place TACF Authorization API calls in your program. 4. Link the program with the TACF library. Both SERVER and ordinary applications use the same library. To use any of the TACF functions, you must include the following line in your C code: #include <api_auth.h> The names of all the functions in the Authorizations API take the form SEOSROUTE_functionName. 4 Version 3.7

25 Protecting Resource This chapter includes sample code that demonstrates how to use some of the Authorization API functions. Additional examples are provided in the usr/seos/apisamples directory. Note: These APIs are not thread-safe. Checking the Access Authority for a User Process Any application can use the TACF Authorization API to check whether a resource can be accessed by the user. You decide whether to perform resource access checks in your application. To write an application that uses the TACF authorization mechanism, all you have to do is to call a single API function called SEOSROUTE_RequestAuth with the appropriate parameters and check the return values. Example The following program demonstrates how to check whether a user is allowed to access a resource. #include <stdio.h> #include <string.h> #include <memory.h> 1. Authorizations API Guide #include "api_auth.h" int ShowUsage(void) { fprintf( stderr,"usage:\n" " upexamp <Class-Name> <Resource-Name>\n"); return 1; } int main(int argc,char *argv[]) { int rv; char buff[seosapi_auth_msglen]; SEOS_ACCESS access; API_AUTH_RES result; /* The result of request structure */ if (argc!= 3) return ShowUsage(); memset(&access,0,sizeof(access) ); access.accs = SEOS_ACCS_READ; rv = SEOSROUTE_RequestAuth( argv[1],/* Class Name */ argv[2],/* Resource Name */ SEOSAPI_AUTH_CURRACEE,/* Myself */ &access, SEOSAPI_AUTH_LOGNONE, &result, buff); Tivoli SecureWay Security Manager Programmer s Guide for TACF 5

26 SEOSROUTE_RequestAuth Function printf( "Result %s (0x%X)\n",buff,rv ); return 0; } Files After compiling and linking this example, you can check whether you are authorized to access a specific resource. For example, to test if TACF allows you to set surrogate to root by using the su root command, type the following command: >upexamp SURROGATE USER.root The following files are used by the program: /usr/seos/apisamples/api_auth/upexamp.c /usr/seos/apisamples/api_auth/makefile /usr/seos/include/api_auth.h /usr/seos/lib/seadmapi.a Application Servers The Authorizations API includes an interface for application servers. The SERVER application is assumed to provide services to many users. Only SERVER applications can perform authorization checks on behalf of users, including the user associated with the process. The SERVER application needs to perform a pseudo-login for each new connected client. The pseudo-login is performed by calling the SEOSROUTE_VerifyCreate function. The SEOSROUTE_VerifyCreate function provides the application with an Accessor s Entry Element (ACEE) handle for the client. Each call to the TACF authorization check module for the client from this point on is made with the ACEE handle returned by the SEOSROUTE_VerifyCreate function. These handles should be carefully maintained by the application. The application must perform a pseudo-logout to release ACEE handles when a client disconnects from it or when it finishes providing services to the client. The pseudo-logout is performed by 6 Version 3.7

27 SEOSROUTE_VerifyCreate Function calling the SEOSROUTE_VerifyDelete function. If handles are not released, both system resources and TACF internal resources remain allocated to the ACEE handle. If these resources remain allocated, the unnecessary allocations can cause the system to slow down, and they may result in the inability to log into the system. Only processes running under effective UID 0 (root) or users that have the SERVER attribute may issue SEOSROUTE_VerifyCreate, SEOSROUTE_VerifyDelete, and SEOSROUTE_RequestAuth calls with a handle other than SEOSAPI_AUTH_CURRACEE. Example The following program demonstrates how to use TACF to manage the security aspects of a multi-user process. #include <stdio.h> #include <string.h> #include <memory.h> 1. Authorizations API Guide #include "api_auth.h" int ShowUsage(void); int ShowUsage(void) { fprintf( stderr,"usage:\n" " musexamp <ClassName> <ResourceName> <UserName>\n"); return 1; } int main(int argc,char *argv[]) { int rv; int usr_acee; char msg_buff[seosapi_auth_msglen]; SEOS_ACCESS access; API_AUTH_RES result; /* The result of request structure */ if (argc!= 4) return ShowUsage(); memset(&access,0,sizeof(access) ); access.accs = SEOS_ACCS_READ SEOS_ACCS_WRITE SEOS_ACCS_EXEC; rv = SEOSROUTE_VerifyCreate( argv[3],null,null,0,null, SEOSAPI_AUTH_LOG, &usr_acee,&result,msg_buff ); if (rv) { printf( "Return Value: 0x%08x\n" "Msg: '%s'\n",rv,msg_buff ); return 1; } else printf( "Got ACEE handle for user '%s': %d\n",argv[3],usr_acee ); Tivoli SecureWay Security Manager Programmer s Guide for TACF 7

28 SEOSROUTE_VerifyCreate Function rv = SEOSROUTE_RequestAuth(argv[1],/* Class Name */ argv[2],/* Resource Name */ usr_acee,/* User's ACEE Handle */ &access, 0, &result, msg_buff); if (rv) printf( "Return Value: 0x%08x\n" "Msg: '%s'\n",rv,msg_buff ); else printf( "Pass!!!!\n" ); rv = SEOSROUTE_VerifyDelete( &usr_acee,1,msg_buff ); if (rv) { printf( "Return Value: 0x%08x\n" "Msg: '%s'\n",rv,msg_buff ); return 1; } else printf( "Released ACEE handle for '%s': %d\n",argv[3],usr_acee ); Files return 0; } The following files are used by the program: /usr/seos/apisamples/api_auth/musexamp.c /usr/seos/apisamples/api_auth/makefile /usr/seos/include/api_auth.h /usr/seos/lib/seadmapi.a Access Authorization The TACF Authorization API contains a single function for managing access authorizations. Use the SEOSROUTE_RequestAuth function to check whether a user is authorized to access a resource in the requested manner. To learn more how TACF decides whether or not to grant a user access to a specific resource, see the section pertaining to access rules in the Tivoli SecureWay Security Manager User s Guide. 8 Version 3.7

29 SEOSROUTE_VerifyCreate Function User Authentication The SEOSROUTE_VerifyCreate function in the TACF Authorization API is able to authenticate a user. To do so, pass the existing password, and optionally the new password, to the API function. TACF verifies that the password matches the password of the user stored in the TACF database. For users defined to both TACF and UNIX, TACF can also use standard UNIX accounts in the UNIX environment to verify user passwords. 1. Authorizations API Guide To use the SEOSROUTE_VerifyCreate function to authenticate a user, TACF must be configured so that TACF password control and maintenance is enabled. To do this, set the property PASSWORD in the TACF class. When using the TACF command language, enter the following command: setoptions class+ (PASSWORD) For more information, see the setoptions command in the Tivoli SecureWay Security Manager Reference Manual for TACF. Note: When TACF password control is enabled, the system administrator can take advantage of its format restrictions, aging, and history maintenance. For more information on the password control functions provided by TACF, see the Tivoli SecureWay Security Manager User s Guide. Because TACF does not use the UNIX password, you are able to create accounts - users - that can only use servers protected by TACF. These accounts are not valid UNIX accounts and these users will not have direct access to stations that enable UNIX shell sessions. Therefore, these users will not be able to log in interactively. Note: Account names in TACF can be up to 255 characters long. Tivoli SecureWay Security Manager Programmer s Guide for TACF 9

30 SEOSROUTE_ParseApiError Function Managing Error Messages The Authorizations API includes a function that helps you manage error messages. When a TACF function fails, it returns an integer representing the reason for the failure (the error code). The function also writes the error message that describes the reason for the failure in the szmsg parameter. The SEOSROUTE_ParseApiError function parses the error message stored in the szmsg parameter and returns the integer representing the error code. This function is included to provide more information (the real error code from seosd) in case SEOSAPI_AUTH_REMOTE_ERR is returned. This would indicate some error in the seosd daemon. Compiling and Linking with the TACF Library Compiling an Application To compile your application with the TACF library, include the api_auth.h header file in the C source code that calls the TACF Authorization API library. You can use any ANSI-C compliant compiler. Linking Your Application with the TACF Authorization API Library The method used to link your application with the TACF Authorization API library depends on the operating system you are using. The following table shows you how to link your application with the TACF Authorization API library. Use these lines together with the rest of the command used by your operating system for linking an application. The examples in the following table assume that TACF was installed in the /usr/seos directory. The TACF libraries are therefore assumed to be located in the /usr/seos/lib directory and the TACF header files in the /usr/seos/include directory. 10 Version 3.7

31 Compiling and Linking Platform Command IBM AIX cc sample.c -I/usr/seos/include \ -bi:/usr/seos/lib/seos_binder.exp \ /usr/seos/lib/seadmapi.a -o sample All other platforms cc sample.c -I/usr/seos/include \ /usr/seos/lib/seadmapi.a -o sample Note: The examples shown in the preceding table are shipped with a makefile that can be used to set the various flags that are required by each environment. 1. Authorizations API Guide Tivoli SecureWay Security Manager Programmer s Guide for TACF 11

32 Compiling and Linking 12 Version 3.7

33 2 Authorizations API Reference The Authorizations API consists of the following functions: Function SEOSROUTE_ParseApiError SEOSROUTE_RequestAuth SEOSROUTE_VerifyCreate SEOSROUTE_VerifyDelete Description Converts an error string into the integer representing the error code. Checks whether a user is authorized to access a resource when using the specified access type. Creates an ACEE handle for a user. Deletes a user s ACEE handle. 2. Authorizations API Reference Tivoli SecureWay Security Manager Programmer s Guide for TACF 13

34 SEOSROUTE_ParseApiError Function SEOSROUTE_ParseApiError Synopsis int SEOSROUTE_ParseApiError(const char *szerrmsg); Description The ParseApiError function parses the error string returned by the verification and authentication functions and returns the integer value associated with it. Notes: 1. Any user can call the ParseApiError function. 2. This function is included in order to be able to get the real error code from seosd, if the value returned by SEOSROUTE_RequestAuth, SEOSROUTE_VerifyCreate, or SEOSROUTE_VerifyDelete is SEOSAPI_AUTH_REMOTE_ERR. Arguments szerrmsg The error string that was returned by TACF in the *szmsg parameter. Return Codes The integer value of the error message. 14 Version 3.7

35 SEOSROUTE_RequestAuth Function SEOSROUTE_RequestAuth Synopsis int SEOSROUTE_RequestAuth(const char *szclass, const char *szentity, int hacee, SEOS_ACCESS *paccess, int LogOpt, API_AUTH_RES *pres, char *szmsg); Description The RequestAuth function asks the TACF authorization daemon whether the specified user is allowed to access the specified resource when using the specified access type. The RequestAuth function sends the request to seosd - the TACF daemon. First seosd checks whether the parameters are valid. If they are, seosd performs its standard resource authorization check. Notes: 1. Before calling RequestAuth, a SERVER application normally calls VerifyCreate to get an ACEE handle for the user whose authorization is being checked. 2. When RequestAuth is called with the hacee parameter set to SEOSAPI_AUTH_CURRACEE, authorization is requested for the user executing the calling process. TACF does not check whether the user has the SERVER attribute. TACF does not check whether the process is running under the effective user ID of root. 2. Authorizations API Reference Authorization All users can use the RequestAuth function. Only SERVER processes can use the query for an ACEE other than its own. Arguments szclass The name of the class to which the resource belongs. Tivoli SecureWay Security Manager Programmer s Guide for TACF 15

36 RequestAuth Arguments szentity The name of the record, or object, representing the resource being accessed. hacee The ACEE handle of the accessor. To specify the ACEE of the user associated with the current process, specify SEOSAPI_AUTH_CURRACEE. Specifying an ACEE handle other than SEOSAPI_AUTH_CURRACEE requires the user associated with the calling process to have the SERVER attribute or the calling process to be running under the effective user ID of 0 (root). paccess A pointer to a structure containing the requested access. The structure contains the single data member access of type SEOS_ACCS. Valid values for this member are SEOS_ACCS_ALL, SEOS_ACCS_CHMOD, SEOS_ACCS_CHOWN, SEOS_ACCS_DELETE, SEOS_ACCS_EXECUTE, SEOS_ACCS_NONE, SEOS_ACCS_READ, SEOS_ACCS_RENAME, SEOS_ACCS_SEC, SEOS_ACCS_UPDATE, SEOS_ACCS_UTIME, and SEOS_ACCS_WRITE. LogOpt A flag that determines whether an audit log entry will be made. Its values are: SEOSAPI_AUTH_LOGNONE For regular uses, if the authorization request succeeds, do not create an audit record. If the authorization request fails, create an audit record, if the current rules in the TACF database require it. For SERVER applications, do not create an audit record, regardless of whether the authorization request succeeds or fails. SEOSAPI_AUTH_LOG If the current rules in the TACF database require it, create an audit record. 16 Version 3.7

37 RequestAuth Arguments pres szmsg SEOSAPI_AUTH_LOGALL For regular users, this is an invalid option. It will be mapped to SEOSAPI_AUTH_LOG. For SERVER applications, always create an audit record, regardless of the TACF database rules. SEOSAPI_AUTH_LOGFAIL For regular users, this is an invalid option. It will be mapped to SEOSAPI_AUTH_LOG. For SERVER applications, create an audit record only if the authorization request fails and the TACF database rules require it. A pointer to a structure containing the authorization result. For more information, see the API_AUTH_RES Structure on page 187. A status message returned by TACF. The buffer must be SEOSAPI_AUTH_MSGLEN bytes long. Return Codes An integer that takes on one of the following values: SEOSAPI_AUTH_OK Access is granted. SEOSAPI_AUTH_BADACCESS_ERR An invalid access authority was specified. SEOSAPI_AUTH_DENY The request was denied. SEOSAPI_AUTH_NORESPONSE_ERR The TACF daemon is not responding. SEOSAPI_AUTH_NOTROOT_ERR The calling process s user ID is not 0 (root) and the user executing the calling process does not have the SERVER attribute. SEOSAPI_AUTH_REMOTE_ERR TACF daemon error; a description of the error is provided in szmsg. 2. Authorizations API Reference Tivoli SecureWay Security Manager Programmer s Guide for TACF 17

38 RequestAuth Arguments See Also SEOSROUTE_VerifyCreate on page Version 3.7

39 SEOSROUTE_VerifyCreate Function SEOSROUTE_VerifyCreate Synopsis int SEOSROUTE_VerifyCreate(const char *szuserid, const char *szpwd, const char *sznewpwd, int ChkFlags, const char *szterm, int LogOpt, int *phacee, API_AUTH_RES *pres, char *szmsg); Description The VerifyCreate function performs a pseudo-login to TACF and returns a handle to the ACEE that is created. For programmers familiar with MVS, this service is similar to the RACF RACROUTE and RACINIT functions, such as RACROUTE REQUEST=VERIFY. Notes: 1. The VerifyCreate function is to be used only by a multi-user (SERVER) process that performs services on behalf of other users. A single-user process can call the RequestAuth function without first calling the VerifyCreate function. 2. TACF checks and updates the password in the TACF database. It neither checks nor updates the standard UNIX password. 2. Authorizations API Reference Authorization To execute the VerifyCreate function, the calling process must have effective user ID of 0 or the user associated with the calling process must have the SERVER attribute. Arguments szuserid The name of the user for whom the ACEE is to be created. This parameter must be supplied. szpwd The password of the user identified by szuserid.if a NULL pointer is specified, TACF skips the password check. Tivoli SecureWay Security Manager Programmer s Guide for TACF 19

40 VerifyCreate Arguments sznewpwd The new password, should your application be changing the user s password. Specify a NULL pointer if you are not specifying a new password or if a NULL pointer is specified for szpwd. ChkFlags A flag that determines whether the password is to be checked. The following are all the flag values, and can be combined (using bitwise OR): VERCRE_CHECK_CURR Check that the current password is valid. VERCRE_CHECK_NEW Check that the new password is valid. VERCRE_CHECK_QUICKLOGIN Simulate login without checking for time restrictions. szterm The name of the terminal from which the user logged into the system. LogOpt A flag that determines whether an audit log entry will be made. Its values are: SEOSAPI_AUTH_LOGNONE For SERVER applications, do not create an audit record. SEOSAPI_AUTH_LOG If the current rules in the TACF database require it, create an audit record. SEOSAPI_AUTH_LOGALL For SERVER applications, always create an audit record, regardless of the TACF database rules. SEOSAPI_AUTH_LOGFAIL For SERVER applications, create an audit record only if the authorization request fails and the TACF database rules require it. 20 Version 3.7

41 VerifyCreate Arguments phacee The ACEE handle returned by TACF. This value is used by TACF in subsequent authorization checks for the currently verified user. pres szmsg Return Codes A structure containing the authorization result. For more information, see the API_AUTH_RES Structure on page 187. A status message returned by TACF. The buffer must be SEOSAPI_AUTH_MSGLEN bytes long. SEOSAPI_AUTH_OK The user is allowed to access the resource as requested. SEOSAPI_AUTH_BADPASSWD_ERR The password does not match the expected password. SEOSAPI_AUTH_DENY The request was denied. SEOSAPI_AUTH_NORESPONSE_ERR The TACF daemon is not responding. SEOSAPI_AUTH_NOTROOT_ERR The user ID of the calling process is not 0 (root), and the user executing the calling process does not have the SERVER attribute. SEOSAPI_AUTH_NOUSERID_ERR A user name was not supplied. SEOSAPI_AUTH_NULLACEE_ERR The phacee parameter is a NULL pointer SEOSAPI_AUTH_REMOTE_ERR TACF daemon error; a description of the error is provided in szmsg. See Also SEOSROUTE_VerifyDelete on page Authorizations API Reference Tivoli SecureWay Security Manager Programmer s Guide for TACF 21

42 SEOSROUTE_VerifyDelete Functions SEOSROUTE_VerifyDelete Synopsis int SEOSROUTE_VerifyDelete(int *phacee, int blog, char *szmsg) Description The VerifyDelete function releases an ACEE. Use this function to release ACEEs that were created using the VerifyCreate function. Your application should release ACEEs once they are no longer required, because each allocated handle uses system resources and TACF internal resources. These resources are limited. Argument phacee A pointer to the handle of the ACEE to be released. blog A flag that determines whether an audit log entry will be made. It can have a value 0 or 1; to create a log entry, set the parameter to 1. szmsg A status message returned by TACF. The buffer must be SEOSAPI_AUTH_MSGLEN bytes long. Authorization To execute the VerifyDelete function, the calling process must have effective user ID of 0 or the user associated with the calling process must have the SERVER attribute. Return Codes An integer that takes on one of the following values: SEOSAPI_AUTH_OK The ACEE was released. SEOSAPI_AUTH_NOACEE_ERR The ACEE to be deleted was not found. SEOSAPI_AUTH_NORESPONSE_ERR The TACF daemon is not responding. 22 Version 3.7

43 VerifyDelete Arguments SEOSAPI_AUTH_NOTROOT_ERR The calling process s user ID is not 0 (root) and the user executing the calling process does not have the SERVER attribute. SEOSAPI_AUTH_NULLACEE_ERR The phacee parameter is a NULL pointer. SEOSAPI_AUTH_REMOTE_ERR TACF daemon error; an error message is placed in szmsg. See Also SEOSROUTE_VerifyCreate on page Authorizations API Reference Tivoli SecureWay Security Manager Programmer s Guide for TACF 23

44 VerifyDelete Arguments 24 Version 3.7

45 II -Exits API The Exits API enables you to add your own functions on top of the TACF authorization and authentication functions. It also enables you to add a special notification function to the TACF daemon. Detailed instructions for designing, writing, compiling, and registering your own Exits API functions follow. Tivoli SecureWay Security Manager Programmer s Guide for TACF 25

46 26 Version 3.7

47 3 Exits API Guide The Exits API enables you to insert your own functions to be executed just before or after TACF authorizes a requested activity. The TACF daemon seosd monitors all system, program, and user activities. Seosd intercepts every activity and decides whether to authorize the requested action. You may insert your own registered functions just before (PRE) or after (POST) TACF makes these decisions. For example, you may register a PRE exit function to be executed before TACF considers each logon request. Your exit function gains control just before TACF starts to authorize a login request. After completing its task, your exit function returns control to TACF with a return code indicating your function s authorization decision. Your function must return one of the return codes described in the following table. Return Code SEOS_EXITR_CHECK SEOS_EXITR_PASS SEOS_EXITR_DENY Description Instructs TACF to perform its own standard authorization check. Instructs TACF to grant the request. TACF does not perform its own standard authorization check. Instructs TACF to deny the request. TACF does not perform its own standard authorization check. 3. Exits API Guide Tivoli SecureWay Security Manager Programmer s Guide for TACF 27

48 If the decision is SEOS_EXITR_PASS or SEOS_EXITR_DENY, TACF grants or denies the request immediately. If your function returns SEOS_EXITR_CHECK, TACF continues with its own standard authorization check. System, program, and user activities that require authorization by TACF are called events. The events that TACF authorizes are described in TACF Events on page 32. Events are grouped into the following categories: Login General Resource Check TCP/IP Request Password Quality Check Password Change Exit functions for Password Quality Check or Password Change events are linked to the TACF password utility sepass. Exit functions for Login, General Resource Check, and TCP/IP Request events are linked to the TACF daemon seosd. Compiling and linking procedures are described in Compiling and Linking with the TACF api_authx Library on page 35. Creating a New Exit Function New exit functions are added to the TACF seosd program and the TACF sepass program by writing C-language functions that can be compiled and linked to a shared library. The configuration files of seosd and sepass must be changed to include this new, shared library. An Exits API function has three parts: Registration Implementation Termination The registration function initializes your Exits API function and registers it with the TACF programs. The implementation function 28 Version 3.7

49 Creating a New Exit Function adds your tasks to the standard TACF processing. The termination function unregisters and shuts your program down properly when the TACF programs themselves terminate. The following diagram describes the flow of the Exits API initialization, implementation, and termination. 3. Exits API Guide Your Exits API exit functions take advantage of functions and header files provided by TACF. You use the same registration, initialization, and termination functions for all your exit functions, whether they Tivoli SecureWay Security Manager Programmer s Guide for TACF 29

50 Creating a New Exit Function link to seosd or sepass. For more information on the pre-defined functions in an exit function, see Exits API Reference on page 45. Once your Exits API function is ready, you must bind your new API to the TACF daemons. For more information on compiling and linking procedures, see Compiling and Linking with the TACF api_authx Library on page 35. All Exits API functions use special data structures provided by TACF to pass information back and forth between functions. Programmers need to know the specific formats and data types used by these structures in order to access the structures correctly in their own programs. For complete information on these formats and data types, see Structures and Data Types on page 185. The input data structure used by your exit function depends on the event being intercepted by the function. All functions use the same output data structure. The following table lists the data structures used by the Exits API functions. Event Data structure Type Login SEOS_EXITLOGIN Input General Resource Check SEOS_EXITGENR Input TCP/IP Request SEOS_EXITINET Input Password Quality Check; SEOS_EXITPASS Input Password Change All events SEOS_EXITRES Output If your Exits API function ends in success, your function should fill in the SEOS_EXITRES structure and return 0. If TACF receives a successful (0) return code, it checks the result field in the SEOS_EXITRES structure. If the SEOS_EXITRES value is Pass or Deny, it is acted on immediately, and TACF does not execute its own authorization check. If the result is Check, TACF continues with its own authorization check. 30 Version 3.7

51 The following diagram shows this processing. Creating a New Exit Function If your Exits API function ends in failure, your function should fill in the SEOS_EXITRES structure and return a non-zero error code. If TACF receives a non-zero return code, it adds an entry to the TACF error log file with the source file name and line number as they appear in the SEOS_EXITRES structure. The other values set in SEOS_EXITRES are ignored. TACF then continues with its own authorization check. 3. Exits API Guide Two sample Exits API functions are provided in this chapter. These examples will help you get started with your own programs. The first example is a simple counter, intercepting every TACF authorization call and keeping statistics on how often such calls are made. The second example adds a new restriction to the password Tivoli SecureWay Security Manager Programmer s Guide for TACF 31