Tivoli SecureWay Security Managerpublib.boulder.ibm.com › tividd › td › security › GC32-0708-00 › ... · 2002-11-09 · Chapter 4. Exits API Reference..... 45 General Functions

Tivoli SecureWay SecurityManagerProgrammer’s Guide for TACFVersion 3.7

Tivoli SecureWay SecurityManagerProgrammer’s Guide for TACFVersion 3.7

Tivoli SecureWay Security Management Programmer’s Guide for TACF (November2000)

Copyright Notice

© Copyright IBM Corporation 2000 All rights reserved. May only be used pursuant to a TivoliSystems Software License Agreement, an IBM Software License Agreement, or Addendum forTivoli Products to IBM Customer or License Agreement. No part of this publication may bereproduced, transmitted, transcribed, stored in a retrieval system, or translated into any computerlanguage, in any form or by any means, electronic, mechanical, magnetic, optical, chemical,manual, or otherwise, without prior written permission of IBM Corporation. IBM Corporationgrants you limited permission to make hardcopy or other reproductions of any machine-readabledocumentation for your own use, provided that each such reproduction shall carry the IBMCorporation copyright notice. No other rights under copyright are granted without prior writtenpermission 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 ADPSchedule 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 BusinessMachines 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 ofMicrosoft 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 UnitedStates, other countries, or both.

Novell, NetWare, NetWare Directory Services, and NDS are trademarks of Novell, Inc.

TACF Copyright © 1993-2000 by MEMCO Software Ltd., U.S. patent pending. All rightsreserved.

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 notimply that they will be available in all countries in which Tivoli Systems or IBM operates. Anyreference to these products, programs, or services is not intended to imply that only TivoliSystems or IBM products, programs, or services can be used. Subject to valid intellectualproperty or other legally protectable right of Tivoli Systems or IBM, any functionally equivalentproduct, 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 thoseexpressly designated by Tivoli Systems or IBM, are the responsibility of the user. Tivoli Systemsor IBM may have patents or pending patent applications covering subject matter in thisdocument. The furnishing of this document does not give you any license to these patents. Youcan send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, NorthCastle Drive, Armonk, New York 10504-1785, U.S.A.

Contents

Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiWho 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 . . . . . . . . . . . . . . . . . . . . . 3Checking the Access Authority for a User Process . . . . . . . . . . . . . . . . . . . . . 5

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Application Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Access Authorization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

User Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Managing Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Compiling and Linking with the TACF Library . . . . . . . . . . . . . . . . . . . . . . 10

iiiTivoli SecureWay Security Manager Programmer’s Guide for TACF

Compiling an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Linking Your Application with the TACF Authorization API Library 10

Chapter 2. Authorizations API Reference . . . . . . . . . . . . . . . 13SEOSROUTE_ParseApiError. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

SEOSROUTE_RequestAuth. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

SEOSROUTE_VerifyCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

SEOSROUTE_VerifyDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Part II. -Exits API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Chapter 3. Exits API Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Creating a New Exit Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

TACF Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Events Linked to seosd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Events linked to sepass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

User Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Compiling and Linking with the TACF api_authx Library . . . . . . . . . . . . . . 35

Compiling an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Linking Your Application with TACF. . . . . . . . . . . . . . . . . . . . . . . . . . 35

System Design and Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Modular Design. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

System Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Exits API Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

TACF Daemon Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Password Utilities Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

iv Version 3.7

Chapter 4. Exits API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . 45General Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Database Interface Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Shared Library Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

authxapi_RegisterExitFunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

authxapi_UnRegisterExitFunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

authxapi_IsThereExitFunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

authxapi_GetObjectProperty. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

authxapi_GetObjectListValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

authxapi_FreeListValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

authxapi_GetUserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Part III. -LogRoute API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Chapter 5. LogRoute API Guide . . . . . . . . . . . . . . . . . . . . . . . . . 67Customizing selogrd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Predefined LogRoute API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Compiling and Linking with the TACF LogRoute Library . . . . . . . . . . 69

Format of the Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Notification Audit Log Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Chapter 6. LogRoute API Reference. . . . . . . . . . . . . . . . . . . . . 79<driver>_Register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

<driver>_UnRegister . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

<driver>_RegisterDestination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

<driver>_UnregisterDestination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

lograpi_InterpretRecord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

vTivoli SecureWay Security Manager Programmer’s Guide for TACF

lograpi_RegisterTargetType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

lograpi_UnregisterTargetType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

lograpi_MakeStringMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

LogrApiSenseFunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

LogrApiSendFunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

LogrApiFreeFunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

servlog_IsThereExit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

servlog_RegisterExit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

servlog_UnRegisterExit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Part IV. -Administration API . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Chapter 7. Administration API Guide . . . . . . . . . . . . . . . . . . 101How the TACF Database Is Organized . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Database Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Class Description File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Properties Description File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Objects Description File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Properties Values File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Lists in the TACF Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Connections of Users to Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Connections of Resources to Resource Groups . . . . . . . . . . . . . . . . . . 106

Access Control List (ACL) Entries. . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Understanding ACEE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Scope Limitations of the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

vi Version 3.7

Compiling and Linking with the seadmapi . . . . . . . . . . . . . . . . . . . . . . . . . 109

Programming Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Chapter 8. Administration API Reference . . . . . . . . . . . . . . 111Class Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Console Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Log Files Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Miscellaneous Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Object Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Property Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Query Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Value Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

seadmapi_ClassGetEqual seadmapi_ClassGetFirst seadmapi_ClassGetNext 117

seadmapi_GetACEE seadmapi_FreeAceeMemory. . . . . . . . . . . . . . . . . . . . 120

seadmapi_GetMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

seadmapi_Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

seadmapi_IsSeOSSyscallLoaded. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

seadmapi_PropGetEqual seadmapi_PropGetFirstInClassseadmapi_PropGetNextInClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

seadmapi_ObjGetEqual seadmapi_ObjGetFirstInClassseadmapi_ObjGetNextInClass seadmapi_ObjGetGreaterEqual . . . . . . . . . . . 129

seadmapi_ObjInClassList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

seadmapi_FreeObjList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

seadmapi_FetchListPropVal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

seadmapi_FetchSinglePropVal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

seadmapi_FreeListPropVal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

seadmapi_SetSinglePropVal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

seadmapi_KillPDFList seadmapi_MakePDFList . . . . . . . . . . . . . . . . . . . . . 147

viiTivoli SecureWay Security Manager Programmer’s Guide for TACF

seadmapi_GetEntity seadmapi_GetExEntity seadmapi_InitEntityRulerseadmapi_KillEntityMem seadmapi_KillExEntityMem . . . . . . . . . . . . . . . . 149

seadmapi_GetGraceInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

seadmapi_OidToName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

seadmapi_WhoAmI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

seadmapi_GetObjType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

seadmapi_SendAuditRecord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

seadmapi_SendStartupAudit seadmapi_SendShutdownAuditseadmapi_SendUserAudit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

seadmapi_SendLoginAudit seadmapi_SendGenrAuditseadmapi_SendWatchdogAudit seadmapi_SendInetAuditseadmapi_SendAdminAudit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

seadmapi_SendErrorLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

seadmapi_ProcessControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

seadmapi_consTraceClear seadmapi_consTraceDisableseadmapi_consTraceEnable seadmapi_consTraceGetStatusseadmapi_consTraceToggle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

seadmapi_consUidLoginDisable seadmapi_consUidLoginEnableseadmapi_consUidLoginGetStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

seadmapi_consAllLoginDisable seadmapi_consAllLoginEnableseadmapi_consAllLoginGetStatus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

seadmapi_consRunTimeStatisticsGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

seadmapi_consMessageSend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

seadmapi_consShutDown. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

seadmapi_ReloadIni. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

seadmapi_WhoIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

sepass_ReplacePassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Chapter 9. Structures and Data Types . . . . . . . . . . . . . . . . . 185Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

viii Version 3.7

API_AUTH_RES Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

CLIENT_ACEE Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

LOGRAPI_FUNCS Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

LOGRECHDR Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

LOGRECORD Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

See Also . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

PFSEOSEXITFUNC Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

SEADMAPI_RTSTAT Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

SEGRACE_RES Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

SEOS_ACCESS Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

See Also . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

SEOS_ACCS Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

SEOS_ACL Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

SEOS_AUDITADMIN Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

SEOS_AUDITDOWN Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

SEOS_AUDITGENR Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

SEOS_AUDITINWARN Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

SEOS_AUDITLOGIN Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

SEOS_AUDITSTART Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

See Also . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

SEOS_AUDITUSER Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

SEOS_AUDITWDWARN Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

SEOS_CID Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

SEOS_EXITGENR Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

SEOS_EXITINET Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

SEOS_EXITLOGIN Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

SEOS_EXITPASS Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

ixTivoli SecureWay Security Manager Programmer’s Guide for TACF

SEOS_EXITRES Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

SEOS_GCONN Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

SEOS_OID Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

SEOS_PACL Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

SEOS_PID Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

SEOS_REQ_ERRORDESCP Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

SEOS_ROUTENTRY Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

SEOS_X_ACL Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214214

SEOS_X_GCONN Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

SEOS_X_OID Data Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

SEOS_X_PACL Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

SEOSDB_CDF Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

SEOSDB_ENTDAT Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

SEOSDB_ODF Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

SEOSDB_PDF Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

Part V. Appendixes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

x Version 3.7

Preface

Who Should Read This GuideDevelopers, administrators, and end users all can profit when theTivoli Access Control Facility (TACF) APIs are effectively used:

¶ For developers, the APIs supply a simple, portable interface toTACF - a security package that provides robust security for theirapplications.

¶ For system administrators, the APIs supply a single securityinterface for both applications and the operating system.

¶ For end users, the APIs supply additional protection for theirdata.

Note:Users of this guide should have some knowledge of the UNIXoperating system and basic security principals.

Prerequisite and Related DocumentsThe 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 ContainsThis guide contains the following parts:

¶ Part I: “Authorizations API” enables client applications requestauthorization for predefined or site-defined abstract resourceclasses using the authorization and auditing mechanismsprovided by TACF. This API also includes the AuthenticationAPI.

¶ Part II: “Exits API” enables you to customize the TACFauthorization mechanisms by complementing TACF authorization

xiTivoli SecureWay Security Manager Programmer’s Guide for TACF

routines with your own authorization routines. You can also adda special notification function to the TACF daemon activities.For example, this API can be used to add site-specific requestsfor password quality verification in TACF.

¶ Part III: “LogRoute API” enables you to add your own alerts tothe standard TACF audit log functions. You can also use thelogroute daemon to add a guaranteed delivery of audit data orthird party alert systems to other programs.

¶ Part IV: “Administration API” enables you to extract informationfrom the TACF database. This API also permits applications toperform administrative tasks such as shutting down seosd - theTACF daemon - or to modify the ability to perform concurrentlogins and so on.

Sample programs are provided. Additional examples can befound in the apisamples subdirectory of the directory in whichTACF is installed - usually /usr/seos.

Each part includes “Guide” and “Reference” chapters. Guidechapters provide examples of the API and instructions on how to useit. Reference chapters provide tables listing API functions bycategory at the beginning of the chapter, followed by a detailedreference for each function.

The last chapter of the book contains the structures and data typesused by the variables of the API functions.

Conventions Used in This GuideThe guide uses several typeface conventions for special terms andactions. These conventions have the following meaning:

Bold Commands, keywords, file names, authorizationroles, URLs, or other information that you must useliterally appear like this, in bold. Names ofwindows, dialogs, and other controls also appear likethis, in bold.

Italics Variables and values that you must provide appear

xii Version 3.7

like this, in italics. Words and phrases that areemphasized also appear like this, in italics.

Monospace Code examples, output, and system messages appearlike this, in a monospace font.

This guide uses the UNIX convention for specifying environmentvariables and for directory notation. When using the Windows NTcommand line, replace $variable with %variable% for environmentvariables and replace each forward slash (/) with a backslash (\) indirectory paths.

Note: When using the bash shell on a Windows NT system, you canuse the UNIX conventions.

Contacting Customer SupportFor support inside the United States, for this or any Tivoli product,contact Tivoli Customer Support in one of the following ways:

¶ Send e-mail to [email protected]

¶ Call 1-800-TIVOLI8

¶ Navigate our Web site at http://www.support.tivoli.com

For support outside the United States, refer to your CustomerSupport Handbook for phone numbers in your country. TheCustomer Support Handbook is available online athttp://www.support.tivoli.com.

When you contact Tivoli Customer Support, be prepared to provideidentification information for your company so that supportpersonnel can assist you more readily.

We are very interested in hearing from you about your experiencewith Tivoli products and documentation. We welcome yoursuggestions for improvements. If you have comments or suggestionsabout this documentation, please send e-mail to [email protected].

xiiiTivoli SecureWay Security Manager Programmer’s Guide for TACF

Platform-specific InformationAttention: The table in this section is an example ofplatform-specific information. Modify this table or create your ownhere.

The following table identifies the supported platform versions knownat the time of publication. For more detailed and up-to-dateinformation, please see the release notes.

Platform Supported Versions

AIX 4.x Managed Node, Endpoint:

IBM RS/6000 series running AIX, Versions 4.1, 4.2,and 4.3

AS/400 Endpoint:

V3R2, V3R7, V4R1, and V4R2

Digital UNIX Managed Node, Endpoint:

Versions 4.0a and 4.0d.

DG/UX Endpoint:

Versions 4.11 and 4.20 on the ix86 platform

HP-UX Managed Node, Endpoint:

HP9000/700 and 800 series running HP-UX, Versions10.01, 10.10, 10.20 and 11.00

NCR Managed Node, Endpoint:

NCR 3000 series running NCR UNIX SVR4MP-RAS 3.0.1 and 3.0.2

NetWare PC Agent, Endpoint:

IBM-compatible PCs 486 or higher running NovellNetWare, Versions 3.11, 3.12, 4.01, 4.1, and 4.11

OS/2 TME 10 Desktop for Windows, PC Agent, Endpoint:

IBM-compatible PCs 486 or higher running IBMOS/2, Versions 2.0, 2.1,Warp 3.0, and Warp 4.0 withWin-OS/2

xiv Version 3.7

Platform Supported Versions

Pyramid Endpoint:

Pyramid MIServer-ES, Version 5.4MN

Sequent Managed Node, Endpoint:

Sequent DYNIX/ptx, Releases 4.2.3 and 4.4.2

SCO Managed Node, Endpoint:

SCO UnixWare 7, SCO UnixWare Versions 2.1.1 and2.1.2

SGI Managed Node, Endpoint:

SGI IRIX, Versions 6.2 and 6.4

Solaris Managed Node, Endpoint:

Sun SPARC series running Solaris, Versions 2.4, 2.5,2.5.1, and 2.6

Solaris Intel Managed Node, Endpoint:

Solaris2-ix86, Versions 2.5.1 and 2.6

SunOS Managed Node, Endpoint:

Sun SPARC series running SunOS, Versions 4.1.3 and4.1.4

Windows TME 10 Desktop for Windows, PC Agent, Endpoint:

IBM-compatible PCs 486 or higher running MicrosoftWindows, Versions 3.1, 3.11, and Windows 95

Windows NT TME 10 Desktop for Windows, PC Agent, ManagedNode, Endpoint:

IBM-compatible PCs 486 or higher running MicrosoftWindows NT, Versions 3.51 SP5, 4.0, and 4.0 SP3.

Other Info for Your ProductIf you have other product-specific sections to include in preface,include them here.

xvTivoli SecureWay Security Manager Programmer’s Guide for TACF

Accessing Publications OnlineThe Tivoli Customer Support Web site(http://www.tivoli.com/support/) offers a guide to support services(the Customer Support Handbook); frequently asked questions(FAQs); and technical information, including release notes, user’sguides, redbooks, and white papers. You can access Tivolipublications online at http://www.tivoli.com/support/documents/.The documentation for some products is available in PDF andHTML formats. Translated documents are also available for someproducts.

To access most of the documentation, you need an ID and apassword. To obtain an ID for use on the support Web site, go tohttp://www.tivoli.com/support/getting/.

Resellers should refer tohttp://www.tivoli.com/support/smb/index.html for moreinformation about obtaining Tivoli technical documentation andsupport.

Business Partners should refer to “Ordering Publications” onpage xvii for more information about obtaining Tivoli technicaldocumentation.

Attention: The following note is an example of exceptionalinformation. If your documentation requires similar, exceptionalinformation, add it in the appropriate section (however, it is likelythat your documentation does not require any additional notes oraddenda). In all instances, remove this Attention element.

Note: For NetView OS/390 customers, additional support is alsoavailable on the NETVIEW CFORUM (Customer Forum)through the IBMLink system. This forum is monitored byNetView developers who answer questions and provideguidance. When a problem with the code is found, you areasked to open an official problem management record (PMR)to get resolution.

xvi Version 3.7

Ordering PublicationsOrder Tivoli publications online athttp://www.tivoli.com/support/Prodman/html/pub_order.html orby calling one of the following telephone numbers:

¶ U.S. customers: (800) 879-2755

¶ Canadian customers: (800) 426-4968

Providing Feedback about PublicationsWe are very interested in hearing about your experience with Tivoliproducts and documentation, and we welcome your suggestions forimprovements. If you have comments or suggestions about ourproducts and documentation, contact us in one of the followingways:

¶ Send e-mail to [email protected].

¶ Fill out our customer feedback survey athttp://www.tivoli.com/support/survey/.

Contacting Customer SupportIf you need support for this or any Tivoli product, contact TivoliCustomer Support in one of the following ways:

¶ Submit a problem management record (PMR) electronically fromour Web site at http://www.tivoli.com/support/reporting/. Forinformation about obtaining support through the Tivoli CustomerSupport Web site, go to http://www.tivoli.com/support/getting/.

¶ Submit a PMR electronically through the IBMLink™ system. Forinformation about IBMLink registration and access, refer to theIBM Web page at http://www.ibmlink.ibm.com.

¶ Send e-mail to [email protected].

¶ Customers in the U.S. can call 1-800-TIVOLI8(1-800-848-6548).

xviiTivoli SecureWay Security Manager Programmer’s Guide for TACF

¶ Customers outside the U.S. should refer to the Tivoli CustomerSupport Web site athttp://www.tivoli.com/support/locations.html for customersupport telephone numbers.

When you contact Tivoli Customer Support, be prepared to providethe customer number for your company so that support personnelcan assist you more readily.

xviii Version 3.7

I — -Authorizations APIThe Authorizations API’s main function is to protect abstract objects you define. Usethis API to call the TACF authorization daemon from within your application tocheck 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 callsdirectly in the program to check authorization before performing tasks.

1Tivoli SecureWay Security Manager Programmer’s Guide for TACF

2 Version 3.7

Authorizations API Guide

TACF governs the access a user has to a resource. Each resourcebelongs to a class that identifies the type of the resource. Forexample, records or objects of the TERMINAL class are used togovern the ability of users to log in from a terminal. A user canaccess a specific resource only if the user has the permissionsrequired to access the resource in the requested manner. Forexample, a user can log in from a terminal only if there exists in theTACF database a record that assigns the user READ access to theterminal. Note that the rule need not be an explicit assignment - theauthority may also be assigned using group membership or defaultaccess settings.

You can find important background information in your other books:

¶ To learn more about TACF resources, see the introduction to theTivoli Access Control Facility section in the Tivoli SecureWaySecurity Manager User’s Guide.

¶ To learn more about adding user-defined resources, see theTACF command language section and the TACF utilities sectionin the Tivoli SecureWay Security Manager Reference Manual forTACF.

¶ To learn more about the way TACF decides whether to grant auser access to a specific resource, see the section pertaining toaccess rules in the Tivoli SecureWay Security Manager User’sGuide.

1


1.A

uth

orizatio

ns

AP

IG

uid

e

The TACF function calls in the TACF Authorization APIcommunicate with the TACF authorization daemon seosd on thelocal station.

TACF supports the following types of processes:

¶ Multi User Servicing Address Space (MUSAS) applications thatrequest authorization on behalf of other users. These applicationsare normally used for servers that provide services to otherprocesses. The terms MUSAS and SERVER are synonymous.

¶ Stand-alone applications (i.e., non-server applications) thatrequest authorizations for the user that is currently using theapplication.

To use TACF to protect the resources of an application, you mustperform the following steps:

1. Add a resource class to the TACF database. This resource classis used to protect the objects of your application. For moreinformation on adding a new resource class to TACF, see theseclassadm command in the Tivoli SecureWay Security ManagerReference Manual for TACF.

2. Add records to the application’s class in the TACF database.These records define rules for protecting your application’sobjects.

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 followingline in your C code:#include <api_auth.h>

The names of all the functions in the Authorizations API take theform SEOSROUTE_functionName.

4 Version 3.7

This chapter includes sample code that demonstrates how to usesome of the Authorization API functions. Additional examples areprovided in the usr/seos/apisamples directory.

Note: These APIs are not thread-safe.

Checking the Access Authority for a User ProcessAny application can use the TACF Authorization API to checkwhether a resource can be accessed by the user. You decide whetherto perform resource access checks in your application. To write anapplication that uses the TACF authorization mechanism, all youhave to do is to call a single API function calledSEOSROUTE_RequestAuth with the appropriate parameters andcheck the return values.

ExampleThe following program demonstrates how to check whether a user isallowed to access a resource.#include <stdio.h>#include <string.h>#include <memory.h>

#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);

Protecting Resource


1.A

uth

orizatio

ns

AP

IG

uid

e

printf( "Result %s (0x%X)\n", buff, rv );return 0;

}

After compiling and linking this example, you can check whetheryou are authorized to access a specific resource. For example, to testif TACF allows you to set surrogate to root by using the su rootcommand, type the following command:>upexamp SURROGATE USER.root

FilesThe 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 ServersThe Authorizations API includes an interface for application servers.The SERVER application is assumed to provide services to manyusers. Only SERVER applications can perform authorization checkson behalf of users, including the user associated with the process.

The SERVER application needs to perform a “pseudo-login” foreach new connected client. The pseudo-login is performed by callingthe SEOSROUTE_VerifyCreate function. TheSEOSROUTE_VerifyCreate function provides the application withan Accessor’s Entry Element (ACEE) handle for the client.

Each call to the TACF authorization check module for the clientfrom this point on is made with the ACEE handle returned by theSEOSROUTE_VerifyCreate function. These handles should becarefully maintained by the application.

The application must perform a “pseudo-logout” to release ACEEhandles when a client disconnects from it or when it finishesproviding services to the client. The pseudo-logout is performed by

SEOSROUTE_RequestAuth Function

6 Version 3.7

calling the SEOSROUTE_VerifyDelete function. If handles are notreleased, both system resources and TACF internal resources remainallocated to the ACEE handle. If these resources remain allocated,the unnecessary allocations can cause the system to slow down, andthey may result in the inability to log into the system.

Only processes running under effective UID 0 (root) or users thathave the SERVER attribute may issue SEOSROUTE_VerifyCreate,SEOSROUTE_VerifyDelete, and SEOSROUTE_RequestAuthcalls with a handle other than SEOSAPI_AUTH_CURRACEE.

ExampleThe following program demonstrates how to use TACF to managethe security aspects of a multi-user process.#include <stdio.h>#include <string.h>#include <memory.h>

#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; }

elseprintf( "Got ACEE handle for user '%s': %d\n", argv[3], usr_acee );

SEOSROUTE_VerifyCreate Function


1.A

uth

orizatio

ns

AP

IG

uid

e

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 );elseprintf( "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;

}elseprintf( "Released ACEE handle for '%s': %d\n", argv[3], usr_acee );

return 0;}

FilesThe 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 AuthorizationThe TACF Authorization API contains a single function formanaging access authorizations. Use theSEOSROUTE_RequestAuth function to check whether a user isauthorized to access a resource in the requested manner. To learnmore how TACF decides whether or not to grant a user access to aspecific resource, see the section pertaining to access rules in theTivoli SecureWay Security Manager User’s Guide.


8 Version 3.7

User AuthenticationThe SEOSROUTE_VerifyCreate function in the TACFAuthorization API is able to authenticate a user. To do so, pass theexisting password, and optionally the new password, to the APIfunction. TACF verifies that the password matches the password ofthe user stored in the TACF database. For users defined to bothTACF and UNIX, TACF can also use standard UNIX accounts in theUNIX environment to verify user passwords.

To use the SEOSROUTE_VerifyCreate function to authenticate auser, TACF must be configured so that TACF password control andmaintenance is enabled. To do this, set the property PASSWORD inthe TACF class. When using the TACF command language, enter thefollowing command:setoptions class+ (PASSWORD)

For more information, see the setoptions command in the TivoliSecureWay Security Manager Reference Manual for TACF.

Note: When TACF password control is enabled, the systemadministrator can take advantage of its format restrictions,aging, and history maintenance. For more information on thepassword control functions provided by TACF, see the TivoliSecureWay Security Manager User’s Guide.

Because TACF does not use the UNIX password, you are able tocreate accounts - users - that can only use servers protected byTACF. These accounts are not valid UNIX accounts and these userswill not have direct access to stations that enable UNIX shellsessions. Therefore, these users will not be able to log ininteractively.

Note: Account names in TACF can be up to 255 characters long.



1.A

uth

orizatio

ns

AP

IG

uid

e

Managing Error MessagesThe Authorizations API includes a function that helps you manageerror messages. When a TACF function fails, it returns an integerrepresenting the reason for the failure (the error code). The functionalso writes the error message that describes the reason for the failurein the szMsg parameter. The SEOSROUTE_ParseApiErrorfunction parses the error message stored in the szMsg parameter andreturns the integer representing the error code. This function isincluded to provide more information (the real error code fromseosd) in case SEOSAPI_AUTH_REMOTE_ERR is returned. Thiswould indicate some error in the seosd daemon.

Compiling and Linking with the TACF Library

Compiling an ApplicationTo compile your application with the TACF library, include theapi_auth.h header file in the C source code that calls the TACFAuthorization API library. You can use any ANSI-C compliantcompiler.

Linking Your Application with the TACF AuthorizationAPI Library

The method used to link your application with the TACFAuthorization API library depends on the operating system you areusing. The following table shows you how to link your applicationwith the TACF Authorization API library. Use these lines togetherwith the rest of the command used by your operating system forlinking an application.

The examples in the following table assume that TACF was installedin the /usr/seos directory. The TACF libraries are therefore assumedto be located in the /usr/seos/lib directory and the TACF header filesin the /usr/seos/include directory.

SEOSROUTE_ParseApiError Function

10 Version 3.7

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 amakefile that can be used to set the various flags that arerequired by each environment.

Compiling and Linking


1.A

uth

orizatio

ns

AP

IG

uid

e


12 Version 3.7

Authorizations API Reference

The Authorizations API consists of the following functions:

Function Description

SEOSROUTE_ParseApiError Converts an error string into theinteger representing the error code.

SEOSROUTE_RequestAuth Checks whether a user is authorizedto access a resource when using thespecified access type.

SEOSROUTE_VerifyCreate Creates an ACEE handle for a user.

SEOSROUTE_VerifyDelete Deletes a user’s ACEE handle.

2


2.A

uth

orizatio

ns

AP

IR

eference

SEOSROUTE_ParseApiError

Synopsisint SEOSROUTE_ParseApiError(const char *szErrMsg);

DescriptionThe ParseApiError function parses the error string returned by theverification and authentication functions and returns the integer valueassociated 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 errorcode from seosd, if the value returned bySEOSROUTE_RequestAuth, SEOSROUTE_VerifyCreate, orSEOSROUTE_VerifyDelete isSEOSAPI_AUTH_REMOTE_ERR.

ArgumentsszErrMsg

The error string that was returned by TACF in the *szMsgparameter.

Return CodesThe integer value of the error message.

SEOSROUTE_ParseApiError Function

14 Version 3.7

SEOSROUTE_RequestAuth

Synopsisint SEOSROUTE_RequestAuth(const char *szClass,

const char *szEntity,int hACEE,SEOS_ACCESS *pAccess,int LogOpt,API_AUTH_RES *pRes,

char *szMsg);

DescriptionThe RequestAuth function asks the TACF authorization daemonwhether the specified user is allowed to access the specified resourcewhen using the specified access type.

The RequestAuth function sends the request to seosd - the TACFdaemon. First seosd checks whether the parameters are valid. If theyare, seosd performs its standard resource authorization check.

Notes:

1. Before calling RequestAuth, a SERVER application normallycalls VerifyCreate to get an ACEE handle for the user whoseauthorization is being checked.

2. When RequestAuth is called with the hACEE parameter set toSEOSAPI_AUTH_CURRACEE, authorization is requested forthe user executing the calling process. TACF does not checkwhether the user has the SERVER attribute. TACF does notcheck whether the process is running under the effective user IDof root.

AuthorizationAll users can use the RequestAuth function. Only SERVERprocesses can use the query for an ACEE other than its own.

ArgumentsszClass

The name of the class to which the resource belongs.

SEOSROUTE_RequestAuth Function


2.A

uth

orizatio

ns

AP

IR

eference

szEntityThe name of the record, or object, representing the resourcebeing accessed.

hACEEThe ACEE handle of the accessor. To specify the ACEE ofthe user associated with the current process, specifySEOSAPI_AUTH_CURRACEE. Specifying an ACEE handleother than SEOSAPI_AUTH_CURRACEE requires theuser associated with the calling process to have the SERVERattribute or the calling process to be running under theeffective user ID of 0 (root).

pAccessA pointer to a structure containing the requested access. Thestructure contains the single data member access of typeSEOS_ACCS. Valid values for this member areSEOS_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.

LogOptA flag that determines whether an audit log entry will bemade. Its values are:

SEOSAPI_AUTH_LOGNONEFor regular uses, if the authorization requestsucceeds, do not create an audit record. If theauthorization request fails, create an audit record, ifthe current rules in the TACF database require it.

For SERVER applications, do not create an auditrecord, regardless of whether the authorizationrequest succeeds or fails.

SEOSAPI_AUTH_LOGIf the current rules in the TACF database require it,create an audit record.

RequestAuth Arguments

16 Version 3.7

SEOSAPI_AUTH_LOGALLFor regular users, this is an invalid option. It will bemapped to SEOSAPI_AUTH_LOG.

For SERVER applications, always create an auditrecord, regardless of the TACF database rules.

SEOSAPI_AUTH_LOGFAILFor regular users, this is an invalid option. It will bemapped to SEOSAPI_AUTH_LOG.

For SERVER applications, create an audit recordonly if the authorization request fails and the TACFdatabase rules require it.

pRes A pointer to a structure containing the authorization result.For more information, see the “API_AUTH_RES Structure”on page 187.

szMsg A status message returned by TACF. The buffer must beSEOSAPI_AUTH_MSGLEN bytes long.

Return CodesAn integer that takes on one of the following values:

SEOSAPI_AUTH_OKAccess is granted.

SEOSAPI_AUTH_BADACCESS_ERRAn invalid access authority was specified.

SEOSAPI_AUTH_DENYThe request was denied.

SEOSAPI_AUTH_NORESPONSE_ERRThe TACF daemon is not responding.

SEOSAPI_AUTH_NOTROOT_ERRThe calling process’s user ID is not 0 (root) and the userexecuting the calling process does not have the SERVERattribute.

SEOSAPI_AUTH_REMOTE_ERRTACF daemon error; a description of the error is provided inszMsg.



2.A

uth

orizatio

ns

AP

IR

eference

See Also“SEOSROUTE_VerifyCreate” on page 19


18 Version 3.7

SEOSROUTE_VerifyCreate

Synopsisint 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);

DescriptionThe VerifyCreate function performs a pseudo-login to TACF andreturns a handle to the ACEE that is created. For programmersfamiliar with MVS, this service is similar to the RACFRACROUTE and RACINIT functions, such as RACROUTEREQUEST=VERIFY.

Notes:

1. The VerifyCreate function is to be used only by a multi-user(SERVER) process that performs services on behalf of otherusers. A single-user process can call the RequestAuth functionwithout first calling the VerifyCreate function.

2. TACF checks and updates the password in the TACF database. Itneither checks nor updates the standard UNIX password.

AuthorizationTo execute the VerifyCreate function, the calling process must haveeffective user ID of 0 or the user associated with the calling processmust have the SERVER attribute.

ArgumentsszUserId

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 NULLpointer is specified, TACF skips the password check.



2.A

uth

orizatio

ns

AP

IR

eference

szNewPwdThe new password, should your application be changing theuser’s password. Specify a NULL pointer if you are notspecifying a new password or if a NULL pointer is specifiedfor szPwd.

ChkFlagsA flag that determines whether the password is to bechecked. The following are all the flag values, and can becombined (using bitwise OR):

VERCRE_CHECK_CURRCheck that the current password is valid.

VERCRE_CHECK_NEWCheck that the new password is valid.

VERCRE_CHECK_QUICKLOGINSimulate login without checking for time restrictions.

szTermThe name of the terminal from which the user logged intothe system.

LogOptA flag that determines whether an audit log entry will bemade. Its values are:

SEOSAPI_AUTH_LOGNONEFor SERVER applications, do not create an auditrecord.

SEOSAPI_AUTH_LOGIf the current rules in the TACF database require it,create an audit record.

SEOSAPI_AUTH_LOGALLFor SERVER applications, always create an auditrecord, regardless of the TACF database rules.

SEOSAPI_AUTH_LOGFAILFor SERVER applications, create an audit recordonly if the authorization request fails and the TACFdatabase rules require it.

VerifyCreate Arguments

20 Version 3.7

phACEEThe ACEE handle returned by TACF. This value is used byTACF in subsequent authorization checks for the currentlyverified user.

pRes A structure containing the authorization result. For moreinformation, see the “API_AUTH_RES Structure” onpage 187.


Return CodesSEOSAPI_AUTH_OK

The user is allowed to access the resource as requested.

SEOSAPI_AUTH_BADPASSWD_ERRThe password does not match the expected password.

SEOSAPI_AUTH_DENYThe request was denied.


SEOSAPI_AUTH_NOTROOT_ERRThe user ID of the calling process is not 0 (root), and theuser executing the calling process does not have theSERVER attribute.

SEOSAPI_AUTH_NOUSERID_ERRA user name was not supplied.

SEOSAPI_AUTH_NULLACEE_ERRThe phACEE parameter is a NULL pointer

SEOSAPI_AUTH_REMOTE_ERRTACF daemon error; a description of the error is provided inszMsg.

See Also“SEOSROUTE_VerifyDelete” on page 22

VerifyCreate Arguments


2.A

uth

orizatio

ns

AP

IR

eference

SEOSROUTE_VerifyDelete

Synopsisint SEOSROUTE_VerifyDelete(int *phACEE,

int bLog,char *szMsg)

DescriptionThe VerifyDelete function releases an ACEE. Use this function torelease ACEEs that were created using the VerifyCreate function.Your application should release ACEEs once they are no longerrequired, because each allocated handle uses system resources andTACF internal resources. These resources are limited.

ArgumentphACEE

A pointer to the handle of the ACEE to be released.

bLog A flag that determines whether an audit log entry will bemade. It can have a value 0 or 1; to create a log entry, setthe parameter to 1.


AuthorizationTo execute the VerifyDelete function, the calling process must haveeffective user ID of 0 or the user associated with the calling processmust have the SERVER attribute.

Return CodesAn integer that takes on one of the following values:

SEOSAPI_AUTH_OKThe ACEE was released.

SEOSAPI_AUTH_NOACEE_ERRThe ACEE to be deleted was not found.


SEOSROUTE_VerifyDelete Functions

22 Version 3.7

SEOSAPI_AUTH_NOTROOT_ERRThe calling process’s user ID is not 0 (root) and the userexecuting the calling process does not have the SERVERattribute.

SEOSAPI_AUTH_NULLACEE_ERRThe phACEE parameter is a NULL pointer.

SEOSAPI_AUTH_REMOTE_ERRTACF daemon error; an error message is placed in szMsg.

See Also“SEOSROUTE_VerifyCreate” on page 19

VerifyDelete Arguments


2.A

uth

orizatio

ns

AP

IR

eference

VerifyDelete Arguments

24 Version 3.7

II — -Exits APIThe Exits API enables you to add your own functions on top of the TACFauthorization and authentication functions. It also enables you to add a specialnotification function to the TACF daemon. Detailed instructions for designing,writing, compiling, and registering your own Exits API functions follow.


26 Version 3.7

Exits API Guide

The Exits API enables you to insert your own functions to beexecuted just before or after TACF authorizes a requested activity.The TACF daemon seosd monitors all system, program, and useractivities. Seosd intercepts every activity and decides whether toauthorize the requested action. You may insert your own registeredfunctions just before (PRE) or after (POST) TACF makes thesedecisions.

For example, you may register a PRE exit function to be executedbefore TACF considers each logon request. Your exit function gainscontrol just before TACF starts to authorize a login request. Aftercompleting its task, your exit function returns control to TACF witha return code indicating your function’s authorization decision. Yourfunction must return one of the return codes described in thefollowing table.

Return Code Description

SEOS_EXITR_CHECK Instructs TACF to perform its own standardauthorization check.

SEOS_EXITR_PASS Instructs TACF to grant the request. TACFdoes not perform its own standard authorizationcheck.

SEOS_EXITR_DENY Instructs TACF to deny the request. TACF doesnot perform its own standard authorizationcheck.

3


3.E

xitsA

PI

Gu

ide

If the decision is SEOS_EXITR_PASS or SEOS_EXITR_DENY,TACF grants or denies the request immediately. If your functionreturns SEOS_EXITR_CHECK, TACF continues with its ownstandard authorization check.

System, program, and user activities that require authorization byTACF are called events. The events that TACF authorizes aredescribed in “TACF Events” on page 32. Events are grouped into thefollowing categories:

¶ Login

¶ General Resource Check

¶ TCP/IP Request

¶ Password Quality Check

¶ Password Change

Exit functions for Password Quality Check or Password Changeevents are linked to the TACF password utility sepass. Exit functionsfor Login, General Resource Check, and TCP/IP Request events arelinked to the TACF daemon seosd. Compiling and linkingprocedures are described in “Compiling and Linking with the TACFapi_authx Library” on page 35.

Creating a New Exit FunctionNew exit functions are added to the TACF seosd program and theTACF sepass program by writing C-language functions that can becompiled and linked to a shared library. The configuration files ofseosd and sepass must be changed to include this new, sharedlibrary. An Exits API function has three parts:

¶ Registration

¶ Implementation

¶ Termination

The registration function initializes your Exits API function andregisters it with the TACF programs. The implementation function

28 Version 3.7

adds your tasks to the standard TACF processing. The terminationfunction unregisters and shuts your program down properly when theTACF programs themselves terminate.

The following diagram describes the flow of the Exits APIinitialization, implementation, and termination.

Your Exits API exit functions take advantage of functions and headerfiles provided by TACF. You use the same registration, initialization,and termination functions for all your exit functions, whether they

Creating a New Exit Function


3.E

xitsA

PI

Gu

ide

link to seosd or sepass. For more information on the pre-definedfunctions in an exit function, see “Exits API Reference” on page 45.

Once your Exits API function is ready, you must bind your new APIto the TACF daemons. For more information on compiling andlinking procedures, see “Compiling and Linking with the TACFapi_authx Library” on page 35.

All Exits API functions use special data structures provided byTACF to pass information back and forth between functions.Programmers need to know the specific formats and data types usedby these structures in order to access the structures correctly in theirown programs. For complete information on these formats and datatypes, see “Structures and Data Types” on page 185.

The input data structure used by your exit function depends on theevent being intercepted by the function. All functions use the sameoutput data structure. The following table lists the data structuresused 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;Password Change

SEOS_EXITPASS Input

All events SEOS_EXITRES Output

If your Exits API function ends in success, your function should fillin the SEOS_EXITRES structure and return 0. If TACF receives asuccessful (0) return code, it checks the result field in theSEOS_EXITRES structure. If the SEOS_EXITRES value is Pass orDeny, it is acted on immediately, and TACF does not execute itsown authorization check. If the result is Check, TACF continueswith its own authorization check.


30 Version 3.7

The following diagram shows this processing.

If your Exits API function ends in failure, your function should fillin the SEOS_EXITRES structure and return a non-zero error code. IfTACF receives a non-zero return code, it adds an entry to the TACFerror log file with the source file name and line number as theyappear in the SEOS_EXITRES structure. The other values set inSEOS_EXITRES are ignored. TACF then continues with its ownauthorization check.

Two sample Exits API functions are provided in this chapter. Theseexamples will help you get started with your own programs. Thefirst example is a simple counter, intercepting every TACFauthorization call and keeping statistics on how often such calls aremade. The second example adds a new restriction to the password



3.E

xitsA

PI

Gu

ide

authorization algorithm of TACF. This exit function stops users fromchoosing the word ‘password’ as their new password.

For more information on the modular design used by TACF thatshould be maintained by your functions, the limits imposed by TACFon Exits API functions, and other information on how to avoidcompile and run-time errors, see “System Design and Limits” onpage 35.

TACF EventsSystem, program, and user activities that require authorization byTACF are called events. The events that TACF authorizes aredescribed in this section. Events are grouped into five categories:

¶ Login


¶ TCP/IP Request

¶ Password Quality Check

¶ Password Change

Exit functions for the Password Quality Check and Password Changeevents are linked to the TACF password utility sepass. Exit functionsfor the Login, General Resource check, and TCP/IP Request eventsare linked to the TACF daemon seosd.

Events Linked to seosdThe following events are registered with seosd:

¶ Login


¶ TCP/IP Request

These events are described below.

The Exits API data structures are used to pass information aboutthese events between functions. These structures are described in“Structures and Data Types” on page 185.


32 Version 3.7

A Login event occurs whenever a user attempts to log in to thesystem. All information relevant to the login attempt is passed to theAPI function. This information includes the name and ID of the userinvolved; the terminal from which the user is trying to log in; andthe device and i-node numbers and the name of the programattempting to perform the login. The information is passed to theExits function in the structure SEOS_EXITLOGIN.

Part of the login authorization process involves a check of whetherthe user is allowed to log in from the terminal from which the loginrequest is received. If a general resource exit function is registered,that exit function is also called as part of the login check.

A General Resource Check event occurs whenever TACF checks theauthorization for any system request except for login and TCP/IPrequests. All information relevant to the system request is passed tothe API function. This information includes the class and resourcename of the object involved; the user ID, user handle, and user nameof the user involved; the device and i-node numbers and the name ofthe program involved; the terminal from which the user is submittingthe request; and the type of access requested. The information ispassed to the function in the structure SEOS_EXITGENR.

A TCP/IP Request event occurs whenever a remote host attempts toconnect to the local host. In this case, there is no informationavailable on the specific user. All information relevant to theconnection attempt is passed to the API function. This informationincludes the host address and name, the type of access requested, thename of the program involved, the port number, and the protocolcode. The information is passed to the function in the structureSEOS_EXITINET.

Events linked to sepassThe Password Quality Check and Password Change events areregistered with the TACF password utility sepass. The Exits APIdata structure SEOS_EXITPASS is used to pass information aboutthese events between functions. For more information on theSEOS_EXITPASS data structure, see “Structures and Data Types” onpage 185.

TACF Events


3.E

xitsA

PI

Gu

ide

A Password Quality Check event occurs whenever a user attempts toenter a new user password. TACF always calls the verify exits (bothpre and post). TACF verifies the password using its built-in featuresonly when users replace their own passwords. All informationrelevant to the attempt to enter a new password is passed to the APIfunction. This information includes the name of the user invokingthe password utility; the name of the user whose password is beingchanged; the user’s old password, if it exists; the user’s newpassword; and the TACF result. Results may be 0 (OK) or 1 (Error).All the information is passed to the function in the structureSEOS_EXITPASS.

A Password Change event occurs whenever a user attempts to updatean existing user password. All information relevant to the updateattempt is passed to the API function. This information includes thename of the user invoking the password utility; the name of the userwhose password is being changed; the user’s new password; andboth the TACF and system results. The information is passed to thefunction in the structure SEOS_EXITPASS.

User InformationThe Exits API functions are passed as much information as possibleabout the user requesting authorization. Depending on what TACFknows about the user, the Exits API function may be given the username, the UNIX user ID number, and the user ACEE handle.

Users may or may not be defined in the TACF database. If the useris defined in the TACF database, TACF has an entry in the AccessorEnvironment Entry (ACEE) table for that user. All entries in theACEE table have an ACEE handle which points to the informationabout that entry. A user not defined in the TACF database is assignedan ACEE handle of -1. Therefore, an ACEE handle of -1 informs theExits API functions that the request did not come from aTACF-defined user.

TACF Events

34 Version 3.7

Compiling and Linking with the TACF api_authxLibrary

This section provides instructions for compiling and linking yourExits API functions with the TACF daemon seosd or the sepassutility. These are general instructions that describe the most commonsystem configurations. Each system has its own specificrequirements. It is impossible to provide exact details for everypossible system configuration. Consult your system manuals for theexact details of your particular system’s compiler and linker options.

Compiling an ApplicationYou must include the header files authxapi.h and seostype.h in yourExits API functions. These files are located in the includesubdirectory. Put the following two lines near the top of the file:#include <authxapi.h>#include <seostype.h>

It is recommended that you use an ANSI-C compliant compiler.

Linking Your Application with TACFBecause the target of your code is a shared library, you may need touse compiler flags to determine the correct code generation method.The examples provided by TACF will help you find the appropriateflag for each platform.

System Design and Limits

Modular DesignTACF is completely modular in design and implementation.Management of resources is also completely modular. Most of thesystem objects that TACF protects are considered general resources.A class is a family of resources that share the same attributes. Forexample, an attempt to open a file is considered an access request toa resource of class FILE. An attempt to substitute (su) to anotheruser is considered an access request to a resource of classSURROGATE. Grouping resources in this manner allows TACF touse a single general authorization algorithm.



3.E

xitsA

PI

Gu

ide

Your Exits API functions must maintain the same modular approachas the TACF functions described above. The Exits API functions arecalled whenever there is an attempt to access a specified resource.Your functions must use a modular algorithm that works consistentlyfor an entire class and does not interfere with or generate errors forother classes. For more information on classes, properties, andresources, see the Tivoli Security Management User’s Guide.

Note: TACF constantly receives authorization requests from systemevents and user programs. These requests may be redirectedto your exit function. Make sure that your function isoptimized and terminates as quickly as possible to minimizesystem overhead. Special care must be taken when writingexit functions. You cannot write an exit function and leavedebugging for run-time. A trivial bug can bring down yoursystem!

Configuration FilesAfter you compile your code, generate a shared library that containsthe compiled version of your code. The API subdirectory containssample LogRoute functions and a makefile demonstrating theprocess. Note that compilation for shared libraries usually requiresadditional compiler parameters to create position-independent code.Consult your compiler/linker documentation to learn how to createshared libraries in your particular system.

After you have written your code and created a shared library, addyour shared library to the ‘on-demand’ shared libraries configurationfile relevant to the program to which your code should link.

If you have written a shared library for one of the followingdaemons or programs, add your shared library to the relevant file.

For daemon: Add shared library to: Write initialization anduninitialization functions:

seosd /usr/seos/etc/seosd.ext <driver>_RegisterExit<driver>_UnregisterExit

sepass /usr/seos/etc/sepass.ext <driver>_InitializeExits<driver>_ShutDownExits


36 Version 3.7

Each configuration file contains two columns: the driver name andthe shared library path. The driver name can be any valid Clanguage symbol. For example, if you have written code toimplement a pager extension for seosd and the driver name is pager,the complete file entry in /usr/seos/etc/seosd.ext would be:pager /usr/local/lib/libseospager.so

This file entry means that the daemon seosd will load the sharedlibrary /usr/local/lib/libseospager.so at startup and call yourpager_RegisterExit function.

Although some systems support a pre-defined function called _init,it is recommended that you use the indicated initialization functionto initialize and register your driver. This is really the first functioncalled from the shared library.

On daemon shutdown, it is recommended that you use the indicateduninitialization function instead of the pre-defined function _fini.

Note: Using the TACF functions instead of the pre-defined systemfunctions gives your code greater portability.

System CallsSince TACF intercepts operating system calls, not all systemactivities can be allowed while you are in the midst of anauthorization action. The following table lists functions, whichcannot be called from an Exits API function of seosd.



3.E

xitsA

PI

Gu

ide

Environment Functions

NIS or DNS servers running TACF;Solaris 2.5x and above

getgrentgetgrgidgetgrnamgethostbyaddrgethostbynamegethostentgetnetbyaddrgetnetbynamegetnetentgetprotobynamegetprotobynumbergetprotoentgetpwentgetpwnamgetpwuidgetservbynamegetservbyportgetservent

Any station running TACF getrpcbynamegetrpcbynumbergetrpcent

Error CodesTACF uses an error code defined as an integer, composed of twobytes. The MSB contains a layer code and the LSB contains an errorcode specific to that layer. This allows up to 256 different layerswith 256 different error codes each. To simplify error codemanagement, TACF uses the macro _SEOS_RC. The Exits API alsouses the macro AUTHXAPI_MODULE to define the layer code. Donot use these macros yourself in your code or you may havecompilation problems.

Return CodesTACF uses the following convention for return codes: A return valueof zero indicates success; any other value indicates an error.


38 Version 3.7

Exits API ExamplesThe API subdirectory contains the API header files and the libraryfunctions. The TACF package also includes the following twosample programs demonstrating the use of the Exits API.

TACF Daemon ExitsThe following program calls a special user-defined exit functionupon any action by the TACF daemon. The function keeps statisticson the number of times each action is executed. When the functionsenses a login for user root it simply prints the information gathered.A more detailed explanation of the main points of this functionfollows the source code.#define __SEOSEXIT_C

#include <sys/types.h>#include <stdio.h>#include <string.h>#include <memory.h>

#if defined(_SUNOS)/* printf does not have a prototype in SunOS */extern int printf(const char *fmt, ...);

#endif

/* authx API header file */#include <authxapi.h>

/* This an example of an exit module in TACF.* The module only ‘printf’ the information and* gathers statistics on the number of events.* When the ‘root’ user logs in the statistics* are printed.*/

typedef struct{ int nPreRes;

int nPostRes;int nPreLogin;int nPostLogin;int nPreInet;int nPostInet;

} EXIT_CALLS_COUNTERS;

static EXIT_CALLS_COUNTERS counters;

Exits API Examples


3.E

xitsA

PI

Gu

ide

static void print_my_statistics(void){

printf(“General Resource ... Pre %6d Post %6d\n”“Login .............. Pre %6d Post %6d\n”“Internet TCP ....... Pre %6d Post %6d\n”,counters.nPreRes, counters.nPostRes,counters.nPreLogin, counters.nPostLogin,counters.nPreInet, counters.nPostInet );

}

static intExitFunc_PreResource(void *data, SEOS_EXITRES *p_sexr){

SEOS_EXITGENR *ptr;

ptr = (SEOS_EXITGENR *)data;counters.nPreRes++;printf(“Pre General Resource Class %s\n”, ptr->szClass);return 0;

}

static intExitFunc_PostResource(void *data, SEOS_EXITRES *p_sexr){

SEOS_EXITGENR *ptr;

ptr = (SEOS_EXITGENR *)data;counters.nPostRes++;printf(“Post General Resource Class %s\n”, ptr->szClass);return 0;

}

static intExitFunc_PreLogin(void *data, SEOS_EXITRES *p_sexr){

SEOS_EXITLOGIN *p_sexl;char buff[20];char const *p;

p_sexl = (SEOS_EXITLOGIN *)data;counters.nPreLogin++;if (p_sexl->szUname == NULL)

{ p = buff; sprintf(buff, “UID=%u”, p_sexl->luid); }else

p = p_sexl->szUname;

Exits API Examples

40 Version 3.7

printf(“Pre Login For %s\n”, p);

/* Print the statistics for root */if (p_sexl->luid == (uid_t)0)

print_my_statistics();return 0;

}

static intExitFunc_PostLogin(void *data, SEOS_EXITRES *p_sexr){ SEOS_EXITLOGIN *p_sexl;

char buff[20];char const *p;

p_sexl = (SEOS_EXITLOGIN *)data;counters.nPostLogin++;if (p_sexl->szUname == NULL)

{ p = buff; sprintf(buff, “UID=%u”, p_sexl->luid); }else

p = p_sexl->szUname;printf(“Post Login For %s\n”, p);

/* Print the statistics for root */if (p_sexl->luid == (uid_t)0)

print_my_statistics();return 0;

}

static intExitFunc_PreInet(void *data, SEOS_EXITRES *p_sexr){

/* Don’t do too much work on TCP */counters.nPreInet++;return 0;

}

static intExitFunc_PostInet(void *data, SEOS_EXITRES *p_sexr){

/* Don’t do too much work on TCP */counters.nPostInet++;return 0;

}

intsample_RegisterExit(void)

Exits API Examples


3.E

xitsA

PI

Gu

ide

{int rc;

memset(&counters, 0, sizeof(counters) );

rc = authxapi_RegisterExitFunction(AUTHXAPI_EV_PREGNRES,ExitFunc_PreResource);

if (rc)return rc;

rc = authxapi_RegisterExitFunction(AUTHXAPI_EV_POSTGNRES,ExitFunc_PostResource);

if (rc)return rc;

rc = authxapi_RegisterExitFunction(AUTHXAPI_EV_PRELOGIN,ExitFunc_PreLogin);

if (rc)return rc;

rc = authxapi_RegisterExitFunction(AUTHXAPI_EV_POSTLOGIN,ExitFunc_PostLogin);

if (rc)return rc;

rc = authxapi_RegisterExitFunction(AUTHXAPI_EV_PREINET,ExitFunc_PreInet);

if (rc)return rc;

rc = authxapi_RegisterExitFunction(AUTHXAPI_EV_POSTINET,ExitFunc_PostInet);

return rc;}

voidsample_UnregisterExit(void){

/* We don’t have anything to do in this example */}

The authxapi.h header file contains the prototypes and definitionsrequired to use the API. The code declares a new typeEXIT_CALLS_COUNTER. This structure consists of counters foreach event the API registers. A static variable of this new local typeis declared. The General Resource and Internet Access functionslisted are simple counters. The Login functions have the samecounters and also compare the user ID of the logged in user to 0.

Exits API Examples

42 Version 3.7

The Login functions take advantage of the fact that the UNIX userID for root is 0 to avoid fetching the real user information fromsystem databases.

Note: This example prints to the screen. TACF daemons should notuse screen output as it causes a significant decline inperformance.

Password Utilities ExitsThe following code demonstrates a simple user exit function forpassword verification. This code compares the potential password tothe string “password” and denies permission to choose the passwordif a match is found./* Example of using password library to extend password rules. *//* This function verifies the password before TACF verifies it. *//* To override TACF checks, use result SEOS_EXITR_PASS. *//* Look at Makefile.exits for compilation options. */

#include <API/authxapi.h>

/* This function does not allow the user to use the word "password" *//* as the new password. */int ExitFunc_PreVerify(void *sexp, SEOS_EXITRES *sexr){if (strcmp(((SEOS_EXITPASS *)sexp)->szPass,"password") == 0){printf("new password is refused by exit function\n");sexr->result = SEOS_EXITR_DENY;

/* Do not allow the password to be “password” */}elsesexr->result = SEOS_EXITR_CHECK; /* Continue with TACF checks */

return 0;}

/* Must register the above exit function */int authxapi_InitializeExits(void){int rc;

rc = authxapi_RegisterExitFunction(AUTHXAPI_EV_PREVERPWD,ExitFunc_PreVerify);if (rc) return rc;

}

void authxapi_ShutDownExits(void){/* Nothing really to do in this case */}

Exits API Examples


3.E

xitsA

PI

Gu

ide

Exits API Examples

44 Version 3.7

Exits API Reference

The following functions provided by TACF can be used to buildyour own Exits API functions. The TACF functions are groupedaccording to the following categories:

Category Description

General functions These functions are used by all Exits APIfunctions, whether they are linked to theTACF daemon seosd or linked to theTACF password daemon sepass. The tasksperformed by these functions includeregistration, deregistration, initialization,and termination.

Database interface functions These are database interface functionsapplicable only to Exits API functionslinked to seosd.

Shared library functions Functions which must be located in ashared library.

General Functions


authxapi_IsThereExitFunction Check if an Exits API function fora specific event has been registeredwith TACF.

4


4.E

xitsA

PI

Referen

ce


authxapi_RegisterExitFunction Register your new Exits APIfunction with TACF.

authxapi_UnRegisterExitFunction Remove an Exits API function thatwas previously registered withTACF.

Database Interface Functions


authxapi_FreeListValues Free the memory allocated during aprevious call toauthxapi_GetObjectListValue.

authxapi_GetObjectListValue Retrieve the values of a list valueproperty from a TACF database object.

authxapi_GetObjectProperty Retrieve the value of a single valueproperty from a TACF database object.

authxapi_GetUserInfo Retrieve user name when given a userhandle from an Exits API function.

Shared Library Functions


<driver>_RegisterExit Function provided by the extension and iscalled on startup of seosd.

<driver>_UnregisterExit Function provided by the extension and iscalled on shutdown of seosd.

<driver>_InitializeExits Function provided by the extension and iscalled on startup of sepass.

<driver>_ShutDownExits Function provided by the extension and iscalled on shutdown of sepass.

The data structures used by these functions are described in“Structures and Data Types” on page 185.

Function Definitions

46 Version 3.7

authxapi_RegisterExitFunction

Synopsisint authxapi_RegisterExitFunction (int event,

PFSeosExitFunc user_func);

DescriptionThe authxapi_RegisterExitFunction function registers an exitfunction for a specific event. Registration should be handled duringprogram startup and program shutdown, although it can beperformed at any stage.

Argumentsevent Code of the event to which your Exits API function is

registered. Password events are available only when linkedto the TACF password utility. General system events areavailable only when linked to the TACF daemon. Thepossible values of the parameter event are shown in thefollowing list:

AUTHXAPI_EV_PRELOGINpre-login event

AUTHXAPI_EV_POSTLOGINpost-login event

AUTHXAPI_EV_PREGNRESpre-general resource event

AUTHXAPI_EV_POSTGNRESpost-general resource event

AUTHXAPI_EV_PREINETpre-TCP verification event

AUTHXAPI_EV_POSTINETpost-TCP verification event

AUTHXAPI_EV_PREVERPWDpre-password quality verification event

AUTHXAPI_EV_POSTVERPWDpost-password quality verification event



4.E

xitsA

PI

Referen

ce

AUTHXAPI_EV_PRESETPWDpre-password set event

AUTHXAPI_EV_POSTSETPWDpost-password set event

Note: Although it is possible to register a passwordverification event in the TACF daemon, seosd doesnot call the password verification exit functions.

user_funcPointer to the user function that TACF should call when thespecified event occurs.

Return CodesThe function returns 0 on success.

If it fails, the function sets the global variable errno and returns oneof the following error codes:

Return code(ERRNO) Meaning

AUTHXAPI_E_OCCUPIED(EEXIST) Event already was registered

AUTHXAPI_E_NOEVENT(EINVAL) Invalid event code

ExamplesRegistering a user’s exit function./* Sample function to deny all login attempts of user 'jsmith' */int MyExitFunc(void *exit_data, SEOS_EXITRES *res){

SEOS_EXITLOGIN *login_data;

login_data = (SEOS_EXITLOGIN *)exit_data;if (login_data->szUname != NULL)

{if ( strcmp(login_data->szUname, "jsmith") )

return 0;res->result = SEOS_EXITR_DENY;

}return 0;

}


48 Version 3.7

/* The function TACF looks for when initializing the extension. */int sample_RegisterExit(void)

{return authxapi_RegisterExitFunction(AUTHXAPI_EV_PRELOGIN,

MyExitFunction);}

See Also“authxapi_UnRegisterExitFunction” on page 50



4.E

xitsA

PI

Referen

ce

authxapi_UnRegisterExitFunction

Synopsisint authxapi_UnRegisterExitFunction (int event);

DescriptionThe authxapi_UnregisterExitFunction function unregisters yourexit function from TACF.

Argumentsevent Integer code of the event to which your Exits API function is

registered. For more information, see“authxapi_RegisterExitFunction” on page 47.


If it fails, it sets the global variable errno to EINVAL and returnsAUTHXAPI_E_NOEVENT, meaning that the event code passed wasinvalid.

ExamplesUnregistering user’s exit function....

rc = authxapi_UnregisterExitFunction(AUTHXAPI_EV_PRELOGIN);if (rc){

syslog(LOG_ERR,"Unexpected error unregistering exit function [%m]");

}...

See Also“authxapi_RegisterExitFunction” on page 47

authxapi_UnRegisterExitFunction

50 Version 3.7

authxapi_IsThereExitFunction

Synopsisint authxapi_IsThereExitFunction (int event);

DescriptionThe authxapi_IsThereExitFunction function determines whether anexit function has been registered for a specific event.

Argumentsevent Integer code of the event being checked. For more

information, see “authxapi_RegisterExitFunction” on page 47.

Return CodesIf the exit function does exist, it returns TRUE (1). If the exitfunction does not exist, it returns FALSE (0).

ExamplesChecking if the exit function exists.{

int rc;...rc = authxapi_IsThereExitFunction(AUTHXAPI_EV_PRELOGIN);if (rc)

printf("There is a pre-login exit function\n");else

printf("There is no pre-login exit function.\n");}

See Also¶ “authxapi_RegisterExitFunction” on page 47

¶ “authxapi_UnRegisterExitFunction” on page 50

authxapi_IsThereExitFunction


4.E

xitsA

PI

Referen

ce

authxapi_GetObjectProperty

Synopsisint authxapi_GetObjectProperty (const char *szClass,

const char *szObj,SEOSDB_ODF *p_odf,const char *szProp,SEOSDB_PDF *p_pdf,void *val,

int *size);

DescriptionThe authxapi_GetObjectProperty function retrieves the value of asingle-value property of an object stored in the TACF database.Properties which have multiple values, such as lists, cannot beretrieved with this function. You can retrieve property lists withauthxapi_GetObjectListValue. All parameter strings must be NULLterminated.

Notes:

1. If the szObjparameter is NULL, the function assumes p_odf ispointing to a valid object descriptor obtained from a previous callto one of the get functions provided by the Exits API. Thisspeeds up processing when you are dealing with a series ofobjects that share the same object descriptor, since you do notspend time repeatedly fetching the same object descriptor.

While it is faster to use an object descriptor rather than an objectname, it is not safe to store the object descriptors in globalvariables and use them in later calls to this function, as updatesto the database may delete these objects.

2. If the szProp parameter is NULL, the function assumes p_pdf ispointing to a valid property descriptor obtained from a previouscall to one of the get functions provided by the Exits API. Thisspeeds up processing when you are dealing with a series ofobjects that share the same property descriptor, since you do notspend time repeatedly fetching the same property descriptor.

It is safe to store property descriptors in global variables and usethem in later calls to this function, since property definitions arenot subject to change while the TACF daemon is active.

authxapi_GetObjectProperty Function

52 Version 3.7

ArgumentsszClass

The name of the class to which the resource belongs.

szObj The name of the object - record - whose property value youwish to retrieve.

p_odf Points to an object descriptor fetched by this function orprovided by the caller from a previous call to an Exits APIget function.

szProp The name of the property whose value you wish to retrieve.

p_pdf A pointer to a property descriptor fetched by this function orprovided by the caller from a previous call to an Exits APIget function.

val A pointer to a variable that is filled with the value of theproperty. The caller should provide a pointer to a variablethat is of the same type as the property’s data type.

size Size in bytes of the region in memory to which the valparameter is pointing.

Return CodesThe function returns 0 on success. If it fails, the function sets theglobal variable errno and returns one of the following error codes:


AUTHXAPI_E_EINVAL(EINVAL) Invalid (NULL) pointers.

AUTHXAPI_E_INVOBJ(EINVAL) Invalid object descriptor.

AUTHXAPI_E_INVPROP(EINVAL) Invalid property descriptor.

AUTHXAPI_E_NOCLASS(ENOENT) Required class not found.

AUTHXAPI_E_NOOBJ(ENOENT) Required object not found.



4.E

xitsA

PI

Referen

ce

AUTHXAPI_E_NOPROP(ENOENT) Required property not found.

AUTHXAPI_E_PTYPE(EINVAL) Property type is a list.

AUTHXAPI_E_DBERROR(EIO) Suspect corruption of database.

AUTHXAPI_E_NOVAL(ENOENT) No value for property associated with thisobject.

ExamplesFetching a value from the TACF database.#include <stdio.h>#include <authxapi.h>#include <seostype.h>

int MyExitFunction(void *exit_data, SEOS_EXITRES *result){

SEOS_EXITGENR *genr_data;SEOSDB_ODF odf;SEOSDB_PDF pdf;SEOS_COMMENT comment;int rc;

genr_data = (SEOS_EXITGENR *)exit_data;

/* Ignore any class that is not of interest */if ( strcmp(genr_data->szClass, "MyClass") )

return 0;

/* Fetch the information for the COMMENT property of the *//* resource to which access is verified. */rc = authxapi_GetObjectProperty("MyClass", genr_data->szRes,

&odf, "COMMENT", &pdf, comment, sizeof(comment) );

if (rc == 0){

/* We now have the comment string. See if it contains " NO " */if ( strstr(comment, " NO ") != NULL){

result->result = SEOS_EXITR_DENY;}

}return 0;

}


54 Version 3.7

This example, part of an exit function for a general resource,retrieves a value stored in the TACF database. The exit functionchecks that the request is for the correct resource class. Other classesare ignored. The authxapi_GetObjectProperty function is called toretrieve the value for the COMMENT property. If the retrieval wassuccessful, the function tests if the string contains the substring “NO “ (<blank>NO<blank>). If so, the request is denied. Otherwisethe function returns control to TACF which performs its standardchecks.

Note: To update the COMMENT field from the TACF commandinterpreter you should use the comment argument. Forexample:newres MyClass anobject \comment('This object has NO in the comment property')

See AlsoFor more information on the TACF database, see the Tivoli SecurityManagement User’s Guide.



4.E

xitsA

PI

Referen

ce

authxapi_GetObjectListValue

Synopsisint authxapi_GetObjectListValue (const char *szClass,

const char *szObj,SEOSDB_ODF *p_odf,const char *szProp,SEOSDB_PDF *p_pdf,void ***val,unsigned int *psize,unsigned int *count);

DescriptionThe authxapi_GetObjectListValue function retrieves a list of valuesassigned to a property of an object stored in the TACF database.Properties which have single values cannot be retrieved with thisfunction. To retrieve single value properties, useauthxapi_GetObjectProperty.

The authxapi_GetObjectListValue function allocates a vector ofvoid pointers, each pointing to an allocated buffer that holds a singleelement in the list of values. Declare a list variable of any type as apointer to a pointer, such as int **. A pointer to this list variable isthen passed into authxapi_GetObjectListValue, typecast as a (void***). For example:{int **list;

unsigned int psize, count;int rc;...rc = authxapi_GetObjectListValue(.., (void ***)&list, \

&psize, &count);...

}

When authxapi_GetObjectListValue returns, the list variable pointsto a newly allocated area of memory containing the pointers, storedsequentially from zero to count, pointing to each list item. Each listitem is stored in yet another newly allocated memory area. Be sureto use authxapi_FreeListValues to free all the memory allocated byauthxapi_GetObjectListValue.

authxapi_GetObjectListValue Function

56 Version 3.7

For example, when you have a list of N data elements, your memoryis allocated as follows:

ArgumentsszClass

The name of the class the object belongs to.

szObj The name of the object whose property value you wish toretrieve.

Note: If this parameter is NULL, the function assumesp_odf is pointing to a valid object descriptor obtainedfrom a previous call to one of the get functionsprovided by the Exits API. This speeds up processingwhen dealing with a series of objects that share thesame object descriptor, because you do not spend timerepeatedly fetching the same object descriptor.

p_odf A pointer to an object descriptor fetched by this function orprovided by the caller from a previous call to an Exits APIget function.

Note: While it is faster to use an object descriptor ratherthan an object name, as explained in the precedingtip, it is not safe to store the object descriptors inglobal variables and use them in later calls to thisfunction, as updates to the database may delete theseobjects.

szProp The name of the property whose values you wish to retrieve.



4.E

xitsA

PI

Referen

ce

Note: If this parameter is NULL, the function assumesp_pdf is pointing to a valid property descriptorobtained from a previous call to one of the getfunctions provided by the Exits API. This speeds upprocessing when dealing with a series of objects thatshare the same property descriptor, because you donot spend time repeatedly fetching the same propertydescriptor.

p_pdf A pointer to a property descriptor fetched by this function orprovided by the caller from a previous call to an Exits APIget function.

Note: It is safe to store the property descriptors in globalvariables and use them in later calls to this function,as property definitions are not subject to change whilethe TACF daemon is active.

val A pointer to a variable that is assigned the memory addressof an array of pointers. The array of pointers points to thedata values being retrieved. Theauthxapi_GetObjectListValue function allocates thememory used here.

psize Size in bytes of the region in memory allocated to eachelement in the value list.

count The number of elements in the value list. May be zero if noelements are found.


If it fails, the function sets the global variable errno and returns oneof the following error codes:




58 Version 3.7






AUTHXAPI_E_PTYPE(EINVAL) Property type is not a list.



ExamplesThe following Exits API function retrieves a list of values from alist-type property of a resource from the TACF database, then loopsthrough the list of values. The code that actually uses theinformation retrieved is not shown.#include <stdio.h>#include <authxapi.h>#include <seostype.h>

int MyExitFunction(void *exit_data, SEOS_EXITRES *result){

SEOS_EXITGENR *genr_data;SEOSDB_ODF odf;SEOSDB_PDF pdf;SEOS_ACL **access_list, *acl_element;int rc;unsigned int psize, count, counter;

genr_data = (SEOS_EXITGENR *)exit_data;

/* Ignore any class that is not of our concern */



4.E

xitsA

PI

Referen

ce

if ( strcmp(genr_data->szClass, "MyClass") )return 0;

/* Fetch the information for the ACL property of the *//* resource being accessed. */rc = authxapi_GetObjectListValue("MyClass", genr_data->szRes, \

&odf,"ACL", &pdf, (void ***)access_list, &psize, &count);

if (rc == 0){

/* We have the ACL now. Let’s just see a demonstration *//* of looping through the list. */for(counter=0; counter < count; counter++){

acl_element = access_list[counter];/** > > > User Code Here < < <*/

}authxapi_FreeListValues((void ***)&access_list, &count);

}return 0;

}

See Also¶ “authxapi_FreeListValues” on page 61

¶ “authxapi_GetObjectProperty” on page 52


60 Version 3.7

authxapi_FreeListValues

Synopsisint authxapi_FreeListValues (void ***value,

unsigned int *count);

DescriptionThe authxapi_FreeListValues function frees the memory allocatedwhen a list of values was retrieved during a previous call to theauthxapi_GetObjectListValue function.

Argumentsvalue A pointer to the list of values held in memory. Set to NULL

when memory is successfully freed.

count The number of elements in the value list. May be zero if noelements are found. Set to zero when memory is successfullyfreed.


If it fails, the function sets the global variable errno to EINVAL andreturns an error code AUTHXAPI_E_EINVAL, indicating that one ofthe pointers passed in was NULL.

ExamplesSee “authxapi_GetObjectListValue” on page 56

See Also“authxapi_GetObjectListValue” on page 56

authxapi_FreeListValues Function


4.E

xitsA

PI

Referen

ce

authxapi_GetUserInfo

Synopsisint authxapi_GetUserInfo (int seos_handle,

char *uname,int *size);

DescriptionThe authxapi_GetUserInfo function retrieves a user name whengiven a TACF user’s ACEE handle.

Argumentsseos_handle

The handle of the user whose user name you are requesting.

uname Buffer large enough to contain the user name being returned.Some UNIX systems allow no more than eight characters pername. Other UNIX systems (and TACF itself) allow manymore.

size On entry, the size in bytes of the memory area pointed to byuname. On return, the length of the user name string.


If it fails, it sets the global variable errno and returns one of thefollowing error codes:






authxapi_GetUserInfo Function

62 Version 3.7



AUTHXAPI_E_PTYPE(EINVAL) Property type is a list.



ExamplesGetting user name string.{

int rc;char name[256];int size;...size = sizeof(name);rc = authxapi_GetUserInfo(seos_handle, name, &size) );...

}

See AlsoFor more information on the TACF database, see the Tivoli SecurityManagement User’s Guide.



4.E

xitsA

PI

Referen

ce


64 Version 3.7

III — -LogRoute APIThe LogRoute API enables you to add your own alerts to the standard TACF auditlog functions. You can also use the LogRoute daemon to add a guaranteed-deliveryfeature to your other programs. Details of the configuration file read by selogrd, thestructures and functions used with writing a new LogRoute API, the compile andlink procedures used under most operating systems, and a sample LogRoute APIfunction are included. The LogRoute API enables you to insert your own alerts inthe TACF audit log file. The TACF daemon seosd generates audit information andstore it in the audit log file. The LogRoute daemon selogrd polls the audit log fileand sends selected local audit log records to the destination targets listed in theTACF configuration file. Destination targets may be screen or mail messages to anindividual user, a local system file, or files located on remote host systems on thenetwork.


66 Version 3.7

LogRoute API Guide

Customizing selogrdYou add user-defined features to the TACF LogRoute daemons bywriting C-language programs that can be compiled and bound into ashared library. A LogRoute API function has three parts:

¶ Registration

¶ Implementation

¶ Termination

Registration initializes your LogRoute API function and registers itwith the TACF daemons. Implementation adds your tasks to thestandard TACF LogRoute daemon process. Termination unregistersand shuts down your program properly when the TACF daemonsthemselves terminate.

Your LogRoute API function takes advantage of functions andheader files provided by TACF. The predefined functions used in aLogRoute function are described in “LogRoute API Reference” onpage 79. You use the same registration, implementation, andtermination functions for all your LogRoute functions.

Once your LogRoute API function is ready, you can add your sharedlibrary to the TACF LogRoute daemon configuration file. For moreinformation on compiling and linking procedures, “Compiling andLinking with the TACF LogRoute Library” on page 69.

5


5.L

og

Ro

ute

AP

IG

uid

e

The TACF LogRoute daemons use a configuration file to determinewhich audit log records to select and where to send those records.You may edit the configuration file to route specific auditinformation to a variety of selected targets supported by theLogRoute daemon. For more information on the syntax of theconfiguration file, see the selogrd utility in the Tivoli SecureWaySecurity Manager Reference Manual for TACF.

The LogRoute API functions use special data structures. For moreinformation on these formats and data types, see “Structures andData Types” on page 185.

A sample LogRoute API function is provided on page Example. Thesample program demonstrates adding the new destination targetsyslog to TACF. The syslog target enables you to send auditinformation to UNIX system logs.

Predefined LogRoute API FunctionsYour LogRoute API function uses built-in functions and header filesprovided by TACF. TACF provides the following pre-definedfunctions:

¶ Selogrd functions:

v <driver>_RegisterDestination

v <driver>_UnregisterDestination

v lograpi_InterpretRecord

v lograpi_MakeStringMessage

v lograpi_RegisterTargetType

v lograpi_UnregisterTargetType

¶ Selogrcd functions:

v <driver>_Register

v <driver>_UnRegister

v servlog_IsThereExit

v servlog_RegisterExit

Customizing selogrd

68 Version 3.7

v servlog_UnRegisterExit

¶ All LogRoute API functions must also include the followingfunctions for each destination type implemented:

v LogrApiSenseFunc

v LogrApiSendFunc

v LogrApiFreeFunc

The functions LogrApiSenseFunc, LogrApiSendFunc, andLogrApiFreeFunc are grouped together in the LOGRAPI_FUNCSstructure. These functions are accessed using the pointers pfSend,pfFree, and pfSense. The API programmer must provide the codeused for each of these functions, since each one is completelytask-dependent.

Compiling and Linking with the TACF LogRouteLibrary

This section provides instructions for compiling and linking yourLogRoute API function with the TACF daemons. These are generalinstructions that describe the most common system configurations.Each system has its own specific requirements. Consult yoursystem’s manuals for the exact details of your particular system’scompiler and linker.

Compiling an ApplicationYou must include the header files lograpi.h and selogtype.h in yourLogRoute API functions. These files are located in the APIsubdirectory. Include near the top of the file the following two lines:#include <lograpi.h>#include <selogtype.h>

You may use any ANSI-C compliant compiler. The compilationshould generate a shared library.

Linking Your Application with TACFAfter you compile your code, generate a shared library that containsthe compiled version of your code. The API subdirectory containssample LogRoute functions and a makefile demonstrating the

Predefined LogRoute API Functions


5.L

og

Ro

ute

AP

IG

uid

e

process. Note that compilation for shared libraries usually requiresadditional compiler parameters to create position-independent code.Consult your compiler/linker documentation to learn how to createshared libraries in your particular system.

After you have written your code and created a shared library, addyour shared library to the ‘on-demand’ shared libraries configurationfile relevant to the program your code should link to.

If you have written a shared library for one of the followingdaemons or programs, add your shared library to the relevant file.

For daemon: Add shared library to: Write initialization anduninitialization functions:

selogrd /usr/seos/etc/selogrd.ext <driver>_Register Destination<driver>_UnRegisterDestination

selogrcd /usr/seos/etc/selogrcd.ext <driver>_Register<driver>_UnRegister

Each configuration file contains two columns: the driver name andthe shared library path. The driver name can be any valid Clanguage symbol. For example, if you have written code toimplement a pager extension for selogrd and the driver name ispager, the complete file entry in /usr/seos/etc/selogrd.ext would be:pager /usr/local/lib/libseospager.so

This file entry means that the daemon selogrd will load the sharedlibrary /usr/local/lib/libseospager.so at startup and call yourpager_RegisterDestination function.

Although some systems support a pre-defined function called _init,it is recommended that you use the indicated initialization functionto initialize and register your driver.This is really the first functioncalled from the shared library.

On daemon shutdown, it is recommended that you use the indicateduninitialization function instead of the pre-defined function _fini.


70 Version 3.7

Note: Using the TACF functions instead of the pre-defined systemfunctions gives your code greater portability.

The daemon selogrcd uses the same file configuration format asselogrd. However, selogrcd searches for the functions<driver>_Register and <driver>_UnRegister. If the function<driver>_UnRegister is not required, it may be omitted.

Format of the Log FileThe format in which TACF writes the auditing log is not publiclyavailable. However, it is essential that programmers using this APIunderstand the basics of the audit log file’s format. The informationprogrammers need to know is provided in this section.

The audit log file is composed of a file header followed by recordssequentially written to the file. Each record is composed of a recordheader followed by information specific to the record. The header ofeach record includes information about the time the record wasplaced in the file, the record type - a code known only by theapplication - and the size of the record which follows the header.The data itself is written in a compressed format; the record sizespecified in the record header is the size in bytes of the compresseddata. The format of the file is shown schematically in the followingdiagram:

The programmer using this API does not need to know thecompression algorithm or the exact format of the file. Informationpassed to a user application is placed in structures in uncompressedformat. Your application simply retrieves the information from thestructure. For more information on the LogRoute API structures, see“Structures and Data Types” on page 185.



5.L

og

Ro

ute

AP

IG

uid

e

ExampleThe API subdirectory under the local TACF directory contains theAPI header files and the library functions. The TACF package alsoincludes the following sample program demonstrating LogRoute APIuse.

Adding the destination target “syslog”The following example demonstrates adding the destination targetsyslog to TACF to send audit information to UNIX system logs.


72 Version 3.7

#define __LOGRSAMPLE_C

#include <syslog.h>#include <string.h>

#include <lograpi.h> /* Include the.h file required by API */

#ifndef NULL#define NULL (void *)0#endif

/* Prototypes for our local functions */

static intsample_Sense(SEOS_ROUTENTRY *pre);static voidsample_Free(SEOS_ROUTENTRY *pre);

static intsample_Send(LOGRECORD *plr, SEOS_ROUTENTRY *pre, int notify,

void *data);

/** We don't use the code of the new route type target, but if we wanted* more than one target type, we could use it to distinguish between* the two.*/

static int our_dest_type_code;

/** Here we preserve the syslog priority required by the configuration* file. This of course means that by storing it in a global variable* we provide only one route line in the configuration file* for syslog. Other lines will just overwrite this variable.*/

static int syslog_priority;

/* This is the function called by selogrd. */

int syslog_RegisterDestination(void){

static LOGRAPI_FUNCS funs ={

sample_Send, sample_Free, sample_Sense};



5.L

og

Ro

ute

AP

IG

uid

e

return lograpi_RegisterTargetType("syslog", &funs,&our_dest_type_code);

}static int sample_Sense(SEOS_ROUTENTRY *pre){ register int i;

/* This function tests if the path specified for the target* is correct. In our sample, the path is actually the* syslog priority. This function compares the priority* specified in the path field of the route line* to the known syslog priorities.*/

typedef struct tagAllowedDestNames{

char const *name;int code;

} ALLOWED_DEST_NAMES;

static ALLOWED_DEST_NAMES allowed_names[] ={

{ "LOG_EMERG", LOG_EMERG },{ "LOG_ALERT", LOG_ALERT },{ "LOG_CRIT", LOG_CRIT },{ "LOG_ERR", LOG_ERR },{ "LOG_WARNING", LOG_WARNING },{ "LOG_NOTICE", LOG_NOTICE },{ "LOG_INFO", LOG_INFO },{ "LOG_DEBUG", LOG_DEBUG },{ NULL, 0 }

};

for(i=0; allowed_names[i].name != NULL; i++){

if ( strcmp(allowed_names[i].name, pre->out) == 0){

/* Preserve the method we should use in syslog */syslog_priority = allowed_names[i].code;return 0;

}}

return 1;}/* xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx */

static void sample_Free(SEOS_ROUTENTRY *pre){

/* This function can be used to free resources allocated by the* extension. Since in this example we did not allocate any* resources, this function remains empty.*/

}

/* xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx */


74 Version 3.7

static int sample_Send(LOGRECORD *plr, SEOS_ROUTENTRY *pre,int notify, void *data){

char *as_string;

if (notify) /* Ignore any NOTIFY messages */return 0;as_string = lograpi_MakeStringMessage(plr, data);if (as_string != NULL)

syslog(syslog_priority, as_string);return 0;

}/* ===============================================================Project : TACFModule : TACF log routing API sample

File : audit2syslog.cPurpose : Provide a sample of the TACF selogrd API:

Place TACF audit records in the UNIX syslog.*/#define __LOGRSAMPLE_C

#include <syslog.h>#include <string.h>

#include <lograpi.h> /* Include the.h file required by API */

#ifndef NULL#define NULL (void *)0#endif

/* Prototypes for our local functions */

static intsample_Sense(SEOS_ROUTENTRY *pre);static voidsample_Free(SEOS_ROUTENTRY *pre);

static intsample_Send(LOGRECORD *plr, SEOS_ROUTENTRY *pre, int notify,

void *data);

/** We don't use the code of the new route type target, but if we wanted* more than one target type, we could use it to distinguish between* the two.*/



5.L

og

Ro

ute

AP

IG

uid

e

static int our_dest_type_code;

/** Here we preserve the syslog priority required by the configuration* file. This of course means that by storing it in a global variable* we provide only one route line in the configuration file* for syslog. Other lines will just overwrite this variable.*/

static int syslog_priority;

/* This is the function called by selogrd. */

int syslog_RegisterDestination(void){

static LOGRAPI_FUNCS funs ={

sample_Send, sample_Free, sample_Sense};

return lograpi_RegisterTargetType("syslog", &funs,&our_dest_type_code);

}

static int sample_Sense(SEOS_ROUTENTRY *pre){ register int i;

/* This function tests if the path specified for the target* is correct. In our sample, the path is actually the* syslog priority. This function compares the priority* specified in the path field of the route line* to the known syslog priorities.*/

typedef struct tagAllowedDestNames{

char const *name;int code;

} ALLOWED_DEST_NAMES;

static ALLOWED_DEST_NAMES allowed_names[] ={

{ "LOG_EMERG", LOG_EMERG },{ "LOG_ALERT", LOG_ALERT },{ "LOG_CRIT", LOG_CRIT },{ "LOG_ERR", LOG_ERR },{ "LOG_WARNING", LOG_WARNING },{ "LOG_NOTICE", LOG_NOTICE },{ "LOG_INFO", LOG_INFO },{ "LOG_DEBUG", LOG_DEBUG },{ NULL, 0 }

};


76 Version 3.7

Notification Audit Log RecordsTACF enables you to store notification information in the databaseas a string associated with a user or resource record. Theadministrator may specify mail addresses to be notified each time anattempt is made to access the resource. A notification request isstored as a special audit log record in the audit log file. Selogrdroutes the notification request to either the mail or the screen addressof the destination specified in the audit log record.

for(i=0; allowed_names[i].name != NULL; i++){

if ( strcmp(allowed_names[i].name, pre->out) == 0){

/* Preserve the method we should use in syslog */syslog_priority = allowed_names[i].code;return 0;

}}

return 1;}


static void sample_Free(SEOS_ROUTENTRY *pre){

/* This function can be used to free resources allocated by the* extension. Since in this example we did not allocate any* resources, this function remains empty.*/

}


static int sample_Send(LOGRECORD *plr, SEOS_ROUTENTRY *pre,int notify, void *data){

char *as_string;

if (notify) /* Ignore any NOTIFY messages */return 0;as_string = lograpi_MakeStringMessage(plr, data);if (as_string != NULL)

syslog(syslog_priority, as_string);return 0;

}



5.L

og

Ro

ute

AP

IG

uid

e

Notification records for a given event are identical to the standardaudit log records associated with that event, except that notificationrecords also have their targets stored at the beginning of the auditlog record. The log codes for the notification records are simply thelog codes of regular audit log records offset by 2048. For example, anormal login audit log record has a log type code of 1. Thenotification log type code would be 2049. Note that an audit logrecord may appear in the audit log file followed by the notificationrecord of the same event.

The format of a notification record structure name isSEOSNF_AUDIT*. The exact names correspond to the matchingaudit log record name:

Notification record Corresponding audit log record

SEOSNF_AUDITADMIN SEOS_AUDITADMIN

SEOSNF_AUDITGENR SEOS_AUDITGENR

SEOSNF_AUDITINWARN SEOS_AUDITINWARN

SEOSNF_AUDITLOGIN SEOS_AUDITLOGIN

SEOSNF_AUDITWDWARN SEOS_AUDITWDWARN

In each structure, the first field is SEOS_NOTIFYSTR, a buffer ofup to 30 bytes to hold the destination string pulled from the TACFdatabase. The second field is the audit log record corresponding tothis notification record.

Audit Log Records

78 Version 3.7

LogRoute API Reference

TACF provides the following LogRoute functions:


<driver>_Register Initializes your extension/driver. Thisfunction is called on startup ofselogrcd. You must provide thisfunction in your shared library for thedriver.

<driver>_UnRegister Uninitializes your extension/driver.This function is called on shutdown ofselogrcd. You must provide thisfunction in your shared library for thedriver.

<driver>_RegisterDestination Initializes your extension/driver. Thisfunction is called on startup ofselogrd. You must provide thisfunction in your shared library for thedriver.

<driver>_UnregisterDestination Uninitializes your extension/driver.This function is called on shutdown ofselogrd. You must provide thisfunction in your shared library for thedriver.

lograpi_InterpretRecord Converts an audit log record to avector of text string pairs.

6


6.L

og

Ro

ute

AP

IR

eference


lograpi_MakeStringMessage Converts an audit log record structureto the one-line text format used byseaudit and seauditx.

lograpi_RegisterTargetType Informs TACF of the exactimplementation details of the newtarget types being registered. Call thisfunction in your selogrd extensioninitialization function.

lograpi_UnregisterTargetType Removes a destination type that waspreviously registered with thelogroutedaemon. Call this function inyour selogrd extension uninitializationfunction.

servlog_IsThereExit Tests whether an exit function exists.Use this function in your selogrcdextension functions.

servlog_RegisterExit Registers an exit function. Call thisfunction in your selogrcd extensioninitialization functions.

servlog_UnRegisterExits Unregisters an exit function. Call thisfunction in your selogrcd extensionuninitialization function.

Your LogRoute API functions that implement a new destination typemust supply code for the following tasks:

Function type Description

LogrApiFreeFunc Frees any memory allocated by the usercode for storage, sockets, and so on, andcloses all network connections.

LogrApiSendFunc Sends the selected audit log record to theuser specified target.

LogrApiSenseFunc Tests the target addresses in eachconfiguration file line for correctness.

80 Version 3.7

<driver>_Register

Synopsisint <driver>_Register (void);

DescriptionThe <driver>_Register function is a predefined function that iscalled by the selogrcd daemon at daemon startup. You insert yourown code into <driver>_Register to register all your newcustomized destination types. Replace the word <driver> with thedestination type as it appears in the selogrcd route configuration fileand the selogrcd extension configuration file.

The function is called when selogrcdstarts. The function shouldregister the exit functions needed for each audit record type.

Note: If a function fails, the return code can be seen in syslog. Ifselogrd is using debug mode, the return code can also beseen on the screen.

Return CodesThe function returns 0 on success and an error code on failure.

See Also¶ “<driver>_UnRegister” on page 82

¶ “lograpi_RegisterTargetType” on page 87

<driver>_Register Function


6.L

og

Ro

ute

AP

IR

eference

<driver>_UnRegister

Synopsisint <driver>_UnRegister (void);

DescriptionThe <driver>_UnRegister function is a predefined function that iscalled by the selogrcd daemon at system termination. You insertyour own code into <driver>_UnRegister to unregister all thedestination types you registered.

Note: If a function fails, the return code can be seen in syslog. Ifselogrcd is using debug mode, the return code can also beseen on the screen.


See Also“<driver>_Register” on page 81

<driver>_UnRegister Function

82 Version 3.7

<driver>_RegisterDestination

Synopsisint <driver>_RegisterDestination (void);

DescriptionThe <driver>_RegisterDestination function is a predefined functionthat is called by the selogrd daemon when the daemon starts. Youinsert your own code into <driver>_RegisterDestination to registerall your new customized destination types.

Replace the word <driver> with the destination type as it appears inthe selogrd route configuration file and the selogrd extensionconfiguration file.

The function is called when the shared library is loaded. Thefunction should initialize the library and register the new target typeby calling the function lograpi_RegisterTargetType.

Note: If a function fails, the return code can be seen in syslog. Ifselogrd is using debug mode, the return code can also beseen on the screen.


See Also¶ “<driver>_UnregisterDestination” on page 84


<driver>_RegisterDestination Function


6.L

og

Ro

ute

AP

IR

eference

<driver>_UnregisterDestination

Synopsisint <driver>_UnregisterDestination (void);

DescriptionThe <driver>_UnregisterDestination function is a predefinedfunction that is called by the selogrd daemon at system termination.You insert your own code into <driver>_UnregisterDestination tounregister all the destination types you registered.

Replace the word <driver> with the destination type as it appears inthe selogrd route configuration file and the selogrd extensionconfiguration file.

Note: If a function fails, the return code can be seen in syslog. Ifselogrdis using debug mode, the return code can also be seenon the screen.


See Also“<driver>_RegisterDestination” on page 83

<driver>_UnregisterDestination Function

84 Version 3.7

lograpi_InterpretRecord

SynopsisSEOS_AUDLOGINTERP *lograpi_InterpretRecord P(LOGRECORD *plr,

void *unc_buff);

DescriptionThe lograpi_InterpretRecord function converts a TACF audit logrecord to a vector of text string pairs. Each pair consists of the labelof the field in the record and the text for that field. The vector itselfends when both members - Label and Value - are NULL pointers.The Value member can be NULL pointer when there is no value fora specific field in the audit record.

The seauditx utility displays audit records in a format similar to thiswhen the user requests more detail about the displayed records.

Argumentsplr A pointer to the audit log record structure passed to the

LogrApiSendFunc function.

unc_buffA pointer to the uncompressed audit log record informationpassed to the LogrApiSendFunc function.

Return CodesIf successful, the function returns a pointer to a vector of structures.Each element in the vector is a structure that contains two members:a label and a value. The pointers Label and Value point to a staticmemory region that is overwritten by any call to the function. Thevector itself ends when both members Label and Value are NULLpointers.

lograpi_InterpretRecord Function


6.L

og

Ro

ute

AP

IR

eference

This following diagram displays this graphically:

See Also“lograpi_MakeStringMessage” on page 91

lograpi_InterpretRecord Arguments

86 Version 3.7

lograpi_RegisterTargetType

Synopsisint lograpi_RegisterTargetType (const char *name,

LOGRAPI_FUNCS *funcs,int *code);

DescriptionThe lograpi_RegisterTargetType function registers a new target ordestination type with the TACF logroute daemon.Lograpi_RegisterTargetType provides the LOGRAPI_FUNCSstructure with pointers to the three user functions used to sense avalid configuration file entry, send the record, and free the allocatedmemory space. Lograpi_RegisterTargetType is normally called bythe <driver>_RegisterDestination function, to register yourfunctions with the TACF log router.

Argumentsname The name of the newly added destination type.

funcs A pointer to a LOGRAPI_FUNCS structure containing thethree destination type functions: LogrApiFreeFunc,LogrApiSendFunc, and LogrApiSenseFunc.

code The code assigned to this target destination. The code is thevalue stored in the destination data member of theSEOS_ROUTENTRY structure.


If a failure occurs, the function returns an unsigned integer errorcode and assigns a value to the global variable errno according tothe following table of values:

TACF error code(Errno) Meaning

LOGRAPI_E_DESTFULL(ENOMEM) Destination table is full. The maximum tablesize is 10 elements.

lograpi_Register TargetType Function


6.L

og

Ro

ute

AP

IR

eference

LOGRAPI_E_NULLPARAM(EINVAL) One of the parameters is NULL.

LOGRAPI_E_NOSENDFUNC(EINVAL) No send function specified.

See Also¶ “<driver>_RegisterDestination” on page 83

¶ “lograpi_UnregisterTargetType” on page 89

lograpi_Register TargetType Arguments

88 Version 3.7

lograpi_UnregisterTargetType

Synopsisint lograpi_UnregisterTargetType (const char *name);

DescriptionThe lograpi_UnregisterTargetType function unregisters a target ordestination type previously registered with the TACF logroutedaemon.

Note: Once a destination type is unregistered, it cannot be registeredagain during the current session. Yet all subsequent recordsare marked as if the send to that destination was successful.Do not unregister a target type unless you will definitely notbe working with that target type any more.

Argumentsname The name of the target or destination type to be unregistered.

code The destination code assigned to this target type whenpreviously registered.


If a failure occurs, the function returns an integer error code andassigns a value to the global variable errno according to thefollowing table of values:

TACF Error Code(Errno) Meaning

LOGRAPI_E_NULLPARM(EINVAL) The code is NULL.

LOGRAPI_E_NODEST(ENOENT) No such destination type.

lograpi_Unregister Target Type Function


6.L

og

Ro

ute

AP

IR

eference

See Also¶ “<driver>_UnregisterDestination” on page 84


lograpi_UnregisterTargetType Arguments

90 Version 3.7

lograpi_MakeStringMessage

Synopsischar * lograpi_MakeStringMessage (LOGRECORD *plr,

void *data);

DescriptionThe lograpi_MakeStringMessage function converts a TACF auditlog record to a one-line text string in the standard TACF format usedby the seaudit and seauditx utilities.

Argumentsplr A pointer to the audit log record structure passed to the

LogrApiSendFunc function.

data A pointer to the uncompressed audit log record informationpassed to the LogrApiSendFunc function.

Return CodesIf successful, the function returns a char pointer to the audit log datastring. This string is held in an area of static memory that isoverwritten when a subsequent call is made to the function.

If a failure occurs, the function returns NULL. Check the value oferrno for more information. Passing a NULL pointer as an inputparameter generates an error. Possible errors are:

EINVAData on pointer parameters are NULL.

See Also“lograpi_InterpretRecord” on page 85

lograpi_MakeStringMessage Function


6.L

og

Ro

ute

AP

IR

eference

LogrApiSenseFunc

Synopsistypedef int (*LogrApiSenseFunc) (SEOS_ROUTENTRY *pre);

DescriptionLogrApiSenseFunc is a function pointer type that specifies auser-defined sense function to be called while the selogrd daemon isinitializing and restarting. The sense function determines (senses) ifthe configuration file route entry is valid. The sense function teststhe target field entries in each configuration file line for validity. Forexample, if the destination name is user jsmith, thenLogrApiSenseFunc should check that there is in fact a user by thatname.

Argumentspre Configuration file entry to check for validity.


LogrApiSenseFunc Function

92 Version 3.7

LogrApiSendFunc

Synopsistypedef int (*LogrApiSendFunc) (LOGRECORD *plr,

SEOS_ROUTENTRY *pre,int notify,void *data);

DescriptionLogrApiSendFunc is a function pointer type that specifies auser-defined send function. When an audit log record is found thatmatches the user’s selection criteria, the send function transmits(sends) the selected audit log record to the user-specified destination.

Argumentsplr The audit log description file.

pre Information on the audit target destination for the audit logrecord.

notify Flag indicating if this audit log record is a notificationrecord. If the audit log record is a notification record, thisparameter is set to TRUE (1); otherwise, the parameter is setto FALSE (0).

data A pointer to the audit log record.

Return CodesThe function returns 0 on success. An audit log record successfullysent is never submitted again to LogrApiSendFunc.

If the send action failed, TACF enters an error notice into the syslogfile and returns any non-zero integer as an error flag. The same auditlog record may be resubmitted an unlimited number of times.

See Also“LogrApiFreeFunc” on page 94

LogrApiSendFunc Function


6.L

og

Ro

ute

AP

IR

eference

LogrApiFreeFunc

Synopsistypedef void (*LogrApiFreeFunc) (SEOS_ROUTENTRY *pre);

DescriptionLogrApiFreeFunc is a function pointer type that specifies auser-defined free function. When selogrd shuts down or restarts, itcalls the free function to free the memory allocated to a previouslyregistered function. The SendData member of theSEOS_ROUTENTRY structure is used as a placeholder for theallocated memory for a target, such as a FILE * or a CLIENT *. Thepointer may be NULL, if the registered function uses no allocatedresources.

Notes:

1. Selogrd shuts down and restarts every time seosd switches logfiles. This may happen often; for example, whenever the log filesexceed a specified maximum size. Be sure that your free functionreliably frees all allocated memory or system resources maybecome unavailable.

2. If there is no need for a free operation, set this function pointerto NULL.

Argumentspre The target entry to free or close.

Return CodesNone.

LogrApiFreeFunc Function

94 Version 3.7

servlog_IsThereExit

System Environmentint servlog_IsThereExit (int rectype);

DescriptionThe servlog_IsThereExit function tests if an exit function isregistered for the given type of audit record. Each audit record inTACF is identified as a particular record type, such as login, audit,or general resource. The values for rectype are defined in the headerfile selogtype.h, which is supplied with the TACF API. The formatof the rectype is AUDIT_rectype. For details on the possible recordtypes, see the “LOGRECHDR Structure” on page 190.

Argumentsrectype

Is an exit function registered for the record type representedby this particular code.

Return CodesThe function returns 1 if there is an exit function for the specifiedrecord type, otherwise it returns 0.

servlog_IsThereExit Function


6.L

og

Ro

ute

AP

IR

eference

servlog_RegisterExit

Synopsisint servlog_RegisterExit (int rectype,

collectexitf func,int *chain);

DescriptionThe servlog_RegisterExit function registers an exit function to becalled by the selogrcd daemon when a particular type of audit recordis received. Each audit record in TACF is identified as a particularrecord type, such as login, audit, or general resource. The values forrectype are defined in the header file selogtype.h, which is suppliedwith the TACF API. The format of the rectype is AUDIT_rectype.For the details on the possible record types, see “LOGRECHDRStructure” on page 190.

It is possible to register more than one exit function for each type ofrecord; TACF allows a maximum of 16 exit functions for each typeof record. When a function is registered, it is assigned a sequencenumber in the list of exit functions for its particular type.

This function should be called during exit initialization to registerthe exit functions. This function is normally called from the<driver>_Register function.

Argumentsrectype

The code of the record type for which the exit function mustbe called.

func A pointer to the user function that should gain control whenan audit record of rectype is received.

chain The number in the chain of exit functions of the specifiedrecord type.


servlog_RegisterExit Function

96 Version 3.7

servlog_UnRegisterExit

Synopsisint servlog_UnRegisterExit (int rectype,

int *chain);;

DescriptionThe servlog_UnRegisterExit function unregisters an exit functionpreviously registered by a call to servlog_RegisterExit. Afterunregistering an exit function, it can no longer be called.

Argumentsrectype

The code of the audit record type.

chain The number (from the chain of exit functions for thespecified record type) of the exit function to be unregistered.The number was assigned to the function when it wasregistered


servlog_UnRegisterExit Function


6.L

og

Ro

ute

AP

IR

eference

servlog_UnRegisterExit Arguments

98 Version 3.7

IV — -Administration APIThe TACF Administration API is used to administer the TACF database. The APIincludes functions for reading and modifying the values of properties stored in theTACF database. The API includes functions for submitting audit records to theTACF audit log. The API also includes functions for controlling the behavior of theTACF daemon.

The functions that update the TACF database are not included with the normaldistribution of the TACF Administration API; these functions are supplied only uponrequest.

Note: One must call the seadmapi_Init function or theseadmapi_IsSeoSSyscallLoaded function prior to calling any other functionin the Seadmapi library.


100 Version 3.7

Administration API Guide

TACF uses an object-oriented database. The TACF database includesdefinitions for classes, objects, and specific class definition of datamembers. It is essential to understand the database architecturebefore using the Administration API, since the API includesfunctions for reading and modifying the information in the database.

Some of the details about the TACF database layout are explained inTivoli Security Management User’s Guide. It is advisable to read theuser’s guide in addition to this chapter.

How the TACF Database Is OrganizedThe information in the TACF database is organized into classes. Aclass’s definition includes information that is common to all records,or objects, of that class. Records that belong to the same class havea similar meaning. For example, every record in the USER classrepresents a user; every record in the GROUP class represents agroup of users; and every record in the TERMINAL class representsa terminal from which users can access the current host. Every classcontains a Properties Definition Table that includes a list ofproperties that can be assigned to records that belong to the class.

A record is a single entity that represents an instance of its class. Forexample, a record in the USER class represents an individual user.Each class contains properties, or fields, that are specific to the class.Information is stored in a record by assigning values to itsproperties. The definition of a property includes information on the

7


7.A

dm

inistratio

nA

PI

Gu

ide

layout of the data and attributes that define how the data is stored inthe TACF database. Values can be assigned to every property of arecord. The definition of the record’s class determines whichproperties can be assigned to the record, and what values can beassigned to each property.

The structure of the TACF database is best described by means ofexample. Consider the USER class. Every record in the USER classrepresents a user of the system. The properties definition table of theUSER class contains a list of properties that can be assigned to userrecords. Some of the properties in the list are FULL_NAME,ORGANIZATION, and GROUPS. Every user who is represented bya record in the TACF database can be assigned values for theseproperties. For example, the FULL_NAME property will be used tostore the user’s full name; the ORGANIZATION property can beused to store information about the organization the user belongs to;and the GROUPS property contains a list of the groups to which theuser belongs. The properties of a record can be thought of as fieldsin a database record. The format of a property can vary, dependingon the definition of the property. In the example here, theFULL_NAME and ORGANIZATION properties have only a singlevalue, whereas the GROUPS property is a list that consists of avariable number of repetitive elements. There is no limit to thenumber of groups a user can belong to.

Each class in the TACF database has a name and an ID associatedwith the name. The class ID is used internally by the databaseengine to achieve better performance and smaller database file sizes.The class IDs do not have any meaning beyond their internal useand may differ between different TACF databases. Use class names;do not use class IDs.

Each property of a class in the TACF database has a name and anID associated with the property name. The property ID is usedinternally by the database engine to achieve better performance andsmaller database file sizes. Note that every class has its ownproperties definition table; thus, a property name can appear in morethan one class and the property may have different attributes in

102 Version 3.7

different classes. A property is identified either by its name and thename of the class in which it resides, or by its unique property ID.

Every record in the TACF database has a name and belongs to aclass. Records in different classes can have the same name. Eachrecord in the database is associated with a record ID. The record IDis a 32-bit number that is unique to each record in the TACFdatabase. The record ID is used internally by TACF. When referringto a record, you may use the record name or the record ID.

Every record in the database can have values assigned to itsproperties. Some properties are automatically set by TACF, whileothers are explicitly set by the user. Most properties are set by thesecurity administrator or a delegated responsible person, using thetools included with TACF Access Control.

Database LayoutThe TACF database consists of the following data files:

File Description

seos_cdf.dat The class description file contains the class definitiontable.

seos_odf.dat The objects description file contains the recordsdefinition table.

seos_pdf.dat The properties description file contains the propertiesdefinition table.

seos_pvf.dat The properties value file contains the values assignedto each TACF property.

The TACF data files also have indexing files which are notmentioned here, because they are transparent to the administrationAPI.

Class Description FileThe class description file stores information on all classes defined toTACF. The information stored therein includes the name of the class,


7.A

dm

inistratio

nA

PI

Gu

ide

the class ID, and other flags used internally by TACF. The classinformation is stored in a structure called SEOSDB_CDF.

Properties Description FileThe properties description file stores information on each propertydefined to TACF. The property information includes the following:

¶ The property ID

¶ The name of the property

¶ The class ID of the class in which the property is defined

¶ The property’s data type - string, integer, structure, and so on

¶ The size, in bytes, required to store a single value of theproperty

Some properties are defined as single value, other properties aredefined as a list value. The properties description information isstored in a structure called SEOSDB_PDF.

Objects Description FileThe objects description file stores basic information on each recorddefined to TACF. The following data is stored in the objectsdescription file: the

¶ Class ID of the class in which the record is defined

¶ Name of the record

¶ Record’s unique internal database ID, also known as the objectID

The objects description information is stored in a structure calledSEOSDB_ODF.

Properties Values FileThe properties values file contains the values assigned to everyproperty of every record defined in the TACF database. Each entryconsists of the following: the

¶ Class ID

¶ Property ID

Database Layout

104 Version 3.7

¶ Record ID

¶ Data assigned to the property

Information used for integrity checking is also stored in theproperties values file; however, this information cannot be accessedusing the Administration API.

Lists in the TACF DatabaseThis section describes the various types of lists that exist in theTACF database.

Connections of Users to GroupsBoth user records and group records contain data that defines theconnections of users to groups.

The user record contains a list of groups the user belongs to. Thefollowing information is stored in the user record:

¶ The date on which the connection was created.

¶ The user or group that owns the connection.

¶ The group attributes, if any, assigned to the user.

The group record contains a list of users who are connected to thegroup. The list contains only the record IDs of the users.

When connecting a user to a group, the list of groups the user isconnected to and the list of users connected to the group need to beupdated. When a user is connected to a group, both lists areautomatically updated by TACF. If a user is subsequently deletedfrom the database, the user may not be deleted from every grouprecord containing the user’s ID. Thus, some group records maycontain user IDs of users who no longer exist in the database. TACFgenerates new object IDs in a manner that ensures that an ID cannotbe assigned to an object more than once in the lifetime of thedatabase. The unused user IDs in the group records do not pose asecurity threat.

Database Layout


7.A

dm

inistratio

nA

PI

Gu

ide

Connections of Resources to Resource GroupsLike a user-group connection, the connection of a resource to aresource group is stored in both the resource record and the resourcegroup record. The resource record contains a list of record IDs thatidentifies the resource groups the resource is connected to. Theresource group record contains a list of resource IDs that identifiesthe resources that are connected to the resource group. The resourceand resource group records are automatically updated whenever aresource is connected to a resource group.

Access Control List (ACL) EntriesAn access control list (ACL) is a list of entries in a resource record.Each entry in the ACL defines the access an accessor object in theTACF database has to the resource. Each ACL entry consists of thefollowing:

¶ The record ID of the accessor - usually either a user ID or agroup ID.

¶ The access authority assigned to the accessor. This entrydetermines what the accessor is allowed to do to the resourcerepresented by the resource record.

TACF also provides program access control lists (PACLs), alsoknown as conditional access control lists, which are similar toregular access control lists. In addition to the record ID of theaccessor and the accessor’s level of authority, PACL entries consistof a PROGRAM record ID.

By convention, TACF does not assign object ID of 0 (zero) to anyobject. In ACLs and PACLs, an object ID of 0 represents user (*),i.e., all TACF defined users. For more information on ACLs, see theauthorize command in the Tivoli SecureWay Security ManagerReference Guide for TACF.

TACF Database Lists

106 Version 3.7

Understanding ACEETACF assigns an accessor environment element (ACEE) to each userwhen the user logs into the system. The ACEE is a data structurecontaining the user’s credentials and definitions of various securityparameters. Every process created by the login process inherits theparent process’s ACEE. The ACEE is maintained even if the processsubstitutes user by executing the system’s su utility or the TACFsesu utility.

Each ACEE has a handle which uniquely describes the process’scredentials and other information at any point in time. The ACEEand its associated handle exist until the login session that createdthem terminates.

The Administration API, as well as all TACF authorizationprocesses, use the ACEE handle to identify and describe the usermaking the request.

The Administration API includes functions that fetch a user’s ACEEor ACEE handle. The information obtained by these functions can beviewed using the sewhoami utility with the appropriate options. Formore information on the sewhoami utility, see the Tivoli SecurityManagement User’s Guide.

Scope Limitations of the APIThe Administration API uses a simpler security scope method thanthe TACF language interpreter, so as not to adversely affectperformance. The Administration API uses the attributes set in theuser’s user record. Other privileges that use ownership, groupattributes, and the ADMIN class are ignored by the API.

This means that the user is not allowed to perform some operationsvia the Administration API that the user is allowed when usingselang, selangx, or the SeAM. For example, in selang a user candisplay and update an object that the user owns. The administrationAPI does not allow an owner of an object to update it if the ownerdoes not also have the ADMIN attribute.

Understanding ACEE


7.A

dm

inistratio

nA

PI

Gu

ide

ConventionsThe Administration API uses the following conventions:

¶ All function names start with seadmapi_.

¶ Unless otherwise documented, all functions return an int valuerepresenting the result code.

¶ A return code of zero always denotes a successful operation.Error codes are described in the TACF status codes section ofthe Tivoli SecureWay Security Manager Reference Guide forTACF.

¶ Variables are always required. If a variable is a pointer, a pointermust be supplied. A pointer can be NULL only where specified.

¶ The library functions assign values to the C global variableerrno, which is also used to return error codes.

¶ The names of parameters which are NULL character terminatedstrings (ASCII-Z or C-Style strings) are preceded by the letterssz.

¶ Many functions use pre-fetched information, such as classdescriptions, property descriptions, and object descriptions, tospeed up the operation. Use these pre-fetched descriptionswherever possible, to reduce the load on the station.

Header FilesTo use this API you will be required to include in your source codecertain header files with prototypes and structure definitions. Allprototypes are in the seadmapi.h file, while most of the data typesare in other headers. The seostypes.h header file provides structuredefinitions of all data stored in the TACF database. The structuredefinitions of auditing and error logging records are located in theheader file selogtype.h.

Understanding ACEE

108 Version 3.7

LibrariesThe seadmapi consists of a single library file seadmapi.a thatshould be linked together with every compiled source file that usesthis API.

TACF also includes a shared library version of this API calledlibseadmapi.xx, where xx is the standard OS convention, usually soor sl, for shared library names.

Before executing programs that use the shared library, such assample_TermOwn.c, check that there is an environment variablepointing to the path of the shared library. To point an environmentvariable to the shared library path, enter the following command:setenv LD_LIBRARY_PATH /usr/seos/lib/

Compiling and Linking with the seadmapiThere are no special flags required to compile with TACF seadmapi.Linking, on the other hand, may require additional settings.Unfortunately these flags are machine and OS dependent. Please usethe makefiles provided by the samples of this API, and look at thosesamples for up to date information.

Programming NotesAll functions provided by this API are thread-safe. If a function isnot thread-safe, the Notes section of the function will specify thatfact.

Note: One must call the seadmapi_Init function or theseadmapi_IsSeOSSyscallLoaded function prior to callingany other function in the Seadmapi library.

Understanding ACEE


7.A

dm

inistratio

nA

PI

Gu

ide

Compiling and Linking with seadmapi

110 Version 3.7

Administration API Reference

The TACF administration API includes functions that are categorizedas follows:

Category Meaning

Class operations Retrieve list of classes and get classcharacteristics information.

Console operations Perform functions connected to consoleoperations.

Log files interface Provide means to add audit and error logrecords.

Miscellaneous operations Some generic operations, such as gettingcommonly required information from theTACF authorization daemon or settingprocess-specific data.

Object operations Retrieve objects and get objectcharacteristics.

Property operations Retrieve properties of a class and getproperties characteristics.

Query operations Perform functions connected to queries.

Value operations Retrieve values, set values, or update valuesin the TACF database.

8


8.A

dm

inistratio

nA

PI

Referen

ce

Class OperationsThe following functions operate on classes.


seadmapi_ClassGetEqual Retrieves a specific class from theTACF database.

seadmapi_ClassGetFirst Retrieves first class from theTACF database.

seadmapi_ClassGetNext Retrieves next class from theTACF database.

Console OperationsThe following functions provide console operations.


seadmapi_consAllLoginDisable Disables all login to system.

seadmapi_consAllLoginEnable Enables all login to system.

seadmapi_consAllLoginGetStatus Gets status of global-logincontrol.

seadmapi_consMessageSend Sends message to TACF trace.

seadmapi_consRunTimeStatisticsGet Gets run time statisticsinformation.

seadmapi_consShutdown Shuts down TACF.

seadmapi_consTraceClear Clears TACF trace file.

seadmapi_consTraceDisable Disables TACF trace.

seadmapi_consTraceEnable Enables TACF trace.

seadmapi_consTraceGetStatus Returns status of TACF trace.

seadmapi_consTraceToggle Toggles TACF trace.

seadmapi_consUidLoginDisable Disables concurrent logins forthe user.

seadmapi_consUidLoginEnable Enables concurrent logins for theuser.

seadmapi_consUidLoginGetStatus Retrieves the current concurrentlogins setting for the user.

Types of Operations

112 Version 3.7

Log Files InterfaceThe following functions operate on the log files.


seadmapi_SendAdminAudit Submits an admin audit record.

seadmapi_SendAuditRecord Provides interface to submit auditrecord.

seadmapi_SendErrorLog Submits an error log.

seadmapi_SendGenrAudit Submits a general-resource auditrecord.

seadmapi_SendInetAudit Submits a TCP/IP audit record.

seadmapi_SendLoginAudit Submits a login audit record.

seadmapi_SendShutdownAudit Submits an audit record of shutdown.

seadmapi_SendStartupAudit Submits an audit record of startup.

seadmapi_SendUserAudit Submits a user audit record.

seadmapi_SendWatchdogAudit Submits a watchdog audit record.

Miscellaneous OperationsThe following functions perform functions that do not fall into anyof the previous categories.


seadmapi_FreeAceeMemory Frees memory allocated by theGetACEE function.

seadmapi_GetACEE Retrieves the current processuser’s ACEE.

seadmapi_GetGraceInfo Retrieves information on theuser’s password and grace logins.

seadmapi_GetMessage Retrieves an error string from agiven error code, using the TACFmessage file.

Types of Operations


8.A

dm

inistratio

nA

PI

Referen

ce


seadmapi_GetObjType Retrieves information on currentprocess user type.

seadmapi_IsSeOSSyscallLoaded Determines if TACF system call isloaded.

seadmapi_ProcessControl Provides control over currentprocess.

seadmapi_ReloadIni Reloads the configuration toakensof the TACF daemon seosd.

SEOS_UMODE_is_attribute Macro used on user type todetermine if user has anadministrative attribute such asAUDITOR, ADMIN, orPWMANAGER.

seamapi_WhoAmI Retrieves information on currentprocess.

seadmapi_WhoIs Retrieves attribute informationabout the user.

sepass_ReplacePassword Replaces the user’s password.

Note: One must call the seadmapi_Init function or theseadmapi_IsSeOSSyscallLoaded function prior to callingany other function in the Seadmapi API library.

Object OperationsThe following functions operate on objects.


seadmapi_FreeObjList Frees the list of objects retrieved byseadmapi_ObjInClassList.

seadmapi_ObjGetEqual Retrieves information on a specificobject.

seadmapi_ObjGetFirstInClass Retrieves information on the firstobject in a class.

Types of Operations

114 Version 3.7


seadmapi_ObjGetGreaterEqual Retrieves information on an objectwhose object ID or name is greaterthan or equal to the specified value.

seadmapi_ObjGetNextInClass Retrieves information on next object ina class.

seadmapi_ObjInClassList Retrieves a list of the objects in aspecified class.

Property OperationsThe following functions operate on properties.


seadmapi_PropGetEqual Retrieves description of a specificproperty.

seadmapi_PropGetNextInClass Retrieves next property description of aclass.

seadmapi_PropGetFirstInClass Retrieves first property description of aclass.

Query OperationsThe following functions perform queries.


seadmapi_GetEntity Retrieves an entire object and itsproperties values, using the entity rulerinitialized before.

seadmapi_GetExEntity Retrieves an entire object and itsproperties values, including the objectand class names, using the entity rulerinitialized before.

seadmapi_GetGraceInfo Retrieves grace information about theuser.

Types of Operations


8.A

dm

inistratio

nA

PI

Referen

ce


seadmapi_InitEntityRuler Initializes an entity query buffer used forthe GetEntity and GetExEntityoperations.

seadmapi_KillEntityMem Frees memory allocated for entity stylequery by the InitEntityRuler function.

seadmapi_KillExEntityMem Frees memory allocated for entity stylequery by the InitEntityRuler function.

seadmapi_KillPDFList Frees the list of properties descriptorsallocated by the MakePDFList function.

seadmapi_MakePDFList Creates a property descriptors list from alist of properties names.

seadmapi_OidToName Translates an object ID to an objectname.

Value OperationsThe following functions operate on values.


seadmapi_FetchListPropVal Gets the values for a list type property.

seadmapi_FetchSinglePropVal Gets the values for a single valueproperty.

seadmapi_FreeListPropVal Frees the list of values from FetchList.

seadmapi_SetSinglePropVal Sets the value of a single propertyvalue type.

Types of Operations

116 Version 3.7

seadmapi_ClassGetEqualseadmapi_ClassGetFirstseadmapi_ClassGetNext

Synopsisint seadmapi_ClassGetEqual(const char *szClass,

SEOS_CID cid,SEOSDB_CDF *p_seclass);

int seadmapi_ClassGetFirst(SEOSDB_CDF *p_seclass);

int seadmapi_ClassGetNext(SEOSDB_CDF *p_seclass);

DescriptionThese functions retrieve information on a class that is defined in theTACF database.

The seadmapi_ClassGetFirst function retrieves information on thefirst class defined in the TACF database.

The seadmapi_ClassGetNext function retrieves information on thenext class that is defined in the TACF database. Theseadmapi_ClassGetNext function uses the class ID from theprevious call to the seadmapi_ClassGetNext function or, if this isthe first time the seadmapi_ClassGetNext function is being called,the class ID is obtained from the seadmapi_ClassGetFirst function.The classes are scanned in the order of their class names.

The seadmapi_ClassGetEqual function retrieves information on aspecific class. The class is identified either by its class name or byits class ID.

To scan all the classes in the TACF database, first call theseadmapi_ClassGetFirst function and then call theseadmapi_ClassGetNextfunction for each subsequent class.

AuthorizationThese functions can be called by processes executed by users whohave any of the following attributes:

seadmapi_ClassGetEqual, First, and Next


8.A

dm

inistratio

nA

PI

Referen

ce

¶ ADMIN

¶ AUDITOR

¶ SERVER

The TACF watchdog and the TACF agent are also allowed to usethese functions.

ArgumentsszClass

The name of the class whose information is to be retrieved.If a class ID is specified in the parameter, set this parameterto NULL.

cid The class ID of the class whose information is to beretrieved. If a class name is specified for the szClassparameter, set this parameter to -1.

p_seclassA pointer to the structure that is to hold the informationretrieved by the function.

Return CodesThe function returns 0 on success or an error code on failure.

ExamplesThe following example demonstrates the use of theseadmapi_ClassGetFirst and seadmapi_ClassGetNext functions toretrieve class definition information on all the classes in the TACFdatabase./* ======================================================

Project : TACFModule : TACF admin API sample.File : sample_ListClass.cPurpose : Sample for seadmapi: List class names.Usage : sample_ListClass===================================================== */

#include <ctype.h>#include <stdio.h>#include <sys/types.h>

#include <unistd.h>#include <seadmapi.h>

int main (void)

{ SEOSDB_CDF cdf;


118 Version 3.7

int rv;

/* -------------------------------------------------- *//* Get the first class from the database *//* -------------------------------------------------- */rv = seadmapi_ClassGetFirst(&cdf);if ( rv )

{ printf("seadmapi_ClassGetFirst returned 0x%04x\n", rv );return 1;

}/* ----------------------------------------------------- *//* If successful, continue looping for all the classes. *//* ----------------------------------------------------- */while (!rv){ printf( "%s\n", cdf.szCName );rv = seadmapi_ClassGetNext(&cdf);

}

return 0;}



8.A

dm

inistratio

nA

PI

Referen

ce

seadmapi_GetACEEseadmapi_FreeAceeMemory

Synopsisint seadmapi_GetACEE(int hAcee,

CLIENT_ACEE **ppAcee);

void seadmapi_FreeAceeMemory(CLIENT_ACEE **ppAcee);

DescriptionWhen given a handle, the function seadmapi_GetACEE retrievesthe relevant ACEE information. The function is also capable ofscanning all ACEEs currently allocated for users in TACF. Theinformation is loaded into a memory area allocated by the functionitself. The information filled in the CLIENT_ACEE structurecontains all the credentials-information-for a given ACEE.

Call the function seadmapi_FreeAceeMemory to free the memoryarea allocated by the function seadmapi_GetACEE.

Note: Processes are scanned by the ACEE handle number. It ispossible that scanning the ACEE handles will not returninformation on all allocated ACEEs because of log-ins orlog-outs that have occurred since the scan began.

AuthorizationThese functions can be used by every process in the system. If aprocess wants to query information on a handle other than thecurrent ACEE, it must have the ADMIN, SERVER, or AUDITORattribute.

Argumentshandle The handle to which information must be fetched. If the

handle is SEADMAPI_FIRST_ACEE, then the functionseadmapi_GetACEE fetches the information for the firstallocated ACEE. Subsequent calls to get information on thenext ACEE must use the macro SEADMAPI_NEXT_ACEEwhen the returned handle is specified as a parameter to themacro. To fetch the information on the current process

seadmapi_GetACEE, FreAceeMemory

120 Version 3.7

ACEE, use the value SEADMAPI_CURR_ACEE. For anyother handle, specify the handle needed.

ppAceeA pointer to a pointer that is assigned to point to thememory area allocated by seadmapi_GetACEE. Thefunction seadmapi_FreeAceeMemory receives this sameaddress in order to free the allocated memory.

Return CodesThe function seadmapi_GetACEE returns 0 on success and an errorcode on failure.

The function seadmapi_FreeAceeMemory does not return a value.

See Also“seadmapi_WhoAmI” on page 157

seadmapi_GetACEE, FreAceeMemory


8.A

dm

inistratio

nA

PI

Referen

ce

seadmapi_GetMessage

Synopsisint seadmapi_GetMessage(int err_code,

int size,char *buff);

DescriptionThis function retrieves an error description from the TACF messagefile and places it into the buffer pointed to by the buff parameter.

AuthorizationThis function can be used by every process in the system.

Argumentserr_code

The error code as returned by one of the TACF functions.

size The size of the buffer in bytes. Normally a 2K buffer isenough.

buff A pointer to a buffer that contains the text describing theerror.


ExamplesExamples using this function can be found under the functions“seadmapi_FetchListPropVal” on page 136 and“seadmapi_FetchSinglePropVal” on page 141

seadmapi_GetMessage

122 Version 3.7

seadmapi_Init

Synopsisint seadmapi_Init(void)

DescriptionThe function initializes the communication channel with TACF.

Note: One must place a call to this function or theseadmapi_IsSeOSSyscallLoaded function prior to callingany other function in the Seadmapi library.


Return CodesThis function returns 0 if initialization is successful, or an error codeotherwise. The function verifies the exact TACF system call loadedon the computer.

seadmapi_Init


8.A

dm

inistratio

nA

PI

Referen

ce

seadmapi_IsSeOSSyscallLoaded

Synopsisint seadmapi_IsSeOSSyscallLoaded(void)

DescriptionThe function checks if the TACF system call is loaded.

For Solaris systems the function resolves TACF’s system callnumber.

Note: One must call this or the seadmapi_Init function prior tocalling any other function in the Seadmapilibrary.


ExamplesAn example using this function can be found under the function“seadmapi_FetchSinglePropVal” on page 141.

Return CodesFor all systems except AIX, the function returns 0 on success and anerror code on failure.

On AIX systems, the function always returns 0 because the AIXsystem loader will not load any process which requires the TACFsystem call to be loaded, unless the TACF system call is actuallyloaded.

seadmapi_IsSeOSSyscallLoaded

124 Version 3.7

seadmapi_PropGetEqualseadmapi_PropGetFirstInClassseadmapi_PropGetNextInClass

Synopsisint seadmapi_PropGetEqual(const char *szClass,

SEOSDB_CDF *p_seclass,const char *szProp,SEOS_PID pid,SEOSDB_PDF *p_seprop);

int seadmapi_PropGetFirstInClass(const char *szClass,SEOSDB_CDF *p_seclass,SEOSDB_PDF *p_seprop);

int seadmapi_PropGetNextInClass(SEOSDB_PDF *p_seprop);

DescriptionThese functions retrieve information on one or more propertiesdefined in the TACF database.

The seadmapi_PropGetFirstInClass function retrieves informationon the first property defined for the specified class.

The seadmapi_PropGetNextInClass function retrieves informationon the next property that is defined in the TACF database for theclass. The seadmapi_PropGetNextInClass function uses theproperty ID from the previous call to theseadmapi_PropGetNextInClass function or, if this is the first timethe seadmapi_PropGetNextInClass function is being called, theproperty ID is obtained from the seadmapi_PropGetFirstInClassfunction. The properties are scanned alphabetically.

The seadmapi_PropGetEqual function retrieves information on aspecific property. The property is identified either by its propertyname or by its property ID.

To scan all the properties in a specific class, first call theseadmapi_PropGetFirstInClass function and then call theseadmapi_PropGetNextInClass function for each subsequentproperty.

seadmapi_PropGetEqual, FirstInClass, NextInClass


8.A

dm

inistratio

nA

PI

Referen

ce


¶ ADMIN

¶ AUDITOR

¶ SERVER

The TACF watchdog and the TACF agent are also allowed to usethese functions. Any process can issue a getEqual request on anyproperty.

ArgumentsszClass

The class name. When specifying a class description insteadof a class name, set this parameter to NULL.

p_seclassThe class description. When specifying a class name insteadof a class description, set this parameter to NULL.

szProp The property name. When specifying a property ID insteadof a property name, set this parameter to NULL.

pid The property ID. When specifying a property name insteadof a property ID, set this parameter to -1.

p_sepropA pointer to the data structure that is to hold the informationretrieved by the function.


ExamplesThe following example demonstrates the use ofseadmapi_PropGetFirstInClass andseadmapi_PropGetNextInClass to retrieve the values of a propertyin a class.


126 Version 3.7

/* =========================================================Project : TACFModule : TACF admin API sampleFile : sample_ListProp.cPurpose : List properties of a specific class.Usage : sample_ListProp CLASS_NAME========================================================= */

#include <ctype.h>#include <stdio.h>#include <string.h>#include <sys/types.h>#include <unistd.h>

#include <seadmapi.h>

static int ErrorMessage( int rv );

int main(int argc, char *argv[]){ SEOSDB_CDF cdf; /* Class Description */SEOSDB_PDF prop; /* Property Description */char Class[CNAME_SIZE+1];unsigned props_cnt = 0;int rv;

if ( argc < 2 ){ fprintf(stderr, "Required parameter (class name) is missing.\n");return 1;

}

/* ------------------------------------------------------- *//* Set class name by specified parameter. *//* ------------------------------------------------------- */strcpy(Class, argv[1]);

/* ------------------------------------------------------- *//* Clear property descriptor. *//* ------------------------------------------------------- */memset( &prop, 0, sizeof(prop) );

/* ------------------------------------------------------- *//* Check if class exists by getting the class descriptor. *//* ------------------------------------------------------- */rv = seadmapi_ClassGetEqual(Class, 0, &cdf);if (rv) return ErrorMessage(rv);

/* ------------------------------------------------------- *//* Set the class ID in the property descriptor. *//* ------------------------------------------------------- */prop.sCId = cdf.sCId;

/* ------------------------------------------------------- *//* Loop for all the properties in the class. Check for rv 0*//* or 1; we want to find all the properties that are equal *//* to or greater than the supplied property, which is zero.*//* ------------------------------------------------------- */rv = seadmapi_PropGetFirstInClass( NULL, &cdf, &prop );while ( (rv == 0) || (rv == 1) )

{ if ( prop.sCId == cdf.sCId ){ props_cnt++;printf("%s %s\n", Class, prop.szPName);

}rv = seadmapi_PropGetNextInClass( &prop );

}if ( props_cnt == 0 )



8.A

dm

inistratio

nA

PI

Referen

ce

printf("Class %s, does not contain this property.\n", Class);return 0;

}

/* ------------------------------------------------------ *//* Display error message from security daemon. *//* ------------------------------------------------------ */static int ErrorMessage( int rv ){char msg_buff[1024];

seadmapi_GetMessage(rv, sizeof(msg_buff), msg_buff);fprintf(stderr, "%s.\n", msg_buff);return rv;

}


128 Version 3.7

seadmapi_ObjGetEqualseadmapi_ObjGetFirstInClassseadmapi_ObjGetNextInClassseadmapi_ObjGetGreaterEqual

Synopsisint seadmapi_ObjGetEqual(const char *szClass,

SEOSDB_CDF *p_seclass,const char *szObj,SEOS_OID oid,SEOSDB_ODF *p_seobj);

int seadmapi_ObjGetFirstInClass(const char *szClass,SEOSDB_CDF *p_seclass,SEOSDB_ODF *p_seobj);

int seadmapi_ObjGetNextInClass(SEOSDB_ODF *p_seobj);

int seadmapi_ObjGetGreaterEqual(const char *szClass,SEOSDB_CDF *p_seclass,const char *szObj,SEOS_OID oid,SEOSDB_ODF *p_seobj);

DescriptionThese functions retrieve information on an object (record) in theTACF database.

The seadmapi_ObjGetFirstInClassfunction retrieves information onthe first object defined in a class.

The seadmapi_ObjGetNextInClass function retrieves informationon the next object defined in the class. The p_seobj structure musthave been set by a previous call to eitherseadmapi_ObjGetFirstInClass or seadmapi_ObjGetNextInClass.

To scan all the objects in a class sequentially, first callseadmapi_ObjGetFirstInClass and then callseadmapi_ObjGetNextInClass for each subsequent object.

The GetEqual function retrieves information on a specific object.The object is identified either by its object name or by its object ID.

seadmapi_ObjGetEqual


8.A

dm

inistratio

nA

PI

Referen

ce

The GetGreaterEqual function retrieves information on the objectwhose object ID or object name is greater than or equal to thespecified value.

ArgumentsszClass

The name of the class to which the object belongs. If theclass is specified using the p_seclass parameter, set thisparameter to NULL.

p_seclassA pointer to a structure containing the class description. Ifthe szClass parameter is specified, set this parameter toNULL.

szObj The name of the object whose value is to be fetched. If anobject ID is specified instead of an object name, set thisparameter to NULL.

oid The object ID of the object whose information is to beretrieved. When specifying an object name instead of anobject ID, set this parameter to -2.

p_seobjA pointer to the structure that is to hold the informationretrieved by the function. If the object is identified by itsobject name - the szObj parameter - then set p_seobjtoNULL.


¶ ADMIN

¶ AUDITOR

¶ SERVER



130 Version 3.7

Return CodesThe function seadmapi_ObjGetGreaterEqual returns one of thefollowing values:

0 The function retrieved information on the object whoseobject ID is equal to the object ID of the specified object.

1 The function retrieved information on an object whose objectID is greater than the object ID of the specified object.

Any other valueThe function failed.

The other functions return 0 on success and an error code on failure.

ExamplesThe following example demonstrates the use ofseadmapi_ObjGetFirstInClass and seadmapi_ObjGetNextInClassto retrieve all the objects in a specific class./* ========================================================

Project : TACFModule : TACF admin API sample.File : sample_ListObjs.cPurpose : Display the objects in a class.Usage : sample_ListObjs CLASS_NAME======================================================== */

#include <ctype.h>#include <stdio.h>#include <string.h>#include <sys/types.h>#include <unistd.h>



int main(int argc, char *argv[]){ SEOSDB_ODF odf; /* Current ODF in loop */SEOSDB_CDF cdf; /* Class Description */char Class[CNAME_SIZE+1];unsigned ents = 0;int rv;

if ( argc < 2 ){ fprintf(stderr, "Required parameter missing.\n");fprintf(stderr, "Usage: ‘%s CLASS_NAME‘\n", argv[0]);return 1;

}

/* ------------------------------------------------------ *//* Set class name by specified parameter. *//* ------------------------------------------------------ */strcpy(Class, argv[1]);



8.A

dm

inistratio

nA

PI

Referen

ce

/* ------------------------------------------------------ *//* Clear object descriptor. *//* ------------------------------------------------------ */memset( &odf, 0, sizeof(odf) );

/* ------------------------------------------------------ *//* Check if class exists by getting the class descriptor. *//* ------------------------------------------------------ */rv = seadmapi_ClassGetEqual(Class, 0, &cdf);if (rv) return ErrorMessage(rv);

/* ------------------------------------------------------ *//* Set the class ID in the object descriptor. *//* ------------------------------------------------------ */odf.sCId = cdf.sCId;

/* ------------------------------------------------------ *//* Loop for all the objects in the class. *//* ------------------------------------------------------ */rv = seadmapi_ObjGetFirstInClass( NULL, &cdf, &odf );while ( (rv == 0) || (rv == 1) )

{ if ( odf.sCId == cdf.sCId ){ ents++;printf("%s %s\n", Class, odf.szOName);

}rv = seadmapi_ObjGetNextInClass( &odf );

}if ( ents > 0 )

printf("Total of %d objects found in Class=%s\n", ents, Class);else

printf("Class %s, does not have any object.\n", Class);return 0;

}

/* ------------------------------------------------------ *//* Display error message from security daemon. *//* ------------------------------------------------------ */static int ErrorMessage( int rv ){ char msg_buff[1024];


}

See Also“seadmapi_ObjInClassList” on page 133


132 Version 3.7

seadmapi_ObjInClassList

Synopsisint seadmapi_ObjInClassList (SEOSDB_CDF *pcdf,

char *start,void **ptr,char **names,int *count);

DescriptionThe seadmapi_ObjInClassList function retrieves a list of objects ina specified class.

Notes:

1. There is a limit on the number of entries that can be retrieved ina single call. The limit is in the fieldSEADMAPI_MAXOBJSLIST.

2. After calling this function, one should call theseadmapi_FreeObjList function to free the memory allocatedfor the query. Use the ptr argument returned from this function.

Argumentspcdf Pointer to the class descriptor.

start A string representing the object name that should start thelist.

ptr A pointer to a ‘void *’ that is used to free memory allocatedfor the list query.

names A pointer to a vector of char pointers. Each element pointsto an object name.

count On entry, the size of the ‘names’ vector. On return, thenumber of entries in the vector.

Return CodesThe function returns 0 on success or an error code on failure.

See Also¶ “seadmapi_FreeObjList” on page 135



8.A

dm

inistratio

nA

PI

Referen

ce

¶ “seadmapi_GetFirstInClass,” on “seadmapi_ObjGetEqualseadmapi_ObjGetFirstInClass seadmapi_ObjGetNextInClassseadmapi_ObjGetGreaterEqual” on page 129


134 Version 3.7

seadmapi_FreeObjList

Synopsisint seadmapi_FreeObjList (void **ptr);

DescriptionThe seadmapi_FreeObjList function frees the memory allocated bythe seadmapi_ObjInClassList function.

Argumentsptr The pointer as obtained by the most recent call to the

seadmapi_ObjInClassListfunction.

Return CodesNone

Note: The function assigns NULL to (*ptr).

See Also“seadmapi_ObjInClassList” on page 133

seadmapi_FreeObjList


8.A

dm

inistratio

nA

PI

Referen

ce

seadmapi_FetchListPropVal

Synopsisint seadmapi_FetchListPropVal(const char *szClass,

SEOSDB_CDF *p_seclass,const char *szObj,SEOSDB_ODF *p_seobj,const char *szProp,SEOSDB_PDF *p_seprop,void ***val,unsigned int *psize,unsigned int *count);

DescriptionThe seadmapi_FetchListPropVal function retrieves the values of aproperty that contains a list. To retrieve a single-value property usethe seadmapi_FetchSinglePropVal function.

The function allocates a vector of void pointer, each pointing to anallocated buffer that holds a single element in the list. The caller hasto define a variable of type void ** or any other type which is apointer to a pointer (i.e., int **). The caller sends a pointer to thisvariable, as shown in the following example.{ int **list;

unsigned int psize, count;int rc;...

rc = seadmapi_FetchListPropVal(.., (void ***)&list, &psize, &count);

Memory layout after call

where element N is stored in the variable count.

seadmapi_FetchListPropVal

136 Version 3.7

All data fetched by this function is allocated and must be freed. Tofree the data, call the seadmapi_FreeListPropVal function.

AuthorizationThe function can be called by processes executed by users who haveany of the following attributes:

¶ ADMIN

¶ AUDITOR

¶ SERVER


ArgumentsszClass

The name of the class to which the object belongs. If theclass is identified by the p_seclass parameter, set thisparameter to NULL.

p_seclassA pointer to a structure containing the class description. Ifthe class is identified by the szClass parameter, set thisparameter to NULL.

szObj The name of the record whose property value is to befetched. If the object is identified by the p_seobj parameter,set this parameter to NULL.

p_seobjA pointer to the structure containing the object description. Ifthe object is identified by the szObjparameter, set thisparameter to NULL.

szProp The name of the property whose value is to be fetched. Ifthe property is identified by the p_sepropparameter, set thisparameter to NULL.

Memory Layout After Call


8.A

dm

inistratio

nA

PI

Referen

ce

p_sepropA pointer to the structure containing the property description.If the property is identified by the szPropparameter, set thisparameter to NULL.

val A pointer to a pointer to a pointer of the type of valuefetched. More information is provided in the descriptionbelow.

psize The size of the fetched value.

count The number of elements in the allocated vector.


ExamplesThe following example demonstrates theseadmapi_FetchListPropVal function to retrieve the values of aproperty that contains a list. This example also demonstrates the useof the seadmapi_gconn structure to display all the groups a user islinked to./* ================================================================ */

Project : TACFFile : sample_FetchList.cPurpose : 1. Display a property that contains a list;

2. Display list of groups the user is connected to and thespecial attributes, if any, the user has in each group.

Usage : ‘sample_FetchList USER_NAME‘/*

#include <stdio.h>#include <string.h>



int main(int argc, char *argv[]){ SEOSDB_ODF odf;SEOS_GCONN **list;char Object[ONAME_SIZE+1];unsigned int elem_size;unsigned int list_cnt;int rv;int cnt;

if ( argc < 2 ){ fprintf(stderr, "Required parameter (User Name) missing.\n");return 1;

}

/* ----------------------------------------------------------- */

seadmapi_FreeListPropVal Arguments

138 Version 3.7

/* Set object name by specified parameter. *//* ----------------------------------------------------------- */strcpy(Object, argv[1]);

/* ----------------------------------------------------------- *//* Get the list for class=USER, property=GROUPS, object=S_Parm *//* ----------------------------------------------------------- */rv = seadmapi_FetchListPropVal("USER", NULL,

Object, NULL,"GROUPS", NULL,(void ***)&list,&elem_size, &list_cnt);

/* ----------------------------------------------------------- *//* Exit with error message in case we fail to get the list. *//* ----------------------------------------------------------- */if ( rv != 0 ) return ErrorMessage(rv);

/* --------------------------------------------------------- *//* In a loop, display all groups in the list. *//* --------------------------------------------------------- */for(cnt=0; cnt<list_cnt; cnt++)

{ rv = seadmapi_ObjGetEqual("GROUP", NULL, NULL,list[cnt]->oidGroup, &odf);

if ( rv == 0 ){ printf("Group Name: %-10s (ID = %6ld)", odf.szOName,

list[cnt]->oidGroup);if ( list[cnt]->ugmUserMode )

{ printf(", Group");if ( list[cnt]->ugmUserMode & SEOS_UGMODE_AUDITOR )

printf(" auditor");if ( list[cnt]->ugmUserMode & SEOS_UGMODE_PWMANAGER )

printf(" pwmanager");if ( list[cnt]->ugmUserMode & SEOS_UGMODE_ADMIN )

printf(" administrator");}

elseprintf(", Regular");

printf(".\n");}

elseprintf("Group ID: %ld, no longer exist in database.\n",

list[cnt]->oidGroup);}

/* --------------------------------------------------------- *//* Free the list. *//* --------------------------------------------------------- */seadmapi_FreeListPropVal((void ***)&list, &list_cnt);return 0;

}

/* ----------------------------------------------------------- *//* Display error message from security daemon. *//* ----------------------------------------------------------- */static int ErrorMessage( int rv ){ char msg_buff[1024];


}



8.A

dm

inistratio

nA

PI

Referen

ce

See Also¶ “seadmapi_FetchSinglePropVal” on page 141

¶ “seadmapi_FetchListPropVal” on page 136


140 Version 3.7

seadmapi_FetchSinglePropVal

Synopsisint seadmapi_FetchSinglePropVal(const char *szClass,

SEOSDB_CDF *p_seclass,const char *szObj,SEOSDB_ODF *p_seobj,const char *szProp,SEOSDB_PDF *p_seprop,void *val,int *size);

DescriptionThe seadmapi_FetchSinglePropVal function retrieves the value of aproperty that contains a single value. The function cannot be used toretrieve lists; for properties that contain lists, use theseadmapi_FetchListPropVal function. In order to store theproperty’s data, the calling program must allocate the space inmemory pointed to by the val variable. To determine the sizerequired, use the property descriptor sPVSize member or some othermeans.

AuthorizationThis function can be called by processes executed by users who haveany of the following attributes:

¶ ADMIN

¶ AUDITOR

¶ SERVER

The TACF watchdog and the TACF agent are allowed to use thesefunctions

This function can be used by any user who wants to view privatedata. The values are set to those of the user’s own record.

This function can be used by any user to retrieve values for recordsof the SUDO class.



8.A

dm

inistratio

nA

PI

Referen

ce

This function can be used by any user to retrieve values for recordsof the TACF class.

ArgumentsszClass

The name of the class to which the object belongs. If theclass is identified by the p_seclass parameter, set thisparameter to NULL.

p_seclassA pointer to a structure containing the class description. Ifthe class is identified by the szClass parameter, set thisparameter to NULL.

szObj The name of the record whose property value is to befetched. If the record is identified by the p_seobj variable,set this parameter to NULL.

p_seobjA pointer to the structure containing the object description. Ifthe object is identified by the szObj parameter, set thisvariable to NULL.

szProp The name of the property that is to be fetched. If theproperty is identified by the p_seprop parameter, set thisvariable to NULL.

p_sepropA pointer to the structure containing the property description.If the property is identified by the sz_Prop parameter, setthis variable to NULL.

val A pointer to a location in memory where the result is to bestored.

size On entry, its value is the size of the memory area pointed toby the parameter val. On return, its value is the size of thedata stored in the memory area.



142 Version 3.7

ExamplesThe following example demonstrates the use ofseadmapi_FetchSinglePropVal to retrieve the value of a singleproperty./* =============================================================

Project : TACFModule : TACF admin API sample. List value of a specific property

File : sample_FetchSingle.cPurpose : Sample for seadmapi. List the value for a given

property in a specific object in a specific class.============================================================ */#include <ctype.h>#include <stdio.h>#include <string.h>#include <sys/types.h>#include <unistd.h>#include <stdlib.h>



int main(int argc, char *argv[]){ SEOSDB_PDF prop; /* Property Description */char Class[CNAME_SIZE+1];char Object[ONAME_SIZE+1];char Property[PNAME_SIZE+1];char *prop_val;int data_size;int rv;

/* -------------------------------------------------------------- *//* Check if SeOS_syscall is loaded. *//* -------------------------------------------------------------- */rv = seadmapi_IsSeOSSyscallLoaded();if ( rv != 0 )

{ fprintf(stderr, "Database server is not running.\n");return 1;

}

/* -------------------------------------------------------------- *//* Check if the user supplied all required parameters. *//* -------------------------------------------------------------- */if ( argc < 4 )

{ fprintf(stderr, "Required parameter(s) missing.\n");fprintf(stderr, "Usage: ‘%s CLASS_NAME PROPERTY_NAME OBJECT_NAME‘\n",

argv[0]);return 1;

}

/* -------------------------------------------------------------- *//* Set the class, property, and object fields. *//* -------------------------------------------------------------- */strcpy(Class, argv[1]);strcpy(Property, argv[2]);strcpy(Object, argv[3]);

/* -------------------------------------------------------------- *//* Clear the property and object fields. *//* -------------------------------------------------------------- */



8.A

dm

inistratio

nA

PI

Referen

ce

memset( &prop, 0, sizeof(prop) );

/* -------------------------------------------------------------- *//* Get the property descriptor. *//* -------------------------------------------------------------- */rv = seadmapi_PropGetEqual( Class, NULL, Property, 0, &prop );if (rv) return ErrorMessage(rv);

/* -------------------------------------------------------------- *//* Check for string type. *//* -------------------------------------------------------------- */if ( prop.cPType != SEOSDB_PTYPE_STR )

{ fprintf(stderr, "This sample can display only character values.\n");return 1;

}

/* -------------------------------------------------------------- *//* Allocate memory for the value's data according to the property size *//*

--=----------------------------------------------------------- */prop_val = (char *)malloc( (size_t)prop.sPVSize );if ( prop_val == NULL )

{ fprintf(stderr, "Failed to allocate required memory for property value.\n");

return 1;}

data_size = prop.sPVSize;/* -------------------------------------------------------------- *//* Get the requested property value. *//* -------------------------------------------------------------- */rv = seadmapi_FetchSinglePropVal(Class, NULL,

Object, NULL,NULL, &prop,prop_val, &data_size);

if (rv){ free(prop_val);return ErrorMessage(rv);

}printf("%s\n", prop_val);free(prop_val);return 0;

}

/* --------------------------------------------------------------------- *//* Display error message from security daemon. *//* --------------------------------------------------------------------- */static int ErrorMessage( int rv ){ char msg_buff[1024];


}


144 Version 3.7

seadmapi_FreeListPropVal

Synopsisvoid seadmapi_FreeListPropVal(void ***list,

unsigned int *count);

DescriptionThe seadmapi_FreeListPropValfunction must be used after fetchingthe list values using the seadmapi_FetchListPropVal function inorder to free the memory allocated for the values. The parameterssupplied to this function must be the same as those supplied to theseadmapi_FetchListPropVal function.

AuthorizationThis function can be called by any process.

Argumentslist A pointer to the vector allocated by the

seadmapi_FetchListPropVal function.

count A pointer to the number of elements in the allocated vector.

Return CodesNone.

See Also“seadmapi_FreeListPropVal”

seadmapi_FreeListPropVal


8.A

dm

inistratio

nA

PI

Referen

ce

seadmapi_SetSinglePropVal

Synopsisint seadmapi_SetSinglePropVal(const char *szClass,

const char *szObj,const char *szProp,

void *val,int size);

DescriptionThe seadmapi_SetSinglePropVal function sets the value of asingle-value property. The function is used by the TACF watchdogand TACF agent daemons. No other process is permitted to use thisfunction, to prevent damage to the TACF database.

AuthorizationThe seadmapi_SetSinglePropVal function can be used only by theTACF watchdog and the TACF agent.

ArgumentsszClass

The name of the class to which the record belongs.

szObj The name of the record whose property is to be set.

szProp The name of the property whose value is to be set.

val The value to be assigned to the property.

size The size, in bytes, of the value.


seadmapi_SetSinglePropVal

146 Version 3.7

seadmapi_KillPDFListseadmapi_MakePDFList

Synopsisint seadmapi_KillPDFList(SEOSDB_PDF **ppPdf,

unsigned int nCount);

int seadmapi_MakePDFList(const char *szClass,SEOSDB_PDF *ppPdf,unsigned int *nCount);

DescriptionThe seadmapi_MakePDFList function retrieves the entire list ofproperties of a given class. The function allocates memory for theproperties vector. After using the seadmapi_MakePDFList function,use the seadmapi_KillPDFList function to free the allocatedmemory.


¶ ADMIN

¶ AUDITOR

¶ SERVER


ArgumentsszClass

The class name.

ppPdf A pointer to SEOSDB_PDF pointer that will point to theallocated region of memory that holds the properties vector.

nCountThe number of properties in the vector.

seadmapi_KillPDFList, MakePDFList


8.A

dm

inistratio

nA

PI

Referen

ce

Return CodesThe functions return 0 on success and an error code on failure.

seadmapi_KillPDFList, MakePDFList

148 Version 3.7

seadmapi_GetEntityseadmapi_GetExEntityseadmapi_InitEntityRulerseadmapi_KillEntityMemseadmapi_KillExEntityMem

Synopsisint seadmapi_GetEntity(const char *szCName,

const char *szOName,SEOSDB_ODF *podf,SEOSDB_ENTDAT *ObjPVs);

int seadmapi_GetExEntity(const char *szCName,const char *szOName,SEOSDB_ODF *podf,SEOSDB_ENTDAT *ObjPVs);

int seadmapi_InitEntityRuler(const char *szCName,SEOSDB_ENTDAT *ObjPvs);

int seadmapi_KillEntityMem(SEOSDB_ENTDAT *ObjPVs);

int seadmapi_KillExEntityMem(SEOSDB_ENTDAT *ObjPVs);

DescriptionThe seadmapi_GetEntity and seadmapi_GetExEntity functionseach retrieve into the ObjPVs vector all the values for the propertiesof a TACF database object.

These functions are used by TACF utilities and provide a convenientmethod of fetching the information from the TACF database. Formore information, see the rdbdump utility in the Tivoli SecureWaySecurity Manager Reference Guide for TACF.

To use these functions, first call the seadmapi_InitEntityRulerfunction to initialize the list of properties which are of interest to thecaller. Next, call the seadmapi_GetEntity orseadmapi_GetExEntity function to fetch the information on a singleobject.

seadmapi_GetEntity, InitEntity, KillEntity


8.A

dm

inistratio

nA

PI

Referen

ce

¶ When you use the seadmapi_GetEntity function, the vectorreceives all the information on the property (property descriptor)as well as the property values. All properties are retrieved andstored as if they were list property values. Single-valueproperties are also stored as lists, with one entry.

¶ When you use the seadmapi_GetExEntity function, the vectorreceives the same information but all property values thatcontain IDs of other objects are expanded. For example, insteadof receiving an owner’s ID, the utility retrieves the expandedOID that contains the ID and owner’s class and name.

After using the information, call the seadmapi_KillEntityMem orseadmapi_KillExEntityMem function to free all memory requiredfor the operation.

A user may initialize the ObjPVs vector from a previous call to theseadmapi_MakePDFList function. The vector pointed to by theObjPVs parameter should contain the last element with the propertyname set to NULL. The functions use this method to determine thesize of the vector.

Notes:

1. The SEOSDB_ENTDAT, SEOS_X_OID, SESO_X_GCONN,SEOS_X_ACL, anfd SEOS_X_PACL structures are defined inthe seostype.h header file

2. To see the way data is fetched, see the notes describing theseadmapi_FetchListPropValfunction.

3. After each call to seadmapi_GetEntity make sure you callseadmapi_KillEntityMem to free the memory allocated by theseadmapi_GetEntity function.

4. After each call to seadmapi_GetExEntity make sure you callseadmapi_KillExEntityMem to free the memory allocated bythe seadmapi_GetExEntityfunction.



150 Version 3.7

¶ ADMIN

¶ AUDITOR

¶ SERVER


ArgumentsszClass

The class name.

szONameThe object name.

podf A pointer to a memory area that will be filled with the objectdescriptor.

ObjPVsA pointer to a vector with both property description andvalue list.


ExamplesThe following example demonstrates the use of theseadmapi_InitEntityRuler and seadmapi_GetExEntityfunctions:/* ==========================================================

Project : TACFModule : TACF admin API sampleFile : sample_TermOwn.cPurpose : Display terminal's owner.Usage : ‘sample_TermOwn‘==========================================================

*//* ----------------------------------------------------------------

Remember to point an environment variable to the shared librarypath by entering the command -

setenv LD_LIBRARY_PATH /usr/seos/lib/---------------------------------------------------------------- */

#include <ctype.h>#include <stdio.h>#include <sys/types.h>#include <memory.h>



8.A

dm

inistratio

nA

PI

Referen

ce



int main(int argc, char *argv[]){ SEOSDB_OD odf; /* Object definition */SEOSDB_ENTDAT entdat[2]; /* Entity data */SEOS_X_OID *owner;int rv;

/* -------------------------------------------------------------- *//* Check if user specified the terminal name. *//* -------------------------------------------------------------- */if ( argc == 1 )

{ printf("Usage: ‘%s terminal_name‘\n", argv[0]);return 1;

}

/* -------------------------------------------------------------- *//* Initialize entity data. *//* -------------------------------------------------------------- */memset(entdat, 0, sizeof(entdat));

/* -------------------------------------------------------------- *//* Set the ruler for the database request. *//* -------------------------------------------------------------- */entdat[0].szPName = "OWNER"; /* Owner */entdat[1].szPName = NULL; /* Null terminator */rv = seadmapi_InitEntityRuler("TERMINAL", entdat);

/* -------------------------------------------------------------- *//* Exit with error message in case we fail to set the ruler. *//* -------------------------------------------------------------- */if ( rv != 0 ) return ErrorMessage(rv);

/* -------------------------------------------------------------- *//* Get all data. *//* -------------------------------------------------------------- */rv = seadmapi_GetExEntity("TERMINAL", /* Class name */

argv[1], /* Terminal name */&odf, /* Object definition */entdat); /* Entity data */

/* -------------------------------------------------------------- *//* Exit with error message in case we fail to get the data. *//* -------------------------------------------------------------- */if ( rv != 0 ) return ErrorMessage(rv);

/* -------------------------------------------------------------- *//* Display OWNER information. *//* -------------------------------------------------------------- */

if ( entdat[0].nPVQty != 0 ){ owner = (SEOS_X_OID *)entdat[0].pPVList[0];if ( owner->pCName != NULL )

printf("OWNER = %s %s, id=%d\n", owner->pCName,owner->pOName, owner->oid);

elseprintf("OWNER = (id=%d)\n", entdat[0].pPVList);

}else

printf("OWNER = \n");

return 0;


152 Version 3.7

}

/* ---------------------------------------------------------------- *//* Display error message from security daemon. *//* ---------------------------------------------------------------- */static int ErrorMessage( int rv ){ char msg_buff[1024];


}

See Also“seadmapi_MakePDFList” on “seadmapi_KillPDFListseadmapi_MakePDFList” on page 147



8.A

dm

inistratio

nA

PI

Referen

ce

seadmapi_GetGraceInfo

Synopsisint seadmapi_GetGraceInfo(SEGRACE_RES *p_sgr);

DescriptionThis function retrieves information regarding a user’s password, dateof last login, and the number of grace logins that the user still has.


¶ ADMIN

All users can execute this function for themselves.

Argumentsp_sgr A pointer to the structure that contains the information

regarding user logins and grace days.

Return CodesThe function returns the data on success and NULL on failure.

ExamplesThe following program shows how to use this function./* ============================================================

Project : TACFModule : TACF admin API sample.File : sample_grace.cPurpose : Sample for seadmapi: Display information from the TACF

database about the user's grace logins.Usage : ‘sample_grace‘

=========================================================== */



int main(void){ SEGRACE_RES sgr;/* Grace information structure */int rv; /* Return value */

/* -------------------------------------------------------------- */


154 Version 3.7

/* Quit if the kernel extension is not loaded. *//* -------------------------------------------------------------- */rv = seossfr_IsSeOSSyscallLoaded();if ( rv )

{ fprintf(stderr, "The kernel extension is not loaded.\n");return rv;

}

/* -------------------------------------------------------------- *//* Quit if the security daemon is not running. *//* -------------------------------------------------------------- */rv = seadmapi_IsServerRunning();if ( rv )

{ fprintf(stderr, "Security daemon is not running.\n");return rv;

}

/* -------------------------------------------------------------- *//* Set username to '0' to fetch current user's grace information *//* -------------------------------------------------------------- */sgr.uname[0] = 0;

/* -------------------------------------------------------------- *//* Get grace information from the database. *//* -------------------------------------------------------------- */rv = seadmapi_GetGraceInfo(&sgr);

/* -------------------------------------------------------------- *//* If rv is not zero, display an error message and quit. *//* -------------------------------------------------------------- */if ( rv )

{ if ( sgr.step ){ if (sgr.msg[0] != 0 )

fprintf(stderr, "%s\n", sgr.msg);return 1;

}}

/* -------------------------------------------------------------- *//* Display the number of grace logins. *//* -------------------------------------------------------------- */printf("User %s has %d grace logins.\n", sgr.uname, sgr.grace);

return 0;}



8.A

dm

inistratio

nA

PI

Referen

ce

seadmapi_OidToName

Synopsischar *seadmapi_OidToName(SEOS_OID oid);

DescriptionThis function provides a convenient way of translating an object IDto a string containing the object name.

If the object does not exist in the database - for instance, if theobject has been deleted - the string returned by this function isNULL.

Note: The pointer returned by this function is a pointer to a staticarea, overwritten by each subsequent call. This makes thefunction unsafe when using multi-threads.


¶ ADMIN

¶ AUDITOR

¶ SERVER


Argumentsoid The object ID of the record.

Return CodesThe function returns the name of an object on success and NULL onfailure.

See Also“seadmapi_objGetEqual” on “seadmapi_ObjGetEqualseadmapi_ObjGetFirstInClass seadmapi_ObjGetNextInClassseadmapi_ObjGetGreaterEqual” on page 129

seadmapi_OidToName

156 Version 3.7

seadmapi_WhoAmI

Synopsisint seadmapi_WhoAmI(uid_t *uid,

int *handle,char *szUNameSEOS_UMODE *objtype);

DescriptionThis function provides information about the current process to theTACF daemon. The information returned by the function may beused to fetch other information from the TACF database or from theTACF authorization daemon.

Notes:

1. Each parameter is a pointer to a user variable that is assigned avalue by the function. Any parameter may be NULL, in whichcase it is not assigned a value.

2. The handle returned by the function is an ACEE handleassociated with current process. Note that there may be morethan one process with the same ACEE; in fact, this is usually thecase, since each user has more than one process running in thesystem.

The memory area pointed to by the szUName parameter must belarge enough to accommodate 255 characters.

3. The function is used by the TACF sewhoami utility.

4. The header file seadmapi.h contains several macros that operateon the objtype variable data, to determine whether a user has aspecific attribute. These macros have the common notation ofSEOS_UMODE_is_attribute.

AuthorizationThe function can be called by every process in the system.

Argumentsuid The UNIX UID associated with the current process. This is

equivalent to and safer than using the getlogin UNIXfunction.

seadmapi_WhoAmI


8.A

dm

inistratio

nA

PI

Referen

ce

handle The ACEE handle associated with the current process. Seethe notes below.

szUNameThe user name associated with the current process.

objtypeThe user type as saved in the database. This specifies theattributes assigned to the user.


ExamplesThe following example demonstrates the use of theseadmapi_WhoAmI function/* ================================================================

Project : TACFPurpose : Display information about the user from the TACF database.Usage : ‘sample_WhoAmI‘================================================================= */



int main(void){ SEOS_UMODE objtype; /* Object type */uid_t uID; /* User ID */char uName[256]; /* User name */int handle; /* Handle */int regular = 1; /* Mode flag */int rv;

/* -------------------------------------------------------------- *//* Get user information from the database. *//* -------------------------------------------------------------- */rv = seadmapi_WhoAmI(&uID, &handle, uName, &objtype);

/* -------------------------------------------------------------- *//* If failed, display message and quit. *//* -------------------------------------------------------------- */if ( (rv != 0) || (uName[0] == '?') )

{ fprintf(stderr, "Can't find current user name.\n", uName, rv);return 1;

}

/* ------------------------------------------------------------- *//* Display the user information: *//* ------------------------------------------------------------- */printf("User Name : %s\n", uName);printf("User ID : %ld\n", uID);printf("User Handle : %ld\n", handle);

seadmapi_WhoAmI

158 Version 3.7

/* ------------------------------------------------------------- *//* Display user authorization attributes by using the *//* SEOS_UMODE_is macro. *//* ------------------------------------------------------------- */printf("User Mode :");if ( SEOS_UMODE_is_auditor(objtype) )

{ printf(" AUDITOR");regular = 0;

}

if ( SEOS_UMODE_is_operator(objtype) ){ printf(" OPERATOR");regular = 0;

}

if ( SEOS_UMODE_is_admin(objtype) ){ printf(" ADMIN");regular = 0;

}

if ( SEOS_UMODE_is_pwmanager(objtype) ){ printf(" PWMANAGER");regular = 0;

}

if ( regular )printf(" REGULAR\n");

elseprintf("\n");

return 0;}

See Also“seadmapi_GetObjType” on page 160

seadmapi_WhoAmI


8.A

dm

inistratio

nA

PI

Referen

ce

seadmapi_GetObjType

Synopsisint seadmapi_GetObjType(SEOS_UMODE *objtype);

DescriptionThis function retrieves the object type stored in the current process’sACEE. This information can be used in conjunction with severalmacros to determine whether the current process belongs to a userwith one of the special attributes that may be assigned to a user -ADMIN, AUDITOR, SERVER, PWMANAGER, etc.

Note: The header file seadmapi.h contains several macros thatoperate on this variable data, to determine whether a user hasa specific attribute. These macros have the common notationof SEOS_UMODE_is_attribute.

AuthorizationThis function can be called by every process in the system.

Argumentsobjtype

A pointer to a SEOS_UMODE type variable that is filledfrom the current process’s ACEE.


ExamplesThe following program shows how to use this function./* ============================================================

Project : TACFFile : mymode.cPurpose : Sample for seadmapi_GetObjType

Display user's mode:REGULAR AUDITOR ADMIN OPERATOR SERVER or PWMANAGER.

============================================================ */

#include <stdio.h>

#include <seostype.h>#include <seadmapi.h>

int main(void)

seadmapi_GetObjType

160 Version 3.7

{ int rv;SEOS_UMODE umode;

if ( (rv = seadmapi_GetObjType(&umode)) == 0){printf("My mode is 0x%x : ", umode);if ( umode != 0 ){if ( umode & SEOS_UMODE_AUDITOR )printf("Auditor ");

if ( umode & SEOS_UMODE_OPERATOR )printf("Operator ");

if ( umode & SEOS_UMODE_ADMIN )printf("Admin ");

if ( umode & SEOS_UMODE_SERVER )printf("Server ");

if ( umode & SEOS_UMODE_PWMANAGER )printf("PwManager ");

}elseprintf("Regular ");

printf("\n");return 0;

}fprintf(stderr, "Error 0x%X for seadmapi_GetObjType.\n", rv);return 1;

}

See Also“seadmapi_WhoAmI” on page 157

seadmapi_GetObjType


8.A

dm

inistratio

nA

PI

Referen

ce

seadmapi_SendAuditRecord

Synopsisint seadmapi_SendAuditRecord(int type,

int result,void *data);

DescriptionThe seadmapi_SendAuditRecord function sends any type of auditinformation to the TACF audit log. This function is used internallyby other functions provided with this API, to submit specific typesof audit log records to the log file. We advise you to use the specificfunctions for each audit record type rather than using this function,although in several cases, the use of this one may be easier.

Note: Whenever possible, use the specific audit function rather thanthe seadmapi_SendAuditRecord function.


¶ ADMIN

¶ AUDITOR

¶ SERVER


Argumentstype The type of the audit record. For a list of valid values, see

the selogtype.h header file.

result One of the valid result codes supported by TACF. For validvalues, see the selogtype.h header file.

data A pointer to the audit record data. This pointer must point tovalid data according to the type of record being submitted.


162 Version 3.7


See Also“seadmapi_SendLoginAudit seadmapi_SendGenrAuditseadmapi_SendWatchdogAudit seadmapi_SendInetAuditseadmapi_SendAdminAudit” on page 166



8.A

dm

inistratio

nA

PI

Referen

ce

seadmapi_SendStartupAuditseadmapi_SendShutdownAuditseadmapi_SendUserAudit

Synopsisint seadmapi_SendStartupAudit(SEOS_AUDITSTART *rec,

int result);

int seadmapi_SendShutdownAudit(SEOS_AUDITDOWN *rec,int result);

int seadmapi_SendUserAudit(SEOS_AUDITUSER *rec,int result);

DescriptionThese functions send audit records to the TACF audit log. Thefunctions use the seadmapi_SendAuditRecord function describedon page 190. It is recommended to use these functions rather thandirectly calling the seadmapi_SendAuditRecordfunction.

The seadmapi_SendStartupAudit function sends audit records tothe TACF audit log in the format of startup records.

The seadmapi_SendShutdownAudit function sends audit records tothe TACF audit log in the format of shutdown records.

The seadmapi_SendUserAudit function sends audit records to theTACF audit log in the format of user records.

Note: TACF uses a compression algorithm on the auditinginformation. It is therefore recommended to initialize thestructure with zero’s before filling in the information. Thestructure can be initialized by calling the memset functionprovided by the standard C library of every system.


¶ ADMIN

seadmapi_SendStartupAudit, Shutdown, User

164 Version 3.7

¶ AUDITOR

¶ SERVER


Argumentsrec A pointer to the structure containing event-specific data.

result One of the valid result codes supported by TACF. For a listof valid result codes, see the selogtype.h header file.


See Also“seadmapi_SendAuditRecord” on page 162

seadmapi_SendStartupAudit, Shutdown, User


8.A

dm

inistratio

nA

PI

Referen

ce

seadmapi_SendLoginAuditseadmapi_SendGenrAuditseadmapi_SendWatchdogAuditseadmapi_SendInetAuditseadmapi_SendAdminAudit

Synopsisint seadmapi_SendLoginAudit(SEOS_AUDITLOGIN *rec,

int result);

int seadmapi_SendGenrAudit(SEOS_AUDITGENR *rec,int result);

int seadmapi_SendWatchdogAudit(SEOS_AUDITWDWARN *rec,int result);

int seadmapi_SendInetAudit(SEOS_AUDITINWARN *rec,int result);

int seadmapi_SendAdminAudit(SEOS_ADMINAUDIT *rec,int result);

DescriptionThese functions send audit records to the TACF audit log. Thefunctions use the seadmapi_SendAuditRecord function describedon page 190. It is recommended to use these functions rather thandirectly calling the seadmapi_SendAuditRecordfunction.

The seadmapi_SendLoginAudit function sends audit records to theTACF audit log in the format of login event records.

The seadmapi_SendGenrAuditfunction sends audit records to theTACF audit log in the format of general resource records.

The seadmapi_SendWatchdogAudit function sends audit records tothe TACF audit log in the format of watchdog records.

The seadmapi_SendInetAudit function sends audit records to theTACF audit log in the format of TCP/IP records.

seadmapi_SendLoginAudit, Genr, Watchdog

166 Version 3.7

The seadmapi_SendAdminAuditfunction sends audit records to theTACF audit log in the format of administrative records.

Note: TACF uses a compression algorithm on the auditinginformation. It is therefore recommended to initialize thestructure with 0’s before filling in the information. Thestructure can be initialized by calling the memset functionprovided by the standard C library of every system.


¶ ADMIN

¶ AUDITOR

¶ SERVER


Argumentsrec A pointer to the structure containing event-specific data.

result One of the valid result codes supported by TACF. For a listof valid result codes, see the selogtype.h header file.


See Also“seadmapi_SendAuditRecord” on page 162

seadmapi_SendLoginAudit, Genr, Watchdog


8.A

dm

inistratio

nA

PI

Referen

ce

seadmapi_SendErrorLog

Synopsisint seadmapi_SendErrorLog(SEOS_REQ_ERRORDESCP *rec);

DescriptionThis function is used by daemons to place a trace-back to note apossible error or malfunction. The error description is common forall error records in the TACF error log file.

Note: TACF uses a compression algorithm on the error information.We recommend that you initialize the structure with 0’sbefore filling in the information. The structure can beinitialized by calling the memset function provided by thestandard C library of every system.

AuthorizationThe seadmapi_SendErrorLog function can be used only by theTACF watchdog and the TACF agent daemons.

Argumentsrec A pointer to the structure containing a description of the

error and the trace-back data.


seadmapi_SendErrorLog

168 Version 3.7

seadmapi_ProcessControl

System Environmentint seadmapi_ProcessControl(unsigned long flags);

DescriptionThis function is used by a process to control its auditing level andsecurity. Any process can call this function to turn on auditing for alloperations or to delete the credentials associated with the process.Using the flags parameter a process can control these values. Theflags parameter can contain any of the values described below or abit-wise ORed value of those.

The following values are currently supported:

SEADMAPI_PROCCNTL_NOACEEA request by a process to remove its ACEE and use thecredentials of a user who is not defined to TACF. The newNULL credentials are assigned to the process and any childprocesses.

SEADMAPI_PROCCNTL_LOGALLA request to audit every request made by the process and itschild processes.

This function is used by the TACF senone utility.

AuthorizationThis function can be called by every process in the system.

Argumentsflags One or more bit-wise values.


seadmapi_ProcessControl


8.A

dm

inistratio

nA

PI

Referen

ce

seadmapi_consTraceClearseadmapi_consTraceDisableseadmapi_consTraceEnableseadmapi_consTraceGetStatusseadmapi_consTraceToggle

Synopsisint seadmapi_consTraceClear (int *CurrStatus);

int seadmapi_consTraceDisable (int *CurrStatus);

int seadmapi_consTraceEnable (int *CurrStatus);

int seadmapi_consTraceGetStatus (int *CurrStatus);

int seadmapi_consTraceToggle (int *CurrStatus);

DescriptionThese functions control the TACF trace logging. The trace functionis used to help diagnose problems and to help understand how TACFbehaves.

All functions return the TACF trace status after the call. A value of 1means the trace is enabled, while 0 means the trace is disabled. Ifthe CurrStatus parameter specified to any of these functions isNULL, the function does not fill in current status of the trace. Thesefunctions and the -t switch of the secons utility provide the samefunctionality.

Note: Trace status is not maintained across sessions of the TACFdaemon.

AuthorizationThese functions can be called by users who have the ADMIN orOPERATOR attribute.

ArgumentsCurrentStatus

Status of the trace after the call.

seadmapi_consTraceClear, Disable, Enable

170 Version 3.7


seadmapi_consTraceClear, Disable, Enable


8.A

dm

inistratio

nA

PI

Referen

ce

seadmapi_consUidLoginDisableseadmapi_consUidLoginEnableseadmapi_consUidLoginGetStatus

Synopsisint seadmapi_consUidLoginDisable (int uid);

int seadmapi_consUidLoginEnable (int uid);

int seadmapi_consUidLoginGetStatus (int uid,int *CurrStatus);

DescriptionThese functions operate on a user’s concurrent login setting. Thefunctions are used to:

¶ disable concurrent logins for the user.

¶ enable concurrent logins for the user.

¶ retrieve the current concurrent logins setting for the user.

The user is identified by the uid parameter.

These functions and the -d and -u switches of the secons utilityprovide the same information.

The seadmapi_consUidLoginDisable function disables concurrentlogins for the specified user ID. Theseadmapi_consUidLoginEnablefunction re-enables concurrentlogins for the specified user ID. Theseadmapi_consUidLoginGetStatus function retrieves the status ofthe user’s concurrent logins setting as provided by the authorizationdaemon.

Notes:

1. Enabling or disabling concurrent logins is not maintained acrosssessions of the TACF daemon.

2. TACF provides an enforced concurrent logins mechanism that issuitable for most sites. Use the MAXLOGINS parameter of thesetoptions command to set the maximum number of concurrently

seadmapi_consUidLoginDisable, Enable

172 Version 3.7

logged-in terminals for every user in the system. (If you giveMAXLOGINS a zero value, there will be no maximum enforcedby the setoptions command.)

AuthorizationUsers can disable or enable concurrent logins for themselves.

Users with the ADMIN or OPERATOR attribute can disableconcurrent logins for any user.

Argumentsuid The user ID on which the function is to operate.

CurrentStatusThe current status of the user’s concurrent logins setting.


seadmapi_consUidLoginDisable, Enable


8.A

dm

inistratio

nA

PI

Referen

ce

seadmapi_consAllLoginDisableseadmapi_consAllLoginEnableseadmapi_consAllLoginGetStatus

Synopsisint seadmapi_consAllLoginDisable (void);

int seadmapi_consAllLoginEnable (void);

int seadmapi_consAllLoginGetStatus (int *CurrStatus);

DescriptionThese functions control the ability of users to log into the system. Iflogin is disabled, no user is permitted to log into the system whileTACF is running. These functions are the same as the functionsprovided by the -L switch of the secons utility.

Notes:

1. The root user is always allowed to login, and is not subject todisabling by this global flag.

2. Enabling or disabling login ability is not maintained acrosssessions of the TACF daemon.

AuthorizationThese functions can be called only by users who have the ADMINor OPERATOR attribute.

ArgumentsCurrentStatus

The current status of the system-wide disable login flag.


seadmapi_consAllLoginDisable, Enable

174 Version 3.7

seadmapi_consRunTimeStatisticsGet

Synopsisint seadmapi_consRunTimeStatisticsGet(SEADMAPI_RTSTAT *rtsStat);

DescriptionThis function retrieves run-time statistics on the TACF authorizationdaemon. This information can also be viewed by using the seconsutility. The information is placed in the structure pointed to by thertsStat parameter. The structure contains the following information:

inet_denyThe number of TCP/IP requests that were denied.

inet_grantThe number of TCP/IP requests that were granted.

inet_errorThe number of TCP/IP requests that could not be resolvedbecause of an error.

audit_log_qThe number of unwritten audit records in the queue.

error_log_qThe number of unwritten error records in the queue.

oidLastLast used object ID.

pidLastLast used property ID.

cidLastLast used class ID.

classRecCountNumber of classes in TACF database.

propRecCountNumber of properties in TACF database.

objRecCountNumber of objects (records) in TACF database.



8.A

dm

inistratio

nA

PI

Referen

ce

pvRecCountNumber of records in properties-values TACF database.

nAceeHandlesNumber of ACEE entries currently used.

nClientsNumber of protected clients (reserved for future use).

nTrustedNumber of trusted programs loaded into TACF cache.

nUntrustedNumber of programs marked as non-trusted in TACF cache.

This function and the -i switch of the secons utility provide the sameinformation.

Note: The information retrieved by this function may be extended infuture versions of TACF; however, backward compatibilitywill always be maintained. Therefore, the size of the structurewill serve as an indication of the TACF version in use. Anyadditional information will be added at the end of this buffer.

AuthorizationThis function can only be called by users who have the ADMIN orOPERATOR attribute.

ArgumentsrtsStat A structure containing the run-time statistics, as described in

the Description.



176 Version 3.7

seadmapi_consMessageSend

Synopsisint seadmapi_consMessageSend(const char *szMessage);

DescriptionThis function submits a message to the TACF trace. This functionand the -m switch of the secons utility do the same thing.

AuthorizationThis function can be called by any user.

ArgumentsszMessage

String of the message to place in the trace log.


seadmapi_consMessageSend


8.A

dm

inistratio

nA

PI

Referen

ce

seadmapi_consShutDown

Synopsisint seadmapi_consShutDown(void);

DescriptionThis function shuts down the TACF authorization daemons - seosd,seoswd, and seagent. After shutting the TACF daemons down, thekernel extension remains loaded but is not active until seosd isexecuted again. The shutdown disables all protection provided bySeOS Access Control. Other daemons that are part of TACF, such asserevu, selogrd, and selogrcd, are not affected by this function.These processes can be killed explicitly. Theseadmapi_consShutDownfunction and the -s switch of the seconsutility do the same thing.

AuthorizationThis function can only be called by users who have the ADMIN orOPERATOR attribute.


seadmapi_consShutDown

178 Version 3.7

seadmapi_ReloadIni

Synopsisint seadmapi_ReloadIni(void):

DescriptionThis function reloads the configuration toakens of the TACF daemonseosd. The tokens are in the seos.ini file. The daemon actually usesonly part of the newly reloaded tokens.

Return ValueIf the function succeeds, it returns 0; if it fails, it returns an errorcode.

NotesThis function can only be called by users who have the ADMIN orOPERATOR attribute.

seadmapi_ReloadIni


8.A

dm

inistratio

nA

PI

Referen

ce

seadmapi_WhoIs

Synopsisint seadmapi_WhoIs(char *szUName, SEOS_UMODE *objtype);

DescriptionThe seadmapi_WhoIs function supplies information about thespecified user. The function gets the user type - attribute - from theTACF database. The memory area pointed to by the szUNameparameter must be large enough to accommodate 255 characters.

Note: The header file seadmapi.h contains several macros thatoperate on the objtype variable data, to determine whether auser has a specific attribute. These macros have the commonnotation of SEOS_UMODE_is_attribute.

AuthorizationThe function can be called by every process in the system.

AttributesszUName

The user name associated with the current process.

objtypeThe user type as saved in the database. This specifies theattributes assigned to the user.


seadmapi_Whols

180 Version 3.7

sepass_ReplacePassword

Synopsisint sepass_ReplacePassword (char *userName,

char *oldPsswd,char *newPsswd,char *szPmd,char * szMsgint msgLen,int domainCodes,int debug,int ignoreRules,int keep_grace,int do_as_user);

DescriptionThe sepass_ReplacePassword function replaces the user passwordwith a new password. Assuming that the user is defined locally, andSEPASS_API_DOMAIN_PMD is not given in the domainCodesarguments, sepass_ReplacePassword replaces the user’s password inthe local UNIX file. Here are the criteria for password replacement.The password can be replaced in the following circumstances:

¶ In the local security database, assuming thatSEPASS_API_DOMAIN_PMD is not given in the domainCodes.

¶ If the policy model confirms the password file.

¶ If a policy model is given.

¶ If a policy model is defined in seos.ini.

¶ If a policy model is specified for the user or its profile groupand the SEPASS_API_DOMAIN_LOCAL is not specified.

¶ If the policy model database is given.

¶ If the policy model database is defined in the seos.ini, orspecified for the user or its profile group, and theSEPAS_API_DOMAIN_LOCAL is not specified.

¶ If the NIS+ map and the nis_env token is set to nisplus.



8.A

dm

inistratio

nA

PI

Referen

ce

ArgumentsuserName

A NULL-terminated string containing the name of the userwhose password is to be replaced.

OldPasswdA NULL-terminated string containing the current (old)password of either the user named, or the administratorinvoking the function.

newPasswdA NULL-terminated string containing the new (desired)password.

szPmd A NULL-terminated string containing the name of the policymodel on which to change the password model (if any).

szMsg A pointer to a buffer in which the success or failuremessages will be stored.

msgLenSize of the above buffer.

domainCodesOne of the values listed below:#define SEPASS_API_DOMAIN_LOCAL#define SEPASS_API_DOMAIN_PMD#define SEPASS_API_DOMAIN_ALL

debug A flag indicating the detailed description that should beprinted.

ignoreRulesThis argument can have one of three values:IGNORE_NEVER, IGNORE_ALWAYS, andIGNORE_ADMIN. IGNORE_NEVER means never ignorepassword quality rules; IGNORE_ALWAYS means alwaysignore password policy rules; IGNORE_ADMIN meansignore password policy rules only in administrative change.

keep_graceReset the grace attribute for the user after password change.


182 Version 3.7

do_as_userChange the password as if the named user is changing it,and not as an admin change.



8.A

dm

inistratio

nA

PI

Referen

ce


184 Version 3.7

Structures and Data Types

This chapter describes the structures and data types used by theTACF API functions to pass information back and forth between thefunctions and the TACF daemons. Every field of these datastructures is described.

IntroductionThe Authorizations, Exits, and LogRoute APIs use the following datatypes:

Data type Description

PFSEOSEXITFUNC Contains a pointer to a function.

SEOS_ACCS Contains a list of access flags.

SEOS_CID Contains the class identification descriptor.

SEOS_OID Contains the object identification descriptor.

SEOS_PID Contains the property identification descriptor.

SEOS_X_OID Holds an expanded object identificationdescriptor.

The Authorizations, Exits, and LogRoute APIs use the followingstructures:

Structure Description

API_AUTH_RES Holds the result of an authorization check.

CLIENT_ACEE Contains the information for a given ACEE.

9


9.S

tructu

resan

dD

ataTyp

es


LOGRAPI_FUNCS Contains the LogRoute API implementationfunctions.

LOGRECHDR Stores the audit log record header.

LOGRECORD Stores the audit log record data.

SEADMAPI_RTSTAT Contains the run time statistics.

SEGRACE_RES Contains the grace login information.

SEOS_ACCESS Encapsulates a single member of typeSEOS_ACCS.

SEOS_ACL Contains a list of ACLs.

SEOS_AUDITADMIN Used for database update events.

SEOS_AUDITDOWN Used for TACF daemons going down.

SEOS_AUDITGENR Used for General Resource Check events.

SEOS_AUDITINWARN Used for TCP/IP Request events.

SEOS_AUDITLOGIN Used for Login events.

SEOS_AUDITSTART Used for TACF daemons starting up.

SEOS_AUDITUSER Used to write trace records to the audit logwhen each action of a user is being audited.

SEOS_AUDITWDWARN Used for TACF Watchdog events.

SEOS_EXITGENR Used for General Resource Check events.

SEOS_EXITINET Used for TCP/IP Request events.

SEOS_EXITLOGIN Used for login events.

SEOS_EXITPASS Used for Password Quality Check andPassword Change events.

SEOS_EXITRES Results returned to TACF after any event.

SEOS_GCONN Contains a list of the groups a user isconnected to and the attributes the user has, ifany, in each group.

SEOS_PACL Contains a list of PACLs.

SEOS_REQ_ERRORDESCPContains a description of the error and thetrace-back data.

SEOS_ROUTENTRY Stores the configuration file entry.

186 Version 3.7


SEOS_X_ACL Contains a list of ACLs with additionalinformation.

SEOS_X_GCONN Contains a list of the groups a user isconnected to and the attributes the user has, ifany, in each group. The list contains moreinformation than the SEOS_GCONNstructure.

SEOS_X_PACL Contains an expanded list of PACLs.

SEOSDB_CDF Contains the definition of a specific class inthe TACF database.

SEOSDB_ENTDAT Contains information about a property in thedatabase.

SEOSDB_ODF Contains the definition of a specific object inthe TACF database.

SEOSDB_PDF Contains the definition of a specific propertyin the TACF database.

API_AUTH_RES StructureThis structure contains the following fields:

int resultThis field can take one of the following values:

P Permission to access the resource was granted.

D The requested access was denied.

C Usually indicates the TACF database has beencorrupted.

int last_stageThe authorization stage at which the information in thestructure was written. This information is useful if accesswas granted, but the authorization failed later for somereason.


9.S

tructu

resan

dD

ataTyp

es

int grant_stageThe authorization stage at which the permit or deny decisionwas made.

SEOS_ACCS allowed_accsThe maximum level of access the accessor has to theresource. For a list of possible accesses, see “SEOS_ACCSData Type” on page 196.

SEOS_OID oidResThe object ID of the resource for which authorization waschecked.

SEOS_OID oidGroupIf accumulated group rights are being checked and if accessis allowed or denied by a group, this member stores theobject ID of the last group checked.

If accumulated group rights are not being checked and ifaccess is allowed or denied by a group, this member storesthe object ID of the group.

CLIENT_ACEE StructureThis structure contains the following fields:

longhAceeThe ACEE’s handle.

long nGroupsThe number of group connections.

CLIENT_ACEE_GCONN *GroupsThe group connection array.

long nCategoriesThe number of categories.

char **pszCategoriesThe array of category names.

char *szSecLabelThe security label.

API_AUTH_RES Structure

188 Version 3.7

char *szUsernameThe user’s name.

SEOS_UAUDIT_MODE AuditModeThe user’s audit mode.

unsigned char SecLevelThe user’s security level.

char *szTerminalThe source terminal.

int countThe process count for the ACEE.

SEOS_UMODE user_modeThe user’s mode.

time_t create_timeThe ACEE’s creation time.

LOGRAPI_FUNCS StructureThe LOGRAPI_FUNCS structure contains pointers to the userdefined functions for each of the tasks that are to be performed by adestination type. This structure is used only during target typeregistration. The LOGRAPI_FUNCS structure contains the followingfields:

LogrApiSendFunc pfSendA pointer to the user’s send function.

LogrApiFreeFunc pfFreeA pointer to the user’s free function.

LogrApiSenseFunc pfSenseA pointer to the user’s sense function.

CLIENT_ACEE Structure


9.S

tructu

resan

dD

ataTyp

es

LOGRECHDR StructureThere are many different types of audit log records, each with itsown structure format. TACF has to know what kind of recordstructure to expect for the next record; therefore, each record storedin the audit log file has a header structure common to all audit logrecords.

LOGRECHDR is the header structure common to all audit logrecords. The LOGRECHDR structure contains the following fields:

unsigned long nBytesThe size, in bytes, of the record in the compressed log file,not including the header.

time_t tLogThe time the record was placed in the file.

unsigned long positorA code for the module that put - wrote - the record.Normally, it has a value of zero.

unsigned long rectypeThe record type. The values of the field rectype can befound in the following table:

Record type Corresponding integer code

AUDIT_LOGIN 1

AUDIT_GENR 2

AUDIT_WATCHDOG 3

AUDIT_INWARN 4

AUDIT_ADMIN 5

AUDIT_DOWN 6

AUDIT_START 7

AUDIT_USER 8

unsigned long rvThe reason the record was written in the log. The values ofthe field rv can be found in the following table:

LOGRECHDR Structure

190 Version 3.7

Symbol Value Auditrecordtypes

Description

SEOS_AUTH_CHECK C All An error occurred inTACF.

SEOS_AUTH_DENY D Login,general,resource,Admin, Inet

TACF denied access to aresource, did not permita login, or did notpermit an update to theTACF database becausethe accessor did nothave sufficientauthorization.

SEOS_AUTH_PASS P Login,general,resource,Inet

TACF permitted accessto a resource orpermitted a login.

SEOS_DOWN_RES M Down, start The TACF daemonsstarted up or shut down.

SEOS_LANG_DENY D Admin An attempt to update theTACF database wasdenied.

SEOS_LANG_FAIL F Admin An attempt to update theTACF database failed.

SEOS_LANG_SUCC S Admin The TACF database wassuccessfully updated.

SEOS_LOGATP_RES A Login An attempt to log infailed because an invalidpassword was enteredmore than once.

SEOS_LOGDIS_RES I Login Serevu daemon disableda user account.

SEOS_LOGENA_RES E Login Serevu daemon enableda disabled user account.

SEOS_LOGOUT_RES O Login A user logged out.

LOGRECHDR Structure


9.S

tructu

resan

dD

ataTyp

es

Symbol Value Auditrecordtypes

Description

SEOS_USER_RES T User An audit record waswritten because all theactions of the user arebeing traced.

(none) U Resource A trusted program(setuid or setgid) waschanged; therefore, it isnow untrusted.

SEOS_WATCHDOG_RES

W Watchdog The TACF daemonseoswd or seosd set aprogram in thePROGRAM class or afile in the SECFILEclass as untrusted.

LOGRECORD StructureThis structure contains the complete audit log record. The genericvoid*data points to any of the data structures used to hold the recorddata. The LOGRECORD structure contains the following fields:

LOGRECHDR lrhLog record header.

void *dataThe compressed data record. Note that the user’s functionreceives this data after it is uncompressed.

See Also“LOGRECHDR Structure” on page 190

PFSEOSEXITFUNC Data TypeThis data type is a pointer to a function. The PFSEOSEXITFUNCstructure contains the following fields:

LOGRECHDR Structure

192 Version 3.7

void *data_bufferContains information about a specific event for which theexit function was called.

SEOS_EXITRES *p_sexrContains the results of the exit function.

int The value returned by the authxapi function. The values areshown in the following table:

Return code Value Meaning

AUTHXAPI_E_EINVAL 1 Invalid (NULL) pointers.

AUTHXAPI_E_NOCLASS 2 Required class not found.

AUTHXAPI_E_NOOBJ 3 Required object not found.

AUTHXAPI_E_DBERROR 4 Suspect corruption of database.

AUTHXAPI_E_INVOBJ 5 Invalid object descriptor.

AUTHXAPI_E_INVPROP 6 Invalid property descriptor.

AUTHXAPI_E_NOPROP 7 Required property not found.

AUTHXAPI_E_PTYPE 8 Property type is not a list.

AUTHXAPI_E_NOVAL 9 No value for propertyassociated with this object.

AUTHXAPI_E_NOHANDLE 10 Invalid TACF handle.

AUTHXAPI_E_NOACEE 11 No ACEE for this handle.

AUTHXAPI_E_OCCUPIED 12 Exit function already installed.

AUTHXAPI_E_NOEVENT 13 No such event.

SEADMAPI_RTSTAT StructureThis structure contains the information retrieved from the functionseadmapi_consRunTimeStatisticsGet. The SEADMAPI_RTSTATstructure contains the following fields:

unsigned int inet_denyThe number of Inet requests that were denied.

unsigned int inet_grantThe number of Inet requests that were granted.

PFSEOSEXITFUNC Data Type


9.S

tructu

resan

dD

ataTyp

es

unsigned int inet_errorsThe number of Inet requests that contained errors.

long audit_log_qThe audit log queue size.

long error_log_qThe error log queue size.

SEOS_OID oidLastThe first free object ID in the database.

SEOS_PID pidLastThe first free property ID in the database.

SEOS_CID cidLastThe first free class ID in the database.

long classRecCountThe number of classes in the TACF database.

long propRecCountThe number of properties in the TACF database.

long objRecCountThe number of objects in the TACF database.

long pvRecCountThe number of property values in the TACF database.

long nAceeHandlesThe number of ACEE handles currently in the system.

long nClientsThe number of protected clients.

long nTrustedThe number of trusted programs currently in the TACFdatabase.

long nUnTrustedThe number of untrusted programs currently in the TACFdatabase.

SEADMAPI_RTSTAT Structure

194 Version 3.7

SEGRACE_RES StructureThis structure contains the data returned byseadmapi_GetGraceInfo. The SEGRACE_RES structure containsthe following fields:

int stepAn integer representing the type of information contained inthe structure. Step can hold one of the following values:

Code Value Meaning

SEGRACE_STEP_NONE 0 There is nothing to display.

SEGRACE_STEP_WARN 1 Display a warning to the user,such as the number of grace daysthe user has left or the number ofdays until the user’s passwordexpires.

SEGRACE_STEP_MUST 2 The user’s password has expired;it must be replaced now.

char msgThe message that is displayed to the user.

char last_logA message containing information regarding the user’s lastlogin.

int graceThe number of grace logins left to the user.

int daysThe number of days until the user must replace thepassword.

char unameThe name of the user for whom the inquiry is done.

SEOS_ACCESS StructureThis structure contains the following field:

SEGRACE_RES Structure


9.S

tructu

resan

dD

ataTyp

es

SEOS_ACCS accsThe type of access requested.

See Also“SEOS_ACCS Data Type”

SEOS_ACCS Data TypeAn unsigned long integer representing the type of access requested.The following is a list of access codes currently defined in the APIs:

Type ofrequest

Access Codes Meaning

All requests SEOS_ACCS_ANY Everything allowed

SEOS_ACCS_AUTHORIZE

Changing ACLs allowed

SEOS_ACCS_CREATE Allowed to create new filesin class FILE and newobjects in class ADMIN.

SEOS_ACCS_DELETE Delete allowed (same asSEOS_ACCS_ERASE)

SEOS_ACCS_ERASE Delete allowed

SEOS_ACCS_EXEC Executing Program allowed

SEOS_ACCS_ FILESCAN Not in use

SEOS_ACCS_JOIN Adding users to or removingusers from groups allowed

SEOS_ACCS_MODIFY Rename allowed

SEOS_ACCS_NONE Nothing allowed

SEOS_ACCS_PASSWD Changing passwordattributes allowed

SEOS_ACCS_READ Read allowed

SEOS_ACCS_RENAME Rename allowed for files

SEOS_ACCS_WRITE Write allowed

SEOS_ACCS_reserved Not in use

SEOS_ACCESS Structure

196 Version 3.7

Type ofrequest

Access Codes Meaning

UNIX-specificrequests

SEOS_ACCS_CHOWN Changing Ownershipallowed

SEOS_ACCS_CHGRP Changing Group Settingallowed

SEOS_ACCS_CHMOD Changing File Modeallowed

SEOS_ACCS_UTIMES Changing modification timeof files allowed

GENERICattributes

SEOS_ACCS_SEC Changing ACLs of Filesallowed

MACROS toincludemultiple accessrequests

SEOS_ACCS_CHOG CHOWN + CHGRP

SEOS_ACCS_UPDATE READ + WRITE + EXEC

SEOS_ACCS_ CONTROL CHOG + CHMOD +UTIMES + SEC + UPDATE

SEOS_ACL StructureThe SEOS_ACL record describes the access permitted to anaccessor. The SEOS_ACL structure contains the following fields:

SEOS_OID oidAccessorThe object ID of the accessor.

SEOS_ACCS AccsUser’s level of access to the resource. For a list of availableaccess types, see “SEOS_ACCS Data Type” on page 196.

SEOS_AUDITADMIN StructureThe SEOS_AUDITADMIN record is submitted to the audit log filewhen a TACF command updates the TACF database. TheSEOS_AUDITADMIN structure contains the following fields:

char szClassClass on which the operation was performed.

SEOS_ACCS Data Type


9.S

tructu

resan

dD

ataTyp

es

char objnameObject on which the operation was performed.

char userUser who issued the command.

int reasonCode explaining why the record was created. For a list ofthe possible codes, see “SEOS_AUDITLOGIN Structure” onpage 201.

int stageThe stage in the authorization algorithm when the decisionwas made to grant or deny the request. The TACF APIincludes a listing of the TACF stage codes in the header fileseauthstages.h.

char terminalTerminal from which the operation was performed.

char commandThe TACF command that was performed.

SEOS_AUDITDOWN StructureThe SEOS_AUDITDOWN record is submitted when a TACFdaemon is brought down. The SEOS_AUDITDOWN structurecontains the following fields:

char szUserThe name of the user who brought the daemon down.

char servnameThe name of the daemon which the user brought down.

int stageThe stage in the authorization algorithm when the decisionwas made to grant or deny the request. The stages are listedin the TACF status codes section of the Tivoli SecureWaySecurity Manager Reference Guide for TACF. The TACFAPI includes a listing of the TACF stage codes in the headerfile seauthstages.h.

SEOS_AUDITADMIN Structure

198 Version 3.7

SEOS_AUDITGENR StructureThe SEOS_AUDITGENR record may be submitted to the audit logfile when a user accesses or attempts to access a general resource.The SEOS_AUDITGENR structure contains the following fields:

char szUserNameName of user attempting to gain access.

char szResClassClass of resource being accessed.

char szResourceName of resource being accessed.

int logReasonReason this audit log record was added to the file. Either theuser or the resource involved has been flagged for auditing.See the file seauthstages.h in the directory /usr/seos/include.For the list of reason codes, see “SEOS_AUDITWDWARNStructure” on page 203.

int stageThe stage in the authorization algorithm when the decisionwas made to grant or deny the request.The stages are listedin the TACF status codes section in the Tivoli SecureWaySecurity Manager Reference Guide for TACF. The TACFAPI includes a listing of the TACF stage codes in the headerfile seauthstages.h.

SEOS_ACCS accessRequested level of access to the resource. For a list ofavailable access types, see “SEOS_ACCS Data Type” onpage 196.

uid_t uidUser’s UNIX user ID.

char szProgName of the program which attempted to gain access to theresource.

SEOS_AUDITGENR Structure


9.S

tructu

resan

dD

ataTyp

es

char szTermName of the terminal or network host from which the userlogged in.

SEOS_AUDITINWARN StructureThe SEOS_AUDITINWARN record is submitted to the audit log filewhen a remote host attempts to access the local host and that remotehost has been flagged for auditing. The SEOS_AUDITINWARNstructure contains the following fields:

char addressInternet address of the remote host attempting access. This iscurrently the 4 byte address of TCP.

char af_typeAF number. Currently only AF_INET (2).

long portPort number to which access was attempted.

long protoProtocol code. Currently 0.

char szProgName of the program in the local host that was trying toaccept the access request.


int logReasonReason this audit log record was added to the file. Either theuser or the resource involved has been flagged for auditing.See the file seauthstages.h in the directory /usr/seos/include.For the list of reason codes, see “SEOS_AUDITWDWARNStructure” on page 203.

SEOS_AUDITGENR Structure

200 Version 3.7

SEOS_AUDITLOGIN StructureThe SEOS_AUDITLOGIN record may be submitted to the audit logfile when a user logs in, attempts to log in, or logs out, when serevudisables or enables a user, when a user fails to log in after a certainnumber of attempts, or when seosd detects an attack on the network.

If the access and use of a resource is being monitored, audit recordsare also submitted to the audit log.

Logout audit records are submitted to the log file only if a loginrecord was also submitted; i.e., the user’s audit mode includesauditing of successful logins or the terminal from which the userlogged in has an audit mode that includes the auditing of successfulaccesses.

The SEOS_AUDITLOGIN structure contains the following fields:

char szUserNameName of user logging in.

char szTerminalName of terminal or network host from which user islogging in.

int LogCodeReason this audit log record was added to the file. There areseveral possible reasons for TACF to record a login event.The possible values of LogCode are:

Source Code Meaning

Login SEOS_AUTH_PASS The user was allowed to log in.

Login SEOS_AUTH_DENY The user was not allowed to login.

Login SEOS_AUTH_CHEK There was an error in the TACFdatabase.

NAP SEOS_LOGATP_RES Detected an attack on thenetwork.

Serevu SEOS_LOGATP_RES Detected attempt to breakpassword.

SEOS_AUDITLOGIN Structure


9.S

tructu

resan

dD

ataTyp

es

Source Code Meaning

Serevu SEOS_LOGDIS_RES The specified user account wasdisabled by serevu because oftoo many login attempts.

Serevu SEOS_LOGENA_RES The specified user account wasreactivated by serevu afterbeing disabled for theconfigured time period.

Logout SEOS_LOGOUT_RES User logged out.


uid_t uidUser’s UNIX user ID.

char szProgName of the program attempting to perform the login.

Logout records are assigned the stage code SEOS_LOGOUT_RES.The stage code assigned to login records written by serevu isSEOS_LOG_SEREVU. An audit record created because of NAPdetection is assigned the stage code SEOS_LOG_NAP.

SEOS_AUDITSTART StructureThe SEOS_AUDITSTART record is submitted when a TACFdaemon is initiated. The SEOS_AUDITSTART structure contains thefollowing field:

char servnameThe name of the daemon which was started.

See Also“SEOS_AUDITDOWN Structure” on page 198

SEOS_AUDITLOGIN Structure

202 Version 3.7

SEOS_AUDITUSER StructureThe SEOS_AUDITUSER record is submitted when a trace record iswritten to the audit log. The SEOS_AUDITUSER structure containsthe following fields:

char szResClassThe name of the resource class which was accessed.

char szResourceThe name of the specific resource object - record - whichwas accessed within the class.

int codeThe code of the trace message.

int stageThe stage in the authorization algorithm when the decisionwas made to grant or deny the request. The stages are listedin the Tivoli SecureWay Security Manager Reference Guidefor TACF. The TACF API includes a listing of the TACFstage codes in the header file seauthstages.h.

uid_t uidThe user’s UNIX ID.

uid_t euidThe user’s effective UID.

uid_t ruidThe ID the user used to log in - the real user ID.

char parm_buffThe parameters in the trace message.

SEOS_AUDITWDWARN StructureThe SEOS_AUDITWDWARN record may be submitted to the auditlog file when the TACF Watchdog (seoswd) finds an integrityproblem in a trusted program or a secured file. TheSEOS_AUDITWDWARN structure contains the following fields:

SEOS_AUDITUSER Structure


9.S

tructu

resan

dD

ataTyp

es

char szClassClass name of resource being audited. This can be eitherPROGRAM or SECFILE.

char szPathFull path name of the program or secure file being audited.

int errnoSystem errno value that may have triggered this audit.

int logReasonReason this audit log record was added to the file. Either theuser or the resource involved has been flagged for auditing.See the file seauthstages.h in the directory /usr/seos/include.The values of the field logReason are as follows:

Reason code Value Meaning

WDWARN_ERROR 0 An error occurred.

WDWARN_STATCHANGED 1 Stat was changed.

WDWARN_EXIT 2 HPUX/AIX extended infochanged.

WDWARN_AIXACL 3 HPUX/AIX ACL changed.

WDWARN_CRC 4 CRC check failed.

WDWARN_STAT 5 Cannot obtain informationabout the trusted file.

WDWARN_SNEFRU 6 Snefru signatures do not match.

WDWARN_MD5 7 MD5 signatures do not match.

SEOS_CID Data TypeAn unsigned short integer representing the class ID.

Each class in the TACF database has a unique class ID. If you knowthe class ID, it is possible to use seadmapi to retrieve informationabout it.

SEOS_AUDITWDWARN Structure

204 Version 3.7

SEOS_EXITGENR StructureThe first parameter passed to exit functions linked to attemptedGeneral Resource Check events is a pointer to theSEOS_EXITGENR structure. This structure contains informationabout the user and resource being verified.

SEOS_EXITGENR contains the following fields:

char const *szClassName of the general resource class being accessed. Checkonly the classes you explicitly decide to verify, and ignorethe others.

char const *szResName of the resource being accessed.

uid_t uidUNIX user ID of the user attempting access. Set to -1 whennot applicable.

int seos_handleACEE handle associated with the user attempting access.Negative if the user is not defined in TACF; otherwise, it iszero or positive.

char const *szUserNameName of the user attempting access.

dev_t deviceDevice number of the program attempting access. Set to zerowhen not applicable.

ino_t inodeI-node number of the program attempting access. Set to zerowhen not applicable.

char const *szTermName of the terminal from which user is attempting access.If user is not at a local terminal, this is set to the remotehost name.

SEOS_EXITGENR Structure


9.S

tructu

resan

dD

ataTyp

es

SEOS_ACCESS accs_infoThe type of access requested. For the complete list, see“SEOS_ACCS Data Type” on page 196.

char const *szProgName of the program attempting access. Set to NULL whennot applicable.

SEOS_EXITINET StructureThe first parameter passed to exit functions linked to attemptedTCP/IP Connection Request Events is a pointer to theSEOS_EXITINET structure. This structure contains information onthe connection being requested. The SEOS_EXITINET structure canbe found in the authxapi.h file.

SEOS_EXITINET contains the following fields:

char const *ClientAddrThe IP address of the host requesting the connection.

char const *szHostNameName of the host requesting the connection.

int PortNumber of the port to which connection is requested.

int ProtocolProtocol code used for the connection request. Currently,only TCP is supported.

SEOS_ACCESS accs_infoThe exact level of connection access requested. For thecomplete list, see “SEOS_ACCS Data Type” on page 196.Currently, only READ access is available for TCP/IPrequests.

char const *szProgName of the program requesting a connection. Set to NULLwhen not applicable.

SEOS_EXITGENR Structure

206 Version 3.7

SEOS_EXITLOGIN StructureThe first parameter passed to exit functions linked to attemptedLogin Events is a pointer to the SEOS_EXITLOGIN structure. Thisstructure contains information about the attempted login. TheSEOS_EXITLOGIN structure can be found in the authxapi.h file.

SEOS_EXITLOGIN contains the following fields:

uid_t luidUser ID of the user trying to log in.

char const *szUnameName of the user trying to log in.

char const *szTermName of the terminal from which the user is trying to log in.Set to NULL on TACF daemon startup.

dev_t deviceDevice number of the program trying to log in.

ino_t inodeI-node number of the program trying to log in.

char const *szProgName of the program trying to log in. Set to NULL whennot applicable.

SEOS_EXITPASS StructureThe first parameter passed to exit functions linked to attemptedPassword Validation Request Events is a pointer to theSEOS_EXITPASS structure. This structure contains information onthe password being validated. The SEOS_EXITPASS structure canbe found in the authxapi.h file.

SEOS_EXITPASS contains the following fields:

char const *szInameName of the user invoking the program. This can be the useror an administrator such as root.

SEOS_EXITLOGIN Structure


9.S

tructu

resan

dD

ataTyp

es

char const *szUnameName of the user whose password is being validated.

char const *szPassNew user password in clear text.

char const *szOldPassOld user password. Defined only when users without theADMIN attribute are changing their own password. Set toNULL when undefined, such as when root is modifyinganother user’s password.

int se_resultResult of TACF password verification mechanism. Notdefined in password pre-verification function. Inpost-verification function, this field holds the result of theTACF password quality checking. When used with the postset exit function, se_result holds a mask containing one ofthe following integer values:

Error code Value Meaning

VERIFYPASS_OK (SUCCESS) 0 Password is OK.

VERIFYPASS_LEN 1 Password too short.

VERIFYPASS_NAME 2 Password containsusername.

VERITYPASS_MINS 3 Too few lowercasecharacters.

VERIFYPASS_MINC 4 Too few uppercasecharacters.

VERIFYPASS_MINN 5 Too few numeric characters.

VERIFYPASS_MINO 6 Too few special characters.

VERIFYPASS_REP 7 Too many repetitions of thesame character.

VERIFYPASS_SAME 8 New password is the sameas the old password.

VERIFYPASS_ASOLD 9 New password is the sameas one of the values storedin the password history list.

SEOS_EXITPASS Structure

208 Version 3.7

Error code Value Meaning

VERIFYPASS_ALFA 10 Too few alphabeticcharacters.

VERIFYPASS_ALFAN 11 Too few alphanumericcharacters.

VERIFYPASS_TIME 12 Not enough time has passedsince the last time thepassword was changed.

VERIFYPASS_PREVCONTAIN

13 The old password iscontained in the new one orvice versa.

VERIFYPASS_BADARG 100 Bad arguments.

The following is a list of error codes currently defined within theExits API:

int sys_resultResult of TACF password setting mechanism. Not defined inpassword pre-setting function. In post-setting function, thisfield holds the result of the TACF attempt to change thepassword. This parameter is not currently used, but will besupported in future versions of the API. The parameter takesthe following values:

Code Value Result

SEOS_LOCAL 0x1 Replaced password locally in the TACFdatabase.

UNIX_LOCAL 0x2 Replaced password locally in the UNIXenvironment.

SEOS_REMOTE 0x4 Replaced password remotely in theTACF database.

UNIX_REMOTE 0x8 Replaced password remotely in theUNIX environment.

See preceding list of error codes.

SEOS_EXITPASS Structure


9.S

tructu

resan

dD

ataTyp

es

SEOS_EXITRES StructureEach Exits API function is passed a pointer to the SEOS_EXITRESstructure as its second parameter. Pre-exit functions receive an emptystructure that the functions fill with their results before returningcontrol to the TACF daemon. Post-exit functions receive a structurefilled with the results of TACF’s authorization. The functions thenrefill the structure with their own results before returning control tothe TACF daemon. The SEOS_EXITRES structure can be found inthe authxapi.h file.

SEOS_EXITRES contains the following fields:

int resultFinal result of the exit function. Valid values are:

Value Meaning

SEOS_EXITR_PASS The function instructs TACF to permit therequest.

SEOS_EXITR_DENY The function instructs TACF to deny therequest.

SEOS_EXITR_CHECK The function requests TACF to make thedecision.

int stageThe stage in the authorization algorithm when the decisionwas made to grant or deny the request. The TACF APIincludes a listing of the TACF stage codes in the header fileseauthstages.h.

You may define your own stages. They must be greater thanSEOS_EXITR_MINSTAGE. Stage is undefined when anauthorization request is granted.

int gstageStage at which the authorization process was granted. Youmay define your own stages. They must be greater thanSEOS_EXITR_MINSTAGE. Gstage is undefined whenauthorization is not granted.

SEOS_EXITRES Structure

210 Version 3.7

int ShouldLogFlag indicating whether or not TACF should record thisevent in the log file:

Value Meaning

FALSE (0) Logging is not required.

TRUE (1) Logging is required.

int logreasonThe reason for logging when logging is required. You maydefine your own reasons. They must be greater thanSEOS_EXITR_EXLOGMIN.

char fnameName of source file reporting an error to the TACF errorlog. (__FILE__ macro in ANSI-C.) This value is not used ifthe function returns SUCCESS (0).

int lnumLine number in source file at which error being logged inTACF log file occurred. (__LINE__ macro in ANSI-C.) Thisvalue is not used if the function returns SUCCESS (0).

SEOS_GCONN StructureThe SEOS_GCONN structure contains the list of groups the user isconnected to and the special attributes, if any, the user has in eachgroup. The SEOS_GCONN structure contains the following fields:

SEOS_OID oidGroupThe group which the user is connected to.

SEOS_OID oidAuthorThe owner of the connection.

SEOS_TIME tConnThe date and time the connection was established.

SEOS_UGMODE ugmUserModeThe attributes of the user in the group.

SEOS_EXITRES Structure


9.S

tructu

resan

dD

ataTyp

es

SEOS_OID Data TypeAn unsigned long integer representing the object ID of a record inthe TACF database.

Each object in the TACF database has a unique object ID. If youknow the object ID, it is possible to use seadmapi to retrieveinformation about an object.

SEOS_PACL StructureThe SEOS_PACL structure contains a list of PACLs. TheSEOS_PACL structure contains the following fields:


SEOS_OID oidProgThe object ID of the trusted program.

SEOS_ACCS accessUser’s level of access to the program. For a list of availableaccess types, see “SEOS_ACCS Data Type” on page 196.

SEOS_PID Data TypeAn unsigned short integer representing a property ID.

Each property in the TACF database has a unique property ID. Ifyou know the property ID, it is possible to use seadmapi to retrieveinformation about it.

SEOS_REQ_ERRORDESCP StructureThe SEOS_REQ_ERRORDESCP structure contains information sentto the audit log. The SEOS_REQ_ERRORDESCP structure containsthe following fields:

int moduleThe number of the module that sent the error record.

SEOS_OID Data Type

212 Version 3.7

int codeThe error code.

char nameThe name of the module that sent the error record.

char sourceThe source file of the error.

int stageThe stage in which the error was noticed.

int severityThe severity of the error.

SEOS_ROUTENTRY StructureThe SEOS_ROUTENTRY structure contains the filtering and targetinformation from each rule in the configuration file. This informationis parsed by selogrd. Note that in this structure, all elements in lowercase are read-only, while elements in mixed case are read-write. TheSEOS_ROUTENTRY structure contains the following fields:

char szClassThe class name.

char objThe object or resource name.

char accrThe accessor user name.

char codeThe access result code:

P (Pass)Success

D (Deny)Failure

U (Untrust)Untrusted action was attempted on a trusted programchecked by the TACF Watchdog. Additional valuesare documented in the file selogtype.h.

SEOS_REQ_ERRORDESCP Structure


9.S

tructu

resan

dD

ataTyp

es

int destThe destination type code. The codes are dynamicallyallocated as the destination types are registered.

char outThe target routing path.

void *SendDataA place holder for information to be stored by the routingfunctions, such as open file handles like FILE *.

int in_errorBoolean flag set if this route entry has previously failed totransmit information. Selogrd calls the destination sendfunction repeatedly to resend the audit records which failedto be transmitted.

SEOS_X_ACL StructureThe SEOS_X_ACL structure is an expanded version of theSEOS_ACL structure. The SEOS_X_ACL structure contains thefollowing fields:



char *pAccessorCNameThe class which the accessor belongs to.

char *pAccessorONameThe accessor’s name.

See Also“SEOS_ACL Structure” on page 197

SEOS_ROUTENTRY Structure

214 Version 3.7

SEOS_X_GCONN StructureThe SEOS_X_GCONN structure is an expanded version of theSEOS_GCONN structure (see page “SEOS_GCONN Structure” onpage 211). The SEOS_X_GCONN structure contains the followingfields:

SEOS_OID oidGroupThe group to which the user is connected.

SEOS_OID oidAuthorThe author of the connection.

SEOS_TIME tConnThe date and time of the connection was established.

SEOS_UGMODE ugmUserModeThe attributes of the user in the group.

char *pGNameThe group’s name.

char *pAuNameThe author’s name.

SEOS_X_OID Data TypeThe SEOS_X_OID data type is an expanded version of theSEOS_OID data type. The SEOS_X_OID data type (see page“SEOS_OID Data Type” on page 212) contains the following fields:

SEOS_OIDAn unsigned long integer representing the object ID of therecord.

char *pCNameThe object’s class.

char *pONameThe object’s name.

SEOS_X_GCONN Structure


9.S

tructu

resan

dD

ataTyp

es

SEOS_X_PACL StructureThe SEOS_X_PACL structure is an expanded version of theSEOS_PACL structure. The SEOS_X_PACL structure (see page“SEOS_PACL Structure” on page 212) contains the following fields:


SEOS_OID oidProgThe object ID of the trusted program.


char *pAccessorCNameThe class name.

char *pAccessorONameThe object name.

char *pProgNameThe name of the program through which access is allowed.

SEOSDB_CDF StructureThe SEOSDB_CDF structure contains the definition of a specificclass in the TACF database. The SEOSDB_CDF structure containsthe following fields:

SEOS_CID sCIdThe ID of the class.

char *szCNameThe name of the class.

unsigned long lCFlagsThe flags of the class.

unsigned char cCRLevelNot in use.

unsigned char cCWLevelNot in use.

SEOS_X_PACL Structure

216 Version 3.7

char reservedReserved for future use.

SEOSDB_ENTDAT StructureThe SEOSDB_ENTDAT structure contains the information returnedby the queries seadmapi_GetEntity and seadmapi_GetExEntity.The SEOSDB_ENTDAT structure contains the following fields:

char *szPNameThe property name.

SEOS_CID sCIdThe class ID of the object’s class.

SEOS_PID sPIdThe property’s ID.

unsigned long int lPFlagsThe property’s flags.

unsigned short int sPVSizeThe property’s size.

unsigned char int cPTypeNot in use.

unsigned char cPRLevelNot in use.

unsigned char cPWLevelNot in use.

unsigned int nPVQtyThe number of values in the list pPVList.

void **pPVListThe value list.

unsigned int nErrCodeThe error code if the query was not able to return therequested data.

SEOSDB_CDF Structure


9.S

tructu

resan

dD

ataTyp

es

SEOSDB_ODF StructureThe SEOSDB_ODF structure contains the definition of a specificobject in the TACF database. The SEOSDB_ODF structure containsthe following fields:

SEOS_CID sCIdThe class ID of the object’s class.

SEOS_OID lOIdThe ID of the object.

char *szONameThe name of the object.


SEOSDB_PDF StructureThe SEOSDB_PDF structure contains the definition of a specificproperty in the TACF database. The SEOSDB_PDF structurecontains the following fields:

SEOS_CID sCIdThe class ID of the class that the object containing thisproperty belongs to.

SEOS_PID sPIdThe ID of the property.

char *szPNameThe name of the property.

unsigned long lPFlagsThe flags of the property.

unsigned short sPVsizeThe size in bytes of the property value.

unsigned char cPTypeThe type of the property value.

unsigned char cPRLevelNot in use.

SEOSDB_ODF Structure

218 Version 3.7

unsigned char cPWLevelNot in use.

unsigned char cSegmentNot in use.


SEOSDB_PDF Structure


9.S

tructu

resan

dD

ataTyp

es

SEOSDB_PDF Structure

220 Version 3.7

V — Appendixes


222 Version 3.7

Index

Special Characters_fini function 37, 70_init function 37, 70_RegisterDestination function 37, 70_SEOS_RC macro 38/usr/seos 10/usr/seos/apisamples 5/usr/seos/apisamples/api_auth/Makefile 6, 8/usr/seos/apisamples/api_auth/musexamp.c 8/usr/seos/apisamples/api_auth/upexamp.c 6/usr/seos/etc/selogrcd.ext 70/usr/seos/etc/selogrd.ext 70/usr/seos/etc/seosd.ext 36/usr/seos/etc/sepass.ext 36/usr/seos/include 10, 199, 200/usr/seos/include/api_auth.h 6, 8/usr/seos/lib 10/usr/seos/lib/seadmapi.a 6, 8

Aaccess

authority 5authorization 8control list entries 106

ACEE handle 34, 107ACL entries 106adding

a new resource class 4the destination target syslog 72

administration functionsclass operations 112console operations 112log file interface 113miscellaneous operations (admin API) 113object operations 114overview 1, 99, 101, 111

administration functions (continued)property operations 115query operations 115seadmapi_ClassGetEqual 117seadmapi_ClassGetFirst 117seadmapi_ClassGetNext 117seadmapi_consAllLoginDisable 174seadmapi_consAllLoginEnable 174seadmapi_consAllLoginGetStatus 174seadmapi_consMessageSend 177seadmapi_consRunTimeStatisticsGet 175seadmapi_consShutDown 178seadmapi_consTraceClear 170seadmapi_consTraceDisable 170seadmapi_consTraceEnable 170seadmapi_consTraceGetStatus 170seadmapi_consTraceToggle 170seadmapi_consUidLoginDisable 172seadmapi_consUidLoginEnable 172seadmapi_consUidLoginGetStatus 172seadmapi_FetchFreeListPropVal 145seadmapi_FetchListPropVal 136seadmapi_FetchSinglePropVal 141seadmapi_FreeAceeMemory 120seadmapi_FreeObjList 135seadmapi_GetACEE 120seadmapi_GetEntity 149seadmapi_GetExEntity 149seadmapi_GetGraceInfo 154seadmapi_GetMessage 122seadmapi_GetNextInClass 125seadmapi_GetObjType 160seadmapi_Init 123seadmapi_InitEntityRuler 149seadmapi_IsSeOSSyscallLoaded 124seadmapi_KillEntityMem 149seadmapi_KillExEntityMem 149seadmapi_KillPDFList 147seadmapi_ObjGetEqual 129


Ind

ex

administration functions (continued)seadmapi_ObjGetFirstInClass 129seadmapi_ObjGetGreaterEqual 129seadmapi_ObjGetNextInClass 129seadmapi_ObjInClassList 133seadmapi_OidToName 156seadmapi_ProcessControl 169seadmapi_PropGetEqual 125seadmapi_PropGetFirstInClass 125seadmapi_ReplacePassword 179seadmapi_ReplacePasswords 180, 181seadmapi_SendAdminAudit 166seadmapi_SendAuditRecord 162seadmapi_SendErrorLog 168seadmapi_SendGenrAudit 166seadmapi_SendInetAudit 166seadmapi_SendLoginAudit 166seadmapi_SendShutdownAudit 164seadmapi_SendStartupAudit 164seadmapi_SendUserAudit 164seadmapi_SendWatchdogAudit 166seadmapi_SetSinglePropVal 146seadmapi_WhoAmI 157value operations 116

APIadministration 1, 99authorizations 3, 13exits 27, 45logroute 65, 67, 79

api_auth.h file 6, 8, 10API_AUTH_RES structure 187api_authx library, compiling and linking 35application

linking with TACF 35servers 6

applicationscompiling 10, 35, 69stand-alone 4

audit_log_q parameter,seadmapi_consRunTimeStatisticsGet 175

audit log records, notification 77authentication, user 8authority, access 5authorization, access 8authorization functions

authxapi_FreeListValues 61

authorization functions (continued)authxapi_GetObjectListValue 56authxapi_GetObjectProperty 52authxapi_GetUserInfo 62authxapi_IsThereExitFunction 51authxapi_RegisterExitFunction 47authxapi_UnRegisterExitFunction 50linking with the AuthAPI library 10SEOSROUTE_ParseApiError 10, 14SEOSROUTE_RequestAuth 5, 8, 15SEOSROUTE_VerifyCreate 6, 9, 19SEOSROUTE_VerifyDelete 7, 22

authorizations API 3, 13authorize command 106authxapi_FreeListValues function 61authxapi_GetObjectListValue function 56authxapi_GetObjectProperty function 52authxapi_GetUserInfo function 62authxapi.h file 35, 42, 206authxapi_IsThereExitFunction function 51AUTHXAPI macro 38authxapi_RegisterExitFunction function 47authxapi_UnRegisterExitFunction function 50

BbLog parameter, SEOSROUTE_VerifyDelete 22buff parameter, seadmapi_GetMessage 122

Ccalls, system 37chain parameter

servlog_RegisterExit 96servlog_UnRegisterExit 97

checkingaccess authority 5if exit function exits (example) 51

ChkFlags parameter,SEOSROUTE_VerifyCreate 20

224 Version 3.7

cid parameterseadmapi_ClassGetEqual 118seadmapi_ClassGetFirst 118seadmapi_ClassGetNext 118

cidLast parameter,seadmapi_consRunTimeStatisticsGet 175

class description file 103class functions

seadmapi_ClassGetEqual 117seadmapi_ClassGetFirst 117seadmapi_ClassGetNext 117

class operations 112classes

adding resource 4GROUP 101SECFILE 192SURROGATE 35TERMINAL 3, 101USER 101

classRecCount parameter,seadmapi_consRunTimeStatisticsGet 175

CLIENT_ACEE structure 188code parameter

lograpi_RegisterTargetType 87lograpi_UnregisterTargetType 89

codes, error 38commands

authorize 106setenv 109setoptions 9, 172su 35su root 6

compiling and linkingwith authAPI library 10with logroute library 69with seadmapi library 109with the api_authx library 35

compiling applications 10, 35, 69configuration files 36connections

of resources to resource groups 106of users to groups 105

console functions (admin API)seadmapi_consAllLoginDisable 174seadmapi_consAllLoginEnable 174seadmapi_consAllLoginGetStatus 174

console functions (admin API) (continued)seadmapi_consMessageSend 177seadmapi_consRunTimeStatisticsGet 175seadmapi_consShutDown 178seadmapi_consTraceClear 170seadmapi_consTraceDisable 170seadmapi_consTraceEnable 170seadmapi_consTraceGetStatus 170seadmapi_consTraceToggle 170seadmapi_consUidLoginDisable 172seadmapi_consUidLoginEnable 172seadmapi_consUidLoginGetStatus 172

console operations (admin API) 112conventions

API 108text xii

count parameterauthxapi_FreeListValues 61authxapi_GetObjectListValue 58seadmapi_FetchListPropVal 138seadmapi_FreeListPropVal 145seadmapi_ObjInClassList 133

creating, new exit function 28CurrentStatus parameter

seadmapi_consAllLoginDisable 174seadmapi_consAllLoginEnable 174seadmapi_consAllLoginGetStatus 174seadmapi_consTraceClear 170seadmapi_consTraceDisable 170seadmapi_consTraceEnable 170seadmapi_consTraceGetStatus 170seadmapi_consTraceToggle 170

CurrrentStatus parameterseadmapi_consUidLoginDisable 173seadmapi_consUidLoginEnable 173seadmapi_consUidLoginGetStatus 173

customer support xiiicustomizing selogrd 67

Ddaemon exits 39daemons

seagent 178


Ind

ex

daemons (continued)selogrcd 68, 70, 79, 96, 178selogrd 65, 67, 68, 70, 71, 178seosd 10, 27, 28, 32, 35, 36, 37, 65, 178seoswd 178, 203serevu 178, 201TACF exits 39

data parameterlograpi_MakeStringMessage 91LogrApiSendFunc 93seadmapi_SendAuditRecord 162

data typesPFSEOSEXITFUNC 192SEOS_ACCS 196SEOS_CID 204SEOS_OID 212SEOS_PID 212SEOS_X_OID 215

databasehow TACF is organized 101interface functions (exits API) 45, 46layout 103lists 105

description fileclass 103objects 104properties 104

design, TACF 35documents, prerequisite xidriver_Register function 68, 71, 81driver_RegisterDestination function 68, 83driver_UnRegister function 68, 71, 82driver_UnregisterDestination function 68, 84

Eentries, ACL 106environment variables

notation for xiiiEOS_AUDITDOWN structure 198err_code parameter, seadmapi_GetMessage 122error codes 38error_log_q parameter,

seadmapi_consRunTimeStatisticsGet 175

error messages, managing 10event, password change 34event parameter

authxapi_IsThereExitFunction 51authxapi_RegisterExitFunction 47authxapi_UnRegisterExitFunction 50

events 28, 30, 32, 33, 34examples

administration API 118, 122, 126, 131, 136,138, 143, 151, 158

authorizations API 5, 7authxapi_FreeListValues 61authxapi_GetObjectListValue 59authxapi_GetObjectProperty 54authxapi_GetUserInfo 63authxapi_IsThereExitFunction 51authxapi_RegisterExitFunction 48authxapi_UnRegisterExitFunction 50exits API 39logroute API 72seadmapi_ClassGetFirst 118seadmapi_ClassGetNext 118seadmapi_FetchListPropVal 136, 138seadmapi_FetchSinglePropVal 143seadmapi_GetExEntity 151seadmapi_GetGraceInfo 154seadmapi_GetMessage 138seadmapi_GetObjType 160seadmapi_InitEntityRuler 151seadmapi_IsSeOSSyscallLoaded 138seadmapi_ObjGetFirstInClass 131seadmapi_ObjGetNextInClass 131seadmapi_PropGetFirstInClass 126seadmapi_PropGetNextInClass 126seadmapi_WhoAmI 158

exits functionsauthxapi_FreeListValues 61authxapi_GetObjectListValue 56authxapi_GetObjectProperty 52authxapi_GetUserInfo 62authxapi_IsThereExitFunction 51authxapi_RegisterExitFunction 47authxapi_UnRegisterExitFunction 50creating 28database interface 46examples 39

226 Version 3.7

exits functions (continued)general 45overview 27, 45password utilities 43shared library 46user information 34

Ffetching a value from the database

(example) 54files

configuration 36header 108

flags parameter, seadmapi_ProcessControl 169format of log file 71FULL_NAME property 102func parameter, servlog_RegisterExit 96funcs parameter, lograpi_RegisterTargetType 87functions

authorization API 13authorizations API 3exits API 45, 46logroute API 79

Ggeneral functions (exits API) 45general resource check events 28, 30, 32, 33getting a value from the database (example) 54GROUP class 101GROUPS property 102

HhACEE parameter,

SEOSROUTE_RequestAuth 16handle parameter

seadmapi_FreeAceeMemory 120

handle parameter (continued)seadmapi_GetACEE 120seadmapi_WhoAmI 158

handles, ACEE 34header files 108how the TACF database is organized 101

Iimplementation function

exits API 28inet_deny parameter,

seadmapi_consRunTimeStatisticsGet 175inet_error parameter,

seadmapi_consRunTimeStatisticsGet 175inet_grant parameter,


Llayout, database 103libraries

linking with AuthAPI 10linking with logroute library 69linking with seadmapi library 109linking with the api_authx library 35

libseadmapi function 109limitations, API 107limits, system 35linking and compiling

with authAPI library 10with the api_authx library 35with the seadmapi 109

linking application with TACF 35linking your application

with AuthAPI library 10with logroute library 69

list parameter, seadmapi_FreeListPropVal 145lists, database 105log file, format 71


Ind

ex

log files interface (admin API)overview 113seadmapi_SendAdminAudit 166seadmapi_SendAuditRecord 162seadmapi_SendErrorLog 168seadmapi_SendGenrAudit 166seadmapi_SendInetAudit 166seadmapi_SendLoginAudit 166seadmapi_SendShutdownAudit 164seadmapi_SendStartupAudit 164seadmapi_SendUserAudit 164seadmapi_SendWatchdogAudit 166

log records, notification audit 77login events 28, 30, 32, 33LogOpt parameter

SEOSROUTE_RequestAuth 16SEOSROUTE_VerifyCreate 20

LOGRAPI_FUNCS structure 189lograpi.h file 69lograpi_InterpretRecord function 68, 85lograpi_MakeStringMessage function 68, 91lograpi_RegisterTargetType function 68, 87lograpi_UnregisterTargetType function 68, 89LogrApiFreeFunc function 69, 94LogrApiSendFunc function 69, 93LogrApiSenseFunc function 69, 92LOGRECHDR structure 190LOGRECORD structure 192logroute functions

driver_Register 68, 71, 81driver_RegisterDestination 68, 83driver_UnRegister 68, 71, 82driver_UnregisterDestination 68, 84lograpi_InterpretRecord 68, 85lograpi_MakeStringMessage 68, 91lograpi_RegisterTargetType 68, 87lograpi_UnregisterTargetType 68, 89LogrApiFreeFunc 69, 94LogrApiSendFunc 69, 93LogrApiSenseFunc 69, 92overview 65, 67, 79servlog_IsThereExit 68, 95servlog_RegisterExit 68, 96servlog_UnRegisterExit 69, 97

logroute library, compiling and linking 69

Mmacros

_SEOS_RC 38AUTHXAPI_MODULE 38SEADMAPI_NEXT_ACEE 120SEOS_UMODE_is_attribute 114

Makefile 6, 8managing, error messages 10miscellaneous functions (admin API)

seadmapi_FreeAceeMemory 120seadmapi_GetACEE 120seadmapi_GetGraceInfo 154seadmapi_GetMessage 122seadmapi_GetObjType 160seadmapi_IsSeOSSyscallLoaded 124seadmapi_ProcessControl 169seadmapi_ReplacePassword 179, 180, 181seadmapi_WhoAmI 157

miscellaneous operations (admin API) 113MUSAS process 4musexamp.c file 8

NnAceeHandles parameter,

seadmapi_consRunTimeStatisticsGet 176name parameter

lograpi_RegisterTargetType 87lograpi_UnregisterTargetType 89

names parameter, seadmapi_ObjInClassList 133nClients parameter,

seadmapi_consRunTimeStatisticsGet 176nCount parameter

seadmapi_KillPDFList 147seadmapi_MakePDFList 147

notification audit log records 77notify parameter, LogrApiSendFunc 93nTrusted parameter,

seadmapi_consRunTimeStatisticsGet 176nUntrusted parameter,


228 Version 3.7

Oobject functions (admin API)

seadmapi_FreeObjList 135seadmapi_ObjGetEqual 129seadmapi_ObjGetFirstInClass 129seadmapi_ObjGetGreaterEqual 129seadmapi_ObjGetNextInClass 129seadmapi_ObjInClassList 133

object operations (admin API) 114objects description file 104ObjPVs parameter

seadmapi_GetEntity 151seadmapi_GetExEntity 151seadmapi_InitEntityRuler 151seadmapi_KillEntityMem 151seadmapi_KillExEntityMem 151

objRecCount parameter,seadmapi_consRunTimeStatisticsGet 175

objtype parameterseadmapi_GetObjType 160seadmapi_WhoAmI 158seadmapi_WhoIs 180

oid parameter, seadmapi_OidToName 156oidLast parameter,

seadmapi_consRunTimeStatisticsGet 175operations (admin API)

class 112console 112log file interface 113miscellaneous 113object 114property 115query 115value 116

organization, TACF database 101ORGANIZATION property 102overview

administration API 1, 99, 101, 111authorizations API 3, 13exits API 27, 45logroute API 65, 67, 79structures and data types 185

Pp_odf parameter

authxapi_GetObjectListValue 57authxapi_GetObjectProperty 53

p_pdf parameterauthxapi_GetObjectListValue 58authxapi_GetObjectProperty 53

p_seclass parameter 118seadmapi_FetchListPropVal 137seadmapi_FetchSinglePropVal 142seadmapi_ObjGetEqual 130seadmapi_ObjGetFirstInClass 130seadmapi_ObjGetGreaterEqual 130seadmapi_ObjGetNextInClass 130seadmapi_PropGetEqual 126seadmapi_PropGetFirstInClass 126seadmapi_PropGetNextInClass 126

p_seobj parameterseadmapi_FetchListPropVal 137seadmapi_FetchSinglePropVal 142seadmapi_ObjGetEqual 130seadmapi_ObjGetFirstInClass 130seadmapi_ObjGetGreaterEqual 130seadmapi_ObjGetNextInClass 130

p_seprop parameterseadmapi_FetchListPropVal 138seadmapi_FetchSinglePropVal 142seadmapi_PropGetEqual 126seadmapi_PropGetFirstInClass 126seadmapi_PropGetNextInClass 126

p_sgr parameter, seadmapi_GetGraceInfo 154pAccess parameter,

SEOSROUTE_RequestAuth 16password

utility, sepass 47password change events 28, 30, 32, 34PASSWORD property 9password quality check event 34password quality check events 28, 30, 32password utilities exits 43password utility, sepass 28, 32, 33, 35, 36pcdf parameter, seadmapi_ObjInClassList 133PFSEOSEXITFUNC data type 192phACEE parameter

SEOSROUTE_VerifyCreate 21


Ind

ex

phACEE parameter (continued)SEOSROUTE_VerifyDelete 22

pid parameterseadmapi_PropGetEqual 126seadmapi_PropGetFirstInClass 126seadmapi_PropGetNextInClass 126

pidLast parameter,seadmapi_consRunTimeStatisticsGet 175

plr parameterlograpi_InterpretRecord 85lograpi_MakeStringMessage 91LogrApiSendFunc 93

podf parameterseadmapi_GetEntity 151seadmapi_GetExEntity 151seadmapi_InitEntityRuler 151seadmapi_KillEntityMem 151seadmapi_KillExEntityMem 151

ppAcee parameterseadmapi_FreeAceeMemory 121seadmapi_GetACEE 121

ppPdf parameterseadmapi_KillPDFList 147seadmapi_MakePDFList 147

pre parameterLogrApiFreeFunc 94LogrApiSendFunc 93LogrApiSenseFunc 92

predefined logroute API 68prerequisite documents xipRes parameter

SEOSROUTE_RequestAuth 17SEOSROUTE_VerifyCreate 21

processesMUSAS 4SERVER 4stand-alone applications 4

programming notes 109properties

description file 104FULL_NAME 102GROUPS 102ORGANIZATION 102

properties description file 104property, PASSWORD 9

property functions (admin API)seadmapi_PropGetEqual 125seadmapi_PropGetFirstInClass 125seadmapi_PropGetNextInClass 125

property operations (admin API) 115propRecCount parameter,

seadmapi_consRunTimeStatisticsGet 175psize parameter

authxapi_GetObjectListValue 58seadmapi_FetchListPropVal 138

ptr parameterseadmapi_FreeObjList 135seadmapi_ObjInClassList 133

pvRecCount parameter,seadmapi_consRunTimeStatisticsGet 176

Qquery functions (admin API)

seadmapi_GetEntity 149seadmapi_GetExEntity 149seadmapi_InitEntityRuler 149seadmapi_KillEntityMem 149seadmapi_KillExEntityMem 149seadmapi_KillPDFList 147seadmapi_OidToName 156

query operations (admin API) 115

RRACF functions

RACINIT 19RACROUTE 19

RACINIT function 19RACROUTE function 19rec parameter

seadmapi_SendAdminAudit 167seadmapi_SendAuditRecord 165seadmapi_SendErrorLog 168seadmapi_SendGenrAudit 167seadmapi_SendInetAudit 167

230 Version 3.7

rec parameter (continued)seadmapi_SendLoginAudit 167seadmapi_SendWatchdogAudit 167

rectype parameterservlog_IsThereExit 95servlog_RegisterExit 96servlog_UnRegisterExit 97

registering a user’s exit function 48registration function

exits API 28resource class, adding 4result parameter

seadmapi_SendAdminAudit 167seadmapi_SendAuditRecord 162, 165seadmapi_SendGenrAudit 167seadmapi_SendInetAudit 167seadmapi_SendLoginAudit 167seadmapi_SendWatchdogAudit 167

return code values 38rtsStat parameter,


Sscope limitations of the API 107seadmapi, compiling and linking 109seadmapi.a file 6, 8, 109seadmapi_ClassGetEqual function 117seadmapi_ClassGetFirst function 117seadmapi_ClassGetNext function 117seadmapi_consAllLoginDisable function 174seadmapi_consAllLoginEnable function 174seadmapi_consAllLoginGetStatus function 174seadmapi_consMessageSend function 177seadmapi_consRunTimeStatisticsGet

function 175seadmapi_consShutDown function 178seadmapi_consTraceClear function 170seadmapi_consTraceDisable function 170seadmapi_consTraceEnable function 170seadmapi_consTraceGetStatus function 170seadmapi_consTraceToggle function 170seadmapi_consUidLoginDisable function 172seadmapi_consUidLoginEnable function 172

seadmapi_consUidLoginGetStatus function 172seadmapi_FetchFreeListPropVal function 145seadmapi_FetchListPropVal function 136seadmapi_FetchSinglePropVal function 141seadmapi_FreeAceeMemory function 120seadmapi_FreeObjList function 135seadmapi_gconn structure 138seadmapi_GetACEE function 120seadmapi_GetEntity function 149seadmapi_GetExEntity function 149seadmapi_GetGraceInfo function 154seadmapi_GetMessage function 122seadmapi_GetObjType function 160seadmapi.h file 108, 157seadmapi_Init function 99, 109, 123seadmapi_InitEntityRuler function 149seadmapi_IsSeoSSyscallLoaded function 99seadmapi_IsSeOSSyscallLoaded function 109,

124seadmapi_KillEntityMem function 149seadmapi_KillExEntityMem function 149seadmapi_KillPDFList function 147SEADMAPI_NEXT_ACEE macro 120seadmapi_ObInClassList function 133seadmapi_ObjGetEqual function 129seadmapi_ObjGetFirstInClass function 129seadmapi_ObjGetGreaterEqual function 129seadmapi_ObjGetNextInClass function 129seadmapi_OidToName function 156seadmapi_ProcessControl function 169seadmapi_PropGetEqual function 125seadmapi_PropGetFirstInClass function 125seadmapi_PropGetNextInClass function 125seadmapi_ReplacePassword function 179, 180,

181SEADMAPI_RTSTAT structure 193seadmapi_SendAdminAudit function 166seadmapi_SendAuditRecord function 162seadmapi_SendErrorLog function 168seadmapi_SendGenrAudit function 166seadmapi_SendInetAudit function 166seadmapi_SendLoginAudit function 166seadmapi_SendShutdownAudit function 164seadmapi_SendStartupAudit function 164seadmapi_SendUserAudit function 164seadmapi_SendWatchdog function 166


Ind

ex

seadmapi_SetSinglePropVal function 146seadmapi_WhoAmI function 157seagent utility (daemon) 178SeAM utility 107seauditx utility 85seauthstages.h file 198, 199, 200, 202, 203SECFILE class 192seclassadm utility 4secons utility 170, 172, 174SEGRACE_RES structure 195selang utility 107selangx utility 107selogrcd utility (daemon) 68, 70, 79, 96, 178selogrd utility (daemon) 65, 67, 68, 70, 71, 178selogtype.h file 69, 96, 108, 162senone utility 169SEOS_ACCESS structure 195SEOS_ACCS data type 196SEOS_ACL structure 197SEOS_AUDITADMIN structure 78, 197SEOS_AUDITGENR structure 78, 199SEOS_AUDITINWARN structure 78SEOS_AUDITLOGIN structure 78, 201SEOS_AUDITSTART structure 202SEOS_AUDITUSER structure 203SEOS_AUDITWDWARN structure 78, 203seos_cdf.dat file 103SEOS_CID data type 204SEOS_EXITGENR structure 30, 33, 205SEOS_EXITINET structure 30, 33, 206SEOS_EXITLOGIN structure 207SEOS_EXITPASS structure 30, 207SEOS_EXITRES structure 30, 210SEOS_GCONN structure 211seos_handle parameter,

authxapi_GetUserInfo 62seos_odf.dat file 103SEOS_OID data type 212SEOS_PACL structure 212seos_pdf.dat file 103SEOS_PID data type 212seos_pvf.dat file 103SEOS_REQ_ERRORDESCP structure 212SEOS_ROUTENTRY structure 213SEOS_UMODE_is_attribute macro 114SEOS_X_ACL structure 214

SEOS_X_GCONN structure 215SEOS_X_OID data type 215SEOS_X_PACL structure 216SEOSAPI_AUTH_CURRACEE handle 7seosd, events linked to 32seosd utility (daemon) 10, 27, 28, 32, 35, 36,

37, 65, 178SEOSDB_CDF structure 216SEOSDB_ENTDAT structure 217SEOSDB_ODF structure 218SEOSDB_PDF structure 104, 218SEOSROUTE_ParseApiError function 10, 14SEOSROUTE_RequestAuth function 5, 8, 15SEOSROUTE_VerifyCreate function 6, 9, 19SEOSROUTE_VerifyDelete function 7, 22seostype.h file 35, 150seostypes.h file 108seoswd utility (daemon) 178, 203sepass utility 28, 32, 33, 35, 36, 47serevu utility (daemon) 178, 201SERVER process 4servers, application 6servlog_IsThereExit function 68, 95servlog_RegisterExit function 68, 96servlog_UnRegisterExit function 69, 97sesu utility 107setenv command 109setoptions command 9, 172sewhoami utility 107shared library functions (exits API) 45, 46size parameter

authxapi_GetObjectProperty 53authxapi_GetUserInfo 62seadmapi_FetchSinglePropVal 142seadmapi_GetMessage 122seadmapi_SetSinglePropVal 146

stand-alone applications 4start parameter, seadmapi_ObjInClassList 133structures

API_AUTH_RES 187CLIENT_ACEE 188LOGRAPI_FUNCS 189LOGRECHDR 190LOGRECORD 192SEADMAPI_RTSTAT 193SEGRACE_RES 195

232 Version 3.7

structures (continued)SEOS_ACCESS 195SEOS_ACL 197SEOS_AUDITADMIN 197SEOS_AUDITDOWN 198SEOS_AUDITGENR 199SEOS_AUDITLOGIN 201SEOS_AUDITSTART 202SEOS_AUDITUSER 203SEOS_AUDITWDWARN 203SEOS_EXITGENR 205SEOS_EXITINIT 206SEOS_EXITLOGIN 207SEOS_EXITPASS 207SEOS_EXITRES 210SEOS_GCONN 211SEOS_PACL 212SEOS_REQ_ERRORDESCP 212SEOS_ROUTENTRY 213SEOS_X_ACL 214SEOS_X_GCONN 215SEOS_X_PACL 216SEOSDB_CDF 216SEOSDB_ENTDAT 217SEOSDB_ODF 218SEOSDB_PDF 104, 218

structures and data types, overview 185su command 6, 35support, customer xiiiSURROGATE class 35syslog file 81, 93system calls 37system design and limits 35szClass parameter

authxapi_GetObjectListValue 57authxapi_GetObjectProperty 53seadmapi_ClassGetEqual 118seadmapi_ClassGetFirst 118seadmapi_ClassGetNext 118seadmapi_FetchListPropVal 137seadmapi_FetchSinglePropVal 142seadmapi_GetEntity 151seadmapi_GetExEntity 151seadmapi_InitEntityRuler 151seadmapi_KillEntityMem 151seadmapi_KillExEntityMem 151

szClass parameter (continued)seadmapi_KillPDFList 147seadmapi_MakePDFList 147seadmapi_ObjGetEqual 130seadmapi_ObjGetFirstInClass 130seadmapi_ObjGetGreaterEqual 130seadmapi_ObjGetNextInClass 130seadmapi_PropGetEqual 126seadmapi_PropGetFirstInClass 126seadmapi_PropGetNextInClass 126seadmapi_SetSinglePropVal 146SEOSROUTE_RequestAuth 15

szEntity parameter,SEOSROUTE_RequestAuth 16

szErrMsg parameter,SEOSROUTE_ParseApiError 14

szMessage parameter,seadmapi_consMessageSend 177

szMsg parameterSEOSROUTE_VerifyDelete 22

szNewPwd parameter,SEOSROUTE_VerifyCreate 20

szObj parameterauthxapi_GetObjectListValue 57authxapi_GetObjectProperty 53seadmapi_FetchListPropVal 137seadmapi_FetchSinglePropVal 142seadmapi_ObjGetEqual 130seadmapi_ObjGetFirstInClass 130seadmapi_ObjGetGreaterEqual 130seadmapi_SetSinglePropVal 146

szOName parameterseadmapi_GetEntity 151seadmapi_GetExEntity 151seadmapi_InitEntityRuler 151seadmapi_KillEntityMem 151seadmapi_KillExEntityMem 151

szProp parameterauthxapi_GetObjectListValue 57authxapi_GetObjectProperty 53seadmapi_FetchListPropVal 137seadmapi_FetchSinglePropVal 142seadmapi_PropGetEqual 126seadmapi_PropGetFirstInClass 126seadmapi_PropGetNextInClass 126seadmapi_SetSinglePropVal 146


Ind

ex

szPwd parameter,SEOSROUTE_VerifyCreate 19

szTerm parameter,SEOSROUTE_VerifyCreate 20

szUName parameterseadmapi_WhoAmI 158seadmapi_WhoIs 180

szUserId parameter,SEOSROUTE_VerifyCreate 19

szzObj parameterseadmapi_ObjGetNextInClass 130

TTACF

daemon exits 39database lists 105events 32watchdog (SEOS_AUDITWDWARN) 203

TCP/IP request events 28, 30, 32, 33TERMINAL class 3, 101termination function 28text conventions xiitype parameter,

seadmapi_SendAuditRecord 162

Uuid parameter

seadmapi_consUidLoginDisable 173seadmapi_consUidLoginEnable 173seadmapi_consUidLoginGetStatus 173seadmapi_WhoAmI 157

uname parameter, authxapi_GetUserInfo 62unc_buff parameter, lograpi_InterpretRecord 85understanding ACEE 107unregistering user’s exit function 50upexamp.c file 6user authentication 8USER class 101

user_func parameter,authxapi_RegisterExitFunction 48

user information, exits API 34user process, access authority for 5utilities

seagent 178SeAM 107seauditx 85seclassadm 4secons 170, 172, 174selang 107selangx 107selogrcd 68, 70, 79, 96, 178selogrd 65, 67, 68, 70, 71, 178senone 169seosd 10, 27, 28, 32, 35, 36, 37, 65, 178seoswd 178, 203sepass 28, 32, 33, 35, 36, 47serevu 178, 201sesu 107sewhoami 107

Vval parameter

authxapi_GetObjectListValue 58authxapi_GetObjectProperty 53seadmapi_FetchListPropVal 138seadmapi_FetchSinglePropVal 142seadmapi_SetSinglePropVal 146

value functions (admin API)seadmapi_FetchFreeListPropVal 145seadmapi_FetchListPropVal 136seadmapi_FetchSinglePropVal 141seadmapi_SetSinglePropVal 146

value operations (admin API) 116value parameter, authxapi_FreeListValues 61variables

environment variablesnotation for xiii

234 Version 3.7

Wwatchdog, TACF 203


Ind

ex

236 Version 3.7

Printed in the United States of Americaon recycled paper containing 10%recovered post-consumer fiber.

GC32-0078-00