Authorization C API Developer Reference

IBM Security Access Manager for Web Version 7.0 Authorization C API Deeloper Reference SC23-6515-02

IBM Security Access Manager for Web Version 7.0 Authorization C API Deeloper Reference SC23-6515-02

Note Before using this information and the product it supports, read the information in Notices on page 277. Edition notice Note: This edition applies to ersion 7, release 0, modification 0 of IBM Security Access Manager (product number 5724-C87) and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright IBM Corporation 2002, 2012. US Goernment Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents Figures.............. ii Tables............... ix About this publication........ xi Intended audience............ xi Access to publications and terminology..... xii Related publications.......... xi Accessibility.............. xi Technical training............ xi Support information........... xi Chapter 1. Authorization API oeriew.. 1 Authorization API introduction........ 1 The Open Group Authorization API standard.. 2 The authorization model......... 3 Authorization API components........ 3 Application deelopment requirements..... 5 Tested compilers............ 5 Demonstration programs......... 6 Application deployment.......... 6 Authorization API task summary....... 7 Chapter 2. Authorization API functions and data types............ 9 API functions.............. 9 Attribute lists............. 9 Credentials............. 10 Authorization decisions......... 10 Initialization, shutdown, and error handling.. 10 API extensions............ 11 Character strings............ 11 Buffers................ 11 Protected object structures......... 12 Default user registry information structure.... 13 Attribute lists.............. 14 Credential handles............ 16 Status codes and error handling....... 17 Chapter 3. Authorization API initialization............ 19 Authorization API initialization oeriew.... 19 Specifying UTF-8 or local code set....... 20 Specifying an authorization API configuration file 20 Specifying cache mode settings........ 21 Cache mode type........... 21 Authorization database file location..... 22 Local cache refresh........... 22 Local cache notification listener....... 23 SSL listener ports........... 23 Local domain............. 24 Configuring SSL from the API client to Security Access Manager............. 24 SSL keyfile............. 24 Stash file.............. 25 Keyfile label............. 25 SSL session timeout........... 26 SSL password expiration......... 26 Authentication method......... 26 User name and password......... 27 Configuration file location........ 27 SSL keyfile password.......... 28 Maximum number of worker threads..... 28 Automatic refresh of SSL certificate and keyfile password.............. 28 Connection timeout........... 29 Specifying communications attributes for the policy serer................ 29 Policy serer host name......... 29 Policy serer port number........ 30 Specifying alues for an authorization serer replica 30 Configuring the authorization API for LDAP access 31 LDAP user registry support........ 31 LDAP serer host name......... 31 LDAP serer port number........ 32 LDAP user distinguished name....... 32 LDAP user password.......... 32 SSL communication with the LDAP serer... 33 SSL keyfile name........... 33 SSL keyfile distinguished name....... 33 SSL keyfile password.......... 33 Maximum search buffer size........ 34 Caching LDAP data.......... 34 LDAP serer query preference....... 34 Authentication method......... 35 Specifying LDAP user registry replica access.. 35 LDAP client-side timeout......... 35 LDAP client-side authentication timeout.... 36 LDAP client-side search timeout...... 36 URAF registry settings.......... 36 URAF configuration file......... 36 Serer identity............ 37 Serer password............ 37 Cache mode............. 37 Cache size.............. 37 Cache lifetime............ 38 Authorization rules initialization....... 38 Prolog text for the XMLADI input document.. 38 Prolog text for the XSL rule document.... 39 Resource manager ADI prefix list...... 39 Dynamic ADI retrieal entitlement serice list.. 40 XMLADI attribute definitions....... 40 Enabling the return of permission information... 41 Configuring eent logging and auditing..... 42 Specifying the host interface on which to listen.. 43 Starting the authorization serice....... 43 Chapter 4. Using the authorization API 45 Authenticating an API application....... 45 Copyright IBM Corp. 2002, 2012 iii

Verifying the identity of a user........ 46 Usage tip: enforcing user lockout policy.... 46 Obtaining user authorization credentials..... 47 Step 1: Specifying the authorization authority and authentication mechanism....... 47 Step 2: Specifying user authentication identity.. 48 Step 3: Specifying additional user information.. 48 Step 4: Placing user information into an API buffer............... 49 Step 5: Obtaining authorization credentials for the user.............. 49 Obtaining an authorization decision...... 50 Step 1: Mapping the user operation to a Security Access Manager permission........ 50 Step 2: Mapping the requested resource to a protected object............ 51 Step 3: Assigning the user credentials to a credentials handle........... 51 Step 4: Building an attribute list for additional application information......... 52 Step 5: Obtaining an authorization decision... 52 Cleaning up and shutting down....... 53 Releasing allocated memory........ 53 Shutting down the authorization API..... 54 Working with credentials.......... 54 Conerting credentials to a transportable format 54 Conerting credentials to the natie format... 54 Creating a chain of credentials....... 55 Determining the number of credentials in a credentials chain............ 55 Obtaining a credential from a chain of credentials 55 Modifying the contents of a credential.... 55 Obtaining an attribute list from a credential.. 56 Setting and getting string attribute alues for a credential.............. 57 Comparing two credentials........ 58 Copying a credential.......... 58 Chapter 5. Compatibility and application migration issues..... 59 Compatibility and application migration oeriew 59 Binary compatibility with earlier ersions.... 59 Deprecated API elements.......... 59 Chapter 6. Authorization serice plug-ins.............. 61 Serice plug-in architecture......... 61 The authorization serice dispatcher..... 62 Authorization serice plug-ins....... 63 Calling applications.......... 63 Supported types of serice plug-ins..... 65 Implementing a serice plug-in........ 66 Initialization and configuration of serice plug-ins.............. 67 Implementing serice interfaces...... 70 Using error codes........... 71 Shut down............. 75 Example serice source code........ 75 Serice plug-in implementations....... 78 Entitlement serices.......... 79 Credentials modification serice...... 82 Priilege attribute certificate serice..... 83 External authorization serice....... 84 Chapter 7. Entitlement serice plug-ins 85 Entitlements oeriew........... 85 Entitlements of type azn_string_t...... 86 Entitlements of type azn_buffer_t...... 86 Initialization, configuration, and shut down... 87 Obtaining entitlements for a specified user.... 87 Authorizing a caller to a specific entitlement serice plug-in................ 88 Using authorization API interfaces....... 88 Entitlement serice error codes........ 88 Dynamic ADI retrieal serices........ 89 Credential attributes entitlement serice..... 91 Registry attribute entitlement serice oeriew 92 Registry attribute entitlement serice configuration............. 93 Migration from a preious release...... 96 Configuring a credential attributes entitlement serice as a dynamic ADI retrieal serice... 97 Chapter 8. Administration serice plug-ins.............. 101 Understanding administration serice plug-ins.. 101 Configuring administration serice plug-ins... 103 Creating a configuration file entry for an administration serice......... 103 Configuring an administration serice programmatically........... 104 Initializing and shutting down administration serice plug-ins............ 104 Using an administration serice plug-in.... 105 Error codes.............. 106 Errors when registering the administration serice plug-in............ 106 Errors when registering administration definitions............. 107 Major errors from administration serice functions.............. 108 Minor errors from administration serice functions.............. 108 Error codes specific to an authorization serices plug-in.............. 108 Deploying an administration serice plug-in... 109 Chapter 9. External authorization serice plug-ins.......... 111 Introducing the external authorization serice.. 111 Understanding the external authorization serice 112 External authorization serice architecture... 112 Policy triggers............ 113 Weightings............. 115 Configuring an external authorization serice plug-in............... 116 Using a configuration file entry...... 116 Configuring an external authorization serice programmatically........... 117 i IBM Security Access Manager for Web Version 7.0: Authorization C API Deeloper Reference

Initializing and shutting down external authorization serice plug-ins........ 117 Obtaining an authorization decision...... 118 Error codes.............. 119 Major error codes........... 119 Minor error codes........... 121 Appendix A. Authorization API reference............. 123 azn_attrlist_add_entry().......... 124 azn_attrlist_add_entry_buffer()....... 125 azn_attrlist_add_entry_pobj()........ 126 azn_attrlist_add_entry_ulong()....... 127 azn_attrlist_copy()............ 127 azn_attrlist_create()........... 128 azn_attrlist_delete()........... 129 azn_attrlist_delete_entry()......... 130 azn_attrlist_delete_entry_alue()....... 131 azn_attrlist_get_entry_buffer_alue()..... 132 azn_attrlist_get_entry_pobj_alue()...... 133 azn_attrlist_get_entry_string_alue()...... 134 azn_attrlist_get_entry_type()........ 135 azn_attrlist_get_entry_ulong_alue()...... 136 azn_attrlist_get_names().......... 137 azn_attrlist_name_get_num()........ 138 azn_creds_combine()........... 139 azn_creds_copy()............ 141 azn_creds_create()............ 141 azn_creds_delete()............ 142 azn_creds_equal()............ 143 azn_creds_for_subject().......... 144 azn_creds_get_attr_alue_string()....... 146 azn_creds_get_attrlist_for_subject()...... 147 azn_creds_get_pac()........... 149 azn_creds_modify()........... 150 azn_creds_num_of_subjects()........ 153 azn_creds_set_attr_alue_string()....... 154 azn_decision_access_allowed()........ 155 azn_decision_access_allowed_ext()...... 157 azn_entitlement_get_entitlements()...... 159 azn_error_get_string().......... 161 azn_error_major()............ 161 azn_error_minor()............ 162 azn_error_minor_get_string()........ 162 azn_id_get_creds2()........... 163 azn_init_set_code_set().......... 165 azn_initialize()............. 166 azn_pac_get_creds()........... 169 azn_release_buffer()........... 170 azn_release_pobj()............ 171 azn_release_string()........... 172 azn_release_strings()........... 172 azn_shutdown()............ 173 azn_util_errcode()............ 174 azn_util_handle_is_alid()......... 175 azn_util_password_authenticate2()...... 175 azn_util_password_change()........ 177 Appendix B. Authorization serice plug-in API reference........ 181 azn_admin_get_object().......... 181 azn_admin_get_objectlist()......... 183 azn_admin_get_tasklist()......... 185 azn_admin_perform_task()......... 187 azn_sc_creds_get_pac().......... 189 azn_sc_creds_modify().......... 191 azn_sc_decision_access_allowed_ext()..... 193 azn_sc_entitlement_get_entitlements()..... 196 azn_sc_initialize()........... 197 azn_sc_pac_get_creds().......... 200 azn_sc_shutdown()........... 201 Appendix C. Attribute names reference............. 203 Initialization attributes.......... 203 Credential attributes........... 213 Permission information attributes....... 215 Authorization API serice plug-in attributes... 220 Authorization engine attributes....... 223 Appendix D. Guidelines for changing configuring files.......... 225 Configuration file organization....... 225 General guidelines........... 226 Default alues............. 226 Strings............... 226 Defined strings............. 227 File names.............. 227 Integers............... 227 Boolean alues............. 228 Appendix E. Stanza reference.... 229 [authentication-mechanisms] stanza...... 229 cert-ldap.............. 229 cert-uraf.............. 230 passwd-ldap............. 230 passwd-uraf............. 231 [aznapi-admin-serices] stanza....... 232 serice-id.............. 232 [aznapi-configuration] stanza........ 233 azn-app-host............ 233 cache-refresh-interal.......... 234 cred-attribute-entitlement-serices..... 235 db-file............... 236 dynamic-adi-entitlement-serices...... 236 input-adi-xml-prolog.......... 237 listen-flags............. 238 logcfg............... 238 mode............... 239 permission-info-returned........ 240 policy-cache-size........... 241 resource-manager-proided-adi...... 241 xsl-stylesheet-prolog.......... 242 [aznapi-cred-modification-serices] stanza.... 243 serice-id.............. 243 [aznapi-entitlement-serices] stanza...... 244 serice-id.............. 244 [aznapi-external-authzn-serices] stanza.... 245 policy-trigger............. 246 [aznapi-pac-serices] stanza........ 247 Contents

serice-id.............. 247 [ldap] stanza............. 248 authn-timeout............ 249 auth-using-compare.......... 249 bind-dn.............. 250 bind-pwd.............. 250 cache-enabled............ 251 enabled.............. 252 host............... 252 ldap-serer-config........... 253 max-search-size............ 253 port............... 254 prefer-readwrite-serer......... 255 replica............... 255 search-timeout............ 256 ssl-enabled............. 256 ssl-keyfile............. 257 ssl-keyfile-dn............ 258 ssl-keyfile-pwd............ 258 ssl-port.............. 258 timeout.............. 259 [manager] stanza............ 259 management-domain.......... 260 master-host............. 260 master-port............. 261 replica............... 261 [meta-info] stanza............ 262 ersion.............. 262 [ssl] stanza.............. 263 ssl-authn-password.......... 263 ssl-authn-type............ 263 ssl-authn-user............ 264 ssl-auto-refresh............ 264 ssl-io-inactiity-timeout......... 265 ssl-keyfile............. 266 ssl-keyfile-label............ 266 ssl-keyfile-stash............ 267 ssl-listening-port........... 267 ssl-local-domain........... 268 ssl-maximum-worker-threads....... 269 ssl-mgr-config............ 269 ssl-pwd-life............. 270 ssl-3-timeout............ 270 [uraf-registry] stanza........... 271 bind-id.............. 271 bind-pwd.............. 272 cache-lifetime............ 273 cache-mode............. 273 cache-size............. 274 uraf-registry-config.......... 275 [xmladi-attribute-definitions] stanza...... 276 attribute_name............ 276 Notices.............. 277 Index............... 281 i IBM Security Access Manager for Web Version 7.0: Authorization C API Deeloper Reference

Figures 1. The ISO 10181-3 Authorization Model.... 2 2. The Security Access Manager implementation of the ISO authorization model....... 2 3. Authorization serice plug-in Architecture 62 4. The administration serice plug-in to the authorization API.......... 102 5. The external authorization serice architecture 112 Copyright IBM Corp. 2002, 2012 ii

iii IBM Security Access Manager for Web Version 7.0: Authorization C API Deeloper Reference

Tables 1. Location of authorization API components 3 2. Location of authorization API header files 4 3. Location of authorization API error codes 4 4. Compilers tested with Security Access Manager 5 5. Demonstration programs........ 6 6. Credential functions and related tasks.... 10 7. Authorization decision functions and related tasks............... 10 8. Functions and related tasks for initialization, shutdown, and error handling...... 11 9. API extension functions and related tasks 11 10. Buffers.............. 12 11. Variables for protected object....... 12 12. Variables for default user registry..... 13 13. Functions that operate on attribute lists 15 14. Error code files........... 17 15. codeset parameter alues........ 20 16. Authorization API configuration file alue 21 17. Cache mode alues.......... 22 18. Local cache refresh alues........ 23 19. Cache notification listener alues..... 23 20. SSL listener port alue......... 23 21. Domain name alue.......... 24 22. SSL keyfile alue........... 25 23. Stash file alue........... 25 24. Certificate label for keyfile....... 25 25. SSL session timeout alue........ 26 26. Expiration interal for keyfile password or stash file............. 26 27. Authentication method for authorization API client............... 27 28. User name and password........ 27 29. Configuration file location alue..... 28 30. SSL keyfile password alue....... 28 31. Maximum number of threads alue.... 28 32. Refresh alue for SSL certificate and key database file password......... 29 33. Timeout alue for input/output connection 29 34. Policy serer host name alue...... 30 35. Policy serer port number alue..... 30 36. Values for an authorization serer replica 31 37. Values to enable LDAP user registry support 31 38. LDAP serer host name alue...... 32 39. LDAP serer port number alue..... 32 40. LDAP user DN alue......... 32 41. LDAP user password alue....... 32 42. LDAP serer SSL communication alue 33 43. SSL keyfile name alue........ 33 44. SSL keyfile distinguished name alue.... 33 45. SSL keyfile password alue....... 34 46. Maximum search buffer size alue..... 34 47. LDAP client-side caching alue...... 34 48. LDAP serer query preference alue.... 35 49. LDAP user authentication method alue 35 50. LDAP user registry replica access alues 35 51. LDAP client-side timeout alue...... 36 52. LDAP client-side authentication timeout alue 36 53. LDAP client-side search timeout alue... 36 54. URAF configuration file alue...... 37 55. URAF serer identity alue....... 37 56. URAF serer password alue...... 37 57. Cache mode alue.......... 37 58. Cache size alue........... 38 59. Cache lifetime alue......... 38 60. Authorization API initialization data attributes 43 61. Host name on which the authorization API application listens.......... 43 62. Additional user information that the authorization API proides....... 48 63. Authorization credentials for the user.... 49 64. Access request result......... 53 65. Authorization access decision information 53 66. Valid handles............ 64 67. Library file names by platform...... 68 68. Default configuration file entries..... 69 69. Authorization API interface....... 70 70. Major error codes from serice dispatcher 72 71. Major error codes from serice plug-ins 73 72. Generic major error codes........ 73 73. Minor error codes.......... 74 74. Protected objects entitlement serice.... 79 75. Extended attributes entitlement serice 80 76. Dynamic ADI retrieal entitlement serice 80 77. Credential attribute entitlement serice 81 78. Credentials attribute list modification serice 82 79. Credentials group membership modification serice.............. 83 80. Priilege attribute certificate (PAC) encoding serice.............. 83 81. External authorization serice...... 84 82. Interface input parameters....... 87 83. Entitlement serice error codes...... 89 84. Example attributes added to the credential 96 85. Supported authorization API functions 105 86. Function mappings......... 105 87. Attributes in the out data attribute list 106 88. Errors registering the administration serice plug-in.............. 106 89. Administration API functions...... 114 90. Major error codes.......... 119 91. Additional major error codes...... 120 92. Initialization attributes........ 203 Copyright IBM Corp. 2002, 2012 ix

x IBM Security Access Manager for Web Version 7.0: Authorization C API Deeloper Reference

About this publication Intended audience IBM Security Access Manager for Web, formerly called IBM Tioli Access Manager for e-business, is a user authentication, authorization, and web single sign-on solution for enforcing security policies oer a wide range of web and application resources. This reference guide contains information about how to use the Security Access Manager C administration API to enable an application to programmatically perform Security Access Manager administration tasks. This document describes the C implementation of the Security Access Manager administration API. See the IBM Security Access Manager for Web: Administration Jaa Classes Deeloper Reference for information regarding the Jaa implementation of these APIs. Information about the pdadmin command-line interface (CLI) can be found in the IBM Security Access Manager for Web: Command Reference. This reference is for application programmers writing programs in C and programming language to authorize the users and objects associated with the Security Access Manager product. Readers must be familiar with: Microsoft Windows and UNIX operating systems Database architecture and concepts Security management Internet protocols, including HTTP, TCP/IP, File Transfer Protocol (FTP), and Telnet The user registry that Security Access Manager is configured to use Lightweight Directory Access Protocol (LDAP) and directory serices, if used by your user registry Authentication and authorization To enable Secure Sockets Layer (SSL) communication, you must be familiar with SSL protocol, key exchange (public and priate), digital signatures, cryptographic algorithms, and certificate authorities. This reference is for application programmers writing programs in C and programming language to administer the users and objects associated with the Security Access Manager product. Readers must be familiar with: Microsoft Windows and UNIX operating systems Database architecture and concepts Security management Internet protocols, including HTTP, TCP/IP, File Transfer Protocol (FTP), and Telnet The user registry that Security Access Manager is configured to use Copyright IBM Corp. 2002, 2012 xi

Lightweight Directory Access Protocol (LDAP) and directory serices, if used by your user registry Authentication and authorization If you are enabling Secure Sockets Layer (SSL) communication, you also should be familiar with SSL protocol, key exchange (public and priate), digital signatures, cryptographic algorithms, and certificate authorities. Access to publications and terminology This section proides: A list of publications in the IBM Security Access Manager for Web library. Links to Online publications on page xi. A link to the IBM Terminology website on page xi. IBM Security Access Manager for Web library The following documents are in the IBM Security Access Manager for Web library: IBM Security Access Manager for Web Quick Start Guide, GI11-9333-01 Proides steps that summarize major installation and configuration tasks. IBM Security Web Gateway Appliance Quick Start Guide Hardware Offering Guides users through the process of connecting and completing the initial configuration of the WebSEAL Hardware Appliance, SC22-5434-00 IBM Security Web Gateway Appliance Quick Start Guide Virtual Offering Guides users through the process of connecting and completing the initial configuration of the WebSEAL Virtual Appliance. IBM Security Access Manager for Web Installation Guide, GC23-6502-02 Explains how to install and configure Security Access Manager. IBM Security Access Manager for Web Upgrade Guide, SC23-6503-02 Proides information for users to upgrade from ersion 6.0, or 6.1.x to ersion 7.0. IBM Security Access Manager for Web Administration Guide, SC23-6504-02 Describes the concepts and procedures for using Security Access Manager. Proides instructions for performing tasks from the Web Portal Manager interface and by using the pdadmin utility. IBM Security Access Manager for Web WebSEAL Administration Guide, SC23-6505-02 Proides background material, administratie procedures, and reference information for using WebSEAL to manage the resources of your secure Web domain. IBM Security Access Manager for Web Plug-in for Web Serers Administration Guide, SC23-6507-02 Proides procedures and reference information for securing your Web domain by using a Web serer plug-in. IBM Security Access Manager for Web Shared Session Management Administration Guide, SC23-6509-02 Proides administratie considerations and operational instructions for the session management serer. IBM Security Access Manager for Web Shared Session Management Deployment Guide, SC22-5431-00 xii IBM Security Access Manager for Web Version 7.0: Authorization C API Deeloper Reference

Proides deployment considerations for the session management serer. IBM Security Web Gateway Appliance Administration Guide, SC22-5432-00 Proides administratie procedures and technical reference information for the WebSEAL Appliance. IBM Security Web Gateway Appliance Configuration Guide for Web Reerse Proxy, SC22-5433-00 Proides configuration procedures and technical reference information for the WebSEAL Appliance. IBM Security Web Gateway Appliance Web Reerse Proxy Stanza Reference, SC27-4442-00 Proides a complete stanza reference for the IBM Security Web Gateway Appliance Web Reerse Proxy. IBM Security Access Manager for Web WebSEAL Configuration Stanza Reference, SC27-4443-00 Proides a complete stanza reference for WebSEAL. IBM Global Security Kit: CapiCmd Users Guide, SC22-5459-00 Proides instructions on creating key databases, public-priate key pairs, and certificate requests. IBM Security Access Manager for Web Auditing Guide, SC23-6511-02 Proides information about configuring and managing audit eents by using the natie Security Access Manager approach and the Common Auditing and Reporting Serice. You can also find information about installing and configuring the Common Auditing and Reporting Serice. Use this serice for generating and iewing operational reports. IBM Security Access Manager for Web Command Reference, SC23-6512-02 Proides reference information about the commands, utilities, and scripts that are proided with Security Access Manager. IBM Security Access Manager for Web Administration C API Deeloper Reference, SC23-6513-02 Proides reference information about using the C language implementation of the administration API to enable an application to perform Security Access Manager administration tasks. IBM Security Access Manager for Web Administration Jaa Classes Deeloper Reference, SC23-6514-02 Proides reference information about using the Jaa language implementation of the administration API to enable an application to perform Security Access Manager administration tasks. IBM Security Access Manager for Web Authorization C API Deeloper Reference, SC23-6515-02 Proides reference information about using the C language implementation of the authorization API to enable an application to use Security Access Manager security. IBM Security Access Manager for Web Authorization Jaa Classes Deeloper Reference, SC23-6516-02 Proides reference information about using the Jaa language implementation of the authorization API to enable an application to use Security Access Manager security. IBM Security Access Manager for Web Web Security Deeloper Reference, SC23-6517-02 About this publication xiii

Proides programming and reference information for deeloping authentication modules. IBM Security Access Manager for Web Error Message Reference, GI11-8157-02 Proides explanations and correctie actions for the messages and return code. IBM Security Access Manager for Web Troubleshooting Guide, GC27-2717-01 Proides problem determination information. IBM Security Access Manager for Web Performance Tuning Guide, SC23-6518-02 Proides performance tuning information for an enironment that consists of Security Access Manager with the IBM Tioli Directory Serer as the user registry. Online publications IBM posts product publications when the product is released and when the publications are updated at the following locations: IBM Security Access Manager for Web Information Center The http://pic.dhe.ibm.com/infocenter/tiihelp/2r1/topic/ com.ibm.isam.doc_70/welcome.html site displays the information center welcome page for this product. IBM Publications Center The http://www-05.ibm.com/e-business/linkweb/publications/serlet/ pbi.wss site offers customized search functions to help you find all the IBM publications that you need. IBM Terminology website The IBM Terminology website consolidates terminology for product libraries in one location. You can access the Terminology website at http://www.ibm.com/ software/globalization/terminology. Related publications This section lists the IBM products that are related to and included with the Security Access Manager solution. Note: The following middleware products are not packaged with IBM Security Web Gateway Appliance. IBM Global Security Kit Security Access Manager proides data encryption by using Global Security Kit (GSKit) ersion 8.0.x. GSKit is included on the IBM Security Access Manager for Web Version 7.0 product image or DVD for your particular platform. GSKit ersion 8 includes the command-line tool for key management, GSKCapiCmd (gsk8capicmd_64). GSKit ersion 8 no longer includes the key management utility, ikeyman (gskikm.jar). ikeyman is packaged with IBM Jaa ersion 6 or later and is now a pure Jaa application with no dependency on the natie GSKit runtime. Do not moe or remoe the bundled jaa/jre/lib/gskikm.jar library. xi IBM Security Access Manager for Web Version 7.0: Authorization C API Deeloper Reference

The IBM Deeloper Kit and Runtime Enironment, Jaa Technology Edition, Version 6 and 7, ikeyman User's Guide for ersion 8.0 is aailable on the Security Access Manager Information Center. You can also find this document directly at: Note: http://download.boulder.ibm.com/ibmdl/pub/software/dw/jdk/security/ 60/iKeyman.8.User.Guide.pdf GSKit ersion 8 includes important changes made to the implementation of Transport Layer Security required to remediate security issues. The GSKit ersion 8 changes comply with the Internet Engineering Task Force (IETF) Request for Comments (RFC) requirements. Howeer, it is not compatible with earlier ersions of GSKit. Any component that communicates with Security Access Manager that uses GSKit must be upgraded to use GSKit ersion 7.0.4.42, or 8.0.14.26 or later. Otherwise, communication problems might occur. IBM Tioli Directory Serer IBM Tioli Directory Serer ersion 6.3 FP17 (6.3.0.17-ISS-ITDS-FP0017) is included on the IBM Security Access Manager for Web Version 7.0 product image or DVD for your particular platform. You can find more information about Tioli Directory Serer at: http://www.ibm.com/software/tioli/products/directory-serer/ IBM Tioli Directory Integrator IBM Tioli Directory Integrator ersion 7.1.1 is included on the IBM Tioli Directory Integrator Identity Edition V 7.1.1 for Multiplatform product image or DVD for your particular platform. You can find more information about IBM Tioli Directory Integrator at: http://www.ibm.com/software/tioli/products/directory-integrator/ IBM DB2 Uniersal Database IBM DB2 Uniersal Database Enterprise Serer Edition, ersion 9.7 FP4 is proided on the IBM Security Access Manager for Web Version 7.0 product image or DVD for your particular platform. You can install DB2 with the Tioli Directory Serer software, or as a stand-alone product. DB2 is required when you use Tioli Directory Serer or z/os LDAP serers as the user registry for Security Access Manager. For z/os LDAP serers, you must separately purchase DB2. You can find more information about DB2 at: http://www.ibm.com/software/data/db2 IBM WebSphere products The installation packages for WebSphere Application Serer Network Deployment, ersion 8.0, and WebSphere extreme Scale, ersion 8.5.0.1, are included with About this publication x

Security Access Manager ersion 7.0. WebSphere extreme Scale is required only when you use the Session Management Serer (SMS) component. WebSphere Application Serer enables the support of the following applications: Web Portal Manager interface, which administers Security Access Manager. Web Administration Tool, which administers Tioli Directory Serer. Common Auditing and Reporting Serice, which processes and reports on audit eents. Session Management Serer, which manages shared session in a Web security serer enironment. Attribute Retrieal Serice. You can find more information about WebSphere Application Serer at: http://www.ibm.com/software/webserers/appser/was/library/ Accessibility Technical training Support information Accessibility features help users with a physical disability, such as restricted mobility or limited ision, to use software products successfully. With this product, you can use assistie technologies to hear and naigate the interface. You can also use the keyboard instead of the mouse to operate all features of the graphical user interface. Visit the IBM Accessibility Center for more information about IBM's commitment to accessibility. For technical training information, see the following IBM Education website at http://www.ibm.com/software/tioli/education. IBM Support proides assistance with code-related problems and routine, short duration installation or usage questions. You can directly access the IBM Software Support site at http://www.ibm.com/software/support/probsub.html. The IBM Security Access Manager for Web Troubleshooting Guide proides details about: What information to collect before you contact IBM Support. The arious methods for contacting IBM Support. How to use IBM Support Assistant. Instructions and problem-determination resources to isolate and fix the problem yourself. Note: The Community and Support tab on the product information center can proide more support resources. xi IBM Security Access Manager for Web Version 7.0: Authorization C API Deeloper Reference

Chapter 1. Authorization API oeriew This chapter proides an oeriew of the IBM Security Access Manager for Web (Security Access Manager) authorization API. Topic Index: Authorization API introduction Authorization API components on page 3 Application deelopment requirements on page 5 Application deployment on page 6 Authorization API task summary on page 7 Authorization API introduction Use the Security Access Manager authorization application programming interface (API) to program Security Access Manager applications and third-party applications to query the Security Access Manager authorization serice for authorization decisions. The Security Access Manager authorization API is the interface between the serer-based resource manager and the authorization serice and proides a standard model for coding authorization requests and decisions. The authorization API lets you make standardized calls to the centrally managed authorization serice from any deeloped application. The authorization API supports two implementation modes: Remote cache mode In remote cache mode, you use the authorization API to call the Security Access Manager authorization serer, which performs authorization decisions on behalf of the application. The authorization serer maintains its own cache of the replica authorization policy database. Local cache mode In local cache mode, you use the authorization API to download a local replica of the authorization policy database. In this mode, the application can perform all authorization decisions locally. The authorization API shields you from the complexities of the authorization serice mechanism. Issues of management, storage, caching, replication, credentials format, and authentication methods are all hidden behind the authorization API. The authorization API works independently from the underlying security infrastructure, the credential format, and the ealuating mechanism. The authorization API makes it possible to request an authorization check and get a simple "yes" or "no" recommendation in return. The authorization API is a component of the Security Access Manager application deelopment kit (ADK). Copyright IBM Corp. 2002, 2012 1

Security Access Manager APIs are thread-safe. Use caution when performing operations on objects with multiple threads. For example, an error is returned if you want to create, modify and delete an ACL, and the delete is done before the modify. The Open Group Authorization API standard The Security Access Manager authorization API implements the Open Group Authorization API (Generic Application Interface for Authorization Frameworks) standard. This interface is based on the International Organization for Standardization (ISO) 10181-3 model for authorization. In this model, an initiator requests access to a target resource. The initiator submits the request to a resource manager, which incorporates 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. Initiator Submit Access Request Resource Manager AEF Present Access Request Target Decision Request Decision ADF Figure 1. The ISO 10181-3 Authorization Model Security Access Manager implements the ADF component of this model and proides the authorization API as an interface to this function. Resource Manager Browser Initiator AEF Web Application Serer Authorization API Protected Data Target ADF Access Manager Authorization Serice Access Manager Secure Domain Figure 2. The Security Access Manager implementation of the ISO authorization model In the figure aboe, a browser (initiator) requests access to a file or other resource on a protected system (target). The browser submits the request to a web application serer (the resource manager that incorporates the access enforcement 2 IBM Security Access Manager for Web Version 7.0: Authorization C API Deeloper Reference

function). The web application serer uses the authorization API to submit the request to the Security Access Manager authorization serice (the access decision function). The Security Access Manager authorization serice returns an access decision, through the authorization API, to the web application serer. The web application serer processes the request as appropriate. To implement this model, deelopers of AEF applications add authorization API function calls to their application code. See the Open Group Authorization API document. The authorization model The first step in adding authorization to an application is to define the security policy requirements for your application. Defining a security policy means that you must determine the business requirements that apply to the application users, operations, and data. These requirements include: Objects to be secured Operations permitted on each object Users that are permitted to do the operations After your security requirements are defined, you can use the authorization API to integrate your security policy with the Security Access Manager security model. Complete the following steps to deploy an application into a Security Access Manager secure domain: 1. Configure the Security Access Manager secure domain to recognize and support the objects, actions, and users that are releant to your application. For an introduction to the Security Access Manager authorization model, see IBM Security Access Manager for Web: Administration Guide. For complete information about access control, see IBM Security Access Manager for Web: Administration Guide. 2. Use the authorization API within your application to obtain the needed authorization decisions. For an introduction to the authorization API, including information about remote cache mode and local cache mode, see IBM Security Access Manager for Web: Administration Guide. 3. Deelop your application logic to enforce the security policy. Authorization API components The authorization API is included in an optional installation package (ADK) in the Security Access Manager distribution. The authorization API files are installed in seeral subdirectories under the Security Access Manager installation directory. Table 1. Location of authorization API components bin include Directory Contents On Microsoft Windows systems, the library to include at run time is pdauthzn.dll. C header files. Chapter 1. Authorization API oeriew 3

Table 1. Location of authorization API components (continued) lib Directory Contents A library that implements the API functions. The name of the library is platform-dependent: Solaris Operating Enironment libpdauthzn.so Linux AIX libpdauthzn.so libpdauthzn.a Microsoft Windows pdauthzn.lib example/authzn_demo/cpp This directory contains an example program that demonstrates usage of the authorization API. Source files and a MAKEFILE are proided. For installation instructions for the ADK, see the IBM Security Access Manager for Web: Installation Guide. Header Files The header files are found in the include directory, located directly under the Security Access Manager ADK package installation directory. Table 2. Location of authorization API header files File ogauthzn.h aznutils.h azn_sc_protos.h azn_admin_sc_protos.h azn_deprecated.h iadminapi.h pdb*msg.h Contents The authorization API standard functions. Utility functions (extensions to the authorization API). Prototypes for generic authorization serice plug-in functions. Contains prototypes for the azn_serice_initialize() and azn_serice_shutdown() functions. This file can optionally be included by a plug-in programmer to prototype the calls defined in the serice. Prototypes for plug-in functions for the authorization administration serice. Prototypes and declarations for the functions, ariables, and attributes that are deprecated in this ersion of Security Access Manager. Aoid including this header file. Function prototypes for the Security Access Manager administration API. This API is described in IBM Security Access Manager for Web: Administration C API Deeloper Reference. Minor error codes. Error Codes The authorization API error codes are defined in the following files, in the include directory: Table 3. Location of authorization API error codes File ogauthzn.h aznutils.h Contents Major error codes for the standard authorization API functions. Major error codes for the authorization API utility functions. 4 IBM Security Access Manager for Web Version 7.0: Authorization C API Deeloper Reference

Table 3. Location of authorization API error codes (continued) File pdb*msg.h Contents Minor error codes for utility functions and the Security Access Manager authorization serices are found in a number of error message files, such as pdbaclmsg.h Application deelopment requirements To deelop applications that use the Security Access Manager authorization API, you must install and configure a Security Access Manager secure domain. If you do not hae a Security Access Manager secure domain installed, install one before beginning application deelopment. The minimum installation consists of a single system with the following Security Access Manager Base components installed: Security Access Manager run time enironment Security Access Manager policy serer Security Access Manager application deelopment kit When the Security Access Manager secure domain uses an LDAP user registry, the application deelopment system must hae an LDAP client installed. If you already hae a Security Access Manager secure domain installed, you can add another deelopment system to that domain. The minimum requirements for adding another deelopment system consist of the following components: Security Access Manager runtime enironment Security Access Manager application deelopment kit Note: For Security Access Manager installation instructions, see the IBM Security Access Manager for Web: Installation Guide. To compile applications that use the authorization API, you must install the Security Access Manager ADK on the build system. When you compile an application, make sure that you add the include directory for the Security Access Manager ADK to the compiler command line. When you link an application, specify the directory that contains the authorization shared library if it is not in the default location. Tested compilers This section lists compilers that IBM tested for use with the Security Access Manager Application Deeloper Kit (ADK). IBM tested the use of the Security Access Manager Application Deeloper Kit (ADK) component with the compilers listed in Table 4. Preious ersions of the compilers listed are not supported. Compilers on other supported platforms were not tested. Table 4. Compilers tested with Security Access Manager IBM AIX 6.1 Operating system platform tested Tested compiler IBM XL C/C++ Version 10.1 Chapter 1. Authorization API oeriew 5

Table 4. Compilers tested with Security Access Manager (continued) Operating system platform tested Tested compiler Sun Solaris 11 Operating System Oracle Solaris Studio Version 12.3 Red Hat Enterprise Linux Serer release 5.6 64 bit x86 GNU GCC 4.1.2 SUSE Linux Enterprise Serer 10 SP3 on 64-bit System z Microsoft Windows Serer 2008 R2 Enterprise Microsoft Visual Studio 2005 (using carsall.bat AMD64) Demonstration programs The Security Access Manager authorization API proides seeral example programs. The authzn_demo directory contains examples programs that demonstrate use of the authorization API. A C language example is included. The C example contains a sample Makefile. See the sample Makefile for build instructions specific to each supported operating system platform. Refer to the README file, located in the same directory, for information regarding the use of this example program. An example of the administration serice plug-in is proided in the admin_sc_demo directory. See the sample Makefile for build instructions. An example of an external authorization serice plug-in is proided in the eas_demo directory. See the sample Makefile for build instructions. An example of an entitlement serice plug-in is proided in the ent_sc_demo directory. See the sample Makefile for build instructions. Table 5. Demonstration programs Program authzn_demo azn_admin_sc_demo azn_eas_demo azn_ent_sc_demo Authorization API demonstration program Administration serice demonstration program External authorization serice demonstration program Entitlement serice demonstration program Application deployment To deploy an application with the authorization API, erify that your enironment contains the necessary supporting software. You can test your enironment by building and running the example program that is proided with the authorization API. Applications that are deeloped with the Security Access Manager authorization API must be run on systems that are configured into a Security Access Manager secure domain. When the Security Access Manager secure domain uses an LDAP user registry, the application deployment system must hae an LDAP client installed. The minimum Security Access Manager installation required on a system that runs an application is the Security Access Manager runtime enironment component. 6 IBM Security Access Manager for Web Version 7.0: Authorization C API Deeloper Reference

For deployment examples, see the demonstration programs described in Demonstration programs on page 6. Authorization API task summary The primary task of the authorization API is to obtain an authorization decision from the Security Access Manager authorization serice. Use the authorization API to present information about the user, operation, and requested resource to the Security Access Manager authorization serice, and receie the authorization decision. Your application is responsible for enforcing the decision, as appropriate. To obtain an authorization decision, you must accomplish certain tasks to configure the authorization API client. The following sections in this document proide a step-by-step guide to completing each of these required tasks: Chapter 3, Authorization API initialization, on page 19 Authenticating an API application on page 45 Verifying the identity of a user on page 46 Obtaining user authorization credentials on page 47 Obtaining an authorization decision on page 50 Cleaning up and shutting down on page 53 The authorization API also proides functions for performing optional tasks on user credentials. The following section describes the supported optional tasks: Working with credentials on page 54 Chapter 1. Authorization API oeriew 7

8 IBM Security Access Manager for Web Version 7.0: Authorization C API Deeloper Reference

Chapter 2. Authorization API functions and data types API functions This chapter describes the functions, structured data types, and constants that are defined as part of the authorization API. Topic Index: API functions Character strings on page 11 Buffers on page 11 Protected object structures on page 12 Default user registry information structure on page 13 Attribute lists on page 14 Credential handles on page 16 Status codes and error handling on page 17 This section proides tables that list the authorization API functions. The tables proide a link to the reference page for the function and a link to the section that describes each task of the function. Attribute lists This section is a list of the attribute list functions. azn_attrlist_add_entry() on page 124 azn_attrlist_add_entry_buffer() on page 125 azn_attrlist_add_entry_pobj() on page 126 azn_attrlist_add_entry_ulong() on page 127 azn_attrlist_create() on page 128 azn_attrlist_copy() on page 127 azn_attrlist_delete() on page 129 azn_attrlist_delete_entry() on page 130 azn_attrlist_delete_entry_alue() on page 131 azn_attrlist_get_entry_buffer_alue() on page 132 azn_attrlist_get_entry_type() on page 135 azn_attrlist_get_entry_ulong_alue() on page 136 azn_attrlist_get_entry_pobj_alue() on page 133 azn_attrlist_get_entry_string_alue() on page 134 azn_attrlist_get_names() on page 137 azn_attrlist_name_get_num() on page 138 azn_release_buffer() on page 170 azn_release_pobj() on page 171 azn_release_string() on page 172 azn_release_strings() on page 172 azn_util_handle_is_alid() on page 175 Copyright IBM Corp. 2002, 2012 9