publib.boulder.ibm.com · Usernameandpassword..............................21 Access Manager configuration file location ........................21 Password for the SSL keyfile

IBM Tivoli Access Manager

Authorization C API Developer’s ReferenceVersion 3.9

GC32-0849-00

IBM Tivoli Access Manager

Authorization C API Developer’s ReferenceVersion 3.9

GC32-0849-00

NoteBefore using this information and the product it supports, read the information in Appendix D, “Notices” on page 185.

Fourth Edition (April 2002)

This edition replaces GC32-0690-01.

© Copyright International Business Machines Corporation 2002. All rights reserved.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixWho should read this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixWhat this book contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixPublications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

IBM Tivoli Access Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xRelated publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiAccessing publications online . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivOrdering publications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivProviding feedback about publications . . . . . . . . . . . . . . . . . . . . . . . . . xv

Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvContacting customer support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvConventions used in this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Typeface conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Chapter 1. Introducing the Access Manager authorization API . . . . . . . . . . . . 1Introducing the authorization API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

The Open Group Authorization API standard . . . . . . . . . . . . . . . . . . . . . . . 1The Access Manager authorization model. . . . . . . . . . . . . . . . . . . . . . . . . 3

Locating the Access Manager authorization API components . . . . . . . . . . . . . . . . . . . 4Building applications with the authorization API . . . . . . . . . . . . . . . . . . . . . . . 4

Demonstration programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Deploying applications with the authorization API . . . . . . . . . . . . . . . . . . . . . . 5Summarizing authorization API tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Chapter 2. Authorization API functions and data types. . . . . . . . . . . . . . . . 7API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Attribute lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Authorization decisions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Initialization, shutdown, and error handling . . . . . . . . . . . . . . . . . . . . . . . . 8API extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Character strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Protected object structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Default user registry information structure . . . . . . . . . . . . . . . . . . . . . . . . . 11Unauthenticated user information structure. . . . . . . . . . . . . . . . . . . . . . . . . 11Attribute lists. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Credential handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Status codes and error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Chapter 3. Initializing the authorization API . . . . . . . . . . . . . . . . . . . . 15Specifying an authorization API configuration file . . . . . . . . . . . . . . . . . . . . . . 16Specifying cache mode settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Specifying cache mode type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Authorization database file location . . . . . . . . . . . . . . . . . . . . . . . . . . 17Local cache refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Local cache notification listener. . . . . . . . . . . . . . . . . . . . . . . . . . . . 18SSL listener ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Configuring SSL from the API client to Access Manager . . . . . . . . . . . . . . . . . . . . 18Specifying an SSL keyfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Specifying a stash file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Specifying a keyfile label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19SSL session timeout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20SSL password expiration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Authentication method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

© Copyright IBM Corp. 2002 iii

User name and password. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Access Manager configuration file location . . . . . . . . . . . . . . . . . . . . . . . . 21Password for the SSL keyfile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Maximum number of worker threads. . . . . . . . . . . . . . . . . . . . . . . . . . 22Automatic refresh of SSL certificate and keyfile password . . . . . . . . . . . . . . . . . . . 22Connection timeout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Specifying communications attributes for the policy server . . . . . . . . . . . . . . . . . . . 22Policy server hostname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Policy server port number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Policy server distinguished name . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Specifying values for an authorization server replica. . . . . . . . . . . . . . . . . . . . . . 24Configuring the authorization API for LDAP access . . . . . . . . . . . . . . . . . . . . . . 24

LDAP user registry support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25LDAP server host name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25LDAP server port number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Configuring LDAP access over SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . 26SSL communication with the LDAP server . . . . . . . . . . . . . . . . . . . . . . . . 26SSL keyfile name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26SSL keyfile distinguished name . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26SSL keyfile password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Configuring advanced LDAP parameters . . . . . . . . . . . . . . . . . . . . . . . . . 27Maximum search buffer size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Caching LDAP data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27LDAP server query preference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Authentication method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Specifying LDAP user registry replica access . . . . . . . . . . . . . . . . . . . . . . . . 28Enabling the return of permission information. . . . . . . . . . . . . . . . . . . . . . . . 29Configuring auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Audit file location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Configuring audit logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Configuring logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Log size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Log flush interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Specifying the host interface on which to listen . . . . . . . . . . . . . . . . . . . . . . . 31Starting the authorization service . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Chapter 4. Using the authorization API . . . . . . . . . . . . . . . . . . . . . . 33Authenticating an API application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Verifying the identity of a user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Obtaining user authorization credentials . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Specifying the authorization authority . . . . . . . . . . . . . . . . . . . . . . . . . 35Specifying user authentication identity . . . . . . . . . . . . . . . . . . . . . . . . . 35Specifying additional user information . . . . . . . . . . . . . . . . . . . . . . . . . 35Placing user information into an API buffer . . . . . . . . . . . . . . . . . . . . . . . 36Obtaining authorization credentials for the user . . . . . . . . . . . . . . . . . . . . . . 36

Obtaining an authorization decision . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Mapping the user operation to an Access Manager permission . . . . . . . . . . . . . . . . . 37Mapping the requested resource to a protected object . . . . . . . . . . . . . . . . . . . . 38Assigning the user credentials to a credentials handle . . . . . . . . . . . . . . . . . . . . 38Building an attribute list for additional application information . . . . . . . . . . . . . . . . . 38Obtaining an authorization decision . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Cleaning up and shutting down . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Releasing allocated memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Shutting down the authorization API . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Working with credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Converting credentials to a transportable format . . . . . . . . . . . . . . . . . . . . . . 40Converting credentials to the native format . . . . . . . . . . . . . . . . . . . . . . . . 41Creating a chain of credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Determining the number of credentials in a credentials chain . . . . . . . . . . . . . . . . . . 41Obtaining a credential from a chain of credentials . . . . . . . . . . . . . . . . . . . . . 41Modifying the contents of a credential . . . . . . . . . . . . . . . . . . . . . . . . . 42

iv IBM Tivoli Access Manager: Authorization C API Developer’s Reference

Obtaining an attribute list from a credential . . . . . . . . . . . . . . . . . . . . . . . 42Setting and getting attribute values for a credential . . . . . . . . . . . . . . . . . . . . . 43Comparing two credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Copying a credential . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Chapter 5. Backwards compatibility and application migration. . . . . . . . . . . . 45Binary backwards compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Deprecated API elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Permission info attribute values . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Deprecated API for comparing credentials . . . . . . . . . . . . . . . . . . . . . . . . 46Obtaining the user’s authorization identification . . . . . . . . . . . . . . . . . . . . . . 46Authorization API initialization attributes . . . . . . . . . . . . . . . . . . . . . . . . 46DCE authentication APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47User registry information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Deprecated return codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Chapter 6. Introducing authorization service plug-ins . . . . . . . . . . . . . . . 49Service plug-in architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

The authorization service dispatcher . . . . . . . . . . . . . . . . . . . . . . . . . . 50Authorization service plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Calling applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Supported types of service plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Implementing a service plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Initialization and configuration of service plug-ins . . . . . . . . . . . . . . . . . . . . . 53Implementing service interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Using error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Example service source code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Supplied implementations for service plug-ins. . . . . . . . . . . . . . . . . . . . . . . . 64Access Manager entitlements services. . . . . . . . . . . . . . . . . . . . . . . . . . 65Credentials modification service . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Privilege attribute certificate service . . . . . . . . . . . . . . . . . . . . . . . . . . 66External authorization service . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Chapter 7. Implementing entitlements service plug-ins . . . . . . . . . . . . . . . 69Understanding entitlements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Entitlements of type azn_string_t . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Entitlements of type azn_buffer_t . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Initialization, configuration, and shutdown . . . . . . . . . . . . . . . . . . . . . . . . . 70Obtaining entitlements for a specified user . . . . . . . . . . . . . . . . . . . . . . . . . 71Authorizing a caller to a specific entitlements service plug-In. . . . . . . . . . . . . . . . . . . 72Using authorization API interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Entitlements service error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Chapter 8. Implementing administration service plug-ins . . . . . . . . . . . . . . 75Understanding administration service plug-ins . . . . . . . . . . . . . . . . . . . . . . . 75Configuring administration service plug-ins . . . . . . . . . . . . . . . . . . . . . . . . 77

Creating a configuration file entry for an administration service . . . . . . . . . . . . . . . . . 77Configuring an administration service programmatically . . . . . . . . . . . . . . . . . . . 78

Initializing and shutting down administration service plug-ins . . . . . . . . . . . . . . . . . . 78Using an administration service plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . 79Error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Errors when registering the administration service plug-in. . . . . . . . . . . . . . . . . . . 80Errors when registering administration definitions . . . . . . . . . . . . . . . . . . . . . 81Major errors from administration service functions . . . . . . . . . . . . . . . . . . . . . 81Minor errors from administration service functions . . . . . . . . . . . . . . . . . . . . . 81Error codes specific to an authorization services plug-in . . . . . . . . . . . . . . . . . . . 82

Deploying an administration service plug-in . . . . . . . . . . . . . . . . . . . . . . . . 82

Chapter 9. Implementing external authorization service plug-ins . . . . . . . . . . . 83

Contents v

Introducing the external authorization service . . . . . . . . . . . . . . . . . . . . . . . . 83Understanding the external authorization service . . . . . . . . . . . . . . . . . . . . . . . 84

External authorization service architecture . . . . . . . . . . . . . . . . . . . . . . . . 84Policy triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Weightings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Configuring an external authorization service plug-in . . . . . . . . . . . . . . . . . . . . . 88Using a configuration file entry. . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Configuring an external authorization service programmatically . . . . . . . . . . . . . . . . . 89

Initializing and shutting down external authorization service plug-Ins . . . . . . . . . . . . . . . . 89Obtaining an authorization decision . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Major error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Minor error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Appendix A. Authorization API reference . . . . . . . . . . . . . . . . . . . . . 95azn_attrlist_add_entry() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97azn_attrlist_add_entry_buffer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98azn_attrlist_add_entry_pobj() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99azn_attrlist_add_entry_ulong() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100azn_attrlist_copy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101azn_attrlist_create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102azn_attrlist_delete() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103azn_attrlist_delete_entry() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104azn_attrlist_get_entry_buffer_value() . . . . . . . . . . . . . . . . . . . . . . . . . . 105azn_attrlist_get_entry_pobj_value() . . . . . . . . . . . . . . . . . . . . . . . . . . . 107azn_attrlist_get_entry_string_value(). . . . . . . . . . . . . . . . . . . . . . . . . . . 108azn_attrlist_get_entry_ulong_value() . . . . . . . . . . . . . . . . . . . . . . . . . . . 110azn_attrlist_get_names() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111azn_attrlist_name_get_num() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112azn_creds_combine() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113azn_creds_copy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115azn_creds_create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116azn_creds_delete() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117azn_creds_equal() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118azn_creds_for_subject() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119azn_creds_get_attr_value_string(). . . . . . . . . . . . . . . . . . . . . . . . . . . . 121azn_creds_get_attrlist_for_subject() . . . . . . . . . . . . . . . . . . . . . . . . . . . 122azn_creds_get_pac() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124azn_creds_modify() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126azn_creds_num_of_subjects() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129azn_creds_set_attr_value_string() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131azn_decision_access_allowed(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133azn_decision_access_allowed_ext() . . . . . . . . . . . . . . . . . . . . . . . . . . . 135azn_entitlement_get_entitlements() . . . . . . . . . . . . . . . . . . . . . . . . . . . 138azn_error_get_string() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140azn_error_major() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141azn_error_minor() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142azn_error_minor_get_string() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143azn_id_get_creds(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144azn_initialize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146azn_pac_get_creds() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149azn_release_buffer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151azn_release_pobj() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152azn_release_string() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153azn_release_strings() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154azn_shutdown() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155azn_util_errcode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156azn_util_handle_is_valid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157azn_util_password_authenticate(). . . . . . . . . . . . . . . . . . . . . . . . . . . . 158azn_util_password_change() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

vi IBM Tivoli Access Manager: Authorization C API Developer’s Reference

Appendix B. Authorization service plug-in API reference . . . . . . . . . . . . . . 163azn_admin_get_object() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164azn_admin_get_objectlist() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166azn_admin_get_tasklist() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168azn_admin_perform_task() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171azn_service_initialize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174azn_service_shutdown() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Appendix C. svrsslcfg reference . . . . . . . . . . . . . . . . . . . . . . . . 179svrsslcfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

Appendix D. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Contents vii

viii IBM Tivoli Access Manager: Authorization C API Developer’s Reference

Preface

IBM® Tivoli® Access Manager application development kit (ADK) is a applicationdevelopment kit for IBM Tivoli Access Manager that enables applicationdevelopers to add Access Manager authorization and security services toapplications.

Note: IBM Tivoli Access Manager is the new name of the previously releasedsoftware entitled Tivoli SecureWay® Policy Director. Also, for users familiarwith the Tivoli SecureWay Policy Director software and documentation, theterm management server is now referred to as policy server.

The IBM Tivoli Access Manager Authorization C API Developer Reference describes a Cimplementation of the Access Manager authorization API.

Who should read this bookThe target audience for this administration guide includes:v Security administratorsv Network system administratorsv IT architectsv Application developers

Reader s should be familiar with:v Internet protocols, including HTTP, TCP/IP, file transfer protocol (FTP), and

telnetv Development of applications in a C language environmentv Security management, including authentication and authorization

If you are enabling Secure Sockets Layer (SSL) communication, you also should befamiliar with SSL protocol, key exchange (public and private), digital signatures,cryptographic algorithms, and certificate authorities.

What this book containsThis document contains the following chapters:v Chapter 1, “Introducing the Access Manager authorization API”

Describes the Access Manager implementation of the Open Group standardAuthorization C API.

v Chapter 2, “Authorization API functions and data types”Describes the functions and data types that are provided in the authorizationAPI.

v Chapter 3, “Initializing the authorization API”Describes how to initialize the authorization API, using either configuration fileentries or programmatic structures.

v Chapter 4, “Using the authorization API”Describes how to perform the main authorization API tasks, such as verifyinguser identity, obtaining authorization credentials, and obtaining an accessdecision.

© Copyright IBM Corp. 2002 ix

v Chapter 5, “Backwards compatibility and application migration”Describes backwards compatibility support, and lists deprecated interfaces.

v Chapter 6, “Introducing authorization service plug-ins”Describes the Authorization Service Plug-in model, provides an overview of howto implement service plug-ins, and describes the supplied implementations.

v Chapter 7, “Implementing entitlements service plug-ins”Describes how to implement and configure entitlements service plug-ins.

v Chapter 8, “Implementing administration service plug-ins”Describes how to implement and configure administration service plug-ins.

v Chapter 9, “Implementing external authorization service plug-ins”Describes how to implement and configure external authorization serviceplug-ins.

v Appendix A, “Authorization API reference”Provides a reference page for each authorization API function.

v Appendix B, “Authorization service plug-in API reference”Provides a reference page for each service plug-in function.

v Appendix C, “svrsslcfg reference”Provides a reference page for the utility svrsslcfg.

Note: Previous editions of this book contained information on the Javaimplementation of the authorization API. The Java implementation is nowdescribed in a separate book, IBM Tivoli Access Manager Authorization JavaClasses Developer’s Reference.

PublicationsThis section lists publications in the Access Manager library and any other relateddocuments. It also describes how to access Tivoli publications online, how to orderTivoli publications, and how to make comments on Tivoli publications.

IBM Tivoli Access ManagerThe Access Manager library is organized into the following categories:v Release informationv Base informationv WebSEAL informationv Web security informationv Developer reference informationv Supplemental technical information

For additional sources of information about Access Manager and related topics, seethe following Web sites:

http://www.ibm.com/redbookshttps://www.tivoli.com/secure/support/documents/fieldguides

Release informationv IBM Tivoli Access Manager for e-business Read Me First

GI11-0918 (am39_readme.pdf)Provides information for installing and getting started using Access Manager.

x IBM Tivoli Access Manager: Authorization C API Developer’s Reference

v IBM Tivoli Access Manager for e-business Release Notes

GI11-0919 (am39_relnotes.pdf)Provides late-breaking information, such as software limitations, workarounds,and documentation updates.

Base informationv IBM Tivoli Access Manager Base Installation Guide

GC32-0844 (am39_install.pdf)Explains how to install, configure, and upgrade Access Manager software,including the Web portal manager interface.

v IBM Tivoli Access Manager Base Administrator’s Guide

GC23-4684 (am39_admin.pdf)Describes the concepts and procedures for using Access Manager services.Provides instructions for performing tasks from the Web portal managerinterface and by using the pdadmin command.

v IBM Tivoli Access Manager Base for Linux on zSeries™ Installation Guide

GC23-4796 (am39_zinstall.pdf)Explains how to install and configure Access Manager Base for Linux on thezSeries platform.

WebSEAL informationv IBM Tivoli Access Manager WebSEAL Installation Guide

GC32-0848 (amweb39_install.pdf)Provides installation, configuration, and removal instructions for the WebSEALserver and the WebSEAL application development kit.

v IBM Tivoli Access Manager WebSEAL Administrator’s Guide

GC23-4682 (amweb39_admin.pdf)Provides background material, administrative procedures, and technicalreference information for using WebSEAL to manage the resources of yoursecure Web domain.

v IBM Tivoli Access Manager WebSEAL Developer’s Reference

GC23-4683 (amweb39_devref.pdf)Provides administration and programming information for the Cross-domainAuthentication Service (CDAS), the Cross-domain Mapping Framework (CDMF),and the Password Strength Module.

v IBM Tivoli Access Manager WebSEAL for Linux on zSeries Installation Guide

GC23-4797 (amweb39_zinstall.pdf)Provides installation, configuration, and removal instructions for WebSEALserver and the WebSEAL application development kit for Linux on the zSeriesplatform.

Web security informationv IBM Tivoli Access Manager for WebSphere Application Server User’s Guide

GC32-0850 (amwas39_user.pdf)Provides installation, removal, and administration instructions for AccessManager for IBM WebSphere® Application Server.

v IBM Tivoli Access Manager for WebLogic Server User’s Guide

GC32-0851 (amwls39_user.pdf)

Preface xi

Provides installation, removal, and administration instructions for AccessManager for BEA WebLogic Server.

v IBM Tivoli Access Manager Plug-in for Edge Server User’s Guide

GC23-4685 (amedge39_user.pdf)Describes how to install, configure, and administer the plug-in for IBMWebSphere Edge Server.

v IBM Tivoli Access Manager Plug-in for Web Servers User’s Guide

GC23-4686 (amws39_user.pdf)Provides installation instructions, administration procedures, and technicalreference information for securing your Web domain using the plug-in for Webservers application.

Developer referencesv IBM Tivoli Access Manager Authorization C API Developer’s Reference

GC32-0849 (am39_authC_devref.pdf)Provides reference material that describes how to use the Access Managerauthorization C API and the Access Manager service plug-in interface to addAccess Manager security to applications.

v IBM Tivoli Access Manager Authorization Java Classes Developer’s Reference

GC23-4688 (am39_authJ_devref.pdf)Provides reference information for using the Java™ language implementation ofthe authorization API to enable an application to use Access Manager security.

v IBM Tivoli Access Manager Administration C API Developer’s Reference

GC32-0843 (am39_adminC_devref.pdf)Provides reference information about using the administration API to enable anapplication to perform Access Manager administration tasks. This documentdescribes the C implementation of the administration API.

v IBM Tivoli Access Manager Administration Java Classes Developer’s Reference

SC32-0842 (am39_adminJ_devref.pdf)Provides reference information for using the Java language implementation ofthe administration API to enable an application to perform Access Manageradministration tasks.

v IBM Tivoli Access Manager WebSEAL Developer’s Reference

GC23-4683 (amweb39_devref.pdf)Provides administration and programming information for the Cross-domainAuthentication Service (CDAS), the Cross-domain Mapping Framework (CDMF),and the Password Strength Module.

Technical supplementsv IBM Tivoli Access Manager Performance Tuning Guide

GC43-0846 (am39_perftune.pdf)Provides performance tuning information for an environment consisting ofAccess Manager with IBM SecureWay Directory defined as the user registry.

v IBM Tivoli Access Manager Capacity Planning Guide

GC32-0847 (am39_capplan.pdf)Assists planners in determining the number of WebSEAL, LDAP, and backendWeb servers needed to achieve a required workload.

v IBM Tivoli Access Manager Error Message Reference

SC32-0845 (am39_error_ref.pdf)

xii IBM Tivoli Access Manager: Authorization C API Developer’s Reference

Provides explanations and recommended actions for the messages produced byAccess Manager.

The Tivoli Glossary includes definitions for many of the technical terms related toTivoli software. The Tivoli Glossary is available, in English only, at the followingWeb site:

http://www.tivoli.com/support/documents/glossary/termsm03.htm

Related publicationsThis section lists publications related to the Access Manager library.

IBM DB2 Universal DatabaseIBM DB2® Universal Database™ is required when installing IBM SecureWayDirectory, z/OS™, and OS/390® SecureWay LDAP servers. DB2 information isavailable at the following Web site:

http://www.ibm.com/software/data/db2/

IBM SecureWay DirectoryIBM SecureWay Directory, Version 3.2.2, is shipped on the IBM Tivoli AccessManager Base CD for your particular platform. If you plan to install the IBMSecureWay Directory server as your user registry, the following documents areavailable in the /doc/Directory path on the IBM Tivoli Access Manager Base CDfor your particular platform:v IBM SecureWay Directory Installation and Configuration Guide

SC32-0845 (aparent.pdf, lparent.pdf, sparent.pdf, wparent.pdf)Provides installation, configuration, and migration information for IBMSecureWay Directory components on AIX®, Linux, Solaris, and Microsoft®

Windows® operating systems.v IBM SecureWay Directory Release Notes

(relnote.pdf)Supplements IBM SecureWay Directory, Version 3.2.2, product documentationand describes features and functions made available to you in this release.

v IBM SecureWay Directory Readme Addendum

(addendum322.pdf)Provides information about changes and fixes that occurred after the IBMSecureWay Directory documentation had been translated. This file is in Englishonly.

v IBM SecureWay Directory Server Readme

(server.pdf)Provides a description of the IBM SecureWay Directory Server, Version 3.2.2.

v IBM SecureWay Directory Client Readme

(client.pdf)Provides a description of the IBM SecureWay Directory Client SDK, Version3.2.2. This software development kit (SDK) provides LDAP applicationdevelopment support.

v SSL Introduction and iKeyman User’s Guide

(gskikm5c.pdf)Provides information for network or system security administrators who plan toenable SSL communication in their Access Manager secure domain.

Preface xiii

v IBM SecureWay Directory Configuration Schema

(scparent.pdf)Describes the directory information tree (DIT) and the attributes that are used toconfigure the slapd32.conf file. In IBM SecureWay Directory Version 3.2, thedirectory settings are stored using the LDAP Directory Interchange Format(LDIF) format in the slapd32.conf file.

v IBM SecureWay Directory Tuning Guide

(tuning.pdf)Provides performance tuning information for IBM SecureWay Directory. Tuningconsiderations for directory sizes ranging from a few thousand entries tomillions of entries are given where applicable.

For more information about IBM SecureWay Directory, see the following Web site:

http://www.software.ibm.com/network/directory/library/

IBM WebSphere Application ServerIBM WebSphere Application Server Standard Edition, Version 4.0.2, is installedwith the Web portal manager interface. For information about IBM WebSphereApplication Server, see the following Web site:

http://www.ibm.com/software/webservers/appserv/infocenter.html

Accessing publications onlinePublications in the product libraries are included in Portable Document Format(PDF) on the product CD. To access these publications using a Web browser, openthe infocenter.html file, which is located in the /doc directory on the product CD.

When IBM publishes an updated version of one or more online or hardcopypublications, they are posted to the Tivoli Information Center. The TivoliInformation Center contains the most recent version of the publications in theproduct library in PDF or HTML format, or both. Translated documents are alsoavailable for some products.

You can access the Tivoli Information Center and other sources of technicalinformation from the following Web site:

http://www.tivoli.com/support/documents/

Information is organized by product, including release notes, installation guides,user’s guides, administrator’s guides, and developer’s references.

Note: If you print PDF documents on other than letter-sized paper, select the Fit topage check box in the Adobe Acrobat Print dialog (which is available whenyou click File → Print) to ensure that the full dimensions of a letter-sizedpage are printed on the paper that you are using.

Ordering publicationsYou can order many Tivoli publications online at the following Web site:

http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi

You can also order by telephone by calling one of these numbers:

xiv IBM Tivoli Access Manager: Authorization C API Developer’s Reference

v In the United States: 800-879-2755v In Canada: 800-426-4968v In other countries, for a list of telephone numbers, see the following Web site:

http://www.tivoli.com/inside/store/lit_order.html

Providing feedback about publicationsWe are very interested in hearing about your experience with Tivoli products anddocumentation, and we welcome your suggestions for improvements. If you havecomments or suggestions about our products and documentation, contact us in oneof the following ways:v Send an e-mail to [email protected] Complete our customer feedback survey at the following Web site:

http://www.tivoli.com/support/survey/

AccessibilityAccessibility features help a user who has a physical disability, such as restrictedmobility or limited vision, to use software products successfully. With this product,you can use assistive technologies to hear and navigate the interface. You can alsouse the keyboard instead of the mouse to operate all features of the graphical userinterface.

Contacting customer supportIf you have a problem with any Tivoli product, you can contact Tivoli CustomerSupport. See the Tivoli Customer Support Handbook at the following Web site:

http://www.tivoli.com/support/handbook/

The handbook provides information about how to contact Tivoli CustomerSupport, depending on the severity of your problem, and the followinginformation:v Registration and eligibilityv Telephone numbers and e-mail addresses, depending on the country in which

you are locatedv What information to gather before contacting support

Conventions used in this bookThis guide uses several conventions for special terms and actions, operatingsystem-dependent commands and paths, and margin graphics.

Typeface conventionsThe following typeface conventions are used in this book:

Bold Command names and options, keywords, and other informationthat you must use literally appear in bold.

Italic Variables, command options, and values you must provide appearin italics. Titles of publications and special words or phrases thatare emphasized also appear in italics.

Monospace Code examples, command lines, screen output, file and directorynames, and system messages appear in monospace font.

Preface xv

xvi IBM Tivoli Access Manager: Authorization C API Developer’s Reference

Chapter 1. Introducing the Access Manager authorization API

This chapter contains the following topics:v “Introducing the authorization API”v “Locating the Access Manager authorization API components” on page 3v “Building applications with the authorization API” on page 4v “Deploying applications with the authorization API” on page 5v “Summarizing authorization API tasks” on page 6

Introducing the authorization APIUsing the IBM® Tivoli® Access Manager authorization application programminginterface (API), you can program Access Manager applications and third-partyapplications to query the Access Manager authorization service for authorizationdecisions.

The Access Manager authorization API is the interface between the server-basedresource manager and the authorization service and provides a standard model forcoding authorization requests and decisions. The authorization API lets you makestandardized calls to the centrally managed authorization service from any legacyor newly developed application.

The authorization API supports two implementation modes:v Remote cache mode

In remote cache mode, you use the authorization API to call the Access Managerauthorization server, which performs authorization decisions on behalf of theapplication. The authorization server maintains its own cache of the replicaauthorization policy database.

v Local cache modeIn local cache mode, you use the authorization API to download a local replicaof the authorization policy database. In this mode, the application can performall authorization decisions locally.

The authorization API shields you from the complexities of the authorizationservice mechanism. Issues of management, storage, caching, replication, credentialsformat, and authentication methods are all hidden behind the authorization API.

The authorization API works independently from the underlying securityinfrastructure, the credential format, and the evaluating mechanism. Theauthorization API makes it possible to request an authorization check and get asimple “yes” or “no” recommendation in return.

The authorization API is a component of the Access Manager applicationdevelopment kit (ADK).

The Open Group Authorization API standardThe Access Manager authorization API implements the Open Group AuthorizationAPI (Generic Application Interface for Authorization Frameworks) standard. Thisinterface is based on the International Organization for Standardization (ISO)10181-3 model for authorization. In this model, an initiator requests access to a

© Copyright IBM Corp. 2002 1

target resource. The initiator submits the request to a resource manager, whichincorporates an access enforcement function (AEF). The AEF submits the request,along with information about the initiator, to an access decision function (ADF).The ADF returns a decision to the AEF, and the AEF enforces the decision.

Access Manager implements the ADF component of this model and provides theauthorization API as an interface to this function.

In the figure above, a browser (initiator) requests access to a file or other resourceon a protected system (target). The browser submits the request to a Webapplication server (the resource manager incorporating the access enforcementfunction). The Web application server uses the authorization API to submit therequest to the Access Manager authorization service (the access decision function).

The Access Manager authorization service returns an access decision, through theauthorization API, to the Web application server. The Web application serverprocesses the request as appropriate.

To implement this model, developers of AEF applications add authorization APIfunction calls to their application code.

Note: Developers should refer to the Open Group Authorization API document foradditional information on the standard authorization model.

Resource

Manager

AEF TargetInitiator

ADF

Submit

Access

Request

Present

Access

Request

Decision

RequestDecision

Figure 1. The ISO 10181-3 Authorization Model

Browser ProtectedData

Access Manager Secure Domain

Initiator

Resource Manager

ADF

Target

Access ManagerAuthorization

Service

Authorization API

Web ApplicationServer

AEF

Figure 2. The Access Manager implementation of the ISO authorization model

2 IBM Tivoli Access Manager: Authorization C API Developer’s Reference

The Access Manager authorization modelThe first step in adding authorization to an application is to define the securitypolicy requirements for your application. Defining a security policy means that youmust determine the business requirements that apply to the application’s users,operations, and data. These requirements include:v Objects to be securedv Operations permitted on each objectv Users that are permitted to perform the operations

After your security requirements have been defined, you can use the authorizationAPI to integrate your security policy with the Access Manager security model.

Complete the following steps in order to deploy an application into an AccessManager secure domain:1. Configure the Access Manager secure domain to recognize and support the

objects, actions, and users that are relevant to your application.v For an introduction to the Access Manager authorization model, see the IBM

Tivoli Access Manager Base Administrator’s Guide.

v For complete information on access control, see the IBM Tivoli Access ManagerBase Administrator’s Guide.

2. Use the authorization API within your application to obtain the neededauthorization decisions.v For an introduction to the authorization API, including information on

remote cache mode and local cache mode, see the IBM Tivoli Access ManagerBase Administrator’s Guide.

3. Develop your application logic to enforce the security policy.

Locating the Access Manager authorization API componentsThe authorization API is included in an optional installation package (ADK) in theAccess Manager distribution. The authorization API files are installed in severalsub-directories under the Access Manager installation directory.

Directory Contents

bin On Microsoft Windows systems, the library to include at run timeis pdauthzn.dll

include C header files

lib A library that implements the API functions. On Solaris systems,the library is libpdauthzn.so On AIX systems, the library islibpdauthzn.a On HP-UX systems, the library islibpdauthzn.slOn Windows, the library to link is pdauthzn.lib

example This directory contains an example program that demonstratesusage of the authorization API. Source files and a MAKEFILE areprovided.

For installation instructions for the ADK, see the IBM Tivoli Access Manager BaseInstallation Guide.v Header Files

The header files are found in the include directory, located directly under theAccess Manager ADK package installation directory.

Chapter 1. Introducing the Access Manager authorization API 3

File Contents

ogauthzn.h The authorization API standard functions

aznutils.h Utility functions (extensions to the authorization API)

azn_svc_protos.h Prototypes for generic authorization service plug-in functions.Contains prototypes for the azn_service_initialize() andazn_service_shutdown() calls. This can optionally be included bya plug-in programmer to prototype the calls defined in theservice.

azn_admin_svc_protos.h Prototypes for plug-in functions for the authorizationadministration service.

azn_deprecated.h Prototypes and declarations for the functions, variables andattributes that are deprecated in Access Manager 3.9.Programmers should avoid including this header file as thesymbols that are contained there will not be supported in futurereleases of the product.

ivadminapi.h Function prototypes for the Access Manager administration API.This API is described in a separate document: IBM Tivoli AccessManager Administration C API Developer’s Reference.

pdb*msg.h Minor error codes.

v Error Codes

The authorization API error codes are defined in the following files, located in theinclude directory:

File Contents

ogauthzn.h Major error codes for the standard authorization API functions.

aznutils.h Major error codes for the authorization API utility functions.

pdb*msg.h Minor error codes for utility functions and the Access Managerauthorization service are found in a number of error messagefiles. For example, pdbaclmsg.h

Building applications with the authorization APITo develop applications that use the Access Manager authorization API, you mustinstall and configure an Access Manager secure domain.

If you do not have an Access Manager secure domain installed, install one beforebeginning application development. The minimum installation consists of a singlesystem with the following Access Manager Base components installed:v Access Manager runtime environmentv Access Manager policy serverv Access Manager application development kit

When the Access Manager secure domain uses an LDAP user registry, theapplication development system must have an LDAP client installed.

If you already have an Access Manager secure domain installed, and want to add adevelopment system to the domain, the minimum Access Manager installationconsists of the following components:


v Access Manager runtime environmentv Access Manager application development kit

Note: For Access Manager installation instructions refer to the IBM Tivoli AccessManager Base Installation Guide.

In order to compile applications that use the authorization API, you must installthe Access Manager ADK on the build machine.

When compiling your application, make sure you add the include directory for theAccess Manager ADK to the compiler command line. When linking yourapplication, specify the directory containing the authorization shared library if it isnot in the default location.

Note: The Access Manager authorization API is compiled as a 32-bit application.

Demonstration programsThe Access Manager authorization API is provided with several exampleprograms. The authzn_demo directory contains examples programs thatdemonstrate use of the authorization API. A C language example is included. TheC example contains a sample Makefile. See the sample Makefile for buildinstructions specific to each supported operating system platform. Refer to theREADME file, located in the same directory, for information regarding the use ofthis example program.

An example of the administration service plug-in is provided in theadmin_svc_demo directory. See the sample Makefile for build instructions.

An example of an external authorization service plug-in is provided in theeas_demo directory. See the sample Makefile for build instructions.

Program Description

authzn_demo Authorization API demonstration program

azn_admin_svc_demo Administration service demonstration program

azn_eas_demo External authorization service demonstration program

Deploying applications with the authorization APITo deploy an application with the authorization API, verify that your environmentcontains the necessary supporting software. You can test your environment bybuilding and running the example program that is provided with the authorizationAPI.

Applications that have been developed with the Access Manager authorization APImust be run on systems that are configured into an Access Manager securedomain. When the Access Manager secure domain uses an LDAP user registry, theapplication deployment system must have an LDAP client installed.

The minimum Access Manager installation required on a system that will run anapplication is the Access Manager runtime environment component.

For deployment examples, see the demonstration programs described in“Demonstration programs”.

Chapter 1. Introducing the Access Manager authorization API 5

Summarizing authorization API tasksThe primary task of the authorization API is to obtain an authorization decisionfrom the Access Manager authorization service.

Use the authorization API to present information about the user, operation, andrequested resource to the Access Manager authorization service, and receive theauthorization decision. Your application is responsible for enforcing the decision, asappropriate.

To obtain an authorization decision, you must accomplish certain tasks to configurethe authorization API client. The following sections in this document provide astep-by-step guide to completing each of these required tasks:v Chapter 3, “Initializing the authorization API” on page 15v “Authenticating an API application” on page 33v “Verifying the identity of a user” on page 34v “Obtaining user authorization credentials” on page 34v “Obtaining an authorization decision” on page 37v “Cleaning up and shutting down” on page 39

The authorization API also provides functions for performing optional tasks onuser credentials. The following section describes the supported optional tasks:v “Working with credentials” on page 40


Chapter 2. Authorization API functions and data types

The authorization API provides a set of functions and data types. This section liststhe name of each authorization API construct and the task it accomplishes.

The following functions, structured data types, and constants are defined as part ofthe authorization API:v “API functions” on page 7v “Character strings” on page 9v “Buffers” on page 9v “Protected object structures” on page 10v “Default user registry information structure” on page 10v “Attribute lists” on page 11v “Credential handles” on page 13v “Status codes and error handling” on page 14

API functionsThe following tables list the authorization API functions and provide both a link tothe reference page for the function and a link to the section in this document thatdescribes each function’s task.

Note: The Access Manager authorization API functions are 32-bit only.

Attribute lists

Function Task

“azn_attrlist_add_entry()” on page 97“azn_attrlist_add_entry_buffer()” on page 98“azn_attrlist_add_entry_pobj()” on page 99“azn_attrlist_add_entry_ulong()” on page 100“azn_attrlist_create()” on page 102“azn_attrlist_copy()” on page 101“azn_attrlist_delete()” on page 103“azn_attrlist_delete_entry()” on page 104“azn_attrlist_get_entry_buffer_value()” on page 105“azn_attrlist_get_entry_ulong_value()” on page 110“azn_attrlist_get_entry_pobj_value()” on page 107“azn_attrlist_get_entry_string_value()” on page 108“azn_attrlist_get_names()” on page 111“azn_attrlist_name_get_num()” on page 112“azn_release_buffer()” on page 151“azn_release_pobj()” on page 152“azn_release_string()” on page 153“azn_release_strings()” on page 154“azn_util_handle_is_valid()” on page 157

“Attribute lists” onpage 7


Credentials

Function Task

“azn_creds_combine()” on page 113 “Creating a chain of credentials” on page41

“azn_creds_copy()” on page 115 “Copying a credential” on page 44

“azn_creds_create()” on page 116 “Obtaining user authorization credentials”on page 34

“azn_creds_delete()” on page 117 “Releasing allocated memory” on page 39

“azn_creds_equal()” on page 118 “Comparing two credentials” on page 44

“azn_creds_for_subject()” on page 119 “Obtaining a credential from a chain ofcredentials” on page 41

“azn_creds_get_attrlist_for_subject()” onpage 122

“Obtaining an attribute list from acredential” on page 42

“azn_creds_set_attr_value_string()” onpage 131

“Setting and getting attribute values for acredential” on page 43

“azn_creds_get_attr_value_string()” onpage 121

“azn_creds_get_pac()” on page 124 “Converting credentials to a transportableformat” on page 40

“azn_creds_modify()” on page 126 “Modifying the contents of a credential” onpage 42

“azn_creds_num_of_subjects()” on page 129 “Determining the number of credentials ina credentials chain” on page 41

“azn_id_get_creds()” on page 144 “Obtaining user authorization credentials”on page 34

“azn_pac_get_creds()” on page 149 “Converting credentials to the nativeformat” on page 41

“azn_util_handle_is_valid()” on page 157 “Credential handles” on page 13

Authorization decisions

Function Task

“azn_decision_access_allowed()” on page 133

“azn_decision_access_allowed_ext()” on page 135

“Obtaining an authorization decision”on page 37

Initialization, shutdown, and error handling

Function Task

“azn_error_major()” on page 141 “Status codes and error handling” on page14“azn_error_minor()” on page 142

“azn_error_minor_get_string()” on page 143

“azn_error_get_string()” on page 140

“azn_initialize()” on page 146 Chapter 3, “Initializing the authorizationAPI” on page 15


Function Task

“azn_release_buffer()” on page 151 “Releasing allocated memory” on page 39

“azn_release_pobj()” on page 152

“azn_release_string()” on page 153

“azn_release_strings()” on page 154

“azn_shutdown()” on page 155 “Shutting down the authorization API” onpage 40

“azn_util_errcode()” on page 156 “Status codes and error handling” on page14

API extensions

Function or Data Type Task

“azn_util_errcode()” on page 156 “Status codes and error handling” on page14

“azn_util_handle_is_valid()” on page 157 “Attribute lists” on page 11 “Credentialhandles” on page 13

“azn_util_password_authenticate()” onpage 158

“Verifying the identity of a user” on page 34

Character stringsMany authorization API functions take character strings as arguments or returncharacter strings as values. Use the azn_string_t data type to pass character stringdata between your application and the authorization API:typedef char *azn_string_t;

Use azn_release_string() and azn_release_strings() to release memory that hasbeen allocated to strings of type azn_string_t.

BuffersSome authorization API functions take byte string arguments and return bytestrings as values. Use the data type azn_buffer_t to pass byte string data betweenyour application and the authorization API.

The azn_buffer_t data type is a pointer to a buffer descriptor consisting of alength field and a value field. The length field contains the total number of bytesin the data. The value field contains a pointer to the data.typedef struct azn_buffer_desc_struct {

size_t length;void *value;

} azn_buffer_desc, *azn_buffer_t;

You must allocate and release the storage necessary for all azn_buffer_desc objects.

Objects of type azn_buffer_t appear as output parameters to theazn_attrlist_get_entry_buffer_value() and azn_creds_get_pac() calls. For thesefunctions, storage for the buffer array referred to by the value member of anazn_buffer_desc object is allocated by the authorization API.

Chapter 2. Authorization API functions and data types 9

Use azn_release_buffer() to release storage allocated for use by azn_buffer_descobjects.

Parameters of type azn_buffer_t can be assigned and compared with the followingconstant values:

Name Value Definition

AZN_C_EMPTY_BUFFER NULL Empty data value-buffer.

AZN_C_NO_BUFFER NULL No value-buffer is supplied orreturned.

Protected object structuresThis data structure is available for applications that want to track informationabout protected objects.typedef struct azn_pobj_desc_struct (

azn_string_t name;unsigned int type;azn_string_t description;azn_boolean_t is_policy_attachable;

) azn_pobj_desc, *azn_pobj_t

The variables in the structure above contain the following information:

Variable Description

name A string containing the protected object path.

type The protected object type, expressed as an unsigned int.This can be defined by the application developer.

description A string description of the protected object.

is_policy_attachable A boolean value that indicates whether authorizationpolicy can be attached to this object.

Default user registry information structureThe authorization API uses this structure to pass information for building AccessManager credentials to the azn_id_get_creds() call.

When this structure is used in conjunction with a NULL mechanism ID in afunction call to azn_id_get_creds(), the client credential is built from informationstored in the default user registry. It will use the registry option that was selectedwhen the Access Manager secure domain was installed. The client does not need toknow the registry type.

This structure replaces the deprecated structures azn_authdce_t, azn_authldap_t,and azn_authuraf_t.typedef struct {

azn_string_t principal;azn_string_t auth_method;unsigned int ipaddr;azn_string_t qop;azn_string_t user_info;azn_string_t browser_info;azn_string_t authmech_info;void *reserved[9];

} azn_authdefault_t;


Field Description

principal The client’s principal name in the registry.

auth_method The authentication method.

ipaddr IP address of the requesting user in network byte order.

qop Quality of protection required for requests made by thisuser.

user_info Additional user information that may be required forauditing.

browser_info The browser employed by the user. This field isoptional.

authnmech_info Additional authentication mechanism information.

reserved Fields reserved for future use

Unauthenticated user information structureThis data structure contains information for use in building an unauthenticatedauthorization credential for a user within the Access Manager secure domain.

This data structure is used to pass information about an unauthenticated user intothe azn_id_get_creds() interface. The content of each element of this structure isdetermined by the application, based on application requirements.typedef struct {

unsigned int ipaddr;azn_string_t qop;azn_string_t user_info;azn_string_t browser_info;

} azn_unauth_t;

Field Description

ipaddr IP address of the requesting user in network byte order.

qop Quality of protection required for requests made by thisuser.

user_info Additional user information that may be required forauditing.

browser_info The browser employed by the user. This field isoptional.

Attribute listsSeveral authorization API functions take attribute list handles as input parametersor return attribute list handles as output parameters. Use the azn_attrlist_h_tdata type to pass attribute list handles between the authorization API and thecalling application.

Variables of type azn_attrlist_h_t are opaque handles to lists of name and valuepairs. Use authorization API functions to add or retrieve name and value pairsfrom attribute lists.


CAUTION:Always initialize attribute list handles to AZN_C_INVALID_HANDLE whendeclaring them on the stack. If an application attempts to access an uninitializedattribute list handle, the access request may result in memory corruption orundefined behavior.

Many authorization API functions use attribute lists to store and retrieve values.Attribute lists are lists of name and value pairs. The values can be stored as eitherstrings or buffers. A name can have more than one value.

The values under each attribute name are stored in the order in which they wereinserted into the list. Each value entry can be retrieved using theazn_attrlist_get_entry_*() functions with an index number starting at 0 for thefirst value in the list. There is no checking performed upon values in the list soduplicate values are permitted.

The authorization API defines some names. You can also define additional namesas needed by your application.

The authorization API provides functions to create attribute lists, set or get listentries, and delete attribute lists. The following table summarizes the functions thatoperate on attribute lists:

Task Description

Create an attribute list Use azn_attrlist_create() to complete the followingtasks:

v Allocate a new, empty attribute list.

v Associate a handle with the attribute list.

v Return the handle.

Set an entry in an attribute list Use azn_attrlist_add_entry() to add a stringname-value pair of type azn_string_t.

Use azn_attrlist_add_entry_buffer() to add a buffername-value pair of type azn_buffer_t.

Use azn_attrlist_add_entry_ulong() to add aname-value pair of type azn_ulong_t.

Use azn_attrlist_add_entry_pobj() to add aname-value pair of type azn_pobj_t.

Delete an entry from anattribute list.

Use azn_attrlist_delete_entry() to delete all the valuesthat are assigned to an attribute in an attribute list.

Get attribute names from anattribute list

Use azn_attrlist_get_names() to get all the names in anattribute list. The names are returned in aNULL-terminated array of strings of type azn_string_t.

Get the number of values for aspecified attribute name

Use azn_attrlist_name_get_num() to get the number, asan integer, of the value attributes for a specified name inthe attribute list.

Copy an attribute list. Use azn_attrlist_copy() to make a copy of an attributelist.


Task Description

Get a value Use azn_attrlist_get_entry_string_value() to get thevalue attribute of a string of type azn_string_t for aspecified name in an attribute list.

Use azn_attrlist_get_entry_buffer_value() to get thevalue attribute of a buffer of type azn_buffer_t for aspecified name in an attribute list.

Use azn_attrlist_get_entry_ulong_value() to get thevalue attribute of type azn_ulong_t.

Use azn_attrlist_get_entry_pobj_value() to get thevalue attribute of type azn_pobj_t.

For each of the functions described above, the specifiedattribute list entry can have multiple values. For amulti-valued attribute, specify an index to get thatinstance of the value. For a single-valued attribute, theindex should be set to 0.

Delete an attribute list Use azn_attrlist_delete() to delete the attribute listassociated with a specified attribute list handle.

Determine if the attribute listhandle is valid

Use azn_util_handle_is_valid() to determine if anattribute list handle is associated with valid data.

Credential handlesA credential handle refers to a credentials chain consisting of the credentials of theinitiator and a series of (zero or more) intermediaries through which the initiator’srequest has passed.

By default, the credentials generated by the azn_id_get_creds() interface andAccess Manager components contain only a single Access Manager credential. Theintermediary credentials are not referenced by Access Manager when making anauthorization decision. Only the primary credential, referred to as the “initiator” isused in authorization decisions. Chains can be used for customer API applicationsbut an External authorization service would need to be developed to authorize theremaining credentials in a chain.

Several authorization API functions take credentials handles as input parameters orreturn pointers to credential handles as output parameters. Use the azn_creds_h_tdata type to pass credential handles between the authorization API and the callingapplication.

Variables of type azn_creds_h_t are opaque handles to credential structures thatare internal to the Access Manager security framework.

CAUTION:Always initialize credential handles to AZN_C_INVALID_HANDLE whendeclaring them on the stack. If an application attempts to access an uninitializedcredential handle, the access request may result in memory corruption orundefined behavior.

Use the function azn_creds_create() to complete the following tasks:v Allocate a new, empty credential structure.v Associate a handle with the credential structure.


v Return a pointer to the handle.

Call the function azn_creds_delete() on the handle to release the memoryallocated for the credential structure.

To determine if a credentials handle is valid, use the authorization API utilityfunction azn_util_handle_is_valid().

For more information on functions that use credentials handles to access credentialinformation, see “Working with credentials” on page 40.

Status codes and error handlingAuthorization API functions return a status code of type azn_status_t. The valuesin azn_status_t are integers. The return value for successful completion of afunction is AZN_S_COMPLETE, which is defined to be 0.

The returned status code includes both major and minor error codes. A major errorcode of AZN_S_FAILURE indicates that a minor error code contains the errorstatus.

Use azn_error_major() to extract major error codes from the returned status.Major error codes are defined according to the The Open Group authorization APIStandard.

Use azn_error_minor() to extract minor error codes from the returned status. Theminor codes contain error messages from the utility function extensions to the API,and contain error messages from the Access Manager authorization server.

Use azn_error_minor_get_string() to obtain string values for the minor errorcodes returned by azn_error_minor().

Use azn_error_get_string() to return the Access Manager serviceability messagestring from a authorization API status structure of type azn_status_t. Thisfunction will automatically select the major or minor code and map the error valueto an error message string.

Use azn_util_errcode() to build an azn_status_t error code from a major andminor status. Use this to return standardized error codes to authorization APIapplications when developing authorization service plug-ins.

See the following files for a complete list of error codes:

File Contents

ogauthzn.h Major error codes for the standard authorization API functions.

aznutils.h Major error codes for the authorization API utility functions.

pdb*msg.h Minor error codes for utility functions and the Access Managerauthorization service are found in a number of files. The filenamesfor these files all share the prefix pdb and the suffix msg.h


Chapter 3. Initializing the authorization API

To use the Access Manager authorization API, an application must initialize theAPI. Initialization consists of specifying initialization data and calling aninitialization function.

There are two ways to specify the initialization data:v Specify input arguments to azn_initialize()

v Specify entries in the authorization API configuration file

The authorization API initialization function azn_initialize() takes as an inputparameter an attribute list named init_data. To specify initialization data, youmust add the necessary attributes to init_data.

Each input argument to azn_initialize() has a corresponding entry in theauthorization API configuration file. Input arguments take precedence overconfiguration file entries.

You can define entries in the configuration file, and then use input parameters toazn_initialize() to override them as needed when each authorization APIapplication initializes.

In order to use a configuration file, specify the configuration file location as aninput parameter to azn_initialize().

Complete the instructions in the following sections:v “Specifying an authorization API configuration file” on page 15v “Specifying cache mode settings” on page 16v “Configuring SSL from the API client to Access Manager” on page 18v “Specifying communications attributes for the policy server” on page 22v “Specifying values for an authorization server replica” on page 24v “Configuring the authorization API for LDAP access” on page 24v “Configuring LDAP access over SSL” on page 26v “Configuring advanced LDAP parameters” on page 27v “Specifying LDAP user registry replica access” on page 28v “Enabling the return of permission information” on page 28v “Starting the authorization service” on page 31

Specifying an authorization API configuration fileYou can specify a configuration file that contains initialization values. Theconfiguration file is a text file consisting of stanzas. Each stanza contains a series ofname = value pairs. Each of the pairs corresponds to an input parameter that canget passed to azn_initialize().

If no configuration file is specified, azn_initialize() obtains initializationparameters only from the attribute list contained in the init_data input parameter.There is no configuration file specified by default.


Specify a configuration file by using the azn_init_cfg_file attribute.

To specify the location of a configuration file:1. Call azn_attrlist_create() to create a new attribute list called init_data. This

function returns a pointer to an attribute list handle.2. Use azn_attrlist_add_entry() to add the attribute azn_init_cfg_file and

assign it a value, as described in the table below.

azn_init_cfg_file

Value Description

<filename> A configuration file containing initialization values for theAccess Manager authorization API. There is no default value.

The sample configuration file distributed with the Authorizationdemonstration program is named aznapi.conf.

Specifying cache mode settingsThe cache mode determines if the authorization API talks to an Access Managerauthorization service running in the same process space (local cache mode) or in adifferent process space (remote cache mode) in the secure domain.

Local cache mode can increase application performance because authorizationchecks can be performed on the same system as the application. Local cache mode,however, requires additional configuration and maintenance of a replicatedauthorization database.v When using remote mode, the caller of the authorization API must be a member

of the remote-acl-users group.v When using local mode, the caller of the authorization API must be a member of

the ivacld-servers group.

Note: For more information on remote cache mode or local cache mode, see theIBM Tivoli Access Manager Base Administration Guide.

The svrsslcfg utility creates a user identity for the caller and automatically adds itto the appropriate group. The svrsslcfg utility determines which groupmembership is required, based on whether you specified local or remote to the -sparameter. For more information, see the reference page for x“svrsslcfg” onpage 180.

Specifying cache mode typeYou can specify the cache mode by using either an attribute list entry or aconfiguration file entry.v Attribute List Entry: azn_init_modev Configuration File Entry: modev Configuration File Stanza: [aznapi-configuration]v Modified by svrsslcfg?: Yes. Must be specified.

Use the option -s [ local | remote ].


The following table displays the valid values for cache modes.

Values Description

local The Access Manager authorization service runs in the same serverprocess as the application using the authorization API.

remote The Access Manager authorization service runs as a different serverprocess from the application using the authorization API.

When you specify local cache mode, you must decide how the local copy of theauthorization database will be updated.

Choose one of the following methods to implement updating:v Set the authorization API to poll the master authorization service database.v Register the local (replicated) database with the master database, and enable a

listener process on the local database’s system. This process listens for updatenotifications.

v Configure the authorization API to both poll and listen.v Configure the authorization API to neither poll nor listen. This could be useful,

for example, when the local system is not connected to a network. You can usethis configuration to only receive updates when the pdadmin server replicatecommand is issued.Note that in order for the pdadmin server replicate command to functioncorrectly, a valid non-zero listening port (azn_ssl_listening_port) must be set.

Authorization database file locationYou can specify the location of the database file used by the authorization serviceby either using attribute list entries or by using configuration file entries.v Attribute List entry: azn_init_db_filev Configuration File Entry: db-filev Configuration File Stanza: [aznapi-configuration]v Modified by svrsslcfg?: No.

Authorization Database File Location

Value Description

filename Path name to the persistent authorization policy database replica.

Local cache refreshYou can specify the interval for the local cache refresh by either using attribute listentries or by using configuration file entries.v Attribute List entry: azn_init_cache_refresh_intervalv Configuration File entry: cache-refresh-intervalv Configuration File Stanza: [aznapi-configuration]v Modified by svrsslcfg?: No.

The following table shows that you can disable or enable the cache refresh. Whenyou enable the cache refresh, you can specify the cache refresh interval in numberof seconds.

Chapter 3. Initializing the authorization API 17

Values Description

disable Refreshing of the local authorization policy database disabled.

default disabled

number of seconds Number of seconds between refreshes of the local authorizationpolicy database. Set appropriate values to ensure that thereplicated database is updated in a timely manner to reflectchanges made to the master database.

Local cache notification listenerYou can configure the notification listener by either using attribute list entries or byusing configuration file entries.v Attribute List entry: azn_init_listen_flagsv Configuration File entry: listen-flagsv Configuration File Stanza: [aznapi-configuration]v Modified by svrsslcfg?: Yes.

Use the option -l [ yes | no ]. If not specified the default is disable.

Value Description

disable Disable the notification listener. This is the default.

enable Enable the notification listener.

SSL listener portsThis port is also used to listen for administration requests from the policy server. Itis mandatory to specify this port when running svrsslcfg.

Note: If you disabled the notification listener, skip this section.

You can specify the notification listener port by using a configuration file entry.v Attribute List entry: azn_init_ssl_listening_portv Configuration File entry: ssl-listening-portv Configuration File stanza: [ssl]

v Modified by svrsslcfg?: Yes.Use the option -r [ <port-number> ]. This must be specified.

Value Description

port number Use this value to specify the TCP port on which the application willlisten for notifications from the master database that is has changed.All communications on this port are SSL encrypted. The value shouldbe non-zero and not used by any other service on the computer.

Configuring SSL from the API client to Access ManagerYou can specify a number of attributes or configuration file entries that describethe SSL communications configuration between the authorization API Client,running in remote mode, and the Access Manager authorization server and AccessManager policy server.


Specifying an SSL keyfilev Attribute List Entry: azn_init_ssl_keyfilev Configuration File Entry: ssl-keyfilev Configuration File Stanza: [ssl]v Modified by svrsslcfg?: Yes. Must be specified.

This uses the svrsslcfg options -d [kdb-directory] and the root from -n[server-name] to create an entry value: <kdb-directory>/<server-name>.kdb.

Value Description

<keyfile-path> This is the keyfile used to communicate with the AccessManager policy server and the Access Manager authorizationserver. It is created by the svrsslcfg utility.

This can be any relative or fully qualified filename.

Specifying a stash filev Attribute List Entry: azn_init_ssl_stashfile

v Configuration File Entry: ssl-keyfile-stashv Configuration File Stanza: [ssl]v Modified by svrsslcfg?: Yes. Must be specified.

This uses the svrsslcfg options -d [kdb-directory] and the root from -n[server-name] to create an entry value: <kdb-directory>/<server-name>.sth.

Value Description

<keyfile-path> This the stash file for the keyfile. It is created by the svrsslcfgutility. It is used as an obfuscated password to the keyfile. Thisfile should be appropriately secured.

This can be any relative or fully qualified filename.

Specifying a keyfile labelv Attribute List Entry: azn_init_ssl_keyfile_labelv Configuration File Entry: ssl-keyfile-labelv Configuration File Stanza: {ssl}v Modified by svrsslcfg?: No.

Value Description

Any string The label of the certificate to use within the keyfile. In normaloperation this is not used. However it is useful if the keyfilesare constructed outside of the svrsslcfg utility and containmultiple certificates.

SSL session timeoutv Attribute List Entry: azn_init_ssl_timeoutv Configuration File Entry: ssl-v3-timeoutv Configuration File Stanza: [ssl]v Modified by svrsslcfg?: Yes.

Use the option -t [ssl-timeout]. If not specified, the default is 7200 seconds.


Value Description

Any non-negative integer.Default value is 7200seconds

This is the amount of time before an SSL session will expire.The Access Manager authorization API client automaticallycreate a new SSL session with new keys when a sessionexpires.

This value only applies to the listening aspect of theauthorization API’s (when the Access Manager policy server iscalling the application). When the application is calling theAccess Manager policy server or the Access Managerauthorization server, the session timeout value is dictated bythe most restrictive of the values for that client and server.

SSL password expirationv Attribute List Entry: azn_init_ssl_pwd_lifev Configuration File Entry: ssl-pwd-lifev Configuration File Stanza: [ssl]v Modified by svrsslcfg?: Yes.

Use the option -e [<password-life>]. If not specified, the default is 183 days.

Value Description

Any non-negative integer.Default value is 183 days.

This is the amount of time before the password or stash file tothe keyfile will expire. The Access Manager authorization APIclient automatically refreshes the password or stash file beforethis expiry time, if automatic refresh is enabled.

Authentication methodv Attribute List Entry: azn_init_ssl_authn_typev Configuration File Entry: ssl-authn-typev Configuration File Stanza: [ssl]v Modified by svrsslcfg?: Yes.

This always has a value of certificate.

Value Description

The type ofauthentication. Possiblevalues are:

v certificate

v password

v none

The default value is none.

The method that the Access Manager policy server will use toauthenticate the authorization API client. If the value iscertificate the Access Manager policy server will map thecertificate provided by the authorization API client into anidentity and authenticate against it. Note that even if passwordor none are specified, the client will still use SSL tocommunicate with the server, and as such will still require akeyring database file that has the Access Manager CertificateAuthority (CA) certificate as a signer certificate or trustedcertificate.

There are currently no operations that can be performed by theAPI successfully with an authentication type of none.

User name and passwordv Attribute List Entry: azn_init_ssl_authn_userv Attribute List Entry: azn_init_ssl_authn_pwd


v Configuration File Entry: authn-userv Configuration FIle Entry: authn-passwordv Configuration File Stanza: [ssl]v Modified by svrsslcfg?: No.

Value Description

Any string. The user name and password that are used if theauthentication type is password. It may be unwise to store thesein the configuration file, however they can be useful for testingcommunications.

Access Manager configuration file locationv Attribute List Entry: azn_init_ssl_mgr_configv Configuration File Entry: ssl-mgr-configv Configuration File Stanza: [ssl]

Value Description

The relative or fullyqualified pathname to thepd.conf file.

This entry is used to point to the configuration file that wascreated as part of configuring the Access Manager runtimeenvironment (pd.conf). If it is specified, the values formaster-host, master-port, and master-dn will come from themanager stanza of pd.conf and override any values specified inthe authorization API client’s configuration file. Furthermore, ifentries or values are not found in pd.conf for any of theseentries, empty values will be used.

The pd.conf usually lives in the Access Manager installationdirectory, under ./lib/pd.conf

Password for the SSL keyfilev Attribute List Entry: azn_init_ssl_keyfile_pwdv Configuration File Entry: ssl-keyfile-pwdv Configuration File Stanza: [ssl]v Modified by svrsslcfg?: No.

Value Description

<password string> Password used to protect keys in the keyfile. When bothssl-keyfile-pwd and ssl-keyfile-stash are specified, thevalue in ssl-keyfile-pwd is used.

Maximum number of worker threadsv Attribute List Entry: azn_init_ssl_max_worker_threadsv Configuration File Entry: ssl-maximum-worker-threadsv Configuration File Stanza: [ssl]v Modified by svrsslcfg?: No.


Value Description

<maximum number ofworker threads>

Maximum number of worker threads that are created by theserver to handle incoming requests. The value is an integer.The minimum number is 1. The maximum number isdetermined by the amount of system resources available.

The default number is 50.

Automatic refresh of SSL certificate and keyfile passwordv Attribute List Entry: azn_init_ssl_auto_refreshv Configuration File Entry: ssl-auto-refreshv Configuration File Stanza: [ssl]v Modified by svrsslcfg?: Yes.

Use the option -a [ yes | no ]. If not specified the default is yes.

Value Description

yes or no Enable or disable automatic refresh of the SSL certificate andkey database file password. When enabled, the certificate andpassword are regenerated when either is close to expiration.

A value of yes enables automatic refresh. A value or nodisabled automatic refresh.

Connection timeoutv Attribute List Entry: azn_init_ssl_io_inactivity_timeoutv Configuration File Entry: ssl-io-inactivity-timeout

v Configuration File Stanza: [ssl]

v Modified by svrsslcfg?: No.

Value Description

<number of seconds> Inactivity timeout for the input/output connection, expressedin seconds. The value is an integer. The minimum value is 0.When the value is 0, no timeout is enforced.

The default value is 0 seconds. The recommended value is 90seconds. Note that this value is set in the supplied aznapi.conffile.

Specifying communications attributes for the policy serverUse the attributes described in this section to specify the location, port number,and distinguished name of the Access Manager policy server. authorization APIClients use this information to communicate with the policy server.

Policy server hostnamev Attribute List Entry: azn_init_master_hostv Configuration File Entry: master-hostv Configuration File Stanza: [manager]

v Modified by svrsslcfg?: Yes.


The value is taken from the pd.conf file. The pd.conf file is created when theAccess Manager runtime component is configured on the machine.

Value Description

<policy server hostname> Specifies the hostname of the Access Manager policy server.

This entry and stanza can be in either the authorization APIclient’s configuration file (aznAPI.conf) or the file pointed to bythe azn_init_ssl_mgr_config attribute (if specified). If theazn_init_ssl_mgr_config attribute is specified, its valueoverrides that in aznAPI.conf.

Policy server port numberv Attribute List Entry: azn_init_master_port

v Configuration File Entry: master-portv Configuration File Stanza: [manager]

v Modified by svrsslcfg?: Yes.The value is taken from the pd.conf file. The pd.conf file is created when theAccess Manager runtime component is configured on the machine.

Value Description

<port number> This entry and stanza can be in either the authorization APIclient’s configuration file (aznAPI.conf) or the file pointed to bythe azn_init_ssl_mgr_config attribute (if specified). If theazn_init_ssl_mgr_config attribute is specified, its valueoverrides that in aznAPI.conf.

Policy server distinguished namev Attribute List Entry: azn_init_master_dnv Configuration File Entry: master-dnv Configuration File Stanza: [manager]v Modified by svrsslcfg?: Yes.


Value Description

<distinguished name> Specifies the Distinguished Name (DN) of the Access Managerpolicy server. The authorization API client can match this valueagainst that provided by the Access Manager policy server atruntime to prevent spoofing. If the value is empty, no checkingwill be performed.

This entry and stanza can be in either the authorization APIclient’s configuration file (aznAPI.conf) or the file pointed to bythe azn_init_ssl_mgr_config attribute (if specified). If theazn_init_ssl_mgr_config attribute is specified, its valueoverrides that in aznAPI.conf.


Specifying values for an authorization server replicaYou can specify a series of values that describe the location and communicationvalues for an authorization server replica. All values are assigned to oneconfiguration file entry.

Each configuration file entry describes one Access Manager authorization server.You can add one or more entries for each authorization server to the configurationfile.

The replicas are of the format:<replica hostname>:<port>:<preference>:<replica cert dn>

For example:“rweber.bball.com:7137:5:cn=ivacld/rweber,o=Access Manager,C=US”

Note that the separator for the fields is a colon (“:”) and not a comma (“,”) like theLDAP replicas use.v Attribute List Entry: azn_init_replicav Configuration File Entry: replicav Configuration File Stanza: [manager]v Modified by svrsslcfg: Can be.

Replicas can be added to the configuration file by using the svrsslcfg-add_replica option.

Value Description

<replica hostname> The fully qualified domain name of the server.

<port> The port on the server.

<preference> A ranking for attempting contact. Valid values are from 1 to 10.The lowest preference is 1, the highest preference is 10.

<replica certificatedistinguished name>

The LDAP distinguished name for the authorization server.

Configuring the authorization API for LDAP accessWhen your application runs in an Access Manager secure domain that uses anLDAP user registry, you must provide the LDAP configuration settings to theauthorization API. The required LDAP configuration settings match the settingsthat were entered when Access Manager was installed on the local system.

LDAP user registry supportv Attribute List Entry: None.v Configuration File Entry: enablev Configuration File Stanza: [ldap]v Modified by svrsslcfg? Yes.



Value Description

yes Enable LDAP user registry support. This is the default value.This entry is not used when building an attribute list. LDAPaccess is automatically enabled when the attributeazn_init_ldap_port is not null.

LDAP server host namev Attribute List Entry: azn_init_ldap_hostv Configuration File Entry: hostv Configuration File Stanza: [ldap]v Modified by svrsslcfg? Yes.


Value Description

host name Host name of LDAP server.

LDAP server port numberv Attribute List Entry: azn_init_ldap_portv Configuration File Entry: portv Configuration File Stanza: [ldap]v Modified by svrsslcfg? Yes.


Value Description

port number Port number for communicating with the LDAP server.

LDAP User Distinguished Name

v Attribute List Entry: azn_init_ldap_bind_dn

v Configuration File Entry: bind-dnv Configuration File Stanza: ldapv Modified by svrsslcfg? Yes.

The value is created based on the server name that was specified with the -nserver_name flag and the local host of the machine.

Value Description

LDAP DN Distinguished Name of the LDAP user. Created by the svrsslcfgutility.

LDAP User Password

v Attribute List Entry: azn_init_ldap_bind_pwd

v Configuration File Entry: bind-pwdv Configuration File Stanza: ldapv Modified by svrsslcfg? Yes.


The value is created based on the password that was specified with the -Spassword flag.

Value Description

password Password for the LDAP user. Created by the svrsslcfg utility.

Configuring LDAP access over SSLIf the communication between the Access Manager Authorization server and theLDAP server is over Secure Sockets Layer (SSL), you must specify thecommunication settings.

Note that the Access Manager authorization API client must use two key files: onefor communicating with the LDAP server and one for communicating with theAccess Manager servers.

SSL communication with the LDAP serverv Attribute List Entry: None.v Configuration File Entry: ssl-enabledv Configuration File Stanza: [ldap]

Value Description

yes Enables SSL communication with the LDAP server. This entryis not used when building attribute lists. Ifazn_init_ldap_ssl_keyfile is not null, then SSL isautomatically configured.

SSL keyfile namev Attribute List Entry: azn_init_ldap_ssl_keyfilev Configuration File Entry: ssl-keyfilev Configuration File Stanza: [ldap]

Value Description

<filename> Name of the SSL key file.

SSL keyfile distinguished namev Attribute List Entry: azn_init_ldap_ssl_keyfile_dnv Configuration File Entry: ssl-keyfile-dnv Configuration File Stanza: [ldap]

Value Description

KeyLabel Key label to identify the client certificate that is presented tothe LDAP server.

SSL keyfile passwordv Attribute List Entry: azn_init_ldap_ssl_keyfile_pwdv Configuration File Entry: ssl-keyfile-pwdv Configuration File Stanza: [ldap]


Value Description

password Password to access the SSL key file. When the keyfile isspecified but the password (ldap_ssl_keyfile_pwd) is notspecified or is set to NULL, the password string is set toNULL. When the keyfile is specified, andldap_ssl_keyfile_pwd is a non-NULL string, the password isset to the non-NULL string value.

Configuring advanced LDAP parameters

Maximum search buffer sizev Attribute List Entry: azn_init_ldap_max_search_sizev Configuration File Entry: max-search-sizev Configuration File Stanza: [ldap]

Value Description

<search-size> Optional. Limit for the maximum search buffer size returnedfrom the LDAP server in entries. Note that this value can alsobe limited by the LDAP server itself.

Caching LDAP datav Attribute List Entry: azn_init_ldap_cachev Configuration File Entry: cache-enabledv Configuration File Stanza: [ldap]

Value Description

true Optional. Enable LDAP client-side caching of user, group andLDAP policy data to improve performance for similar LDAPqueries.

false Optional. Disable LDAP client-side caching. This is the defaultvalue.

LDAP server query preferencev Attribute List Entry: azn_init_prefer_rw_svrv Configuration File Entry: prefer-readwrite-serverv Configuration File Stanza: [ldap]

Value Description

true Optional. The client attempts to query the read/write LDAPserver (see ldap-replica configuration option) before queryingany read-only servers that are configured in the domain.

false Optional. Do not query read/write LDAP server first

Authentication methodv Attribute List Entry: azn_init_ldap_using_comparev Configuration File Entry: auth-using-comparev Configuration File Stanza: [ldap]


Value Description

true Optional. Choose whether ldap_compare() is used insteadof ldap_bind() to authenticate LDAP users. This optionchanges the method used by the Access Manager authorizationAPI call and azn_util_password_authenticate().

false Optional. Use ldap_bind().

Specifying LDAP user registry replica accessUse can adds an attribute or configuration file entry that defines the LDAP userregistry replicas in the domain.v Attribute List Entry: azn_init_ldap_replicav Configuration File Entry: ldap-replicav Configuration File Stanza: [ldap]

Assign multiple values to ldap-replica by entering a list consisting of entries thatare separated by commas. For example:ldap-replica = barney,391,readwrite,2ldap-replica = fred,391,readonly,3

Value Description

<ldap-server> The network name of the LDAP server.

<port> The port on the LDAP server.

<type> Either readonly or readwrite

<pref> A preference or priority level to assign to accessing this replica.The minimum value is 1. The maximum value is 10. A highernumber denotes a higher preference.

Enabling the return of permission informationYou can specify information to be returned by theazn_decision_access_allowed_ext() function call. This call returns a pointer to anattribute list (azn_attrlist_h_t) named permission_info. This attributes listcontains more detailed information on the result or reasoning behind the accessdecision that was made. It may also be used to return additional information thatis applicable to the authorization decision. For example, this could include thequality of protection (QOP) that is required for communication between client andserver entities.

You can specify the information returned in the permission_info attribute list byadding values to the azn_init_set_perminfo_attrs attribute during initialization ofthe authorization API. The azn_init_set_perminfo_attrs attribute is set in theinit_data attribute list.

The init_data attribute list is passed as an input parameter to the authorizationAPI initialization function, azn_initialize(). You can add multiple values toazn_init_set_perminfo_attrs. The defined values are listed in the table below.

To enable the return of permission information you must supply values for one ofthe following:v Attribute List Entry: azn_init_set_perminfo_attrs


v Configuration File Entry: permission-info-returnedv Configuration File Stanza: [aznapi-configuration]

The default configuration file for the authorization server is ivacld.conf. Thisconfiguration file has the permission-info-returned parameter commented out(disabled) by default:##permission-info-returned = azn_perminfo_qop azn_perminfo_qop_ulong#

Uncomment the line in order to enable the return of permission info.

The following table contains the values that you can specify.

Value Description

azn_perminfo_all_attrs Include all of the permission informationattributes

azn_perminfo_wm_ulong Warning mode. when warning mode isenabled, access is always granted. Ifaccess should not have been granted thenthe access is logged.

azn_perminfo_wm_permitted_ulong Access permitted because of warningmode. The boolean indicator is used totell the caller that access was grantedbecause warning mode is enabled.

azn_perminfo_al_ulong Auditing events that are performed forthis authorization check.

<pop-extended-attribute-name> Any attribute of a protected object policy(pop) that is used when making anauthorization decision.

<acl-extended-attribute-name> Any extended attribute of an accesscontrol list (acl) that is used when makingan authorization decision.

azn_acl_ext_attr_loc The value of this attribute is the locationwithin the object space to which an ACLwith extended attributes is attached. Theextended attributes must be defined inthe <acl-extended-attribute-name> valueabove.

azn_pop_ext_attr_loc The value of this attribute is the locationwithin the object space to which a POPwith extended attributes is attached. Theextended attributes must be defined inthe <pop-extended-attribute-name> valueabove.

azn_perminfo_qop_ulong The quality of protection level.

azn_perminfo_stepup_level The level required for step-upauthentication. When this value is notspecified, no step-up authentication isrequired.


Configuring auditing

Audit file locationYou can specify the location of the audit file used by the authorization service byeither using attribute list entries or by using configuration file entries.v Attribute List entry: azn_init_audit_filev Configuration File Entry: auditlog

This entry is located in the [aznapi-configuration] stanza.

Audit File

Value Description

<filename> Path name to the persistent authorization policy database replica.

<filename> Path and file name for the file that collects authorization API auditevents.

Configuring audit loggingv Attribute List Entry: azn_init_auditcfgv Configuration File Entry: auditcfgv Configuration File Stanza: [aznapi-configuration]

Value Description

azn or authn To disable or enable component specific audit records, you canadd or remove either authentication (authn) or authorization(azn).

Configuring logging

Log sizev Attribute List Entry: azn_init_log_sizev Configuration File Entry: logsizev Configuration File Stanza: [aznapi-configuration]

Value Description

<size in bytes> The maximum size in bytes for the auditing and debug files.When the log size reaches this value, the log is backed up anda new log file is started.

A value of 0 disables log rollover. A negative value performsrollover daily, regardless of size. The default value is 2000000.

Log flush intervalv Attribute List Entry: azn_init_log_flush_intervalv Configuration File Entry: logflushv Configuration File Stanza: [aznapi-configuration]


Value Description

<flush interval in seconds> The auditing and logging service flush interval in seconds. Avalue of 0 sets the default flush interval of 20 seconds. Themaximum value is 600 seconds.

Specifying the host interface on which to listenMachines that have more than one network interface card installed and configuredcan have more than one hostname. When more than one network interface card isconfigured, use this authorization API initialization attribute to specify thehostname on which the authorization API application listens.

When this attribute is not specified, the default hostname is used.v Attribute List Entry: azn_app_hostv Configuration File Entry: azn-app-hostv Configuration File Stanza: [aznapi-configuration]

Value Description

<hostname> The hostname on which the application is running. This valuecan be used to specify a hostname on machines that supportmultiple hostnames (by using multiple network interfacecards). When this is not specified, the default hostname is used.

Starting the authorization serviceComplete the following steps:1. Ensure that the attribute list init_data has been created and filled in, as

described in the preceding sections.2. Call azn_initialize() to bind to and initialize the authorization service.

For example:/* Start the service */status = azn_initialize(init_data, &init_info);if (status != AZN_S_COMPLETE)

return(status);

In the example code above, azn_initialize() returns the attribute list init_info.This attribute list is appended with any initialization information attributes thatapply. This includes the AZN_C_VERSION attribute, which contains the versionnumber of the API implementation.

Note: To re-initialize the API, use azn_shutdown() and then call azn_initialize().

When using this function on Windows NT, do not call it from dllMain(). For moreinformation, see the reference page for “azn_initialize()” on page 146.



Chapter 4. Using the authorization API

This chapter contains the following topics:v “Authenticating an API application”v “Verifying the identity of a user” on page 34v “Obtaining user authorization credentials” on page 34v “Obtaining an authorization decision” on page 37v “Cleaning up and shutting down” on page 39v “Working with credentials” on page 40

Authenticating an API applicationThe API application must establish its own authenticated identity within theAccess Manager secure domain, in order to request authorization decisions fromthe Access Manager authorization service.

Before you run the authorization API application for the first time, you must createa unique identity for the application in the Access Manager secure domain.

In order for the authenticated identity to perform API checks, the application mustbe a member of at least one of the following groups:v ivacld-servers

This group membership is needed for applications using local cache mode.v remote-acl-users

This group membership is needed for applications using remote cache mode.

When the application wants to contact one of the secure domain services, it mustfirst log in to the secure domain.

Use the svrsslcfg utility to accomplish the above tasks. Run this utility beforeinitializing the authorization API.

The svrsslcfg utility creates a user identity for the application, and configures theSSL communication between the application and the Access Manager policy server.

The svrsslcfg utility performs the following tasks:v Creates a user identity for the application by combining the server name with

the local TCP/IP host name.v Creates an SSL key file for that user: For example, demo_user.kdb and

demo_user.sth.v Adds the user ivacld-servers group for a server type of local, or to the

remote-acl-users group for a server type of remote.

For more information, including the svrsslcfg syntax, see the reference page for“svrsslcfg” on page 180.


Verifying the identity of a userThe application must verify the identity of the user who has submitted a request.The identity can be expressed as one of the following types of users:v Authenticated

In this case, the user’s identity in the secure domain is registered in the LDAPUser registry. The user is authenticated, and information about the user can beobtained. This information includes, for example, the LDAP DistinguishedName.

v Unauthenticated

In this case, the user’s identity in the secure domain is not specifically registeredin the LDAP user registry. The user is defined to be unauthenticated, and furtherinformation about the user’s identity is irrelevant to the authorization process.

Applications can obtain user identities through a variety of methods. These caninclude the use of a Credentials Acquisition Server, or a call to anapplication-specific method for querying user registries and establishing a security(login) context.

Optionally, applications can use the Access Manager authorization API utilityfunction azn_util_password_authenticate() to obtain user identity informationfrom the secure domain.

The function azn_util_password_authenticate() requires the user name andpassword as input parameters. Typically, an application receives a user name andpassword from the user who initiated the access request.

The function performs a login using the supplied user name and password. If thelogin is successful, the function returns the following information:v The string mechanism_id, which specifies the authentication mechanism (LDAP)

that was used.v A pointer to the buffer authinfo. This buffer contains user identity information.

Note: The function azn_util_password_authenticate() does not obtain a security(login) context for the user.

For more information, see the reference page for“azn_util_password_authenticate()” on page 158.

After the application has obtained identity information for the user, you can usethe authorization API to obtain authorization credentials for the user.

Obtaining user authorization credentialsIn order to submit an authorization request to the Access Manager authorizationservice, an application must obtain authorization credentials for the user makingthe request. The authorization credentials contain user identity information that isneeded to make authorization decisions, such as group memberships and a list ofactions or rights that the user can exercise.

To obtain credentials for a user who has submitted an access request, anapplication must obtain user identity information from the LDAP user registry thatis used by the Access Manager secure domain.


The authorization API function azn_id_get_creds() takes user identity informationas input parameters and returns user authorization credentials.

The credentials can then be submitted to the authorization service for anauthorization decision.

Note: Identity information can also be obtained from a privilege attributecertificate (PAC). See“Converting credentials to the native format” onpage 41.

To obtain a credential, complete the instructions in each of the following sections:1. “Specifying the authorization authority”2. “Specifying user authentication identity”3. “Specifying additional user information”4. “Placing user information into an API buffer” on page 365. “Obtaining authorization credentials for the user” on page 36

Specifying the authorization authorityAssign the appropriate value for the authorization authority to a string of typeazn_string_t. This string is passed as the parameter mechanism_idtoazn_id_get_creds(). Set mechanism_id to NULL to specify Access Managerauthorization.

Specifying user authentication identityFor each user to be authenticated, information is loaded into the data structureazn_authdefault_t.

If the user is authenticated, you must load the user’s identity into the principalstring (of type azn_string_t) in the azn_authdefault_t data structure.

If the user is unauthenticated, information is loaded into the data structureazn_unauth_t. You do not have to load an identity into azn_unauth_t.

Specifying additional user informationWhen the application authenticates the user, the application can optionally obtainadditional information about the user. This additional information is for use by theapplication as needed. The Access Manager authorization service does not use thisinformation.

The application can store the additional user information in the data structures thatthe authorization API provides for each type of authenticated identity. The datastructures are: azn_authdefault_t, and azn_unauth_t.

The elements in each data structure are character strings, with the exception ofipaddr, which is an integer.

Element Description

authnmech_info Additional authentication information. This value can be anystring that is useful to the application. Not available inazn_unauth_t.

user_info Additional user information for auditing purposes. This stringcan contain any information that is useful to the application.

Chapter 4. Using the authorization API 35

Element Description

browser_info Information about the type of browser through which the userhas submitted the request, if applicable. This string can containany information that is useful to the application.

ipaddr The IP address of the user. This is optional information for useby the application.

qop The quality of protection required for requests made by this user.

Placing user information into an API bufferPlace the data structure you filled out in “Specifying user authentication identity”on page 35 and “Specifying additional user information” on page 35 into an

authorization API buffer.

Complete the following steps:1. Declare a buffer of type azn_buffer_t:

typedef struct azn_buffer_desc_struct {size_t length;void *value;} azn_buffer_desc, *azn_buffer_t;

2. Determine the length of your data structure and assign that value to length.3. Set the pointer value to point to the address of your data structure.

This buffer is passed as the parameter mechanism_info to azn_id_get_creds().

Obtaining authorization credentials for the userTo obtain authorization credentials, call azn_id_get_creds() with the followinginput parameters:

Parameter Description

authority The authorization authority, as described in “Specifying theauthorization authority” on page 35.

mechanism_id The authentication mechanism.c

mechanism_info User information, as described in the preceding sections:

v “Specifying user authentication identity” on page 35

v “Specifying additional user information” on page 35

v “Placing user information into an API buffer”

The azn_id_get_creds() function returns a handle to the authorization credentialsfor the user. The authorization credentials are contained in an azn_creds_h_tstructure.

For example, the following sample code demonstrates the assigning of identityinformation for a user authenticated in an LDAP user registry, and callsazn_id_get_creds() to obtain authorization credentials:azn_authdefault_t ldap_minfo;azn_string_t mech = NULL;azn_buffer_desc buf = { 0, 0 };azn_creds_h_t creds;

azn_creds_create(&creds);


/* Specify LDAP user name */ldap_minfo.ldap_dn = “cn=testuser”;

/* Set LDAP user information. Note: these values are just placeholders */ldap_minfo.auth_method = “ldap_auth_method”;ldap_minfo.authnmech_info = “ldap_authnmech_info”;ldap_minfo.user_info = “ldap_user_info”;ldap_minfo.browser_info = “ldap_browser_info”;ldap_minfo.ipaddr = 0x0a000002;

/* Set a buffer to point to the LDAP user information */buf.length = sizeof(ldap_minfo);buf.value = (unsigned char *)&ldap_minfo;

/* Obtain an authorization credential. *//* Specify the authority as NULL *//* Specify the authentication registry (mech) as NULL */

status = azn_id_get_creds(NULL, mech, &buf, &creds);if (status != AZN_S_COMPLETE) {

fprintf(stderr, “Could not get creds.\n”);continue;

}

For more information, see the reference page for “azn_id_get_creds()” on page 144.Refer also to the authorization API demonstration program.

The application is now ready to submit the authorization request. See “Obtainingan authorization decision”.

Obtaining an authorization decisionAfter the application has obtained authorization credentials for the user, theapplication passes the requested operation and the requested resource to theauthorization API function azn_decision_access_allowed(). This function returnsthe authorization decision.

To obtain an authorization decision, complete the instructions in each of thefollowing sections:v “Mapping the user operation to an Access Manager permission”v “Mapping the requested resource to a protected object” on page 38v “Assigning the user credentials to a credentials handle” on page 38v “Building an attribute list for additional application information” on page 38v “Obtaining an authorization decision” on page 39

Mapping the user operation to an Access Manager permissionThe operation requested by the user must correspond to one of the operations forwhich an Access Manager permission has been defined. The operation is astandard action supported in all Access Manager secure domains. Examplesoperations are azn_operation_read and azn_operation_traverse.

Note: For a complete list of defined operations, see the file ogauthzn.h.

Alternatively, the operation can be a custom operation.v Assign the operation to a string named operation.v Pass this string as an input parameter to azn_decision_access_allowed().


Mapping the requested resource to a protected objectThe requested resource to query for must correspond to a resource that has beendefined as a protected object in the secure domain’s protected object namespace.

The resource can be a standard WebSEAL protected resource, such as a file in theWeb space. Alternatively, the resource can be a custom protected object.

Complete the following steps:v Assign the protected object to the string protected_resource.v Pass this string as an input parameter to azn_decision_access_allowed().

Assigning the user credentials to a credentials handleThe authorization credentials for a user obtained in “Obtaining user authorizationcredentials” on page 34 can be accessed through the handle returned byazn_id_get_creds().

These credentials contain the user’s identity information and include informationsuch as the user’s group membership and permitted operations.

Complete the following step:v Pass the handle returned by azn_id_get_creds() as an input parameter to

azn_decision_access_allowed().

Note: Authorization credentials can also be obtained from the functionazn_pac_get_creds(). For more information, see “Converting credentials tothe native format” on page 41.

Building an attribute list for additional application informationThe Access Manager authorization API provides the extended functionazn_decision_access_allowed_ext() for obtaining an access decision. This functionextends azn_decision_access_allowed() by providing an additional inputparameter and an additional output parameter.

These parameters can be used to supply additional information as needed by theapplication. The Access Manager authorization service does not use theseparameters when making the access control decision. However, you can writeexternal authorization servers to use this information.

The parameters consist of an attribute list. You can build an attribute list of anylength to hold information specific to the application.

To add additional application-specific context, complete the following steps:1. Use azn_attrlist_create() to create a new, empty attribute list.2. Use azn_attrlist_add_entry() or azn_attrlist_add_entry_buffer() to add

attributes.3. When all attributes have been added, assign the input parameter app_context

to point to the attribute list.

For more information, see the reference page for“azn_decision_access_allowed_ext()” on page 135.


Obtaining an authorization decisionTo obtain an authorization decision, call one of the following functions:v azn_decision_access_allowed()

v azn_decision_access_allowed_ext()

If the API is operating in remote cache mode, the authorization request will beforwarded to the Access Manager authorization server. The authorization servermakes the decision and returns the result.

If the API is operating in local cache mode, the API uses the local authorizationpolicy database replica to make the authorization decision.

The result of the access request is returned in the following output parameter:

Type Parameter Description

int permission The result of the access request. Consists of one ofthe following constants:

AZN_C_PERMITTED AZN_C_NOT_PERMITTED

The extended function azn_decision_access_allowed_ext() also returns thefollowing information:

Type Parameter Description

azn_attrlist_h_t *permission_info Application-specific context informationcontained in attribute list.

For more information, see the reference pages for the following functions:v “azn_decision_access_allowed()” on page 133v “azn_decision_access_allowed_ext()” on page 135

Cleaning up and shutting downThe authorization API provides functions to perform the following clean up andshut down functions:v “Releasing allocated memory”v “Shutting down the authorization API” on page 40

Releasing allocated memoryThe authorization API provides the following functions to perform the releasing ofmemory functions:v azn_attrlist_delete()

Use this function to release memory that is allocated for attribute lists.v azn_attrlist_delete_entry()

Use this function to delete an entry from an attribute list.v azn_creds_delete()

Use this function to release memory that is allocated for the azn_creds_h_tstructure that is returned by a call to azn_creds_create().

v azn_release_buffer()


Use this function to release memory that is allocated for buffers of typeazn_buffer_t. Buffers of this type are used by some attribute list functions, andalso by some of the credentials handling functions.

v azn_release_pboj()

Use this function to release memory that is allocated for the azn_pobj_t structurethat is returned by a call to azn_attrlist_entry_get_pobj_value().

v azn_release_string()

Use this function to release memory allocated for any strings of typeazn_string_t. Many authorization API functions use this data type to storevalues in strings.

v azn_release_strings()

Use this function to release memory allocated for an array of strings of typeazn_string_t.

Shutting down the authorization APIWhen an application has obtained an authorization decision and when it does notneed further authorization decisions, use azn_shutdown() to disconnect from andshut down the authorization API.

Working with credentialsIn addition to the credentials handling tasks described earlier in this chapter, theauthorization API provides functions to accomplish the following optional tasks:v “Converting credentials to a transportable format”v “Converting credentials to the native format” on page 41v “Creating a chain of credentials” on page 41v “Determining the number of credentials in a credentials chain” on page 41v “Obtaining a credential from a chain of credentials” on page 41v “Modifying the contents of a credential” on page 42v “Obtaining an attribute list from a credential” on page 42

Converting credentials to a transportable formatUse the function azn_creds_get_pac() to place user credentials into a format thatcan be transported across a network to another application. Use this function whenyou need to delegate the authorization decision to an application on anothersystem.

Complete the following steps:1. Set the input string pac_svc_id to NULL.2. Set the input credentials handle creds to the credentials handle returned by a

previous call to azn_id_get_creds() or azn_pac_get_creds().3. Call azn_creds_get_pac().

The privilege attribute certificate (PAC) is returned in an output buffer named pac.This buffer can be transported to another system, where the functionazn_pac_get_creds() can be used to return the credentials to a native format.


Converting credentials to the native formatUse the function azn_pac_get_creds() when an application receives credentialsfrom another system on the network. Typically, these credentials are placed into abuffer by azn_creds_get_pac().

Complete the following steps:1. Set the input string pac_svc_id to NULL.2. Set the input buffer pac to the buffer returned by a previous call to

azn_creds_get_pac().3. Call azn_pac_get_creds().

This function returns a handle to a credentials structure of type azn_creds_h_t, foraccess by other authorization API functions.

Creating a chain of credentialsUse the function azn_creds_combine to combine, or chain, two credentials together.Use this, for example, when the credentials for a server application must becombined with user credentials in order to delegate the authorization decision toanother application.

Complete the following steps:1. Assign the credentials handle creds_to_prepend to point to the credentials of

the initiator of the request.2. Assign the credentials handle creds_to_add to point to the credentials to be

added.3. Call azn_creds_create() to create a new, empty credentials structure.4. Call azn_creds_combine().

The combined credentials are placed in a credentials structure that can bereferenced by the credentials handle combined_creds.

Determining the number of credentials in a credentials chainUse the function azn_creds_num_of_subjects() to determine the number ofcredentials that are contained in a credentials chain. Credentials chains are createdby the azn_creds_combine() function.

This functions takes as an input parameter the credentials handle of the credentialschain, and returns an integer containing the number of credentials.

Obtaining a credential from a chain of credentialsUse the function azn_creds_for_subject() to extract individual credentials from acredentials chain. Credentials chains are created by the azn_creds_combine()function.

Complete the following steps:1. Assign the credentials handle creds to point to the credentials chain.2. Assign the integer subject_index the index of the needed credential within the

credentials chain.The credentials of the user who made the request are always stored at index 0.To retrieve the credentials for the initiator (user), you can pass the constantAZN_C_INITIATOR_INDEX as the value for subject_index.


Use azn_creds_num_of_subjects(), if necessary, to determine the number ofcredentials in the chain.

3. Call azn_creds_for_subject().

This function returns the requested credentials in the credentials structurenew_creds.

Modifying the contents of a credentialUse the function azn_creds_modify() to modify a credential by placing additionalinformation, contained in an attribute list, into the credentials structure. Use thisfunction when you need to add application-specific information to a user’scredentials.

Complete the following steps:1. Use the attribute list functions to create an attribute list containing the

information to be added. Assign the attribute list handle mod_info to the newattribute list.For more information on attribute lists, see the section “Attribute lists” onpage 11.

2. Set the credential modification service mod_svc_id to NULL.3. Assign the credentials handle creds to point to the credentials to be modified.4. Call azn_creds_create() to create a new, empty credentials structure.5. Call azn_creds_modify().

The modified credentials are placed in the credentials structure new_creds.

Obtaining an attribute list from a credentialUse the function azn_creds_for_subject() to obtain information, in the form of anattribute list, from a credential. Attribute lists are added to credentials structures bycalls to azn_creds_modify().

You can use this function to obtain the attribute list for a credential that is part of acredentials chain.

The authorization API defines a number of attributes that can be returned in theattribute list. Some of the attributes might not be present in an attribute listaccording to the type of authenticated user and the information that was usedwhen the credential was built.

Attribute Name Description

azn_cred_version The credential version

azn_cred_mech_id The mechanism ID for this credential

azn_cred_principal_uuid The UUID for the entity

azn_cred_principal_name The string name of the entity

azn_cred_group_uuids The string group UUID memberships of this entity

azn_cred_group_names The string group name memberships of this entity

azn_cred_ldap_dn The LDAP DN used to build these authorizationcredentials

azn_cred_uraf_name The URAF name used to build these authorizationcredentials


Attribute Name Description

azn_cred_user_info Any user information that was passed in themechinfo structure

azn_cred_auth_method Any authentication method information that waspassed in the mechinfo structure.

azn_cred_authmech_info Any authentication mechanism information thatwas passed in the mechinfo structure.

azn_cred_ip_address The IP address information passed in the mechinfostructure

azn_cred_browser_info The browser information passed in the mechinfostructure.

Complete the following steps:1. Assign the credentials handle creds to point to the credentials chain.2. Assign the integer subject_index to the index of the credential within the

credentials chain.If the credential is not part of a chain, set subject_index to 0.The credentials of the user who made the request are always stored at index 0.To retrieve the credentials for the initiator (user), you can pass the constantAZN_C_INITIATOR_INDEX as the value for subject_index.Use azn_creds_num_of_subjects(), if necessary, to determine the number ofcredentials in the chain.

3. Call azn_attrlist_create() to create a new, empty attribute list.4. Call azn_creds_get_attrlist_for_subject().

The function returns a pointer to a handle to the attribute list containing thecredential’s attribute information. The handle is named creds_attrlist.

Setting and getting attribute values for a credentialUse the function azn_creds_get_attr_value_string() to obtain the string value ofa specified attribute in a credential. This function access the attribute list for aspecified credential, and returns the string value of the specified attribute. Formore information, see the reference page for “azn_creds_get_attr_value_string()” onpage 121.

Use the function azn_creds_set_attr_value_string() to set the value of aspecified attribute in the user credential. This function edits the attribute list of thespecified credential and sets the attribute to the specified string value.

Note that there are a number of attributes that are considered read-only and mustnot be modified by functions such as azn_creds_set_attr_value_string() orazn_creds_modify(). These attributes are read-only:v azn_cred_principal_uuid

v azn_cred_principal_name

v azn_cred_version

v azn_cred_mech_id

v azn_cred_group_uuids

v azn_cred_group_names

v azn_cred_authzn_id


v azn_cred_ldap_dn

For more information, see the reference page for“azn_creds_set_attr_value_string()” on page 131.

Comparing two credentialsUse the function azn_creds_equal() to compare the contents of two credentials.1. Identify the credentials handles (azn_creds_h_t) for each credential to be

compared.2. Pass the credentials handles as input parameters to azn_creds_equal().

The function azn_creds_eqaul() returns a boolean value of type azn_boolean_t.The value is true if the credentials are identical or false if the credentials differ.

Copying a credentialUse the function azn_creds_copy() to copy the contents of one credentials toanother, new credentials.1. Identify the credentials handles (azn_creds_h_t) for the credential to be copied.2. Pass the credentials handle as the input parameter to azn_creds_copy().

The function azn_creds_copy() returns a credentials handle to the newcredential.When the application is finished using the new credential, useazn_creds_delete() to release the memory that was allocated.

Note: To add a credential to an existing credential, use azn_creds_combine().


Chapter 5. Backwards compatibility and application migration

Access Manager Base Version 3.9 is binary backwards compatible to existing TivoliPolicy Director Version 3.8 and Version 3.7 non-DCE authorization API clients.

Existing authorization API clients that are being migrated to use the Tivoli AccessManager Base Version 3.9 ADK must run svrsslcfg again. You should use thesample configuration file aznAPI.conf, which is provided with the authorizationAPI demonstration program, as the base to create the authorization APIconfiguration file.

You may receive errors for some interfaces when compiling existing authorizationAPI clients with the Access Manager 3.9 ADK. This is because some of theauthorization API interfaces from Version 3.7 and Version 3.8 have been deprecatedfor Version 3.9.

The deprecated interfaces are located in the azn_deprecated.h header file. You canlook in azn_deprecated.h to determine the new interface that replaces eachdeprecated interface. You can also review the section “Deprecated API elements”.

In the short term, you can compile with azn_deprecated.h to continue to use thedeprecated Version 3.7 and Version 3.8 interfaces. However, you should switch assoon as possible to the new interfaces, to avoid further problems.

Binary backwards compatibilityAccess Manager Version 3.9 supports binary backwards compatibility for TivoliSecureWay Policy Director 3.7.1, Tivoli SecureWay Policy Director Version 3.8, andAccess Manager Version 3.9 applications as follows:v The Access Manager Version 3.9 runtime environment supports applications

compiled against the Tivoli SecureWay Policy Director ADK 3.7.1 (SSL based)Tivoli SecureWay Policy Director ADK Version 3.8, and Access Manager ADKVersion 3.9, with the following exception:Access Manager Version 3.9 runtime environment on the Solaris OperatingEnvironment only supports applications compiled against the Access ManagerADK Version 3.9.

v Access Manager Version 3.9 runtime environment on the Solaris OperatingEnvironment does not support applications compiled against the Access ManagerADK Version 3.8 or Version 3.7.1, due to a Solaris compiler problem.

Deprecated API elementsThis section describes elements of the authorization API that have been deprecated.The deprecated elements are supported for backwards compatibility in AccessManager 3.9. Application developers should not use the deprecated elements forany new applications

Permission info attribute valuesThe following values for the azn_init_set_perminfo_attrs attribute have beendeprecated:v azn_perminfo_wm


Replaced by azn_perminfo_wm_ulong.v azn_perminfo_wm_permitted

Replaced by azn_perminfo_wm_permitted_ulongv azn_perminfo_al

Replaced by azn_perminfo_al_ulong

The above attributes are passed as input parameters to azn_initialize().

Each of the deprecated attributes has a corresponding attribute that is returned bythe permission_info output parameter of the azn_decision_access_allowed_ext()function call. The corresponding attributes have been deprecated also.

The deprecated attributes do not work when the remote authorization API clientand the Authorization server are on operating system platforms that implementdifferent Endian ordering.

Remote authorization API clients no longer receive the azn_perminfo_qop andazn_perminfo_qop_int attributes by default. To enable this support, you mustspecify these attributes in the authorization server’s configuration file ivacld.conf.To specify these attributes, uncomment the following line in the configuration file:#permission-info-returned = azn_perminfo_qop azn_perminfo_qop_ulong

Deprecated API for comparing credentialsThe API for comparing credentials have been deprecated.v azn_creds_compare()

The azn_creds_compare() API has been replaced by azn_creds_equal(). Youshould use azn_creds_equal() because it returns an azn_status_t return code,which can be used to handle API execution failures.

Obtaining the user’s authorization identificationThe new attribute azn_cred_authzn_id replaces the following attributes:v azn_cred_dce_namev azn_cred_uraf_name

The attribute azn_cred_ldap_dn remains a valid attribute specific to LDAP butdoes not now perform the same function as azn_cred_authzn_id. Theazn_cred_ldap_dn attribute is now, for LDAP credentials only, defined to be theLDAP Distinguished Name (DN) of the principal

Authorization API initialization attributesThe following attributes have been deprecated. These attributes formerly werepassed as parameters to azn_initialize().v azn_init_namespace_locationv azn_init_tcp_portv azn_init_udp_portv azn_init_qopv azn_init_remote_ns_locv azn_init_max_handle_groups

The following configuration file entries have been deprecated. These configurationfile entries correspond to each of the attributes in the list above.


v namespace-locationv tcp-portv udp-portv remote-qopv remote-ns-locv max-handle-groups

DCE authentication APIsThe following DCE authentication APIs have been deprecated:v azn_util_server_authenticate()v azn_util_client_authenticate()

When called, these functions now return the error codeAZN_S_UNIMPLEMENTED_FUNCTION.

For Access Manager 3.9, applications are now authenticated as part ofazn_initialize().

User registry informationThe new data structure azn_authdefault_t contains credential and otherinformation used within the Access Manager secure domain. This data structurereplaces the following deprecated data structures:v azn_authdce_tv azn_authldap_tv azn_authuraf_t

Deprecated return codesThe following minor error codes have been deprecated:v AZN_ENT_PDPOBJ_INVALID_SVCINFO_HDLv AZN_ENT_PDPOBJ_INVALID_ARG_COUNTv AZN_ENT_PDPOBJ_ARG_ARRAYv AZN_ENT_PDPOBJ_OUT_OF_MEMORYv AZN_ENT_PDPOBJ_INVALID_ARGUMENTv AZN_PAC_EPAC_INVALID_SVCINFO_HDLv AZN_PAC_EPAC_INVALID_ARG_COUNTv AZN_PAC_EPAC_ARG_ARRAYv AZN_PAC_EPAC_OUT_OF_MEMORYv AZN_PAC_EPAC_INVALID_ARGUMENT

The following return codes have been replaced by major error codes defined inogauthzn.h.v AZN_S_SVC_ENT_INVALID_SVCINFO_HDLv AZN_S_SVC_ENT_INVALID_ARG_COUNTv AZN_S_SVC_ENT_ARG_ARRAYv AZN_S_SVC_ENT_OUT_OF_MEMORYv AZN_S_SVC_ENT_INVALID_ARGUMENTv AZN_S_SVC_PAC_INVALID_SVCINFO_HDLv AZN_S_SVC_PAC_INVALID_ARG_COUNT

Chapter 5. Backwards compatibility and application migration 47

v AZN_S_SVC_PAC_ARG_ARRAYv AZN_S_SVC_PAC_OUT_OF_MEMORYv AZN_S_SVC_PAC_INVALID_ARGUMENT


Chapter 6. Introducing authorization service plug-ins

The authorization API supports a service plug-in model. This model enablesdevelopers to write plug-in modules that extend the capabilities of the AccessManager authorization service. Developers of third party applications can useauthorization API functions that access the service plug-in interface to performauthorization operations that are specific to the Access Manager secure domain.

This chapter contains the following sections:v “Service plug-in architecture”v “Implementing a service plug-in” on page 53v “Supplied implementations for service plug-ins” on page 64

Service plug-in architectureThe Authorization service plug-in Architecture features the following objects:v Authorization service plug-in dispatcherv Service plug-in modulesv Calling applications

When an external application needs authorization information, it sends a request tothe service dispatcher. The service dispatcher vectors the request to the appropriateservice plug-in.


The architecture for each type of service plug-in may expand the architecturemodel illustrated above. For example, the administration service presents someextensions, as shown in Figure 4 on page 76.

The authorization service dispatcherThe authorization service dispatcher is a service of the authorization API library.The dispatcher is the management layer between authorization API interfaces andthe service plug-in modules. The dispatcher manages the location, configurationand loading of available service plug-ins.

The service dispatcher performs the following tasks:v Initializes each configured service plug-in.v Directs authorization API interface calls to the specified service plug-in.v Receives returned information from the service plug-in and returns it to the

calling application.

Access ManagerPolicy Server

Access Manager Administration API

pdadmin

AccessManager

Web PortalManager

UserApplication

or GUI

CredentialsModification

ServicePlug-in

databasedatabase

PrivilegeAttribute

CertificateServicePlug-in

EntitlementsServicePlug-in

ExternalAuthorization

ServicePlug-in

AdministrationServicePlug-in

User Application

Authorization API Client

Service Dispatcher

Authorization APIAdministration

Service APIInterface

AuthorizationEngine

Figure 3. Authorization service plug-in Architecture


v Shuts down each configured service plug-in when the authorization API is shutdown.

Authorization service plug-insAuthorization service plug-ins are shared libraries written by applicationdevelopers. Developers create these libraries to implement a domain-specific taskfor the domain-specific application. The types of data passed between the serviceplug-in and the application are also domain-specific. This means that the onlyrestrictions on the data types are the parameter definitions in the authorization APIservice functions.

The data can be in a format that is unknown to the Access Manager authorizationserver. The data is passed unchanged through the authorization service dispatcherto the authorization service plug-ins.

Authorization service plug-ins are identified by a unique identification number(ID). The service dispatcher uses the unique ID number to load the service plug-in.The service dispatcher can optionally pass initialization parameters to the serviceplug-in. The service plug-in can optionally return service information, such as theplug-in version number, to the service dispatcher.

Calling applicationsApplications may choose to use information received from service plug-ins tomake authorization decisions without requiring access to databases maintained bythe Access Manager authorization server. The service plug-in framework operatesindependently from the authorization API access_decision_* call environment.

The application invokes an authorization API function that is specific to the type ofservice. For example, to obtain entitlements information, the calling applicationcalls azn_entitlement_get_entitlements().

The API call is processed by the service dispatcher and forwarded to theappropriate service plug-in. The service performs basic error checking on thepassed parameters, to ensure that all handles are valid.

The following table lists the handles that must be valid:

Service API Function Invoked By the CallingApplication

Handle

Entitlements azn_entitlements_get_entitlements() entitlements

CredentialsModification

azn_creds_modify() creds

new_creds

Privilege AttributeCertificate

azn_pac_get_creds() new_pac

azn_creds_get_pac() pac

Administration ivadmin_protobj_get2()ivadmin_protobj_list3()ivadmin_server_gettasklist()ivadmin_server_performtask()

creds indata outdata

External authorization azn_decision_access_allowed_ext() creds app_contextpermission_info

Chapter 6. Introducing authorization service plug-ins 51

Applications are responsible for initializing and shutting down the authorizationAPI. To do this, applications call the authorization API functions azn_initialize()and azn_shutdown(). These functions call the appropriate functions for initializingand shutting down the service plug-ins.

For some services, Access Manager provides a default service. For all otherservices, the application must specify a service ID as a parameter toazn_service_initialize().

Supported types of service plug-insThe authorization service supports these types of service plug-ins:v Entitlements servicev Credentials modification servicev Privilege attribute certificate (PAC) servicev Administration servicev External authorization service

The authorization API provides common initialization and shutdown interface callsfor use by the service plug-ins. The authorization API also provides additionalinterfaces that are specific to each of the service plug-ins.

Entitlements servicesAn entitlements service plug-in enables domain-specific authorization APIapplications to retrieve the entitlements for a user from a domain-specific policyrepository. The application can use this entitlements information as needed. Forexample:v An application can allow or deny a user request for access to a protected action

or protected resource, based on the user’s entitlements.v A graphical user interface application can use entitlements information to

construct a graphical view of the Access Manager secure domain that containsonly those protected objects that the user is authorized to view.

Credentials modification serviceA credentials modification service plug-in enables domain-specific authorizationAPI applications to perform modifications on a Access Manager credential. Thecredentials modification service can then return this modified credential for use bythe calling application. Applications can use this service to add additionalinformation to a user’s credential. For example, this additional information couldinclude the user’s credit card number and the user’s credit limit.

Privilege attribute certificate serviceA privilege attribute certificate (PAC) service plug-in gives domain-specificauthorization API applications the ability to move Access Manager credentials backand forth between the native Access Manager credentials format and an alternateformat called privilege attribute certificates (PAC).

Applications can convert user credentials to PACs for use within otherauthorization domains. Applications can then pass the PACs to a server in anotherauthorization domain and perform an operation.

Administration serviceAn administration service plug-in enables applications to performapplication-specific administration tasks on protected object resources that aresecured in the Access Manager secure domain. The administration service providesfunctions that enable a plug-in to obtain the contents of a defined portion of the


protected object hierarchy. Additional functions enable a plug-in to defineapplication-specific administration tasks, and to return commands that performthose tasks.

The administration service plug-in is accessed by a calling application that sendsAccess Manager administration API calls. The calling application can be either aadministrative utility such as the Access Manager pdadmin command or theAccess Manager web portal manager, or can be a custom-built application. Theadministration service maps the administration API calls to the correspondingadministration service API calls, and carries out the requested action.

External authorization serviceAn external authorization service plug-in is an optional extension of the AccessManager authorization service that allows you to impose additional authorizationcontrols and conditions. You can use an external authorization service plug-in toforce authorization decisions to made based on application-specific criteria that arenot known to the Access Manager authorization service.

Implementing a service plug-inThis section describes how to implement a service plug-in. The service plug-inarchitecture supports standard methods for initialization, configuration, errorhandling and shutdown. Each service plug-in requires implementation of interfacesthat are specific to the service type.

This section contains the following topics:v “Initialization and configuration of service plug-ins”v “Implementing service interfaces” on page 57v “Using error codes” on page 58v “Shutdown” on page 61v “Example service source code” on page 61

Initialization and configuration of service plug-insApplications initialize the authorization API by calling azn_initialize(). Thisfunction checks the services stanzas in either the specified authorizationconfiguration file or in data contained in the init_data attribute list parameter.When a service is defined, azn_initialize() loads the service plug-in and calls theazn_service_initialize() interface.

The azn_service_initialize() interface contains parameters named argc and argv.These parameters contain the values specified in the service definition within theconfiguration file. The service definition defines all entries after the character & tobe initialization parameters. Unlike the C language argv, the argv[0] array entry isthe first parameter, and not the calling sequence for the service plug-in.

The azn_service_initialize() interface must also take the svc_init inputparameter, which specifies an attribute list. The service dispatcher may use theattribute list to pass additional information to the service plug-in.

Note: Currently, there are no attributes defined for the svc_init parameter.


The service plug-in can return information to the service dispatcher through theoptional output parameter svc_info. This parameter specifies an attribute list thatcan be used to return information, such as the version number, that is specific tothe service plug-in.

For more information, see the reference page for “azn_service_initialize()” onpage 174.

Constructing a service definitionYou can deploy an authorization service plug-in by registering it with theauthorization service. To register a service plug-in, construct a service definition.The service definition can be entered into a configuration file, or passed inprogrammatically to azn_service_initialize().

To construct a service definition, you must define several elements and thencombine them into a service definition. To do this, complete the following tasks:1. Specifying a service ID

The service ID is a unique string that identifies the service to the callingapplication. The service ID can be any string that is accepted as a valid keyname by the stanza file parsing code. The service ID is case insensitive.

2. Specifying the location of the plug-in libraryThe plug-in location is the fully qualified pathname for the shared library orDLL module that contains the plug-in for the given service ID. The fullyqualified path name is case sensitive.If the library or DLL is located in a directory that is normally searched forsystem libraries or DLLs, you can just use the library name. Examples of thistype of location are /usr/lib on UNIX systems and %PATH% on Windows NTsystems.You can specify a “short form” library name if you want the library name to beplatform independent. This enables the library to be loaded on any supportedAccess Manager platform.The authorization API will prepend and append the library with known libraryprefixes and suffixes, and search for each possibility in turn.For example, the authorization API will search for a library with the short formname of azn_ent_user by looking for each of the following files:

Platform Library File Name

Windows NT azn_ent_user.dll

AIX libazn_ent_user.so, libazn_ent_user.a

Solaris libazn_ent_user.so

HP/UX libazn_ent_user.sl

3. Specifying plug-in parametersThe entry of additional parameters is optional. The azn_service_initialize()function can pass these parameters to the service plug-in as initializationinformation in the form of arguments.To add optional initialization parameters to the service definition, insert the &character and then specify the arguments.

4. Building a service definitionEach service plug-in entry uses the following syntax:<service-id> = <plug-in location> [ & <plug-in parameters> ]


Parameters specified after the ampersand (&) are passed to the service plug-in’sshared library. Parameters specified before the & are processed by theauthorization API. For example, the external authorization service can have anoptional weight parameter, and the administration service can optionally takethe name of a protected object hierarchy name.

The following line is an example entry for an entitlements service plug-in:entsvc = /lib/libentsvc.so & -server barney

In the above example:v The service ID is entsvc.v The plug-in location is /lib/libentsvc.so

v The optional arguments are -server barney. In this example, the optionalarguments tell the service plug-in the name of the server where the plug-inexecutes.

After constructing your service definition, choose one of the following methods forregistering your service definition:v “Configuring a service by using a configuration file” on page 55v “Configuring a service programmatically” on page 55

Configuring a service by using a configuration fileThe Access Manager authorization service recognizes and registers service plug-insby reading entries in the configuration file aznapi.conf.

When the application initializes the authorization API, the authorization serverparses the configuration file. The dispatcher resolves the location of each serviceplug-in, and loads each service plug-in. The azn_service_initialize() functionreturns an error if a service plug-in is not configured correctly or if the serviceplug-in module cannot be located.

Each type of service has a separate section within the configuration file. Thedefault configuration file contains the following entries:

Entry Service Type

[aznapi-entitlement-services] Entitlements service plug-ins

[aznapi-pac-services] Privilege attribute certificate serviceplug-ins

[aznapi-cred-modification-services] Credentials modification serviceplug-ins

[aznapi-admin-services] Administration service plug-ins

[aznapi-extern-authzn-services] External Authorization serviceplug-ins

Configuring a service programmaticallyYou can use the init_data input parameter to pass a service definition toazn_initialize(). Service definitions that are defined programmatically do nothave to be defined in the configuration file aznapi.conf.

To use init_data, build an attribute list that contains the service definition entries.The file ogauthzn.h defines the following strings to use for the attribute list namesfor each type of service.


/* Entitlements service definition attribute */AZN_DECLSPEC azn_string_t azn_init_ent_svc;/* PAC service definition attribute */AZN_DECLSPEC azn_string_t azn_init_pac_svc;/* Credential modification service definition attribute */AZN_DECLSPEC azn_string_t azn_init_cred_mod_svc;/* Administration service definition attribute */AZN_EXTSPEC azn_string_t azn_init_admin_svc;/* External authorization service definition attribute */AZN_EXTSPEC azn_string_t azn_init_extern_authzn_svc;

Use each of the above attributes to define a service of that particular type. Theformat of the string attribute values is described in “Constructing a servicedefinition” on page 54. Each part of service definition, such as <service id>,represents a separate string value for the attribute.

Each attribute can have multiple service definitions. Use the functionazn_attrlist_add_entry() to add the attribute and string values to the attributelist.

The following example shows source code for configuring an entitlements serviceprogrammatically.azn_status_t status;azn_attrlist_h_t init_data, init_info;azn_string_t service_entry;

azn_attrlist_create(&init_data);azn_attrlist_create(&init_info);

/** Load an Entitlements Service programmatically. The service* entry will load the DLL “mysvc” and associate it with the* service ID “MYSVC”. The dispatcher will automatically search* the library search path for the platform specific DLL name* variations of this name. On NT: mysvc.dll, and on Unix:* libmysvc.so. The parameters -server and -port will be passed* to the azn_service_initialize() interface of the service in the* argv array.*/

service_entry = “MYSVC=mysvc & -server barney -port 1234";

status = azn_attrlist_add_entry(init_data,azn_init_ent_svc,service_entry);

if (status != AZN_S_COMPLETE) {fprintf(stderr, “azn_attrlist_add_entry_failed: [%08X:%08X]\n”,

azn_error_major(status),azn_error_minor(status));

exit -1;}

/** Call initialize*/status = azn_initialize(init_data, &init_info);

if (status != AZN_S_COMPLETE) {fprintf(stderr, “\nazn_initialize failed: [%08X:%08X]\n”,

azn_error_major(status),azn_error_minor(status));

exit -1;}


Implementing service interfacesThe implementation of a service plug-in consists of building a shared library. Theshared library must contain interfaces that are specific to the type of service. Theseinterfaces perform the work that is specific to the service. A calling applicationsends a request to the authorization API, which vectors the request to theappropriate service plug-in. The service plug-in shared library must contain animplementation of the authorization API interface that will perform the tasksspecific to the service plug-in.

The following table shows the authorization API interface that is invoked by thecalling application, and the corresponding authorization API interface that isimplemented in the service plug-in shared library.

Service API function invoked by the callingapplication

Function implemented by the serviceplug-in

Entitlements service azn_entitlement_get_entitlements() azn_entitlement_get_entitlements()

Credentials modificationservice

azn_creds_modify() azn_creds_modify()

Privilege attribute certificateservice

azn_creds_get_pac() azn_creds_get_pac()

azn_pac_get_creds() azn_pac_get_creds()

Administration service ivadmin_protobj_get2() azn_admin_get_object()

ivadmin_protobj_list3() azn_admin_get_objectlist()

ivadmin_server_gettasklist() azn_admin_get_tasklist()

ivadmin_server_performtask() azn_admin_perform_task()

External authorization service azn_decision_access_allowed()

azn_decision_access_allowed_ext()

azn_decision_access_allowed()


Note that the name of the authorization API function that is invoked by the callingapplication and the name of the authorization API function that is invoked by theservice plug-in shared library are often the same. Note, however, that these are twoseparate implementations of the interface (function). The service plug-in sharedlibrary implements its own version of the interface, in order to perform servicetype-specific tasks.

For example, calling applications often call azn_decision_access_allowed_ext() torequest an authorization decision. When the authorization API has been configuredto recognize an external authorization service, this call toazn_decision_access_allowed_ext() is routed through the service dispatcher to theappropriate external authorization service plug-in shared library. Within thislibrary the plug-in developer will have implemented a local version ofazn_decision_access_allowed_ext() that can make authorization decisions basedon conditions or rules that are potentially unknown to the core Access Managerauthorization engine.

As long as the implementation of the interface within the service plug-in satisfiesthe interface (function) signature of the authorization API function, the serviceplug-in shared library can augment the default authorization process with codespecific to the plug-in.


Note that the interfaces described in this section are in addition to the interfacesthat are generic to all types of service plug-ins. These generic interfaces includeinitialization, shutdown, and error handling functions.

Using error codesThe authorization API service plug-in interface defines a number of major errorcodes. The interface also defines a minor error code mask and an error codecreation utility which service plug-ins must use to construct error codes.

Use of this error mask ensures that the 32 bit major and minor error codes arecorrectly translated to a 32 bit error code for return to the calling application.

The calling application parses the returned error code into its major and minorerror code components by the using the azn_error_major() and azn_error_minor()function calls.

Developers of service plug-ins should use the authorization API utility functionazn_util_errcode() to construct valid error codes to return to the callingapplication. The function azn_util_errcode() takes major and minor integer errorcode values and converts them in to an azn_status_t value. The minor error codemust be defined as described in “Minor error codes” on page 60.

Major error codesAuthorization service plug-ins should return all applicable major error codes thatare defined by the authorization API. service plug-ins should also return the majorerror codes defined for a particular type of service plug-in, such as the entitlementsservice.

Note: Some error codes do not apply to all service plug-in types.

The following additional major error codes are defined for the authorization APIservice modules in ogauthzn.h. The service dispatcher returns only some of theerror codes, while other error codes are returned only by the service plug-in.

The following table shows the error codes that the service dispatcher returns.

Error Description

AZN_S_SVC_DEFINITION_ERROR

The service dispatcher returns this error when the service definition isconstructed incorrectly in the Service stanza of the configuration file or in avalue that is passed in the init_data attribute list of azn_intialize().

AZN_S_SVC_SERVICE_NOT_FOUND

The service dispatcher returns this error when it cannot locate theauthorization API service plug-in. The service dispatcher also returns this errorwhen it cannot load the service plug-in.

AZN_S_SVC_INITIALIZE_NOT_FOUND

The service dispatcher returns this error when it encounters an error whileeither locating or loading a service interface within a specific service plug-in.For example, the service dispatcher returns this error if theazn_service_initialize() interface could not be found in the loaded serviceplug-in.

AZN_S_ INVALID_MOD_FUNCTION

The supplied modification service identifier is invalid.


Error Description

AZN_S_INVALID_PAC_SVC

The identifier (id) of the PAC service is invalid.

AZN_S_SVC_DISPATCHER_FAILURE

The service dispatcher failed. This can be caused by incorrect initialization ofthe authorization API.

AZN_S_SVC_DLL_LOAD_FAILED

The DLL for a service plug-in failed to load correctly

AZN_S_SVC_SERVICE_IS_REGISTERED

The service ID cannot be registered because it is already listed as registered bythe service dispatcher.

AZN_S_SVC_INITIALIZE_NOT_FOUND

The azn_service_intialize() function was not found.

AZN_S_SVC_SHUTDOWN_NOT_FOUND

The azn_service_shutdown() function was not found.

AZN_S_SVC_ENT_FUNC_NOT_FOUND

The azn_entitlement_get_entitlements() function was not found.

AZN_S_SVC_PAC_FUNC_NOT_FOUND

One of either azn_pac_get_creds() or azn_creds_get_pac() was not found.

AZN_S_SVC_CRED_MOD_FUNC_NOT_FOUND

The azn_creds_modify() function was not found.

AZN_S_SVC_EAS_FUNC_NOT_FOUND

One of either azn_decision_access_allowed() orazn_decision_access_allowed_ext() was not found.

AZN_S_SVC_ADMIN_POBJ_FUNC_NOT_FOUND

One of either azn_admin_get_object() or azn_admin_get_objectlist() was notfound.

AZN_S_SVC_ADMIN_TASK_FUNC_NOT_FOUND

One of either azn_admin_perform_task() or azn_admin_get_tasklist() was notfound.

The following table shows the major error codes that service plug-ins return:

Error Description

AZN_S_ SVC_INIT_FAILED

The service plug-in returns this error when it encounters an error duringinitialization.

AZN_S_ SVC_SHUTDOWN_FAILED

The service plug-in returns this error when it encounters an error duringshutdown.

AZN_S_SVC_AUTHORIZATION_FAILURE

The service plug-in returns this error when the calling application lacksauthorization to invoke the Service.


In addition to the generic major codes that apply to all types of service plug-ins,there exist generic major codes that apply to a specific service plugin. These majorcodes are defined in ogauthzn.h.

Error Code Prefix Description

AZN_S_SVC_ADMIN_* Administration service plug-in major errorcodes.

AZN_S_SVC_ENT_* Entitlements service plug-in major error codes.

AZN_S_SVC_EAS_* External authorization service plug-in majorerror codes

AZN_S_SVC_CRED_MOD_* Credentials modification service plug-in majorerror codes.

AZN_S_SVC_PAC_* Privilege attribute certificate services plug-inmajor error codes

In all of the above cases, the application developer may also insert animplementation specific minor error code into the status code. The minor errorcode provides the calling application with further information on the error that theservice plug-in encountered. The calling application uses azn_error_minor() toextract the minor error code.

Minor error codesThe service plug-in modules define minor error codes. Each minor error code isspecific to a particular service plug-in. Developers should define the minor errorcodes in the interface file for the service plug-in. The interface file also containsother details specific to the service plug-in, such as the names of the attributesrecognized by the service. Applications that use the service plug-in will includeand reference the service interface file.

The authorization API encodes all minor error codes by using a table of knownmessage catalog prefixes. There is one prefix for all service plug-ins of the sametype. For example, all entitlements service plug-ins use the same prefix.

The file ogauthzn.h defines the following prefixes:

Service Prefix

Entitlements azn_ent_svc_err_prefix

Credentials Modification azn_mod_svc_err_prefix

Privilege Attribute Certificate azn_pac_svc_err_prefix

Administration service azn_admin_svc_err_prefix

External authorization service azn_eas_svc_err_prefix

The service plug-in developer must use these prefixes to define the minor errorcodes for each service plug-in. The azn_util_errcode() interface uses theseprefixes to properly encode each minor error into an azn_status_t.

For example, the prefix for Entitlement Services is defined as follows in the fileogauthzn.h:

extern unsigned int azn_ent_svc_err_prefix;


Entitlement service developers should define their error messages in terms ofazn_ent_svc_err_prefix.

For example, minor error codes for authorization API entitlement service plug-insare defined in the interface file as follows:#define ENT_SVC_CORE_DUMP (azn_ent_svc_err_prefix | 0x1)

#define ENT_SVC_INVALID_ATTRIBUTE (azn_ent_svc_err_prefix | 0x2)

#define ENT_SVC_BAD_FILENAME (azn_ent_svc_err_prefix | 0x3)

The service plug-in developer has 16 bits of the minor error code to use for minorerror codes specific to a service. The 16 bit error code can be personalized for theservice, to avoid conflicts with other service plug-ins of the same type.

For example:#define MY_ENTSVC_ERR (0xE000)#define ENT_SVC_CORE_DUMP \(azn_ent_svc_err_prefix | (MY_ENTSVC_ERR | 0x1))

ShutdownApplications shut down the service plug-ins as part of shutting down theauthorization API. The application calls azn_shutdown(). If a Service is initialized,azn_shutdown() calls azn_service_shutdown().

The azn_service_shutdown() interface is called with the same argc and argvparameters that were passed to the azn_service_initialize() interface when theservice plug-in was first initialized.

The azn_service_shutdown() also takes the optional input parameter svc_init,which specifies an attribute list. The service plug-in developer can use the attributelist to pass additional information to the service plug-in. Currently, there are nodefined attributes for svc_init.

The service plug-in can return information to the service dispatcher through theoptional output parameter svc_info.

For more information, see the reference page for “azn_service_shutdown()” onpage 177.

Example service source codeThis section contains source code for an example implementation of anentitlements service plug-in. This code demonstrates configuration, initialization,shutdown, and implementation of interfaces specific to the service type./** FILENAME* mysvc.cpp** DESCRIPTION** Example entitlements service for the aznAPI.**/

#include <stdio.h>#include <ogauthzn.h>#include <aznutils.h>


#ifdef _WIN32#define AZN_DECLSPEC __declspec(dllexport)#else#define AZN_DECLSPEC#endif

#define MY_SVC_VER “Example Entitlements Service v1.0”

/** Define a mask to identify minor errors that originate from this* service. All 3rd party entitlements services must use the* azn_ent_svc_err_prefix to prefix minor code definitions. The lower* 16 bits should be differentiated from other installed entitlements* services. eg. in this case 0x8000 identifies the error as originating* from this service.*/#define AZN_MYSVC_ERROR_MASK (azn_ent_svc_err_prefix | 0x8000)#define AZN_MYSVC_INVALID_SVCINFO_HDL (AZN_MYSVC_ERROR_MASK | 1)#define AZN_MYSVC_INVALID_ARG_COUNT (AZN_MYSVC_ERROR_MASK | 2)#define AZN_MYSVC_INVALID_ARG_ARRAY (AZN_MYSVC_ERROR_MASK | 3)

#ifdef __cplusplusextern “C” {#endif

/*********************************************************************** Interface function definitions.***********************************************************************/

/** FUNCTION NAME* azn_service_initialize** DESCRIPTION* init the entitlements service** ARGUMENTS* [in] argc The count of arguments to the service.* [in] argv The array of argument strings.* [in] svc_init List of initialization attributes for

the service.* [out] svc_info attr list ptr for attributes returned by the* service.** RETURN VALUE* AZN_S_COMPLETE on success, error code on failure*/

AZN_DECLSPECazn_status_tAZN_CALLTYPEazn_service_initialize(

int argc, /* in */char **argv, /* in */azn_attrlist_h_t svc_init, /* in */azn_attrlist_h_t *svc_info /* out */

){

azn_status_t st;azn_boolean_t freeAttrlist = FALSE;

/* svc_info must not be NULL */if (svc_info == NULL) {

return (azn_util_errcode(AZN_S_FAILURE,AZN_MYSVC_INVALID_SVCINFO_HDL));

}


/* ensure argc is valid */if (argc < 0 || (argc == 0 && argv != NULL)) {

return (azn_util_errcode(AZN_S_FAILURE,AZN_MYSVC_INVALID_ARG_COUNT));

}

if (argc > 0 && argv == NULL) {return (azn_util_errcode(AZN_S_FAILURE,

AZN_MYSVC_INVALID_ARG_ARRAY));}

/*** Process arguments and initialize service.**/

/* return the service version to the dispatcher */if (*svc_info == AZN_C_INVALID_HANDLE) {

azn_attrlist_create(svc_info);freeAttrlist = TRUE;

}

st = azn_attrlist_add_entry(*svc_info, azn_svc_version, MY_SVC_VER);

if (st != AZN_S_COMPLETE) {if (freeAttrlist) {

azn_attrlist_delete(svc_info);}return (st);

}

return (AZN_S_COMPLETE);}

/** FUNCTION NAME* azn_service_shutdown** DESCRIPTION* Shutdown the entitlements service.* The initialization parameters are passed in* again on shutdown but are ignored. No version* info is returned.** ARGUMENTS* [in] argc The count of arguments to the service.* [in] argv The array of argument strings.* [in] svc_init List of initialization attributes for

the service.** [out] svc_info attr list ptr for attributes returned by the* service.** RETURN VALUE* AZN_S_COMPLETE*/

AZN_DECLSPECazn_status_tAZN_CALLTYPEazn_service_shutdown(

int argc, /* in */char **argv, /* in */azn_attrlist_h_t svc_init, /* in */


azn_attrlist_h_t *svc_info /* out */){


/** FUNCTION NAME* azn_entitlement_get_entitlements** DESCRIPTION* Returns entitlements information associated with* the credential and context info passed in.** ARGUMENTS* [in] creds The credentials of the caller* [in] svc_id The id of the entitlements service* [in] app_context attribute list containing information* regarding the type of object we are* operating on* [out] entitlements attribute list containing the* entitlements associated with the specified* object** RETURN VALUE* AZN_S_COMPLETE on success, error code on failure*/AZN_DECLSPECazn_status_tAZN_CALLTYPEazn_entitlement_get_entitlements(

azn_creds_h_t creds, /* in */azn_string_t svc_id, /* in */azn_attrlist_h_t app_context, /* in */azn_attrlist_h_t *entitlements /* out */

){

/* Authenticate the call or authorize the caller */

/* Obtain entitlements data from back-end database */


#ifdef __cplusplus}#endif

Supplied implementations for service plug-insThe Access Manager authorization ADK supplies implementations for a number ofdifferent service plug-in types. Some of these implementations are built into theauthorization API. Others consist of separate shared libraries.

The name for each implementation that consists of a shared library is specified asthe short name in the table in each of the following sections. You can use the shortname when specifying the plug-in location, as part of constructing the servicedefinition. For more information, see “Constructing a service definition” onpage 54.

The following sections describe the supplied service implementations:v “Access Manager entitlements services” on page 65


v “Credentials modification service” on page 66v “Privilege attribute certificate service” on page 66v “External authorization service” on page 67

Access Manager entitlements servicesAccess Manager provides a default entitlement service specific to the AccessManager environment. This entitlements service is called the Access Managerprotected objects entitlements service, and is provided in the authorization APIdistribution package.

This entitlements service should be configured in secure domains with AccessManager servers that have been configured and are running.

The Access Manager protected objects entitlements service provides the followingfeatures:v The service returns a list of protected resources in the database for which the

given credential has the specified access privilege. For example, the applicationcan request the service to return a list of HTML objects under/WebSEAL/srvA/staff for which a specified user has read permission. A graphicaluser interface application can use the returned entitlements (protected objectnames) to determine which buttons the specified user can see when the GUIapplication is loaded.

v The entitlements service accepts a single, multi-valued string attribute thatspecifies the root node(s) for searching the Access Manager protected objectnamespace. This enables the application to limit its search to a particular set ofprotected objects in the web space, rather than search the entire web space.Because the attribute can contain multiple values, the application can specifymultiple root nodes for the search.

v Entitlements data is returned as a multi-valued attribute list of protected objectsfor each search tree root node passed in to theazn_entitlement_get_entitlements() call. The list contains only objectsunderneath the specified root node.

Service Plug-in Summary

Category Description

Name Extended attributes entitlements service

Service ID User specified in the service definition.

Plug-in Short Name azn_ent_ext_attr

Parameters app_context Input attribute name: One of “POP”, “ACL” or“OBJ”. This attribute contains the protectedobject name that is the target for the request.

entitlements An list of the extended attributes that aredefined for the target object.

Description Returns the extended attributes defined for an ACL, POP orprotected object. The protected object to which the ACL or POP isattached or that is the target for the operation is specified as aparameter.


Credentials modification serviceThe Access Manager authorization ADK provides two implementations of acredentials modification service. One implementation modifies attribute lists. Theother implementation modifies group memberships.

The service described in the table below is built-in to the authorization API.



Name Credentials attribute list modification service

Service ID Null

Plug-in Short Name not applicable (built-in)

Parameters creds The credentials with which to work.

list The attribute list to replace.

outcred The credential resulting from the operation.

Description This service will replace the attribute list in credential creds withthe attribute list list. Read-only attributes, such as group UUIDs,cannot be changed by this service. The original credential is leftunchanged and a new credential containing list is returned inoutcred.

The service described in the table below is not built into the authorization API.



Name Credentials group membership modification service


Plug-in Short Name azn_mod_rad

Parameters creds The credentials to modify

mod_info Input attribute:AZN_MOD_RAD_GROUP_NAMES Containsthe names of the groups to which the resultingcredential creds will effectively be added.

newcreds A new credential based on creds and built toinclude the groups in mod_info.

Description Gives a credential membership in a specified set of groups. Thenew credential is returned in newcreds. The original credential isunaffected and the results are localized to authorization checksmade with the returned credential newcreds. The actual user registryand the user’s entry within the registry are not affected by thismodification service.

Privilege attribute certificate serviceThis service is built in to the authorization API.



Name Access Manager privilege attribute certificate (PAC) encodingservice




Service ID NULL

Plug-in Name not applicable (built-in)

Parameters:azn_creds_get_pac()

creds Input parameter. The credentials to beencoded.

pac An azn_buffer_t that will contain theencoded credentials PAC for creds oncompletion.

Parameters:azn_pac_get_creds()

pac An encoded PAC to be decoded intocredentials.

new_creds A pointer to an azn_creds_h_t that willrefer to the credential decoded by theservice from pac.

Description Encodes and decodes a Access Manager credential to or froma format that is transmissible in a text only environment. Theformat is a combination of ASN1 and MIME encoding.

External authorization serviceThe Authorization ADK provides a sample implementation of an externalauthorization service (EAS) plug-in. This implementation is not built-in to theauthorization API.



Name Example external authorization service


Plug-in Short Name azn_eas_demo

Parameters not applicable

Description This is an example EAS plug-in which simply returnsAZN_C_PERMITTED for all authorizations in which it is called toparticipate. Configure the EAS to be called for a decision thatwould normally return AZN_C_NOT_PERMITTED. Thedemonstration program performs some perfunctory checking ofinput parameters but does not attempt to make any authorizationrelated decisions based upon the incoming access decisioninformation (ADI).



Chapter 7. Implementing entitlements service plug-ins

The authorization API services framework provides a modular, plug-in stylearchitecture that enables application developers to supplement Access Managerauthorization with their own entitlements models. Developers can build a sharedlibrary object that implements an entitlements service. Developers then configurethe authorization API to use their module by exposing the appropriate entitlementsinterface.

The entitlements shared library object is a plug-in to the authorization API.Application developers build their plug-in as an authorization API client. Theentitlements service plug-in must know how to manipulate authorization APIstructures such as user credentials and attribute lists. In most cases, the serviceplug-in functions as an authorization API client.

This chapter contains the following topics:v “Understanding entitlements”v “Initialization, configuration, and shutdown” on page 70v “Obtaining entitlements for a specified user” on page 71v “Authorizing a caller to a specific entitlements service plug-In” on page 72v “Using authorization API interfaces” on page 72v “Entitlements service error codes” on page 72

Understanding entitlementsAn entitlement is a data structure that contains externalized policy information. Anentitlement is policy data or capabilities that is formatted in a way that isunderstandable to a specific application. The application uses the authorization APIto instruct the Access Manager authorization service to obtain and return theentitlements.

For example, an application for processing stock market trading can define anentitlement called trading limit. This entitlement defines the maximum amount thata specific trader can trade in one transaction. The entitlement can be setindependently for each trader known to the application. The application canrequest the trading limit for a specific trader. The authorization service returns theentitlement in a format, such as United States dollars, that the application canunderstand.

Entitlements to be brokered by the service are designed with the target applicationin mind. The policy to be modeled using entitlements is first identified and thenthe possible values for these entitlements are specified.

The authorization API uses attributes within an attribute list to representindividual entitlements. Each attribute within the list consists of an attribute nameand a multi-valued list of values for that attribute. Attributes can consist of valuesrepresented by data of type azn_string_t, by data of type azn_buffer_t, or by anyother valid attribute type.

Note: For more information on authorization API attribute lists and data types, seeChapter 2, “Authorization API functions and data types” on page 7.


Entitlements of type azn_string_tAn example of an entitlement is the time of day access restrictions for a particularresource. This refers to the time periods during a day that a particular user ispermitted to access the resource to which the entitlement is attached. The attributename defined by the entitlements service for this entitlement is simply a string:extern azn_string_t time_of_day_restriction;

The value of the data returned is specific to the implementation and so may bereturned as multiple strings identifying times of the day in which the resource maybe accessed.

For example:

"mon-fri: 9am-5pm"

“mon-fri: 1pm-5pm”

“sat: 9am-12pm”

These string values for time_of_day_restriction define valid access times.

The entitlements service defines how these strings are formatted and interpretedby the calling application.

The Access Manager protected object entitlements serviceAnother example of an entitlement is the data returned by the Access Managerprotected object entitlements service.

This service returns a list of objects within the protected object space for which thegiven user credential has the specified access privileges.

An application could use this information to create a portal interface specificallyfor each user that invokes the application. The services that each user can employare returned to the application as a list of strings. Each string represents aprotected object within the Access Manager protected object space that the callerwith the specified privileges can access.

Entitlements of type azn_buffer_tEntitlements services may also define an entitlement as a blob of data using anazn_buffer_t value for the attribute. This may be used by distributed object basedapplications such as Common Object Request Broker Architecture (CORBA) toretrieve encoded CORBA objects from the entitlements service that can then beused to perform an operation for the calling application. The contents of theazn_buffer_t data type are opaque to the authorization service.

For more information on data type azn_buffer_t, see “Buffers” on page 9.

Initialization, configuration, and shutdownEach entitlements service plug-in is a standalone module that is dynamicallyloaded into the authorization service.

The Access Manager authorization service recognizes and registers entitlementsservice plug-ins with the service dispatcher by reading entries in the configurationfile aznapi.conf.


Entitlements service plug-ins are declared in the configuration file under thefollowing stanza entry:[aznapi-entitlement-services]

The Access Manager authorization service also recognizes and registersentitlements service plug-ins through arguments passed to the init_data parameterof the azn_initialize() function.

For complete configuration specifications, see “Initialization and configuration ofservice plug-ins” on page 53.

The authorization API service plug-in model provides standard interfaces to theservice dispatcher to initialize and shut down all types of service plug-ins.Developers of entitlements service plug-ins should provide the standard functions.See the following sections:

For more information, see the following sections:v “Initialization and configuration of service plug-ins” on page 53v “Shutdown” on page 61

See also the reference pages for “azn_service_initialize()” on page 174 and“azn_service_shutdown()” on page 177.

Obtaining entitlements for a specified userThe authorization API provides the azn_entitlement_get_entitlements() interfacefor obtaining entitlements for a specified user. Both the calling application and theservice plug-in must provide this interface. Theazn_entitlement_get_entitlements() interface has the following input parameters:

Input Parameter Type Parameter Description

azn_creds_h_t creds The credentials of the user for whom thecalling application wants the list ofentitlements.

azn_string_t svc_id The service identification string of theentitlements service plug-in.

azn_attrlist_h_t app_context The resource within the protected objectspace, and the action requested.

The authorization API service dispatcher directs the request to the appropriateservice plug-in, based on the svc_id parameter.

The service plug-in also takes the above parameters as input, and returns therequested entitlements in the attribute list entitlements. The service plug-in is notrequired to use the input parameters, but it is required to return valid data in theentitlements output parameter.

Entitlements service plug-ins share the address space of both the callingapplication and the authorization API shared library. service plug-ins can assumethat pointers passed in through the app_context parameter are valid within theaddress space of the service plug-in. Credential and attribute list handles are alsovalid to use within the service plug-in.

Chapter 7. Implementing entitlements service plug-ins 71

Authorizing a caller to a specific entitlements service plug-InEntitlements service plug-ins typically supply information in a directory service,such as LDAP, or in a data store, such a DB2 database, to the application caller.These directory services or data stores may require a proprietary authenticationstep before permitting access to stored information. The developer of eachentitlements service plug-in must implement these proprietary authentication steps.The authorization API does not provide functions to implement proprietaryauthentication models.

The authorization API does, however, provide the plug-in initialization interfaceazn_service_initialize(). This interface permits the passing of proprietary datain parameters to the service initialization function.

Alternately, the developer can use the initialization parameters to authenticate theauthorization API application before loading the entitlements service plug-in. Inthis case, the entitlements service plug-in can inherit privileges from theauthorization API application.

Using authorization API interfacesEntitlements service plug-ins should access the contents of passed parametersusing the authorization API. The entitlements service plug-ins are not required tomake use of any other features or interfaces of the authorization API other thanthose that provide access to these data types.

The entitlements service plug-in becomes part of the authorization APIapplication’s address space. The service plug-in can assume that if it is deniedaccess to a particular authorization API interface that the calling application wasnot allowed to perform the operation.

Entitlements service error codesThe entitlements service can generate error codes from the following functions:v azn_service_initialize()

v azn_service_shutdown()

v azn_entitlement_get_entitlements()

For information on error codes for azn_service_initialize() andazn_service_shutdown(), see “Using error codes” on page 58.

The azn_entitlement_get_entitlements() function returns the following errorcodes:

Error Code Description

AZN_S_INVALID_CREDS_HDL

The credentials handle supplied is invalid.

AZN_S_INVALID_ENTITLEMENTS_SVC

The entitlements service identifier is invalid.

AZN_S_INVALID_APP_CONTEXT_HDL

The attribute list handle for the application context isinvalid.

AZN_S_INVALID_ENTITLEMENTS_HDL



The attribute list handle for the entitlements is invalid.

AZN_S_FAILURE An implementation specific error or failure hasoccurred. An implementation specific minor error codeshould be returned in the status code for the caller toextract with azn_error_minor().

Each entitlements service plug-in can optionally return minor error codes thatexpress errors specific to the service plug-in implementation. For more informationon implementing minor error codes, see “Minor error codes” on page 60.

Chapter 7. Implementing entitlements service plug-ins 73


Chapter 8. Implementing administration service plug-ins

This chapter contains the following topics:v “Understanding administration service plug-ins”v “Configuring administration service plug-ins” on page 77v “Initializing and shutting down administration service plug-ins” on page 78v “Using an administration service plug-in” on page 79v “Error codes” on page 80v “Deploying an administration service plug-in” on page 82

Understanding administration service plug-insThe administration service makes available to applications several administrativefunctions that operate on objects in the Access Manager protected objectnamespace. Application developers can write a plug-in to the administrationservice that applies these administrative functions to objects in a section of thenamespace that is specific to the application. Through the plug-in, applicationdevelopers can also specify administrative actions that are specific to objects in theapplication-specific namespace.

The administration service differs from other authorization API services in that itdoes not provide direct access to the administrative function to the callingapplications. Instead, the calling applications use the Access Manageradministration API to send a request.

For example, the administration service functions are called in response toadministrative operations that are issued by a calling application such as thepdadmin command line interface, the Access Manager Web portal managergraphical console, or a third-party application that has been written to use theAccess Manager administration API.

The administration service maps the administration API calls to the correspondingadministration service API calls, and carries out the requested action. There is aone-to-one mapping between several administration API functions and acorresponding administration service function.

The administration service supports dynamic object creation and task execution byadding an externalized administration family of functions to the authorization API.The name of each of these functions is prefixed byazn_admin. You implement thesefunctions within libraries that are registered with the Authorization administrationservice by an authorization API client application.


In Figure 4, the user application or GUI sends an administrative operation throughthe Access Manager administration API to the Access Manager policy server. TheAccess Manager policy server uses an internal interface to forward the call to theadministration service interface. The administration service interface maps theincoming call to the appropriate administration service function and passes it tothe authorization service plug-in dispatcher. The dispatcher routes the request tothe application that registered an administration service plug-in to handle thisfunction. The function call within the registered library is made and the results arereturned to the Access Manager policy server. The Access Manager policy serverthen returns the results to the calling application.

Note that the diagram above shows three different administration service plug-ins.You do not need to implement more than one plug-in, but multiple plug-ins aresupported.

Do not confuse the Access Manager authorization administration service with theAccess Manager administration API. The Access Manager administration API

Access ManagerPolicy Server

AdministrationService Plug-in

A

database


B


C

database database

Access Manager Administration API

pdadminAccess

Manager WebPortal Manager

UserApplication or

GUI

Service Dispatcher

Authorization APIAdministration

Service APIInterface

AuthorizationEngine

Figure 4. The administration service plug-in to the authorization API


provides a series of programmatic interfaces that a calling application can use tosend requests to the Access Manager policy server.

In most cases, applications can use the administration API independent from anyuse of the authorization administration service. However, application developerscan use the authorization administration service plug-in to provide “back-end”authorization functions that can leverage administration API functions to executeapplication-specific administrative commands. This is described in more detail in“Using an administration service plug-in” on page 79.

Most of the Access Manager administration API functions provide programmaticequivalents to each of the pdadmin command line interfaces. The names of theadministration API functions begin with the ivadmin_ prefix. The functions aredescribed in the ivadminapi.h header file. For more information on the AccessManager administration API, see the IBM Tivoli Access Manager Administration CAPI Developer’s Reference.

Configuring administration service plug-insYou can configure an administration service plug-in either manually orprogrammatically. Manual configuration is accomplished by setting values in aconfiguration file. Programmatic configuration is accomplished by passingattributes to the administration API at API initialization. These methodscorrespond directly to the registration steps used by all types of authorizationservice plug-ins, as described in “Constructing a service definition” on page 54.

Configuration of an administration service plug-in is describe d in the followingsections:v “Creating a configuration file entry for an administration service”v “Configuring an administration service programmatically” on page 78

Creating a configuration file entry for an administrationservice

Administration service plug-ins are typically configured in aznapi.conf, under thefollowing stanza:[aznapi-admin-services]

The administration services definition syntax is as follows:<service-id> = <plug-in location> [-pobj <protected object hierarchy name>]

[& <plug-in parameters>]

The protected object hierarchy name is an optional parameter. This parameter anrefer to either the name of a protected object space (hierarchy) or simply to aprotected object. The authorization service does not process the characters after theampersand &. It passes these characters directly to the administration serviceplug-in.

Here is an example configuration file entry:[aznapi-admin-services]adminsvc1 = /lib/libadminsvc1.so -pobj /Printers/printer1 & -printer sequoiaadminsvc2 = /lib/libadminsvc2.so -pobj /Printers/printer2 & -printer sequoiaadminsvc3 = /lib/libadminsvc3.so & -printer sequoiaadminsvc4 = /lib/libadminsvc4.so

Chapter 8. Implementing administration service plug-ins 77

As shown in the example above, an authorization API application can registermore than one administration service plug-in, but each must have a unique serviceID.

Each authorization service plug-in passes the administration service definitions tothe Access Manager policy server during the azn_initialize() call. This enablesthe Access Manager policy server to know the mapping of a protected objecthierarchy name to the authorization API client application that has registered anadministration service plug-in for it. Since this mapping is global, care must betaken to specify protected object space mappings that do not conflict acrossauthorization API client applications.

Thus, protected object hierarchy names must be unique for each administrationservice plug-in within the scope of an authorization API application. Multipleauthorization API application instances, however, can register to service the sameprotected object hierarchy name(s). This can be used to provide failover supportfor administration of an object space in the event that a particular authorizationAPI application server fails.

Configuring an administration service programmaticallyThe authorization API header file ogauthzn.h contains a service definition attribute:azn_string_t azn_init_admin_svc

Complete the following steps to use this service definition attribute to configure anadministration service plug-in.1. Use the azn_attrlist_add_entry() API to assign to the init_data attribute list as

many values to the azn_init_admin_svc attribute as the number ofAdministrative service plug-ins needed. These values are expressed as strings,and need to conform to the administration service definition syntax specified in“Initialization and configuration of service plug-ins” on page 53.Ensure that protected object hierarchies that are specified as part of the servicedefinition attribute are unique. See the discussion just above in “Creating aconfiguration file entry for an administration service” on page 77.

2. Pass the init_data attribute to the azn_initialize() call to ensure that thespecified administration service plug-ins are loaded.

Initializing and shutting down administration service plug-insEach administration service plug-in is a standalone module that is dynamicallyloaded into the authorization service.

The authorization API service plug-in model provides standard interfaces to theservice dispatcher to initialize and shut down all types of service plug-ins.Developers of administration service plug-ins should provide the standardfunctions. See the following sections:v “Initialization and configuration of service plug-ins” on page 53v “Shutdown” on page 61

For more information, see the reference pages for “azn_service_initialize()” onpage 174 and “azn_service_shutdown()” on page 177.


Using an administration service plug-inThe administration service supports the following authorization API functions:

Function Description

azn_admin_get_object() Retrieves a potential protected object. Tests for theexistence of a protected object.

azn_admin_get_objectlist() Accesses the administration service to provide a listof all potential protected objects that are children ofthe specified parent object.

azn_admin_perform_task() Instructs the service to perform an administrationtask. The service returns the results of the task.

azn_admin_get_tasklist() Returns a list of all the supported administrationtasks.

Each of the functions above maps to an equivalent administration API functionand an equivalent pdadmin command line interface. The mappings are shown inthe table below.

Authorization API administrationFunction

Administration API function pdadmin command line interface

azn_admin_get_object() ivadmin_protobj_get2() pdadmin object show object_name

azn_admin_get_objectlist() ivadmin_protobj_list3() pdadmin object list object_namepdadmin object listandshowobject_name

azn_admin_perform_task() ivadmin_server_performtask() pdadmin server task server_name task

azn_admin_get_tasklist() ivadmin_server_gettasklist() pdadmin server listtasks server_name

The Access Manager policy server uses these mappings to redirect theadministration API calls (ivadmin_*) and the pdadmin command lines thatcorrespond to the azn_admin_get_object() and azn_admin_get_objectlist() APIsto the appropriate administration service plug-in. When processing theadministration APIs (ivadmin_*) and the pdadmin command lines that correspondto the azn_admin_perform_task() and azn_admin_get_tasklist() APIs, the AccessManager policy server just forwards them to the corresponding authorization APIclient application.

Not all of the authorization API administration service interfaces are relevant toevery Authorization administration service plug-in. Therefore, a result of notsupported is returned for each administration service interface not implemented bythe authorization service plug-in.

The administration service plug-ins make use of the following attributes in theoutdata attribute list that they return.

Attribute Description

azn_admin_svc_pobj Administration service protected object attribute,of type azn_string_t.

azn_admin_svc_task Administration service task attribute, of typeazn_string_t.

azn_admin_svc_results Administration service results attribute, of typeazn_string_t.


For more information on the authorization API administration functions, see thefollowing reference pages:v “azn_admin_get_object()” on page 164v “azn_admin_get_objectlist()” on page 166v “azn_admin_get_tasklist()” on page 168v “azn_admin_perform_task()” on page 171

Error codesThis section contains the following topics:v “Errors when registering the administration service plug-in”v “Errors when registering administration definitions” on page 81v “Major errors from administration service functions” on page 81v “Minor errors from administration service functions” on page 81v “Error codes specific to an authorization services plug-in” on page 82

Errors when registering the administration service plug-inThe authorization API initialization function azn_initialize() fails when theAuthorization administration service definitions made by a single authorizationAPI application result in following error conditions:


AZN_S_SERVICE_IS_REGISTERED

Attempted to register more than one service definitionwith the same service-id

AZN_S_SVC_ADMIN_POBJ_ALREADY_REGISTERED

Attempted to register more than one service definitionwith the same protected object hierarchy name

AZN_S_SVC_ADMIN_POBJ_FUNC_NOT_FOUND

The -pobj option is specified for an administration servicedefinition, but the specified plug-in does not contain theazn_admin_get_objectlist() and theazn_admin_get_object() functions.

When the -pobj option is not specified, the plug-in is notrequired to support either of these functions.

AZN_S_SVC_ADMIN_TASK_FUNC_NOT_FOUND

The administration service plug-in supports only one ofthe task related functions azn_admin_get_tasklist() andazn_admin_perform_task(). Each Administration serviceplug-in must support either both the task-relatedfunctions or support none of them.

AZN_S_INVALID_LISTENING_PORT

When the administration service plug-in registrationsucceeds, but the ssl-listening-port has not beenspecified as part of the authorization API initialization,azn_initialize() returns this error.


Errors when registering administration definitionsThe authorization API registers the administration service definitions with theAccess Manager policy server during the azn_initialize() call. The policy serverstores the registered administration service definitions in persistent store andoverwrites an existing registration when it receives a new registration from thesame authorization API application.

When the authorization API cannot contact the Access Manager policy serverduring azn_initialize(), it skips registration of the specified administrationservice definitions, logs a message describing that failure, loads the associatedplug-ins, and completes the azn_initialize() call.

The failure of the authorization API to contact the Access Manager policy servercan occur within one of the following contexts:v The administration services have already been registered with the policy server.

In this case, when the policy server becomes operational again, anyadministration API functions or pdadmin command lines that are handled bythe administration service definitions will automatically succeed again.

v The administration service definitions have not been registered with the policyserver, because this was the first attempt to register them.In this case, the authorization API must be re-initialized so that it can registerthe administration service definitions. Once contact with the policy serversucceeds, the administration API functions and pdadmin commands willsucceed.

v The authorization API has already registered the administration services withthe policy server. However, the service definitions being registered now differfrom definitions that are already registered.In this case, the new service definitions have not successfully registered, and theadministration API functions and pdadmin commands will fail once the policyserver starts. The authorization API needs to be restarted. This causes theauthorization API to be re-initialized, which results in the policy serverregistering the new service definitions and deleting the old ones.

Major errors from administration service functionsThe authorization service APIs are not invoked directly by the end user. They areinvoked by policy server in response to certain administration API functions orpdadmin commands. The administration service plug-ins can return the majorerror codes specified for the authorization API, as well as those specifiedgenerically for all authorization service plug-ins.

The authorization service APIs can also return the AZN_S_SVC_ADMIN_* majorstatus codes that are generic for all Authorization administration service plug-ins.The authorization API forwards these return codes to the policy server, whichreturns them to the administration API or pdadmin command. The final returncode sent to the end-user conforms to the error codes returned by theadministration API functions or the pdadmin commands.

Minor errors from administration service functionsThe administration service functions conform to the authorization services plug-inmodel for using azn_util_errorcode() to return plug-in specific error return codeswithin the 16-bit minor error code portion of azn_status_t. The returned minorerror code must be a valid Access Manager minor error code, in order for theAccess Manager policy server to generate a message for it. If the returned minor


code is invalid, an error message of unknown error is returned to the pdadmincommand or administration API function that issued the request.

For more information on authorization service minor error codes, see “Minor errorcodes” on page 60.

Error codes specific to an authorization services plug-inAdministration service plug-ins can also return implementation-specific returncodes in the outdata output parameter for the azn_admin_* calls. For example, thefunctions can return status codes of type unsigned long by using theazn_attrlist_add_entry_ulong() API to add unsigned long values to apre-defined attribute in the outdata attribute list.

The administration service functions can return results strings (which are displayedat the pdadmin CLI) as values for the azn_admin_svc_results attribute of theoutdata attribute list. These results strings are forwarded by the policy server to thepdadmin command line interface or to the application using the administrationAPI functions.

The administration service functions can also return other attributes of their choice.These attributes are added to the outdata attribute list and directly forwarded to thecaller of the administration API.

Deploying an administration service plug-inWhen you have developed your administration service plug-in, and are ready todeploy it, complete the following steps:v Run svrsslcfg for the authorization API application. Specify the appropriate

input parameters.For more information, see the reference page for “svrsslcfg” on page 180.

v When configuring the authorization API calling application, use pdadmin or theadministration API to create the application-specific portion of the protectedobject namespace.

v Create the appropriate protected objects under the application-specific portion ofthe protected object namespace.

v Register the administration service plug-ins for the protected objects created inthe previous step. See “Configuring administration service plug-ins” on page 77.


Chapter 9. Implementing external authorization serviceplug-ins

This sections consists of the following topics:v “Introducing the external authorization service”v “Understanding the external authorization service” on page 84v “Configuring an external authorization service plug-in” on page 88v “Initializing and shutting down external authorization service plug-Ins” on

page 89v “Obtaining an authorization decision” on page 90v “Error codes” on page 91

Introducing the external authorization serviceThe external authorization service is a modular authorization service plug-in thatallows system designers to supplement Access Manager authorization with theirown authorization models. Developers can build a shared library object thatimplements an external authorization service. You can configure the authorizationAPI client to use this plug-in by ensuring that the appropriate interfaces areexposed within the library. The external authorization service is implemented as anauthorization API client so that the plug-in can manipulate authorization API datastructures such as the credentials and attribute lists.

External authorization service plug-ins are called only by local-mode authorizationAPI client. Remote-mode authorization API clients do not have a localauthorization server and thus cannot call out to an external authorization service.The configuration of external authorization service plug-ins is applicable only tolocal-mode authorization API clients.

The external authorization service plug-in model includes a Distributed ComputingEnvironment (DCE) Remote Procedure Call (RPC) based external authorizationservice, for backwards compatibility with previous versions of Access Manager.This plug-in transforms the parameters of the new plug-in interface into those usedby the RPC interface in Policy Director Version 3.7 and earlier. Clients that want toconsult an RPC-based external authorization service need to deploy a DCE clienton the client machine.

Configuration of external authorization service plug-ins is performed in the sameway as other authorization service plug-ins. Initialization settings are specifiedeither through a configuration file or programmatically through the initializationattribute list of the azn_initialize() function. For legacy DCE-RPC externalauthorization servers, the configuration that was previously stored in theauthorization database is now configured for each local mode authorization APIclient. This configuration information is passed to the plug-in as parameters thatare specific to the individual plug-in.

Initialization settings consist of a service definition that specifies a policy trigger forwhich the external authorization service is invoked, a weighting that is assigned inthe access decision process to the particular external authorization service, and thelocation of the dynamically-loadable library module that performs the


authorization work specific to the external authorization service. The concepts ofpolicy triggers and weightings are described later in this section.

Each external authorization service plug-in must expose three interfaces to theauthorization service:v azn_service_intialize()

v azn_service_shutdown()

v azn_decision_access_allowed_ext()

The external authorization service plug-ins follow the service plug-in model forreturning error messages by combining major error codes and application-specificminor error codes to produce valid error codes that can be returned to the callingapplications.

Understanding the external authorization serviceThis section consists of the following topics:v “External authorization service architecture”v “Policy triggers” on page 86v “Weightings” on page 87

External authorization service architectureThe external authorization service architecture is derived directly from the generalauthorization service plug-in architecture.


The calling application is represented by the authorization API application object inthe above diagram. The calling application sends access decision information (ADI)to the authorization engine to request an authorization decision. The authorizationengine first makes an access decision based on the ADI that was passed-in and onthe credentials of the requesting user. The decision is assigned an integer valuecalled a weighting.

Next, the Access Decision Combinator is called. It returns a weighted accessdecision result, based on calls to all applicable external authorization serviceplug-ins. The Combinator is responsible for identifying and invoking each externalauthorization service that is applicable to the authorization decision request. TheCombinator examines the policy actions contained in the Access Control List (ACL)that has requested the decision, and combines these with the protected objectpolicy (POP) attributes from the applicable POP. These actions and attributes arecombined to create a policy trigger.

The Combinator uses this policy trigger information to call the service dispatcherto identify a list of external authorization service plug-ins which must be called.

LDAPDatabase

OracleDatabase

Authorization API Application

OtherDatabase

EAS Plug-in A EAS Plug-in B EAS Plug-in C

Authorization API

Authorization Engine

Authorization Decision Combinator

Service Dispatcher

Figure 5. The external authorization service architecture

Chapter 9. Implementing external authorization service plug-ins 85

The Combinator then calls each external authorization service in turn. Thepermission value returned from each call is multiplied by the weighting for thespecific EAS. The weighted result is then passed to the Access Managerauthorization engine.

The service dispatcher for the external authorization service plug-ins manages thelocation, configuration, and loading of the available EAS plug-ins. The servicedispatcher handles EAS plug-ins in the same manner as other types of plug-ins,such as entitlements services, administration services, and credentials modificationservices.

Policy triggersPolicy triggers refer to the set of policy circumstances that trigger a particular EASto be invoked for any particular access decision. In prior versions of AccessManager, only a specific action or operation in an access control list (ACL) couldserve as a policy trigger. For version 3.8 and later of Access Manager, the policytriggers have been expanded to include more ACL permissions and POPs.

ACL based policy triggers have been expanded to include action sets in addition tosingle action flags. For example, you can set the trigger to rx to have the EAScalled whenever this bit mask appears in the primary action group of the ACLunder evaluation. Similarly, a trigger of Printer[wx] invokes an EAS when boththe w and x permission bits of the user-defined Printer action group are presenttogether in the ACL that is being evaluated. The condition is triggered when allactions in the set are present in the current ACL for the access decision.

POP-based policy triggers allow an EAS to be called for one or more specificprotected objects within the protected object space. The POP trigger is defined asan extended attribute within the POP. Its value is set to the specific policy triggerstring needed to trigger the target EAS. The policy trigger is simply the service IDof the target EAS.

When the extended attribute value is not NULL, the POP is evaluated as part ofthe authorization process in the Access Manager authorization engine. Theattribute name to be used must be specifically for the purpose of EAS registration.The attribute name can have more than one value. This means that multiple policytriggers can be configured for the one POP. Each policy trigger is called in turn.The EAS are called in the order in which they were first added to the attribute.

Configuring a POP policy triggerPOP objects reserve the extended attribute name eas-trigger for the purpose ofregistering EAS triggers. New POP objects have no entry for this name by default.User must explicitly register an policy trigger with the POP through pdadmin orthe administration API. To be valid, the extended attribute must contains one ormore values that must match the policy trigger field in the service definition of atleast one of the EAS modules that are loaded when the authorization API isinitialized.

The following examples show the pdadmin commands for adding and removingpolicy triggers from POP objects.pdadmin> pop show <pop-name> eas-triggerpdadmin> pop modify <pop-name> set eas-trigger trigger-stringpdadmin> pop modify <pop-name> delete eas-triggerpdadmin> pop modify <pop-name> delete eas-trigger trigger-string


By passing the trigger string as a parameter to the set command you can add aspecific trigger from the list of configured triggers. Likewise, by passing the triggerstring as a parameter to the delete command you can remove a specific triggerfrom the list of configured triggers.

You can also use the Access Manager administration API to add and delete policytriggers within the POP extended attributes. In each of the cases shown in the tablebelow, the caller passes the string eas-trigger as the attr_key input string.

Administration API Function Description

ivadmin_pop_attrget() Get the EAS policy triggers for a POP

ivadmin_pop_attrput() Set an EAS policy trigger for a POP

ivadmin_pop_attrdelkey() Delete all the EAS policy triggers for a POP

ivadmin_pop_attrdelval() Delete a specific EAS policy trigger for a POP

WeightingsThe Access Manager authorization service provides the core authorization engineresponsible for making authorization decisions. You can add one or more externalauthorization service plug-ins to provide additional authorization decision-makingdecisions. When you have more than one authorization decision-making process,you must specify the relative rank or priority that each decision carries. You canuse the concept of a weighting to specify this rank or priority. For each externalauthorization service, you specify the appropriate weighting in the servicedefinition that is used to configure the external authorization service.

The weight parameter is an unsigned size_t value and is optional. The defaultAccess Manager Authorization engine has a weight of 100. The weight of each EASis relative to other external authorization services, and to the core authorizationengine. When the weighting for an external authorization service is not specified adefault value of 101 is assigned.

When the Access Manager authorization engine or an EAS returns an accesspermitted decision, the value of the overall access decision is increased by theinteger amount of the applicable weighting. When the authorization engine or anEAS returns an access denied decision, the value of the overall access decision isdecreased by the integer amount of the applicable weighting.

When the value of the overall decision is greater than zero (0), the access request isapproved. When the value of the overall decision is less than zero (0), the accessrequest is denied.

When the value equals zero, the access decision is made based on the valuereturned by the Access Manager authorization engine. Thus, the authorizationengine takes precedence over the external authorization services when the sumtotal of the supplemental external authorization services’ decisions is not strongenough to override the decisions made by the core engine.

For example, when the core engine is given a weight of 100 and it returns an accesspermitted decision, the value of the result is +100. When an external authorizationservice with a weighting of 60 is then called, and returns an access denied decision,then this final result value is modified to +40. If another EAS with weighting of 60


is called, and it also returns an access denied decision, then the final result is -20. Inthis case, access is denied because the overall result is less than zero.

Each external authorization service has the option of not participating in a specificaccess decision. The EAS can return a permission value of AZN_C_INDIFFERENT.When this occurs, the Access Manager authorization service does not factor theweighting for the EAS into the final result.

Configuring an external authorization service plug-inYou can configure an external authorization service plug-in either manually orprogrammatically. Manual configuration is accomplished by setting values in aconfiguration file. Programmatic configuration is accomplished by passingattributes to the administration API at API initialization. These methodscorrespond directly to the registration steps used by all types of authorizationservice plug-ins, as described in “Constructing a service definition” on page 54.

Configuration of an external authorization service plug-in is described in thefollowing sections:v “Using a configuration file entry”v “Configuring an external authorization service programmatically” on page 89

Using a configuration file entryExternal authorization service plug-ins are typically configured in aznapi.conf,under the following stanza:[aznapi-external-authzn-services]

The external authorization services definition syntax is as follows:<policy-trigger> = <plug-in location> [-weight <N>] [& <plug-in parameters>]

For example:Printer:rxT = eas_plugin -weight 60 & -server barney

Orwebseal_pop_trigger = eas_plugin_2 -weight 70 & -hostname fred

The policy-trigger can be any string that is recognized as a valid key name. Stanzakey names cannot contain white space or the open bracket “[“ and close bracket“]” characters. The bracket characters are used to define new stanza names. Thepolicy-trigger is case sensitive for action set definitions because the actionsthemselves are case sensitive. However, the policy-trigger is case insensitive if thetrigger is a POP attribute.

The first example above shows an action set trigger with a user-defined actiongroup of Printer and the actions rxT within that group. To specify the primaryaction group you would specify only :rxT. This entry has an empty action groupname. Any policy-trigger that does not contain a colon “:” character is consideredto be a protected object policy (POP) attribute name.

The second example above is for a POP attribute trigger calledwebseal-pop-trigger. When a POP that contains a reference to this string is passedto the Combinator, the appropriate external authorization service is called to take


part in the access decision. Note that the POP configuration must have beencompleted previously by the secure domain administrator, using the pdadmincommand.

The plug-in location is the path name to the shared library or DLL module thatcontains the implementation of the plug-in that matches the policy trigger. Thepath name can be in a truncated form if the external authorization service is to beloaded by clients on multiple platforms. In this case, the service dispatchersearches for the plug-in using platform-specific prefixes and suffixes to match DLLnames.

The weight parameter is an unsigned size_t value and is optional. The valuesignifies the weight that any decision returned by this external authorizationservice should be given in the entire decision process.

Optionally, the external authorization service can be passed additional initializationinformation in the form of arguments. The arguments must be preceded by theampersand “&”. The optional arguments in the first example above are & -server-barney

Configuring an external authorization serviceprogrammatically

The authorization API header file ogauthzn.h contains a service definition attribute:azn_string_t azn_init_extern_authzn_svc

The value of the attribute is a string of the format:policy-trigger = plug-in_location [-weight N] [& plug-in_parameters]

For example:POP_EAS_A = my_eas_pop_1 -weight 50 & -server fred

Or:rmx = my_acl_ops_pop_1 -weight 60 & -server barney

Complete the following steps to use this service definition attribute to configure anexternal authorization service plug-in.1. Use the azn_attrlist_add_entry() API to assign to the init_data attribute list as

many values to the azn_init_extern_authzn_svc attribute as the number ofAdministrative service plug-ins needed. These values are expressed as strings,and need to conform to the external authorization service definition syntaxspecified in “Using a configuration file entry” on page 88.

2. Pass the init_data attribute to the azn_initialize() call to ensure that thespecified Administration service plug-ins are loaded.

Initializing and shutting down external authorization service plug-InsEach external authorization service plug-in is a standalone module that isdynamically loaded into the authorization service.

The authorization API service plug-in model provides standard interfaces to theservice dispatcher to initialize and shut down all types of service plug-ins.Developers of external authorization service plug-ins should provide the standardfunctions. See the following sections:v “Initialization and configuration of service plug-ins” on page 53


v “Shutdown” on page 61

When the authorization API is initialized the configuration file is parsed and eachexternal authorization service plug-in listed in the [aznapi-external-authzn-service] stanza is loaded and resolved by the service plug-in dispatcher. Theauthorization API also recognizes the external authorization service plug-insspecified by the azn_init_extern_authzn_svc attribute in the init_data attribute listthat is passed as input to azn_initialize(). Each of those plug-ins is also loadedand resolved by the service plug-in dispatcher.

If a plug-in is configured incorrectly, or the plug-in module can’t be found, theazn_initialize() function returns an appropriate error.

When each external authorization service plug-in has been successfully loaded, theauthorization service initialization interface is called with the parameters specifiedafter the ampersand “&” character in the service definition.

For more information on initialization and shutdown of service plug-ins, see thereference pages for “azn_service_initialize()” on page 174 and“azn_service_shutdown()” on page 177.

Obtaining an authorization decisionThe service dispatcher calls this interface to request an access decision from theEAS plug-in. This interface is called by the azn_decision_access_allowed() andazn_decision_access_allowed_ext() API interfaces and is expected to return bothpermission codes and error codes consistent with that required by authorizationAPI interface specification for the those interfaces. For example:azn_status_tazn_decision_access_allowed_ext(azn_creds_h_t creds, /* input */azn_string_t protected_resource, /* input */azn_string_t operation, /* input */azn_attrlist_h_t app_context, /* input */int *permission, /* output */azn_attrlist_h_t *permission_info /* output */);

The azn_decision_access_allowed() and azn_decision_access_allowed_ext()functions return the same permission code values as their counterpart calls do in theauthorization API. The EAS can return one of three possible permission values tothe authorization engine:AZN_C_PERMITTED 0AZN_C_NOT_PERMITTED 1AZN_C_INDIFFERENT -1

The EAS returns AZN_C_INDIFFERENT when it does not care about the accessdecision in question. For example, this can occur when a minimum requirement forthe input conditions was not met. Alternatively, the EAS may decide it does nothave jurisdiction for the decision. In these cases, the Combinator ignores the returnvalue from this EAS when calculating the result of the access decision.

The permission_info parameter should contain any decision-related informationattributes that the EAS wants to return to the calling application. If an initializedattribute list handle is passed back to the service dispatcher, then the attributes areadded to the permission_info list that is passed back to the caller.


Ensure that your implementation of azn_decision_access_allowed_ext() isthread-safe. Input parameters must not be modified. You can assume that thecalling application will free the output parameters that are returned. This interfacereturns AZN_S_COMPLETE when successful, or an error when it fails.

Error codesThe authorization service plug-in interface, including the EAS plug-in interface,defines a number of major error codes and a minor error code mask that an EASmust use to construct error codes to return to the calling application. The errorcodes returned by the plug-in interfaces are not parsed or modified by theauthorization API runtime functions. These codes are passed back unmodified tothe calling application. Thus, the error code that is returned must be able to beparsed into its major and minor error code components by the calling application.The calling application uses azn_error_major() and azn_error_minor() tocomplete the parsing. To properly construct the error codes, the authorization APIprovides a utility function that enables developers of third-party extensions,(including service plugs-in such as the EAS) to the authorization API to constructvalid error codes to return to application programmers. This function isazn_util_errcode(). This function takes a major and minor integer error codevalue and converts them into an azn_status_t value. The minor error codereturned must be defined in accordance with the rules below.

Major error codesExternal authorization service plug-ins should return all applicable major errorcodes that are defined for returning status from theazn_decision_access_allowed() and azn_decision_access_allowed_ext()interfaces. Note that not all error codes will apply to all plug-in services.

The following table shows major error codes:


AZN_S_INVALID_CREDS_HDL

The credentials handle supplied is invalid

AZN_S_INVALID_PROTECTED_RESOURCE

The protected_resource string supplied is invalid.

AZN_S_INVALID_OPERATION

The operation string supplied is invalid.

AZN_S_INVALID_EAS_ACL_TRIGGER

The EAS ACL policy trigger specified is invalid.

AZN_S_INVALID_EAS_POP_TRIGGER

The EAS POP policy trigger specified is invalid.

AZN_S_INVALID_EAS_WEIGHTING

The EAS weighting specified is invalid. An absolute size_t value isrequired.

AZN_S_UNKNOWN_EAS_SVC_PARAMETER

A parameter other than -weight was specified in an externalauthorization service definition.

AZN_S_INVALID_APP_CONTEXT_HDL

The attribute list handle for the application context is invalid.



AZN_S_INVALID_PERMISSION_REF

The integer pointer for the permission parameter is invalid.

AZN_S_FAILURE

An implementation specific error or failure has occurred. Animplementation specific minor error code should be returned in thestatus code for the caller to extract with azn_error_minor().

The following additional major error codes are defined for authorization APIservice modules in ogauthzn.h. Some of the following error codes are returnedonly by the service dispatcher, and some are returned only by the service plug-in.The returning entity is noted in the description of each error code.


AZN_S_SVC_DEFINITION_ERROR

Returned by the service dispatcher when an error has been found inthe service definition in the authorization API configuration file.

AZN_S_SVC_NOT_FOUND

Returned by the service dispatcher when an error occurs either whilelocating or loading an authorization service plug-in.

AZN_S_SVC_INITIALIZE_NOT_FOUND AZN_S_SVC_SHUTDOWN_NOT_FOUNDAZN_S_SVC_EAS_FUNC_NOT_FOUND

Returned by the service dispatcher when an error occurs eitherlocating or loading a service interface within a particular plug-in. Forexample, this is returned by the dispatcher if theazn_service_initialize() interface was not found in the loadedplug-in.

AZN_S_ SVC_INIT_FAILED

Returned by the plug-in when an error occurs while it is initializing.

AZN_S_ SVC_SHUTDOWN_FAILED

Returned by the plug-in when an error occurs while it is shuttingdown.

AZN_S_SVC_AUTHORIZATION_FAILED

The calling application does not possess the authority required toinvoke the services of this plug-in.

Minor error codesMinor error codes are encoded by the authorization API using a table of knownmessage catalogue prefixes. All Access Manager messages are composed of a prefixvalue and the specific error code within that message set. When the authorizationAPI encodes a minor error code, using azn_util_errcode(), the prefix is removedfrom the minor code and cross-referenced with a table of known prefixes. Whenthe prefix is identified, it is converted into a mask, which is then inserted into themajor error portion of the azn_status_t code returned. The reverse operation isperformed by the azn_error_minor() function to rebuild the original minor errorcode.

To enable minor error codes returned by authorization API services to be properlyencoded by azn_util_errcode() an appropriate prefix must be defined for


authorization API service plug-ins. The same prefix is shared by all services of thesame type. The prefix for all external authorization services is defined inogauthzn.h as follows:extern unsigned int azn_eas_svc_err_prefix;

Define error messages for your external authorization service by using theazn_eas_svc_err_prefix. For example, minor error codes for an external authorizationservice plug-in are defined in the interface file as follows:#define EAS_SVC_CORE_DUMP(azn_eas_svc_err_prefix | 0x1)#define EAS_SVC_INVALID_ATTRIBUTE(azn_eas_svc_err_prefix | 0x2)#define EAS_SVC_BAD_FILENAME(azn_eas_svc_err_prefix | 0x3)



Appendix A. Authorization API reference

This section contains the following reference pages:v azn_attrlist_add_entry()v azn_attrlist_add_entry_buffer()v “azn_attrlist_add_entry_pobj()” on page 99v “azn_attrlist_add_entry_ulong()” on page 100v “azn_attrlist_copy()” on page 101v “azn_attrlist_create()” on page 102v “azn_attrlist_delete()” on page 103v “azn_attrlist_delete_entry()” on page 104v “azn_attrlist_get_entry_buffer_value()” on page 105v “azn_attrlist_get_entry_pobj_value()” on page 107v “azn_attrlist_get_entry_string_value()” on page 108v “azn_attrlist_get_entry_ulong_value()” on page 110v “azn_attrlist_get_names()” on page 111v “azn_attrlist_name_get_num()” on page 112v “azn_creds_combine()” on page 113v “azn_creds_copy()” on page 115v “azn_creds_create()” on page 116v “azn_creds_delete()” on page 117v “azn_creds_equal()” on page 118v “azn_creds_for_subject()” on page 119v “azn_creds_get_attr_value_string()” on page 121v “azn_creds_get_attrlist_for_subject()” on page 122v “azn_creds_get_pac()” on page 124v “azn_creds_modify()” on page 126v “azn_creds_num_of_subjects()” on page 129v “azn_creds_set_attr_value_string()” on page 131v “azn_decision_access_allowed()” on page 133v “azn_decision_access_allowed_ext()” on page 135v “azn_entitlement_get_entitlements()” on page 138v “azn_error_get_string()” on page 140v “azn_error_major()” on page 141v “azn_error_minor()” on page 142v “azn_error_minor_get_string()” on page 143v “azn_id_get_creds()” on page 144v “azn_initialize()” on page 146v “azn_pac_get_creds()” on page 149v “azn_release_buffer()” on page 151v “azn_release_pobj()” on page 152v “azn_release_string()” on page 153v “azn_release_strings()” on page 154


v “azn_shutdown()” on page 155v “azn_util_errcode()” on page 156v “azn_util_handle_is_valid()” on page 157v “azn_util_password_authenticate()” on page 158v “azn_util_password_change()” on page 160


azn_attrlist_add_entry()Adds a name or string-value entry to an attribute list

Syntaxazn_status_tazn_attrlist_add_entry(

azn_attrlist_h_t attr_list,azn_string_t attr_name,azn_string_t string_value);

ParametersInput

attr_listHandle to an attribute list. The attribute list handle can be one of thefollowing:v An attribute list handle for a new, empty attribute list, which has been

initialized by a call to azn_attrlist_create().v An attribute list handle for an existing, non-empty attribute list which

contains valid data.

attr_nameAttribute name of the entry to be added.

string_valueString attribute value to be added.

DescriptionThis function adds a string value to the attribute attr_name within the attribute listattr_list. If the attribute attr_name already exists in the list then the value isappended to the existing list of values for attr_name. The values under attr_nameare stored in the order in which they were inserted into the list. There is nochecking performed upon values in the list; therefore duplicate values arepermitted.

Return ValuesIf successful, the function will return AZN_S_COMPLETE.

If the returned status code is not equal to AZN_S_COMPLETE, the major errorcodes will be derived from the returned status code with azn_error_major().v AZN_S_COMPLETE

Successful completion.v AZN_S_INVALID_ATTRLIST_HDL

Attribute list handle is invalid.v AZN_S_INVALID_ATTR_NAME

Attribute name is invalid.v AZN_S_INVALID_STRING_VALUE

Attribute value is invalid.v AZN_S_FAILURE

An error or failure has occurred. Use azn_minor_error() to derive specific minorerror codes from the returned status code.

Appendix A. Authorization API reference 97

azn_attrlist_add_entry_buffer()

Adds a name/buffer value entry to an attribute list.

Syntaxazn_status_tazn_attrlist_add_entry_buffer(

azn_attrlist_h_t attr_list,azn_string_t attr_name,azn_buffer_t buffer_value

);

ParametersInput




attr_nameAttribute name of the entry to be added.

buffer_valueBuffer attribute value to be added.

DescriptionThis function adds a buffer value to the attribute attr_name within the attribute listattr_list. If the attribute attr_name already exists in the list then the value isappended to the existing list of values for attr_name. The values under attr_nameare stored in the order in which they were inserted into the list. There is nochecking performed upon values in the list; therefore duplicate values arepermitted.

Return ValuesIf successful, the function returns AZN_S_COMPLETE.

If the returned status code is not equal to AZN_S_COMPLETE, the major errorcodes will be derived from the returned status code with azn_error_major.v AZN_S_COMPLETE



Attribute name is invalid.v AZN_S_INVALID_BUFFER

Attribute buffer is invalid.v AZN_S_FAILURE

An error or failure has occurred. Use azn_minor_error() to derive specific minorerror codes from the returned status code.


azn_attrlist_add_entry_pobj()Adds the name of a protected object entry to the attribute list.

Syntaxazn_status_tazn_attrlist_add_entry_pobj(azn_attrlist_h_t attr_list,azn_string_t attr_name,azn_pobj_t pobj_value);

ParametersInput




attr_nameName of the attribute to which the value is to be added.

pobj_valueProtected object attribute value to be added.

DescriptionThis function adds a protected object value to the attribute attr_name within theattribute list attr_list. If the attribute attr_name already exists in the list then thevalue is appended to the existing list of values for attr_name. The values underattr_name are stored in the order in which they were inserted into the list. There isno checking performed upon values in the list; therefore duplicate values arepermitted.

Return ValuesWhen successful, the function returns AZN_S_COMPLETE.

When unsuccessful, the function returns one of the following major error codes:v AZN_S_INVALID_ATTRLIST_HDL

The attribute list is invalid.v AZN_S_INVALID_ATTR_NAME

The attribute list name is invalid.v AZN_S_INVALID_POBJ

The protected object value is NULL.


azn_attrlist_add_entry_ulong()Adds an unsigned long entry to the attribute list.

Syntaxazn_status_tazn_attrlist_add_entry_ulong(azn_attrlist_h_t attr_list,azn_string_t attr_name,azn_ulong_t ulong_value);

ParametersInput




attr_nameIterate name to which the value is to be added.

ulong_valueUlong attribute value to be added.

DescriptionThis function adds a ulong value to the attribute attr_name within the attribute listattr_list. If the attribute attr_name already exists in the list then the value isappended to the existing list of values for attr_name. The values under attr_nameare stored in the order in which they were inserted into the list. There is nochecking performed upon values in the list; therefore duplicate values arepermitted.




The attribute list name is invalid.


azn_attrlist_copy()

Copies a valid attribute list to a new attribute list.

Syntaxazn_attrlist_h_tazn_attrlist_copy(

azn_attrlist_h_t attr_list );

ParametersInput




DescriptionThis function copies an existing attribute list and returns a handle to the newattribute list.

Return ValuesIf unsuccessful, the function will return AZN_S_INVALID_HANDLE.


azn_attrlist_create()

Creates a valid, empty attribute list, assigns it a handle, and returns the handle.

Syntaxazn_status_tazn_attrlist_create(

azn_attrlist_h_t *new_attr_list );

ParametersOutput

new_attr_listPointer to an azn_attrlist_h_t variable that will contain the handle to thenew attribute list upon successful completion.

DescriptionThis function creates a new and empty attribute list, assigns it a handlenew_attr_list, and returns a pointer to the handle.

Note: Alternatively, you can declare a new attribute list handle and initialize it toAZN_C_INVALID_HANDLE before using it. However, use ofazn_attrlist_create() is recommended.

When new_attr_list is no longer needed, its storage should be released by callingazn_attrlist_delete().




Attribute list handle is invalid.v AZN_S_FAILURE

An error or failure has occurred. Use azn_error_minor() to derive specific minorerror codes from the returned status code.


azn_attrlist_delete()

Deletes the attribute list associated with the attribute list handle.

Syntaxazn_status_tazn_attrlist_delete(

azn_attrlist_h_t *old_attr_list );

ParametersInput

old_attr_listPointer to the attribute list handle for the attribute list to be deleted. Theattribute list handle can be one of the following:v An attribute list handle for a new, empty attribute list, which has been



DescriptionThis function deletes the attribute list associated with the handle old_attr_list. Thisfunction will set the input attribute list handle to an invalid value to ensure that itcannot be used in future functions.







azn_attrlist_delete_entry()

Deletes the specified attribute associated with the attribute list handle.

Syntaxazn_status_tazn_attrlist_delete_entry(

azn_attrlist_h_t attr_list,azn_string_t attr_name);

ParametersInput

attr_listHandle to an attribute list. The attribute list handle should be a handle for anexisting, non-empty attribute list which contains valid data.

attr_nameThe name of an attribute contained within the attribute list that is referencedby attr_list.

DescriptionThis function deletes the specified attribute attr_name from the attribute listassociated with the handle attr_list.







azn_attrlist_get_entry_buffer_value()

Returns a single specified value attribute for a name attribute that has multiplevalues that are contained in buffers.

Syntaxazn_status_tazn_attrlist_get_entry_buffer_value(

azn_attrlist_h_t attr_list,azn_string_t attr_name,unsigned int value_index,azn_buffer_t *buffer_value

);

ParametersInput


attr_nameName attribute of the entry from which the value attribute is to be returned.

value_indexIndex within the entry of the value attribute to be returned.

Output

buffer_valuePointer to an azn_buffer_t variable that will contain the address of the bufferdata upon successful completion of the routine.

DescriptionThis function returns one buffer-type value attribute in buffer_value. The returnedvalue attribute is the one at position value_index within the entry whose nameattribute is specified by attr_name. The first value attribute for any particular nameattribute within an attribute list has index 0.

When buffer_value is no longer needed, its storage should be released by callingazn_release_buffer().


If the returned status code is not equal to AZN_S_COMPLETE, the major errorcodes will be derived from the returned status code with azn_major_error().v AZN_S_COMPLETE



Attribute name is invalid.v AZN_S_INVALID_BUFFER_REF


Buffer reference is not valid.v AZN_S_ATTR_VALUE_NOT_BUFFER_TYPE

The value attributes of this entry are not of type buffer.v AZN_S_ATTR_INVALID_INDEX

Index is not valid (no value exists for this index).v AZN_S_FAILURE



azn_attrlist_get_entry_pobj_value()Returns a single specified value attribute for a name attribute that has one or morevalues that contain protected object information.

Syntaxazn_status_tazn_attrlist_get_entry_pobj_value(azn_attrlist_h_t attr_list,azn_string_t attr_name,unsigned int value_index,azn_pobj_t *pobj_value);

ParametersInput


attr_nameName of the attribute from which the value needs to be returned.

value_indexIndex within the entry of the value attribute to be returned

Output

pobj_valuePointer to an azn_pobj_t variable that will contain the address of the protectedobject information upon successful completion of the routine.

DescriptionReturns a single specified value attribute for a name attribute that has one or morevalues that contain protected object information.

Return ValuesWhen successful, the function returns AZN_S_COMPLETE



The attribute name is NULL, or the attribute name is not found.v AZN_S_INVALID_INDEX

The index value_index is invalid.v AZN_S_INVALID_POBJ_REF

The pobj_value pointer is NULL.v AZN_S_ATTR_VALUE_NOT_POBJ_TYPE

The value type at the specified index is not of type pobj.


azn_attrlist_get_entry_string_value()

Returns a single specified value attribute for a name attribute that has multiplevalues that are strings.

Syntaxazn_status_tazn_attrlist_get_entry_string_value(

azn_attrlist_h_t attr_list,azn_string_t attr_name,unsigned int value_index,azn_string_t *string_value);

ParametersInput



value_indexIndex within the entry of the value attribute to be returned

Output

string_valuePointer to an azn_string_t variable that will contain the string data uponsuccessful completion of the routine.

DescriptionThis function returns one string-type value attribute in string_value. The returnedvalue attribute is the one at position value_index within the set of value attributesbelonging to the name attribute that is specified by attr_name. The first valueattribute for a specified name attribute within an attribute list has index 0.

When string_value is no longer needed, call azn_release_string() to release itsstorage.





Attribute name is invalid.v AZN_S_INVALID_STRING_REF

String reference is invalid.


v AZN_S_ATTR_VALUE_NOT_STRING_TYPEValue attributes of this entry are not of type string.

v AZN_S_ATTR_INVALID_INDEXIndex is invalid (no value exists for this index).

v AZN_S_FAILUREAn error or failure has occurred. Use azn_error_minor() to derive specific minorerror codes from the returned status code.


azn_attrlist_get_entry_ulong_value()

Returns a single specified value for a name attribute that has one or more valuesthat are of type unsigned long.

Syntaxazn_status_tazn_attrlist_get_entry_ulong_value(

azn_attrlist_h_t attr_list,azn_string_t attr_name,unsigned int value_index,azn_ulong_t *ulong_value);

ParametersInput



value_indexIndex within the entry of the value attribute to be returned.

Output

ulong_valuePointer to an unsigned long variable that holds the value of the returnedattribute.

DescriptionReturns a single specified value for a name attribute that has one or more valuesthat are of type unsigned long.


When the returned status code is not equal to AZN_S_COMPLETE, the major errorcodes are derived from the returned status code with azn_major_error().v AZN_S_INVALID_ATTRLIST_HDL


Attribute name is invalid or the attribute name is not found.v AZN_S_INVALID_INDEX

The variable value_index is not valid.v AZN_S_ATTR_VALUE_NOT_ULONG_TYPE

The value attributes of this entry are not of type ulong.


azn_attrlist_get_names()

Returns the list of all name attributes appearing in entries of the attribute list.

Syntaxazn_status_tazn_attrlist_get_names(

azn_attrlist_h_t attr_list,azn_string_t *attr_names[]);

ParametersInput


Output

attr_namesPointer to an array of NULL-terminated strings that hold the returned list ofname attributes. The last entry in the array is denoted by a NULL azn_string_t.

DescriptionThis function returns a list of names attributes as an array of NULL terminatedstrings. When the attr_names array is no longer required, call azn_release_strings()to release its storage.




Attribute list handle is invalid.v AZN_S_INVALID_STRING_REF

String reference is invalid.v AZN_S_FAILURE



azn_attrlist_name_get_num()

Returns the number of value attributes for a specified name attribute in a specifiedattribute list.

Syntaxazn_status_tazn_attrlist_name_get_num(

azn_attrlist_h_t attr_list,azn_string_t attr_name,unsigned int *num_values);

DescriptionInput


attr_nameName attribute for the entry whose number of value attributes is to bereturned.

Output

num_valuesPointer to an integer through which the number of value attributes (in theentry whose name attribute is specified by attr_name) is returned.

DescriptionThis function returns the number of value attributes for a specified name attributein a specified attribute list.





Attribute name is invalid.v AZN_S_INVALID_INTEGER_REF

Integer reference is invalid.v AZN_S_FAILURE



azn_creds_combine()

Combines two authorization credentials chains and a returns a pointer to a handleto the resulting combined credentials chain.

Syntaxazn_status_tazn_creds_combine(

azn_creds_h_t creds,azn_creds_h_t creds_to_add,azn_creds_h_t *combined_creds);

ParametersInput

credsHandle to an credentials chain whose first indexed entry is the credential ofthe initiator of the request. The credential handle should be a handle for anexisting, non-empty credential which contains valid data.

creds_to_addHandle to the credentials chain to be appended to creds. The credential handleshould be a handle for an existing, non-empty credential which contains validdata.

Output

combined_credsPointer to a handle to the returned new credentials chain, which consists of thecredentials chain referenced by creds followed by the credentials chainreferenced by creds_to_add.

The credential handle can be one of the following:v A credential handle for a new, valid, empty credential.v A credential handle initialized to AZN_C_INVALID_HANDLE.

DescriptionThis function takes a credential handle creds_to_add, which refers to a credentialschain, and adds it to the end of a chain of one or more credentials, which arereferenced by the credential handle creds. The credentials chain referenced by credsmust contain as its first indexed credential the credentials of the initiator. Thecredentials chain referenced by creds might also contain the (previously combined)credentials of one or more of the initiator’s proxies. A handle to the combinedcredentials is returned through combined_creds.

The input credential handles and the credentials chains to which they refer are notmodified in any way by this call. Later changes to these structures, including thereleasing of their storage, will have no effect on combined_creds.

Note: When declaring a new credential handle, always initialize it toAZN_C_INVALID_HANDLE before using it.




Successful completion.v AZN_S_API_UNINITIALIZED

This function has been called before azn_initialize().v AZN_S_INVALID_CREDS_HDL

Handle passed as creds is invalid.v AZN_S_INVALID_ADDED_CREDS_HDL

Credentials handle passed as creds_to_add is invalid.v AZN_S_INVALID_COMB_CREDS_HDL

Credentials handle passed as combined_creds is invalid.v AZN_S_UNIMPLEMENTED_FUNCTION

This function is not supported by the implementation.v AZN_S_FAILURE

An error or failure has occurred. Use azn_error_minor() to derive specific minorerror codes from the returned status code.The minor error code ivacl_s_unauthorized is returned when the caller is notauthorized to use this function. Authorization might fail because the caller doesnot belong to the correct group for the Authorization API mode (remote orlocal), or because of issues specific to the authentication mechanism.See pdbaclmsg.h for a complete list of minor error codes that describe accesscontrol problems.


azn_creds_copy()

Creates a reference copy of the target credential.

Syntaxazn_creds_h_tazn_creds_copy(

const azn_creds_h_t creds);

ParametersInput

credsHandle to a credential. The handle can be one of the following:v A credential handle for a new, empty credential, which has been initialized

by a call to azn_creds_create().v A handle for an existing, non-empty credential which contains valid data.

DescriptionThis function creates a reference copy of the target credential. This function doesnot make a new copy of the original credential. It creates a duplicate credentialshandle to the original credential. Use azn_id_get_creds() to create an entirely newcopy of a credential.

Return ValuesIf unsuccessful, the function will return AZN_S_INVALID_HANDLE. Otherwise itwill return another handle to the credential creds.


azn_creds_create()

Creates a new, empty credentials chain, assigns it a handle, and returns a pointerto the handle.

Syntaxazn_status_tazn_creds_create(

azn_creds_h_t *creds);

ParametersOutput

credsA pointer to an azn_creds_h_t variable that will contain the handle to the newcredential chain upon successful completion.

DescriptionThis function creates a new, empty credentials chain, assigns it a handle, andreturns a pointer to the handle.

Note: Alternatively, you can declare a new credentials handle and initialize it toAZN_C_INVALID_HANDLE before using it. However, use ofazn_creds_create() is recommended.

When creds is no longer required, call azn_creds_delete() to release its storage.





The credentials handle supplied is invalid.v AZN_S_FAILURE



azn_creds_delete()

Deletes the credentials chain associated with the credential handle.

Syntaxazn_status_tazn_creds_delete(

azn_creds_h_t *creds);

ParametersInput

credsPointer to the credential handle for the credential chain to be deleted. Thehandle should be a handle for an existing, non-empty credentials chain whichcontains valid data.

Output

credsNULL pointer to a credentials handle that is invalid upon return.

DescriptionThis function deletes the credentials chain associated with the handle creds. Thisfunction sets the input credentials handle to an invalid value to ensure that itcannot be used in future functions.





The credentials handle supplied is invalid.v AZN_S_FAILURE



azn_creds_equal()

Compares the contents of two credentials.

Syntaxazn_status_tazn_creds_equal(const azn_creds_h_t cred1,const azn_creds_h_t cred2,azn_boolean_t *is_equal);

ParametersInput

cred1Handle to a credential. The credential handle should be a handle for anexisting, non-empty credential which contains valid data.

cred2Handle to a credential. The credential handle should be a handle for anexisting, non-empty credential which contains valid data.

Output

is_equalA pointer to an azn_boolean_t variable that will receive the boolean result ofthis call. azn_creds_equal() returns a boolean value of true or false, indicatingif the two compared credentials are equal. This value is true when thecredentials are equal, and false when the credentials are not equal.

DescriptionThis function compares the contents of two credentials. The function returns truewhen the credentials are identical and false when the credentials differ. The valueis returned in the output parameter is_equal.

Return ValuesIf the returned status code is not equal to AZN_S_COMPLETE, the major errorcodes will be derived from the returned status code with azn_error_major().v AZN_S_COMPLETE



Handle passed as cred1 or cred 2 is invalid.v AZN_S_FAILURE

An error or failure has occurred. Use azn_error_minor() to derive specific minorerror codes from the returned status code.The minor error code ivacl_s_unauthorized is returned when the caller is notauthorized to use this function. Authorization might fail because the caller doesnot belong to the correct group for the Authorization API mode (remote orlocal), or because of issues specific to the authentication mechanism.


azn_creds_for_subject()

Returns a pointer to a handle to a credentials chain. The handle is used to extractan individual credentials chain from a longer chain containing the combinedcredentials chains of several subjects.

Syntaxazn_status_tazn_creds_for_subject(

azn_creds_h_t creds,unsigned int subject_index,azn_creds_h_t *new_creds);

ParametersInput

credsHandle to a credentials structure representing the combined credentials chainof several subjects. The combined credentials chain contains a list of 1 or moreindividual credentials chains. When this function returns, the structure referredto by creds is unchanged.

The credentials handle should be a handle for an existing, non-emptycredentials chain which contains valid data.

subject_indexIndex of the requested individual credentials chain within the combinedcredentials chain. The index of the first credentials chain in the combinedcredentials chain, which should be that of the initiator, is zero (0).

Output

new_credsPointer to the handle to the new credentials structure that is returned.

DescriptionThis function returns a handle, new_creds, to a credentials chain for the individualcredential at index subject_index within the credentials chain creds. The chain credscontains the combined credentials of several subjects.

This function does not modify the input handle creds and the credentials chain towhich it refers. Later changes to this structure, including the release of its storage,have no effect on new_creds.

Combined credentials chains are created by azn_creds_combine(). The firstcredential chain in a combined credentials chain is that of the initiator, and itsindex is zero (0). Callers can retrieve the credentials of the initiator by passing theconstant AZN_C_INITIATOR_INDEX as the value of subject_index.


When new_creds is no longer required, use azn_creds_delete() to release its storage.

Use azn_creds_num_of_subjects() to determine the total number of credentialschains in a combined credentials chain.


Return ValuesIf successful, the function will returns AZN_S_COMPLETE.




The credentials handle supplied as creds is invalid.v AZN_S_INVALID_NEW_CREDS_HDL

The pointer to the new credentials handle supplied as new_creds is invalid.v AZN_S_INVALID_SUBJECT_INDEX

The supplied index is invalid.v AZN_S_UNIMPLEMENTED_FUNCTION


An error or failure has occurred. Use azn_error_minor() to derive specific minorerror codes from the returned status code. The minor error codeivacl_s_unauthorized is returned when the caller is not authorized to use thisfunction. Authorization might fail because the caller does not belong to thecorrect group for the Authorization API mode (remote or local), or because ofissues specific to the authentication mechanism. See pdbaclmsg.h for a completelist of minor error codes that describe access control problems.


azn_creds_get_attr_value_string()Obtains the string value of the specified attribute in the specified credential

Syntaxazn_status_tazn_creds_get_attr_value_string(

azn_creds_h_t creds,unsigned int subject_index,azn_string_t attr_name,azn_string_t *attr_value

);

ParametersInput

credsHandle to a credential list.


subject_indexThe index of the specified credential with the credential chain for which theattribute value is to be retrieved.

attr_nameThe attribute name.

Output

attr_valuePointer to an azn_string_t variable that will contain the address of theattribute string value upon successful completion of the routine.

DescriptionThis function retrieves attribute values from a user credential. This functionaccesses the attribute list of the specified credential directly and gets the stringvalue of the specified attribute from it.


When the returned status code is not equal to AZN_S_COMPLETE, the major errorcodes will be derived from the returned status code with azn_error_major().v AZN_S_INVALID_STRING_REF

The specified attribute name is invalid.v AZN_S_INVALID_CREDS_HDL

The specified credentials handle is invalid.v AZN_S_INVALID_SUBJECT_INDEX

The index into the credentials chain is invalid.


azn_creds_get_attrlist_for_subject()

Returns information from a specified subject’s credentials chain within a specified(and possibly combined) credentials chain.

Syntaxazn_status_tazn_creds_get_attrlist_for_subject (

azn_creds_h_t creds,unsigned int subject_index,azn_attrlist_h_t *creds_attrlist);

ParametersInput

credsHandle to a credentials chain.


subject_indexIndex of the requested individual subject within the credentials chain. Theindex of the first credential in the combined credentials chain, which should bethat of the initiator, is zero (0).

Output

creds_attrlistPointer to the handle of an attribute list that holds the specified subject’sattribute information on return. The attribute list handle can be one of thefollowing:v An attribute list handle that has been initialized to

AZN_C_INVALID_HANDLE.v An attribute list handle for a new, empty attribute list, which has been


contains valid data. In this case, attribute list data is appended to theexisting attribute list.

DescriptionThis function returns an attribute list containing privilege attribute informationfrom the credentials chain for the individual subject at index subject_index within acredentials chain creds.

Combined credentials chains are created by azn_creds_combine(). The firstcredential chain in a combined credentials chain is that of the initiator, and itsindex will be zero (0). Callers can retrieve the attributes of the credentials chain ofthe initiator by passing the constant AZN_C_INITIATOR_INDEX as the value ofsubject_index.

This function does not modify the input handle creds and the credentials chain towhich it refers. Later changes to creds, including releasing its storage, will have noeffect on creds_attrlist.


Use the azn_attrlist* functions to retrieve individual attribute values fromcreds_attrlist. See ogauthzn.h for a list of attribute names.

The audit identifier associated with the specified credentials structure is present inthe returned attribute list. It is the value attribute of an entry whose name attributeis AZN_C_AUDIT_ID.

Note: When declaring a new credential handle or attribute list handle alwaysinitialize it to AZN_C_INVALID_HANDLE before using it.

When creds_attrlist is no longer required, call azn_attrlist_delete() to release itsstorage.





The credentials handle supplied is invalid.v AZN_S_INVALID_SUBJECT_INDEX

The supplied index is invalid.v AZN_S_INVALID_ATTRLIST_HDL

The attribute list handle supplied is invalid.v AZN_S_UNIMPLEMENTED_FUNCTION




azn_creds_get_pac()

Creates and returns a privilege attribute certificate (PAC) by invoking a specifiedPAC service on the supplied credentials chain.

Syntaxazn_status_tazn_creds_get_pac(

azn_creds_h_t creds,azn_string_t pac_svc_id,azn_buffer_t *pac);

ParametersInput

credsHandle to the credentials chain whose information is used to build the PAC.


pac_svc_idIdentification (id) of the PAC service that produces the PAC.

Output

pacPointer to an azn_buffer_t variable that will contain the address of the bufferdata upon successful completion of the routine.

DescriptionThis function uses the PAC service whose identification is supplied as pac_svc_id tobuild a new PAC. The PAC service uses the information in the supplied credentialschain to build the PAC. Different PAC services might produce PACs with differentformats. Some PAC services can cryptographically protect or sign the PACs theyproduce.

When pac_svc_id is NULL, the default PAC service returns an architecture-independent and network-independent encoding of the specified credentials chain.This PAC can be safely transmitted. The receiver of the PAC can useazn_pac_get_creds() to decode the PAC and obtain a valid copy of the originalcredentials chain.

This function takes as an input parameter a handle to an existing credentialsstructure, and returns a pointer to the output PAC in an Authorization API buffer.

This function does not modify the input handle creds and the credentials chain towhich it refers. Later changes to creds, including releasing its storage, will have noeffect on pac.

When pac is no longer required, call azn_release_buffer() to release its storage.






The credentials handle supplied is invalid.v AZN_S_INVALID_PAC_SVC

The privilege attribute certificate service identifier is invalid.v AZN_S_SVC_SERVICE_NOT_FOUND

The service with the specified identification number was not found in the list ofconfigured services.

v AZN_S_SVC_AUTHORIZATION_FAILEDThe caller is not authorized to make calls to the service. The minor error codecontains additional information about the reason for the failure.

v AZN_S_SVC_DISPATCHER_FAILUREThe service dispatcher failed. This can be caused by incorrect initialization of theAuthorization API.

v AZN_S_UNIMPLEMENTED_FUNCTIONThis function is not supported by the implementation.

v AZN_S_FAILUREAn error or failure has occurred. Use azn_error_minor() to derive specific minorerror codes from the returned status code.The minor error code ivacl_s_unauthorized is returned when the caller is notauthorized to use this function. Authorization might fail because the caller doesnot belong to the correct group for the Authorization API mode (remote orlocal), or because of issues specific to the authentication mechanism.See pdbaclmsg.h for a complete list of minor error codes that describe accesscontrol problems.


azn_creds_modify()

Modifies an existing credentials chain and returns a pointer to the handle to a newcredentials chain containing the modifications.

Syntaxazn_status_tazn_creds_modify(

azn_creds_h_t creds,azn_string_t mod_svc_id,azn_attrlist_h_t mod_info,azn_creds_h_t *new_creds);

ParametersInput

credsHandle to the authorization credentials chain to be modified.


mod_svc_idIdentification (id) of the credential modification service.

mod_infoAttribute list containing modification service-specific or application-specificdata that describes the desired credential modifications. Attribute lists that areempty are inserted into the credentials. The attribute list handle can be one ofthe following:v An attribute list handle that has been initialized to




Output

new_credsPointer to a handle to a credentials chain that contains the modified credentialschain upon return.The credentials handle can be one of the following:v A credentials handle that has been initialized to

AZN_C_INVALID_HANDLE. Note that this will result in an empty outputcredential.

v A credentials handle for a new, empty credential, which has been initializedby a call to azn_creds_create(). Note that this will result in an emptyoutput credential.

DescriptionThis function uses the specified modification service mod_svc_id, and optionally anattribute list mod_info which contains modification information provided by thecaller, to modify a copy of the supplied credentials chain creds. The functionreturns a pointer to a handle to a new credentials chain new_creds containing therequested modifications. The supplied credentials chain is unchanged.


When mod_svc_id is NULL, this function modifies an existing credential chain credsby adding the attribute list mod_info to the credentials chain, and returning themodified credential in new_creds.

The following credential attributes are considered readonly and must not bemodified:v azn_cred_principal_uuidv azn_cred_principal_namev azn_cred_versionv azn_cred_mech_idv azn_cred_group_uuidsv azn_cred_group_namesv azn_cred_authzn_id

If the input creds handle references a combined credentials chain with more thanone element, only the first element will be modified. This is the default behaviorwhen mod_svc_id is NULL. In this case, the output chain consists of the modifiedfirst element followed by unmodified copies of the remaining elements in the inputcombined credentials chains. The elements in the output credentials chain are keptin the same order as their counterparts in the input credentials chain.


When new_creds is no longer required, call azn_creds_delete() to release its storage.





The credentials handle supplied is invalid.v AZN_S_ INVALID_MOD_FUNCTION

The supplied modification service identifier is invalid.v AZN_S_INVALID_ATTRLIST_HDL

The attribute list handle is invalid.v AZN_S_INVALID_NEW_CREDS_HDL

The pointer to the new credentials handle that references the new outputcredentials chain is invalid.


v AZN_S_SVC_SERVICE_NOT_FOUNDThe service with the specified identification number was not found in the list ofconfigured services.




v AZN_S_ATTR_READONLYModification of the attribute is prohibited.



azn_creds_num_of_subjects()

Returns the number of individual subjects’ credentials chains in a combinedcredentials chain.

Syntaxazn_status_tazn_creds_num_of_subjects(

azn_creds_h_t creds,unsigned int *num_of_subjects);

ParametersInput

credsHandle to a credentials chain.


Output

num_of_subjectsPointer to an unsigned int variable that will contain the number of individualcredentials within the credential chain upon successful completion of theroutine. Note that if the credentials handle passed in as an input parameter isinvalid (AZN_C_INVALID_HANDLE) or points to an empty credentials list, anerror will be generated and num_of_subjects will be set to 0.

DescriptionThis function returns the number of individual subjects, num_of_subjects, whosecredentials appear in a credentials chain creds. Combined credentials chains arecreated by the azn_creds_combine() function.





The credentials handle supplied is invalid.v AZN_S_ATTR_INVALID_INTEGER_REF

The integer reference is invalid.v AZN_S_UNIMPLEMENTED_FUNCTION




The minor error code ivacl_s_unauthorized is returned when the caller is notauthorized to use this function. Authorization might fail because the caller doesnot belong to the correct group for the Authorization API mode (remote orlocal), or because of issues specific to the authentication mechanism.See pdbaclmsg.h for a complete list of minor error codes that describe accesscontrol problems.


azn_creds_set_attr_value_string()Sets the value of the specified attribute in the specified user credential.

Syntaxazn_status_tazn_creds_set_attr_value_string

azn_creds_h_t creds,unsigned int subject_index,azn_string_t attr_name,azn_string_t attr_value

);

ParametersInput

credsHandle to the credentials chain.


subject_indexThe index of the specified credential within the credential chain.

attr_nameThe name of the attribute to be modified.

attr_valueThe string value to be assigned to the attribute.

DescriptionUse this function to modify the attribute values in a user credential. This functionedits the attribute list of the specified credential and sets the specified attribute tothe specified string value.

The following credential attributes are considered readonly and must not bemodified using this API.v azn_cred_principal_uuidv azn_cred_principal_namev azn_cred_versionv azn_cred_mech_idv azn_cred_group_uuidsv azn_cred_group_namesv azn_cred_authzn_idv azn_cred_ldap_dn


When the returned status code is not equal to AZN_S_COMPLETE, the major errorcodes will be derived from the returned status code with azn_error_major().v AZN_S_INVALID_STRING_VALUE

The specified string value is invalid.v AZN_S_INVALID_CREDS_HDL


The specified credentials handle is invalid.v AZN_S_INVALID_SUBJECT_INDEX

The index into the credentials chain is invalid.v AZN_S_ATTR_READONLY

Modification of the attribute is prohibited.


azn_decision_access_allowed()

Makes an access control decision.

Syntaxazn_status_tazn_decision_access_allowed(

azn_creds_h_t creds,azn_string_t protected_resource,azn_string_t operation,int *permission);

ParametersInput

credsHandle to the initiator’s credential chain.


protected_resourceName of the request’s target.

operationName of the requested operation.

Output

permissionPointer to an integer variable that will contain the appropriate permission codeupon successful completion of the routine.

When the returned status value is AZN_S_COMPLETE, the returnedpermission is either AZN_C_PERMITTED or AZN_C_NOT_PERMITTED.When the returned status code is not AZN_S_COMPLETE, the returnedpermission is set to AZN_C_NOT_PERMITTED.

If additional information beyond a boolean result is needed, useazn_decision_access_allowed_ext().

DescriptionThis function decides whether the initiator specified by credentials creds isauthorized to perform the operation operation on the target protected_resource. Thedecision is returned through permission.

azn_decision_access_allowed() is semantically equivalent toazn_decision_access_allowed_ext() when app_context=NULL andpermission_info=NULL.



Successful completion.


v AZN_S_API_UNINITIALIZEDThis function has been called before azn_initialize().

v AZN_S_INVALID_CREDS_HDLThe credentials handle supplied is invalid.

v AZN_S_INVALID_PROTECTED_RESOURCEThe target name is invalid.

v AZN_S_INVALID_OPERATIONThe operation has no meaning for the specified target.

v AZN_S_INVALID_PERMISSION_REFThe integer reference to return the permission is invalid.




Makes an access control decision using application-specific context information;returns information about why the decision was made.

Syntaxazn_status_tazn_decision_access_allowed_ext(

azn_creds_h_t creds,azn_string_t protected_resource,azn_string_t operation,azn_attrlist_h_t app_context,int *permission,azn_attrlist_h_t *permission_info);

ParametersInput

credsHandle to the initiator’s credentials chain.


protected_resourceName of the target of the request.

operationName of the requested operation.

app_contextAttribute list containing application-specific context access control information.A NULL value indicates there is no context access control information. Theattribute list handle can be one of the following:v An attribute list handle that has been initialized to




permission_infoPointer to an attribute list through which the implementation might returnimplementation-specific information about the decision. If a NULL value ispassed as input, then no information will be returned.

Output

permissionPointer to an integer variable that will contain the appropriate permission codeupon successful completion of the routine.

When the returned status value is AZN_S_COMPLETE, the returnedpermission is either AZN_C_PERMITTED or AZN_C_NOT_PERMITTED.When the returned status code is not AZN_S_COMPLETE, the returnedpermission is set to AZN_C_NOT_PERMITTED.


permission_infoPointer to an attribute list through which the implementation can returnimplementation-specific information about the decision. When a NULL pointeris passed as input, no information is returned.

The information contained in the attribute list is added to the list when theattribute list handle is one of the following:v An attribute list handle for a new, empty attribute list, which has been



The output parameter permission_info can be used to returnimplementation-specific qualifiers to AZN_C_NOT_PERMITTED. The qualifierscan be used to assist the calling application or the initiator in formulating arequest which will be authorized. Examples of such qualifiers might include:“not permitted yet,” “requires additional privilege attributes,” or “permissiblewith restrictions.”

For more information, see “Enabling the return of permission information” onpage 28.

DescriptionThis function decides whether the initiator specified by the credentials chain credsis authorized to perform the operation operation on the target protected_resource.Optionally, callers can supply application-specific context access controlinformation using the app_context argument. The decision is returned throughpermission.

Optionally, the implementation can return implementation-specific informationabout the decision through permission_info. For example, the information canindicate which rule was responsible for granting or denying access.






The credentials handle supplied is invalid.v AZN_S_INVALID_PROTECTED_RESOURCE

The target name is invalid.v AZN_S_INVALID_OPERATION

The operation has no meaning for the specified target.v AZN_S_INVALID_PERMISSION_REF


The integer reference to return the permission is invalid.v AZN_S_INVALID_APP_CONTEXT_HDL

The attribute list handle for the context access control information (ACI) isinvalid.

v AZN_S_INVALID_ATTRLIST_HDLThe attribute list handle for the returned permission information is invalid.




azn_entitlement_get_entitlements()

Returns entitlements of an initiator

Syntaxazn_status_tazn_entitlement_get_entitlements(

azn_creds_h_t creds,azn_string_t entitlements_svc_id,azn_attrlist_h_t app_context,azn_attrlist_h_t *entitlements

);

ParametersInput

credsHandle to the credentials of the subject whose entitlements are to be returned.


entitlements_svc_idThe id of the entitlements service to be used

app_contextHandle to an attribute list containing application-specific orentitlements-service-specific context information. A NULL value should beused if no application state is passed.The attribute list handle can be one of thefollowing:v An attribute list handle that has been initialized to




Output

entitlementsPointer to a attribute list handle variable which will hold the entitlementinformation on return.

The handle can be one of the following:v A attribute list handle that has been initialized to

AZN_C_INVALID_HANDLE.v A attribute list handle for a new, empty attribute list, which has been



DescriptionThis uses an entitlements service identified by entitlements_svc_id to return theentitlements of an initiator identified by credentials creds. The calling application


may pass application-specific or entitlements-service-specific context data using anattribute list app_context. The entitlements are returned using the attribute listentitlements.


The constants AZN_C_REQUEST_TIME, AZN_C_AUTHN_QUALITY,AZN_C_REQUESTER_LOC, and AZN_C_REQUEST_ROUTE_QOP, may be used asname attribute of entries in the app_context attribute list to communicate commontypes of context information.

Return ValuesIf successful, the function returns AZN_S_COMPLETE.

If the returned status code is not equal to AZN_S_COMPLETE, the major errorcodes can be derived from the returned status code with azn_error_major().v AZN_S_COMPLETE

Successful completion.v AZN_S_INVALID_CREDS_HDL

The creds handle supplied is invalid.v AZN_S_INVALID_ENTITLEMENT_SVC

The entitlements service identifier is invalid.v AZN_S_INVALID_APP_CONTEXT_HDL

The attribute list handle for the application context is invalid.v AZN_S_INVALID_ENTITLEMENTS_HDL

The attribute list handle for the entitlements is invalid.v AZN_S_AUTHORIZATION_FAILURE

The caller does not possess the authority required to invoke this function.v AZN_S_UNIMPLEMENTED_FUNCTION


An implementation specific error or failure has occurred. Implementationspecific minor error codes can be derived from the returned status code withazn_error_minor().


azn_error_get_string()Returns the Policy Director Serviceability message string for the specified datastructure of type azn_status_t.

Syntaxazn_status_t azn_error_get_string(azn_status_t aznstatus,azn_string_t *error_string,)

ParametersInput

aznstatusAuthorization API status

Output

error_stringPointer to an azn_string_t variable that will contain the error string uponsuccessful completion of the routine.

DescriptionThis interface returns the Policy Director Serviceability (PDSVC) message string forthe Authorization API status that is passed in. It returns the message string for theminor error code if one exists. When a minor error code does not exist, it returnsthe message string for the major error code.


When unsuccessful, the function returns one of the following major error codes:v AZN_S_INVALID_MAJOR_CODE

The major error code is invalid.v AZN_S_MAJOR_CODE_MESSAGE_NOT_FOUND

There is no message in the message table for the major error code.v AZN_S_MINOR_CODE_MESSAGE_NOT_FOUND

The minor error code is invalid. Alternately, this error message can mean thatthere is no message in the message table for the minor error code.

v AZN_S_INVALID_STRING_REFThe pointer of type error_string is NULL.


azn_error_major()

Returns the major error code that is associated with a returned status code.

Syntaxunsigned intazn_error_major(

azn_status_t status_code);

ParametersInput

status_codePreviously returned status code by any of the azn_* routines.

DescriptionThis function returns the major error code associated with a previously returnedstatus code.

Return ValuesAny of the defined major error codes, AZN_S_*. For a list of error codes, seeogauthzn.h and aznutils.h.


azn_error_minor()

Returns the implementation-specific minor error code that is associated with areturned status code.

Syntaxunsigned intazn_error_minor(

azn_status_t status_code);

ParametersInput

status_codePreviously returned status code by any of the azn_* routines.

DescriptionThe function returns the minor error code associated with a previously returnedstatus code.

Return ValuesAn implementation specific minor error code is returned. For a complete list ofminor error codes, see the file pdbaclmsg.h.


azn_error_minor_get_string()

Returns a string describing the implementation-specific minor error code.

Syntaxazn_status_tazn_error_minor_get_string(

unsigned int minor_errorazn_string_t *minor_error_string

);

ParametersInput

minor_errorMinor error code previously returned by azn_error_minor().

Output

minor_error_stringPointer to an azn_string_t variable that will contain the minor error stringupon successful completion of the routine.

DescriptionThis function returns a string that describes the error corresponding to apreviously returned minor error status code. When minor_error_string is no longerneeded, use azn_release_string() to release its storage.



Successful completion.v AZN_S_MINOR_CODE_MESSAGE_NOT_FOUND

The specified minor code has not corresponding error message in the catalog.This message also appears when a minor code of 0 (success) is passed.

v AZN_S_INVALID_STRING_REFThe minor error string is NULL.


azn_id_get_creds()

Returns a handle to the credentials chain associated by a specified authorizationauthority with a specified identity.

Syntaxazn_status_tazn_id_get_creds(

azn_string_t authority,azn_string_t mechanism_id,azn_buffer_t mechanism_info,azn_creds_h_t *new_creds);

ParametersInput

authorityIdentification (id) of the authorization authority to be used to build thecredential. The only valid input value is the default value of NULL.

mechanism_idAuthentication mechanism that is used to generate the identity passed throughmechanism_info. A NULL input value selects a default authenticationmechanism.

mechanism_infoBuffer containing initiator access control information, which consists of identityinformation obtained from an authentication service. The authentication serviceused to produce this information should be identified using the mechanism_idargument. A NULL input value denotes the default identity for the selectedauthentication mechanism from the environment.

Output

new_credsPointer to the handle of a new, empty credentials chain that will hold thereturned credentials.

The handle can be one of the following:v A credentials handle that has been initialized to

AZN_C_INVALID_HANDLE.v A credentials handle for a new, empty credentials list, which has been

initialized by a call to azn_attrlist_create(). In this case, the handle isupdated.

v A credentials handle for an existing, non-empty credentials list whichcontains valid data. In this case, the handle is updated.

DescriptionThis function builds an authorization credentials chain, referenced by the returnedhandle new_creds, for the identity corresponding to the initiator access controlinformation mechanism_info produced by an authentication mechanismmechanism_id.

Specifying a NULL value for authority causes the default authority to be used. Thedefault authority is Policy Director, which is the only authority supported by thisrelease of the Policy Director Authorization API.


Specifying NULL values for mechanism_id and causes the default authenticationmechanism to be the installed user registry in the Policy Director secure domain.For more information, see “Default user registry information structure” on page 10.




This function has been called before azn_initialize().v AZN_S_INVALID_AUTHORITY

The authorization authority identification (id) is invalid.v AZN_S_INVALID_MECHANISM

The security mechanism identification (id) is not supported by the selectedauthorization authority.

v AZN_S_INVALID_MECHANISM_INFOThe security mechanism information is invalid.

v AZN_S_INVALID_NEW_CREDS_HDLThe credentials handle supplied for the new credentials chain is invalid.

v AZN_S_FAILUREAn error or failure has occurred. Use azn_error_minor() to derive specific minorerror codes from the returned status code.The minor error code ivacl_s_unauthorized is returned when the caller is notauthorized to use this function. Authorization might fail because the caller doesnot belong to the correct group for the Authorization API mode (remote orlocal), or because of issues specific to the authentication mechanism. Seepdbaclmsg.h for a complete list of minor error codes that describe access controlproblems.


azn_initialize()

Initializes the authorization service.

Syntaxazn_status_tazn_initialize(

azn_attrlist_h_t init_data,azn_attrlist_h_t *init_info);

ParametersInput

init_dataHandle to an attribute list containing implementation-specific initializationdata.


Output

init_infoPointer to a handle to an attribute list through which implementation-specificinformation is returned from initialization.

The handle can be one of the following:v A attribute list handle that has been initialized to

AZN_C_INVALID_HANDLE.v A attribute list handle for a new, empty attribute list, which has been

initialized by a call to azn_attrlist_create().v A credentials handle for an existing, non-empty attribute list which contains

valid data.

DescriptionThis function must be called before calling most other Authorization API functions.The exceptions to this rule are the attribute list functions (azn_attrlist_*) and theerror handling functions (azn_error_*).

Upon return from this call, the attribute list referenced by init_info contains theAuthorization API version number, which is returned as the value for the attributeAZN_C_VERSION.

When init_info is no longer required, use azn_attrlist_delete() to release itsstorage.

When using this function on Windows NT, do not call it from dllMain(). Thefunction dllMain() is run as one thread, which prevents azn_initialize() fromspawning other threads. When programming in C++ on Windows NT, do not callazn_initialize() from a global or statically defined class constructor becausethese constructors are run from dllMain().


Return ValuesIf successful, the function will return AZN_S_COMPLETE. If the returned statuscode is not equal to AZN_S_COMPLETE, the major error codes will be derivedfrom the returned status code with azn_error_major().v AZN_S_COMPLETE

Successful completion.v AZN_S_API_ALREADY_INITIALIZED

azn_initialize() has been called twice without an intervening call toazn_shutdown().

v AZN_S_CONFIG_INVALID_LISTENING_PORTAn Administration Service plug-in was registered but no ssl-listening-port wasspecified.

v AZN_S_INVALID_INIT_DATA_HDLThe attribute list handle for the initialization information is invalid.

v AZN_S_INVALID_INIT_INFO_HDLThe attribute list handle for the output initialization information is invalid.

v AZN_S_SVC_DEFINITION_ERRORA service has been defined incorrectly. The error condition is caused either byinvalid entries in the service definition attributes that are passed as input toazn_initialize(), or by invalid entries in the configuration file.

v AZN_S_SVC_INIT_FAILEDA service failed to initialize correctly. The minor error code contains additionalinformation about the reason for the failure.


v AZN_S_SVC_DLL_LOAD_FAILEDThe DLL for a service failed to load correctly

v AZN_S_SVC_INITIALIZE_NOT_FOUNDThe azn_service_initialize() interface was not found in the DLL module for aservice.

v AZN_S_SVC_SHUTDOWN_NOT_FOUNDThe azn_service_shutdown() interface was not found in the DLL module for aservice.

v AZN_S_SVC_ENT_FUNC_NOT_FOUNDThe azn_entitlement_get_entitlements() interface was not found in the DLLmodule for an entitlements service.

v AZN_S_SVC_PAC_FUNC_NOT_FOUNDThe azn_pac_get_creds() or azn_creds_get_pac() interface was not found in theDLL module for a PAC service.

v AZN_S_SVC_CRED_MOD_FUNC_NOT_FOUNDThe azn_creds_modify() interface was not found in the DLL module for acredentials modification service.

v AZN_S_SVC_SERVICE_IS_REGISTEREDThe service ID cannot be registered because it is already listed as registered bythe Service Dispatcher.

v AZN_S_SVC_DISPATCHER_FAILURE


The service dispatcher failed. This can be caused by incorrect initialization of theAuthorization API.

v AZN_S_SVC_ADMIN_UNKNOWN_PARAMETERThe service definition for the Administration Service plug-in contained aninvalid parameter.

v AZN_S_SVC_ADMIN_POBJ_NOT_SPECIFIEDThe Administration Service plug-in definition specified the -pboj parameter butfailed to specify the name of the protected object hierarchy.

v AZN_S_SVC_ADMIN_POBJ_ALREADY_REGISTEREDThe protected object hierarchy name has already been registered by anotherAdministration service definition within this Authorization API application.

v AZN_S_SVC_ADMIN_TASK_FUNC_NOT_FOUNDThe Administration Service plug-in implemented either azn_admin_get_tasklist()or azn_admin_perform_task() but did not implement both interfaces.Administration Service plug-ins must implement either both or none.



azn_pac_get_creds()

Returns a handle to new credentials chain that is derived from a privilege attributecertificate (PAC) by a specified PAC service.

Syntaxazn_status_tazn_pac_get_creds(

azn_buffer_t pac,azn_string_t pac_svc_id,azn_creds_h_t *new_creds);

ParametersInput

pacBuffer structure that holds the supplied PAC.

pac_svc_idIdentification (id) of the PAC service that produces the credentials chain.

Output

new_credsPointer to a handle to the returned credentials chain.

The handle can be one of the following:v A credentials handle that has been initialized to

AZN_C_INVALID_HANDLE.v A credentials handle for a new, empty credential, which has been initialized

by a call to azn_creds_create(). In this case, the handle is updated(overwritten) with new credentials.

v A credentials handle for an existing, non-empty credential chain whichcontains valid data. In this case, the handle is updated (overwritten) withnew credentials.

DescriptionThis function uses the identified PAC service (pac_svc_id) to build a newcredentials chain using the information in the supplied PAC (pac). Some PACservices will cryptographically verify the protection or signature on the receivedPAC, and will return an error if the PAC cannot be verified.

This function decodes PACs that are built by azn_creds_get_pac().




This function has been called before azn_initialize().v AZN_S_INVALID_PAC


The PAC is invalid or could not be verified by the PAC service.v AZN_S_INVALID_PAC_SVC

The id of the PAC service is invalid.v AZN_S_INVALID_NEW_CREDS_HDL

The credentials handle supplied for new_creds is invalid.v AZN_S_UNIMPLEMENTED_FUNCTION

This function is not supported by the implementation.v AZN_S_SVC_SERVICE_NOT_FOUND

The service with the specified identification number was not found in the list ofconfigured services.





azn_release_buffer()

Frees storage associated with a buffer.

Syntaxazn_status_tazn_release_buffer(

azn_buffer_t *buffer);

ParametersInput

bufferPointer to the buffer whose memory is to be released.

Output

bufferPointer to the buffer whose memory is released. The pointer is set to an invalidvalue upon successful completion.

DescriptionThis function releases the specified azn_buffer_t structure. The input buffer pointeris set to an invalid value to ensure that it cannot be used in future function calls.



Successful completion.v AZN_S_INVALID_BUFFER_REF

The pointer to the buffer is invalid.v AZN_S_FAILURE



azn_release_pobj()Releases storage associated with a protected object data structure.

Syntaxazn_status_tazn_release_pobj(azn_pobj_t pobj);

ParametersInput

pobjPointer to a protected object structure whose storage is to be released.

Output

pobjPointer to a protected object structure whose storage is released. The pointer isset to an invalid value upon successful completion.

DescriptionReleases storage associated with a protected object structure.


If the returned status code is not equal to AZN_S_COMPLETE, the major errorcodes will be derived from the returned status code with azn_error_major().v AZN_S_INVALID_POBJ_REF

The pointer to the protected object is NULL.


azn_release_string()

Frees storage that is associated with a string.

Syntaxazn_status_tazn_release_string(

azn_string_t *string);

ParametersInput

stringPointer to the string to be released.

Output

stringPointer to the string whose memory is released. The pointer is set to an invalidvalue upon successful completion.

DescriptionThis function releases the specified azn_string_t structure. The input stringpointer is set to an invalid value to ensure that it cannot be used in future functioncalls.



Successful completion.v AZN_S_INVALID_STRING_REF

The pointer to the string is invalid.v AZN_S_FAILURE



azn_release_strings()

Frees storage that is associated with an array of strings.

Syntaxazn_status_tazn_release_strings(

azn_string_t *strings[]);

ParametersInput

stringsPointer to the array of azn_string_t structures to be released upon successfulcompletion.

DescriptionThis function releases a NULL-terminated array of azn_string_t structures. Theinput string pointer is set to an invalid value to ensure that it cannot be used infuture function calls.



Successful completion.v AZN_S_INVALID_STRING_REF

Pointer to the array of strings is invalid.v AZN_S_FAILURE



azn_shutdown()

Cleans up internal authorization service state in preparation for shutdown.

Syntaxazn_status_tazn_shutdown();

DescriptionUseazn_shutdown() to clean up the Authorization API’s memory and other internalimplementation state before the application exits. This function shuts down theimplementation state created by azn_initialize().

The only authorization API functions that can be used after calling azn_shutdown(),prior to calling azn_initialize() again, are the attribute list functions(azn_attrlist_*), the error handling functions (azn_error_*), and the memoryrelease functions (azn_*_delete and azn_release_*).




This function has been called before azn_initialize().v AZN_S_SVC_SHUTDOWN_FAILED

A service failed to shutdown correctly. The minor error code contains additionalinformation about the reason for the failure.





azn_util_errcode()

Builds an azn_status_t error code from a major and minor status.

Syntaxazn_status_tazn_util_errcode(

const unsigned int major,const unsigned int minor);

DescriptionBuilds an azn_status_t error code from a major and minor status.

ParametersInput

majorThe major component of the error status.

minorThe minor component of the error status.

Return ValuesReturns complete azn_status_t error code.


azn_util_handle_is_valid()

Determine if the handle references a valid data structure.

Syntaxazn_boolean_tazn_util_handle_is_valid(

long handle);

ParametersInput

handleA handle to an attribute list.

DescriptionThis function determines if the specified handle references a valid data structure.


Return ValuesReturns true if the handle is valid or false if the handle is invalid.


azn_util_password_authenticate()

Performs a login for a user name and password pair, and returns authenticationinformation if the login was successful.

Syntaxazn_status_tazn_util_password_authenticate(

const azn_string_t principal_name,const azn_string_t password,azn_string_t *mechanism_id,azn_buffer_t *authinfo);

ParametersInput

principal_nameName of the user (principal) used to log in. If LDAP authentication is used,this will be a DN string.

passwordPassword for the user.

Output

mechanism_idPointer to a string identifying the authentication mechanism with which theuser is authenticated.

authinfoPointer to a buffer that is loaded with the authentication information that isreturned by a successful login attempt.

DescriptionThis function performs a login for a user name and password pair, and returnsauthentication information when the login is successful.

The authentication mechanism used depends upon the underlying authenticationmechanism that was configured when the Authorization API was installed.

This function does not establish a security context for the application.

The mechanism_id and authinfo returned can be appended with data specific to theprincipal and passed into the azn_id_get_creds() function. The mechanism_idstring is allocated by the utility function and must be freed usingazn_release_string() when no longer needed. The authinfo buffer must be freedusing azn_release_buffer().

Return ValuesReturns AZN_S_COMPLETE on success, or an error code on failure.

The minor error code ivacl_s_unauthorized is returned when the caller is notauthorized to use this function. Authorization might fail because the caller doesnot belong to the correct group for the Authorization API mode (remote or local),or because of issues specific to the authentication mechanism.


Note: When used with Domino or Active Directory, additional error codes can bereturned, in cases where there is more than one error in the inputparameters.

See pdbaclmsg.h for a complete list of minor error codes that describe accesscontrol problems.

When unsuccessful, the following major error codes are returned:v AZN_S_FAILURE

An error has been encountered.v AZN_S_U_INVALID_PASSWORD

The password is not valid.v AZN_S_U_INVALID_PRINC_NAME

The principal name is unknown.v AZN_S_U_LDAP_AUTHEN_FAILED

Authentication to the LDAP user registry failed.v AZN_S_U_URAF_AUTHEN_FAILED

URAF authentication failedv AZN_S_U_PASSWORD_EXPIRED

The user authenticated correctly but the password has expired and must bechanged. Mechanism_id and authinfo are not returned.

v AZN_S_U_ACCOUNT_DISABLED,The account has been disabled by the administrator.

v AZN_S_U_TOD_ACCESS_DENIEDThe login failed due to policy restrictions based on Time of Day.

v AZN_S_U_ACCOUNT_LOCKEDOUTThe account has been locked because too many invalid login attempts have beenmade. The number of invalid attempts and the logout period can be configuredthrough policy.

v AZN_S_U_INSUFFICIENT_ACCESSThe caller of this function has insufficient privileges to perform the requestedoperation.



azn_util_password_change()Changes the password for the specified Access Manager principal in the registry.

Syntaxazn_status_tazn_util_password_change(

const azn_string_t principal_name,const azn_string_t password

);

ParametersInput

principal_nameName of the principal who’s password is to change. When using an LDAPregistry for authentication, this may also be a Distinguished Name (DN) string.

passwordNew password for the principal.

DescriptionChanges the password for a username pair. The method of changing password isselected automatically according to the underlying authentication mechanism withwhich the authorization API was installed. Examples of authentication mechanismsare LDAP, Domino, and Active Directory.

Limitations

This call can succeed even though the calling application (server) lacks sufficientaccess, when used with either Domino or Active Directory authentication.

On Domino, this is because the server uses the local Notes ID file, and hencealways has the authority to change the password.

On Active Directory, the authorization to make this call is taken from the ActiveDirectory system group membership, not from the Access Manager groups. Pleasethe the IBM Tivoli Access Manager Release Notes for a workaround for this limitation.

Return ValuesReturns AZN_S_COMPLETE on success, or an error code on failure.

The minor error code ivacl_s_unauthorized is returned when the caller is notauthorized to use this function. Authorization might fail because the caller doesnot belong to the correct group for the Authorization API mode (remote or local),or because of issues specific to the authentication mechanism.

See pdbaclmsg.h for a complete list of minor error codes that describe accesscontrol problems.

Note: When used with Domino or Active Directory, additional error codes can bereturned, in cases where there is more than one error in the inputparameters.

When unsuccessful, the following major error codes are returned:


v AZN_S_FAILUREv AZN_S_U_ACCOUNT_DISABLED

The user account is disabled by the administrator.v AZN_S_U_ACCOUNT_LOCKEDOUT

The account has been locked because too many invalid login attempts have beenmade. The number of invalid attempts and the logout period can be configuredthrough policy.

v AZN_S_U_INSUFFICIENT_ACCESSThe caller of this function has insufficient privileges to perform the requestedoperation.

v AZN_S_U_INVALID_PASSWORDThe password is not valid.

v AZN_S_U_INVALID_PRINC_NAMEThe principal name is unknown.

v AZN_S_U_LDAP_AUTHEN_FAILEDAuthentication to the LDAP user registry failed.

v AZN_S_U_PASSWORD_EXPIREDThe user password has expired.

v AZN_S_U_PASSWORD_HAS_SPACESThe user password contains spaces.

v AZN_S_U_PASSWORD_TOO_FEW_ALPHAThe user password must have more alphanumeric characters.

v AZN_S_U_PASSWORD_TOO_FEW_NONALPHAThe user password must have more non-alphanumeric characters.

v AZN_S_U_PASSWORD_TOO_MANY_REPEATEDThe user password has one or more characters that are repeated too many times.

v AZN_S_U_PASSWORD_TOO_SHORTThe user password must contain more characters.

v AZN_S_U_URAF_AUTHEN_FAILEDURAF authentication failed

v AZN_S_U_TOD_ACCESS_DENIEDAccess denied because time or day restrictions prevent access at the currenttime.




Appendix B. Authorization service plug-in API reference

This chapter contains the following reference pages:v “azn_admin_get_object()” on page 164v “azn_admin_get_objectlist()” on page 166v “azn_admin_get_tasklist()” on page 168v “azn_admin_perform_task()” on page 171v “azn_service_initialize()” on page 174v “azn_service_shutdown()” on page 177


azn_admin_get_object()Retrieves a potential protected object. Tests for the existence of a protected object.

Syntaxazn_status_tazn_admin_get_object(

azn_creds_h_t creds,azn_string_t locale,azn_string_t path,azn_attrlist_h_t indata,azn_attrlist_h_t outdata

);

ParametersInput

credsCredentials of the identity requesting the object. The administration servicemust verify that the credentials have sufficient authorization to perform therequested operation. The Access Manager policy server forwards thecredentials of the administrator when performing this function.

localeLocale of the caller at the client machine. The locale is the string equal toLC_MESSAGES returned from the client machine. Note: This parameter is notused in Access Manager 3.9.

pathThe complete path name of the protected object.

indataAn undefined (free form) attribute list that can be used for agreed uponcommunication between the administration service implementation and acustom user interface.

Output

outdataAn undefined (free form) attribute list. This attribute list is allocated by theadministration service implementation. See the Description section immediatelybelow for a discussion of how to use this output parameter.

DescriptionThis function returns information about an object in the Access Manager protectedobject namespace. The credentials of the identity requesting the object areforwarded by the Access Manager policy server when this function is called.

When the caller has sufficient permissions, the protected object information isplaced into a authorization API attribute list. This list is returned as the outputparameter outdata.

The administration service must pass the protected object information in theazn_admin_svc_pobj attribute. Use azn_attrlist_add_entry_pobj() to add thisattribute to the attribute list.


The administration service must pass the result strings information in theazn_admin_svc_results attribute. Use azn_attrlist_add_entry_pobj() to add thisattribute to the attribute list. Typically, these strings include error, warning, andinformation messages.

The administration service and the custom user interface can exchange informationof their choice by setting other attributes. Use the azn_attrlist_add_entry_* APIsto set attributes. The Access Manager policy server passes these other attributes inthe outdata parameter of the corresponding administration API function call.

Multiple authorization API applications can register to service the protected objecthierarchy name for the protected object. You can use this feature to providefailover support in the event that a particular application server fails. If theauthorization API implementation fails to connect to a registered serviceimplementation, it attempts to contact other service implementations until aconnection is successful or until the list of appropriate service implementations isexhausted.


When the returned status code is not equal to AZN_S_COMPLETE, the major errorcodes are derived from the returned status code with azn_error_major().

When this function calls another authorization API function, and the calledfunction returns an error, this function should return the error to the callingapplication.v AZN_S_SVC_ADMIN_OUT_OF_MEMORY

A memory allocation error has occurred.v AZN_S_SVC_ADMIN_INVALID_SVCINFO_HDL

The svc_info passed to the administration service plug-in shared library isinvalid.

v AZN_S_SVC_ADMIN_INVALID_ARG_COUNTThe argument count argc passed to the administration service plug-in sharedlibrary is invalid.

v AZN_S_SVC_ADMIN_INVALID_ARG_ARRAYThe argument array passed to the administration service plug-in shared libraryis invalid.

v AZN_S_SVC_ADMIN_INVALID_ARGUMENTOne or more of the arguments passed in to initialize the administration serviceplug-in is invalid.

v AZN_S_FAILUREAn implementation specific error or failure has occurred. An implementationspecific minor error code should be returned in the status code for the caller toextract with azn_error_minor().

Appendix B. Authorization service plug-in API reference 165

azn_admin_get_objectlist()Accesses the administration service to provide a list of all potential protectedobjects that are children of the specified parent object.

Syntaxazn_status_tazn_admin_get_object(

azn_creds_h_t creds,azn_string_t locale,azn_string_t path,azn_attrlist_h_t indata,azn_attrlist_h_t outdata

);

ParametersInput



pathThe complete path name of the protected object.


Output

outdataAn undefined (free form) attribute list. This attribute list is allocated by theadministration service implementation. See the Description section immediatelybelow for a discussion of how to use this output parameter.

DescriptionThis function returns information about objects in the Access Manager protectedobject namespace. The credentials of the identity requesting the objects areforwarded by the Access Manager policy server when this function is called.

When the caller has sufficient permissions, the protected object information isplaced into a authorization API attribute list. This list is returned as the outputparameter outdata.

The administration service plug-in must pass the protected object information inthe azn_admin_svc_pobj attribute. Use azn_attrlist_add_entry_pobj() to add thisattribute to the attribute list.


The administration service plug-in must pass the result strings information in theazn_admin_svc_results attribute. Use azn_attrlist_add_entry_pobj() to add thisattribute to the attribute list. Typically, these strings include error, warning, andinformation messages.


Multiple authorization API applications can register to service the protected objecthierarchy name for the protected object. You can use this feature to providefailover support in the event that a particular application server fails. If theauthorization API implementation fails to connect to a registered serviceimplementation, it attempts to contact other service implementations until aconnection is successful or until the list of appropriate service implementations isexhausted.











azn_admin_get_tasklist()Returns a list of all the supported administration tasks.

Syntaxazn_status_tazn_admin_get_tasklist(

azn_creds_h_t creds,azn_string_t locale,azn_attrlist_h_t indata,azn_attrlist_h_t outdata

);

ParametersInput




commands[]A NULL terminated list of administration commands supported by this serviceimplementation.

Commands should conform to pdadmin command line interface syntax rules.

The command list may be state sensitive. Only commands that can besuccessful in the current state can be returned. Thus the returned list does notinclude all possible commands.

Output

outdataAn undefined (free form) attribute list. This attribute list is allocated by theadministration service implementation.

DescriptionReturns a list of all the supported administration tasks. The list is obtained fromthe administration service.

The administration service plug-in must pass the task information in theazn_admin_svc_task attribute. Use the azn_attrlist_add_entry() API to build thelist. Information about each specific task is a value of this attribute.


The administration service plug-in must pass the result strings information in theazn_admin_svc_results attribute. Use azn_attrlist_add_entry_pobj() to add thisattribute to the attribute list. Typically, these strings include error, warning, andinformation messages.

Each value for the azn_admin_svc_results attribute indicates any resultinformation for the azn_admin_get_tasklist() call. These results are displayed bypdadmin in response to typing the command server listtasks server name at thepdadmin command line interface. For example, if this call was successful, theimplementor may choose not to return anything in the azn_admin_svc_resultsattribute. If this call was unsuccessful, the implementor can returnimplementation-specific error messages in the adm_admin_svc_results attribute.


The authorization API invokes this function on all registered administration serviceplug-ins and returns the output back from all of them. If two plug-ins return thesame task names, both are returned. If any of the plug-ins return an error, theremaining plug-ins do not get invoked. The results obtained thus far are returnedalong with the error that occurred. If a plug-in does not support any tasks, itshould return an AZN_S_COMPLETE major code so that this function can beinvoked on the remaining plug-ins (if any).

Each value for the azn_admin_svc_task attribute needs to be the completespecification of how to invoke the task. These values are displayed in response totyping the command server listtasks server name at the pdadmin command lineinterface. These value could also potentially be used by a graphical user interface,so they must to be complete.








v AZN_S_SVC_ADMIN_INVALID_ARGUMENT


One or more of the arguments passed in to initialize the administration serviceplug-in is invalid.



azn_admin_perform_task()Instructs the service to perform an administration task. The service returns theresults of the task.

Syntaxazn_status_tazn_admin_perform_task(

azn_creds_h_t creds,azn_string_t locale,azn_string_t command,azn_attrlist_h_t indata,azn_attrlist_h_t outdata

);

ParametersInput



commandCommand string that identifies the task to be performed. The string mustconforms to the pdadmin command line interface syntax rules.


Output

outdataAn undefined (free form) attribute list. This attribute list is allocated by theadministration service implementation.

DescriptionInstructs the service to perform an administration task. The caller must havecredentials with sufficient permission to perform the task. The service returns theresults of the task in the outdata attribute list.

The administration service must pass the result strings information in theazn_admin_svc_results attribute. Use azn_attrlist_add_entry_pobj() to add thisattribute to the attribute list. Typically, these strings include error, warning, andinformation messages.



The authorization API implementation invokes this function on all registeredadministration service plug-ins until it finds one that implements this interface. Ifmore than one service plug-in supports this task, the first plug-in is selected toexecute the task. The service plug-in should return anAZN_S_SVC_ADMIN_INVALID_TASK major code if it is passed on a task that itcannot perform.

The ssl-v3-timeout parameter specified in the [ssl] stanza of the authorizationconfiguration file determines the timeout for the communication between theauthorization AP application and Access Manager policy server, and for thecommunication between the Access Manager policy server and the pdadmin utilitycommand line interface.

A value of zero specifies an infinite timeout. Other values represent the actualamount of time within which a response is expected for a request. If the task beingperformed by azn_admin_perform_task() takes a long time, this communicationcould time out and cause an SSL error. Therefore, this timeout value needs to beset properly in the [ssl] stanza in the various configuration files. The relevantconfiguration files include ivmgrd.conf, the authorization API configuration file,ivacld.conf, and pd.conf.




A memory allocation error has occurred.v AZN_S_SVC_ADMIN_INVALID_TASK

The passed-in task is not implemented by this administration service plug-in.Use the pdadmin server listtasks authorization_API_application_name command todetermine the list of tasks supported by this authorization API application. If thetask in question is not shown on the list, make sure that the authorizationadministration service plug-in that implements this task is registered by theauthorization API application.

v AZN_S_SVC_ADMIN_INVALID_SVCINFO_HDLThe svc_info passed to the administration service plug-in shared library isinvalid.




v AZN_S_FAILURE


An implementation specific error or failure has occurred. An implementationspecific minor error code should be returned in the status code for the caller toextract with azn_error_minor().


azn_service_initialize()

Initialize the specified authorization service plug-in.

Syntaxazn_status_tazn_service_initialize(

int argc,const char **argv,azn_attrlist_h_t svc_init,azn_attrlist_h_t *svc_info);

DescriptionUse this initialization function to initialize a service plug-in. The service dispatchercalls this function prior to calling the functions that are specific to each plug-in. Forexample, this function is called before calling azn_entitlement_get_entitlements()to obtain entitlements information from the service plug-in.

The input parameters argc and argv are built from the parameters that are specifiedin the service definition for the service instance.

A sample service definition for an Entitlements service named entsvc is:entsvc = /lib/libentsvc.so & -server barney

For the service definition above azn_service_initialize() is called with an argcvalue of 2. The argv array contains the following values:argv[0] = “-server”argv[1] = “barney”

In this example, the argv values are used to specify the server system where theEntitlements service plug-in is to be loaded.

The service information returned by the service plug-in in svc_info can contain theversion number of the service. This value is defined in ogauthzn.h:extern azn_string_t azn_svc_version;

The service plug-in can assume that the service dispatcher will release the attributelist returned in svc_info when it has finished with it.

Plug-ins are only required to return service information when the dispatcherspecifically requests this information.

Input parameters should not be modified.

The prototype for this function is included in the file azn_svc_protos.h, in the AccessManager include directory.

ParametersInput

argcThe number of arguments contained in the argv array.

argvThe string arguments passed in the service definition for this service instance.


svc_initThe svc_init parameter is an attribute list containing attributes that arespecified by the service dispatcher to either configure or request initializationinformation from the service plug-in.

Output

svc_infoThe svc_info parameter is a list of attributes returned by the service plug-in torequest specific treatment by the service dispatcher or to inform the servicedispatcher of the operational parameters of service.

Examples of the information listed in the attributes are the version of theservice and the largest minor error code that maybe returned by the service.


If the returned status code is not equal to AZN_S_COMPLETE, the major errorcodes will be derived from the returned status code with azn_error_major().

Each of the following error messages also returns an implementation-specific minorerror code. Use azn_error_minor() to derive specific minor error codes from thereturned status code.v AZN_S_SVC_DEFINITION_ERROR

Returned by the service dispatcher when an error has been found in the servicedefinition in the authorization API configuration file aznapi.conf.

v AZN_S_SVC_NOT_FOUNDReturned by the service dispatcher when an error occurs either while locating orloading an authorization API service plug-in.

v AZN_S_SVC_INTERFACE_NOT_FOUNDReturned by the service dispatcher when an error occurs either locating orloading a service interface within a particular plug-in. For example, thedispatcher returns this error if the azn_service_initialize() interface was notfound in the loaded plug-in.

v AZN_S_ SVC_INIT_FAILEDReturned by the entitlements service plug-in if an error occurs when theentitlements service is initializing.

v AZN_S_SVC_AUTHORIZATION_FAILUREReturned when the calling application does not have sufficient authority toinvoke the services of this service plug-in.

v AZN_S_SVC_ADMIN_INVALID_SVCINFO_HDLThe svc_info passed to the administration service plug-in shared library isinvalid.



v AZN_S_SVC_ADMIN_INVALID_ARGUMENT


One or more of the arguments passed in to initialize the administration serviceplug-in is invalid.



azn_service_shutdown()

Shut down the specified service Plug-In.

Syntaxazn_status_tazn_service_shutdown(

int argc,const char **argv,azn_attrlist_h_t svc_init,azn_attrlist_h_t *svc_info);

DescriptionThe authorization API service dispatcher calls this interface to shut down thespecified authorization service plug-in as part of shutting down the authorizationAPI.

The input parameters argc and argv are built from the parameters that werespecified in the service definition for this service instance.

A sample configuration file entry for an entitlements service named entsvc is:entsvc = /lib/libentsvc.so & -server barney

For the service definition above azn_service_shutdown() is called with an argcvalue of 2. The argv array contains the following values:argv[0] = “-server”argv[1] = “barney”

The service plug-in can assume that the service dispatcher will release the attributelist returned in svc_info when it has finished with it.

Information that may be requested of the service during shutdown is not currentlydefined but may be defined by the interface in future.

The prototype for this function is included in the file azn_svc_protos.h, in theAccess Manager include directory.

ParametersInput

argcThe number of arguments in the argv array.

argvThe string arguments contained in the service definition for this serviceinstance.

svc_initThe svc_init parameter is an attribute list containing attributes that arespecified by the dispatcher to either unconfigure or request information fromthe service plug-in after shutdown is complete.

Output

svc_infoThe svc_info parameter is a list of attributes returned by the entitlements


service to request specific treatment by the service dispatcher or to inform theservice dispatcher of the results of service shutdown.


If the returned status code is not equal to AZN_S_COMPLETE, the major errorcodes will be derived from the returned status code with azn_error_major().v AZN_S_ SVC_SHUTDOWN_FAILED

Returned by the authorization service plug-in when an error occurs while it isshutting down.



Appendix C. svrsslcfg reference

This section contains the following reference page:v “svrsslcfg” on page 180


svrsslcfg

Configure and unconfigure an Authorization API application to communicate withthe Policy Director Management Server or Authorization Server.

Syntaxsvrsslcfg action parameter1 parameter2....

Supported actions and their parameters:

-add_replica-f absolute_pathname_of_configuration_file-h host_name-p port-k rank

-chgcert

-chgport-r port

-chgpwd[-e pwd_life]

-chg_replica-f absolute_pathname_of_configuration_file-h host_name-p port-k rank

-config-f absolute_pathname_of_configuration_file

-d kdb_dir-n server_name-s server_type-r port-P admin_pwd[-S server_password][-A admin_id][-t timeout][-e pwd_life][-C cert_file][-l listening_mode][-a refresh_mode]

-rmv_replica-f absolute_pathname_of_configuration_file-h host_name

-unconfig-f absolute_pathname_of_configuration_file-n server_name-P admin_pwd

[-A admin_id]


Description-add_replica

Use this option when running the application in remote mode. This optioninstructs the application how to contact the Access Manager authorization server.

This option requires two parameters:v -f absolute_pathname_of_configuration_file

v -h host_name

This option takes two optional parameters:v -p port

v -k rank

This option is not used when running the application in local mode. For moreinformation on local mode and remote mode, see the IBM Tivoli Access ManagerBase Administration Guide.

-chgcert

Renew the server certificate. A new public-private key pair and certificate will becreated and stored in the keyring file. Use this command if the original certificatehas been compromised. If the certificate and the password to the keyring databasefile containing that certificate have expired, use svrsslcfg -chgpwd to refresh thepassword first. This is necessary because a valid password is needed to open thekeyring database file to get the certificate.

Ensure that the Access Manager policy server is running before attempting torenew the server certificate. Ensure that the application server (when used with anauthorization API application) is stopped before renewing the certificate.

-chgport

Change the listening port number.

-chgpwd

Change the keyring file password. A new random password will be generated andsaved in the stash file. Only the -e parameter is allowed with this action. Ensurethat the application server (when used with an authorization API application) isstopped before changing the password.

-chgreplica

Change a replica. The replica hostname is used to identify the replica and cannotbe changed by this action. The listening port and preference may be changed.

-config

The svrsslcfg -config action performs the following configuration tasks:v Creates a user with a name by combining the specified server_name with the

local TCP/IP host name.Note that if the server_name supplied with the -n option includes the localTCP/IP host name, then the server_name will equate to the user name. For

Appendix C. svrsslcfg reference 181

example, svrsslcfg will combine a server_name of MyApp with a local host name ofhost1.domain.com to form a user account name of myApp/host1.domain.com.When the server_name is specified as myApp/host1.domain.com, svrsslcfg does notdetermine the TCP/IP host name, but instead uses the supplied string as theuser name.

v Creates an SSL key file for that user. For example, demo_user.key anddemo_user.sth.

v Adds the user to the ivacld-servers group when the server_type is local, or to theremote-acl-users group when the server_type is remote.

Administrators use the -config option to configure an application that has beenwritten with the authorization API. This option enables the application tocommunicate with the either the Access Manager policy server or the AccessManager authorization server. The Access Manager runtime environment must beinstalled before using this utility.

This utility creates an SSL stanza or modifies an existing stanza for the SSL in theconfiguration file. The utility also creates a key database in the specified directory.The database contains an SSL certificate signed by the Access Manager policyserver.

You must provide a unique Access Manager name for the server, the directory inwhich the key ring database files are created, the application authorization type(local or remote) and a TCP port number if the application will listen for databaseupdate notifications (local mode only).

-rmv_replica

Remove a replica. The replica hostname is used to identify the replica to beremoved.

-unconfig

Unconfigure the server. The key ring files will be deleted, and the server removedfrom the user registry and Access Manager database.

The following parameters are required:v -f absolute_pathname_of_configuration_file

v -n server_name

v -P admin_pwd

The following parameter is optional:v -A admin_id

Parameters-a refesh_mode

Sets the certificate and keyring file password auto-refresh enabled flag in theconfiguration file. The value of this parameter must be yes or no. If notspecified, the default is yes.

Optional parameter for -config.

-A admin_idThe Access Manager administrator name. When the user registry type is LDAP,this parameter is ignored, and the value sec_master is used instead.


Optional parameter for -config and -unconfig.

-C cert_fileSpecifies the fully qualified name of the file containing the base-64 encodedSSL certificate used when the server authenticates directly with LDAP. This isoptional.


-d kdb_dirThe directory that is to contain the keyring database files for the server. Thisdirectory must already exist, it will not be created by svrsslcfg.

Required parameter for -config

-e pwd_lifeThe keyring file’s password expiration time in days. This parameter is optional.If not specified during initial configuration, a default of 183 days is used.

Optional parameter for -config and -chgpwd.

-f absolute_pathname_of_configuration_file-fileThe absolute path to the configuration file for the application. Theconfiguration file consists of a series of stanza entries that specify configurationsettings, such as the location of the SSL key file.

Required parameter for -config, -unconfig, --add_replica, -chg_replica,rmv_replica.

-h host_nameThe TCP hostname of the Access Manager authorization server.

Required parameter for -add_replica, -chg_replica, and -rmv_replica.

-k rankReplica order of preference among other replicas. This parameter default to 10when the -add_replica option is used. Rank must be an integer value from 1 to10. The higher the number, the higher the rank. When the application needs torequest an authorization decision from an authorization server, it will send therequest first to the authorization server with the highest rank. If that server isunavailable, the application will send the request to the server with the nexthighest rank. This process continues until an authorization decision has beenobtained, or all configured authorization servers have been accessed.

Optional parameter for -add_replica and -chg_replica.

-l -l listen_modeSets the listening-enabled flag in the configuration file. The value of thisparameter must be yes or no. If not specified, the default is no. When usedwith the -config action, a value of yes requires that the -r parameter must havea non zero value. When used with the -modify action, a value of yes requiresthat the listening port number in the configuration file be non zero.

Optional parameter for -config and -modify.

-n server_nameThe name of the server. The name may be specified as eitherserver_name/hostname or server_name, in which case the local hostname will beappended to form name/hostname. The names ivacld, secmgrd, and ivweb arereserved for Access Manager servers.

Required parameter for -config and -unconfig.

Appendix C. svrsslcfg reference 183

-p portListening port number of the Access Manager authorization server. This is porton which the Access Manager authorization server listens for requests. If notspecified as an option to -add_replica, a default port of 7136 is used.

Optional parameter for -add_replica and -chg_replica.

-P admin_pwdThe Access Manager administrator password. When the user registry type isLDAP, then this must be the security master (sec_master) principal’s password.This is a required parameter. If this parameter is not specified, the passwordwill be read from stdin.

Required parameter for -config and -unconfig.

-r port_numSets the listening port number for the server. This is a required parameter. Avalue of 0 may be specified only if the [aznapi-admin-services] stanza in theconfiguration file is empty.

Required parameter for -config.

-s server_typeThe type of server being configured. The value must be either local or remote.This is a required parameter.

Required parameter for -config.

-S server_pwdThe server’s password. This parameter is required. However, you can requestthat a password be created by the system by specifying a dash (-) for thepassword. If this option is used, the configuration file will not be updated withthe password created by the system. If the user registry type is LDAP and apassword is specified, it is saved in the configuration file. If this parameter isabsent, the server password is read from stdin.


-t ssl_timeoutSpecifies the SSL session timeout in seconds. The value must be in the range1-86400. This parameter is optional. If it is not specified during initialconfiguration, a default value of 7200 is used.


ExamplesFor example, the demonstration authorization program that is distributed with theADK invokes svrsslcfg as follows:svrsslcfg -config -f \/opt/PolicyDirector/example/authzn_demo/local.conf \-d /opt/PolicyDirector/example/authzn_demo \-n authzn_local -S <svr-password> -s local \-P <admin-password> -r 7777

Note that the demonstration program uses a configuration file named local.conf.For more information, see the Readme file that accompanies the demonstrationprogram software.


Appendix D. Notices

This information was developed for products and services offered in the U.S.A.IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user’s responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not give youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM Corporation500 Columbus AvenueThornwood, NY 10594U.S.A

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia CorporationLicensing2-31 Roppongi 3-chome, Minato-kuTokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not applyto you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.


Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM Corporation2Z4A/10111400 Burnet RoadAustin, TX 78758USA

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this information and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement, or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurement may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

All statements regarding IBM’s future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrates programming techniques on various operating platforms. You may copy,modify, and distribute these sample programs in any form without payment toIBM, for the purposes of developing, using, marketing or distributing applicationprograms conforming to the application programming interface for the operatingplatform for which the sample programs are written. These examples have notbeen thoroughly tested under all conditions. IBM, therefore, cannot guarantee orimply reliability, serviceability, or function of these programs. You may copy,modify, and distribute these sample programs in any form without payment toIBM for the purposes of developing, using, marketing, or distributing applicationprograms conforming to IBM’s application programming interfaces.


Each copy or any portion of these sample programs or any derivative work, mustinclude a copyright notice as follows:

© (your company name) (year). Portions of this code are derived from IBM Corp.Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rightsreserved.

If you are viewing this information softcopy, the photographs and colorillustrations may not appear.

TrademarksThe following terms are trademarks or registered trademarks of InternationalBusiness Machines Corporation in the United States, other countries, or both:

AIXDB2IBMIBM logoSecureWayTivoliTivoli logo

Microsoft, Windows, Windows NT, and the Windows logo are trademarks ofMicrosoft Corporation in the United States, other countries, or both.

Java and all Java-based trademarks and logos are trademarks or registeredtrademarks of Sun Microsystems, Inc. in the United States and other countries.

UNIX is a registered trademark of The Open Group in the United States and othercountries.

Other company, product, and service names may be trademarks or service marksof others.

Appendix D. Notices 187


Index

Aaccess control decisions

making 133making and extending 135

access decision function (ADF) 1access enforcement function (AEF) 2adding

additional application-specific context 38attributes for LDAP access 24authorization to an application 3credentials and handle 113name or buffer value to attribute list 98name or value to attribute list 97

additional user information 35address of data structure 36ADF (access decision function) 1ADK 1administration service

configuring 77error codes 80implementing 75initializing 78shutdown 78supported functions 79

administrator’s distinguished name 25AEF (access enforcement function) 2AIX

libivauthzn.a library file 3allocated memory 39API

attribute lists 7authorization decisions 8credentials 8error handling 8extensions 9functions 7

API functionsazn_attrlist_add_entry_buffer() 98azn_attrlist_add_entry() 97azn_attrlist_create() 101, 102azn_attrlist_delete() 103, 104azn_attrlist_get_entry_buffer_value() 110azn_attrlist_get_entry_string_value() 108azn_attrlist_get_names() 111azn_attrlist_name_get_num() 112azn_creds_combine() 113azn_creds_create() 116azn_creds_delete() 117azn_creds_for_subject() 119azn_creds_get_attrlist_for_subject() 122azn_creds_get_pac() 124azn_creds_modify() 126azn_creds_num_of_subjects() 129azn_decision_access_allowed_ext() 135azn_decision_access_allowed() 133azn_error_major() 141azn_error_minor_get_string() 143azn_error_minor() 142azn_id_get_creds() 144azn_initialize() 146azn_pac_get_creds() 149

API functions (continued)azn_release_buffer() 151azn_release_strings() 154azn_shutdown() 155azn_util_password_authenticate() 158

Application Development Kit (ADK) 1applications

building 4building an attribute list 38deploying with the Authorization API 5determining user’s authorization credentials 34

array of stringsmemory, releasing 40storage, freeing 154

assigninghandle for an empty attribute list 101, 102handle to empty credentials structure 116user credentials to a credentials handle 38

attribute list functions 7attribute lists

adding name or buffer value 98adding name or value 97building for additional application information 38creating 12creating and assigning a handle 101, 102deleting 13, 103, 104getting an attribute name 12getting the number of values 12getting values 13obtaining a credential 41releasing memory 39setting an entry 12

auditidentifier 123user information user_info 35

authenticated user identity 34authentication

identity, user 35information 35, 158mechanism 34

authority, authorization 35authorization

authority 35credentials 34, 36, 37decisions 8, 37, 39

Authorization APIbuffer 36building applications 4changing the credential’s contents 42character strings 9converting credentials to a transportable format 40converting credentials to the native format 41creating a chain of credentials 41deploying applications 5determining the number of credentials in a chain 41handling credentials 40initializing 146introducing 1obtaining a credential from a chain 41obtaining credential from a chain 41shutting down 39


Authorization API (continued)specifying cache mode type 16tasks 6

Authorization serverspecifying cache mode type 16

authorization serviceinitializing 146minor error codes 4minor errors 14starting 31submitting requests to 2

authorization service dispatcher 50azn_admin_get_object() 164azn_admin_get_objectlist() 166azn_admin_get_tasklist() 168azn_admin_perform_task() 171azn_attrlist_add_entry_buffer() 38azn_attrlist_add_entry() 38azn_attrlist_create() 38, 43azn_attrlist_delete() 103azn_attrlist_get_entry_buffer_value() 105, 110azn_attrlist_get_entry_string_value() 108azn_attrlist_get_names() 111azn_attrlist_h_ 11azn_attrlist_h_t 39azn_attrlist_name_get_num() 112azn_buffer_desc 10azn_buffer_t 10AZN_C_AUDIT_ID 123AZN_C_EMPTY_BUFFER 10AZN_C_INITIATOR_INDEX 41, 43, 119, 122AZN_C_NO_BUFFER 10AZN_C_NOT_PERMITTED 39, 133, 135AZN_C_PERMITTED 39, 133, 135AZN_C_VERSION 31azn_creds_combine() 41, 113azn_creds_create() 39, 41, 42, 116azn_creds_delete() 117azn_creds_for_subject() 42, 119azn_creds_get_attrlist_for_subject() 43, 122azn_creds_get_pac() 40, 124azn_creds_h_t 13, 39, 41azn_creds_modify() 42, 126azn_creds_num_of_subjects 42azn_creds_num_of_subjects() 41, 129azn_decision_access_allowed_ext() 39, 135azn_decision_access_allowed() 37, 39, 133azn_error_get_string() 14azn_error_major() 141azn_error_minor_get_string() 143azn_error_minor() 142azn_id_get_creds() 36, 38, 40, 144azn_initialize() 146azn_operation_read 37azn_operation_traverse 37azn_pac_get_creds() 149azn_release_buffer() 151azn_release_pobj() 40azn_release_string 9azn_release_string() 9, 153azn_release_strings() 9, 154AZN_S_ INVALID_MOD_FUNCTION 127AZN_S_ATTR_INVALID_INDEX 106AZN_S_ATTR_INVALID_INTEGER_REF 129AZN_S_ATTR_VALUE_NOT_BUFFER_TYPE 106, 110AZN_S_ATTR_VALUE_NOT_STRING_TYPE 109AZN_S_COMPLETE 14

AZN_S_FAILURE 14AZN_S_INVALID_ADDED_CREDS_HDL 114AZN_S_INVALID_APP_CONTEXT_HDL 137AZN_S_INVALID_ATTR_NAME 97, 105, 110AZN_S_INVALID_ATTRLIST_HDL 97, 105, 110AZN_S_INVALID_AUTHORITY 145AZN_S_INVALID_BUFFER 98AZN_S_INVALID_BUFFER_REF 105, 110, 151AZN_S_INVALID_COMB_CREDS_HDL 114AZN_S_INVALID_CREDS_HDL 114, 117, 118, 120, 125, 134AZN_S_INVALID_INTEGER_REF 112AZN_S_INVALID_MECHANISM 145AZN_S_INVALID_MECHANISM_INFO 145AZN_S_INVALID_NEW_CREDS_HDL 120, 145, 150AZN_S_INVALID_OPERATION 134AZN_S_INVALID_PAC 149AZN_S_INVALID_PAC_SVC 125, 150AZN_S_INVALID_PERMISSION_REF 134AZN_S_INVALID_PROTECTED_RESOURCE 134AZN_S_INVALID_STRING_REF 153, 154AZN_S_INVALID_STRING_VALUE 97AZN_S_INVALID_SUBJECT_INDEX 120AZN_S_UNIMPLEMENTED_FUNCTION 120, 150azn_service_initialize() 174azn_service_shutdown() 177azn_shutdown() 31, 155azn_status_t 14azn_string_t 9, 12, 35azn_util_password_authenticate() 34, 158aznutils.h 4, 14

Bbackwards compatibility

Solaris limitations 45Version 3.7 45Version 3.8 45

backwards compatibilitydeprecated API elements 45browser information 36buffer 9

declaration 9empty 10

buffer attribute value 105buffers

declaration 36introduction to 9none 10release of memory 40storage, freeing 151

buildingapplications 4attribute lists 38

Ccache modes 16chain of credentials 41, 129changing

contents of a credential 42existing credential 126

character strings 9cleaning up 39, 155combining credentials and handle 113components of

ADK 3Policy Director 3


configuration file 55configuring

Authorization API 16Policy Director secure domain 3

contents of the credential 42converting

credentials to a transportable format 40creating

attribute lists 12chain of credentials 41empty credentials structure 116new attribute lists 16, 38privilege attribute certificates 124valid empty attribute list 101, 102

credentials 8changing 126changing the credential’s contents 42combining with a handle 113converting to a transportable format 40converting to the native format 41creating a chain of credentials 41creating and assigning a handle 116deleting 117determining number of credentials 41extracting individual credentials 119handle 38invoking a privilege attribute certificate service 124making access control decisions 133making extended access control decisions 135obtaining attribute list from a credential 42obtaining for user authorization 34, 36obtaining from a chain of credentials 41returning handle to new PAC credentials 149returning in a chain 129returning information from 122user authorization 36

creds_attrlist 43custom-protected object 38

Ddata type structure

azn_attrlist_h_t 11azn_buffer_t 9azn_status_t 14azn_string_t 9

decisionauthorization 39

decision, authorization 39decisions

access control 133, 135authorization 8

definingsecurity policy 3

deletingattribute list 13, 103, 104credentials 117

deployingapplications 5applications into secure domain 3

deprecated API elements 45deprecated DCE authentication 47determining

authorization credentials for a user 36identity for a user 35number of credentials in a credentials chain 41

disablingnotification listener 18refreshes of local authorization policy database 18

distinguished name 25

Eempty credentials chain 116enabling

notification listener 18entitlements service

authorizing a caller 72configuring 70error codes 72imitializing 70implementing 69shutdown 70

entitlements service plug-insample code 61

error codesaznutils.h 4, 14ogauthzn.h 4, 14pdb*msg.h 4, 14

error handling 8, 14example of

assigning user identity information 36attribute list initialization data 18declaring a buffer 36

extendingAPI function standard 9function for obtaining an access decision 39

extensions, API 9external authorization server (see Authorization server) 38external authorization service

architecture 84authorization decision 90configuring 88error codes 91implementing 83initializing 89policy triggers 86shutdown 89weightings 87

extracting individual credentials 119

Ffiles

aznutils.h 4, 14ogauthzn.h 4, 14pdb*msg.h 14

formatcredentials, transportable 40

freeingarray of strings storage 154buffer storage 151string storage 153

Ggetting

attribute list name 12entry string value 108handle for a specified identity 144name attributes 111number of attribute entries 112

Index 191

getting (continued)number of values for attribute list name 12value attributes 13

Hhandle 113, 116, 117, 144

credentials 13, 38handling credentials 40header files

aznutils.h 4ogauthzn.h 4

host name, LDAP server 25

Iidentities, user 34, 35implementation modes 1initialization 8initializing

authorization service 146data 146invalid data 147

initiator 2installing

Policy Director 5interfaces

Authorization API manual pages 95International Organization for Standardization (ISO) 1introduction to

Authorization API 1IP address 36ISO (International Organization for Standardization) 1ivacld-servers 33

Kkey file, SSL 26key label, SSL 26

LLDAP

administrator’s distinguished name 25administrator’s password 26key file password 27port number 25server host name 25server key label 26SSL key file 26

lengthdata structure 36

local cache mode 1, 16logging in

using username and password pair 158

Mmajor errors 4, 14, 141making

access control decisions 133extended access control decisions 135

manual pagessummary 95

mappingrequested resource to protected object 38user operation to a permission 37

memorycredential structure 14release 39

minor errors 4, 14, 142mod_info 42mod_svc_id 42mode

local cache 1remote cache 1

modes, specifying 16modifying

contents of a credential 42existing credential 126

Nname value 111notification listener 17number of

bytes in the data 9individual credentials in a chain 129seconds before refreshing 18value attributes in the entry 112values for an attribute name 12

number of port, LDAP server 25

Oobtaining

authorization decision 39credential from a chain of credentials 41user authorization credentials 35, 36

ogauthzn.h 4, 14Open Group 1output parameters

authorization decision 39extended authorization decision 39

PPAC (privilege attribute certificate) 35, 40, 124, 149pac_svc_id 41password

accessing the SSL key file 27authenticating 158LDAP administrator 26

pdb*msg.h 14permissions 37persistent authorization policy database 17, 30placing the data structure into a buffer 36policy database replica 17, 30port number

for a TCP port 18, 25privilege attribute certificate (PAC) 35, 40, 124, 149protected object 38protected object namespace 38providing

additional parameters 38


Rrefreshing

local authorization database 18registry, user 4, 34releasing

allocated memory 39memory allocated 14

remote cache mode 1, 17remote-acl-users 33removing

attribute list 103, 104credentials 117

requested resource 38returning

access control decision information 136entry string value 108handle 126handle for a specified identity 144handle to credentials structure 119handle to new PAC credentials 149individual credentials in a chain 129information from a credentials structure 122major error code 141minor error code 142name attributes 111number of buffer attribute entries 112number of value attributes 112privilege attribute certificate 124

Ssecure domain 4Secure Socket Layer (SSL) 26security policy 3server

host name, LDAP 25service definition 54service plug-in 54, 55

administration service 52architecture 49configuring 53credentials modification service 52, 66entitlements service 52, 65error codes 58external authorization service 53, 67implementing 53initializing 53privilege attribute certificate service 52, 66shutdown 61supplied implementations 64

service plug-in interfacesimplementing 57

setting an attribute list entry 12shutdown 8, 39shutting down 8, 39, 40, 155Solaris

libivauthzn.so library file 3specifying

additional user information 35authorization authority 35type of cache mode 16user authentication identity 35

SSLcommunications 26key file password 27key label 26

standard, The Open Group 1starting

authorization service 31status codes 14, 141, 142storage

array of strings, freeing 154buffer, freeing 151string, freeing 153

stringsfreeing of storage 153release of memory 40see also array of strings 40value 108

successful login 158summary of

API extensions 9API functions 7attribute list functions 7attribute list tasks 12authentication parameters 36Authorization API manual pages 95Authorization API tasks 6authorization decision functions 8authorization decision output parameters 39buffer names and values 9cache modes 16credentials functions 8error code files 14initialization, shutdown, and error handling functions 8local cache mode attributes and values 17SSL attributes for LDAP access 26user identity types 34

svrsslcfgreference page 180

Ttasks, Authorization API 6TCP port number 18types of

additional user information 35authentication parameters 36cache modes 16user identities 34

Uunauthenticated user 34unauthenticated users 11user

additional auditing information 35assigning credentials to a credentials handle 38authentication identity 35authorization credentials 35, 36mapping the user operation 37obtaining an identity 34specifying additional information 35unauthenticated 35

user registryspecifying LDAP 4specifying the user authentication identity 35

username and password 158using

as input of credentials information 11username and password to log in 158

Index 193

utility function error codesmajor errors 4minor errors 4

Vvalue attributes

buffer 105, 110entry number 112name 111string 108

values 9version number 31

Wweightings 87Windows NT

ivauthzn.dll library file 3


Printed in U.S.A.

GC32-0849-00

Documents

publib.boulder.ibm.com · Usernameandpassword..............................21 Access Manager configuration file location ........................21 Password for the SSL keyfile