Upload
others
View
5
Download
0
Embed Size (px)
Citation preview
IBM Tivoli Access Manager
Administration C APIDeveloper’s ReferenceVersion 4.1
SC32-1142-01
���
IBM Tivoli Access Manager
Administration C APIDeveloper’s ReferenceVersion 4.1
SC32-1142-01
���
Note:Before using this information and the product it supports, read the information in Appendix D, “Notices”, on page 305.
Fourth Edition (August 2003)
This edition replaces SC32-1142-00.
© Copyright International Business Machines Corporation 2000, 2003. All rights reserved.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.
Contents
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiWho should read this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiWhat this book contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiPublications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Release information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiBase information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiWebSEAL information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiWeb security information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivDeveloper references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivTechnical supplements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvRelated publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvAccessing publications online . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiOrdering publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiContacting software support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiConventions used in this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Typeface conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiiUser registry differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiiOperating system differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Chapter 1. Introducing the administration API . . . . . . . . . . . . . . . . . . . 1Administration API overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Administration API components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Administration API shared libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Administration API application development kit . . . . . . . . . . . . . . . . . . . . . . . 3Building applications with the administration API . . . . . . . . . . . . . . . . . . . . . . . 3
Software requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Linking required libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Tested compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Administration API example program . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Deploying an administration API application . . . . . . . . . . . . . . . . . . . . . . . . 5Gathering problem determination information . . . . . . . . . . . . . . . . . . . . . . . . 5
Enabling tracing on the policy server . . . . . . . . . . . . . . . . . . . . . . . . . . 5Enabling tracing on a system using the runtime component . . . . . . . . . . . . . . . . . . 6Gathering trace and message logs . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Chapter 2. Using the administration API . . . . . . . . . . . . . . . . . . . . . . 7Establishing security contexts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Required input parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Returned objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Example code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Backward compatibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Delegating user credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Creating objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Setting object values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Getting objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Reading object values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Listing object information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Handling errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Evaluating a response object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Obtaining error message text . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Obtaining error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Obtaining error message modifiers . . . . . . . . . . . . . . . . . . . . . . . . . . 15
© Copyright IBM Corp. 2000, 2003 iii
Cleaning up and shutting down . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Freeing memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Deleting a security context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Chapter 3. Administering users and groups . . . . . . . . . . . . . . . . . . . . 17Administering users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Administering user accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Administering user passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Administering groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Administering group attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Chapter 4. Administering protected objects and protected object spaces . . . . . . . 23Administering protected object spaces . . . . . . . . . . . . . . . . . . . . . . . . . . 23Administering protected objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Administering protected object attributes . . . . . . . . . . . . . . . . . . . . . . . . . 25
Chapter 5. Administering access control . . . . . . . . . . . . . . . . . . . . . 27Administering access control lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Administering access control list entries . . . . . . . . . . . . . . . . . . . . . . . . . . 28Administering access control list extended attributes . . . . . . . . . . . . . . . . . . . . . 30Administering action groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Administering extended actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Chapter 6. Administering protected object policies. . . . . . . . . . . . . . . . . 33Administering protected object policy objects . . . . . . . . . . . . . . . . . . . . . . . . 33Administering protected object policy settings . . . . . . . . . . . . . . . . . . . . . . . . 34Administering protected object policy extended attributes . . . . . . . . . . . . . . . . . . . . 35
Chapter 7. Administering single signon resources . . . . . . . . . . . . . . . . . 37Web resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Resource groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Resource credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Chapter 8. Configuring application servers . . . . . . . . . . . . . . . . . . . . 41Configuring application servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Administering replicas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Certificate maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Chapter 9. Administering servers . . . . . . . . . . . . . . . . . . . . . . . . 43Getting and performing administration tasks . . . . . . . . . . . . . . . . . . . . . . . . 43Notifying replica databases when the master authorization database is updated . . . . . . . . . . . . 43
Notifying replica databases automatically . . . . . . . . . . . . . . . . . . . . . . . . 44Notifying replica databases manually . . . . . . . . . . . . . . . . . . . . . . . . . . 44Setting the maximum number of notification threads . . . . . . . . . . . . . . . . . . . . 44Setting the notification wait time . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Administrating servers and database notification . . . . . . . . . . . . . . . . . . . . . . . 45
Chapter 10. Administration C API reference . . . . . . . . . . . . . . . . . . . . 47ivadmin_acl_attrdelkey() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48ivadmin_acl_attrdelval() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49ivadmin_acl_attrget() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50ivadmin_acl_attrlist() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51ivadmin_acl_attrput() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52ivadmin_acl_create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53ivadmin_acl_delete() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54ivadmin_acl_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55ivadmin_acl_getanyother() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56ivadmin_acl_getdescription() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57ivadmin_acl_getgroup() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
iv IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_acl_getid(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59ivadmin_acl_getunauth() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60ivadmin_acl_getuser() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61ivadmin_acl_list() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62ivadmin_acl_listgroups() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63ivadmin_acl_listusers() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64ivadmin_acl_removeanyother() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65ivadmin_acl_removegroup() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66ivadmin_acl_removeunauth() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67ivadmin_acl_removeuser() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68ivadmin_acl_setanyother() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69ivadmin_acl_setdescription(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71ivadmin_acl_setgroup() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72ivadmin_acl_setunauth() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74ivadmin_acl_setuser() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76ivadmin_action_create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78ivadmin_action_create_in_group() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80ivadmin_action_delete() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82ivadmin_action_delete_from_group() . . . . . . . . . . . . . . . . . . . . . . . . . . . 83ivadmin_action_getdescription() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84ivadmin_action_getid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85ivadmin_action_gettype() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86ivadmin_action_group_create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87ivadmin_action_group_delete() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88ivadmin_action_group_list() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89ivadmin_action_list() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90ivadmin_action_list_in_group() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91ivadmin_cfg_addreplica() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92ivadmin_cfg_chgreplica() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93ivadmin_cfg_configureserver2(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94ivadmin_cfg_renewservercert() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96ivadmin_cfg_rmvreplica(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97ivadmin_cfg_setapplicationcert() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98ivadmin_cfg_setkeyringpwd() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99ivadmin_cfg_setlistening() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100ivadmin_cfg_setport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101ivadmin_cfg_setssltimeout() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102ivadmin_cfg_unconfigureserver() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103ivadmin_context_cleardelcred() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104ivadmin_context_create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105ivadmin_context_createdefault() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107ivadmin_context_delete() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108ivadmin_context_getaccexpdate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109ivadmin_context_getdisabletimeint() . . . . . . . . . . . . . . . . . . . . . . . . . . . 110ivadmin_context_getmaxlgnfails(). . . . . . . . . . . . . . . . . . . . . . . . . . . . 111ivadmin_context_getmaxpwdage() . . . . . . . . . . . . . . . . . . . . . . . . . . . 112ivadmin_context_getmaxpwdrepchars() . . . . . . . . . . . . . . . . . . . . . . . . . . 113ivadmin_context_getminpwdalphas() . . . . . . . . . . . . . . . . . . . . . . . . . . 114ivadmin_context_getminpwdnonalphas() . . . . . . . . . . . . . . . . . . . . . . . . . 115ivadmin_context_getminpwdlen(). . . . . . . . . . . . . . . . . . . . . . . . . . . . 116ivadmin_context_getpwdspaces() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117ivadmin_context_gettodaccess() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118ivadmin_context_getuserreg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119ivadmin_context_setaccexpdate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120ivadmin_context_setdelcred() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121ivadmin_context_setdisabletimeint() . . . . . . . . . . . . . . . . . . . . . . . . . . . 122ivadmin_context_setmaxlgnfails(). . . . . . . . . . . . . . . . . . . . . . . . . . . . 123ivadmin_context_setmaxpwdage() . . . . . . . . . . . . . . . . . . . . . . . . . . . 124ivadmin_context_setmaxpwdrepchars() . . . . . . . . . . . . . . . . . . . . . . . . . . 125ivadmin_context_setminpwdalphas() . . . . . . . . . . . . . . . . . . . . . . . . . . 126ivadmin_context_setminpwdnonalphas() . . . . . . . . . . . . . . . . . . . . . . . . . 127
Contents v
ivadmin_context_setminpwdlen() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128ivadmin_context_setpwdspaces() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129ivadmin_context_settodaccess() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130ivadmin_free() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131ivadmin_group_addmembers() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132ivadmin_group_create2() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133ivadmin_group_delete2() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135ivadmin_group_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136ivadmin_group_getbydn() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137ivadmin_group_getcn() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138ivadmin_group_getdescription() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139ivadmin_group_getdn() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140ivadmin_group_getid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141ivadmin_group_getmembers() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142ivadmin_group_import2() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143ivadmin_group_list() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144ivadmin_group_listbydn() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145ivadmin_group_removemembers() . . . . . . . . . . . . . . . . . . . . . . . . . . . 147ivadmin_group_setdescription() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148ivadmin_objectspace_create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149ivadmin_objectspace_delete() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151ivadmin_objectspace_list() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152ivadmin_pop_attach() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153ivadmin_pop_attrdelkey() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154ivadmin_pop_attrdelval() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155ivadmin_pop_attrget() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156ivadmin_pop_attrlist() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157ivadmin_pop_attrput() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158ivadmin_pop_create(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159ivadmin_pop_delete() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160ivadmin_pop_detach() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161ivadmin_pop_find() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162ivadmin_pop_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163ivadmin_pop_getanyothernw() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164ivadmin_pop_getauditlevel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165ivadmin_pop_getdescription() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166ivadmin_pop_getid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167ivadmin_pop_getipauth() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168ivadmin_pop_getqop() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169ivadmin_pop_gettod() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170ivadmin_pop_getwarnmode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172ivadmin_pop_list() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173ivadmin_pop_removeipauth() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174ivadmin_pop_setanyothernw(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175ivadmin_pop_setanyothernw_forbidden() . . . . . . . . . . . . . . . . . . . . . . . . . 176ivadmin_pop_setauditlevel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177ivadmin_pop_setdescription() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178ivadmin_pop_setipauth() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179ivadmin_pop_setipauth_forbidden() . . . . . . . . . . . . . . . . . . . . . . . . . . . 180ivadmin_pop_setqop() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181ivadmin_pop_settod() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182ivadmin_pop_setwarnmode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184ivadmin_protobj_attachacl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185ivadmin_protobj_attrdelkey() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186ivadmin_protobj_attrdelval() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187ivadmin_protobj_attrget() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188ivadmin_protobj_attrlist() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189ivadmin_protobj_attrput() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190ivadmin_protobj_create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191ivadmin_protobj_delete() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192ivadmin_protobj_detachacl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
vi IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_protobj_get2() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194ivadmin_protobj_getacl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196ivadmin_protobj_getdesc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197ivadmin_protobj_getid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198ivadmin_protobj_getpolicyattachable() . . . . . . . . . . . . . . . . . . . . . . . . . . 199ivadmin_protobj_getpop() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200ivadmin_protobj_gettype() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201ivadmin_protobj_list3() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202ivadmin_protobj_listbyacl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204ivadmin_protobj_setdesc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205ivadmin_protobj_setname() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206ivadmin_protobj_setpolicyattachable() . . . . . . . . . . . . . . . . . . . . . . . . . . 207ivadmin_protobj_settype() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208ivadmin_response_getcode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209ivadmin_response_getcount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210ivadmin_response_getmessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211ivadmin_response_getmodifier() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212ivadmin_response_getok() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213ivadmin_server_gettasklist() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214ivadmin_server_performtask() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216ivadmin_server_replicate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218ivadmin_ssocred_create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219ivadmin_ssocred_delete() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220ivadmin_ssocred_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221ivadmin_ssocred_getid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222ivadmin_ssocred_getssopassword() . . . . . . . . . . . . . . . . . . . . . . . . . . . 223ivadmin_ssocred_getssouser() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224ivadmin_ssocred_gettype() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225ivadmin_ssocred_getuser() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226ivadmin_ssocred_list() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227ivadmin_ssocred_set() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228ivadmin_ssogroup_addres() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229ivadmin_ssogroup_create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230ivadmin_ssogroup_delete() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231ivadmin_ssogroup_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232ivadmin_ssogroup_getdescription() . . . . . . . . . . . . . . . . . . . . . . . . . . . 233ivadmin_ssogroup_getid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234ivadmin_ssogroup_getresources() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235ivadmin_ssogroup_list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236ivadmin_ssogroup_removeres() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237ivadmin_ssoweb_create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238ivadmin_ssoweb_delete() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239ivadmin_ssoweb_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240ivadmin_ssoweb_getdescription(). . . . . . . . . . . . . . . . . . . . . . . . . . . . 241ivadmin_ssoweb_getid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242ivadmin_ssoweb_list() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243ivadmin_user_create3() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244ivadmin_user_delete2() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246ivadmin_user_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247ivadmin_user_getaccexpdate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248ivadmin_user_getaccountvalid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249ivadmin_user_getbydn() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250ivadmin_user_getcn(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251ivadmin_user_getdescription() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252ivadmin_user_getdisabletimeint() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253ivadmin_user_getdn() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254ivadmin_user_getid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255ivadmin_user_getmaxlgnfails() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256ivadmin_user_getmaxpwdage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257ivadmin_user_getmaxpwdrepchars(). . . . . . . . . . . . . . . . . . . . . . . . . . . 258ivadmin_user_getmemberships() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Contents vii
ivadmin_user_getminpwdalphas() . . . . . . . . . . . . . . . . . . . . . . . . . . . 260ivadmin_user_getminpwdlen() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261ivadmin_user_getminpwdnonalphas() . . . . . . . . . . . . . . . . . . . . . . . . . . 262ivadmin_user_getpasswordvalid() . . . . . . . . . . . . . . . . . . . . . . . . . . . 263ivadmin_user_getpwdspaces() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264ivadmin_user_getsn() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265ivadmin_user_getssouser() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266ivadmin_user_gettodaccess() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267ivadmin_user_import2() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268ivadmin_user_list() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269ivadmin_user_listbydn() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271ivadmin_user_setaccexpdate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272ivadmin_user_setaccountvalid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273ivadmin_user_setdescription() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274ivadmin_user_setdisabletimeint() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275ivadmin_user_setmaxlgnfails(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276ivadmin_user_setmaxpwdage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277ivadmin_user_setmaxpwdrepchars() . . . . . . . . . . . . . . . . . . . . . . . . . . . 278ivadmin_user_setminpwdalphas() . . . . . . . . . . . . . . . . . . . . . . . . . . . 279ivadmin_user_setminpwdlen(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280ivadmin_user_setminpwdnonalphas() . . . . . . . . . . . . . . . . . . . . . . . . . . 281ivadmin_user_setpassword() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282ivadmin_user_setpasswordvalid() . . . . . . . . . . . . . . . . . . . . . . . . . . . 283ivadmin_user_setpwdspaces() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284ivadmin_user_setssouser() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285ivadmin_user_settodaccess() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Appendix A. Deprecated APIs . . . . . . . . . . . . . . . . . . . . . . . . . 287
Appendix B. User registry differences . . . . . . . . . . . . . . . . . . . . . . 289
Appendix C. Administration C API, Java method, and command line equivalents . . . 293
Appendix D. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
viii IBM Tivoli Access Manager: Administration C API Developer’s Reference
Tables
1. Shared libraries . . . . . . . . . . . 22. Administration API application developer kit
files . . . . . . . . . . . . . . . 33. Compilers tested with Tivoli Access Manager 44. Creating objects . . . . . . . . . . . 105. Example set operations. . . . . . . . . 106. Example data types returned by get functions 117. Example read operations . . . . . . . . 128. Administrating users . . . . . . . . . 189. Administrating user accounts . . . . . . 19
10. Administrating user passwords . . . . . . 2011. Administering groups . . . . . . . . . 2112. Administering group attributes . . . . . . 2113. Administering protected object spaces. . . . 2414. Administering protected objects . . . . . . 2415. Administering protected object attributes 2516. Administering access control lists . . . . . 2817. Administering access control list entries 2918. Administering access control list extended
attributes . . . . . . . . . . . . . 3019. Administering action groups . . . . . . . 3020. Administering extended actions . . . . . . 3121. Administering protected object policy objects 3322. Administering protected object policy settings 3523. Administering protected object policy
extended attributes . . . . . . . . . . 35
24. Administering Web resources . . . . . . 3825. Administering resource groups . . . . . . 3826. Administering credentials . . . . . . . . 3927. Configuring application servers . . . . . . 4128. Administering replicas . . . . . . . . . 4229. Certificate maintenance . . . . . . . . 4230. Administrating servers and database
notification. . . . . . . . . . . . . 4531. Supported object types . . . . . . . . 14932. Protected object policy default values 15933. Descriptions of audit levels . . . . . . . 16534. APIs deprecated in Tivoli Access Manager
Version 4.1 . . . . . . . . . . . . 28735. APIs deprecated in previous versions of
Tivoli Access Manager and Tivoli SecureWayPolicy Director . . . . . . . . . . . 287
36. User registry differences when adding aduplicate user to a group . . . . . . . 290
37. User registry differences when removing auser from a group who is not a member ofthe group . . . . . . . . . . . . . 290
38. Maximum lengths for names based on userregistry . . . . . . . . . . . . . 291
39. Mapping between administration C API, Javamethods, and the command line interface . . 294
© Copyright IBM Corp. 2000, 2003 ix
x IBM Tivoli Access Manager: Administration C API Developer’s Reference
Preface
IBM® Tivoli® Access Manager (Tivoli Access Manager) is the base software that isrequired to run applications in the IBM Tivoli Access Manager product suite. Itenables the integration of IBM Tivoli Access Manager applications that provide awide range of authorization and management solutions. Sold as an integratedsolution, these products provide an access control management solution thatcentralizes network and application security policy for e-business applications.
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, themanagement server is now referred to as the policy server.
This reference contains information about how to use Tivoli Access Manager Cadministration API to enable an application to programmatically perform TivoliAccess Manager administration tasks. This document describes the Cimplementation of the Tivoli Access Manager administration API. See the IBMTivoli Access Manager Administration Java Classes Developer’s Reference for informationregarding the Java™ implementation of these APIs.
Information on the pdadmin command line interface (CLI) can be found in theIBM Tivoli Access Manager Command Reference.
Who should read this bookThis reference is for application programmers implementing programs in the Cprogramming language to administer the users and objects associated with theIBM Tivoli Access Manager product.
Readers should be familiar with the following:v PC and UNIX® operating systemsv Database architecture and conceptsv Security managementv Internet protocols, including HTTP, TCP/IP, File Transfer Protocol (FTP), and
Telnetv The user registry that Tivoli Access Manager is configured to usev Lightweight Directory Access Protocol (LDAP) and directory services, if used by
your user registryv 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 reference contains the following chapters and appendixes:v Chapter 1, “Introducing the administration API”, on page 1
© Copyright IBM Corp. 2000, 2003 xi
Provides an overview of the administration API and its components. It alsocovers building applications with the API and deploying an administration APIprogram.
v Chapter 2, “Using the administration API”, on page 7Each application that uses the administration API must perform certain tasksnecessary for API initialization, shut down, cleanup, memory management, anderror handling. This chapter describes the supported functions for establishingsecurity contexts, creating objects, setting object values, reading object values,listing object information, deleting objects, handling errors, administratingpolicies, cleaning up, and shutting down.
v Chapter 3, “Administering users and groups”, on page 17The administration API provides a collection of methods for administering TivoliAccess Manager users and groups. This chapter describes the tasks that thosefunctions accomplish. It describes the supported functions for administeringusers, user accounts, user passwords, groups, group attributes, and the policiesassociated with users.
v Chapter 4, “Administering protected objects and protected object spaces”, onpage 23This chapter describes the administration API functions that are used toadminister protected object spaces and protected objects. It describes thesupported functions for administering protected object spaces, protected objects,and protected object attributes.
v Chapter 5, “Administering access control”, on page 27This chapter describes the administration API functions that are used toadminister access control. It describes the supported functions for administeringaccess control lists, access control list permissions, access control list extendedattributes, extended actions, and action groups.
v Chapter 6, “Administering protected object policies”, on page 33This chapter describes the administration API functions that are used to create,modify, examine, and delete protected object policies. It also discusses attachingor detaching protected objects from protected object policies. It describes thesupported functions for administering protected object policy objects, protectedobject policy settings, and protected object policy extended attributes.
v Chapter 7, “Administering single signon resources”, on page 37This chapter provides instructions for using the administration API to create,modify, or delete web resources, resource groups, and resource credentials.
v Chapter 9, “Administering servers”, on page 43This chapter provides information about getting and performing administrationtasks and notifying the replica database when the master authorization databaseis updated.
v Chapter 8, “Configuring application servers”, on page 41This chapter provides instructions for using the administration API to configureservers, modify server configurations, administer replicas, and performcertificate maintenance.
v Chapter 10, “Administration C API reference”, on page 47This chapter provides detailed information about specific commands in theadministration API.
v Appendix A, “Deprecated APIs”, on page 287This appendix provides a list of the APIs that have been deprecated in thisversion of Tivoli Access Manager.
v Appendix B, “User registry differences”, on page 289
xii IBM Tivoli Access Manager: Administration C API Developer’s Reference
This appendix outlines the differences in behavior of the APIs based on the userregistry being used by Tivoli Access Manager.
v Appendix C, “Administration C API, Java method, and command lineequivalents”, on page 293This appendix shows the mapping that exists between the Administration CAPIs, the Administration Java classes and methods, and the command lineinterface (CLI).
v Appendix D, “Notices”, on page 305This appendix provides copyright, legal, and trademark information.
PublicationsThe Tivoli Access Manager library is organized into the following categories:v “Release information”v “Base information”v “WebSEAL information”v “Web security information” on page xivv “Developer references” on page xivv “Technical supplements” on page xv
Release informationv IBM Tivoli Access Manager Read Me First Card
GI11-4198-00 (am41_readme.pdf)Provides information for installing and getting started using Tivoli AccessManager.
v IBM Tivoli Access Manager Release NotesSC32-1130-00 (am41_relnotes.pdf)Provides late-breaking information, such as software limitations, workarounds,and documentation updates.
Base informationv IBM Tivoli Access Manager Base Installation Guide
SC32-1131-01 (am41_install.pdf)Explains how to install, configure, and upgrade Tivoli Access Manager software,including the Web Portal Manager interface.
v IBM Tivoli Access Manager Base Administrator’s GuideSC32-1132-01 (am41_admin.pdf)Describes the concepts and procedures for using Tivoli Access Manager services.Provides instructions for performing tasks from the Web Portal Managerinterface and by using the pdadmin command.
WebSEAL informationv IBM Tivoli Access Manager WebSEAL Installation Guide
SC32-1133-01 (amweb41_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 GuideSC32-1134-01 (amweb41_admin.pdf)
Preface xiii
Provides background material, administrative procedures, and technicalreference information for using WebSEAL to manage the resources of yoursecure Web domain.
Web security informationv IBM Tivoli Access Manager for WebSphere Application Server User’s Guide
SC32-1136-01 (amwas41_user.pdf)Provides installation, removal, and administration instructions for Tivoli AccessManager for IBM WebSphere® Application Server.
v IBM Tivoli Access Manager for WebLogic Server User’s GuideSC32-1137-01 (amwls41_user.pdf)Provides installation, removal, and administration instructions for Tivoli AccessManager for BEA WebLogic Server.
v IBM Tivoli Access Manager Plug-in for Edge Server User’s GuideSC32-1138-01 (amedge41_user.pdf)Describes how to install, configure, and administer the plug-in for IBMWebSphere Edge Server application.
v IBM Tivoli Access Manager Plug-in for Web Servers User’s GuideSC32-1139-01 (amws41_user.pdf)Provides installation instructions, administration procedures, and technicalreference information for securing your Web domain using the plug-in for Webservers.
Developer referencesv IBM Tivoli Access Manager Authorization C API Developer’s Reference
SC32-1140-01 (am41_authC_devref.pdf)Provides reference material that describes how to use the Tivoli Access Managerauthorization C API and the Access Manager service plug-in interface to addTivoli Access Manager security to applications.
v IBM Tivoli Access Manager Authorization Java Classes Developer’s ReferenceSC32-1141-01 (am41_authJ_devref.pdf)Provides reference information for using the Java™ language implementation ofthe authorization API to enable an application to use Tivoli Access Managersecurity.
v IBM Tivoli Access Manager Administration C API Developer’s ReferenceSC32-1142-01 (am41_adminC_devref.pdf)Provides reference information about using the administration API to enable anapplication to perform Tivoli Access Manager administration tasks. Thisdocument describes the C implementation of the administration API.
v IBM Tivoli Access Manager Administration Java Classes Developer’s ReferenceSC32-1143-01 (am41_adminJ_devref.pdf)Provides reference information for using the Java language implementation ofthe administration API to enable an application to perform Tivoli AccessManager administration tasks.
v IBM Tivoli Access Manager WebSEAL Developer’s ReferenceSC32-1135-01 (amweb41_devref.pdf)Provides administration and programming information for the Cross-domainAuthentication Service (CDAS), the Cross-domain Mapping Framework (CDMF),and the Password Strength Module.
xiv IBM Tivoli Access Manager: Administration C API Developer’s Reference
Technical supplementsv IBM Tivoli Access Manager Command Reference
GC32-1107-01 (am41_cmdref.pdf)Provides information about the command line utilities and scripts provided withTivoli Access Manager.
v IBM Tivoli Access Manager Error Message ReferenceSC32-1144-01 (am41_error_ref.pdf)Provides explanations and recommended actions for the messages produced byTivoli Access Manager.
v IBM Tivoli Access Manager Problem Determination GuideGC32-1106-01 (am41_pdg.pdf)Provides problem determination information for Tivoli Access Manager.
v IBM Tivoli Access Manager Performance Tuning GuideSC32-1145-01 (am41_perftune.pdf)Provides performance tuning information for an environment consisting of TivoliAccess Manager with the IBM Directory server defined as the user registry.
Related publicationsThis section lists publications related to the Tivoli Access Manager library.
The Tivoli Software Library provides a variety of Tivoli publications such as whitepapers, datasheets, demonstrations, redbooks, and announcement letters. The TivoliSoftware Library is available on the Web at:http://www.ibm.com/software/tivoli/library/
The Tivoli Software Glossary includes definitions for many of the technical termsrelated to Tivoli software. The Tivoli Software Glossary is available, in English only,from the Glossary link on the left side of the Tivoli Software Library Web pagehttp://www.ibm.com/software/tivoli/library/
IBM Global Security ToolkitTivoli Access Manager provides data encryption through the use of the IBM GlobalSecurity Toolkit (GSKit). GSKit is included on the IBM Tivoli Access Manager BaseCD for your particular platform.
The GSKit package installs the iKeyman key management utility, gsk5ikm, whichenables you to create key databases, public-private key pairs, and certificaterequests. The following document is available on the Tivoli Information CenterWeb site in the same section as the IBM Tivoli Access Manager productdocumentation:v Secure Sockets Layer Introduction and iKeyman User’s Guide
(gskikm5c.pdf)Provides information for network or system security administrators who plan toenable SSL communication in their Tivoli Access Manager environment.
IBM DB2 Universal DatabaseIBM DB2® Universal Database™ is required when installing IBM Directory Server,z/OS™, and OS/390® LDAP servers. DB2 is provided on the product CDs for thefollowing operating system platforms:v IBM AIX®
v Microsoft™ Windows™
v Sun Solaris Operating Environment
Preface xv
DB2 information is available at:
http://www.ibm.com/software/data/db2/
IBM Directory ServerIBM Directory Server, Version 4.1, is included on the IBM Tivoli Access ManagerBase CD for all platforms except Linux for zSeries™. You can obtain the IBMDirectory Server software for Linux for S/390 at:
http://www.ibm.com/software/network/directory/server/download/
If you plan to use IBM Directory Server as your user registry, see the informationprovided at:
http://www.ibm.com/software/network/directory/library/
IBM WebSphere Application ServerIBM WebSphere Application Server, Advanced Single Server Edition 4.0.3, isincluded on the Web Portal Manager CDs and installed with the Web PortalManager interface. For information about IBM WebSphere Application Server, see:
http://www.ibm.com/software/webservers/appserv/infocenter.html
IBM Tivoli Access Manager for Business IntegrationIBM Tivoli Access Manager for Business Integration, available as a separatelyorderable product, provides a security solution for IBM MQSeries®, Version 5.2,and IBM WebSphere® MQ for Version 5.3 messages. IBM Tivoli Access Manager forBusiness Integration allows WebSphere MQSeries applications to send data withprivacy and integrity by using keys associated with sending and receivingapplications. Like WebSEAL and IBM Tivoli Access Manager for OperatingSystems, IBM Tivoli Access Manager for Business Integration, is one of theresource managers that use the authorization services of IBM Tivoli AccessManager for e-business.
The following documents associated with IBM Tivoli Access Manager for BusinessIntegration Version 4.1 are available on the Tivoli Information Center Web site:v IBM Tivoli Access Manager for Business Integration Administrator’s Guide
(SC23-4831-00)v IBM Tivoli Access Manager for Business Integration Release Notes (GI11-0957-00)v IBM Tivoli Access Manager for Business Integration Read Me First (GI11-0958-00)
IBM Tivoli Access Manager for Operating SystemsIBM Tivoli Access Manager for Operating Systems, available as a separatelyorderable product, provides a layer of authorization policy enforcement on UNIXsystems in addition to that provided by the native operating system. IBM TivoliAccess Manager for Operating Systems, like WebSEAL and IBM Tivoli AccessManager for Business Integration, is one of the resource managers that use theauthorization services of IBM Tivoli Access Manager for e-business.
The following documents associated with IBM Tivoli Access Manager forOperating Systems Version 4.1 are available on the Tivoli Information Center Website:v IBM Tivoli Access Manager for Operating Systems Installation Guide (SC23-4829-00)v IBM Tivoli Access Manager for Operating Systems Administration Guide
(SC23-4827-00)
xvi IBM Tivoli Access Manager: Administration C API Developer’s Reference
v IBM Tivoli Access Manager for Operating Systems Problem Determination Guide(SC23-4828-00)
v IBM Tivoli Access Manager for Operating Systems Release Notes (GI11-0951-00)v IBM Tivoli Access Manager for Operating Systems Read Me First (GI11-0949-00)
Accessing publications onlineThe publications for this product are available online in Portable Document Format(PDF) or Hypertext Markup Language (HTML) format, or both in the TivoliSoftware Library: http://www.ibm.com/software/tivoli/library
To locate product publications in the library, click the Product manuals link on theleft side of the Library page. Then, locate and click the name of the product on theTivoli Software Information Center page.
Product publications include release notes, installation guides, user’s guides,administrator’s guides, and developer’s references.
Note: To ensure proper printing of PDF publications, select the Fit to page checkbox in the Adobe Acrobat Print window (which is available when you clickFile →Print).
Ordering publicationsYou can order many IBM Tivoli publications online at:http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi
You can also order by telephone:v In the United States: 800-879-2755v In Canada: 800-426-4968v In other countries, for a list of telephone numbers, see
http://www.ibm.com/software/tivoli/order-lit/
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 also canuse the keyboard instead of the mouse to operate all features of the graphical userinterface.
Contacting software supportBefore contacting IBM Tivoli Software support with a problem, refer to the IBMTivoli Software support Web site at:http://www.ibm.com/software/sysmgmt/products/support/
If you need additional help, contact software support by using the methodsdescribed in the IBM Software Support Guide at the following Web site:http://techsupport.services.ibm.com/guides/handbook.html
The guide provides the following information:v Registration and eligibility requirements for receiving support
Preface xvii
v Telephone numbers and e-mail addresses, depending on the country in whichyou are located
v A list of information you should gather before contacting customer support
Conventions used in this bookThis reference uses several conventions for special terms and actions and foroperating system-dependent commands and paths.
Typeface conventionsThe following typeface conventions are used in this reference:
Bold Lowercase commands or mixed case commands that are difficult todistinguish from surrounding text, keywords, parameters, options, namesof Java classes, and objects are in bold.
Italic Variables, titles of publications, and special words or phrases that areemphasized are in italic.
MonospaceCode examples, command lines, screen output, file and directory namesthat are difficult to distinguish from surrounding text, system messages,text that the user must type, and values for arguments or commandoptions are in monospace.
User registry differencesTivoli Access Manager supports a number of different user registries. In mostcases, the behavior of Tivoli Access Manager is the same regardless of what userregistry is in use. However, there are several cases where the processing of a givenfunction differs based on what user registry is being used. A note similar to thefollowing highlights these differences:
User registry difference: This text would describe the different behavior based onthe user registry in use.
See Appendix B, “User registry differences”, on page 289 for a complete list ofknown differences.
Operating system differencesThis book uses the UNIX convention for specifying environment variables and fordirectory notation. When using the Windows command line, replace $variable with%variable% for environment variables and replace each forward slash (/) with abackslash (\) in directory paths. If you are using the bash shell on a Windowssystem, you can use the UNIX conventions.
xviii IBM Tivoli Access Manager: Administration C API Developer’s Reference
Chapter 1. Introducing the administration API
The IBM Tivoli Access Manager (Tivoli Access Manager) administration APIcomponent provides a set of functions for the administration of Tivoli AccessManager users and data objects. The API provides a way for applications toadminister users, groups, protected objects, access control lists, protected objectpolicies, and Web resources.
You can use the Tivoli Access Manager application developer kit (ADK) componentto enable your application to programmatically administer Tivoli Access Managerusers and data.
This chapter contains the following topics:v “Administration API overview”v “Administration API components” on page 2v “Building applications with the administration API” on page 3v “Administration API example program” on page 4v “Deploying an administration API application” on page 5
Note: Due to a compiler problem, existing Tivoli SecureWay Policy Director,Version 3.8 applications compiled on the Sun Solaris Operating Environmentmust be recompiled using the Tivoli Access Manager libraries. Backwardcompatibility is maintained on all the other supported platforms.
Administration API overviewYou can use the administration API to administer the following types of objects:v Policiesv Usersv Groupsv Access control lists (ACLs)v Extended ACL actionsv Protected object policies (POPs)v Protected objectsv Protected object spacesv Web resourcesv Web resource groupsv Resource credentials
The administration API provides a set of functions for creating, modifying,examining, and deleting each of the preceding object types. The API also definesdata types to represent each object type. The API includes the function callsnecessary for manipulating each of the data types.
The administration API communicates directly with the Tivoli Access Managerpolicy server component. The API establishes an authenticated, Secure SocketsLayer (SSL) session with the Tivoli Access Manager policy server process. Whenthe SSL session is established, the API can send administration requests to thepolicy server.
© Copyright IBM Corp. 2000, 2003 1
The Tivoli Access Manager policy server component services these requests in thesame manner that it would service any other incoming requests.
System administrators also can use the pdadmin and svrsslcfg command lineinterfaces to accomplish Tivoli Access Manager administration tasks. Theadministration API functions map closely to these commands. Appendix C,“Administration C API, Java method, and command line equivalents”, on page 293describes the commands that match administration API functions. Someadministration API functions do not have a pdadmin or svrsslcfg command lineequivalent.
Administration API componentsThe administration API consists of the following components:v The administration API shared libraryv The administration API header filev The administration API library to link against (Microsoft® Windows® only)v A demonstration applicationv Makefiles for the demonstration application
Note: The administration APIs are 32-bit only. When running on operating systemsthat support 64-bit addressing, ensure that the administration APIs areinvoked in 32-bit compatibility mode.
The administration API shared libraries are distributed in the Tivoli AccessManager runtime environment for each platform. The remainder of theadministration API components are distributed in the Tivoli Access Manager ADKcomponent.
The following sections provide more information about the shared libraries andADK.
Administration API shared librariesThe administration API shared library is distributed in the Tivoli Access Managerruntime environment component. The administration APIs are 32-bit only. Whenrunning on operating systems that support 64-bit addressing, ensure that theadministration APIs are invoked in 32-bit compatibility mode. Table 1 lists thenames of the shared libraries on each platform.
Table 1. Shared libraries
Platform Shared Library Name
Solaris Operating Environment libpdadminapi.so
IBM® AIX® libpdadminapi.a
Hewlett-Packard HP-UX libpdadminapi.sl
Microsoft Windows pdadminapi.dll
Linux libpdadminapi.so
Note: Due to a compiler problem, existing Tivoli SecureWay Policy Director,Version 3.8 applications compiled on the Sun Solaris Operating Environmentmust be recompiled using the Tivoli Access Manager libraries. Backwardcompatibility is maintained on all the other supported platforms.
2 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Administration API application development kitThe ADK files are installed as part of the Tivoli Access Manager ADK componentpackage.
The ADK component contains files that can be placed anywhere on your system.Table 2 lists the files and suggests an installation directory (beneath the TivoliAccess Manager installation directory) for each file.
Table 2. Administration API application developer kit files
Suggested Directory File to Install File Description
include ivadminapi.h The C header file containing theadministration API functiondeclarations.
include ivadmin_deprecated.h The C header file containing theprototypes and declarations for thefunctions, variables, and attributesthat are deprecated in this version ofTivoli Access Manager.
Avoid including this header file asthe symbols provided in it will beremoved in a future release of theproduct.
lib pdadminapi.lib The library against which to link onthe Microsoft Windows platform.
admin_demo pdadminapi_demo.cMakefileREADME.pdadminapi
This ADK provides a demonstrationprogram and a sample makefile foreach supported platform. You canplace the demonstration program inany directory. The readme fileexplains how to build thedemonstration program.
Building applications with the administration APITo develop applications that use the Tivoli Access Manager administration API,you must install the required software and then link using the proper libraries.
Software requirementsYou must install and configure an Tivoli Access Manager secure domain. If you donot have an Tivoli Access Manager secure domain installed, install one beforebeginning application development. The minimum installation consists of a singlesystem with the following Tivoli Access Manager base components installed:v Tivoli Access Manager runtime environmentv Tivoli Access Manager policy serverv Tivoli Access Manager ADK
All systems in the Tivoli Access Manager secure domain that have the runtimeenvironment installed must have the IBM Global Security Toolkit (GSKit)component installed on them as well. If the policy server is using an LDAP orLotus Domino server as the user registry, the IBM SecureWay Directory client alsomust be installed on the system.
Chapter 1. Introducing the administration API 3
For detailed installation instructions, refer to the section of the IBM Tivoli AccessManager Base Installation Guide relating to your operating system platform.
If you already have an Tivoli Access Manager secure domain installed and want toadd a development system to the domain, the minimum Tivoli Access Managerinstallation consists of the following components:v Tivoli Access Manager runtime environmentv Tivoli Access Manager ADK
Linking required librariesTo compile applications that use the administration API, you must install the TivoliAccess Manager Application Developer Kit (ADK) component on the buildmachine.
When compiling your application on Windows systems, make sure that you addthe include directory for the Windows library to the compiler command line.
When linking your application, specify the directory containing the administrationAPI shared library if it is not in the default location. You must explicitly linkagainst the shared library.
Tested compilersIBM has tested the use of the Tivoli Access Manager Application Developer Kit(ADK) component with the compilers listed in Table 3. Previous versions of thecompilers listed are not supported. Compilers on other supported platforms, suchas IBM AIX 5.1 or HP-UX 11i, have not been tested.
Table 3. Compilers tested with Tivoli Access Manager
Operating system platform tested Tested compiler
IBM AIX 4.3.3 xlC.3.6.7
Sun Solaris Operating Environment 7 Forte 6.1
Hewlett-Packard HP-UX 11.0 aCC 3.30a
Red Hat Linux for Intel GNU GCC 2.95.3 (seeNote)
SuSE Linux Enterprise Server 7 for S/390 and zSeries GNU GCC 2.95.3 (seeNote)
Microsoft Windows NT 4.0Microsoft Windows 2000 Advanced Server
MSVC 6.0.5
Note: The GNU GCC compiler listed is the only one supported on Linux systems.The GNU GCC compiler is not supported on non-Linux operating systems.
Administration API example programThe Tivoli Access Manager administration API ADK includes source for anexample program that demonstrates use of the administration API.
The example program demonstrates how to perform the following tasks:v Initialize an administration API security contextv Display an error messagev Create a new Tivoli Access Manager user
4 IBM Tivoli Access Manager: Administration C API Developer’s Reference
v Set a user account to be validv Change the password of the new userv Create a new groupv Add the new user to the groupv Delete a groupv Delete a userv Delete the administration API security context
See the sample makefile supplied with the sample program for build instructionsspecific to each supported operating system platform.
Deploying an administration API applicationApplications that have been developed with the Tivoli Access Manageradministration API must be run on systems that are configured as part of an TivoliAccess Manager secure domain.
To run an administration API application, you must have installed the TivoliAccess Manager runtime environment.
The Tivoli Access Manager runtime environment requires that the IBM SecureWayDirectory client be installed on the application deployment system if an LDAP orLotus Domino server is being used as the user registry.
Administration API applications use the SSL protocol to communicate with theTivoli Access Manager policy server. IBM Global Security Toolkit provides thenecessary SSL support. The IBM Global Security Toolkit is installed as part of theproduct installation.
Note: The Tivoli Access Manager runtime environment installation enforcesinstallation of the required software. For installation instructions, see theappropriate section in the IBM Tivoli Access Manager Base Installation Guidefor your operating system.
Gathering problem determination informationWhen developing an administratiapplication, you might encounter a problem withTivoli Access Manager. To assist Tivoli support personnel in diagnosing yourproblem, gather problem determination information relating to your error.
Tivoli Access Manager components can be configured to log information to one ormore trace files. You can enable tracing for the policy server, or any system usingthe Tivoli Access Manager runtime environment.
Enabling tracing on the policy serverTo enable tracing on the policy server, edit the /etc/routing file, located in theinstallation directory for the Tivoli Access Manager policy server, and uncommentthe last line.
Shut down and restart the policy server daemon, pdmgrd.
Chapter 1. Introducing the administration API 5
Enabling tracing on a system using the runtime componentTo enable tracing on the system where the error is occurring, edit the /etc/routingfile, located in the installation directory for the Tivoli Access Manager runtimecomponent, and uncomment the last line.
Restart the application that encountered the error, or re-enter the pdadmincommand that failed. After the failure occurs again, gather the trace logs asoutlined in the next section.
Gathering trace and message logsTrace and message log files for the policy server, and Tivoli Access Managerruntime environment are written to the /log directory in the Tivoli AccessManager installation directory. To determine the names of the trace log files, youneed to determine the process identifier, or PID, of the Tivoli Access Managerprocess.
Determine the PID for the policy or authorization server by checking theivmgrd.pid file:cat ivmgrd.pid
After determining the PID, look in the AM_BASE/log directory for trace files withnames of the form: PID.trace.log.*. Also collect the following message files in thesame directory::notice*.logfatal*.logwarning*.logerror*.log
6 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Chapter 2. Using the administration API
Each application that uses the administration API must perform certain tasksnecessary for API initialization, cleanup, memory management, and error handling.
The administration API provides functions for each of these tasks.
The following sections in this chapter describe the supported functions:v “Establishing security contexts”v “Creating objects” on page 9v “Setting object values” on page 10v “Getting objects” on page 11v “Reading object values” on page 11v “Listing object information” on page 12v “Handling errors” on page 13v “Cleaning up and shutting down” on page 15
Establishing security contextsTo use the administration API, you must first establish a Secure Sockets Layer(SSL) connection between the administration API application and the IBM TivoliAccess Manager (Tivoli Access Manager) policy server. The administration APIrefers to this connection as a security context.
The security context provides for the secure transfer of requests and data betweenthe administration API application and the Tivoli Access Manager policy server.
Call the function ivadmin_context_createdefault() to create a context with thedefault SSL configuration. The default SSL configuration is the SSL configurationused by the Tivoli Access Manager policy server.
The function ivadmin_context_createdefault() automatically accesses the followingTivoli Access Manager policy server configuration information:v SSL key-ring file locationv SSL key-ring stash file locationv Tivoli Access Manager policy server host namev Tivoli Access Manager policy server listening port
When ivadmin_context_createdefault() is run on the same system as the TivoliAccess Manager policy server, the preceding information is obtained from TivoliAccess Manager configuration files.
When ivadmin_context_createdefault() is run on another system in the TivoliAccess Manager secure domain—a system that does not run the Tivoli AccessManager policy server—the preceding information is obtained from storedinformation that was provided by the system administrator when the Tivoli AccessManager runtime environment was configured.
This following sections further describe how to create a security context.
© Copyright IBM Corp. 2000, 2003 7
Required input parametersYou must provide the following information as input parameters when you callivadmin_context_createdefault ():v The administrative user ID to use when authenticating
The user ID is the Tivoli Access Manager user ID. Tivoli Access Manager usesthe underlying user registry to maintain this information.
v The password for the administratorThe administrative user ID and password must be established before callingivadmin_context_createdefault(). The user account and password are establishedduring initial configuration of the Tivoli Access Manager runtime environment.
Returned objectsThe function ivadmin_context_createdefault () returns the following data:v A pointer to a context object of type ivadmin_context
The context object contains all the information necessary to establish an SSLconnection with the Tivoli Access Manager policy server.
v A pointer to a response object of type ivadmin_response
The response object contains information about any errors that are generated byadministration API function calls.
Example codeThe following code fragment shows an example call ofivadmin_context_createdefault() with the administrative user sec_master:ivadmin_context ctx;ivadmin_response rsp;unsigned long status;
status = ivadmin_context_createdefault("sec_master", sec_masterpwd, &ctx, &rsp);if (status!= IVADMIN_TRUE) {
/* The context create call failed so we should just exit.* Optionally, you can insert error handling code here *return 0}
Backward compatibilityThe administration API provides one other function that can create a context:ivadmin_context_create(). This function provides backward compatibility withapplications developed using older versions of Tivoli Access Manager. Applicationsshould use the ivadmin_context_createdefault() function to create a securitycontext.
The function ivadmin_context_create() only provides a subset of the functionsavailable in ivadmin_context_createdefault(). It does not automatically determinethe SSL configuration for the Tivoli Access Manager policy server and you mustmanually supply the necessary SSL configuration information.
Delegating user credentialsEach security context has a set of user credentials. The Tivoli Access Managerpolicy server examines these credentials when it is deciding whether to allow ordeny a request for access to Tivoli Access Manager data. The credentials associatedwith a security context are those of the user specified to theivadmin_context_create() or ivadmin_context_createdefault() function.
8 IBM Tivoli Access Manager: Administration C API Developer’s Reference
You can use the administration API function ivadmin_context_setdelcred() tospecify an alternative user credential to be used by the Tivoli Access Managerpolicy server to make access decisions. The specified credentials accompany allaccess requests in the secure context until the credentials are cleared and set again.
The user must previously have authenticated and established credentials before thecredentials can be delegated.
To call ivadmin_context_setdelcred(), you must supply the following inputparameters:v Privilege Attribute Certificate (PAC) datav PAC length
You can use the Tivoli Access Manager authorization API functionazn_creds_get_pac() to create PAC data from a credential. For more informationabout establishing and using user credentials, see the IBM Tivoli Access ManagerAuthorization C API Developer’s Reference.
You can call the function ivadmin_context_cleardelcred() to clear the delegatedcredentials.
See the following reference pages:v “ivadmin_context_setdelcred()” on page 121v “ivadmin_context_cleardelcred()” on page 104
Creating objectsYou can use the administration API to create Tivoli Access Manager objects that areneeded to complete administration tasks.
Before you can create an object, you must establish a security context. See“Establishing security contexts” on page 7.
For example, to create a user object, supply the following information:v A security contextv Initialization values for data specific to the object, such as a user’s IDv Any policies that apply to the object, such as password enforcement policies
To create a new user in the user registry, supply the following parameters toivadmin_user_create3():unsigned longivadmin_user_create3(
ivadmin_context ctx, // input - security contextconst char *userid, // input - Tivoli Access Manager user IDconst char *dn, // input - user registry distinguished nameconst char *cn, // input - user registry common nameconst char *sn, // input - user registry attribute surnameconst char *pwd, // input - user registry attribute passwordunsigned long group_count, // input - Number of user registry group membershipsconst char **groups, // input - user registry group membershipsunsigned long ssouser, // input - SSO credentials policy
// (true/false)unsigned long nopwdpolicy, // input - password policy enforced
// at creation (true/false)ivadmin_response *rsp // output - response object
);
Chapter 2. Using the administration API 9
Administration API functions that create objects return error conditions within anivadmin_response object.
For example, the administration API provides functions to create the followingobjects in Table 4.
Table 4. Creating objects
Function Description
ivadmin_user_create3() Creates an Tivoli Access Manager user.
ivadmin_group_create2() Creates a new Tivoli Access Manager group.
ivadmin_acl_create() Creates a new access control list.
ivadmin_protobj_create() Creates a new protected object.
ivadmin_pop_create() Creates a new protected object policy.
Setting object valuesYou can use the administration API to set values within the data objects from theuser registry.
Use the administration API set operations in the following situations:v To modify values just after you have created and initialized an object
For example, after creating a new user in the user registry, callivadmin_user_setaccexpdate() to set an account expiration date for the user.
v To modify values for existing objectsFor example, to modify the maximum password age for all user accounts, callivadmin_context_setmaxpwdage().
To perform a set operation, you must have a valid context established between theadministration API application and the Tivoli Access Manager policy server.
All set operations return the following data:v An integer value (IVADMIN_TRUE or IVADMIN_FALSE) indicating if the
operation succeeded or failed.v An ivadmin_response object. This object contains information about error
conditions.
Table 5 lists examples of administration API set operations.
Table 5. Example set operations
Function Description
ivadmin_user_setdescription() Sets the description for the specified user
ivadmin_user_setaccexpdate() Sets the expiration date for the specified useraccount
ivadmin_context_setminpwdlen() Sets the minimum password length for alluser accounts
ivadmin_acl_setuser() Sets the entry for the user in the specifiedaccess control list
ivadmin_pop_setauditlevel() Sets the audit reporting level for the specifiedprotected object policy
ivadmin_protobj_settype() Sets the protected object type
10 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Getting objectsThe administration API defines a number of data types to contain Tivoli AccessManager data. You can use the administration API to obtain objects of each of thedefined data types. You can then use administration API functions to examine thevalues contained in each object.
The administration API get operations send a request to the Tivoli Access Managerpolicy server to retrieve a reference or handle to the specified object. For example,the object could be user information contained in a user registry.
The Tivoli Access Manager policy server verifies the requester’s authority to obtainthe specified object and then retrieves it from the appropriate database. The TivoliAccess Manager policy server sends the requested object to the application throughthe security context. The client application places the object in local memory.
Free the local memory when the Tivoli Access Manager object is no longer needed.
Table 6 lists examples of some administration API data types that are returned byAPI get functions.
Table 6. Example data types returned by get functions
Function Data Type Returned Object Description
ivadmin_acl_get() ivadmin_acl Access control list
ivadmin_pop_get() ivadmin_pop Protected object policy
ivadmin_user_get() ivadmin_ldapuser User information
ivadmin_group_get() ivadmin_ldapgroup Group information
ivadmin_protobj_get2() ivadmin_protobj Protected object
ivadmin_ssocred_get() ivadmin_ssocred Resource credential
ivadmin_ssogroup_get() ivadmin_ssogroup Resource group
ivadmin_ssoweb_get() ivadmin_ssoweb Single signon Web resource
Reading object valuesWhen you have established a context and obtained an object through a getoperation, you can use the administration API to perform read operations on thedata contained in the object. For example, when the application has obtained anivadmin_ldapuser object, the application can use API functions to read the user’sdistinguished name.
For performance reasons, the administration API does not send read requestsdirectly to the Tivoli Access Manager policy server without first obtaining therelevant object. Performance is optimized by completing one get transactionthrough the security context to obtain the relevant object and then querying theobject’s contents after it is stored on the local system.
Table 7 on page 12 shows some example operations that read values from areturned object.
Chapter 2. Using the administration API 11
Table 7. Example read operations
Function Description
ivadmin_user_getcn() Gets the common name from the specifiedivadmin_ldapuser object
ivadmin_user_getdn() Gets the distinguished name from thespecified ivadmin_ldapuser object
ivadmin_user_getsn() Gets the user’s surname from the specifiedivadmin_ldapuser object
ivadmin_group_getdescription() Gets the group’s description entry from theivadmin_ldapgroup object
ivadmin_acl_getuser() Gets the actions defined for a user from theivadmin_acl object
ivadmin_pop_getauditlevel() Gets the audit level defined for the protectedobject policy (POP) from the ivadmin_popobject
ivadmin_protobj_getacl() Gets the access control list (ACL) that isattached to the protected object from theivadmin_protobj object
ivadmin_ssocred_gettype() Gets the type of single signon resourceassociated with the credential from theivadmin_ssocred object
Listing object informationSome administrative tasks require the application to obtain a list of objects of onespecific type. For example, an administrator might need to review the list ofexisting users in order to decide if a new user must be created.
You can use the administration API list operations to accomplish tasks of this type.These operations are similar to API get operations. Both types of operations takethe following actions:v Communicate with the policy server through the secure contextv Request Tivoli Access Manager data from the policy server
Administration API list operations differ from get operations in one important way.List operations do not obtain a reference to an entire data object and place it inlocal memory. Instead, they obtain an array of pointers to the relevant data type, orto character data (which are names of listed items.) This enables list operations toextract only the important data from much larger data structures and return it tothe client application. The client application must free all the data associated withthe list using the ivadmin_free() function when it is no longer needed.
For example, the function ivadmin_user_list() returns a list of user IDs in the formof an array of pointers to character strings:unsigned longivadmin_user_list(
ivadmin_context ctx, // input - Context to policy serverconst char *pattern, // input - Search patternunsigned long maxreturn, // input - Maximum number of returned itemsunsigned long *count, // output - Count of returned itemchar ***userids, // output - Array of pointers to userIDsivadmin_response *rsp // output - Response object
);
12 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Free the memory used by the list when it is no longer needed using theivadmin_free() function. You must free the data associated with each characterpointer and the array of pointers.
Should the list operation encounter an error, the count is set to zero and the arrayof pointers is set to NULL.
Handling errorsThe way an administration API call indicates that an error occured depends onhow the API returns information. For the purposes of error handling, theadministration APIs can be divided into three groups:v APIs that return a numeric return code, output arguments, and a response
object, such as ivadmin_user_list() and ivadmin_pop_find().v APIs that return a numeric return code and output arguments, such as
ivadmin_acl_attrget() and ivadmin_ssogroup_getresources().v APIs that only return a value, such as ivadmin_group_getdescription() and
ivadmin_user_getsn().
If an administration API call returns a numeric return code, check the return codeto determine if the API was successful. If the API was unsuccessful and a responseobject is available, check the response object for additional information, asdescribed in “Evaluating a response object”.
Regardless of whether a return code is provided or not, if an administration APIcall was not successful, any output or return values are set to indicate that noinformation was returned: pointer arguments are set to NULL and counts andnumeric values are set to zero.
Evaluating a response objectMany administration API calls return a pointer to an object of typeivadmin_response.
ivadmin_response *rsp;
Objects of type ivadmin_response are referred to as response objects and provideadditional information regarding the operation.
The response objects are initialized by the administration API to NULL.
If a response object is returned, examine the contents to obtain further informationabout the error. Use the ivadmin_response_getok() function to examine a responseobject. This function returns an unsigned long integer. This return valuecorresponds to one of the following constants, which are defined in ivadminapi.h:#define IVADMIN_FALSE 0#define IVADMIN_TRUE 1
v If the call encountered an error, the response object contains the constantIVADMIN_FALSE.
v If the validation of input parameters fail, IVADMIN_FALSE is returned.v If the call succeeded, the response object contains the constant IVADMIN_TRUE.
When ivadmin_response_getok() returns IVADMIN_FALSE, you can useadditional administration API functions to obtain information about the error. Seethe following sections for more information.
Chapter 2. Using the administration API 13
Obtaining error message textTo view text messages describing an error, complete the following steps:1. Call ivadmin_response_getcount() to determine how many error messages
were returned.
Note: Most API calls return only one error message.2. For each message returned, call ivadmin_response_getmessage(). Pass in, as an
input parameter, an index value for each error message.The following sample code prints the response message (character string) froman administration API command:void printResponse(ivadmin_response rsp, char *api_call) {int i=0;
if (rsp == NULL) {printf(" %s : failed\n", api_call);
}
if (ivadmin_response_getok(rsp)) {printf(" %s : succeeded\n", api_call);
} else {for (i=0; i<ivadmin_response_getcount(rsp); i++) {printf(" %s : %s\n", api_call,
ivadmin_response_getmessage(rsp, i));}
}}
In the preceding example, note that in some failure scenarios, the response(rsp) can be NULL.
For more information, see the following reference pages:v “ivadmin_response_getcount()” on page 210v “ivadmin_response_getmessage()” on page 211
Obtaining error codesUse the following steps to display an Tivoli Access Manager value code thatcorresponds to each message that can be displayed withivadmin_response_getmessage(). When you know the meaning of a particularvalue code, you can use this information to develop application logic specific tothe particular error condition.
To view error or warning codes, complete the following steps:1. Call ivadmin_response_getcount() to determine how many error messages
were returned.
Note: Most API calls return only one error message.2. Call ivadmin_response_getcode() with an integer argument (input parameter)
specifying the error message to examine.The response code is returned in the form of an unsigned integer:void printErrorCode(ivadmin_response rsp, char *api_call) {int i=0;
if (rsp == NULL) {printf(" %s : failed\n", api_call);}
14 IBM Tivoli Access Manager: Administration C API Developer’s Reference
if (ivadmin_response_getok(rsp)) {printf(" %s : succeeded\n", api_call);
} else {for (i=0; i<ivadmin_response_getcount(rsp); i++) {
printf(" %s : %ul\n", api_call,ivadmin_response_getcode(rsp, i));
}}
}
Obtaining error message modifiersSome administration API calls return a modifier that categorizes the returnedmessage as one of the following types:v Informationv Warningv Error
The modifiers are defined as constants (unsigned longs):#define IVADMIN_RESPONSE_INFO 0#define IVADMIN_RESPONSE_WARNING 1#define IVADMIN_RESPONSE_ERROR 2
v Call ivadmin_message_getcount() to determine how many information,warning, or error messages were returned.
v Call ivadmin_response_getmodifier() to determine the modifier for the specifiedmessage:unsigned long = modifier;modifier = ivadmin_response_getmodifier(ivadmin_response rsp,unsigned long index);
Cleaning up and shutting downCleanup and shutdown of the administration API consists of freeing the memoryand deleting the security contexts.
Freeing memoryThe administration API provides the function ivadmin_free() for freeing memorythat has been allocated by administration API calls. All memory that has beenallocated by administration API calls must be freed using this function.void ivadmin_free(void *p);
Be sure to free memory allocated when you create the following objects:v An ivadmin_context object
See “Establishing security contexts” on page 7.v A local copy of a data object created by an administration API get function
See “Getting objects” on page 11.v An ivadmin_response object containing error information
See “Handling errors” on page 13.
You also must free character strings and array pointers that have been created byan administration API list function. Use the ivadmin_free function to free thismemory as well. See “Listing object information” on page 12. for additionalinformation on list operations.
Chapter 2. Using the administration API 15
Deleting a security contextThe administration API application must close the connection, or security context,to the Tivoli Access Manager policy server before exiting. The context must bedeleted so that the client system and the Tivoli Access Manager policy server canfree the SSL resources.
The administration API provides the function ivadmin_context_delete(). Thisfunction takes the following input parameters:v A context object of type ivadmin_context
v A pointer to the response object of type ivadmin_response
When the context has been deleted, the context memory is freed. Both theivadmin_context object and ivadmin_response object must be freed.
The following code fragment shows a sample usage of ivadmin_context_delete():unsigned long status:ivadmin_context ctx;ivadmin_response rsp;status = ivadmin_context_delete(ctx, &rsp);
if (status != IVADMIN_TRUE) {/* Delete failed; insert appropriate error handling */
}ivadmin_free(rsp);ivadmin_free(ctx);
16 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Chapter 3. Administering users and groups
The administration API provides a collection of functions for administering IBMTivoli Access Manager (Tivoli Access Manager) users and groups. This chapterdescribes the tasks that those functions accomplish.
Information about Tivoli Access Manager users and groups is stored in the userregistry. You can use the administration API to both modify and access user andgroup settings in the user registry. The administration API provides functions toadminister both individual user settings and global user settings.
Tivoli Access Manager provides the pdadmin command line interface (CLI) thataccomplishes many of the same user and group administration tasks. Applicationdevelopers who have previously used the pdadmin command to manage an TivoliAccess Manager secure domain will find the administration API functionsstraightforward to implement.
This chapter displays the pdadmin command line equivalent for each of theadministration API function calls. You can review the output from the pdadmincommand line equivalents to better understand the types of information returnedby the administration APIs. See theIBM Tivoli Access Manager Base Administrator’sGuide for detailed information on the pdadmin command.
This chapter contains the following topics:v “Administering users”v “Administering user accounts” on page 18v “Administering user passwords” on page 20v “Administering groups” on page 21v “Administering group attributes” on page 21
Administering usersThe administration API provides functions for creating, accessing, deleting, andlisting Tivoli Access Manager user information within the user registry.
The function ivadmin_user_create3 () creates a user in the user registry used bythe Tivoli Access Manager policy server.
Note: When a user definition already exists in the user registry, use theivadmin_user_import2() function instead.
The ivadmin_user_import2() function imports an existing user definition from theuser registry into Tivoli Access Manager and allows the user definition to bemanaged by Tivoli Access Manager.
Use the ivadmin_user_delete2() function to delete a user from Tivoli AccessManager.
Table 8 on page 18 lists the user administration functions.
© Copyright IBM Corp. 2000, 2003 17
User registry difference: Leading and trailing blanks in a user name do not makethe name unique when using an LDAP or ActiveDirectory user registry. However, leading and trailingblanks do make the user name unique when using aDomino server as a user registry. To keep nameprocessing consistent regardless of what user registry isbeing used, do not define user names with leading ortrailing blanks.
Table 8. Administrating users
Function Description
ivadmin_user_create3() Creates the specified user.
ivadmin_user_delete2() Deletes the specified user.
ivadmin_user_import2() Creates an Tivoli Access Manager user byimporting an existing user from the userregistry.
ivadmin_user_list() Lists Tivoli Access Manager users.
ivadmin_user_listbydn() Lists users by using the user registry’sdistinguished name.
Administering user accountsWhen a user account has been created in the user registry, you can set and getdifferent pieces of information about the user. You must create a security contextbetween the calling application and the Tivoli Access Manager policy server beforeyou can access the user registry. You can obtain the user registry information for auser object by specifying either the user ID or the user distinguished name.
Call the ivadmin_user_* group of API functions to establish security policies thatapply to one specific Tivoli Access Manager user. Call the ivadmin_context_* groupof API functions to establish security policies that apply to all Tivoli AccessManager users.
Note: When both an ivadmin_user_* command and an ivadmin_context_*command exist with similar functionality, they are combined andalphabetized under the ivadmin_context_* command as shown in Table 9 onpage 19.
This section describes the API calls that you can use to modify or access thefollowing data:v Account expiration datev Account disablement time intervalv Maximum number of failed loginsv Time of day accessv User registry typev User objectsv User account-valid statusv User names (distinguished names, common names, and surnames)v User descriptionsv Group memberships
18 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Table 9. Administrating user accounts
Function Description
ivadmin_context_getaccexpdate()ivadmin_user_getaccexpdate()
Gets the account expiration date for useraccounts.
ivadmin_context_getdisabletimeint()ivadmin_user_getdisabletimeint()
Gets the time to disable user accounts whenthe maximum number of login failures isexceeded.
ivadmin_context_getmaxlgnfails()ivadmin_user_getmaxlgnfails()
Gets the maximum number of failed loginsallowed for user accounts.
ivadmin_context_gettodaccess()ivadmin_user_gettodaccess()
Gets the time of day access policy for useraccounts.
ivadmin_context_getuserreg() Determines which type of user registry isconfigured for the Tivoli Access Managerpolicy server.
ivadmin_context_setaccexpdate()ivadmin_user_setaccexpdate()
Sets the account expiration date for useraccounts.
ivadmin_context_setdisabletimeint()ivadmin_user_setdisabletimeint()
Sets the time to disable for user accounts whenthe maximum number of login failures isexceeded.
ivadmin_context_setmaxlgnfails()ivadmin_user_setmaxlgnfails()
Sets the maximum number of failed loginsallowed for user accounts.
ivadmin_context_settodaccess()ivadmin_user_settodaccess()
Sets the time of day access for the account foruser accounts.
ivadmin_user_get() Gets the user object. Takes userID (characterstring) as an input parameter. Returns anobject of type ivadmin_ldapuser. This objectcontains a number of user registry attributesfor the specified user.
ivadmin_user_getaccountvalid() Returns the account-valid indicator for thespecified user object.
ivadmin_user_getbydn() Gets the user object by using the distinguishedname in the user registry. Returns an object oftype ivadmin_ldapuser.
ivadmin_user_getcn() Returns the common name attribute from thespecified user.
ivadmin_user_getdescription() Returns the user description as a characterstring.
ivadmin_user_getdn() Returns the distinguished name from thespecified user.
ivadmin_user_getmemberships() Lists the groups in which the specified user isa member.
ivadmin_user_getsn() Returns the surname attribute for the specifieduser.
ivadmin_user_getssouser() Returns a setting that indicates if the useraccount has single signon capabilities.
ivadmin_user_setaccountvalid() Enables or disables the specified user account.
ivadmin_user_setdescription() Sets the user description.
ivadmin_user_setssouser() Enables or disables the single signoncapabilities of the Tivoli Access Manager user.
Chapter 3. Administering users and groups 19
Administering user passwordsYou can manage user access by setting password attributes. You can specifypolicies that apply only to a single user or specify policies that apply for all users.
This section describes the administration API calls that you can use to modify oraccess password data and policies.
Call the ivadmin_user_* group of API functions to establish security policies thatapply to one specific Tivoli Access Manager user. Call the ivadmin_context_* groupof API functions to establish security policies that apply to all Tivoli AccessManager users.
Note: When both a ivadmin_user_* command and a ivadmin_context_* commandexist with similar functionality, they are combined and alphabetized underthe ivadmin_context_* command in Table 10.
Table 10. Administrating user passwords
Function Description
ivadmin_context_getmaxpwdage()ivadmin_user_getmaxpwdage()
Gets the maximum password age for useraccounts.
ivadmin_context_getmaxpwdrepchars()ivadmin_user_getmaxpwdrepchars()
Gets the maximum number of repeatedcharacters allowed in a password for useraccounts.
ivadmin_context_getminpwdalphas()ivadmin_user_getminpwdalphas()
Gets the minimum number of alphabeticcharacters allowed in a password for useraccounts.
ivadmin_context_getminpwdlen()ivadmin_user_getminpwdlen()
Gets the minimum password length for useraccounts.
ivadmin_context_setminpwdnonalphas()ivadmin_user_getminpwdnonalphas()
Gets the minimum number of nonalphabeticcharacters allowed in a password for useraccounts.
ivadmin_context_getpwdspaces()ivadmin_user_getpwdspaces()
Gets policy for whether spaces are allowed inpasswords for user accounts.
ivadmin_context_setmaxpwdage()ivadmin_user_setmaxpwdage()
Sets the maximum password age for useraccounts.
ivadmin_context_setmaxpwdrepchars()ivadmin_user_setmaxpwdrepchars()
Sets the maximum number of repeatedcharacters allowed in a password for useraccounts.
ivadmin_context_setminpwdalphas()ivadmin_user_setminpwdalphas()
Sets the minimum number of alphabeticcharacters allowed in a password for useraccounts.
ivadmin_context_setminpwdlen()ivadmin_user_setminpwdlen()
Sets the minimum password length for useraccounts.
ivadmin_context_setminpwdnonalphas()ivadmin_user_setminpwdnonalphas()
Sets the minimum number of nonalphabeticcharacters allowed in a password for useraccounts.
ivadmin_context_setpwdspaces()ivadmin_user_setpwdspaces()
Sets policy for whether spaces are allowed inpasswords for user accounts.
ivadmin_user_getpasswordvalid() Returns the enabled indicator for the user’spassword.
ivadmin_user_setpassword() Sets the user’s password.
20 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Table 10. Administrating user passwords (continued)
Function Description
ivadmin_user_setpasswordvalid() Enables or disables the Tivoli Access Manageruser’s password.
Administering groupsThe administration API provides functions for creating, deleting, and listing themembers of a group.
The name of a group is not case sensitive. Therefore ″group″, ″GROUP″, ″Group″,and ″GrOuP″ all refer to the same Tivoli Access Manager group. Table 11 lists thegroup administration functions.
User registry difference: Leading and trailing blanks in a group name do notmake the name unique when using an LDAP or ActiveDirectory user registry. However, leading and trailingblanks do make the group name unique when using aDomino server as a user registry. To keep nameprocessing consistent regardless of what user registry isbeing used, do not define group names with leading ortrailing blanks.
Table 11. Administering groups
Function Description
ivadmin_group_create2() Creates a group.
ivadmin_group_import2() Creates an Tivoli Access Manager group byimporting an existing group from the userregistry..
ivadmin_group_delete2() Deletes the specified group.
ivadmin_group_list() Lists group names that match the specifiedpattern. Group names can be Tivoli AccessManager or user registry names.
Administering group attributesThe administration API allows you to administer the attributes of a group. Table 12lists the group attribute administration functions.
Table 12. Administering group attributes
Function Description
ivadmin_group_get() Gets the group object for the specified groupname.
ivadmin_group_getbydn() Gets the group object for the specifieddistinguished name.
ivadmin_group_getcn() Returns the group common name attribute forthe specified group.
ivadmin_group_getdescription() Returns the group description.
ivadmin_group_getdn() Returns the group distinguished name for thespecified group.
Chapter 3. Administering users and groups 21
Table 12. Administering group attributes (continued)
Function Description
ivadmin_group_getid() Returns the group ID for the specified group.
ivadmin_group_listbydn() Lists groups that match the specified pattern fordistinguished names.
ivadmin_group_setdescription() Sets the group description.
ivadmin_group_getmembers() Lists the members of the group.
ivadmin_group_addmembers() Adds the specified users to the specified group.User registry difference: Attempting to add aduplicate user to a group is handled differentlydepending on what user registry is being used.See Table 36 on page 290 for details.
ivadmin_group_removemembers() Removes the specified users from the specifiedgroup.User registry difference: Attempting to removea user from a group who is not a member ofthe group is handled differently depending onwhat user registry is being used. See Table 37on page 290 for details.
22 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Chapter 4. Administering protected objects and protectedobject spaces
You can use the administration API to create, modify, examine, list, and delete IBMTivoli Access Manager (Tivoli Access Manager) protected objects. These protectedobjects represent resources that must be secured to enforce your security policy.You can specify the security policy by applying access control lists (ACLs) andprotected object policies (POPs) to the protected objects.
Tivoli Access Manager protected objects exist within a virtual hierarchy known as aprotected object space. Tivoli Access Manager provides several protected objectspaces by default. You can use the administration API to define new regions of theprotected object space, to define and secure resources that are specific to athird-party application.
This chapter describes the administration API functions that you can use toadminister protected object spaces and protected objects.
You must be familiar with protected objects before using the administration API.For an introduction to protected objects, see the chapter about managing protectedobjects in the IBM Tivoli Access Manager Base Administrator’s Guide.
For an introduction to the use of ACLs and POPs to secure protected objects, seethe chapter about using access control policies and protected object policies in theIBM Tivoli Access Manager Base Administrator’s Guide.
This chapter contains the following topics:v “Administering protected object spaces”v “Administering protected objects” on page 24v “Administering protected object attributes” on page 25
Administering protected object spacesYou can use the administration API to create and administer a user-definedprotected object space. You can use this protected object space to define a resourcehierarchy that is specific to a third-party application that uses Tivoli AccessManager authorization services to enforce a security policy.
User-defined object spaces created with the administration API are dynamicbecause they can be updated while Tivoli Access Manager is running.
Table 13 on page 24 lists the methods available for administering protected objectspaces.
Note: For an introduction to the creation of protected object spaces, see theprotected object space information in the IBM Tivoli Access Manager BaseAdministrator’s Guide.
© Copyright IBM Corp. 2000, 2003 23
Table 13. Administering protected object spaces
Function Description
ivadmin_objectspace_create() Creates an Tivoli Access Manager protectedobject space.
ivadmin_objectspace_delete() Deletes the specified Tivoli Access Managerprotected object space.
ivadmin_objectspace_list() Lists the Tivoli Access Manager protectedobject spaces.
Administering protected objectsDefine protected objects that reflect the resources that your security policy protects.
Tivoli Access Manager defines two types of protected objects: container objects andresource objects. Understand these concepts before creating and administeringprotected objects.
The name of a protected object can be of any length and contain any character.However, the forward slash (/) character is interpreted to be part of the objecthierarchy, which allows ACLs to be attached at the various points indicated by theforward slash character.
After you create a protected object, you must specify security policy for it bydefining and attaching ACLs, POPs, or both.
For more information about these Tivoli Access Manager security concepts, see theIBM Tivoli Access Manager Base Administrator’s Guide.
Use caution when implementing protected objects programmatically. In manycases, the protected object hierarchy is manually designed, built, and tested by asecurity expert. Carefully review the hierarchy to ensure that the security policy iscorrectly enforced. If you choose to build protected object hierarchiesprogrammatically, be sure to test and review the settings for each object beforedeploying the security environment.
Table 14 lists the methods available to administer protected objects.
Table 14. Administering protected objects
Function Description
ivadmin_protobj_attachacl() Attaches the specified access control list to thespecified protected object.
ivadmin_protobj_create() Creates an Tivoli Access Manager protectedobject.
ivadmin_protobj_delete() Deletes the specified Tivoli Access Managerprotected object.
ivadmin_protobj_detachacl() Detaches the access control list from thespecified protected object.
ivadmin_protobj_get2() Returns the specified protected object.
ivadmin_protobj_getdesc() Gets the description of the specified protectedobject.
ivadmin_protobj_getid() Gets the name of the specified protected object.
24 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Table 14. Administering protected objects (continued)
Function Description
ivadmin_protobj_getpolicyattachable() Indicates whether a protected object policy oraccess control list can be attached to thespecified protected object.
ivadmin_protobj_getpop() Returns the protected object policy for thespecified protected object.
ivadmin_protobj_list3() Returns the protected objects contained underthe specified directory.
ivadmin_protobj_listbyacl() Returns a list of protected objects that have thespecified access control list attached.
ivadmin_protobj_setdesc() Sets the description field of the specifiedprotected object.
ivadmin_protobj_setname() Sets or changes the name of the specifiedprotected object.
ivadmin_protobj_setpolicyattachable() Sets whether a protected object policy oraccess control list can be attached to thespecified protected object.
ivadmin_protobj_settype() Sets the type field of the specified protectedobject.
Administering protected object attributesThe attributes for a protected object can be created, set, queried, and deleted.
Table 15 describes the methods for administering protected object attributes.
Table 15. Administering protected object attributes
Function Description
ivadmin_protobj_attrdelkey() Deletes the specified extended attribute (nameand values) from the specified protectedobject.
ivadmin_protobj_attrdelval() Deletes the specified value from the specifiedextended attribute key in the specifiedprotected object.
ivadmin_protobj_attrget() Returns the values associated with thespecified extended attribute for the specifiedprotected object.
ivadmin_protobj_attrlist() Lists all the extended attributes associatedwith the specified protected object.
ivadmin_protobj_attrput() Creates an extended attribute with thespecified name and value, if it does notalready exist, and adds the attribute to thespecified protected object. If the attributespecified already exists, the specified value isadded to the existing attribute.
Chapter 4. Administering protected objects and protected object spaces 25
26 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Chapter 5. Administering access control
You can use the administration API to create, modify, examine, list, and delete IBMTivoli Access Manager (Tivoli Access Manager) access control lists (ACLs). You canalso use the administration API to attach ACLs to Tivoli Access Manager protectedobjects and to detach ACLs from protected objects.
Each ACL might contain entries for specific users and groups. You can use theadministration API to set ACL entries for users and groups that already exist in theTivoli Access Manager secure domain. You also can use the administration API toset ACL entries for the default user categories any-other and unauthenticated.
ACL entries consist of one or more permissions. These permissions specify actionsthat the owner of the entry is allowed to perform. Tivoli Access Manager providesa number of default permissions. You can use the adinistration API to defineadditional extended actions. You also can use the administration API to group theextended actions into action groups.
Understand the construction and use of ACLs before using the administration APIACL functions. The proper use of ACLs is key to successfully implementing asecurity policy. For more information, see the chapter about using access controllists in the IBM Tivoli Access Manager Base Administrator’s Guide.
This chapter contains the following topics:v “Administering access control lists”v “Administering access control list entries” on page 28v “Administering access control list extended attributes” on page 30v “Administering extended actions” on page 31v “Administering action groups” on page 30
Administering access control listsACLs enable you to grant or restrict specific users and groups access to protectedresources. The administration API enables you to:v Create and delete ACLsv Retrieve or change information associated with an ACLv List the user, group, any-other, and unauthenticated entries that are included in
the ACLv List all defined ACLs.
The name of an ACL can be of any length. The following characters are allowed inan ACL name:v Alphanumeric characters defined in the localev The underscore (_) characterv The hyphen (-) character
You specify the user entries that belong in each ACL. You also specify thepermissions or actions that each user is allowed to perform.
© Copyright IBM Corp. 2000, 2003 27
You can specify permissions or actions based on group membership, rather thanindividual user identity, to expedite administration tasks.
The administration API defines the ivadmin_acl data type to contain a retrievedACL. You can use administration API functions to extract information from theivadmin_acl object.
Be sure that you understand how to define an ACL policy before using theadministration API ACL functions. For more information, see the section aboutACL entry syntax in the IBM Tivoli Access Manager Base Administrator’s Guide.
Table 16 describes the methods for administering ACLs.
Table 16. Administering access control lists
Function Description
ivadmin_acl_create() Creates a new ACL.
ivadmin_acl_delete() Deletes the specified ACL.
ivadmin_acl_get() Returns the specified ACL.
ivadmin_acl_getdescription() Returns the description of the specified ACL.
ivadmin_acl_getid() Returns the name of the specified ACL.
ivadmin_acl_list() Returns the names of all the defined ACLs.
ivadmin_acl_listgroups() Returns a list of group names included in thespecified ACL.
ivadmin_acl_listusers() Returns a list of the user names included inthe specified ACL.
ivadmin_acl_setdescription() Sets or modifies the description for thespecified ACL.
Administering access control list entriesYou must create an ACL object before you can administer ACL entries for theobject. To create an ACL object, see “ivadmin_acl_create()” on page 53.
The administration API can be used to specify entries for each of the followingACL entry types:v Usersv Groupsv User any-other (also known as any-authenticated)v User unauthenticated
The type any-other applies to any user that has been authenticated into the TivoliAccess Manager secure domain but that does not have a separate entry in theACL.The type unauthenticated applies to all user identities that are unknown toTivoli Access Manager. Unknown users cannot authenticate into the Tivoli AccessManager secure domain.
Be sure that you understand ACL entry syntax, ACL entry types, ACL IDattributes, and ACL permission (action) attributes before you use theadministration API functions in this section.
28 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Tivoli Access Manager supports 18 default actions. For a list of the default TivoliAccess Manager actions, see the section about default Tivoli Access Managerpermissions for actions in the IBM Tivoli Access Manager Base Administrator’s Guide.
For more information, see the section about ACL entry syntax in the IBM TivoliAccess Manager Base Administrator’s Guide.
Table 17 lists the methods for administering ACL entries.
Table 17. Administering access control list entries
Function Description
ivadmin_acl_getanyother() Returns the actions defined in the entry forthe user type any-other in the specified ACL.
ivadmin_acl_getunauth() Returns the actions (permissions) defined inthe entry for the user type unauthenticated inthe specified ACL.
ivadmin_acl_getuser() Returns the actions (permissions) defined inthe entry for the specified user in thespecified ACL.
ivadmin_acl_setuser() Returns the actions (permissions) defined inthe entry for the specified group in thespecified ACL.
ivadmin_acl_removeanyother() Removes the ACL entry for the any-otheruser from the specified ACL.
ivadmin_acl_removegroup() Removes the ACL entry for the specifiedgroup from the specified ACL.
ivadmin_acl_removeunauth() Removes the ACL entry for theunauthenticated user from the specified ACL.
ivadmin_acl_removeuser() Removes the ACL entry for the specified userfrom the specified ACL.
ivadmin_acl_setanyother() Sets or modifies the ACL entry for theany-other user in the ACL.
Call this function to specify permissions forall authenticated users that do not have aseparate user or group entry in the specifiedACL.
ivadmin_acl_setgroup() Sets or modifies the ACL entry for thespecified group in the specified ACL.
ivadmin_acl_setunauth() Sets the ACL entry for the unauthenticateduser in the specified ACL.
Call this function to specify permissions forthose users that have not been authenticated.
ivadmin_acl_setuser() Sets the entry for the specified user in thespecified ACL. Use this to specify the actionsthat a user is permitted to perform.
Chapter 5. Administering access control 29
Administering access control list extended attributesExtended attributes for an ACL can be obtained, set, and deleted. Table 18 lists themethods available for administering ACL extended attributes.
Table 18. Administering access control list extended attributes
Function Description
ivadmin_acl_attrdelkey() Deletes the specified extended attribute keyfrom the specified ACL.
ivadmin_acl_attrdelval() Deletes the specified value from the specifiedextended attribute key in the specified ACL.
ivadmin_acl_attrget() Gets the extended attribute values for thespecified extended attribute key from thespecified ACL.
ivadmin_acl_attrlist() Lists the extended attribute keys associatedwith the specified ACL.
ivadmin_acl_attrput() Creates an extended attribute with thespecified name and value, if it does notalready exist, and adds the attribute to thespecified ACL. If the attribute specifiedalready exists, the specified value is added tothe existing attribute.
Administering action groupsYou can use the administration API to create, examine, and delete new actiongroups.
Each action group can contain 32 action codes. The default action group, referredto as the primary action group, contains the 18 predefined Tivoli Access Manageraction codes. Thus, you can create up to 14 new action codes to the primary group.
When you need to create more than 32 action codes, you can use theadministration API to define a new action group. Tivoli Access Manager supportsup to 32 action groups.
For more information about action groups, see the section about creating extendedACL actions and action groups in the IBM Tivoli Access Manager BaseAdministrator’s Guide.
Table 19. Administering action groups
Function Description
ivadmin_action_create_in_group() Defines a new action (permission) code in thespecified action group. Call this function toadd an action code to a user-defined extendedaction group.
ivadmin_action_delete_from_group() Deletes an action (permission) code from thespecified action group.
ivadmin_action_group_create() Creates a new action group with the specifiedname.
ivadmin_action_group_delete() Deletes the specified action group and all theactions that belong to the specified group.
ivadmin_action_group_list() Lists all the defined action group names.
30 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Table 19. Administering action groups (continued)
Function Description
ivadmin_action_list_in_group() Lists all the defined action (permission) codesfrom the specified action group.
Administering extended actionsTivoli Access Manager provides a default set of actions (permissions) that belongto the primary action group that can be granted to users or groups. You can usethe administration API to define new, extended actions that supplement the set ofdefault actions. Each of the extended actions can belong to the primary actiongroup or to a custom action group.
Extended actions are typically defined to support actions that are specific to athird-party application. For more information about extended actions, see thesection about creating extended ACL actions and action groups in the IBM TivoliAccess Manager Base Administrator’s Guide.
Table 20. Administering extended actions
Function Description
ivadmin_action_create() Defines a new action (permission)codein thespecified action group.
ivadmin_action_delete() Deletes an action (permission) code from thespecified action group.
ivadmin_action_getdescription() Returns the description for the specifiedaction.
ivadmin_action_getid() Returns the code for the specified action.
ivadmin_action_gettype() Returns the type for the specified action.
ivadmin_action_list() Lists all the defined action (permission) codesfor the specified action group.
Chapter 5. Administering access control 31
32 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Chapter 6. Administering protected object policies
You can use the administration API to create, modify, examine, and delete IBMTivoli Access Manager (Tivoli Access Manager) protected object policies (POPs).You can also use the Administration API to attach or detach POPs from protectedobjects.
You can use POPs to impose additional conditions on operations that are permittedby an access control list (ACL) policy. These additional conditions are enforcedregardless of the user or group identities specified in the ACL entries.
Examples of additional conditions include the following:v Specifying the quality of protectionv Writing a report record to the auditing servicev Requiring an authentication strength levelv Restricting access to a specific time periodv Enabling or disabling warning mode, which allows an administrator to validate
security policy
Be sure that you understand Tivoli Access Manager POPs before using theadministration API to administer POPs. For more information, see the chapterabout using POPs in the IBM Tivoli Access Manager Base Administrator’s Guide.
This chapter contains the following topics:v “Administering protected object policy objects”v “Administering protected object policy settings” on page 34v “Administering protected object policy extended attributes” on page 35
Administering protected object policy objectsPOP objects are administered in a similar way to ACL policies. You can create andconfigure a POP, and then attach the POP to objects in the protected object space.
The administration API defines the ivadmin_pop data type to contain the retrievedPOP. You can use administration API functions to extract data from theivadmin_pop objects. You do not need to know the internal structure of theivadmin_pop data type.
Table 21. Administering protected object policy objects
Function Description
ivadmin_pop_create() Creates a POP object with the default values.
ivadmin_pop_delete() Deletes the specified POP.
ivadmin_pop_detach() Detaches a POP from the specified protectedobject.
ivadmin_pop_find() Finds and lists all protected objects that havethe specified POP attached.
ivadmin_pop_get() Gets the specified POP object. Call thisfunction to get an object of type ivadmin_pop.
ivadmin_pop_list() Lists all POP objects.
© Copyright IBM Corp. 2000, 2003 33
Administering protected object policy settingsYou can use the administration API to set, modify, or remove attributes in a POP.You must create the POP object before specifying POP settings. To create a POPobject, see “ivadmin_pop_create()” on page 159.
You can use administration API functions to specify the following POP attributes:v Authentication levelsv Quality of Protection (QOP) requirementsv Auditing levelsv Time of day access restrictionsv Warning mode settings
Call ivadmin_pop_setanyothernw() or ivadmin_pop_setipauth() to specify step-upauthentication policy for objects requiring authentication-sensitive authorization.When using step-up authentication, you can either filter users based on IP addressor you can specify step-up authentication for all users, regardless of IP address.
Call ivadmin_pop_setanyothernw() or ivadmin_pop_setipauth() when you wantto specify a POP that specifies step-up authentication policy for all users,regardless of IP address.
For more information about the use of the authentication level by WebSEAL, seethe section about authentication strength POP policy (step-up) in the IBM TivoliAccess Manager WebSEAL Developer’s Reference.
The quality of protection (QOP) level is not enforced internally by Tivoli AccessManager. Applications that set the quality of protection can enforce it.
Audit levels specify what operations generate an audit record. This value is usedinternally by Tivoli Access Manager and also can be used by applications togenerate their audit records.
The time of day access setting is used to control access to a protected object basedon the time when the access occurs.
The warning mode enables a security administrator to troubleshoot theauthorization policy set on the protected object space.
When you set the warning attribute to yes, any action is possible by any user onthe object where the POP is attached. Any access to an object is permitted even ifthe ACL policy attached to the object is set to deny this access.
Audit records are generated that capture the results of all ACL policies withwarning mode set throughout the object space. The audit log shows the outcomeof an authorization decision as it would have been made if the warning attributehad been set to no.
34 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Table 22. Administering protected object policy settings
Function Description
ivadmin_pop_getanyothernw() Gets the anyothernw, or any other network,setting for the IP authentication level from thespecified POP.
ivadmin_pop_getauditlevel() Gets the audit level for the specified POP.
ivadmin_pop_getdescription() Gets the description of the specified POP.
ivadmin_pop_getipauth() Gets the IP endpoint authentication setting inthe specified POP.
ivadmin_pop_getid() Gets the name of the specified POP.
ivadmin_pop_getqop() Gets the quality of protection (QOP) level forthe specified POP.
ivadmin_pop_gettod() Gets the time of day range for the specifiedPOP.
ivadmin_pop_getwarnmode() Gets the warning mode value from thespecified POP.
ivadmin_pop_removeipauth() Removes the ipauth access setting forauthentication level from the specified POP.
ivadmin_pop_setanyothernw() Sets the anyothernw setting for authenticationlevel from the specified POP.
ivadmin_pop_setanyothernw_forbidden() Sets the anyothernw access setting toforbidden for the specified POP.
ivadmin_pop_setauditlevel() Sets the audit level for the specified POP.
ivadmin_pop_setdescription() Sets the description of the specified POP.
ivadmin_pop_setipauth() Sets the ipauth setting for authentication levelin the specified POP.
ivadmin_pop_setipauth_forbidden() Sets the ipauth setting for authentication levelto forbidden in the specified POP.
ivadmin_pop_setqop() Sets the quality of protection level for thespecified POP.
ivadmin_pop_settod() Sets the time of day range for the specifiedPOP.
ivadmin_pop_setwarnmode() Sets the warning mode for the specified POP.
Administering protected object policy extended attributesTable 23. Administering protected object policy extended attributes
Function Description
ivadmin_pop_attrdelkey() Deletes the specified extended attribute fromthe specified POP.
ivadmin_pop_attrdelval() Deletes the specified value from the specifiedextended attribute key in the specified POP.
ivadmin_pop_attrget() Gets the values for the specified extendedattribute from the specified POP.
ivadmin_pop_attrlist() Lists the extended attributes associated withthe specified POP.
ivadmin_pop_attrput() Sets the value for the specified extendedattribute in the specified POP.
Chapter 6. Administering protected object policies 35
36 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Chapter 7. Administering single signon resources
You can use the administration API to administer resources that enable an IBMTivoli Access Manager (Tivoli Access Manager) user to obtain single signon (SSO)capability across more than one Web server. This capability requires the use ofTivoli Access Manager WebSEAL junctions.
You can use the administration API to create, modify, examine, and delete thefollowing types of resources:v Web resourcesv Resource groupsv Resource credentials
Be sure that you understand Tivoli Access Manager single signon support beforeyou use the administration API to administer single signon resources. For moreinformation about administering single signon capability across junctioned Webserver resources, see the section about user registry resource managementcommands in the IBM Tivoli Access Manager Base Administrator’s Guide and thesection about using global sign-on (GSO) in the IBM Tivoli Access ManagerWebSEAL Developer’s Reference.
This chapter contains the following topics:v “Web resources”v “Resource groups” on page 38v “Resource credentials” on page 39
Web resourcesA Web resource is a Web server that serves as the backend of an Tivoli AccessManager WebSEAL junction. An application on the joined Web server can requireusers to authenticate specifically to the application. The authentication information,such as user name and password, often differs from the authentication informationused by Tivoli Access Manager.
The junctioned Web server thus requires an authenticated Tivoli Access Manageruser to log in again, using the user name and password specific to the applicationon the joined Web server.
You can use the administration API to configure Tivoli Access Manager so thatTivoli Access Manager users need to authenticate only one time. You must define aWeb resource (server) and then define a user-specific resource credential thatcontains user-specific authentication information for the Web resource.
This section describes how to create, modify, and delete Web resources.Administration of resource credentials is described in “Resource credentials” onpage 39.
Note: The administration API does not perform all WebSEAL junctionconfiguration tasks through the API. Use the pdadmin commands to modifythe junction definitions. For more information, see the IBM Tivoli AccessManager WebSEAL Administrator’s Guide.
© Copyright IBM Corp. 2000, 2003 37
Table 24. Administering Web resources
Function Description
ivadmin_ssoweb_create() Creates a single signon Web resource.
ivadmin_ssoweb_delete() Deletes the specified single signon Webresource.
ivadmin_ssoweb_get() Returns the specified single signon Webresource.
ivadmin_ssoweb_getdescription() Returns the description of the specified singlesignon Web resource.
ivadmin_ssoweb_getid() Returns the name (identifier) of the specifiedsingle signon Web resource.
ivadmin_ssoweb_list() Returns a list of all of the single signon Webresource names.
Resource groupsA resource group is a group of Web servers, all of which have been junctioned to anTivoli Access Manager WebSEAL server and all of which use the same set of userIDs and passwords.
You can use the administration API to create resource groups. You can then createa single resource credential for all the resources in the resource group. This enablesyou to simplify the management of Web resources by grouping similar Webresources into resource groups.
You can also use the administration API to add more Web resources, whennecessary, to an existing resource group.
Table 25. Administering resource groups
Function Description
ivadmin_ssogroup_addres() Adds a single signon resource to asingle signon resource group.
ivadmin_ssogroup_create() Creates a single signon groupresource.
ivadmin_ssogroup_delete() Deletes a single signon groupresource.
ivadmin_ssogroup_get() Returns the specified single signongroup resource.
ivadmin_ssogroup_getdescription() Returns the description of thesingle signon group resource.
ivadmin_ssogroup_getid() Returns the name of the singlesignon group resource.
ivadmin_ssogroup_getresources() Returns a list of the member singlesignon resource names for thespecified single signon group.
ivadmin_ssogroup_list Returns a list of all of the singlesignon group resource names.
ivadmin_ssogroup_removeres() Removes a single signon resourcefrom the specified single signonresource group.
38 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Resource credentialsA resource credential provides a user ID and password for a single signonuser-specific resource, such as a Web server or a group of Web servers. The Webresource or group of Web resources must exist before you can apply resourcecredentials to it.
Resource credential information is stored in the user’s Tivoli Access Manager entryin the user registry.
You can use the administration API to create, modify, examine, and delete resourcecredentials.
Table 26. Administering credentials
Function Description
ivadmin_ssocred_create() Creates a single signon credential.
ivadmin_ssocred_delete() Deletes a single signon credential.
ivadmin_ssocred_get() Returns the specified single signon credential.
ivadmin_ssocred_getid() Returns the name of the single signonresource associated with this credential.
ivadmin_ssocred_getssopassword() Returns the password associated with thissingle signon credential.
ivadmin_ssocred_getssouser() Returns the name of the resource userassociated with the specified single signoncredential.
ivadmin_ssocred_gettype() Returns the type of the single signon resourceassociated with the specified single signoncredential.
ivadmin_ssocred_getuser() Returns the name of the Tivoli AccessManager user associated with this singlesignon credential.
ivadmin_ssocred_list() Returns the list of single signon credentials forthe specified user.
ivadmin_ssocred_set() Modifies a single signon credential.
Chapter 7. Administering single signon resources 39
40 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Chapter 8. Configuring application servers
You can use the administration API to configure and unconfigure authorizationand administration API servers, modify configuration parameters, administerreplicas, and perform certificate maintenance. These APIs are used by the svrsslcfgcommand line utility instead of the pdadmin command line utility.
The svrsslcfg utility is used to perform the necessary configuration steps that allowan application to use a secure sockets layer (SSL) connection for communicatingwith the policy server or the authorization server. It is not intended to do all of theconfiguration that may be required to ensure a correctly functioning application.For more information about the svrsslcfg utility, see the section about usingsvrsslcfg in the IBM Tivoli Access Manager Command Reference.
Note: The local host name is used to build a unique name for the application. Insome cases, depending on the TCP/IP configuration, the host name is notalways consistent and may result in look-up failures. For example, theoperating system might return the fully qualified host name while anothermachine might just return the host name. If this happens in your network,you should use the following format to specify the server name to thecommand line interface:server_name/desired_host_name
For the API, these parameters are separate. There, desired_host_name shouldbe specified for the host_name parameter.
This chapter contains the following topics:v “Configuring application servers”v “Administering replicas” on page 42v “Certificate maintenance” on page 42
Configuring application serversUse the configuration commands to enable an application server (an applicationthat uses the authorization or administration API) to communicate with the policyserver or the authorization server. An administrative user identity (for example,sec_master) and password must be specified for connecting to the policy server.
Table 27. Configuring application servers
Function Description
ivadmin_cfg_configureserver2() Configures an application server by updatingthe configuration file and creating the key-ringfile.
ivadmin_cfg_setlistening() Sets or resets the enable-listening parameter inthe configuration file.
ivadmin_cfg_setport() Changes the listening port number of theapplication and updates the port number inthe configuration file.
ivadmin_cfg_unconfigureserver() Unconfigures an application server.
© Copyright IBM Corp. 2000, 2003 41
Administering replicasTable 28. Administering replicas
Function Description
ivadmin_cfg_addreplica() Adds a replica entry to the configuration file.
ivadmin_cfg_chgreplica() Changes parameters of a replica entry in theconfiguration file.
ivadmin_cfg_rmvreplica() Removes a replica entry from theconfiguration file.
Certificate maintenanceOnly use ivadmin_cfg_renewservercert() when the certificate has beencompromised or when the automatic certificate refresh logic fails.
Table 29. Certificate maintenance
Function Description
ivadmin_cfg_renewservercert() Renews the server SSL certificate.
42 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Chapter 9. Administering servers
You can use the administration API to get a list of tasks from the server, send aspecific task to an authorization server, and notify replica databases, eitherautomatically or manually, when the master authorization database is updated.
This chapter contains the following topics:v Getting and performing administration tasksv Notifying replica databases when the master authorization database is updated
– Notifying replica databases automatically– Notifying replica databases manually– Setting the maximum number of notification threads– Setting the notification wait time
Getting and performing administration tasksYou can send an administration task to a server. You also can request a list of allsupported administration tasks from a server. The caller must have credentialswith sufficient permission to perform the task. For more information, see the IBMTivoli Access Manager Authorization C API Developer’s Reference.
Notifying replica databases when the master authorization database isupdated
When an administrator makes security policy changes, the policy server makesadjustments to the master authorization database to reflect these changes. Toensure that these changes also are dispersed to any authorization servers withreplica databases, you can do one or more of the following:v Configure an IBM Tivoli Access Manager (Tivoli Access Manager) application,
such as WebSEAL, to poll the master authorization database at regular intervalsfor updates. By default, polling is disabled. For more information about pollingthe master authorization database, see the cache-refresh-interval optiondescribed in the IBM Tivoli Access Manager Authorization C API Developer’sReference.
v Enable the policy server to notify authorization servers each time that the masterauthorization database is updated. This automatic process is recommended forenvironments where database changes are infrequent. For more information, see“Notifying replica databases automatically” on page 44.
v Notify authorization servers, on demand, after you make updates to the masterauthorization database. This manual process is recommended for environmentswhere database changes are frequent and involve substantial changes. Forinstructions, see “Notifying replica databases manually” on page 44.
After you select the method that you want to use to update replica databases(automatic, manual, or both), you can fine-tune settings in the ivmgrd.conf file onthe policy server. For more information, see “Setting the maximum number ofnotification threads” on page 44 and “Setting the notification wait time” on page44.
© Copyright IBM Corp. 2000, 2003 43
Notifying replica databases automaticallyYou can enable the policy server to send notifications to authorization servers eachtime that the master authorization database is updated. In turn, the authorizationservers automatically request a database update from the policy server.
To enable automatic database updates, edit the ivmgrd.conf file on the policyserver and add the following attribute=value pair:[ivmgrd]auto-database-update-notify = yes
You must restart the policy server for changes to take effect. Note that this settingis recommended for environments where the master database is changedinfrequently. To turn off automatic notification, specify no.
Notifying replica databases manuallyWhen the master authorization database is updated, you can use theivadmin_server_replicate() function to send notification to application servers thatare configured to receive database update notifications. You can indicate that aspecific server receive update notifications, or specify NULL, which notifies allconfigured authorization servers in the secure domain. If you specify a servername, you are notified whether the server was replicated successfully or if a failureoccurred. If you do not specify a server name, return codes indicate whether or notthe policy server started notifying authorization servers in your secure domain.Note that unless you specify the server-name option, you are not notified when anauthorization server’s database was replicated successfully.
Setting the maximum number of notification threadsWhen the master authorization database is updated, this update is announced toreplica databases through the use of notification threads. Each replica then has theresponsibility of downloading the new data from the master authorizationdatabase.
You can edit the ivmgrd.conf file to set a value for the maximum number ofnotification threads. This number is calculated based on the number of replicadatabases in your secure domain. For example, if you have 10 replica databasesand want to notify them of master database changes simultaneously, specify avalue of 10 for the max-notifier-threads attribute as shown:[ivmgrd]max-notifier-threads = 10
The default value is 10 (threads).
Setting the notification wait timeThere is a time delay between when the policy server updates the masterauthorization database and when notification is sent to database replicas. If youadded auto-database-update-notify = yes to the ivmgrd.conf file as described in“Notifying replica databases automatically” on page 44, you can set this period oftime. To do so, edit the notifier-wait-time value in the ivmgrd.conf file. Forexample, if you are making batch changes to the master authorization database, itis advisable to wait until all changes have been made before policy changes aresent to database replicas. Therefore, you might decide to increase the default valuefrom 15 seconds to 25 seconds as shown:[ivmgrd]notifier-wait-time = 25
44 IBM Tivoli Access Manager: Administration C API Developer’s Reference
By editing the value for this attribute, the policy server is prevented from sendingindividual replica notifications for each of a series of database changes.
Administrating servers and database notificationTable 30. Administrating servers and database notification
Function Description
ivadmin_server_gettasklist() Gets the list of tasks from the server.
ivadmin_server_performtask() Sends a command to an authorization server.
ivadmin_server_replicate() Notifies authorization servers to receivedatabase updates.
Chapter 9. Administering servers 45
46 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Chapter 10. Administration C API reference
The APIs in this chapter are presented alphabetically by name. Refer to“Conventions used in this book” on page xviii for a description of the conventionsused to illustrate commands.
© Copyright IBM Corp. 2000, 2003 47
ivadmin_acl_attrdelkey()Deletes the specified extended attribute key from the specified access control list.
Syntaxunsigned long
ivadmin_acl_attrdelkey(ivadmin_context ctx,char *aclid,char *attr_key,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
aclid The name of the access control list.
attr_keyThe extended attribute to delete.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionDeletes the specified extended attribute key from the specified access control list.
Command line equivalent:pdadmin modify ACL_name delete attribute attribute_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
48 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_acl_attrdelval()Deletes the specified value from the specified extended attribute key in thespecified access control list.
Syntaxunsigned longivadmin_acl_attrdelval(
ivadmin_context ctx,char *aclid,char *attr_key,char *attr_value,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
aclid The name of the access control list.
attr_keyThe extended attribute key.
attr_valueThe extended attribute value to delete from the extended attribute key.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionDeletes the specified value from the specified extended attribute key in thespecified access control list.
Command line equivalent:pdadmin modify ACL_name delete attribute attribute_name attribute_value
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 49
ivadmin_acl_attrget()Gets the extended attribute value for the specified extended attribute key from thespecified access control list.
Syntaxunsigned longivadmin_acl_attrget(
ivadmin_acl acl,char *attr_key,unsigned long *count,char ***attr_value
);
ParametersInput
acl The ivadmin_acl object. This object contains the access control list.
attr_keyThe attribute key to look up.
Output
count The number of values returned. Zero is returned if an error occurs.
attr_valueAn array of pointers to the values returned. You must free the characterdata referenced by each pointer, as well as the array of pointers when theyare no longer needed.
DescriptionGets the extended attribute values for the specified extended attribute key from thespecified access control list.
Command line equivalent:pdadmin acl show ACL_name attribute attribute_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
50 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_acl_attrlist()Lists the extended attribute keys associated with the specified access control list.
Syntaxunsigned longivadmin_acl_attrlist(
ivadmin_acl acl,unsigned long *count,char ***attr_list
);
ParametersInput
acl The ivadmin_acl object. This object contains the access control list.
Output
count The number of extended attributes returned. Zero is returned if an erroroccurs.
attr_listAn array of pointers to the extended attributes returned. You must free thecharacter data referenced by each pointer, as well as the array of pointerswhen they are no longer needed.
DescriptionLists the extended attribute keys associated with the specified access control list.
Command line equivalent:pdadmin acl list ACL_name attribute
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 51
ivadmin_acl_attrput()Sets the extended attribute value for the specified extended attribute key in thespecified access control list.
Syntaxunsigned longivadmin_acl_attrput(
ivadmin_context ctx,char *aclid,char *attr_key,char *attr_value,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
aclid The name of the access control list.
attr_keyThe extended attribute key for which you want to set a value.
attr_valueThe value to set.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the extended attribute value for the specified extended attribute key in thespecified access control list.
Command line equivalent:pdadmin acl modify ACL_name set attribute attribute_name attribute_value
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
52 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_acl_create()Creates a new access control list.
Syntaxunsigned longivadmin_acl_create(
ivadmin_context ctx,const char *aclid,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
aclid The name of the access control list to be created. The name can be of anylength. The following characters are valid in an ACL name.v Alphanumeric characters defined in the localev The underscore (_) characterv The hyphen (-) character
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionCreates a new access control list (ACL). This function creates a new ACL policy inthe Tivoli Access Manager ACL database. It does not create the specific ACLentries.
Command line equivalent:pdadmin acl create ACL_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 53
ivadmin_acl_delete()
Deletes the specified access control list.
Syntaxunsigned longivadmin_acl_delete(
ivadmin_context ctx,const char *aclid,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
aclid The name of the access control list.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionDeletes the specified access control list.
Command line equivalent:pdadmin acl delete ACL_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
54 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_acl_get()Returns the specified access control list.
Syntaxunsigned longivadmin_acl_get(
ivadmin_context ctx,const char *aclid,ivadmin_acl *acl,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
aclid The name of the access control list.
Output
acl Returned access control list. Free this memory when it is no longer needed.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionReturns the specified access control list.
Command line equivalent:pdadmin acl show ACL_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 55
ivadmin_acl_getanyother()Returns the actions (permissions) defined in the entry for the user any-other
in the specified access control list.
Syntaxconst char *ivadmin_acl_getanyother(
ivadmin_acl acl);
ParametersInput
acl Pointer to the access control list.
DescriptionReturns the actions defined in the entry for the user any-other in the specifiedaccess control list. You must call the ivadmin_acl_get() function to obtain theivadmin_acl object before using this function to obtain the actions defined for theany-other user type. Free this character string when it is no longer needed.
Each action is represented by a single alphabetic character. Default actions areprovided in the primary action group by Tivoli Access Manager. These defaultactions, such as A for add, or v for view, are listed in the IBM Tivoli Access ManagerBase Administrator’s Guide. Actions in the primary action group are always returnedfirst, followed by the actions defined in other action groups. For example, if theentry contains the add and view actions from the primary action group, along withthe P, D, and q actions from the AdminGroup action group, and the b and Vactions from the Auditors action group, the returned string might be:Av[AdminGroup]PDq[Auditors]bV
If no actions are defined in the entry, an empty string (″″) is returned.
Command line equivalent:pdadmin acl show any-other
Return ValuesReturns the actions defined in the entry for the user any-other in the specifiedaccess control list.
56 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_acl_getdescription()
Returns the description of the specified access control list.
Syntaxconst char *ivadmin_acl_getdescription(
ivadmin_acl acl);
ParametersInput
acl Pointer to the access control list.
DescriptionReturns the description of the specified access control list. You must call theivadmin_acl_get() function to obtain the ivadmin_acl object before usingivadmin_acl_getdescription (). Do not free this entry. This is data maintained inthe access control list structure.
Command line equivalent:pdadmin acl show ACL_name
The description is part of the information returned by the pdadmin acl showcommand.
Return ValuesReturns the description of the specified access control list. The maximum length fora description is 1024 characters.
Chapter 10. Administration C API reference 57
ivadmin_acl_getgroup()Returns the actions (permissions) defined in the entry for the specified group inthe specified access control list.
Syntaxconst char *ivadmin_acl_getgroup(
ivadmin_acl acl,const char *groupid
);
ParametersInput
acl Pointer to the access control list.
groupidThe name of the group for which you want the actions.
DescriptionReturns the actions (permissions) defined in the entry for the specified group inthe specified access control list. You must call the ivadmin_acl_get() function toobtain the ivadmin_acl object before using this function to obtain the actionsdefined for the group. Free this entry when it is no longer needed.
Each action is represented by a single alphabetic character. Default actions areprovided in the primary action group by Tivoli Access Manager. These defaultactions, such as A for add, or v for view, are listed in the IBM Tivoli Access ManagerBase Administrator’s Guide. Actions in the primary action group are always returnedfirst, followed by the actions defined in other action groups. For example, if theentry contains the add and view actions from the primary action group, along withthe P, D, and q actions from the AdminGroup action group, and the b and Vactions from the Auditors action group, the returned string might be:Av[AdminGroup]PDq[Auditors]bV
If no actions are defined in the entry, an empty string (″″) is returned.
Command line equivalent:pdadmin acl show ACL_name
Return ValuesReturns the actions (permissions) defined in the entry for the specified group inthe specified access control list.
58 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_acl_getid()
Returns the name of the specified access control list.
Syntaxconst char *ivadmin_acl_getid(
ivadmin_acl acl);
ParametersInput
acl Pointer to the access control list.
DescriptionReturns the name of the specified access control list. You must call theivadmin_acl_get() function to obtain the ivadmin_acl object before using thisfunction. Do not free the returned name. This is data maintained in theivadmin_acl structure.
Command line equivalent:pdadmin acl show ACL_name
The access control list name is part of the information returned by the pdadmincommand.
Return ValuesReturns the name of the specified access control list. There is no limit to the lengthof the name.
Chapter 10. Administration C API reference 59
ivadmin_acl_getunauth()
Returns the actions (permissions) defined in the entry for the user unauthenticatedin the specified access control list.
Syntaxconst char *ivadmin_acl_getunauth(
ivadmin_acl acl);
ParametersInput
acl Pointer to the access control list.
DescriptionReturns the actions (permissions) defined in the entry for the user unauthenticatedin the specified access control list. You must call the ivadmin_acl_get() function toobtain the ivadmin_acl object before using this function to obtain the actionsdefined for all unauthenticated users. Free the returned actions when they are nolonger needed.
Each action is represented by a single alphabetic character. Default actions areprovided in the primary action group by Tivoli Access Manager. These defaultactions, such as A for add, or v for view, are listed in the IBM Tivoli Access ManagerBase Administrator’s Guide. Actions in the primary action group are always returnedfirst, followed by the actions defined in other action groups. For example, if theentry contains the add and view actions from the primary action group, along withthe P, D, and q actions from the AdminGroup action group, and the b and Vactions from the Auditors action group, the returned string might be:Av[AdminGroup]PDq[Auditors]bV
If no actions are defined in the entry, an empty string (″″) is returned.
Command line equivalent:pdadmin acl show ACL_name
Return ValuesReturns the actions (permissions) defined in the entry for the user unauthenticatedin the specified access control list.
60 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_acl_getuser()
Returns the actions (permissions) defined in the entry for the specified user in thespecified access control list.
Syntaxconst char *ivadmin_acl_getuser(
ivadmin_acl acl,const char * userid
);
ParametersInput
acl Pointer to the access control list.
userid The name of the user entry from which you want to get the list of definedactions.
DescriptionReturns the actions (permissions) defined in the entry for the specified user in thespecified access control list. You must call the ivadmin_acl_get() function to obtainthe ivadmin_acl object before using ivadmin_acl_getuser() to obtain the actionsdefined for the user. Free this character string when no longer needed.
Each action is represented by a single alphabetic character. Default actions areprovided in the primary action group by Tivoli Access Manager. These defaultactions, such as A for add, or v for view, are listed in the IBM Tivoli Access ManagerBase Administrator’s Guide. Actions in the primary action group are always returnedfirst, followed by the actions defined in other action groups. For example, if theentry contains the add and view actions from the primary action group, along withthe P, D, and q actions from the AdminGroup action group, and the b and Vactions from the Auditors action group, the returned string might be:Av[AdminGroup]PDq[Auditors]bV
If no actions are defined in the entry, an empty string (″″) is returned.
Command line equivalent:pdadmin acl show ACL_name
Return ValuesReturns the actions (permissions) defined in the entry for the specified user in thespecified access control list.
Chapter 10. Administration C API reference 61
ivadmin_acl_list()
Returns the names of all the defined access control lists.
Syntaxunsigned longivadmin_acl_list(
ivadmin_context ctx,unsigned long *count,char ***aclids,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
Output
count The number of access control list names returned. Zero is returned if anerror occurs.
aclids An array of pointers to the access control list names returned. You mustfree the character data referenced by each pointer, as well as the array ofpointers when they are no longer needed.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionReturns the names of all of the defined access control lists. If no access control listsexist, or an error is encountered, NULL is returned.
Command line equivalent:pdadmin acl list
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
62 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_acl_listgroups()
Returns a list of group names included in the specified access control list.
Syntaxunsigned longivadmin_acl_listgroups(
ivadmin_acl acl,unsigned long *count,char ***groupids
);
ParametersInput
acl Pointer to the access control list.
Output
count The number of group names returned. Zero is returned if an error occurs.
groupidsAn array of pointers to the group names returned. You must free thecharacter data referenced by each pointer, as well as the array of pointerswhen they are no longer needed.
DescriptionReturns a list of group names included in the specified access control list. Youmust call the ivadmin_acl_get() function to obtain the ivadmin_acl object beforeusing this function.
Command line equivalent:pdadmin acl show ACL_name
The list of group names is part of the information returned by this pdadmincommand.
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 63
ivadmin_acl_listusers()
Returns a list of the user names included in the specified access control list.
Syntaxunsigned longivadmin_acl_listusers(
ivadmin_acl acl,unsigned long *count,char ***userids
);
ParametersInput
acl Pointer to the access control list.
Output
count The number of user names returned. Zero is returned if an error occurs.
useridsAn array of pointers to the user names returned. You must free thecharacter data referenced by each pointer, as well as the array of pointerswhen they are no longer needed..
DescriptionReturns a list of the user names included in the specified access control list. Youmust call the ivadmin_acl_get() function to obtain the ivadmin_acl object beforeusing this function.
Command line equivalent:pdadmin acl show ACL_name
The list of users is part of the information returned in the pdadmin command.
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
64 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_acl_removeanyother()
Removes the access control list entry for the user any-other from the specifiedaccess control list.
Syntaxunsigned longivadmin_acl_removeanyother(
ivadmin_context ctx,const char *aclid,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
aclid The name of the access control list.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionRemoves the access control list entry for the user any-other from the specifiedaccess control list.
Command line equivalent:pdadmin acl modify ACL_name remove any-other
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 65
ivadmin_acl_removegroup()
Removes the access control list entry for the specified group from the specifiedaccess control list.
Syntaxunsigned longivadmin_acl_removegroup(
ivadmin_context ctx,const char *aclid,const char *groupid,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
aclid The name of the access control list.
groupidThe name of the group entry to be removed from the access control list.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionRemoves the access control list entry for the specified group from the specifiedaccess control list.
Command line equivalent:pdadmin acl modify ACL_name remove group group_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
66 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_acl_removeunauth()
Removes the access control list entry for the user unauthenticated from thespecified access control list.
Syntaxunsigned longivadmin_acl_removeunauth(
ivadmin_context ctx,const char *aclid,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
aclid The name of the access control list.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionRemoves the access control list entry for the user unauthenticated from thespecified access control list.
Command line equivalent:pdadmin acl modify ACL_name remove unauthenticated
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 67
ivadmin_acl_removeuser()
Removes the access control list entry for the specified user from the specifiedaccess control list.
Syntaxunsigned longivadmin_acl_removeuser(
ivadmin_context ctx,const char *aclid,const char *userid,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
aclid The name of the access control list.
userid The name of the user entry to be removed from the access control list.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionRemoves the access control list entry for the specified user from the specifiedaccess control list.
Command line equivalent:pdadmin acl modify ACL_name remove user user_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
68 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_acl_setanyother()
Sets or modifies the access control list entry for the user any-other in the accesscontrol list.
Syntaxunsigned longivadmin_acl_setanyother(
ivadmin_context ctx,const char *aclid,const char *actions,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
aclid Access control list name.
actionsThe new permissions for this access control list entry. This is a stringconsisting of single-letter permission codes. Each action is represented by asingle alphabetic character. Default actions are provided in the primaryaction group by Tivoli Access Manager. These default actions, such as A foradd, or v for view, are listed in the IBM Tivoli Access Manager BaseAdministrator’s Guide.
Actions in the primary action group can be specified first without thename of the action group. Otherwise, the action group name must precedethem. Actions in other action groups must always be preceded with theaction group name, which is enclosed in brackets ([ ]).
For example, to set an entry so that it contains the add and view actionsfrom the primary action group, along with the P, B, and J actions from theAdmin2 action group, and the b and C actions from the Auditors actiongroup, any of the following strings can be used:Av[Admin2]PBJ[Auditors]bC[primary]Av[Admin2]PBJ[Auditors]bC[Auditors]bC[Admin2]PBJ[primary]Av[Admin2]PBJ[primary]Av[Auditors]bC
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets or modifies the access control list entry for the user any-other in the accesscontrol list.
Command line equivalent:pdadmin acl modify ACL_name set any-other perms
Chapter 10. Administration C API reference 69
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
70 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_acl_setdescription()
Set or modify the description for the specified access control list.
Syntaxunsigned longivadmin_acl_setdescription(
ivadmin_context ctx,const char *aclid,const char *description,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
aclid Access control list name.
descriptionNew description.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSet or modify the description for the specified access control list.
Command line equivalent:pdadmin acl modify ACL_name description description
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 71
ivadmin_acl_setgroup()
Sets or modifies the access control list entry for the specified group in the specifiedaccess control list.
Syntaxunsigned longivadmin_acl_setgroup(
ivadmin_context ctx,const char *aclid,const char *groupid,const char *actions,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
aclid Access control list name.
groupidThe access control list entry for this group is set.
actionsThe new permissions for this access control list entry. This is a stringconsisting of single-letter permission codes. Each action is represented by asingle alphabetic character. Default actions are provided in the primaryaction group by Tivoli Access Manager. These default actions, such as A foradd, or v for view, are listed in the IBM Tivoli Access Manager BaseAdministrator’s Guide.
Actions in the primary action group can be specified first without thename of the action group. Otherwise, the action group name must precedethem. Actions in other action groups must always be preceded with theaction group name, which is enclosed in brackets ([ ]).
For example, to set an entry so that it contains the add and view actionsfrom the primary action group, along with the P, B, and J actions from theAdmin2 action group, and the b and C actions from the Auditors actiongroup, any of the following strings can be used:Av[Admin2]PBJ[Auditors]bC[primary]Av[Admin2]PBJ[Auditors]bC[Auditors]bC[Admin2]PBJ[primary]Av[Admin2]PBJ[primary]Av[Auditors]bC
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets or modifies the access control list (ACL) entry for the specified group in thespecified access control list. The Tivoli Access Manager user registry must containan entry for the specified group before you can call this function to add an entryfor the group to an ACL.
72 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Command line equivalent:pdadmin acl modify ACL_name set group group_name perms
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 73
ivadmin_acl_setunauth()
Sets the access control list entry for the user unauthenticated in the specifiedaccess control list.
Syntaxunsigned longivadmin_acl_setunauth(
ivadmin_context ctx,const char *aclid,const char *actions,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
aclid Access control list name.
actionsThe new permissions for this access control list entry. This is a stringconsisting of single-letter permission codes. Each action is represented by asingle alphabetic character. Default actions are provided in the primaryaction group by Tivoli Access Manager. These default actions, such as A foradd, or v for view, are listed in the IBM Tivoli Access Manager BaseAdministrator’s Guide.
Actions in the primary action group can be specified first without thename of the action group. Otherwise, the action group name must precedethem. Actions in other action groups must always be preceded with theaction group name, which is enclosed in brackets ([ ]).
For example, to set an entry so that it contains the add and view actionsfrom the primary action group, along with the P, B, and J actions from theAdmin2 action group, and the b and C actions from the Auditors actiongroup, any of the following strings can be used:Av[Admin2]PBJ[Auditors]bC[primary]Av[Admin2]PBJ[Auditors]bC[Auditors]bC[Admin2]PBJ[primary]Av[Admin2]PBJ[primary]Av[Auditors]bC
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the access control list entry for the user unauthenticated in the specifiedaccess control list.
Command line equivalent:pdadmin acl modify ACL_name set unauthenticated perms
74 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 75
ivadmin_acl_setuser()
Sets the entry for the specified user in the specified access control list.
Syntaxunsigned longivadmin_acl_setuser(
ivadmin_context ctx,const char *aclid,const char *userid,const char *actions,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
aclid Access control list name.
userid The access control list entry for this user is set.
actionsThe new permissions for this access control list entry. This is a stringconsisting of single-letter permission codes. Each action is represented by asingle alphabetic character. Default actions are provided in the primaryaction group by Tivoli Access Manager. These default actions, such as A foradd, or v for view, are listed in the IBM Tivoli Access Manager BaseAdministrator’s Guide.
Actions in the primary action group can be specified first without thename of the action group. Otherwise, the action group name must precedethem. Actions in other action groups must always be preceded with theaction group name, which is enclosed in brackets ([ ]).
For example, to set an entry so that it contains the add and view actionsfrom the primary action group, along with the P, B, and J actions from theAdmin2 action group, and the b and C actions from the Auditors actiongroup, any of the following strings can be used:Av[Admin2]PBJ[Auditors]bC[primary]Av[Admin2]PBJ[Auditors]bC[Auditors]bC[Admin2]PBJ[primary]Av[Admin2]PBJ[primary]Av[Auditors]bC
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionCall this function to specify the permissions that the user is permitted to perform.For a list of the default Tivoli Access Manager actions, see the section about defaultTivoli Access Manager permissions for actions in the IBM Tivoli Access ManagerBase Administrator’s Guide. The Tivoli Access Manager user registry must contain anentry for the specified user before you can use this function to add an entry for theuser to an access control list (ACL).
76 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Command line equivalent:pdadmin acl modify ACL_name set user user_name perms
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 77
ivadmin_action_create()
Defines a new action (permission) code in the primary action group.
Syntaxunsigned longivadmin_action_create(
ivadmin_context ctx,const char *actionid,const char *description,const char *type,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
actionidAction identifier. This must be a single-letter code that does not conflictwith existing permission codes. The input is left as a string for futureexpansion.
descriptionDescription of a permission code. This description appears in the TivoliAccess Manager Web Portal Manager.
type Label for action category. This label appears in the Tivoli Access ManagerWeb Portal Manager.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionDefines a new action (permission) code in the primary action group.
Each action group can contain 32 action codes. The default action group containsthe 18 predefined Tivoli Access Manager action codes. Thus, you can callivadmin_action_create() to add up to 14 new action codes to the primary group.
Actions codes consist of one alphabetic character (a–z or A–Z). Actions codes arecase-sensitive. Each action code only can be used once within an action group. Besure that you do not attempt to redefine the default Tivoli Access Manager actioncodes when adding new codes to the primary group.
Command line equivalent:pdadmin action create name description action_type
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
78 IBM Tivoli Access Manager: Administration C API Developer’s Reference
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 79
ivadmin_action_create_in_group()
Defines a new action (permission) code in the specified action group.
Syntaxunsigned longivadmin_action_create_in_group(
ivadmin_context ctx,const char *actionid,const char *description,const char *type,const char *groupname,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
actionidAction identifier. This must be a single-letter code that does not conflictwith existing permission codes. The input is left as a string for futureexpansion.
descriptionDescription of the permission code. This appears in the Tivoli AccessManager Web Portal Manager.
type Label for the action category. This appears in the Tivoli Access ManagerWeb Portal Manager.
groupnameName of the action group in which to create the action.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionDefines a new action (permission) code in the specified action group. Call thisfunction to add an action code to a user-defined extended action group.
Actions codes consist of one alphabetic character (a–z or A–Z). Actions codes arecase-sensitive. Each action code can be used only once within an action group.Tivoli Access Manager supports up to 32 actions in one action group.
Command line equivalent:pdadmin action create name description action_type action_group_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
80 IBM Tivoli Access Manager: Administration C API Developer’s Reference
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 81
ivadmin_action_delete()
Deletes an action (permission) code from the primary action group.
Syntaxunsigned longivadmin_action_delete(
ivadmin_context ctx,const char *actionid,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
actionidAction identifier. This must be a single-letter code that identifies thepermission to delete.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionDeletes an action (permission) code from the primary action group.
Command line equivalent:pdadmin action delete name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
82 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_action_delete_from_group()
Deletes an action (permission) code from the specified action group.
Syntaxunsigned longivadmin_action_delete_from_group(
ivadmin_context ctx,const char *actionid,const char *groupname,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
actionidAction identifier. This must be a single-letter code that identifies thepermission to delete.
groupnameName of the action group from which to delete the action.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionDeletes an action (permission) code from the specified action group.
Command line equivalent:pdadmin action delete name action_group_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 83
ivadmin_action_getdescription()
Returns the description for the specified action.
Syntaxconst char *ivadmin_action_getdescription(
ivadmin_action action);
ParametersInput
action Pointer to the action.
DescriptionReturns the description for the specified action.
Do not free this string. This data is maintained in the ivadmin_action object.
Command line equivalent:pdadmin action list
This pdadmin command lists information about all the actions, including thedescription for each action.
Return ValuesReturns the description for the specified action. The maximum length for adescription is 1024 characters.
84 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_action_getid()
Returns the action identifier for the specified action.
Syntaxconst char *ivadmin_action_getid(
ivadmin_action action);
ParametersInput
action Pointer to the action.
DescriptionReturns the single character action identifier for the specified action.
Do not free this string. This data is maintained in the ivadmin_action structure.
Command line equivalent:pdadmin action list
This pdadmin command lists information about all the actions, including the codefor each action.
Return ValuesReturns the single character action identifier for the specified action, or NULL if anerror occurred.
Chapter 10. Administration C API reference 85
ivadmin_action_gettype()
Returns the type, or label, for the action category associated with the specifiedaction.
Syntaxconst char *ivadmin_action_gettype(
ivadmin_action action);
ParametersInput
action Pointer to the action.
DescriptionReturns the type, or label, of the action category associated with the specifiedaction.
Do not free this string. This data is maintained in the ivadmin_action structure.
Command line equivalent:pdadmin action list
This pdadmin command lists information about all the actions, including the typefor each action.
Return ValuesReturns the type, or label, of the action category associated with the specifiedaction. There is no limit to the length of the label.
86 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_action_group_create()
Creates a new action group with the specified name.
Syntaxunsigned longivadmin_action_group_create(
ivadmin_context ctx,const char *groupname,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
groupnameName of the new action group.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionCreates a new action group with the specified name. Tivoli Access Managersupports a maximum of 32 action groups. Command line equivalent:pdadmin action group create action_group_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 87
ivadmin_action_group_delete()
Deletes the specified action group and all the actions that belong to the specifiedgroup.
Syntaxunsigned longivadmin_action_group_delete(
ivadmin_context ctx,const char *groupname,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
groupnameName of the action group to delete.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionDeletes the specified action group and all of the actions that belong to the specifiedgroup.
Command line equivalent:pdadmin action group delete action_group_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
88 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_action_group_list()
Lists all the defined action group names.
Syntaxunsigned longivadmin_action_group_list(
ivadmin_context ctx,unsigned long *count,char ***names,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
Output
count The number of action group names returned. Zero is returned if an erroroccurs.
names An array of pointers to the action group names returned. You must free thecharacter data referenced by each pointer, as well as the array of pointerswhen they are no longer needed.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionLists all the defined action group names.
Command line equivalent:pdadmin action group list
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 89
ivadmin_action_list()
Lists all the defined action (permission) codes from the primary action group.
Syntaxunsigned longivadmin_action_list(
ivadmin_context ctx,unsigned long *count,ivadmin_action **actions,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
Output
count The number of actions returned. Zero is returned if an error occurs.
actions An array of pointers to the actions returned. You must free the datareferenced by each pointer, as well as the array of pointers when they areno longer needed.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionLists all the defined action (permission) codes from the primary action group. Usethis function to obtain an opaque list of actions. You can then use additionalfunctions to obtain information from each action (ivadmin_action). For example,you can use ivadmin_action_getdescription() to obtain a description for thespecified ivadmin_action object.
Command line equivalent:pdadmin action list
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
90 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_action_list_in_group()
Lists all the defined action (permission) codes from the specified action group.
Syntaxunsigned longivadmin_action_list_in_group(
ivadmin_context ctx,const char *actiongroup,unsigned long *count,ivadmin_action **actions,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
actiongroupName of the action group to list.
Output
count The number of actions returned. Zero is returned if an error occurs.
actions An array of pointers to the actions returned. You must free the datareferenced by each pointer, as well as the array of pointers when they areno longer needed.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionLists all the defined action (permission) codes from the specified action group.
Command line equivalent:pdadmin action list action_group_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 91
ivadmin_cfg_addreplica()Adds a replica entry to the configuration file.
Syntaxunsigned longivadmin_cfg_addreplica(
const char *cfg_file_name,const char *ivacld_host,int ivacld_port,int ivacld_rank,ivadmin_response *rsp
);
ParametersInput
cfg_file_nameSpecifies the configuration file to use. Unless the configuration file is in thecurrent directory, this must be a fully qualified path name.
ivacld_hostSpecifies the TCP host name of the ivacld server.
ivacld_portSpecifies the listening port number of the ivacld replica server. This is theport number on which the ivacld server listens for requests.
ivacld_rankSpecifies the replica order of preference among other replicas.
Output
rsp Specifies the response object. Indicates the success or failure of thefunction. Contains error information. Free this object when it is no longerneeded.
DescriptionCommand line equivalent:svrsslcfg -add_replica -f cfg_file -h host_name [-p port] [-k rank]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
92 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_cfg_chgreplica()Changes parameters of a replica entry in the configuration file.
Syntaxunsigned longivadmin_cfg_chgreplica(
const char *cfg_file_name,const char *ivacld_host,int ivacld_port,int ivacld_rank,ivadmin_response *rsp
);
ParametersInput
cfg_file_nameSpecifies the configuration file to use. Unless the configuration file is in thecurrent directory, this must be a fully qualified path name.
ivacld_hostSpecifies the TCP host name of the ivacld server.
ivacld_portSpecifies the listening port number of the ivacld replica server. This is theport number on which the ivacld server listens for requests.
ivacld_rankSpecifies the replica order of preference among other replicas.
Output
rsp Specifies the response object. Indicates the success or failure of thefunction. Contains error information. Free this object when it is no longerneeded.
DescriptionCommand line equivalent:svrsslcfg -chg_replica -f cfg_file -h host_name [-p port] [-k rank]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 93
ivadmin_cfg_configureserver2()Configures an authorization API server by updating the configuration file andcreating the keyring database.
Syntaxunsigned longivadmin_cfg_configureserver2(
ivadmin_context ctx,const char *cfg_file_name,const char *kdb_dir_name,const char *server_name,const char *host_name,ivadmin_cfg_servertype server_type,const char *server_pwd,int enable_listening,int listening_port,int enable_refresh,int kdb_pwd_life,int ssl_timeout,const char *appl_cert,const char *azn_app_host,ivadmin_response *rsp
);
ParametersInput
ctx Specifies the context to use when communicating with the Tivoli AccessManager policy server.
cfg_file_nameSpecifies the configuration file to use. Unless the configuration file is in thecurrent directory, this must be a fully qualified path name.
kdb_dir_nameSpecifies the keyring database directory.
server_nameSpecifies a unique server name.
host_nameSpecifies the host name on which the application runs.
server_typeSpecifies the server type. Possible values are local or remote.
server_pwdAdministrator password.
enable_listeningSets the listening-enabled flag in the configuration file.
listening_portSpecifies the TCP/IP port on which the application listens.
enable_refreshEnables or disables the certificate automatic refresh support.
kdb_pwd_lifeSpecifies the keyring database password life in days. If it is 0, a default of183 days is used.
94 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ssl_timeoutSpecifies the Secure Sockets Layer (SSL) session timeout value in seconds.If it is 0, a default of 7200 is used.
appl_certSpecifies the name of the file that contains a base-64 encoded SSLcertificate. This is an optional parameter. If specified, the certificate isstored in the keyring database using a label of APPL_LDAP_CERT. Typicaluse of this parameter is to store the certificate authority certificate that theapplication uses when it authenticates directly to the user registry.
Do not confuse this certificate with the certificate that is used toauthenticate with the Tivoli Access Manager policy server. The certificatespecified by this parameter does not participate in authentication with thepolicy server; it is strictly for application use and allows the application touse a single keyring database for all SSL certificates.
azn_app_hostThe host name to be written to the azn-host-name entry in theconfiguration file and used by the application at runtime.
This optional parameter is needed only if the host name returned by theTCP gethostbyname() is incorrect or different from the host_nameparameter specified.
Output
rsp Specifies the response object. Indicates the success or failure of thefunction. Contains error information. Free this object when it is no longerneeded.
DescriptionConfigures an authorization API server by updating the configuration file andcreating the keyring database.
Command line equivalent:svrsslcfg -config -f cfg_file_name -d kdb_dir_name -n server_name \-s server_type -r listening_port -P admin_pwd [-S server_pwd] \[-A admin_ID] [-t ssl_timeout] [-e kbd_pwd_life] [-l listening_mode]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 95
ivadmin_cfg_renewservercert()Renews the server Secure Sockets Layer (SSL) certificate.
Syntaxunsigned longivadmin_cfg_renewservercert(
ivadmin_context ctx,const char *cfg_file_name,const char *server_name,const char *host_name,ivadmin_response *rsp
);
ParametersInput
ctx Specifies the context to use when communicating with the Tivoli AccessManager policy server.
cfg_file_nameSpecifies the configuration file to use. Unless the configuration file is in thecurrent directory, this must be a fully qualified path name.
server_nameSpecifies the unique server name.
host_nameSpecifies the host name on which the application will run.
Output
rsp Specifies the response object. Indicates the success or failure of thefunction. Contains error information. Free this object when it is no longerneeded.
DescriptionUse this API to refresh the certificate used to authenticate with the policy server ifit has expired or been compromised. The application must be stopped before usingthis API.
Command line equivalent:svrsslcfg -chgcert -f cfg_file -n server_name [-A admin_id] -P admin_pwd
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
96 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_cfg_rmvreplica()Removes a replica entry from the configuration file.
Syntaxunsigned longivadmin_cfg_rmvreplica(
const char *cfg_file_name,const char *ivacld_host,ivadmin_response *rsp
);
ParametersInput
cfg_file_nameSpecifies the configuration file to use. Unless the configuration file is in thecurrent directory, this must be a fully qualified path name.
ivacld_hostSpecifies the TCP host name of the ivacld server.
Output
rsp Specifies the response object. Indicates the success or failure of thefunction. Contains error information. Free this object when it is no longerneeded.
DescriptionRemoves a replica entry from the configuration file.
Command line equivalent:svrsslcfg -chg_replica -f cfg_file -h host_name [-p port] [-k rank]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 97
ivadmin_cfg_setapplicationcert()Replaces the optional application certificate authority certificate and the optionalSecure Sockets Layer (SSL) certificate in the keyring database.
Syntaxunsigned longivadmin_cfg_setapplicationcert(
const char *cfg_file_name,const char *appl_cert,ivadmin_response *rsp
);
ParametersInput
cfg_file_nameSpecifies the configuration file to use. Unless the configuration file is in thecurrent directory, this must be a fully qualified path name.
appl_certSpecifies the name of the file that contains a base-64 encoded SSLcertificate. This is an optional parameter. If specified, the certificate isstored in the keyring database using a label of APPL_LDAP_CERT. Typicaluse of this parameter is to store the certificate authority certificate that theapplication uses when it authenticates directly to the user registry.
Do not confuse this certificate with the certificate that is used toauthenticate with the Tivoli Access Manager policy server. The certificatespecified by this parameter does not participate in authentication with thepolicy server; it is strictly for application use and allows the application touse a single keyring database for all SSL certificates.
Output
rsp Specifies the response object. Indicates the success or failure of thefunction. Contains error information. Free this object when it is no longerneeded.
DescriptionThe application must be stopped prior to invoking this API.
Command line equivalent:svrsslcfg -modify -f cfg_file [-t timeout] [-C cert_file] [-llistening_mode]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
98 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_cfg_setkeyringpwd()Refreshes or changes the keyring database password.
Syntaxunsigned longivadmin_cfg_setkeyringpwd(
const char *cfg_file_name,int kdb_pwd_life,ivadmin_response *rsp
);
ParametersInput
cfg_file_nameSpecifies the configuration file to use. Unless the configuration file is in thecurrent directory, this must be a fully qualified path name.
kdb_pwd_lifeSpecifies the keyring database password life in days. If 0, a default of 183days is used.
Output
rsp Specifies the response object. Indicates the success or failure of thefunction. Contains error information. Free this object when it is no longerneeded.
DescriptionUse this API to refresh or change the keyring database random password. A newrandom password is created in the stash file. The application must be stopped toexecute this API.
Command line equivalent:svrsslcfg -chgcert -f cfg_file -n server_name [-A admin_id] -P admin_pwd
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 99
ivadmin_cfg_setlistening()
Sets or resets the enable-listening parameter in the configuration file.
Syntaxunsigned longivadmin_cfg_setlistening(
const char *cfg_file_name,int enable_listening,ivadmin_response *rsp
);
ParametersInput
cfg_file_nameSpecifies the configuration file to use. Unless the configuration file is in thecurrent directory, this must be a fully qualified path name.
enable_listeningSets the listening-enabled flag in the configuration file.
Output
rsp Specifies the response object. Indicates the success or failure of thefunction. Contains error information. Free this object when it is no longerneeded.
DescriptionThe listening port in the configuration file must be nonzero to enable listening.Otherwise, an invalid parameter error is returned. The application must be stoppedand restarted after calling this API.
Command line equivalent:svrsslcfg -chgcert -f cfg_file -modify -l yes
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
100 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_cfg_setport()Changes the listening port number of the application and updates the port numberin the configuration file.
Syntaxunsigned longivadmin_cfg_setport(
const char *cfg_file_name,int listening_port,ivadmin_response *rsp
);
ParametersInput
cfg_file_nameSpecifies the configuration file to use. Unless the configuration file is in thecurrent directory, this must be a fully qualified path name.
listening_portSpecifies the TCP/IP port on which the application listens.
Output
rsp Specifies the response object. Indicates the success or failure of thefunction. Contains error information. Free this object when it is no longerneeded.
DescriptionThe server must be stopped and restarted to activate this change. If the port is setto zero, the listen-flags are set to disable.
Command line equivalent:svrsslcfg –config -f cfg_file_name -d kdb_dir_name -n server_name \-s server_type -r listening_port -P admin_pwd [-S server_pwd] \[-A admin_ID] [-t ssl_timeout] [-e kbd_pwd_life] [-l listening_mode]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. If a server was specified, this indicates the successfulnotification and database replication by that server. If no server isspecified, this indicates that the policy server has begun notifying eachauthorization server, but is not an indication of successful notification orreplication to any one of those servers.
IVADMIN_FALSEDefined as 0. If a server was specified, this indicates the failure of thenotification and database replication by that server. If no server isspecified, this indicates a failure has occurred in requesting that the policyserver begin notifying each authorization server.
Chapter 10. Administration C API reference 101
ivadmin_cfg_setssltimeout()Changes the Secure Sockets Layer (SSL) timeout value in the configuration file.
Syntaxunsigned longivadmin_cfg_setssltimeout(
const char *cfg_file_name,int ssl_timeout,ivadmin_response *rsp
);
ParametersInput
cfg_file_nameSpecifies the configuration file to use. Unless the configuration file is in thecurrent directory, this must be a fully qualified path name.
ssl_timeoutSpecifies the SSL session timeout value in seconds. If 0 is specified, adefault of 7200 is used.
Output
rsp Specifies the response object. Indicates the success or failure of thefunction. Contains error information. Free this object when it is no longerneeded.
DescriptionThe application must be stopped and restarted to activate this change.
Command line equivalent:svrsslcfg -modify -f cfg_file [-t timeout] [-C cert_file] [-llistening_mode]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
102 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_cfg_unconfigureserver()Unconfigures an authorization API server.
Syntaxunsigned longivadmin_cfg_unconfigureserver(
ivadmin_context ctx,const char *cfg_file_name,const char *server_name,const char *host_name,ivadmin_response *rsp
);
ParametersInput
ctx Specifies the context to use when communicating with the Tivoli AccessManager policy server.
cfg_file_nameSpecifies the configuration file to use. Unless the configuration file is in thecurrent directory, this must be a fully qualified path name.
server_nameSpecifies a unique server name.
host_nameSpecifies the host name on which the application runs.
Output
rsp Specifies the response object. Indicates the success or failure of thefunction. Contains error information. Free this object when it is no longerneeded.
DescriptionThis API reports success even if the server was not configured. This commanddestroys the keyring, any objects in the user registry, and the access control list(ACL) database for the server.
The application must be stopped before calling this API.
Command line equivalent:svrsslcfg –unconfig -f cfg_file_name -n server_name \[-P admin_password] [-A admin_ID]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 103
ivadmin_context_cleardelcred()
Clears the delegated credential for the context.
Syntaxunsigned longivadmin_context_cleardelcred(
ivadmin_context ctx,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionClears the delegated credential for the context.
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
104 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_context_create()
Creates a context.
Syntaxunsigned longivadmin_context_create(
const char *keyringfile,const char *keyringstashfile,const char *keyringpassword,const char *userid,const char *pwd,const char *serverdn,const char *serverhost,unsigned long port,ivadmin_context *ctx,ivadmin_response *rsp
);
ParametersInput
keyringfileFully qualified path name to the Secure Sockets Layer (SSL) keyring filethat contains the public key of the Tivoli Access Manager policy server.
keyringstashfileFully qualified path name to the stash file that contains the password usedto access the keyring file. You must specify either a keyring stash file orkeyring file password.
If you specify both, the password will be used. If you specify neither, aninvalid input error is returned.
keyringpasswordPassword used to access the keyring file. You must specify either a keyringstash file or a keyring file password. If you specify both, the password isused. If you specify neither, an invalid input error is returned.
userid Administrator user name to authenticate as. This user must be a memberof the following user registry group:cn=iv-admin,cn=SecurityGroups,secauthority=default
pwd Administrator password.
serverdnTivoli Access Manager policy server certificate distinguished name used toauthenticate the Tivoli Access Manager policy server.
This parameter is optional. If you do not want to authenticate the TivoliAccess Manager policy server you can specify NULL or an empty string.
serverhostTivoli Access Manager policy server host name or IP address.
port Tivoli Access Manager policy server listening port number.
Output
ctx Returned context. This is used to send administration requests to the TivoliAccess Manager policy server. This object should be freed when it is nolonger needed.
Chapter 10. Administration C API reference 105
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionThe context represents a connection to the Tivoli Access Manager policy server. Tosuccessfully create a context the Tivoli Access Manager policy server must beavailable and the authentication must be successful.
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
106 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_context_createdefault()
Creates a context using the default Secure Sockets Layer (SSL) configuration.
Syntaxunsigned longivadmin_context_createdefault(
const char *userid,const char *pwd,ivadmin_context *ctx,ivadmin_response *rsp
);
ParametersInput
userid Administrator user name to use for authenticating. This user must be amember of the following user registry group:cn=iv-admin,cn=SecurityGroups,secauthority=default
pwd Administrator password.
Output
ctx Returned context. This is used to send administration requests to the TivoliAccess Manager policy server. Free this object when it is no longer needed.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionThe context represents a connection to the Tivoli Access Manager policy server. Thelocation of the Tivoli Access Manager policy server and SSL information isretrieved from the current Tivoli Access Manager runtime environmentconfiguration.
To successfully create a context, the Tivoli Access Manager policy server must beavailable and the authentication must be successful.
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 107
ivadmin_context_delete()
Deletes the connection with the Tivoli Access Manager policy server.
Syntaxunsigned longivadmin_context_delete(
ivadmin_context ctx,ivadmin_response *rsp
);
ParametersInput
ctx Context for communicating with the Tivoli Access Manager policy server.This is the context to delete.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionDeletes the connection with the Tivoli Access Manager policy server. This must becalled before exiting the program. Deleting the connection enables the client andTivoli Access Manager policy server to free Secure Sockets Layer (SSL) resources.The context is no longer usable; free the context memory after this call.
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
108 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_context_getaccexpdate()
Gets the account expiration date for all user accounts.
Syntaxunsigned longivadmin_context_getaccexpdate(
ivadmin_context ctx,unsigned long *seconds,unsigned long *unlimited,unsigned long *unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
Output
secondsReturned date and time of the expiration of all user accounts. This is thenumber of seconds since 00:00:00 Universal time, 1 January 1970 (same astime_t).
unlimitedReturned the account expiration not restricted indicator.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets the account expiration date for all user accounts.
Command line equivalent:pdadmin policy get account-expiry-date
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 109
ivadmin_context_getdisabletimeint()
Gets the time to disable user accounts when the maximum number of loginfailures is exceeded. This setting applies to all user accounts.
Syntaxunsigned longivadmin_context_getdisabletimeint(
ivadmin_context ctx,unsigned long *seconds,unsigned long *disable,unsigned long *unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
Output
secondsDisable the user account for the specified number of seconds if themaximum number of login failures is exceeded.
disable Disable the user account if the maximum number of login failures isexceeded. Administrator action is required to enable the account.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets the time to disable user accounts if the maximum number of login failureshas been exceeded. This setting applies to all user accounts.
Command line equivalent:pdadmin policy get disable-time-interval
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
110 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_context_getmaxlgnfails()
Gets the maximum number of login failures allowed for each user account.
Syntaxunsigned longivadmin_context_getmaxlgnfails(
ivadmin_context ctx,unsigned long *failures,unsigned long *unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
Output
failures Maximum number of login failures allowed.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets the maximum number of login failures allowed for each user account.
Command line equivalent:pdadmin policy get max-login-failures
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 111
ivadmin_context_getmaxpwdage()
Gets the maximum password age for all user accounts.
Syntaxunsigned longivadmin_context_getmaxpwdage(
ivadmin_context ctx,unsigned long *seconds,unsigned long *unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
Output
secondsReturned maximum lifetime, in seconds, before expiration of password.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets the maximum password age for all user accounts.
Command line equivalent:pdadmin policy get max-password-age
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
112 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_context_getmaxpwdrepchars()
Gets the maximum number of repeated characters allowed in a password for eachuser account.
Syntaxunsigned longivadmin_context_getmaxpwdrepchars(
ivadmin_context ctx,unsigned long *chars,unsigned long *unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
Output
chars Maximum number of repeated characters allowed.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets the maximum number of repeated characters allowed in a password for eachuser account.
Command line equivalent:pdadmin policy get max-password-repeated-chars
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 113
ivadmin_context_getminpwdalphas()
Gets the minimum number of alphabetic characters allowed in a password for eachuser account.
Syntaxunsigned longivadmin_context_getminpwdalphas(
ivadmin_context ctx,unsigned long *chars,unsigned long *unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
Output
chars Minimum number of alphabetic characters allowed.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets the minimum number of alphabetic characters allowed in a password for eachuser account.
Command line equivalent:pdadmin policy get min-password-alphas
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
114 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_context_getminpwdnonalphas()
Gets the minimum number of nonalphabetic characters allowed in a password foreach user account.
Syntaxunsigned longivadmin_context_getminpwdnonalphas(
ivadmin_context ctx,unsigned long *chars,unsigned long *unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
Output
chars Minimum number of nonalphabetic characters allowed.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets the minimum number of nonalphabetic characters allowed in a password foreach user account.
Command line equivalent:pdadmin policy get min-password-non-alphas
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 115
ivadmin_context_getminpwdlen()
Gets the minimum password length for all user accounts.
Syntaxunsigned longivadmin_context_getminpwdlen(
ivadmin_context ctx,unsigned long *length,unsigned long *unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
Output
length The minimum allowed password length.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets the minimum password length for all user accounts.
Command line equivalent:pdadmin policy get min-password-length
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
116 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_context_getpwdspaces()
Gets whether spaces are allowed in passwords for all user accounts.
Syntaxunsigned longivadmin_context_getpwdspaces(
ivadmin_context ctx,unsigned long *allowed,unsigned long *unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
Output
allowedIndicates whether spaces are allowed in passwords.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets whether spaces are allowed in passwords for all user accounts.
Command line equivalent:pdadmin policy get password-spaces
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 117
ivadmin_context_gettodaccess()
Gets the global time of day access policy.
Syntaxunsigned longivadmin_context_gettodaccess(
ivadmin_context ctx,unsigned long *days,unsigned long *start,unsigned long *end,unsigned long *reference,unsigned long *unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
Output
days A bitmap of the days for the time of day access policy.
start The minutes after midnight for the start of the time range.
end The minutes after midnight for the end of the time range.
referenceThe time zone: Coordinated Universal Time (UTC) or local.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets the global time of day access policy
Command line equivalent:pdadmin policy get todaccess
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
118 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_context_getuserreg()
Returns an indicator of which type of user registry is configured for the TivoliAccess Manager policy server.
Syntaxunsigned longivadmin_context_getuserreg(
ivadmin_context ctx,unsigned long *registry,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
Output
registryPointer a registry type indicator (IVADMIN_CONTEXT_DCEUSERREG orIVADMIN_CONTEXT_LDAPUSERREG).
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionReturns an indicator of which type of user registry is configured for this TivoliAccess Manager policy server. The following indicators are defined:#define IVADMIN_CONTEXT_DCEUSERREG 0#define IVADMIN_CONTEXT_LDAPUSERREG 1
Command line equivalent:pdadmin admin show configuration
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 119
ivadmin_context_setaccexpdate()
Sets the account expiration date for all user accounts.
Syntaxunsigned longivadmin_context_setaccexpdate(
ivadmin_context ctx,unsigned long seconds,unsigned long unlimited,unsigned long unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
secondsDate and time of the expiration of all user accounts. This is the number ofseconds since 00:00:00 Universal time, 1 January 1970 (same as time_t).
unlimitedDo not expire user accounts and ignore seconds parameter if set to true.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the account expiration date for all user accounts.
Command line equivalent:pdadmin policy set account-expiry-date {unlimited | absolute_time | unset}
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
120 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_context_setdelcred()
Sets the delegated credential for the context based on the specified PrivilegeAttribute Certificate (PAC).
Syntaxunsigned longivadmin_context_setdelcred(
ivadmin_context ctx,const unsigned char* pacValue,const unsigned long pacLength,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
pacValueThe credential PAC data.
pacLengthThe credential PAC length.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the delegated credential for the context based on the specified PAC. Only onecredential can be delegated at a time. If a delegated credential already exists forthis context, it is overwritten.
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 121
ivadmin_context_setdisabletimeint()
Sets the time to disable each user account when the maximum number of loginfailures is exceeded.
Syntaxunsigned longivadmin_context_setdisabletimeint(
ivadmin_context ctx,unsigned long seconds,unsigned long disable,unsigned long unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
secondsDisable the user account for the specified number of seconds when themaximum number of login failures is exceeded.
disable Disable the user account when the maximum number of login failures isexceeded. Administrator action is required to enable the account.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the time to disable each user account when the maximum number of loginfailures is exceeded.
Command line equivalent:pdadmin policy set disable-time-interval {number | unset | disable}
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
122 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_context_setmaxlgnfails()
Sets the maximum number of login failures allowed for each user account.
Syntaxunsigned longivadmin_context_setmaxlgnfails(
ivadmin_context ctx,unsigned long failures,unsigned long unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
failures Maximum number of login failures allowed.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the maximum number of login failures allowed for each user account.
Command line equivalent:pdadmin policy set max-login-failures number | unset
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 123
ivadmin_context_setmaxpwdage()
Sets the maximum password age for all user accounts.
Syntaxunsigned longivadmin_context_setmaxpwdage(
ivadmin_context ctx,unsigned long seconds,unsigned long unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
secondsMaximum lifetime, in seconds, before expiration of a password.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the maximum password age for all user accounts.
Command line equivalent:pdadmin policy set max-password-age {unset | relative_time}
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
124 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_context_setmaxpwdrepchars()
Sets the maximum number of repeated characters allowed in a password for eachuser account.
Syntaxunsigned longivadmin_context_setmaxpwdrepchars(
ivadmin_context ctx,unsigned long chars,unsigned long unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
chars Maximum number of repeated characters allowed.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the maximum number of repeated characters allowed in a password for eachuser account.
Command line equivalent:pdadmin policy set max-password-repeated-chars number | unset
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 125
ivadmin_context_setminpwdalphas()
Sets the minimum number of alphabetic characters allowed in a password for eachuser account.
Syntaxunsigned longivadmin_context_setminpwdalphas(
ivadmin_context ctx,unsigned long chars,unsigned long unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
chars Minimum number of alphabetic characters allowed.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the minimum number of alphabetic characters allowed in a password for eachuser account.
Command line equivalent:pdadmin policy set min-password-alphas {unset | number}
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
126 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_context_setminpwdnonalphas()
Sets the minimum number of nonalphabetic characters allowed in a password foreach user account.
Syntaxunsigned longivadmin_context_setminpwdnonalphas(
ivadmin_context ctx,unsigned long chars,unsigned long unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
chars Minimum number of nonalphabetic characters allowed.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the minimum number of nonalphabetic characters allowed in a password foreach user account.
Command line equivalent:pdadmin policy set min-password-non-alphas {unset | number}
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 127
ivadmin_context_setminpwdlen()
Sets the minimum password length for each user account.
Syntaxunsigned longivadmin_context_setminpwdlen(
ivadmin_context ctx,unsigned long length,unsigned long unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
length Minimum allowed password length to be set.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the minimum password length for each user account.
Command line equivalent:pdadmin policy set min-password-length {unset | number}
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
128 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_context_setpwdspaces()
Sets whether spaces are allowed in passwords for all user accounts.
Syntaxunsigned longivadmin_context_setpwdspaces(
ivadmin_context ctx,unsigned long allowed,unsigned long unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
allowedIndicates whether spaces are allowed in passwords
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets whether spaces are allowed in passwords for all user accounts.
Command line equivalent:pdadmin policy set password-spaces {yes | no | unset}
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 129
ivadmin_context_settodaccess()
Sets the global time of day access policy.
Syntaxunsigned longivadmin_context_settodaccess(
ivadmin_context ctx,unsigned long days,unsigned long start,unsigned long end,unsigned long reference,unsigned long unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
days A bitmap of the days for the time of day policy.
start The minutes after midnight for the start of the time range.
end The minutes after midnight for the end of the time range.
referenceThe time zone: Coordinated Universal Time (UTC) or local.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the global yime of day access policy.
Command line equivalent:pdadmin policy set todaccess todaccess_string
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
130 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_free()
Frees the memory that has been allocated to the specified object.
Syntaxvoidivadmin_free(
void p*);
ParametersInput
p Pointer to the object to be freed.
DescriptionFrees the memory that has been allocated to the specified object.
Use this function to free all memory that has been allocated by the administrationAPI functions.
There is no command line equivalent for this function.
Chapter 10. Administration C API reference 131
ivadmin_group_addmembers()
Adds the specified users to the specified group.
Syntaxunsigned longivadmin_group_addmembers(
ivadmin_context ctx,const char *groupid,unsigned long user_count,const char **users,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
groupidGroup name.
user_countThe number of users to be added to the group.
users New member user names.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionAdds the specified users to the specified group. Tivoli Access Manager does notsupport a group as a group member.
Command line equivalents:pdadmin group modify group_name add user_name
pdadmin group modify group_name add (user_name1 user_name2 ... )
User registry difference: Attempting to add a duplicate user to a group is handleddifferently depending on what user registry is beingused. See Table 36 on page 290 for details.
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
132 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_group_create2()
Creates a group.
Syntaxunsigned longivadmin_group_create2(
ivadmin_context ctx,const char *groupid,const char *dn,const char *cn,const char *group_container,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
groupidGroup name.
dn User registry distinguished name.
cn User registry common name attribute.
group_containerContainer object within the management object space. Can be NULL toindicate that it is at the root level.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionCreates a new Tivoli Access Manager group by creating a new group in the userregistry with the specified name, distinguished name, and common name.
User registry difference: Leading and trailing blanks in a group name do notmake the name unique when using an LDAP or ActiveDirectory user registry. However, leading and trailingblanks do make the group name unique when using aDomino server as a user registry. To keep nameprocessing consistent regardless of what user registry isbeing used, do not define group names with leading ortrailing blanks.
Command line equivalent:pdadmin group create group_name dn cn
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
Chapter 10. Administration C API reference 133
IVADMIN_FALSEDefined as 0. The function encountered an error.
134 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_group_delete2()
Deletes the specified group.
Syntaxunsigned longivadmin_group_delete2(
ivadmin_context ctx,const char *groupid,unsigned long registry,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
groupidGroup name.
registryIndicates whether to delete the group from the user registry as well asfrom Tivoli Access Manager.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionDeletes the specified group. Deletes all Tivoli Access Manager information aboutthe group and optionally deletes the user registry contents.
Command line equivalent:pdadmin group delete [–registry] group_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 135
ivadmin_group_get()
Gets the specified group object.
Syntaxunsigned longivadmin_group_get(
ivadmin_context ctx,const char *groupid,ivadmin_ldapgroup *group,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
groupidGroup name.
Output
group Returned group. Free the memory for this ivadmin_ldapgroup object whenit is no longer needed.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets the group object for the specified group name. Free the memory for thisivadmin_ldapgroup object when it is no longer needed.
Command line equivalent:pdadmin group show group-name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
136 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_group_getbydn()
Returns a group user using the user registry distinguished name for identification.
Syntaxunsigned longivadmin_group_getbydn(
ivadmin_context ctx,const char *dn,ivadmin_ldapgroup *group,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
dn User registry distinguished name of group.
Output
group Returned group. Free this memory when no longer needed.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionReturns a group user using the user registry DN for identification. Free thememory for this ivadmin_ldapgroup object when it is no longer needed.
User registry difference: The maximum length of the distinguished name variesdepending on the user registry being used. SeeAppendix B, “User registry differences”, on page 289 todetermine the maximum length in your environment.
Command line equivalent:pdadmin group show-dn dn
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 137
ivadmin_group_getcn()
Returns the user registry common name attribute for the specified group.
Syntaxconst char *ivadmin_group_getcn(
ivadmin_ldapgroup group);
ParametersInput
group Pointer to the group structure.
DescriptionReturns the user registry common name attribute from the specified group object.
Do not free this memory. This data is maintained in the ivadmin_ldapgroupstructure.
User registry difference: The maximum length of the common name variesdepending on the user registry being used. SeeAppendix B, “User registry differences”, on page 289 todetermine the maximum length in your environment.
Command line equivalent:pdadmin group show group-name
The user registry common name is part of the information returned by thepdadmin group show command.
Return ValuesReturns the user registry common name attribute for the specified group.
138 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_group_getdescription()
Returns the user registry description for the specified group.
Syntaxconst char *ivadmin_group_getdescription(
ivadmin_ldapgroup group);
ParametersInput
group Pointer to the group structure.
DescriptionReturns the user registry description for the specified group.
Do not free this memory. This data is maintained in the ivadmin_ldapgroupstructure.
Command line equivalent:pdadmin group show group-name
The description is part of the information returned by the pdadmin group showcommand.
Return ValuesReturns the user registry description for the specified group. The maximum lengthof a description is 1024 characters.
Chapter 10. Administration C API reference 139
ivadmin_group_getdn()Returns the user registry distinguished name for the specified group.
Syntaxconst char *ivadmin_group_getdn(
ivadmin_ldapgroup group);
ParametersInput
group Pointer to the group structure.
DescriptionReturns the user registry distinguished name for the specified group.
Do not free this memory. This data is maintained in the ivadmin_ldapgroupstructure.
User registry difference: The maximum length of the distinguished name variesdepending on the user registry being used. SeeAppendix B, “User registry differences”, on page 289 todetermine the maximum length in your environment.
Command line equivalent:pdadmin group show group-name
The user registry distinguished name is part of the information returned by thepdadmin group show command.
Return ValuesReturns the user registry distinguished name for the specified group.
140 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_group_getid()
Returns the group name from the specified group object.
Syntaxconst char *ivadmin_group_getid(
ivadmin_ldapgroup group);
ParametersInput
group Pointer to the group structure.
DescriptionReturns the group name from the specified group object.
Do not free this memory. This data is maintained in the ivadmin_ldapgroupstructure.
Command line equivalent:pdadmin group show group-name
The group name is part of the information returned by the pdadmin group showcommand.
Return ValuesReturns the group name from the specified group object. The maximum length of agroup name is 256 characters.
Chapter 10. Administration C API reference 141
ivadmin_group_getmembers()
Lists the user names of the members of the specified group.
Syntaxunsigned longivadmin_group_getmembers(
ivadmin_context ctx,const char *groupid,unsigned long *count,char ***userids,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
groupidGroup name.
Output
count The number of user names returned. Zero is returned if an error occurs.
userids An array of pointers to the user names returned. You must free thecharacter data referenced by each pointer, as well as the array of pointerswhen they are no longer needed.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionLists the user names of the members of the specified group.
Command line equivalent:pdadmin group show-members group_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
142 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_group_import2()
Creates an Tivoli Access Manager group by importing a group that already existsin the user registry.
Syntaxunsigned longivadmin_group_import2(
ivadmin_context ctx,const char *groupid,const char *dn,const char *group_container,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
groupidGroup name.
dn User registry distinguished name.
group_containerContainer object within the management object space. Can be NULL toindicate that it is at the root level.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionCreates an Tivoli Access Manager group by importing a group that already existsin the user registry.
Command line equivalent:pdadmin group import group_name dn
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 143
ivadmin_group_list()
Lists the Tivoli Access Manager groups.
Syntaxunsigned longivadmin_group_list(
ivadmin_context ctx,const char *pattern,unsigned long maxreturn,unsigned long *count,char ***groupids,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
pattern Pattern match for group names. IVADMIN_ALLPATTERN indicates allgroups.
maxreturnMaximum number to return. IVADMIN_MAXRETURN indicatesunlimited. This number can also be limited by the user registry server sothe maximum returned is really the minimum of the server configurationand this value.
Output
count The number of group names returned. Zero is returned if an error occurs.
groupidsAn array of pointers to the group names returned. You must free thecharacter data referenced by each pointer, as well as the array of pointerswhen they are no longer needed..
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionLists the Tivoli Access Manager groups. Returns the list of group names whosename matches the pattern specified.
The order returned is the order created.
Command line equivalent:pdadmin group list pattern max_return
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
144 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_group_listbydn()
Returns the list of user registry distinguished names whose user registry commonname attribute matches the pattern specified.
Syntaxunsigned longivadmin_group_listbydn(
ivadmin_context ctx,const char *pattern,unsigned long maxreturn,unsigned long *count,char ***dns,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
patternPattern match for common name attribute. IVADMIN_ALLPATTERNindicates all users.
maxreturnMaximum number to return. IVADMIN_MAXRETURN indicatesunlimited. This number can also be limited by the user registry server sothat the maximum returned is really the minimum of the serverconfiguration and this value.
Output
count The number of user registry distinguished names returned. Zero isreturned if an error occurs.
dns An array of pointers to the user registry distinguished names returned. Youmust free the character data referenced by each pointer, as well as thearray of pointers when they are no longer needed.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionReturns the list of user registry distinguished names whose user registry commonname attributes match the pattern specified.
User registry difference: The maximum length of the distinguished name variesdepending on the user registry being used. SeeAppendix B, “User registry differences”, on page 289 todetermine the maximum length in your environment.
Command line equivalent:pdadmin group list-dn pattern max_return
Return ValuesReturns the following Boolean values:
Chapter 10. Administration C API reference 145
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
146 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_group_removemembers()
Removes the specified users from the specified group.
Syntaxunsigned longivadmin_group_removemembers(
ivadmin_context ctx,const char *groupid,unsigned long user_count,const char **users,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
groupidGroup name.
user_countNumber of user names to remove.
users Member user names to remove.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionRemoves the specified users from the specified group.
Command line equivalents:pdadmin group modify group_name remove user_name
pdadmin group modify group_name remove ( user_name1 user_name2 ... )
User registry difference: Attempting to remove a user from a group who is not amember of the group is handled differently dependingon what user registry is being used. See Table 37 onpage 290 for details.
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 147
ivadmin_group_setdescription()
Changes the description for the specified group.
Syntaxunsigned longivadmin_group_setdescription(
ivadmin_context ctx,const char *groupid,const char *description,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
groupidGroup name.
descriptionNew description.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionChanges the description for the specified group.
Command line equivalent:pdadmin group modify group_name description description
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
148 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_objectspace_create()
Creates an Tivoli Access Manager protected object space.
Syntaxunsigned longivadmin_objectspace_create(
ivadmin_context ctx,const char *objspaceid,unsigned long type,const char *description,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
objspaceidThe name of the object space to create.
type The type of object space to create.
descriptionA description for the object space.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionCreates an Tivoli Access Manager protected object space.
You must specify as the input parameter type, the object space type for each newobject space. The object space type is used by the Tivoli Access Manager WebPortal Manager to display an appropriate icon with the object.
Note: The root of the new protected object space automatically has theispolicyattachable attribute set to true. For more information, see“ivadmin_protobj_setpolicyattachable()” on page 207.
The supported object types are in Table 31.
Table 31. Supported object types
Variable Name Value Description
IVADMIN_PROTOBJ_TYPE_UNKNOWN 0 Unknown
IVADMIN_PROTOBJ_TYPE_DOMAIN 1 Secure domain
IVADMIN_PROTOBJ_TYPE_FILE 2 File
IVADMIN_PROTOBJ_TYPE_PROGRAM 3 Executable program
IVADMIN_PROTOBJ_TYPE_DIR 4 Directory
IVADMIN_PROTOBJ_TYPE_JNCT 5 Junction
IVADMIN_PROTOBJ_TYPE_WEBSEAL_SVR 6 WebSEAL server
Chapter 10. Administration C API reference 149
Table 31. Supported object types (continued)
Variable Name Value Description
IVADMIN_PROTOBJ_TYPE_NETSEAL_SVR 7 Unused
IVADMIN_PROTOBJ_TYPE_EXTERN_AUTH_SVR 8 Unused
IVADMIN_PROTOBJ_TYPE_HTTP_SVR 9 Unused
IVADMIN_PROTOBJ_TYPE_NON_EXIST_OBJ 10 Nonexistent object
IVADMIN_PROTOBJ_TYPE_CONTAINER 11 Container object
IVADMIN_PROTOBJ_TYPE_LEAF 12 Leaf object
IVADMIN_PROTOBJ_TYPE_PORT 13 Port
IVADMIN_PROTOBJ_TYPE_APP_CONTAINER 14 Application containerobject
IVADMIN_PROTOBJ_TYPE_APP_LEAF 15 Application leaf object
IVADMIN_PROTOBJ_TYPE_MGMT_OBJ 16 Management object
IVADMIN_PROTOBJ_TYPE_NETSEAL_NET 17 Unused
Command line equivalent:pdadmin objectspace create objectspace_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
150 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_objectspace_delete()
Deletes the specified Tivoli Access Manager protected object space.
Syntaxunsigned longivadmin_objectspace_delete(
ivadmin_context ctx,const char *objspaceid,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
objspaceidThe name of the object space to delete.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionDeletes the specified Tivoli Access Manager protected object space.
Command line equivalent:pdadmin objectspace delete objectspace_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 151
ivadmin_objectspace_list()
Lists all the Tivoli Access Manager protected object spaces.
Syntaxunsigned longivadmin_objectspace_list(
ivadmin_context ctx,unsigned long *count,char ***objspace_list,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
Output
count The number of object space names returned. Zero is returned if an erroroccurs.
objspace_listAn array of pointers to the names of the object spaces returned. You mustfree the character data referenced by each pointer, as well as the array ofpointers when they are no longer needed.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionLists all the Tivoli Access Manager protected object spaces.
Command line equivalent:pdadmin objectspace list
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
152 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_pop_attach()
Attaches a protected object policy (POP) to the specified protected object.
Syntaxunsigned longivadmin_pop_attach(
ivadmin_context ctx,char *popid,char *objid,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
popid The name of the protected object policy to attach.
objid The name of the protected object.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionAttaches a protected object policy to the specified protected object. Be sure that theprotected object exists in the protect object space before attempting to attach a POP.
Command line equivalent:pdadmin attach object_name pop_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 153
ivadmin_pop_attrdelkey()
Deletes the specified extended attribute from the specified protected object policy(POP).
Syntaxunsigned longivadmin_pop_attrdelkey(
ivadmin_context ctx,char *popid,char *attr_key,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
popid The name of the protected object policy.
attr_keyThe extended attribute to delete.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionDeletes the specified extended attribute from the specified protected object policy.
Command line equivalent:pdadmin pop modify pop_name delete attribute attribute_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
154 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_pop_attrdelval()
Deletes the specified value from the specified extended attribute key in thespecified protected object policy (POP).
Syntaxunsigned longivadmin_pop_attrdelval(
ivadmin_context ctx,char *popid,char *attr_key,char *attr_value,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
popid The name of the protected object policy.
attr_keyThe extended attribute containing the value that is to be deleted.
attr_valueThe value to delete from the extended attribute.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionDeletes the specified value from the specified extended attribute key in thespecified protected object policy.
Command line equivalent:pdadmin pop modify pop_name delete attribute attribute_name attribute_value
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 155
ivadmin_pop_attrget()
Gets the values for the specified extended attribute from the specified protectedobject policy.
Syntaxunsigned longivadmin_pop_attrget(
ivadmin_pop pop,char *attr_key,unsigned long *count,char ***attr_value
);
ParametersInput
pop The protected object policy to be accessed.
attr_keyThe extended attribute to get.
Output
count The number of values returned. Zero is returned if an error occurs.
attr_valueAn array of pointers to the extended attribute values returned. You mustfree the character data referenced by each pointer, as well as the array ofpointers when they are no longer needed.
DescriptionGets the values for the specified extended attribute from the specified protectedobject policy. The value returned is in the same format as when it was createdusing the ivadmin_pop_attrput() function. If an error occurs, NULL is returned.
Command line equivalent:pdadmin pop show pop_name attribute
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
156 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_pop_attrlist()
Lists the extended attributes associated with the specified protected object policy.
Syntaxunsigned longivadmin_pop_attrlist(
ivadmin_pop pop,unsigned long *count,char ***attr_list
);
ParametersInput
pop The protected object policy.
Output
count The number of extended attributes returned. Zero is returned if an erroroccurs.
attr_listAn array of pointers to the extended attributes returned. You must free thecharacter data referenced by each pointer, as well as the array of pointerswhen they are no longer needed.
DescriptionLists the extended attributes associated with the specified protected object policy. Ifan error occurs, NULL is returned.
Command line equivalent:pdadmin pop list pop_name attribute
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 157
ivadmin_pop_attrput()
Sets the value for the specified extended attribute in the specified protected objectpolicy.
Syntaxunsigned longivadmin_pop_attrput(
ivadmin_context ctx,char *popid,char *attr_key,char *attr_value,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
popid The name of the protected object policy.
attr_keyThe extended attribute for which a value must be set.
attr_valueThe value to set.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the value for the specified extended attribute in the specified protected objectpolicy.
Command line equivalent:pdadmin modify pop_name set attribute attribute_name attribute_value
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
158 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_pop_create()
Creates a protected object policy object.
Syntaxunsigned longivadmin_pop_create(
ivadmin_context ctx,const char *popid,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
popid The name of the protected object policy to create.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionCreates a protected object policy object with the default values seen in Table 32.
Table 32. Protected object policy default values
Attribute Name Default Value
Description none
Warning mode no
Audit level none
Quality of protection none
Time of day access sun, mon, tue, wed, thu, fri,sat:anytime:local
IP endpoint authentication method policy 0
Any other cetwork 0
For more information about creating POPs, see the section about creating anddeleting protected object policies in the IBM Tivoli Access Manager BaseAdministrator’s Guide.
Command line equivalent:pdadmin pop create pop_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 159
ivadmin_pop_delete()
Deletes the specified protected object policy.
Syntaxunsigned longivadmin_pop_delete(
ivadmin_context ctx,const char *popid,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
popid The name of the protected object policy to delete.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionDeletes the specified protected object policy.
Command line equivalent:pdadmin pop delete pop_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
160 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_pop_detach()
Detaches a protected object policy (POP) from the specified protected object.
Syntaxunsigned longivadmin_pop_detach(
ivadmin_context ctx,char *objid,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
objid The protected object to detach from.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionDetaches a protected object policy from the specified protected object.
Command line equivalent:pdadmin pop detach pop_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 161
ivadmin_pop_find()
Finds and lists all protected objects that have the specified protected object policyattached.
Syntaxunsigned longivadmin_pop_find(
ivadmin_context ctx,char *popid,unsigned long *count,char ***obj_list,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
popid The name of the protected object policy to find.
Output
count The number of protected objects returned. Zero is returned if an erroroccurs.
obj_list An array of pointers to the protected objects returned. You must free thecharacter data referenced by each pointer, as well as the array of pointerswhen they are no longer needed.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionFinds and lists all protected objects that have the specified protected object policyattached.
Command line equivalent:pdadmin pop find pop_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
162 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_pop_get()
Gets the specified protected object policy object.
Syntaxunsigned longivadmin_pop_get(
ivadmin_context ctx,char *popid,ivadmin_pop *pop,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
popid The name of the protected object policy to get.
Output
pop The protected object policy that is returned.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets the specified protected object policy object. Call this function to get an objectof type ivadmin_pop.
You must free the ivadmin_pop object when it is no longer needed.
Command line equivalent:pdadmin pop show pop_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 163
ivadmin_pop_getanyothernw()
Gets the anyothernw, or any other network, setting for the IP authentication levelfrom the specified protected object policy.
Syntaxunsigned longivadmin_pop_getanyothernw(
ivadmin_pop popunsigned long *level,);
ParametersInput
pop The name of the protected object policy.
level Returns the authentication level associated with anyothernw.
DescriptionReturns the anyothernw, or any other network, setting for the authentication levelfrom the specified protected object policy (POP).
Command line equivalent:pdadmin pop show pop_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
164 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_pop_getauditlevel()
Gets the audit level for the specified protected object policy.
Syntaxunsigned longivadmin_pop_getauditlevel(
ivadmin_pop pop);
ParametersInput
pop The protected object policy.
DescriptionGets the audit level for the specified protected object policy.
Command line equivalent:pdadmin show pop_name
The audit level is part of the information returned by the pdadmin command.
Return ValuesAudit level is specified as an unsigned long. The following audit levels aredefined:#define IVADMIN_AUDIT_NONE (0)#define IVADMIN_AUDIT_PERMIT (1)#define IVADMIN_AUDIT_DENY (2)#define IVADMIN_AUDIT_ERROR (4)#define IVADMIN_AUDIT_ADMIN (8)#define IVADMIN_AUDIT_ALL (15)
Descriptions for the audit levels can be found in Table 33.
Table 33. Descriptions of audit levels
Audit Value Description
none Auditing is disabled.
permit Audit all requests on a protected object that result insuccessful access.
deny Audit all requests on a protected object that result in denialof access.
error Audit all internally generated error messages when access tothe protected object is denied.
admin Not implemented.
all Audit success, error, and failure for all events.
Chapter 10. Administration C API reference 165
ivadmin_pop_getdescription()
Gets the description of the specified protected object policy.
Syntaxconst char*ivadmin_pop_getdescription(
ivadmin_pop pop);
ParametersInput
pop The protected object policy.
DescriptionGets the description of the specified protected object policy. You must callivadmin_pop_get() to obtain an ivadmin_pop object before calling this function.
Do not free this description. This data is maintained in the ivadmin_pop structure.
Command line equivalent:pdadmin show pop_name
The description is part of the information returned by the pdadmin command.
Return ValuesGets the description of the specified protected object policy. There is no limit to thelength of the description.
166 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_pop_getid()
Gets the name of the specified protected object policy.
Syntaxconst char*ivadmin_pop_getid(
ivadmin_pop pop);
ParametersInput
pop The protected object policy.
DescriptionGets the name of the specified protected object policy. You must callivadmin_pop_get() to obtain an ivadmin_pop object before calling this function.
Do not free this name. This data is maintained in the ivadmin_pop structure.
Command line equivalent:pdadmin show pop_name
The name is part of the information returned by the pdadmin command.
Return ValuesGets the name of the specified protected object policy. There is no limit to thename of the policy.
Chapter 10. Administration C API reference 167
ivadmin_pop_getipauth()
Gets the IP endpoint authentication setting in the specified protected object policy.
Syntaxunsigned longivadmin_pop_getipauth(
ivadmin_pop pop,unsigned long *count,unsigned long **network,unsigned long **netmask,unsigned long **authMethod,);
ParametersInput
pop The protected object policy.
Output
count The number of settings retrieved.
networkThe array of network addresses.
netmaskThe array of netmasks.
authMethodThe array of authentication levels associated with the network.
DescriptionGets the IP endpoint authentication settings in the specified protected object policy.You must call ivadmin_pop_get() to obtain an ivadmin_pop object before callingthis function.
Command line equivalent:pdadmin pop show pop_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
168 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_pop_getqop()
Gets the quality of protection level for the specified protected object policy.
Syntaxconst char*ivadmin_pop_getqop(
ivadmin_pop pop);
ParametersInput
pop The protected object policy.
DescriptionGets the quality of protection level for the specified protected object policy.
Do not free this string. This data is maintained in the ivadmin_pop structure.
Command line equivalent:pdadmin show pop_name
The quality of protection level is part of the information returned by the pdadmincommand.
Return ValuesGets the quality of protection level for the specified protected object policy.
The following levels are defined:v nonev integrityv privacy
Chapter 10. Administration C API reference 169
ivadmin_pop_gettod()
Gets the time of day range for the specified protected object policy.
Syntaxunsigned longivadmin_pop_gettod(
ivadmin_pop pop,unsigned long *days,unsigned long *start,unsigned long *end,unsigned long *reference
);
ParametersInput
pop The protected object policy.
Output
days A bitmap of the days.
start The minutes for the start of the range.
end The minutes for the end of the range.
referenceThe time reference; either Universal Time Coordinated (UTC) or local.
DescriptionGets the time of day range for the specified protected object policy.
Command line equivalent:pdadmin show pop_name
The time of day range is part of the information returned by the pdadmincommand.
The following values are defined for time of day settings:#define IVADMIN_TIME_LOCAL (0)#define IVADMIN_TIME_UTC (1)#define IVADMIN_TOD_ANY (0)#define IVADMIN_TOD_SUN (1)#define IVADMIN_TOD_MON (2)#define IVADMIN_TOD_TUE (4)#define IVADMIN_TOD_WED (8)#define IVADMIN_TOD_THU (16)#define IVADMIN_TOD_FRI (32)#define IVADMIN_TOD_SAT (64)#define IVADMIN_TOD_ALL (127)#define IVADMIN_TOD_WEEKDAY (62)#define IVADMIN_TOD_WEEKEND (65)#define IVADMIN_TOD_MINUTES (60)#define IVADMIN_TOD_OCLOCK (3600)
Return ValuesReturns the following Boolean values:
170 IBM Tivoli Access Manager: Administration C API Developer’s Reference
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 171
ivadmin_pop_getwarnmode()
Gets the warning mode value from the specified protected object policy.
Syntaxunsigned longivadmin_pop_getwarnmode(
ivadmin_pop pop);
ParametersInput
pop The protected object policy.
DescriptionGets the warning mode value from the specified protected object policy.
Command line equivalent:pdadmin show pop_name
The warning mode value is part of the information returned by the pdadmincommand.
Return ValuesReturns the warning mode set for this protected object policy.
172 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_pop_list()
Lists all protected object policy objects.
Syntaxunsigned longivadmin_pop_list(
ivadmin_context ctx,unsigned long *count,char ***poplist,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
Output
count The number of protected object policies returned. Zero is returned if anerror occurs.
poplist An array of pointers to the protected object policies returned. You mustfree the character data referenced by each pointer, as well as the array ofpointers when they are no longer needed.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionLists all protected object policy objects.
Command line equivalent:pdadmin pop list
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 173
ivadmin_pop_removeipauth()
Removes the IP endpoint authentication settings from the specified protected objectpolicy.
Syntaxunsigned longivadmin_pop_removeipauth(
ivadmin_context ctx,char *popid,char *network,char *netmask,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
popid The name of the protected object policy.
networkThe network address to delete.
netmaskThe netmask address.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionRemoves the IP endpoint authentication settings from the specified protected objectpolicy.
Command line equivalent:pdadmin pop modify pop_name set ipauth remove network netmask
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
174 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_pop_setanyothernw()
Sets the anyothernw, or any other network, setting for the IP authentication levelfrom the specified protected object policy.
Syntaxunsigned longivadmin_pop_setanyothernw(
ivadmin_context ctx,char *popid,unsigned long level,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
popid The name of the protected object policy.
level The authentication level to associate with anyothernw.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the anyothernw, or any other network, setting for the authentication levelfrom the specified protected object policy (POP). If controlling access by IP addressis not important, use the anyothernw setting to set the authentication level for allIP addresses and IP address ranges not listed explicitly in the POP.
Command line equivalent:pdadmin pop modify pop_name set ipauth anyothernw authentication_level
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 175
ivadmin_pop_setanyothernw_forbidden()
Sets the anyothernw, or any other network, access setting to forbidden for thespecified protected object policy.
Syntaxunsigned longivadmin_pop_setanyothernw_forbidden(
ivadmin_context ctx,char *popid,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
popid The name of the protected object policy.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the anyothernw, or any other network, access setting to forbidden for thespecified protected object policy.
Command line equivalent:pdadmin pop modify pop_name set ipauth anyothernw forbidden
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
176 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_pop_setauditlevel()
Sets the audit level for the specified protected object policy.
Syntaxunsigned longivadmin_pop_setauditlevel(
ivadmin_context ctx,char *popid,unsigned long audit_level,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
popid The name of the protected object policy.
audit_levelThe new audit level for the protected object policy.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the Audit Level for the specified protected object policy.
Command line equivalent:pdadmin pop modify pop_name set audit-level [all | none | audit_level_list]
Audit level is specified as an unsigned long. The following audit levels aredefined:#define IVADMIN_AUDIT_NONE (0)#define IVADMIN_AUDIT_PERMIT (1)#define IVADMIN_AUDIT_DENY (2)#define IVADMIN_AUDIT_ERROR (4)#define IVADMIN_AUDIT_ADMIN (8)#define IVADMIN_AUDIT_ALL (15)
Table 33 on page 165lists audit levels and their descriptions.
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 177
ivadmin_pop_setdescription()
Sets the description of the specified protected object policy.
Syntaxunsigned longivadmin_pop_setdescription(
ivadmin_context ctx,char *popid,char *desc,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
popid The name of the protected object policy.
desc The new description for the protected object policy.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the description of the specified protected object policy.
Command line equivalent:pdadmin pop modify pop_name set description description
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
178 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_pop_setipauth()
Sets the IP endpoint authentication setting in the specified protected object policy.
Syntaxunsigned longivadmin_pop_setipauth(
ivadmin_context ctx,char *popid,unsigned long network,unsigned long netmask,unsigned long authMethod,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
popid The name of the protected object policy.
networkThe network address.
netmaskThe netmask address.
authMethodThe authentication level to associate with the network.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the IP endpoint authentication settings in the specified protected object policy.
Command line equivalent:pdadmin pop modify pop_name set ipauth add network netmask \authentication_level
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 179
ivadmin_pop_setipauth_forbidden()
Sets the IP endpoint authentication setting to forbidden in the specified protectedobject policy.
Syntaxunsigned longivadmin_pop_setipauth_forbidden(
ivadmin_context ctx,char *popid,unsigned long network,unsigned long netmask,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
popid The name of the protected object policy.
networkThe network address.
netmaskThe netmask address.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the ipauth setting for the authentication level to forbidden in the specifiedprotected object policy.
Command line equivalent:pdadmin pop modify pop_name set ipauth add network netmask forbidden
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
180 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_pop_setqop()
Sets the quality of protection level for the specified protected object policy.
Syntaxunsigned longivadmin_pop_setqop(
ivadmin_context ctx,char *popid,char *qop_level,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
popid Name of the protected object policy
qop_levelThe new quality of protection level to set. The following string values aresupported:v nonev integrityv privacy
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the quality of protection level for the specified protected object policy. Thefollowing string values are supported:v nonev integrityv privacy
Command line equivalent:pdadmin pop modify pop_name set qop [none|integrity|privacy]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 181
ivadmin_pop_settod()
Sets the time of day range for the specified protected object policy.
Syntaxunsigned longivadmin_pop_settod(
ivadmin_context ctx,char *popid,unsigned long days,unsigned long start,unsigned long end,unsigned long reference,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
popid The name of the protected object policy.
days A bitmap of the days.
start The minutes for the start of the range.
end The minutes for the end of the range.
referenceThe time zone: Universal Time Coordinated (UTC) or local.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the time of day range for the specified protected object policy.
Command line equivalent:pdadmin pop modify pop_name set tod-access time_of_day_string
The following values are defined for time of day settings:#define IVADMIN_TIME_LOCAL (0)#define IVADMIN_TIME_UTC (1)#define IVADMIN_TOD_ANY (0)#define IVADMIN_TOD_SUN (1)#define IVADMIN_TOD_MON (2)#define IVADMIN_TOD_TUE (4)#define IVADMIN_TOD_WED (8)#define IVADMIN_TOD_THU (16)#define IVADMIN_TOD_FRI (32)#define IVADMIN_TOD_SAT (64)#define IVADMIN_TOD_ALL (127)#define IVADMIN_TOD_WEEKDAY (62)#define IVADMIN_TOD_WEEKEND (65)#define IVADMIN_TOD_MINUTES (60)#define IVADMIN_TOD_OCLOCK (3600)
182 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 183
ivadmin_pop_setwarnmode()
Sets the warning mode for the specified protected object policy.
Syntaxunsigned longivadmin_pop_setwarnmode(
ivadmin_context ctx,char *popid,unsigned long warn_mode,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
popid The name of the protected object policy.
warn_modeThe new value of the warning mode. The following values are supported:IVADMIN_TRUE (1) or IVADMIN_FALSE (0).
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the warning mode for the specified protected object policy.
Command line equivalent:pdadmin pop modify pop_name set warning [on | off].
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
184 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_protobj_attachacl()
Attaches the specified access control list (ACL) to the specified protected object.
Syntaxunsigned longivadmin_protobj_attachacl(
ivadmin_context ctx,const char *objid,const char *aclid,ivadmin_response *rsp);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
objid The name of the protected object.
aclid The name of the access control list.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionAttaches the specified access control list to the specified protected object. If thespecified protected object already has an ACL attached, this function replaces thatACL with the new one. Understand Tivoli Access Manager ACLs before using thisfunction. For more information about ACLs, see the chapter about using accesscontrol policies in the IBM Tivoli Access Manager Base Administrator’s Guide.
Command line equivalent:pdadmin acl attach object_name ACL_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 185
ivadmin_protobj_attrdelkey()
Deletes the specified extended attribute (name and value) from the specifiedprotected object.
Syntaxunsigned longivadmin_protobj_attrdelkey(
ivadmin_context ctx,const char *objid,const char *attr_name,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
objid The name of the protected object.
attr_nameThe name of the extended attribute to delete.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionDeletes the specified extended attribute (name and value) from the specifiedprotected object.
Command line equivalent:pdadmin object modify object_name delete attribute_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
186 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_protobj_attrdelval()
Deletes the specified value from the specified extended attribute key in thespecified protected object.
Syntaxunsigned longivadmin_protobj_attrdelval(
ivadmin_context ctx,char *popid,char *attr_key,char *attr_value,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
popid The name of the protected object.
attr_keyThe name of the extended attribute.
attr_valueThe name of the value to delete from the specified extended attribute.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionDeletes the specified value from the specified extended attribute key in thespecified protected object.
Command line equivalent:pdadmin object modify object_name delete attribute_name attribute_value
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 187
ivadmin_protobj_attrget()
Returns the value associated with the specified extended attribute for the specifiedprotected object.
Syntaxunsigned longivadmin_protobj_attrget(
ivadmin_protobj protobj,const char *attr_key,unsigned long *count,char ***attr_value
);
ParametersInput
protobj Tivoli Access Manager protected object structure.
attr_keyThe extended attribute to access.
count The number of values returned. Zero is returned if an error occurs.
attr_valueAn array of pointers to the extended attribute values returned. You mustfree the character data referenced by each pointer, as well as the array ofpointers when they are no longer needed.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionReturns the value associated with the specified extended attribute for the specifiedprotected object.
Command line equivalent:pdadmin object show object_name attribute attribute_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
188 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_protobj_attrlist()
Lists all the extended attributes associated with the specified protected object.
Syntaxunsigned longivadmin_protobj_attrlist(
ivadmin_protobj protobj,unsigned long *count,char ***attrs_list
);
ParametersInput
protobj Tivoli Access Manager protected object structure.
Output
count The number of extended attributes returned. Zero is returned if an erroroccurs.
attrs_listAn array of pointers to the extended attributes returned. You must free thecharacter data referenced by each pointer, as well as the array of pointerswhen they are no longer needed.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionLists all the extended attributes associated with the specified protected object.
Command line equivalent:pdadmin object list object_name attribute
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 189
ivadmin_protobj_attrput()
Creates an extended attribute, with the specified name and value, and adds it tothe specified protected object.
Syntaxunsigned longivadmin_protobj_attrput(
ivadmin_context ctx,const char *objid,const char *attr_name,const char *attr_value,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
objid The name of the protected object.
attr_nameThe name of the extended attribute.
attr_valueThe value for the extended attribute.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionCreates an extended attribute, with the specified name and value, and adds it tothe specified protected object.
Command line equivalent:pdadmin object modify object_name set attribute attribute_name attribute_value
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
190 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_protobj_create()
Creates an Tivoli Access Manager protected object.
Syntaxunsigned longivadmin_protobj_create(
ivadmin_context ctx,const char *objid,unsigned long type,const char *description,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
objid The name of the protected object to create. The name can be of any lengthand contain any character. Forward slash (/) characters are interpreted aspart of the object hierarchy, which allows ACLs to be attached at thevarious points indicated by the forward slash character.
type The type of protected object to create.
descriptionThe description of the protected object.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionYou must specify, as a parameter to ivadmin_protobj_create(), an object space typefor each new object space. The object space type is used by the Tivoli AccessManager Web Portal Manager to display an appropriate icon with the object.
Table 31 on page 149 lists the supported object types.
Command line equivalent:pdadmin object create object_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 191
ivadmin_protobj_delete()
Deletes the specified Tivoli Access Manager protected object.
Syntaxunsigned longivadmin_protobj_delete(
ivadmin_context ctx,const char *objid,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
objid The name of the protected object to delete.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionDeletes the specified Tivoli Access Manager protected object.
Command line equivalent:pdadmin object delete object_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
192 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_protobj_detachacl()
Detaches the access control list (ACL) from the specified protected object.
Syntaxunsigned longivadmin_protobj_detachacl(
ivadmin_context ctx,const char *objid,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
objid The name of the protected object.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionDetaches the access control list from the specified protected object. Because onlyone access control list at a time can be attached to an object, the currently attachedaccess control list is detached. Understand Tivoli Access Manager ACLs beforeusing this function. For more information about ACLs, see the chapter about usingaccess control policies in the IBM Tivoli Access Manager Base Administrator’s Guide.
Command line equivalent:pdadmin acl detach object_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 193
ivadmin_protobj_get2()Returns the specified protected object.
Syntaxunsigned longivadmin_protobj_get2(
ivadmin_context ctx,const char *objid,azn_attrlist_h_t *indata,ivadmin_protobj *obj,azn_attrlist_h_t *outdata,unsigned long *resultcount,char ***results,ivadmin_response *rsp
);
ParametersInput
ctx Specifies the context to use when communicating with the Tivoli AccessManager policy server.
objid Specifies the parent object name.
indata Specifies pass-through data that allows additional information to becommunicated to the server. If a NULL is specified, it is ignored. Fornon-null inputs, a valid address for an azn_attrlist_h_t structure isexpected. It is also assumed that the caller created this azn_attrlist_h_tstructure using the azn_attrlist_create () function. When this data is nolonger required, free the associated memory using the azn_attrlist_delete()function.
Output
obj Specifies the returned object.
outdataSpecifies pass-through data that allows the server to communicateadditional information to the caller. When the data is no longer required,free the associated memory using azn_attrlist_delete().
resultcountThe number of result strings returned. Zero is returned if an error occurs.
results An array of pointers to the result strings returned. The result strings arethe message strings returned by the task. These are typically output to acommand line interface (CLI) or log output and contain information aboutthe success or failure of the task. You must free the character datareferenced by each pointer, as well as the array of pointers when they areno longer needed.
rsp Specifies the response object. Indicates the success or failure of thefunction. Contains error information. Free this object when it is no longerneeded.
DescriptionCommand line equivalent:pdadmin object show object_name
194 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 195
ivadmin_protobj_getacl()
Returns the access control list (ACL) that is attached to the specified protectedobject.
Syntaxivadmin_aclivadmin_protobj_getacl(
ivadmin_protobj protobj);
ParametersInput
protobj Pointer to protected object structure.
DescriptionReturns the access control list that is attached to the specified protected object.
Free this structure when it is no longer needed.
Command line equivalent:pdadmin object show object_name
The ACL is part of the information returned by this pdadmin object showcommand.
Return ValuesReturns the access control list that is attached to the specified protected object.
196 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_protobj_getdesc()
Gets the description of the specified protected object.
Syntaxconst char *ivadmin_protobj_getdesc(
ivadmin_protobj protobj);
ParametersInput
protobj The protected object structure.
DescriptionGets the description of the specified protected object. You must callivadmin_protobj_get2() before calling this function.
Do not free this string. This data is maintained in the protected object structureivadmin_protobj.
Command line equivalent:pdadmin object show object_name
The description is part of the information returned by this pdadmin command.
Return ValuesGets the description of the specified protected object. There is no limit to the lengthof the description.
Chapter 10. Administration C API reference 197
ivadmin_protobj_getid()
Gets the name of the specified protected object.
Syntaxconst char *ivadmin_protobj_getid(
ivadmin_protobj protobj);
ParametersInput
protobj Pointer to the protected object structure.
DescriptionGets the name of the specified protected object. You must callivadmin_protobj_get2() before calling this function.
Do not free this string. This data is maintained in the protected object structureivadmin_protobj.
Command line equivalent:pdadmin object show object_name
The protected object name is part of the information returned by this pdadmincommand.
Return ValuesGets the name of the specified protected object. There is no limit to the length ofthe name.
198 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_protobj_getpolicyattachable()
Gets the isPolicyAttachable attribute of the specified protected object.
Syntaxunsigned longivadmin_protobj_getpolicyattachable(
ivadmin_protobj protobj);
ParametersInput
protobj The protected object structure.
DescriptionGets the isPolicyAttachable attribute of the specified protected object. TheisPolicyAttachable attribute of a protected object indicates whether a protectedobject policy (POP) can be attached to that protected object. The default value ofthis attribute is yes.
Command line equivalent:pdadmin object show object_name
The protected object isPolicyAttachable attribute is part of the informationreturned by this pdadmin command.
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. Indicates that isPolicyAttachable is true.
IVADMIN_FALSEDefined as 0. Indicates that isPolicyAttachable is false.
Chapter 10. Administration C API reference 199
ivadmin_protobj_getpop()
Returns the protected object policy for the specified protected object.
Syntaxivadmin_popivadmin_protobj_getpop(
ivadmin_protobj protobj);
ParametersInput
protobj The protected object structure.
DescriptionReturns the protected object policy for the specified protected object.
Free this structure when it is no longer needed.
Return ValuesReturns the protected object policy for the specified protected object.
200 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_protobj_gettype()
Returns the type of the specified protected object.
Syntaxunsigned longivadmin_protobj_gettype(
ivadmin_protobj protobj);
ParametersInput
protobjPointer to protected object structure.
DescriptionReturns the type of the specified protected object.
Command line equivalent:pdadmin object show object_name
The protected object type is part of the information returned by this pdadmincommand.
Return ValuesReturns the type of the specified protected object.
Table 31 on page 149 in the description of the ivadmin_objectspace_create()function enumerates the types, values, and their descriptions.
Chapter 10. Administration C API reference 201
ivadmin_protobj_list3()Returns the protected objects in the specified directory, not includingsubdirectories.
Syntaxunsigned longivadmin_protobj_list3(
ivadmin_context ctx,const char *objid,azn_attrlist_h_t *indata,unsigned long *objcount,char ***objs,azn_attrlist_h_t *outdata,unsigned long *resultcount,char ***results,ivadmin_response *rsp
);
ParametersInput
ctx Specifies the context to use when communicating with the Tivoli AccessManager policy server.
objid Specifies the parent object name.
indata Specifies pass-through data that allows additional information to becommunicated to the server. If a NULL is specified, it is ignored. Fornon-null inputs, a valid address for an azn_attrlist_h_t structure isexpected. It is also assumed that the caller created this azn_attrlist_h_tstructure using the azn_attrlist_create() function. When this data is nolonger required, free the associated memory using the azn_attrlist_delete()function.
Output
objcountThe number of object names returned. Zero is returned if an error occurs.
objs An array of pointers to the list of object names that exist directly below thespecified parent object. You must free the character data referenced by eachpointer, as well as the array of pointers when they are no longer needed.
outdataSpecifies pass-through data that allows the server to communicateadditional information to the caller. When the data is no longer required,free the associated memory using the azn_attrlist_delete() function.
resultcountThe number of result strings returned. Zero is returned if an error occurs.
results An array of pointers to the result strings returned. The result strings arethe message strings returned by the task. These are typically output on acommand line interface (CLI) or log output and contain information aboutthe success or failure of the task. You must free the character datareferenced by each pointer, as well as the array of pointers when they areno longer needed.
202 IBM Tivoli Access Manager: Administration C API Developer’s Reference
rsp Specifies the response object. Indicates the success or failure of thefunction. Contains error information. Free this object when it is no longerneeded.
DescriptionReturns the protected objects in the specified directory, not includingsubdirectories. If an error occurs, NULL is returned.
Command line equivalent:pdadmin object list object_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 203
ivadmin_protobj_listbyacl()
Returns a list of protected objects that have the specified access control listattached.
Syntaxunsigned longivadmin_protobj_listbyacl(
ivadmin_context ctx,const char *aclid,unsigned long *count,char ***objids,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
aclid The name of the access control list.
count The number of protected objects returned. Zero is returned if an erroroccurs.
objids An array of pointers to the protected objects returned. You must free thecharacter data referenced by each pointer, as well as the array of pointerswhen they are no longer needed.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionReturns a list of protected objects which have the specified access control listattached.
Command line equivalent:pdadmin acl find ACL_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
204 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_protobj_setdesc()
Sets the description field of the specified protected object.
Syntaxunsigned longivadmin_protobj_setdesc(
ivadmin_context ctx,const char *objid,const char *description,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
objid The name of the protected object for which a new description is to be set.
descriptionThe new description for the protected object.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
SyntaxSets the description field of the specified protected object.
Command line equivalent:pdadmin object modify object_name description new_description
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 205
ivadmin_protobj_setname()
Sets the name of the specified protected object.
Syntaxunsigned longivadmin_protobj_setname(
ivadmin_context ctx,const char *old_objid,const char *new_objid,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
old_objidThe old name of the protected object.
new_objidThe new name of the protected object.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the name of the specified protected object.
Command line equivalent:pdadmin object modify object_name name new_name \
conflict-resolution resolution-modifier
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
206 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_protobj_setpolicyattachable()
Sets the isPolicyAttachable attribute of the specified protected object.
Syntaxunsigned longivadmin_protobj_setpolicyattachable(
ivadmin_context ctx,const char *objid,unsigned long flag,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
objid The name of the protected object.
flag The flag containing the value of the isPolicyAttachable attribute. Thepossible values are IVADMIN_TRUE or 1 (yes) and IVADMIN_FALSE or 0(no).
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the isPolicyAttachable attribute of the specified protected object. TheisPolicyAttachable attribute of a protected object indicates whether a protectedobject policy (POP) can be attached to that protected object. The default value ofthis attribute is yes.
Command line equivalent:pdadmin object modify object_name isPolicyAttachable [yes | no]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 207
ivadmin_protobj_settype()
Sets the type field of the specified protected object.
Syntaxunsigned longivadmin_protobj_settype(
ivadmin_context ctx,const char *objid,unsigned long type,ivadmin_response *rsp
);
SyntaxInput
ctx Context to communicate with the Tivoli Access Manager policy server.
objid The name of the protected object.
type The new type for the object.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the type field of the specified protected object.
Command line equivalent:pdadmin object modify object_name type new_type
Table 31 on page 149 lists the supported object types.
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
208 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_response_getcode()
Returns the message code.
Syntaxunsigned longivadmin_response_getcode(
ivadmin_response rsp,unsigned long index
);
ParametersInput
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
index Zero-based index of the message code requested.
DescriptionReturns the error or warning code associated with the message.
Return ValuesReturns the error or warning code associated with the message.
Chapter 10. Administration C API reference 209
ivadmin_response_getcount()
Returns the number of messages in the response object.
Syntaxunsigned longivadmin_response_getcount(
ivadmin_response rsp);
ParametersInput
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionReturns the number of messages in the response object.
Return ValuesReturns the number of messages in the response object.
210 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_response_getmessage()
Returns the message text from the specified index location in the response object.
Syntaxconst char *ivadmin_response_getmessage(
ivadmin_response rsp,unsigned long index
);
ParametersInput
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
index Zero-based index of message text requested.
DescriptionReturns the message text from the specified index location in the response object.
Do not free this object. This is data maintained in the response structure.
Return ValuesReturns the message text from the specified index location in the response object.
Chapter 10. Administration C API reference 211
ivadmin_response_getmodifier()
Returns the message modifier from the specified index location in the responseobject.
Syntaxunsigned longivadmin_response_getmodifier(
ivadmin_response rsp,unsigned long index
);
ParametersInput
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
index Zero-based index of the message modifier requested.
DescriptionReturns the message modifier from the specified index location in the responseobject. The modifier can be either an error, a warning, or information. Thefollowing values are defined:#define IVADMIN_RESPONSE_INFO 0#define IVADMIN_RESPONSE_WARNING 1#define IVADMIN_RESPONSE_ERROR 2
Return ValuesReturns the message modifier from the specified index location in the responseobject.
212 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_response_getok()
Returns a Boolean indicator of the success of the operation.
Syntaxunsigned longivadmin_response_getok(
ivadmin_response rsp);
ParametersInput
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionReturns a Boolean indicator of the success of the operation.
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 213
ivadmin_server_gettasklist()Gets the list of tasks from the server.
Syntaxunsigned longivadmin_server_gettasklist(
ivadmin_context ctx,const char *server,azn_attrlist_h_t *indata,unsigned long *taskcount,char ***tasks,azn_attrlist_h_t *outdata,unsigned long *resultcount,char ***results,ivadmin_response *rsp
);
ParametersInput
ctx Specifies the context to use when communicating with the Tivoli AccessManager policy server.
server Specifies the name of the server to notify of a database update. Thisparameter is optional. If NULL is specified, all servers configured toreceive database update notifications are notified.
indata Specifies pass-through data that allows additional information to becommunicated to the server. If NULL is specified, it is ignored. Fornon-null inputs, a valid address for an azn_attrlist_h_t structure isexpected. It is also assumed that the caller created this azn_attrlist_h_tstructure using the azn_attrlist_create() function. When this data is nolonger required, free the associated memory using the azn_attrlist_delete()function.
Output
taskcountThe number of task strings returned. Zero is returned if an error occurs.
tasks An array of pointers to the list of tasks currently supported by this server.The task strings are typically in the supported command line interface(CLI) syntax.You must free the character data referenced by each pointer,as well as the array of pointers when they are no longer needed.
outdataSpecifies pass-through data that allows the server to communicateadditional information to the caller. When the data is no longer required,free the associated memory by using the azn_attrlist_delete() function.
resultcountThe number of result strings returned. Zero is returned if an error occurs.
results An array of pointers to the result strings returned. The result strings arethe message strings returned by the task. These are typically output on acommand line interface (CLI) or log output and contain information aboutthe success or failure of the task.You must free the character datareferenced by each pointer, as well as the array of pointers when they areno longer needed.
214 IBM Tivoli Access Manager: Administration C API Developer’s Reference
rsp Specifies the response object. Indicates the success or failure of thefunction. Contains error information. Free this object when it is no longerneeded.
DescriptionGets the list of tasks from the server. If no tasks are supported, or an error occurs,NULL is returned.
Command line equivalent:pdadmin server listtasks server_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 215
ivadmin_server_performtask()Sends a command to an authorization server.
Syntaxunsigned longivadmin_server_performtask(
ivadmin_context ctx,const char *server,const char *task,azn_attrlist_h_t *indata,azn_attrlist_h_t *outdata,unsigned long *resultcount,char ***results,ivadmin_response *rsp
);
ParametersInput
ctx Specifies the context to use when communicating with the Tivoli AccessManager policy server.
server Specifies the name of server to notify of database update. This parameter isoptional. If NULL is specified, all servers configured to receive databaseupdate notifications will be notified.
task Specifies the task to perform.
indata Specifies pass-through data that allows additional information to becommunicated to the server. If NULL is specified, it is ignored. Fornon-null inputs, a valid address for an azn_attrlist_h_t structure isexpected. It is also assumed that the caller created this azn_attrlist_h_tstructure using the azn_attrlist_create() function. When this data is nolonger required, free the associated memory by using theazn_attrlist_delete() function.
Output
outdataPass-through data that allows the server to communicate additionalinformation to the caller. When the data is no longer required, free theassociated memory by using the azn_attrlist_delete() function.
resultcountThe number of result strings returned. Zero is returned if an error occurs.
results An array of pointers to the result strings returned. The result strings arethe message strings returned by the task. These are typically output on acommand line interface (CLI) or log output and contain information aboutthe success or failure of the task.You must free the character datareferenced by each pointer, as well as the array of pointers when they areno longer needed.
rsp Specifies the response object. Indicates the success or failure of thefunction. Contains error information. Free this object when it is no longerneeded.
216 IBM Tivoli Access Manager: Administration C API Developer’s Reference
DescriptionSends a command to the authorization server.
Command line equivalent:pdadmin server task server_name task_to_perform
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 217
ivadmin_server_replicate()Notify authorization servers to receive database updates.
Syntaxunsigned longivadmin_server_replicate(
ivadmin_context ctx,const char *server,ivadmin_response *rsp
);
ParametersInput
ctx Specifies the context to use when communicating with the Tivoli AccessManager policy server.
server Specifies the name of the server to notify of a database update. Thisparameter is optional. If NULL is specified, all servers configured toreceive database update notifications are notified.
Output
rsp Specifies the response object. Indicates the success or failure of thefunction. Contains error information. Free this object when it is no longerneeded.
DescriptionNotify authorization servers to receive database updates. If a server name isspecified, but is not configured to receive database updates, an error message isdisplayed. If no server name is specified, the process of notifying all configuredservers is initiated, but error messages are not displayed for individual servers.The caller must have the authority to perform server administration tasks on thepolicy server. (The azn_operation_server_admin permission is required on thepolicy server object.)
Command line equivalent:pdadmin server replicate [server-name]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. If a server is specified, this indicates the successfulnotification and database replication by that server. If no server isspecified, this indicates that the policy server has begun to notify eachauthorization server. In this case, a return code of IVADMIN_TRUE is notan indication of successful notification or replication for any one of theservers.
IVADMIN_FALSEDefined as 0. If a server is specified, this indicates the a failure of thenotification and database replication by that server. If no server isspecified, this indicates that a failure has occurred in requesting that thepolicy server begin notifying each authorization server.
218 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_ssocred_create()
Creates a single signon credential.
Syntaxunsigned longivadmin_ssocred_create(
ivadmin_context ctx,const char *ssoid,unsigned long ssotype,const char *userid,const char *ssouserid,const char *ssopassword,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
ssoid Single signon resource name with which the single signon credential isassociated. This resource must already exist.
ssotype Single signon resource type. The following types are defined:v IVADMIN_SSOCRED_SSOWEBv IVADMIN_SSOCRED_SSOGROUP
userid User ID associated with the single signon credential.
ssouseridThe user name that this user uses to access the specified resource.
ssopasswordThe password that this user uses to access the specified resource.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionCreates a single signon credential.
Command line equivalent:pdadmin rsrccred create resource_name rsrcuser resource_userid rsrcpwd \resource_password rsrctype {web | group} user user_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 219
ivadmin_ssocred_delete()
Deletes a single signon credential.
Syntaxunsigned longivadmin_ssocred_delete(
ivadmin_context ctx,const char *ssoid,unsigned long ssotype,const char *userid,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
ssoid Single signon resource name with which the single signon credential isassociated.
ssotype Single signon resource type. The following types are defined:v IVADMIN_SSOCRED_SSOWEBv IVADMIN_SSOCRED_SSOGROUP
userid The user ID associated with the single signon credential.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionDeletes a single signon credential.
Command line equivalent:pdadmin rsrccred delete resource_name rsrctype {web | group} user user_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
220 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_ssocred_get()
Returns the specified single signon credential.
Syntaxunsigned longivadmin_ssocred_get(
ivadmin_context ctx,const char *ssoid,unsigned long ssotype,const char *userid,ivadmin_ssocred *ssocred,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
ssoid Single signon resource name with which the single signon credential isassociated.
ssotypeSingle signon resource type. The following types are defined:v IVADMIN_SSOCRED_SSOWEBv IVADMIN_SSOCRED_SSOGROUP
userid The user name associated with the single signon credential.
Output
ssocred Returned single signon credential. Free this credential when it is no longerneeded.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionReturns the specified single signon credential.
Specify the single signon credential type when using this function. The followingsingle signon credential types are defined:#define IVADMIN_SSOCRED_SSOWEB 0#define IVADMIN_SSOCRED_SSOGROUP 1
Command line equivalent:pdadmin rsrccred show resource_name rsrctype {web | group} user user_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 221
ivadmin_ssocred_getid()
Returns the name of the single signon resource associated with this credential.
Syntaxconst char *ivadmin_ssocred_getid(
ivadmin_ssocred ssocred);
ParametersInput
ssocred Pointer to the single signon credential.
DescriptionReturns the name of the single signon resource associated with this credential. Youmust call ivadmin_ssocred_get() to obtain an ivadmin_ssocred object beforecalling this function.
Do not free this string. This data is maintained in the single signon credentialstructure (ivadmin_ssocred).
Command line equivalent:pdadmin rsrccred show resource_name rsrctype {web | group} user user_name
The credential identifier is part of the information returned by the pdadmincommand.
Return ValuesReturns the name of the single signon resource associated with this credential.
User registry difference: The maxmum length of the name is dependent on theuser registry being used. See Appendix B, “User registrydifferences”, on page 289 to determine the maximumlength for your environment.
222 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_ssocred_getssopassword()
Returns the password associated with this single signon credential.
Syntaxconst char *ivadmin_ssocred_getssopassword(
ivadmin_ssocred ssocred);
ParametersInput
ssocred Pointer to the single signon credential.
DescriptionReturns the password associated with this single signon credential. You must callivadmin_ssocred_get() to obtain an ivadmin_ssocred object before calling thisfunction.
Do not free this string. This data is maintained in the single signon credentialstructure (ivadmin_ssocred).
Return ValuesReturns the password associated with this single signon credential. There is nolimit to the length of the password.
Chapter 10. Administration C API reference 223
ivadmin_ssocred_getssouser()
Returns the name of the user associated with the specified single signon credential.
Syntaxconst char *ivadmin_ssocred_getssouser(
ivadmin_ssocred ssocred);
ParametersInput
ssocred Pointer to the single signon credential.
DescriptionReturns the name of the user associated with the specified single signon credential.You must call ivadmin_ssocred_get() to obtain an ivadmin_ssocred object beforecalling this function.
Do not free this string. This data is maintained in the single signon credentialstructure (ivadmin_ssocred).
Return ValuesReturns the name of the user associated with the specified single signon credential.
User registry difference: The maxmum length of the name is dependent on theuser registry being used. See Appendix B, “User registrydifferences”, on page 289 to determine the maximumlength for your environment.
224 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_ssocred_gettype()
Returns the type of the single signon resource associated with the specified singlesignon credential.
Syntaxunsigned longivadmin_ssocred_gettype(
ivadmin_ssocred ssocred);
ParametersInput
ssocred Pointer to the single signon credential.
DescriptionReturns the type of the single signon resource associated with the specified singlesignon credential.
Command line equivalent:pdadmin rsrccred show resource_name rsrctype {web | group} user user_name
The credential type is part of the information returned by the pdadmin command.
Return ValuesReturns the type of the single signon resource associated with the specified singlesignon credential. You must call ivadmin_ssocred_get () to obtain anivadmin_ssocred object before calling this function.
The defined types are:#define IVADMIN_SSOCRED_SSOWEB 0#define IVADMIN_SSOCRED_SSOGROUP 1
Do not free the resource credential type (integer) when it is no longer needed. Thisdata is maintained in the ivadmin_ssocred object.
Chapter 10. Administration C API reference 225
ivadmin_ssocred_getuser()
Returns the name of the user associated with this single signon credential.
Syntaxconst char *ivadmin_ssocred_getuser(
ivadmin_ssocred ssocred);
ParametersInput
ssocred Pointer to the single signon credential.
DescriptionReturns the name of the user associated with this single signon credential. Youmust call ivadmin_ssocred_get() to obtain an ivadmin_ssocred object beforecalling this function.
Do not free this string. This data is maintained in the single signon credentialstructure (ivadmin_ssocred).
Command line equivalent:pdadmin rsrccred show resource_name rsrctype {web | group} user user_name
The user name is part of the information returned by the pdadmin command.
Return ValuesReturns the name of the user associated with this single signon credential.
User registry difference: The maxmum length of the name is dependent on theuser registry being used. See Appendix B, “User registrydifferences”, on page 289 to determine the maximumlength for your environment.
226 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_ssocred_list()
Returns the list of single signon credentials for the specified user.
Syntaxunsigned longivadmin_ssocred_list(
ivadmin_context ctx,const char *userid,unsigned long *count,ivadmin_ssocred **ssocreds,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid The user ID of the user for whom the single signon credentials are to beretrieved.
Output
count Number of single signon credentials returned. Zero is returned if an erroroccurs.
ssocredsArray of pointers to single signon credentials. You must free the datareferenced by each pointer, as well as the array of pointers when they areno longer needed.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionReturns the list of single signon credentials for the specified user.
Command line equivalent:pdadmin rsrccred list user user_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 227
ivadmin_ssocred_set()
Creates or modifies a single signon credential.
Syntaxunsigned longivadmin_ssocred_set(
ivadmin_context ctx,const char *ssoid,unsigned long ssotype,const char *userid,const char *ssouserid,const char *ssopassword,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
ssoid Single signon resource name with which the single signon credential isassociated.
ssotypeSingle signon resource type. The following types are defined:v IVADMIN_SSOCRED_SSOWEBv IVADMIN_SSOCRED_SSOGROUP
userid User name associated with the single signon credential.
ssouseridThe user name that the user (as specified by the input parameter userid)uses to access the specified resource.
ssopasswordThe password that this user uses to access the specified resource.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionCreates or modifies a single signon credential.
Command line equivalent:pdadmin rsrccred modify resource_name rsrctype {web | group} set \[-rsrcuser resource_userid] [-rsrcpwd resource_password] user user_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
228 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_ssogroup_addres()
Adds a single signon resource to a single signon resource group.
Syntaxunsigned longivadmin_ssogroup_addres(
ivadmin_context ctx,const char *ssogroupid,const char *ssoid,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
ssogroupidSingle signon resource group name.
ssoid New member single signon resource name.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionAdds a single signon resource to a single signon resource group. Tivoli AccessManager does not support a resource group as a resource group member.
Command line equivalent:pdadmin rsrcgroup modify resource_group_name add rsrcname resource_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 229
ivadmin_ssogroup_create()
Creates a single signon group resource.
Syntaxunsigned longivadmin_ssogroup_create(
ivadmin_context ctx,const char *ssogroupid,const char *description,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
ssogroupidSingle signon group resource name.
descriptionDescription of the single signon group resource.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionCreates a single signon group resource.
Command line equivalent:pdadmin rsrcgroup create resource_group_name [-desc description]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
230 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_ssogroup_delete()
Deletes a single signon group resource.
Syntaxunsigned longivadmin_ssogroup_delete(
ivadmin_context ctx,const char *ssogroupid,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
ssogroupidSingle signon group resource name.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionDeletes a single signon group resource.
Command line equivalent:pdadmin rsrcgroup delete resource_group_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 231
ivadmin_ssogroup_get()
Returns the specified single signon group resource.
Syntaxunsigned longivadmin_ssogroup_get(
ivadmin_context ctx,const char *ssogroupid,ivadmin_ssogroup *ssogroup,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
ssogroupidSingle signon group resource name.
Output
ssogroupReturned single signon group resource. Free the memory containing thereturned single signon group resource when it is no longer needed
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionReturns the specified single signon group resource. The ivadmin_ssogroup objectcontains the resource group name, the resource group description, and a list of thenames of the resource group members. The resource group members are theindividual Web resources (servers).
Command line equivalent:pdadmin rsrcgroup show resource_group_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
232 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_ssogroup_getdescription()
Returns the description of the single signon group resource.
Syntaxconst char *ivadmin_ssogroup_getdescription(
ivadmin_ssogroup ssogroup);
ParametersInput
ssogroupPointer to the single signon group resource.
DescriptionReturns the description of the single signon group resource. You must callivadmin_ssogroup_get() to obtain an ivadmin_ssogroup object before calling thisfunction.
Do not free this string. This data is maintained in the single signon group resourcestructure.
Command line equivalent:pdadmin rsrcgroup show resource_group_name
The description is part of the information returned by the pdadmin command.
Return ValuesReturns the description of the single signon group resource. The maximum lengthof the description is 1024 characters.
Chapter 10. Administration C API reference 233
ivadmin_ssogroup_getid()
Returns the name of the single signon group resource.
Syntaxconst char *ivadmin_ssogroup_getid(
ivadmin_ssogroup ssogroup);
ParametersInput
ssogroupPointer to the single signon group resource.
DescriptionReturns the name of the single signon group resource. You must callivadmin_ssogroup_get() to obtain an ivadmin_ssogroup object before calling thisfunction.
Do not free this string. This data is maintained in the single signon group resourcestructure.
Command line equivalent:pdadmin rsrcgroup show resource_group_name
The name is part of the information returned by the pdadmin command.
Return ValuesReturns the name of the single signon group resource.
User registry difference: The maxmum length of the name is dependent on theuser registry being used. See Appendix B, “User registrydifferences”, on page 289 to determine the maximumlength for your environment.
234 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_ssogroup_getresources()
Returns a list of the member single signon resource names for the specified singlesignon group.
Syntaxunsigned longivadmin_ssogroup_getresources(
ivadmin_ssogroup ssogroup,unsigned long *count,char *** ssoids
);
ParametersInput
ssogroupPointer to the single signon group resource.
Output
count The number of single signon resource names returned. Zero is returned ifan error occurs.
ssoids An array of pointers to the single signon resource names returned. Youmust free the character data referenced by each pointer, as well as thearray of pointers when they are no longer needed.
DescriptionReturns a list of the member single signon resource names.
Command line equivalent:pdadmin rsrcgroup show resource_group_name
The resource name is part of the information returned by the pdadmin command.
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 235
ivadmin_ssogroup_list
Returns a list of all the single signon group resource names.
Syntaxunsigned longivadmin_ssogroup_list(
ivadmin_context ctx,unsigned long *count,char ***ssogroupids,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
Output
count The number of single signon group resource names returned. Zero isreturned if an error occurs.
ssogroupidsAn array of pointers to the single signon group resource names returned.You must free the character data referenced by each pointer, as well as thearray of pointers when they are no longer needed..
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionReturns a list of all of the single signon group resource names.
Command line equivalent:pdadmin rsrcgroup list
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
236 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_ssogroup_removeres()
Removes a single signon resource from the specified single signon resource group.
Syntaxunsigned longivadmin_ssogroup_removeres(
ivadmin_context ctx,const char *ssogroupid,const char *ssoid,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
ssogroupidsingle signon resource group name.
ssoid The member single signon resource name to remove.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionRemoves a single signon resource from the specified single signon resource group.
Command line equivalent:pdadmin rsrcgroup modify resource_group_name remove rsrcname resource_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 237
ivadmin_ssoweb_create()
Creates a single signon Web resource.
Syntaxunsigned longivadmin_ssoweb_create(
ivadmin_context ctx,const char *ssowebid,const char *description,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
ssowebidThe single signon Web resource name.
descriptionThe description of the single signon Web resource.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionCreates a single signon Web resource. The name of the Web server does not needto match the junction. You can use this function call before joining the Web serverto the Tivoli Access Manager WebSEAL server.
Command line equivalent:pdadmin rsrc create resource_name [-desc description]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
238 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_ssoweb_delete()
Deletes the specified single signon Web resource.
Syntaxunsigned longivadmin_ssoweb_delete(
ivadmin_context ctx,const char *ssowebid,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
ssowebidThe name of the single signon Web resource to delete.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionDeletes the specified single signon Web resource.
Command line equivalent:pdadmin rsrc delete resource_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 239
ivadmin_ssoweb_get()
Returns the specified single signon Web resource.
Syntaxunsigned longivadmin_ssoweb_get(
ivadmin_context ctx,const char *ssowebid,ivadmin_ssoweb *ssoweb,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
ssowebidThe name of the single signon Web resource to get.
Output
ssowebThe returned single signon Web resource. Free the memory for the singlesignon Web resource (ivadmin_ssoweb) when it is no longer needed.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionReturns the specified single signon Web resource.
Command line equivalent:pdadmin rsrc show resource_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
240 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_ssoweb_getdescription()
Returns the description of the specified single signon Web resource.
Syntaxconst char *ivadmin_ssoweb_getdescription(
ivadmin_ssoweb ssoweb);
ParametersInput
ssowebPointer to single signon Web resource.
DescriptionReturns the description of the specified single signon Web resource. You must callivadmin_ssoweb_get() to obtain an ivadmin_ssoweb object before calling thisfunction.
Do not free this string. This data is maintained in the single signon Web resourcestructure (ivadmin_ssoweb).
Command line equivalent:pdadmin rsrc show resource_name
The description is part of the information returned by the pdadmin command.
Return ValuesReturns the description of the specified single signon Web resource. The maximumlength of the description is 1024 characters.
Chapter 10. Administration C API reference 241
ivadmin_ssoweb_getid()
Returns the name (identifier) of the specified single signon Web resource.
Syntaxconst char *ivadmin_ssoweb_getid(
ivadmin_ssoweb ssoweb);
ParametersInput
ssowebPointer to single signon Web resource.
DescriptionReturns the name (identifier) of the specified single signon Web resource. You mustcall ivadmin_ssoweb_get() to obtain an ivadmin_ssoweb object before calling thisfunction.
Do not free this string. This data is maintained in the single signon Web resourcestructure (ivadmin_ssoweb).
Command line equivalent:pdadmin rsrc show resource_name
The name is part of the information returned by the pdadmin command.
Return ValuesReturns the name, or identifier, of the specified single signon Web resource.
User registry difference: The maxmum length of the name is dependent on theuser registry being used. See Appendix B, “User registrydifferences”, on page 289 to determine the maximumlength for your environment.
242 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_ssoweb_list()
Returns a list of all the single signon Web resource names.
Syntaxunsigned longivadmin_ssoweb_list(
ivadmin_context ctx,unsigned long *count,char ***ssowebids,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
Output
count The number of single signon Web resource names returned. Zero isreturned if an error occurs.
ssowebidsAn array of pointers to the single signon Web resource names returned.You must free the character data referenced by each pointer, as well as thearray of pointers when they are no longer needed.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionReturns a list of all the single signon Web resource names.
Command line equivalent:pdadmin rsrc list
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 243
ivadmin_user_create3()
Creates a user in the directory used by the Tivoli Access Manager policy serverand initially associates that user with one or more groups.
Syntaxunsigned longivadmin_user_create3(
ivadmin_context ctx,const char *userid,const char *dn,const char *cn,const char *sn,const char *pwd,unsigned long group_count,const char **groups,unsigned long ssouser,unsigned long nopwdpolicy,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid Tivoli Access Manager user name.
dn User registry distinguished name.
cn User registry attribute common name.
sn User registry attribute surname.
pwd User registry attribute password.
group_countThe number of groups to which the user initially belongs.
groups The initial user registry groups to which the user belongs. Specify NULL toindicate no initial group membership.
ssouser The user is capable of having single signon credentials.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
nopwdpolicyPassword policy is not enforced during creation. This has no effect onpassword policy enforcement after user creation.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionCreates a user in the user registry used by the Tivoli Access Manager policy server.Accounts are created invalid by default. Use ivadmin_user_setaccountvalid() toenable the account.
244 IBM Tivoli Access Manager: Administration C API Developer’s Reference
User registry difference: Leading and trailing blanks in a user name do not makethe name unique when using an LDAP or ActiveDirectory user registry. However, leading and trailingblanks do make the user name unique when using aDomino server as a user registry. To keep nameprocessing consistent regardless of what user registry isbeing used, do not define user names with leading ortrailing blanks.
Command line equivalents:pdadmin user create [-gsouser] [-no-password-policy] user_name dn cn sn \pwd group_name
pdadmin user create [-gsouser] [-no-password-policy] user_name dn cn sn \pwd ( group_name1 group_name2 ... group_nameN )
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 245
ivadmin_user_delete2()
Deletes the Tivoli Access Manager user and optionally deletes the user from theuser registry.
Syntaxunsigned longivadmin_user_delete2(
ivadmin_context ctxconst char *userid,unsigned long registryivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid Tivoli Access Manager user name.
registryDelete user from the user registry as well as from Tivoli Access Manager.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionDeletes Tivoli Access Manager information about the user from the user registry.The optional pdadmin parameter -registry causes the entire user object to bedeleted from the user registry.
Command line equivalent:pdadmin user delete [-registry] user_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
246 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_user_get()
Gets the user object for the specified user.
Syntaxunsigned longivadmin_user_get(
ivadmin_context ctx,const char *userid,ivadmin_ldapuser *user,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid Tivoli Access Manager user name.
Output
user Returned user. Free this memory when no longer needed.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets the user object for the specified user.
Free the memory used by the ivadmin_ldapuser object when it is no longerneeded.
Command line equivalent:pdadmin user show user_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 247
ivadmin_user_getaccexpdate()
Gets the account expiration date for the specified user.
Syntaxunsigned longivadmin_user_getaccexpdate(
ivadmin_context ctx,const char *userid,unsigned long *seconds,unsigned long *unlimited,unsigned long *unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
secondsReturned date and time of the expiration of the specified user account.This is the number of seconds since 00:00:00 Universal time,1 January 1970 (same as time_t).
unlimitedReturns the account-expiration-not-restricted indicator.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets the account expiration date for the specified user.
Command line equivalent:pdadmin policy get account-expiry-date [-user user_name]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
248 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_user_getaccountvalid()
Returns the account-valid indicator from the specified user object.
Syntaxunsigned longivadmin_user_getaccountvalid(
ivadmin_ldapuser user);
ParametersInput
user Pointer to the user structure.
DescriptionReturns the account valid indicator from the specified user object.
Command line equivalent:pdadmin user show user_name
The account-valid status is part of the information returned by the pdadmincommand.
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 249
ivadmin_user_getbydn()
Obtains an Tivoli Access Manager user object by using the user registrydistinguished name.
Syntaxunsigned longivadmin_user_getbydn(
ivadmin_context ctx,const char *dn,ivadmin_ldapuser *user,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
dn User registry distinguished name of the user.
Output
user Returned user. Free the memory for this object when it is no longerneeded.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionObtains an Tivoli Access Manager user object by using the user registrydistinguished name.
User registry difference: The maxmum length of the distinguished name isdependent on the user registry being used. SeeAppendix B, “User registry differences”, on page 289 todetermine the maximum length for your environment.
Command line equivalent:pdadmin user show-dn dn
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
250 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_user_getcn()
Returns the user registry common name attribute from the specified user object.
Syntaxconst char *ivadmin_user_getcn(
ivadmin_ldapuser user);
ParametersInput
user Pointer to the user structure.
DescriptionReturns the user registry common name attribute from the specified user object.
Do not free the character string that is returned. This data is maintained in theivadmin_ldapuser object.
Command line equivalent:pdadmin user show user_name
The user registry common name for the user is part of the information returned bythe pdadmin command.
Return ValuesReturns the user registry common name attribute from the specified user object.
User registry difference: The maxmum length of the common name is dependenton the user registry being used. See Appendix B, “Userregistry differences”, on page 289 to determine themaximum length for your environment.
Chapter 10. Administration C API reference 251
ivadmin_user_getdescription()
Returns the user description from the specified user object.
Syntaxconst char *ivadmin_user_getdescription(
ivadmin_ldapuser user);
ParametersInput
user Pointer to the user structure.
DescriptionReturns the user description from the specified user object.
Do not free the character string that is returned. This data is maintained in theivadmin_ldapuser object.
Command line equivalent:pdadmin user show user_name
The user description is part of the information returned by the pdadmincommand.
Return ValuesReturns the user description from the specified user object. The maximum lengthof the description is 1024 characters.
252 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_user_getdisabletimeint()
Gets the amount of time to disable the specified user account if the maximumnumber of login failures is exceeded.
Syntaxunsigned longivadmin_user_getdisabletimeint(
ivadmin_context ctx,const char *userid,unsigned long *seconds,unsigned long *disable,unsigned long *unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
Output
secondsDisable the user account for the specified number of seconds if themaximum number of login failures is exceeded.
disable Disable the user account if the maximum number of login failures isexceeded. Administrator action is required to enable the account.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets the amount of time to disable each user account if the maximum number oflogin failures is exceeded.
Command line equivalent:pdadmin policy get disable-time-interval [-user user_name]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 253
ivadmin_user_getdn()
Returns the user registry distinguished name from the specified user object.
Syntaxconst char *ivadmin_user_getdn(
ivadmin_ldapuser user);
ParametersInput
user Pointer to the user structure.
DescriptionReturns the user registry distinguished name from the specified user object.
Do not free the character string that is returned. This data is maintained in theivadmin_ldapuser object.
Command line equivalent:pdadmin user show user_name
The user registry distinguished name for the user is part of the informationreturned by the pdadmin command.
Return ValuesReturns the user registry distinguished name from the specified user object.
User registry difference: The maxmum length of the distinguished name isdependent on the user registry being used. SeeAppendix B, “User registry differences”, on page 289 todetermine the maximum length for your environment.
254 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_user_getid()
Returns the user name from the specified user object.
Syntaxconst char *ivadmin_user_getid(
ivadmin_ldapuser user);
ParametersInput
user Pointer to the user structure.
DescriptionReturns the user name from the specified user object.
Do not free the character string that is returned. This data is maintained in theivadmin_ldapuser object.
Command line equivalent:pdadmin user show user_name
The user name (login identifier) is part of the information returned by thepdadmin command.
Return ValuesReturns the user name from the specified user object. The maximum length of thename is 256 characters.
Chapter 10. Administration C API reference 255
ivadmin_user_getmaxlgnfails()
Gets the maximum number of login failures allowed for the specified user account.
Syntaxunsigned longivadmin_user_getmaxlgnfails(
ivadmin_context ctx,const char *userid,unsigned long *failures,unsigned long *unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
Output
failuresMaximum number of login failures allowed.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets the maximum number of login failures allowed for the specified user account.
Command line equivalent:pdadmin policy get max-login-failures [-user user_name]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
256 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_user_getmaxpwdage()
Gets the maximum password age for the specified user account.
Syntaxunsigned longivadmin_user_getmaxpwdage(
ivadmin_context ctx,const char *userid,unsigned long *seconds,unsigned long *unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
Output
secondsReturned maximum lifetime, in seconds, before expiration of the password.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets the maximum password age for the specified user account.
Command line equivalent:pdadmin policy get max-password-age [-user user_name]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 257
ivadmin_user_getmaxpwdrepchars()
Gets the maximum number of repeated characters allowed in a password for thespecified user account.
Syntaxunsigned longivadmin_user_getmaxpwdrepchars(
ivadmin_context ctx,const char *userid,unsigned long *chars,unsigned long *unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
Output
chars Maximum number of repeated characters allowed.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets the maximum number of repeated characters allowed in a password for thespecified user account.
Command line equivalent:pdadmin policy get max-password-repeated-chars [-user user_name]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
258 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_user_getmemberships()
Gets the groups in which the specified user is a member.
Syntaxunsigned longivadmin_user_getmemberships(
ivadmin_context ctx,const char *userid,unsigned long *count,char ***groupids,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid Tivoli Access Manager user name.
Output
count The number of group names returned. Zero is returned if an error occurs.
groupidsAn array of pointers to the group names returned. You must free thecharacter data referenced by each pointer, as well as the array of pointerswhen they are no longer needed.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets the groups in which the specified user is a member.
Command line equivalent:pdadmin user show-groups user_name
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 259
ivadmin_user_getminpwdalphas()
Gets the minimum number of alphabetic characters allowed in a password for thespecified user account.
Syntaxunsigned longivadmin_user_getminpwdalphas(
ivadmin_context ctx,const char *userid,unsigned long *chars,unsigned long *unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
Output
chars Minimum number of alphabetic characters allowed.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets the minimum number of alphabetic characters allowed in a password for thespecified user account.
Command line equivalent:pdadmin policy get min-password-alphas [-user user_name]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
260 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_user_getminpwdlen()
Gets the minimum password length for the specified user account.
Syntaxunsigned longivadmin_user_getminpwdlen(
ivadmin_context ctx,const char *userid,unsigned long *length,unsigned long *unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
Output
length Returned minimum allowed password length.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets the minimum password length for the specified user account.
Command line equivalent:pdadmin policy get min-password-length [-user user_name]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 261
ivadmin_user_getminpwdnonalphas()
Gets the minimum number of nonalphabetic characters allowed in a password forthe specified user account.
Syntaxunsigned longivadmin_user_getminpwdnonalphas(
ivadmin_context ctx,const char *userid,unsigned long *chars,unsigned long *unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
Output
chars Minimum number of nonalphabetic characters allowed.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets the minimum number of nonalphabetic characters allowed in a password forthe specified user account.
Command line equivalent:pdadmin policy get min-password-non-alphas [-user user_name]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
262 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_user_getpasswordvalid()
Returns the password valid indicator.
Syntaxunsigned longivadmin_user_getpasswordvalid(
ivadmin_ldapuser user);
ParametersInput
user Pointer to the user structure.
DescriptionReturns the password valid indicator. Supported values are IVADMIN_TRUE andIVADMIN_FALSE.
Command line equivalent:pdadmin user show user_name
The password valid status is part of the information returned by the pdadmincommand.
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. Indicates that the password is valid.
IVADMIN_FALSEDefined as 0. Indicates that the password has expired.
Chapter 10. Administration C API reference 263
ivadmin_user_getpwdspaces()
Gets whether spaces are allowed in passwords for the specified user account.
Syntaxunsigned longivadmin_user_getpwdspaces(
ivadmin_context ctx,const char *userid,unsigned long *allowed,unsigned long *unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
Output
allowedIndicates whether spaces are allowed in passwords.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets whether spaces are allowed in passwords for the specified user account.
Command line equivalent:pdadmin policy get password-spaces [-user user_name]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
264 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_user_getsn()
Returns the user registry surname attribute for the specified user.
Syntaxconst char *ivadmin_user_getsn(
ivadmin_ldapuser user);
ParametersInput
user Pointer to the user structure.
DescriptionReturns the user registry surname attribute for the specified user.
Do not free the character string that is returned. This data is maintained in theivadmin_ldapuser structure.
Command line equivalent:pdadmin user show user_name
The user registry surname for the user is part of the information returned by thepdadmin command.
Return ValuesReturns the user registry surname attribute for the specified user.
User registry difference: The maxmum length of the surname attribute isdependent on the user registry being used. SeeAppendix B, “User registry differences”, on page 289 todetermine the maximum length for your environment.
Chapter 10. Administration C API reference 265
ivadmin_user_getssouser()
Returns a setting that indicates if the user account has single signon capabilities.
Syntaxunsigned longivadmin_user_getssouser(
ivadmin_ldapuser user);
ParametersInput
user Pointer to the user structure.
DescriptionReturns a setting that indicates if the user account has single signon capabilities.
Command line equivalent:pdadmin user show user_name
The single signon status for the user is part of the information returned by thepdadmin command.
Return ValuesThe following values are returned:
IVADMIN_TRUEDefined as 1. Indicates that the user account is single signon capable.
IVADMIN_FALSEDefined as 0. Indicates that the user account is not single signon capable.
266 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_user_gettodaccess()
Gets the time of day access policy for the specified user.
Syntaxunsigned longivadmin_user_gettodaccess(
ivadmin_context ctx,const char *userid,unsigned long *days,unsigned long *start,unsigned long *end,unsigned long *reference,unsigned long *unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server
userid User registry user name.
Output
days A bitmap of the days for the time of day access policy.
start The minutes after midnight for the start of the time range.
end The minutes after midnight for the end of the time range.
referenceThe time zone: Universal Time Coordinated (UTC) or local.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionGets the time of day access policy for the specified user.
Command line equivalent:pdadmin policy get todaccess -user userID
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 267
ivadmin_user_import2()
Creates an Tivoli Access Manager user by importing an existing user in the userregistry.
Syntaxunsigned longivadmin_user_import2(
ivadmin_context ctx,const char *userid,const char *dn,const char *groupid,unsigned long ssouser,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
dn User registry distinguished name.
groupidThe initial user registry group to which the user belongs. This value can beNULL to indicate no initial group membership.
ssouser User is capable of having single signon credentials.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionCreates an Tivoli Access Manager user by importing an existing user in the userregistry.
Accounts are created invalid by default. You must useivadmin_user_setaccountvalid() to enable the account.
Command line equivalent:pdadmin user import [-gsouser] user_name dn
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
268 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_user_list()
Lists the Tivoli Access Manager users that match the specified pattern.
Syntaxunsigned longivadmin_user_list(
ivadmin_context ctx,const char *pattern,unsigned long maxreturn,unsigned long *count,char ***userids,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
patternPattern match for user names. IVADMIN_ALLPATTERN indicates all users.
maxreturnMaximum number to return. IVADMIN_MAXRETURN indicatesunlimited. This number can be limited by the user registry server so thatthe maximum returned is really the minimum of the server configurationand this value.
Output
count The number of user names returned. Zero is returned if an error occurs.
userids An array of pointers to the user names returned. You must free thecharacter data referenced by each pointer, as well as the array of pointerswhen they are no longer needed.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionLists the names of the Tivoli Access Manager users in the user registry that matchthe specified pattern. Returns an array of pointers to character strings containingthe user IDs.
The following constants are defined:#define IVADMIN_MAXRETURN 0#define IVADMIN_ALLPATTERN "*"
Command line equivalent:pdadmin user list pattern max_return
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
Chapter 10. Administration C API reference 269
IVADMIN_FALSEDefined as 0. The function encountered an error.
270 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_user_listbydn()
Returns the list of user registry distinguished names whose user registry commonname attribute matches the pattern specified.
Syntaxunsigned longivadmin_user_listbydn(
ivadmin_context ctx,const char *pattern,unsigned long maxreturn,unsigned long *count,char ***dns,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
pattern Pattern match for user registry common name attribute.IVADMIN_ALLPATTERN indicates all users.
maxreturnMaximum number to return. IVADMIN_MAXRETURN indicatesunlimited. This number can be limited by the user registry server so thatthe maximum returned is really the minimum of the server configurationand this value.
Output
count The number of user registry distinguished names returned. Zero isreturned if an error occurs.
dns An array of pointers to the user registry distinguished names returned. Youmust free the character data referenced by each pointer, as well as thearray of pointers when they are no longer needed.
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionReturns the list of user registry distinguished names whose user registry commonname attribute matches the pattern specified. Returns an array of pointers tocharacter strings containing each user’s distinguished name.
Command line equivalent:pdadmin user list-dn pattern max_return
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 271
ivadmin_user_setaccexpdate()
Sets the account expiration date for specified user.
Syntaxunsigned longivadmin_user_setaccexpdate(
ivadmin_context ctx,const char *userid,unsigned long seconds,unsigned long unlimited,unsigned long unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
secondsDate and time of the expiration of specified user account. This is thenumber of seconds since 00:00:00 Universal time, 1 January 1970 (same astime_t).
unlimitedDo not expire specified user account and ignore the seconds parameter ifset to true.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the account expiration date for specified user.
Command line equivalent:pdadmin policy set account-expiry-date {unlimited | absolute_time | unset} \[-user user_name]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
272 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_user_setaccountvalid()
Enables or disables the specified Tivoli Access Manager user account.
Syntaxunsigned longivadmin_user_setaccountvalid(
ivadmin_context ctx,const char *userid,unsigned long valid,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
valid Boolean indicator of account validity.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionEnables or disables the specified Tivoli Access Manager user account. Use thisfunction to enable an account after it has been created with ivadmin_user_create3()or ivadmin_user_import().
Command line equivalent:pdadmin user modify user_name account-valid {yes | no}
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 273
ivadmin_user_setdescription()
Modifies the user description.
Syntaxunsigned longivadmin_user_setdescription(
ivadmin_context ctx,const char *userid,const char *description,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
descriptionNew description.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionModifies the user description. The description is an arbitrary text string. Forexample:Diana Lucas, Credit Dept HCUS
Command line equivalent:pdadmin user modify user_name description description
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
274 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_user_setdisabletimeint()
Sets the time to disable the specified user account when the maximum number oflogin failures is exceeded.
Syntaxunsigned longivadmin_user_setdisabletimeint(
ivadmin_context ctx,const char *userid,unsigned long seconds,unsigned long disable,unsigned long unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
secondsDisable the user account for the specified number of seconds when themaximum number of login failures is exceeded.
disable Disable the user account when the maximum number of login failures isexceeded. Administrator action is required to enable the account.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the time to disable the specified user account when the maximum number oflogin failures is exceeded.
Command line equivalent:pdadmin policy set disable-time-interval {number | unset | disable} \[-user user_name]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 275
ivadmin_user_setmaxlgnfails()
Sets the maximum number of login failures allowed for the specified user account.
Syntaxunsigned longivadmin_user_setmaxlgnfails(
ivadmin_context ctx,const char *userid,unsigned long failures,unsigned long unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
failures Maximum number of login failures allowed.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSet the maximum number of login failures allowed for the specified user account.
Command line equivalent:pdadmin policy set max-login-failures number | unset [-user user_name]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
276 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_user_setmaxpwdage()
Sets the maximum password age for the specified user account.
Syntaxunsigned longivadmin_user_setmaxpwdage(
ivadmin_context ctx,const char *userid,unsigned long seconds,unsigned long unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
secondsMaximum lifetime, in seconds, before expiration of password.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the maximum password age for the specified user account.
Command line equivalent:pdadmin policy set max-password-age {unset | relative_time} [-user user_name]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 277
ivadmin_user_setmaxpwdrepchars()
Sets the maximum number of repeated characters allowed in a password for thespecified user account.
Syntaxunsigned longivadmin_user_setmaxpwdrepchars(
ivadmin_context ctx,const char *userid,unsigned long chars,unsigned long unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
chars Maximum number of repeated characters allowed.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the maximum number of repeated characters allowed in a password for thespecified user account.
Command line equivalent:pdadmin policy set max-password-repeated-chars number | unset [-user user_name]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
278 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_user_setminpwdalphas()
Sets the minimum number of alphabetic characters allowed in a password for thespecified user account.
Syntaxunsigned longivadmin_user_setminpwdalphas(
ivadmin_context ctx,const char *userid,unsigned long chars,unsigned long unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
chars Minimum number of alphabetic characters allowed.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the minimum number of alphabetic characters allowed in a password for thespecified user account.
Command line equivalent:pdadmin policy set min-password-alphas {unset | number}[-user user_name]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 279
ivadmin_user_setminpwdlen()
Sets the minimum password length for the specified user account.
Syntaxunsigned longivadmin_user_setminpwdlen(
ivadmin_context ctx,const char *userid,unsigned long length,unsigned long unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
length Minimum allowed password length to be set.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the minimum password length for the specified user account.
Command line equivalent:pdadmin policy set min-password-length {unset | number} [-user user_name]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
280 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_user_setminpwdnonalphas()
Sets the minimum number of nonalphabetic characters allowed in a password forthe specified user account.
Syntaxunsigned longivadmin_user_setminpwdnonalphas(
ivadmin_context ctx,const char *userid,unsigned long chars,unsigned long unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
chars Minimum number of nonalphabetic characters allowed.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the minimum number of nonalphabetic characters allowed in a password forthe specified user account.
Command line equivalent:pdadmin policy set min-password-non-alphas {unset | number} [-user user_name]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 281
ivadmin_user_setpassword()
Modifies the user password.
Syntaxunsigned longivadmin_user_setpassword(
ivadmin_context ctx,const char *userid,const char *pwd,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
pwd New password.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionModifies the user password.
If the user that is having its password set is the same user that created the securitycontext, ctx, no further authorization checks are performed.
Command line equivalent:pdadmin user modify user_name password password
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
282 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_user_setpasswordvalid()
Expires the Tivoli Access Manager account password.
Syntaxunsigned longivadmin_user_setpasswordvalid(
ivadmin_context ctx,const char *userid,unsigned long valid,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
valid Indicates whether the password is valid or has expired.
Supported values are IVADMIN_FALSE (expired) or IVADMIN_TRUE(valid).
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionExpires the Tivoli Access Manager account password. This forces the user tochange the password at the next login attempt.
Command line equivalent:pdadmin user modify user_name password-valid {yes | no}
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 283
ivadmin_user_setpwdspaces()
Sets whether spaces are allowed in passwords for the specified user account.
Syntaxunsigned longivadmin_user_setpwdspaces(
ivadmin_context ctx,const char *userid,unsigned long allowed,unsigned long unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
allowedIndicates whether spaces are allowed in passwords.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets whether spaces are allowed in passwords for the specified user account.
Command line equivalent:pdadmin policy set password-spaces {yes | no | unset} [-user user_name]
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
284 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_user_setssouser()
Enables or disables the single sign on capabilities of an Tivoli Access Manager user.
Syntaxunsigned longivadmin_user_setssouser(
ivadmin_context ctx,const char *userid,unsigned long ssouser,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User name.
ssouser User is capable of having single signon credentials.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionEnables or disables the single sign on capabilities of an Tivoli Access Manager user.
Command line equivalent:pdadmin user modify user-name gsouser {yes | no}
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
Chapter 10. Administration C API reference 285
ivadmin_user_settodaccess()
Sets the time of day access policy for the specified user.
Syntaxunsigned longivadmin_user_settodaccess(
ivadmin_context ctx,const char *userid,unsigned long days,unsigned long start,unsigned long end,unsigned long reference,unsigned long unset,ivadmin_response *rsp
);
ParametersInput
ctx Context to communicate with the Tivoli Access Manager policy server.
userid User registry user name.
days A bitmap of the days for the time of day access policy.
start The minutes after midnight for the start of the time range.
end The minutes after midnight for the end of the time range.
referenceThe time zone: Universal Coordinated Time (UTC) or local.
unset Policy ignored and not enforced if set to true. If set to false, the policy isset as specified.
Supported values are IVADMIN_TRUE and IVADMIN_FALSE.
Output
rsp The response object. Indicates the success or failure of the function.Contains error information. Free this object when it is no longer needed.
DescriptionSets the time of day access policy for the specified user.
Command line equivalent:pdadmin policy set todaccess todaccess_string -user userID
Return ValuesReturns the following Boolean values:
IVADMIN_TRUEDefined as 1. The function executed successfully.
IVADMIN_FALSEDefined as 0. The function encountered an error.
286 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Appendix A. Deprecated APIs
The APIs listed in Table 34 have been deprecated in IBM Tivoli Access Manager(Tivoli Access Manager) Version 4.1. The ivadmin_deprecated.h header file containsthe prototypes and definitions for these deprecated APIs. Avoid including thisheader file because the symbols it declares are not supported. Instead, changeexisting applications to use any replacement APIs listed in the table.
Table 34. APIs deprecated in Tivoli Access Manager Version 4.1
Deprecated API Replacement API
ivadmin_user_setauthmech None
ivadmin_user_getauthmech None
The constants listed in Figure 1 have been deprecated in Tivoli Access ManagerVersion 4.1. The ivadmin_deprecated.h header file contains the definitions for thesedeprecated constants. Avoid including this header file because the symbols itdeclares are not supported.
The APIs listed in Table 35 were deprecated in previous versions of IBM TivoliAccess Manager and Tivoli SecureWay Policy Director.
Table 35. APIs deprecated in previous versions of Tivoli Access Manager and TivoliSecureWay Policy Director
Deprecated API Replacement API
ivadmin_cfg_configureserver ivadmin_cfg_configureserver2
ivadmin_context_create ivadmin_context_createdefault
ivadmin_group_addmember ivadmin_group_addmembers
ivadmin_group_removemember ivadmin_group_removemembers
ivadmin_user_create2 ivadmin_user_create3
ivadmin_group_create ivadmin_group_create2
ivadmin_group_delete ivadmin_group_delete2
ivadmin_group_import ivadmin_group_import2
ivadmin_protobj_get ivadmin_protobj_get2
ivadmin_protobj_list2 ivadmin_protobj_list3
ivadmin_user_create ivadmin_user_create3
ivadmin_user_delete ivadmin_user_delete2
ivadmin_user_import ivadmin_user_import2
IVADMIN_USER_DCEAUTHMETHIVADMIN_USER_LDAPAUTHMETH
Figure 1. Constants deprecated in Tivoli Access Manager Version 4.1
© Copyright IBM Corp. 2000, 2003 287
288 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Appendix B. User registry differences
The following user registry differences are known to exist in this version of IBMTivoli Access Manager (Tivoli Access Manager.)1. Leading and trailing blanks in user names and group names are ignored when
using LDAP or Microsoft Active Directory as the user registry in an TivoliAccess Manager secure domain. However, when using a Lotus Domino serveras a user registry, leading and trailing blanks are significant. To ensure thatprocessing is consistent regardless of what user registry is being used, defineusers and groups in the user registry without leading or trailing blanks intheir names.
2. The forward slash character (/) should be avoided in user and group namesdefined using distinguished name strings. The forward slash character istreated differently in different user registries:
Lotus Domino serverUsers and groups can not be created with names using adistinguished name string containing a forward slash character. Toavoid the problem, either do not use a forward slash character ordefine the user without using the distinguished name designation:pdadmin user create myuser username/locinfo test test testpwd
instead of using this one:pdadmin user create myuser cn=username/o=locinfo test test testpwd
Microsoft Active DirectoryUsers and groups can be created with names using a distinguishedname string containing a forward slash character. However,subsequent operations on the object might fail as some ActiveDirectory functions interpret the forward slash character as a separatorbetween the object name and the host name. To avoid the problem, donot use a forward slash character to define the user.
3. When using a multi-domain Microsoft Active Directory user registry, multipleusers and groups can be defined with the same short name as long as theyreside in different domains. To query information associated with a specificuser or group, use the full name, including the domain, of the user or groupto ensure that you are getting the correct information. If the domaininformation is omitted, information about the user or group defined in thedefault domain is returned, which might not be the expected user or group.The sole use of a short name to identify a user or group should be avoidedfor the same reason.
4. If Microsoft Active Directory is used as the user registry, care must be takenwith user and group names that contain period characters (.) Active Directorydoes not permit a name to end with a period. (See Microsoft Knowledge Basearticle 316595 for details.) The first twenty (20) characters of a user or groupname created by Tivoli Access Manager are mapped to a SAMAccountNamein Active Directory. If the 20th character happens to be a period character,Active Directory considers the name not valid and generates an error. This canhappen if a server in the Tivoli Access Manager happens to have a period inits name in that position, such as centralpolicyserver.company.com.To avoid this problem, rename servers in the Tivoli Access Managerenvironment that have a period character in the 20th position of their name.
© Copyright IBM Corp. 2000, 2003 289
Alternately, if the period occurs in the DNS suffix for a Microsoft Windowsserver, you might be able to avoid the problem by removing the primary DNSsuffix from the Network settings.
5. When using iPlanet Version 5.0 as the user registry, a user that is created,added to a group, and then deleted from the user registry retains its groupmembership. If a user with the same name is created at some later time, thenew user automatically inherits the old group membership and might begiven inappropriate permissions. It is strongly recommended that the user beremoved from all groups before the user is deleted. This problem does notoccur when using the other supported user registries.
6. Attempting to add a duplicate user to a group produces different resultsbased on the user registry being used. Table 36 outlines the differences.
Table 36. User registry differences when adding a duplicate user to a group
Operation LDAP Lotus Domino server Microsoft ActiveDirectory
Add one user andthat user is duplicate
Error No error Error
Add multiple users,first user is duplicate
Error for all users No error Error for all users
Add multiple users, auser other than thefirst is a duplicate
Error for all users No error Partial completionmessage
7. Attempting to remove a user from a group who is not a member of the groupproduces different results based on the user registry being used. Table 37outlines the differences.
Table 37. User registry differences when removing a user from a group who is not amember of the group
Operation LDAP Lotus Domino server Microsoft ActiveDirectory
Remove one user,user is not in thegroup
Error Error Error
Remove multipleusers, first user notin the group
Error for all users Error Error for all users
Remove multipleusers, a user otherthan the first is not inthe group
Error for all users Partial completionmessage
Partial completionmessage
8. The maximum lengths of various names associated with Tivoli AccessManager vary depending on the user registry being used. See Table 38 onpage 291 for a comparison of the maximum lengths allowed and therecommended maximum length to use to ensure compatibility with all theuser registries supported by Tivoli Access Manager.
290 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Table 38. Maximum lengths for names based on user registry
Maximumlength of:
LDAP Microsoft ActiveDirectory
Lotus Dominoserver
Recommendedmaximum value
First name(LDAP CN)
256 64 960 64
Middle name 128 64 65535 64
Last name(surname)
128 64 960 64
Registry UID(LDAP DN)
1024 2048 255 This value isuser
registry-specificand must be
changed whenchanging user
registries.
Tivoli AccessManager useridentity
256 2048 - 1 -length_of_
domain_name
200 - 4 -length_of_
domain_name
This value isuser
registry-specificand must be
changed whenchanging user
registries.
User password unlimited 256 unlimited 256
User description 1024 1024 1024 1024
Group name 256 256
Groupdescription
1024 1024 1024 1024
Single signonresource name
240 256 256 240
Single signonresourcedescription
1024 1024 1024 1024
Single signonuser ID
240 256 256 240
Single signonpassword
unlimited 256 unlimited 256
Single signongroup name
240 256 256 240
Single signongroupdescription
1024 1024 1024 1024
Action name 1 1 1 1
Actiondescription,action type
unlimited unlimited unlimited
Object name,object spacename, ACLname, POPname
unlimited unlimited unlimited
Appendix B. User registry differences 291
Table 38. Maximum lengths for names based on user registry (continued)
Maximumlength of:
LDAP Microsoft ActiveDirectory
Lotus Dominoserver
Recommendedmaximum value
Objectdescription,object spacedescription, ACLdescription, POPdescription
unlimited unlimited unlimited
Even though some names can be of unlimited length, excessive lengths canresult in policy that is difficult to manage and might result in poor systemperformance. Choose maximum values that are logical for your environment.
9. Users created in a Lotus Domino server or Microsoft Active Directory userregistry are automatically given the capability to own single signon credentialsand this capability can not be removed. When using an LDAP user registry,this capability must be explicitly granted to a user and subsequently can beremoved.
10. When the Tivoli Access Manager policy server is using either Microsoft ActiveDirectory or a Lotus Domino server as its user registry, existing TivoliSecureWay Policy Director, Version 3.8 clients are not able to connect to thepolicy server. Either use a different user registry or upgrade the clients toTivoli Access Manager.
292 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Appendix C. Administration C API, Java method, andcommand line equivalents
This appendix shows the mapping that exists between the administration C APIfunctions, the administration Java classes and methods, and the command lineinterface (CLI). In some cases, a given operation can be performed different ways.Note that in some cases two or more method calls might be necessary to achievethe same effect as a single C API function.
Information about the administration Java classes and methods can be found in theIBM Tivoli Access Manager Administration Java Classes Developer’s Reference.
Information about the pdadmin command line interface can be found in the IBMTivoli Access Manager Command Reference.
© Copyright IBM Corp. 2000, 2003 293
Tabl
e39
.M
appi
ngbe
twee
nad
min
istr
atio
nC
AP
I,Ja
vam
etho
ds,
and
the
com
man
dlin
ein
terf
ace
CA
PI
Java
Cla
ssan
dM
eth
odC
omm
and
Lin
eE
qu
ival
ent
ivad
min
_acl
_att
rdel
key
()P
DA
cl.d
elet
eAtt
rib
ute
PD
Acl
obje
ct.d
elet
eAtt
rib
ute
pdad
min
acl
modi
fyac
l_na
mede
lete
attr
ibut
eat
trib
ute_
name
ivad
min
_acl
_att
rdel
val(
)P
DA
cl.d
elet
eAtt
rib
ute
Val
ue
PD
Acl
obje
ct.d
elet
eAtt
rib
ute
Val
ue
pdad
min
acl
modi
fyac
l_na
mede
lete
attr
ibut
eat
trib
ute_
name
attr
ibut
e_va
lue
ivad
min
_acl
_att
rget
()P
DA
clob
ject
.get
Att
rib
ute
Val
ues
pdad
min
acl
show
acl_
name
attr
ibut
eat
trib
ute_
name
ivad
min
_acl
_att
rlis
t()
PD
Acl
obje
ct.g
etA
ttri
bu
teN
ames
pdad
min
acl
list
acl_
name
attr
ibut
e
ivad
min
_acl
_att
rpu
t()
PD
Acl
.set
Att
rib
ute
Val
ue
PD
Acl
obje
ct.s
etA
ttri
bu
teV
alu
epd
admi
nac
lmo
dify
acl_
name
set
attr
ibut
eat
trib
ute_
name
attr
ibut
e_va
lue
ivad
min
_acl
_cre
ate(
)P
DA
cl.c
reat
eAcl
pdad
min
acl
crea
teac
l_na
me
ivad
min
_acl
_del
ete(
)P
DA
cl.d
elet
eAcl
pdad
min
acl
dele
teac
l_na
me
ivad
min
_acl
_get
()P
DA
clco
nstr
ucto
rpd
admi
nac
lsh
owac
l_na
me
ivad
min
_acl
_get
anyo
ther
()P
DA
clob
ject
.get
PD
Acl
En
tryA
nyO
ther
pdad
min
acl
show
any-
othe
r
ivad
min
_acl
_get
des
crip
tion
()P
DA
clob
ject
.get
Des
crip
tion
pdad
min
acl
show
acl_
name
ivad
min
_acl
_get
grou
p()
PD
Acl
obje
ct.g
etP
DA
clE
ntr
iesG
rou
ppd
admi
nac
lsh
owac
l_na
me
ivad
min
_acl
_get
id()
PD
Acl
obje
ct.g
etId
pdad
min
acl
show
acl_
name
ivad
min
_acl
_get
un
auth
()P
DA
clob
ject
.get
PD
Acl
En
tryU
nA
uth
pdad
min
acl
show
acl_
name
ivad
min
_acl
_get
use
r()
PD
Acl
obje
ct.g
etP
DA
clE
ntr
iesU
ser
pdad
min
acl
show
acl_
name
ivad
min
_acl
_lis
t()
PD
Acl
.list
Acl
spd
admi
nac
lli
st
ivad
min
_acl
_lis
tgro
up
s()
PD
Acl
obje
ct.g
etP
DA
clE
ntr
iesG
rou
ppd
admi
nac
lsh
owac
l_na
me
ivad
min
_acl
_lis
tuse
rs()
PD
Acl
obje
ct.g
etP
DA
clE
ntr
iesU
ser
pdad
min
acl
show
acl_
name
ivad
min
_acl
_rem
ovea
nyo
ther
()P
DA
cl.r
emov
ePD
Acl
En
tryA
nyO
ther
PD
Acl
obje
ct.r
emov
ePD
Acl
En
tryA
nyO
ther
pdad
min
acl
modi
fyac
l_na
mere
move
any-
othe
r
ivad
min
_acl
_rem
oveg
rou
p()
PD
Acl
.rem
oveP
DA
clE
ntr
yGro
up
PD
Acl
obje
ct.r
emov
ePD
Acl
En
tryG
rou
ppd
admi
nac
lmo
dify
acl_
name
remo
vegr
oup
grou
p_na
me
ivad
min
_acl
_rem
oveu
nau
th()
PD
Acl
.rem
oveP
DA
clE
ntr
yUn
Au
thP
DA
clob
ject
.rem
oveP
DA
clE
ntr
yUn
Au
thpd
admi
nac
lmo
dify
acl_
name
remo
veun
auth
enti
cate
d
ivad
min
_acl
_rem
oveu
ser(
)P
DA
cl.r
emov
ePD
Acl
En
tryU
ser
PD
Acl
obje
ct.r
emov
ePD
Acl
En
tryU
ser
pdad
min
acl
modi
fyac
l_na
mere
move
user
user
_nam
e
ivad
min
_acl
_set
anyo
ther
()P
DA
cl.s
etP
DA
clE
ntr
yAn
yOth
erP
DA
clob
ject
.set
PD
Acl
En
tryA
nyO
ther
pdad
min
acl
modi
fyac
l_na
mese
tan
y-ot
her
perm
s
294 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Tabl
e39
.M
appi
ngbe
twee
nad
min
istr
atio
nC
AP
I,Ja
vam
etho
ds,
and
the
com
man
dlin
ein
terf
ace
(con
tinue
d)
CA
PI
Java
Cla
ssan
dM
eth
odC
omm
and
Lin
eE
qu
ival
ent
ivad
min
_acl
_set
des
crip
tion
()P
DA
cl.s
etD
escr
ipti
onP
DA
clob
ject
.set
Des
crip
tion
pdad
min
acl
modi
fyac
l_na
mede
scri
ptio
nde
scri
ptio
n
ivad
min
_acl
_set
grou
p()
PD
Acl
.set
PD
Acl
En
tryG
rou
pP
DA
clob
ject
.set
PD
Acl
En
tryG
rou
ppd
admi
nac
lmo
dify
acl_
name
set
grou
pgr
oup_
name
perm
s
ivad
min
_acl
_set
un
auth
()P
DA
cl.s
etP
DA
clE
ntr
yUn
Au
thP
DA
clob
ject
.set
PD
Acl
En
tryU
nA
uth
pdad
min
acl
modi
fyac
l_na
mese
tun
auth
enti
cate
dpe
rms
ivad
min
_acl
_set
use
r()
PD
Acl
.set
PD
Acl
En
tryU
ser
PD
Acl
obje
ct.s
etP
DA
clE
ntr
yUse
rpd
admi
nac
lmo
dify
acl_
name
set
user
user
_nam
epe
rms
ivad
min
_act
ion
_cre
ate(
)P
DA
ctio
n.c
reat
eAct
ion
pdad
min
acti
oncr
eate
name
desc
ript
ion
acti
on_t
ype
ivad
min
_act
ion
_cre
ate_
in_g
rou
p()
PD
Act
ion
.cre
ateA
ctio
npd
admi
nac
tion
crea
tena
mede
scri
ptio
nac
tion
_typ
eac
tion
_gro
up_n
ame
ivad
min
_act
ion
_del
ete(
)P
DA
ctio
n.d
elet
eAct
ion
pdad
min
acti
onde
lete
name
ivad
min
_act
ion
_del
ete_
from
_gro
up
()P
DA
ctio
n.d
elet
eAct
ion
pdad
min
acti
onde
lete
name
acti
on_g
roup
_nam
e
ivad
min
_act
ion
_get
des
crip
tion
()P
DA
ctio
nob
ject
.get
Des
crip
tion
pdad
min
acti
onli
st
ivad
min
_act
ion
_get
id()
PD
Act
ion
obje
ct.g
etId
pdad
min
acti
onli
st
ivad
min
_act
ion
_get
typ
e()
PD
Act
ion
obje
ct.g
etTy
pe
pdad
min
acti
onli
st
ivad
min
_act
ion
_gro
up
_cre
ate(
)P
DA
ctio
nG
rou
p.c
reat
eAct
ion
Gro
up
pdad
min
acti
ongr
oup
crea
teac
tion
_gro
up_n
ame
ivad
min
_act
ion
_gro
up
_del
ete(
)P
DA
ctio
nG
rou
p.d
elet
eAct
ion
Gro
up
pdad
min
acti
ongr
oup
dele
teac
tion
_gro
up_n
ame
ivad
min
_act
ion
_gro
up
_lis
t()
PD
Act
ion
Gro
up
.list
Act
ion
Gro
up
spd
admi
nac
tion
grou
pli
st
ivad
min
_act
ion
_lis
t()
PD
Act
ion
.list
Act
ion
spd
admi
nac
tion
list
ivad
min
_act
ion
_lis
t_in
_gro
up
()P
DA
ctio
n.li
stA
ctio
ns
pdad
min
acti
onli
stac
tion
_gro
up_n
ame
ivad
min
_cfg
_ad
dre
pli
ca()
PD
Ap
pS
vrC
onfi
g.ad
dP
DS
erve
r.
svrs
slcf
g-a
dd_r
epli
ca-f
cfg_
file
-hho
st_n
ame
[-p
port
][-
kra
nk]
ivad
min
_cfg
_ch
grep
lica
()P
DA
pp
Svr
Con
fig.
chan
geP
DS
erve
rsv
rssl
cfg
-chg
_rep
lica
-fcf
g_fi
le-h
host
_nam
e[-
ppo
rt]
[-k
rank
]
ivad
min
_cfg
_con
figu
rese
rver
2()
PD
Ap
pS
vrC
onfi
g.co
nfi
gure
Ap
pS
vrsv
rssl
cfg
-con
fig
-fcf
g_fi
le-d
kdb_
dir_
name
-nse
rver
_nam
e..
.
ivad
min
_cfg
_ren
ewse
rver
cert
()P
DA
pp
Svr
Con
fig.
rep
lace
Ap
pS
vrC
ert
svrs
slcf
g-c
hgce
rt-f
cfg_
file
-nse
rver
_nam
e[-
Aad
min_
ID]
-Pad
min_
pwd
ivad
min
_cfg
_rm
vrep
lica
()P
DA
pp
Svr
Con
fig.
rem
oveP
DS
erve
rsv
rssl
cfg
-rmv
_rep
lica
-fcf
g_fi
le-h
host
_nam
e[-
ppo
rt]
[-k
rank
]
Appendix C. Administration C API, Java method, and command line equivalents 295
Tabl
e39
.M
appi
ngbe
twee
nad
min
istr
atio
nC
AP
I,Ja
vam
etho
ds,
and
the
com
man
dlin
ein
terf
ace
(con
tinue
d)
CA
PI
Java
Cla
ssan
dM
eth
odC
omm
and
Lin
eE
qu
ival
ent
ivad
min
_cfg
_set
app
lica
tion
cert
()N
otsu
ppor
ted
atth
isti
me.
svrs
slcf
g-m
odif
y-f
cfg_
file
[-t
time
out]
[-C
cert
_fil
e][-
lli
sten
ing_
mode
]
ivad
min
_cfg
_set
key
rin
gpw
d()
Not
appl
icab
le.
svrs
slcf
g-c
hgpw
d-f
cfg_
file
-nse
rver
_nam
e[-
Aad
min_
ID]
[-P
admi
n_pw
d]
ivad
min
_cfg
_set
list
enin
g()
PD
Ap
pS
vrC
onfi
g.se
tAp
pS
vrL
iste
nin
gsv
rssl
cfg
-fcf
g_fi
le-m
odif
y-l
yes
ivad
min
_cfg
_set
por
t()
PD
Ap
pS
vrC
onfi
g.se
tAp
pS
vrP
ort
svrs
slcf
g-c
onfi
g-f
cfg_
file
-dkd
b_di
r_na
me-n
serv
er_n
ame
...
ivad
min
_cfg
_set
sslt
imeo
ut(
)N
otsu
ppor
ted
atth
isti
me.
svrs
slcf
g-m
odif
y-f
cfg_
file
-tti
meou
t[-
Cce
rt_f
ile]
[-l
list
enin
g_mo
de]
ivad
min
_cfg
_un
con
figu
rese
rver
()P
DA
pp
Svr
Con
fig.
un
con
figu
reA
pp
Svr
svrs
slcf
g-u
ncon
fig
-fcf
g_fi
le-n
serv
er_n
ame
[-A
admi
n_ID
]-P
admi
n_pw
d
ivad
min
_con
text
_cle
ard
elcr
ed()
Not
supp
orte
dat
this
tim
e.no
tap
plic
able
ivad
min
_con
text
_cre
ate(
)P
DC
onte
xtco
nstr
ucto
rno
tap
plic
able
ivad
min
_con
text
_cre
ated
efau
lt()
PD
Con
text
cons
truc
tor
not
appl
icab
le
ivad
min
_con
text
_del
ete(
)no
tap
plic
able
not
appl
icab
le
ivad
min
_con
text
_get
acce
xpd
ate(
)P
DP
olic
yob
ject
.get
Acc
tExp
Dat
epd
admi
npo
licy
get
acco
unt-
expi
ry-d
ate
ivad
min
_con
text
_get
dis
able
tim
ein
t()
PD
Pol
icy
obje
ct.g
etA
cctD
isab
leT
imeI
nte
rval
pdad
min
poli
cyge
tdi
sabl
e-ti
me-i
nter
val
ivad
min
_con
text
_get
max
lgn
fail
s()
PD
Pol
icy
obje
ct.g
etM
axFa
iled
Log
ins
pdad
min
poli
cyge
tma
x-lo
gin-
fail
ures
ivad
min
_con
text
_get
max
pw
dag
e()
PD
Pol
icy
obje
ct.g
etM
axP
wd
Age
pdad
min
poli
cyge
tma
x-pa
sswo
rd-a
ge
ivad
min
_con
text
_get
max
pw
dre
pch
ars(
)P
DP
olic
yob
ject
.get
Max
Pw
dR
epC
har
spd
admi
npo
licy
get
max-
pass
word
-rep
eate
d-ch
ars
ivad
min
_con
text
_get
min
pw
dal
ph
as()
PD
Pol
icy
obje
ct.g
etM
inP
wd
Alp
has
pdad
min
poli
cyge
tmi
n-pa
sswo
rd-a
lpha
s
ivad
min
_con
text
_get
min
pw
dle
n()
PD
Pol
icy
obje
ct.g
etM
inP
wd
Len
pdad
min
poli
cyge
tmi
n-pa
sswo
rd-l
engt
h
ivad
min
_con
text
_get
min
pw
dn
onal
ph
as()
PD
Pol
icy
obje
ct.g
etM
inP
wd
Non
Alp
has
pdad
min
poli
cyge
tmi
n-pa
sswo
rd-n
on-a
lpha
s
ivad
min
_con
text
_get
pw
dsp
aces
()P
DP
olic
yob
ject
.pw
dS
pac
esA
llow
edpd
admi
npo
licy
get
pass
word
-spa
ces
ivad
min
_con
text
_get
tod
acce
ss()
PD
Pol
icy
obje
ct.g
etA
cces
sib
leD
ays
PD
Pol
icy
obje
ct.g
etA
cces
sSta
rtT
ime
PD
Pol
icy
obje
ct.g
etA
cces
sEn
dT
ime
PD
Pol
icy
obje
ct.g
etA
cces
sTim
ezon
e
pdad
min
poli
cyge
tto
d-ac
cess
296 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Tabl
e39
.M
appi
ngbe
twee
nad
min
istr
atio
nC
AP
I,Ja
vam
etho
ds,
and
the
com
man
dlin
ein
terf
ace
(con
tinue
d)
CA
PI
Java
Cla
ssan
dM
eth
odC
omm
and
Lin
eE
qu
ival
ent
ivad
min
_con
text
_get
use
rreg
()P
DU
ser.g
etU
serR
gypd
admi
nad
min
show
conf
igur
atio
n
ivad
min
_con
text
_set
acce
xpd
ate(
)P
DP
olic
y.se
tAcc
tExp
Dat
eP
DP
olic
yob
ject
.set
Acc
tExp
Dat
epd
admi
npo
licy
set
acco
unt-
expi
ry-d
ate
[unl
imit
ed|
abso
lute
_tim
e|
unse
t]
ivad
min
_con
text
_set
del
cred
()N
otsu
ppor
ted
atth
isti
me.
not
appl
icab
le
ivad
min
_con
text
_set
dis
able
tim
ein
t()
PD
Pol
icy.
setA
cctD
isab
leT
ime
PD
Pol
icy
obje
ct.s
etA
cctD
isab
leT
ime
pdad
min
poli
cyse
tdi
sabl
e-ti
me-i
nter
val
[num
ber
|un
set
|di
sabl
e]
ivad
min
_con
text
_set
max
lgn
fail
s()
PD
Pol
icy.
setM
axFa
iled
Log
ins
PD
Pol
icy
obje
ct.s
etM
axFa
iled
Log
ins
pdad
min
poli
cyse
tma
x-lo
gin-
fail
ures
[num
ber
|un
set]
ivad
min
_con
text
_set
max
pw
dag
e()
PD
Pol
icy.
setM
axP
wd
Age
PD
Pol
icy
obje
ct.s
etM
axP
wd
Age
pdad
min
poli
cyse
tma
x-pa
sswo
rd-a
ge[r
elat
ive_
time
|un
set]
ivad
min
_con
text
_set
max
pw
dre
pch
ars(
)P
DP
olic
y.se
tMax
Pw
dR
epC
har
sP
DP
olic
yob
ject
.set
Max
Pw
dR
epC
har
spd
admi
npo
licy
set
max-
pass
word
-rep
eate
d-ch
ars
[num
ber
|un
set]
ivad
min
_con
text
_set
min
pw
dal
ph
as()
PD
Pol
icy.
setM
inP
wd
Alp
has
PD
Pol
icy
obje
ct.s
etM
inP
wd
Alp
has
pdad
min
poli
cyse
tmi
n-pa
sswo
rd-a
lpha
s[n
umbe
r|
unse
t]
ivad
min
_con
text
_set
min
pw
dle
n()
PD
Pol
icy.
setM
inP
wd
Len
PD
Pol
icy
obje
ct.s
etM
inP
wd
Len
pdad
min
poli
cyse
tmi
n-pa
sswo
rd-l
engt
h[n
umbe
r|
unse
t]
ivad
min
_con
text
_set
min
pw
dn
onal
ph
as()
PD
Pol
icy.
setM
inP
wd
Non
Alp
has
PD
Pol
icy
obje
ct.s
etM
inP
wd
Non
Alp
has
pdad
min
poli
cyse
tma
x-pa
sswo
rd-n
on-a
lpha
s[n
umbe
r|
unse
t]
ivad
min
_con
text
_set
pw
dsp
aces
()P
DP
olic
y.se
tPw
dS
pac
esA
llow
edP
DP
olic
yob
ject
.set
Pw
dS
pac
esA
llow
edpd
admi
npo
licy
set
pass
word
-spa
ces
[yes
|no
|un
set]
ivad
min
_con
text
_set
tod
acce
ss()
PD
Pol
icy.
setT
odA
cces
sP
DP
olic
yob
ject
.set
Tod
Acc
ess
pdad
min
poli
cyse
tto
d-ac
cess
toda
cces
s_va
lue
ivad
min
_fre
e()
not
appl
icab
leno
tap
plic
able
ivad
min
_gro
up
_ad
dm
emb
ers(
)P
DG
rou
p.a
dd
Mem
ber
sP
DG
roup
obje
ct.a
dd
Mem
ber
spd
admi
ngr
oup
modi
fygr
oup_
name
add
(use
r_na
me1
user
_nam
e2..
.)
ivad
min
_gro
up
_cre
ate2
()P
DG
rou
p.c
reat
eGro
up
pdad
min
grou
pcr
eate
grou
p_na
medn
cn
ivad
min
_gro
up
_del
ete2
()P
DG
rou
p.d
elet
eGro
up
pdad
min
grou
pde
lete
[-re
gist
ry]
grou
p_na
me
ivad
min
_gro
up
_get
()P
DG
rou
pco
nstr
ucto
rpd
admi
ngr
oup
show
grou
p_na
me
ivad
min
_gro
up
_get
byd
n()
PD
Gro
up
cons
truc
tor
pdad
min
grou
psh
ow-d
ndn
ivad
min
_gro
up
_get
cn()
Will
not
besu
ppor
ted
.pd
admi
ngr
oup
show
grou
p_na
me
ivad
min
_gro
up
_get
des
crip
tion
()P
DG
roup
obje
ct.g
etD
escr
ipti
onpd
admi
ngr
oup
show
grou
p_na
me
Appendix C. Administration C API, Java method, and command line equivalents 297
Tabl
e39
.M
appi
ngbe
twee
nad
min
istr
atio
nC
AP
I,Ja
vam
etho
ds,
and
the
com
man
dlin
ein
terf
ace
(con
tinue
d)
CA
PI
Java
Cla
ssan
dM
eth
odC
omm
and
Lin
eE
qu
ival
ent
ivad
min
_gro
up
_get
dn
()P
DG
roup
obje
ct.g
etR
gyN
ame
pdad
min
grou
psh
owgr
oup_
name
ivad
min
_gro
up
_get
id()
PD
Gro
upob
ject
.get
Idpd
admi
ngr
oup
show
grou
p_na
me
ivad
min
_gro
up
_get
mem
ber
s()
PD
Gro
upob
ject
.get
Mem
ber
spd
admi
ngr
oup
show
-mem
bers
grou
p_na
me
ivad
min
_gro
up
_im
por
t2()
PD
Gro
up
.imp
ortG
rou
ppd
admi
ngr
oup
impo
rtgr
oup_
name
dn
ivad
min
_gro
up
_lis
t()
PD
Gro
up
.list
Gro
up
spd
admi
ngr
oup
list
patt
ern
max_
retu
rn
ivad
min
_gro
up
_lis
tbyd
n()
PD
Gro
up
.list
Gro
up
spd
admi
ngr
oup
list
-dn
patt
ern
max_
retu
rn
ivad
min
_gro
up
_rem
ovem
emb
ers(
)P
DG
rou
p.r
emov
eMem
ber
sP
DG
roup
obje
ct.r
emov
eMem
ber
spd
admi
ngr
oup
modi
fygr
oup_
name
remo
ve(u
ser_
name
1us
er_n
ame2
...)
ivad
min
_gro
up
_set
des
crip
tion
()P
DG
rou
p.s
etD
escr
ipti
onP
DG
roup
obje
ct.s
etD
escr
ipti
onpd
admi
ngr
oup
modi
fygr
oup_
name
desc
ript
ion
desc
ript
ion
ivad
min
_ob
ject
spac
e_cr
eate
()P
DP
rotO
bje
ctS
pac
e.cr
eate
Pro
tOb
ject
Sp
ace
pdad
min
obje
ctsp
ace
crea
teob
ject
spac
e_na
me
ivad
min
_ob
ject
spac
e_d
elet
e()
PD
Pro
tOb
ject
Sp
ace.
del
eteP
rotO
bje
ctS
pac
epd
admi
nob
ject
spac
ede
lete
obje
ctsp
ace_
name
ivad
min
_ob
ject
spac
e_li
st()
PD
Pro
tOb
ject
Sp
ace.
list
Pro
tOb
ject
Sp
aces
pdad
min
obje
ctsp
ace
list
ivad
min
_pop
_att
ach
()P
DP
rotO
bje
ct.a
ttac
hP
opP
DP
rotO
bjec
tob
ject
.att
ach
Pop
pdad
min
pop
atta
chob
ject
_nam
epo
p_na
me
ivad
min
_pop
_att
rdel
key
()P
DP
op.d
elet
eAtt
rib
ute
PD
Pop
obje
ct.d
elet
eAtt
rib
ute
pdad
min
pop
modi
fypo
p_na
mede
lete
attr
ibut
eat
trib
ute_
name
ivad
min
_pop
_att
rdel
val(
)P
DP
op.d
elet
eAtt
rib
ute
Val
ue
PD
Pop
obje
ct.d
elet
eAtt
rib
ute
Val
ue
pdad
min
pop
modi
fypo
p_na
mede
lete
attr
ibut
eat
trib
ute_
name
attr
ibut
e_va
lue
ivad
min
_pop
_att
rget
()P
DP
opob
ject
.get
Att
rib
ute
Val
ues
pdad
min
pop
show
pop_
name
attr
ibut
e
ivad
min
_pop
_att
rlis
t()
PD
Pop
obje
ct.g
etA
ttri
bu
teN
ames
pdad
min
pop
list
pop_
name
attr
ibut
e
ivad
min
_pop
_att
rpu
t()
PD
Pop
.set
Att
rib
ute
Val
ue
PD
Pop
obje
ct.s
etA
ttri
bu
teV
alu
epd
admi
npo
pmo
dify
pop_
name
set
attr
ibut
eat
trib
ute_
name
attr
ibut
e_va
lue
ivad
min
_pop
_cre
ate(
)P
DP
op.c
reat
ePop
pdad
min
pop
crea
tepo
p_na
me
ivad
min
_pop
_del
ete(
)P
DP
op.d
elet
ePop
pdad
min
pop
dele
tepo
p_na
me
ivad
min
_pop
_det
ach
()P
DP
rotO
bje
ct.d
etac
hP
opP
DP
rotO
bjec
tob
ject
.att
ach
Pop
pdad
min
pop
deta
chpo
p_na
me
ivad
min
_pop
_fin
d()
PD
Pro
tOb
ject
.list
Pro
tOb
ject
sByP
oppd
admi
npo
pfi
ndpo
p_na
me
ivad
min
_pop
_get
()P
DP
opco
nstr
ucto
rpd
admi
npo
psh
owpo
p_na
me
ivad
min
_pop
_get
aud
itle
vel(
)P
DP
opob
ject
.get
Au
dit
Lev
elpd
admi
npo
psh
owpo
p_na
me
298 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Tabl
e39
.M
appi
ngbe
twee
nad
min
istr
atio
nC
AP
I,Ja
vam
etho
ds,
and
the
com
man
dlin
ein
terf
ace
(con
tinue
d)
CA
PI
Java
Cla
ssan
dM
eth
odC
omm
and
Lin
eE
qu
ival
ent
ivad
min
_pop
_get
des
crip
tion
()P
DP
opob
ject
.get
Des
crip
tion
pdad
min
pop
show
pop_
name
ivad
min
_pop
_get
id()
PD
Pop
obje
ct.g
etId
pdad
min
pop
show
pop_
name
ivad
min
_pop
_get
qop
()P
DP
opob
ject
.get
QO
Ppd
admi
npo
psh
owpo
p_na
me
ivad
min
_pop
_get
tod
()P
DP
opob
ject
.get
Tod
Acc
essI
nfo
pdad
min
pop
show
pop_
name
ivad
min
_pop
_get
war
nm
ode(
)P
DP
opob
ject
.get
War
nin
gMod
epd
admi
npo
psh
owpo
p_na
me
ivad
min
_pop
_lis
t()
PD
Pop
.list
Pop
spd
admi
npo
pli
st
ivad
min
_pop
_rem
ovei
pau
th()
PD
Pop
.rem
oveI
PAu
thIn
foP
DP
opob
ject
.rem
oveI
PAu
thIn
fopd
admi
npo
pmo
dify
pop_
name
set
ipau
thre
move
netw
ork
netm
ask
ivad
min
_pop
_set
anyo
ther
nw
()P
DP
op.s
etu
thIn
fopd
admi
npo
pmo
dify
pop_
name
set
ipau
than
yoth
ernw
auth
enti
cati
on_l
evel
ivad
min
_pop
_set
anyo
ther
nw
_for
bid
den
()P
DP
op.s
etIP
Au
thIn
fopd
admi
npo
pmo
dify
pop_
name
set
ipau
than
yoth
ernw
forb
idde
n
ivad
min
_pop
_set
aud
itle
vel(
)P
DP
op.s
etA
ud
itL
evel
PD
Pop
obje
ct.s
etA
ud
itL
evel
pdad
min
pop
modi
fypo
p_na
mese
tau
dit-
leve
l[a
ll|
none
|au
dit_
leve
l_li
st]
ivad
min
_pop
_set
des
crip
tion
()P
DP
op.s
etD
escr
ipti
onP
DP
opob
ject
.set
Des
crip
tion
pdad
min
pop
modi
fypo
p_na
mese
tde
scri
ptio
nde
scri
ptio
n
ivad
min
_pop
_set
ipau
th()
PD
Pop
.set
IPA
uth
Info
PD
Pop
obje
ct.s
etIP
Au
thIn
fopd
admi
npo
pmo
dify
pop_
name
set
ipau
thad
dne
twor
kne
tmas
kau
then
tica
tion
_lev
el
ivad
min
_pop
_set
ipau
th_f
orb
idd
en()
PD
Pop
.set
IPA
uth
Info
PD
Pop
obje
ct.s
etIP
Au
thIn
fopd
admi
npo
pmo
dify
pop_
name
set
ipau
thad
dne
twor
kne
tmas
kfo
rbid
den
ivad
min
_pop
_set
qop
()P
DP
op.s
etQ
OP
PD
Pop
obje
ct.s
etQ
OP
pdad
min
pop
modi
fypo
p_na
mese
tqo
p[n
one
|in
tegr
ity
|pr
ivac
y]
ivad
min
_pop
_set
tod
()P
DP
op.s
etTo
dA
cces
sIn
foP
DP
opob
ject
.set
Tod
Acc
essI
nfo
.
pdad
min
pop
modi
fypo
p_na
mese
tto
d-ac
cess
tod_
valu
e
ivad
min
_pop
_set
war
nm
ode(
)P
DP
op.s
etW
arn
ingM
ode
PD
Pop
obje
ct.s
etW
arn
ingM
ode
pdad
min
pop
modi
fypo
p_na
mese
twa
rnin
g[
on|
off
]
ivad
min
_pro
tob
j_at
tach
acl(
)P
DP
rotO
bje
ct.a
ttac
hA
clP
DP
rotO
bjec
tob
ject
.att
ach
Acl
pdad
min
acl
atta
chob
ject
_nam
eac
l_na
me
ivad
min
_pro
tob
j_at
trd
elk
ey()
PD
Pro
tOb
ject
.del
eteA
ttri
bu
teP
DP
rotO
bjec
tob
ject
.del
eteA
ttri
bu
tepd
admi
nob
ject
modi
fyob
ject
_nam
ede
lete
attr
ibut
e_na
me
Appendix C. Administration C API, Java method, and command line equivalents 299
Tabl
e39
.M
appi
ngbe
twee
nad
min
istr
atio
nC
AP
I,Ja
vam
etho
ds,
and
the
com
man
dlin
ein
terf
ace
(con
tinue
d)
CA
PI
Java
Cla
ssan
dM
eth
odC
omm
and
Lin
eE
qu
ival
ent
ivad
min
_pro
tob
j_at
trd
elva
l()
PD
Pro
tOb
ject
.del
eteA
ttri
bu
teV
alu
eP
DP
rotO
bjec
tob
ject
.del
eteA
ttri
bu
teV
alu
epd
admi
nob
ject
modi
fyob
ject
_nam
ede
lete
attr
ibut
e_na
meat
trib
ute_
valu
e
ivad
min
_pro
tob
j_at
trge
t()
PD
Pro
tObj
ect
obje
ct.g
etA
ttri
bu
teV
alu
espd
admi
nob
ject
show
obje
ct_n
ame
attr
ibut
eat
trib
ute_
name
ivad
min
_pro
tob
j_at
trli
st()
PD
Pro
tObj
ect
obje
ct.g
etA
ttri
bu
teN
ames
pdad
min
obje
ctli
stob
ject
_nam
eat
trib
ute
ivad
min
_pro
tob
j_at
trp
ut(
)P
DP
rotO
bje
ct.s
etA
ttri
bu
teV
alu
eP
DP
rotO
bjec
tob
ject
.set
Att
rib
ute
Val
ue
pdad
min
obje
ctmo
dify
obje
ct_n
ame
set
attr
ibut
eat
trib
ute_
name
attr
ibut
e_va
lue
ivad
min
_pro
tob
j_cr
eate
()P
DP
rotO
bje
ct.c
reat
ePro
tOb
ject
pdad
min
obje
ctcr
eate
obje
ct_n
ame
ivad
min
_pro
tob
j_d
elet
e()
PD
Pro
tOb
ject
.del
eteP
rotO
bje
ctpd
admi
nob
ject
dele
teob
ject
_nam
e
ivad
min
_pro
tob
j_d
etac
hac
l()
PD
Pro
tOb
ject
.det
ach
Acl
PD
Pro
tObj
ect
obje
ct.d
etac
hA
clpd
admi
nac
lde
tach
obje
ct_n
ame
ivad
min
_pro
tob
j_ge
t2()
PD
Pro
tOb
ject
cons
truc
tor
pdad
min
obje
ctsh
owob
ject
_nam
e
ivad
min
_pro
tob
j_ge
tacl
()P
DP
rotO
bjec
tob
ject
.get
Acl
pdad
min
obje
ctsh
owob
ject
_nam
e
ivad
min
_pro
tob
j_ge
tdes
c()
PD
Pro
tObj
ect
obje
ct.g
etD
escr
ipti
onpd
admi
nob
ject
show
obje
ct_n
ame
ivad
min
_pro
tob
j_ge
tid
()P
DP
rotO
bjec
tob
ject
.get
Idpd
admi
nob
ject
show
obje
ct_n
ame
ivad
min
_pro
tob
j_ge
tpol
icya
ttac
hab
le()
PD
Pro
tObj
ect
obje
ct.is
Pol
icyA
ttac
hab
lepd
admi
nob
ject
show
obje
ct_n
ame
ivad
min
_pro
tob
j_ge
tpop
()N
otsu
ppor
ted
atth
isti
me.
not
appl
icab
le
ivad
min
_pro
tob
j_ge
ttyp
e()
Will
not
besu
ppor
ted
.pd
admi
nob
ject
show
obje
ct_n
ame
ivad
min
_pro
tob
j_li
st3(
)P
DP
rotO
bje
ct.li
stP
rotO
bje
cts
pdad
min
obje
ctli
stdi
rect
ory_
name
ivad
min
_pro
tob
j_li
stb
yacl
()P
DP
rotO
bje
ct.li
stP
rotO
bje
ctsB
yAcl
pdad
min
acl
find
acl_
name
ivad
min
_pro
tob
j_se
tdes
c()
PD
Pro
tOb
ject
.set
Des
crip
tion
PD
Pro
tObj
ect
obje
ct.s
etD
escr
ipti
onpd
admi
nob
ject
modi
fyob
ject
_nam
ede
scri
ptio
nde
scri
ptio
n
ivad
min
_pro
tob
j_se
tnam
e()
Will
not
besu
ppor
ted
.pd
admi
nob
ject
modi
fyob
ject
_nam
ena
mena
meco
nfli
ct_r
esol
utio
nre
solu
tion
_mod
ifie
r
ivad
min
_pro
tob
j_se
tpol
icya
ttac
hab
le()
PD
Pro
tOb
ject
.set
Pol
icyA
ttac
hab
leP
DP
rotO
bjec
tob
ject
.set
Pol
icyA
ttac
hab
lepd
admi
nob
ject
modi
fyob
ject
_nam
eis
Poli
cyAt
tach
able
[yes
|no
]
ivad
min
_pro
tob
j_se
ttyp
e()
Will
not
besu
ppor
ted
.pd
admi
nob
ject
modi
fyob
ject
_nam
ety
pety
pe
ivad
min
_res
pon
se_g
etco
de(
)no
tap
plic
able
not
appl
icab
le
ivad
min
_res
pon
se_g
etco
un
t()
not
appl
icab
leno
tap
plic
able
ivad
min
_res
pon
se_g
etm
essa
ge()
not
appl
icab
leno
tap
plic
able
300 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Tabl
e39
.M
appi
ngbe
twee
nad
min
istr
atio
nC
AP
I,Ja
vam
etho
ds,
and
the
com
man
dlin
ein
terf
ace
(con
tinue
d)
CA
PI
Java
Cla
ssan
dM
eth
odC
omm
and
Lin
eE
qu
ival
ent
ivad
min
_res
pon
se_g
etm
odif
ier(
)no
tap
plic
able
not
appl
icab
le
ivad
min
_res
pon
se_g
etok
()no
tap
plic
able
not
appl
icab
le
ivad
min
_ser
ver_
gett
ask
list
()P
DS
erve
r.get
Task
Lis
tpd
admi
nse
rver
list
task
sse
rver
_nam
e
ivad
min
_ser
ver_
per
form
task
()P
DS
erve
r.per
form
Task
pdad
min
serv
erta
skse
rver
_nam
eta
sk_t
o_pe
rfor
m
ivad
min
_ser
ver_
rep
lica
te()
PD
Ser
ver.s
erve
rRep
lica
tepd
admi
nse
rver
repl
icat
ese
rver
_nam
e
ivad
min
_sso
cred
_cre
ate(
)P
DS
SO
Cre
d.c
reat
eSS
OC
red
pdad
min
rsrc
cred
crea
tere
sour
ce_n
ame
rsrc
user
reso
urce
_use
rid
rsrc
pwd
reso
urce
_pwd
rsrc
type
[web
|gr
oup]
user
user
_nam
e
ivad
min
_sso
cred
_del
ete(
)P
DS
SO
Cre
d.d
elet
eSS
OC
red
pdad
min
rsrc
cred
dele
tere
sour
ce_n
ame
rsrc
type
[web
|gr
oup]
user
user
_nam
e
ivad
min
_sso
cred
_get
()P
DS
SO
Cre
dco
nstr
ucto
rpd
admi
nrs
rccr
edsh
owre
sour
ce_n
ame
rsrc
type
[web
|gr
oup]
user
user
_nam
e
ivad
min
_sso
cred
_get
id()
PD
SSO
Cre
dob
ject
.get
Res
ourc
eNam
epd
admi
nrs
rccr
edsh
owre
sour
ce_n
ame
rsrc
type
[web
|gr
oup]
user
user
_nam
e
ivad
min
_sso
cred
_get
ssop
assw
ord
()P
DSS
OC
red
obje
ct.g
etR
esou
rceP
assw
ord
not
appl
icab
le
ivad
min
_sso
cred
_get
ssou
ser(
)P
DSS
OC
red
obje
ct.g
etR
esou
rceU
ser
not
appl
icab
le
ivad
min
_sso
cred
_get
typ
e()
PD
SSO
Cre
dob
ject
.get
Res
ourc
eTyp
epd
admi
nrs
rccr
edsh
owre
sour
ce_n
ame
rsrc
type
[web
|gr
oup]
user
user
_nam
e
ivad
min
_sso
cred
_get
use
r()
PD
SSO
Cre
dob
ject
.get
Use
rpd
admi
nrs
rccr
edsh
owre
sour
ce_n
ame
rsrc
type
[web
|gr
oup]
user
user
_nam
e
ivad
min
_sso
cred
_lis
t()
PD
SSO
Cre
dob
ject
.list
An
dS
how
SS
OC
red
sP
DSS
OC
red
obje
ct.li
stS
SO
Cre
ds
pdad
min
rsrc
cred
list
user
user
_nam
e
ivad
min
_sso
cred
_set
()P
DS
SO
Cre
d.s
etS
SO
Cre
dP
DSS
OC
red
obje
ct.s
etS
SO
Cre
d.
pdad
min
rsrc
cred
modi
fyre
sour
ce_n
ame
rsrc
type
[web
|gr
oup]
[-rs
rcus
erre
sour
ce_u
seri
d][-
rsrc
pwd
reso
urce
_pwd
]us
erus
er_n
ame
ivad
min
_sso
grou
p_a
dd
res(
)P
DS
SO
Res
ourc
eGro
up
.ad
dS
SO
Res
ourc
eP
DSS
OR
esou
rceG
roup
.ad
dS
SO
Res
ourc
epd
admi
nrs
rcgr
oup
modi
fyre
sour
ce_g
roup
_nam
ead
drs
rcna
mere
sour
ce_n
ame
ivad
min
_sso
grou
p_c
reat
e()
PD
SS
OR
esou
rceG
rou
p.c
reat
eSS
OR
esou
rceG
rou
ppd
admi
nrs
rcgr
oup
crea
tere
sour
ce_g
roup
_nam
e[-
desc
desc
ript
ion]
ivad
min
_sso
grou
p_d
elet
e()
PD
SS
OR
esou
rceG
rou
p.d
elet
eSS
OR
esou
rceG
rou
ppd
admi
nrs
rcgr
oup
dele
tere
sour
ce_g
roup
_nam
e
ivad
min
_sso
grou
p_g
et()
PD
SS
OR
esou
rceG
rou
pco
nstr
ucto
rpd
admi
nrs
rcgr
oup
show
reso
urce
_gro
up_n
ame
Appendix C. Administration C API, Java method, and command line equivalents 301
Tabl
e39
.M
appi
ngbe
twee
nad
min
istr
atio
nC
AP
I,Ja
vam
etho
ds,
and
the
com
man
dlin
ein
terf
ace
(con
tinue
d)
CA
PI
Java
Cla
ssan
dM
eth
odC
omm
and
Lin
eE
qu
ival
ent
ivad
min
_sso
grou
p_g
etd
escr
ipti
on()
PD
SSO
Cre
dob
ject
.get
Des
crip
tion
pdad
min
rsrc
grou
psh
owre
sour
ce_g
roup
_nam
e
ivad
min
_sso
grou
p_g
etid
()P
DSS
OC
red
obje
ct.g
etId
pdad
min
rsrc
grou
psh
owre
sour
ce_g
roup
_nam
e
ivad
min
_sso
grou
p_g
etre
sou
rces
()P
DSS
OC
red
obje
ct.g
etS
SO
Res
ourc
espd
admi
nrs
rcgr
oup
show
reso
urce
_gro
up_n
ame
ivad
min
_sso
grou
p_l
ist(
)P
DS
SO
Cre
d.li
stS
SO
Res
ourc
eGro
up
spd
admi
nrs
rcgr
oup
list
ivad
min
_sso
grou
p_r
emov
eres
()P
DS
SO
Cre
d.r
emov
eSS
OR
esou
rce
PD
SSO
Cre
dob
ject
.rem
oveS
SO
Res
ourc
e.pd
admi
nrs
rcgr
oup
modi
fyre
sour
ce_g
roup
_nam
ere
move
rsrc
name
reso
urce
_nam
e
ivad
min
_sso
web
_cre
ate(
)P
DS
SO
Res
ourc
e.cr
eate
SS
OR
esou
rce
pdad
min
rsrc
crea
tere
sour
ce_n
ame
[-de
scde
scri
ptio
n]
ivad
min
_sso
web
_del
ete(
)P
DS
SO
Res
ourc
e.d
elet
eSS
OR
esou
rce
pdad
min
rsrc
dele
tere
sour
ce_n
ame
ivad
min
_sso
web
_get
()P
DS
SO
Res
ourc
eon
stru
ctor
pdad
min
rsrc
show
reso
urce
_nam
e
ivad
min
_sso
web
_get
des
crip
tion
()P
DSS
OR
esou
rce
obje
ct.g
etD
escr
ipti
onpd
admi
nrs
rcsh
owre
sour
ce_n
ame
ivad
min
_sso
web
_get
id()
PD
SSO
Res
ourc
eob
ject
.get
Idpd
admi
nrs
rcsh
owre
sour
ce_n
ame
ivad
min
_sso
web
_lis
t()
PD
SS
OR
esou
rce.
list
SS
OR
esou
rces
pdad
min
rsrc
list
ivad
min
_use
r_cr
eate
3()
PD
Use
r.cre
ateU
ser
pdad
min
user
crea
te[-
gsou
ser]
[-no
-pas
swor
d-po
licy
]us
er_n
ame
dncn
snpw
d(
grou
p1gr
oup2
....
)
ivad
min
_use
r_d
elet
e2()
PD
Use
r.del
eteU
ser
pdad
min
user
dele
te[-
regi
stry
]us
er_n
ame
ivad
min
_use
r_ge
t()
PD
Use
rco
nstr
ucto
rpd
admi
nus
ersh
owus
er_n
ame
ivad
min
_use
r_ge
tacc
exp
dat
e()
PD
Pol
icy
obje
ct.g
etA
cctE
xpD
ate
pdad
min
user
get
acco
unt-
expi
ry-d
ate
[-us
erus
er_n
ame
]
ivad
min
_use
r_ge
tacc
oun
tval
id()
PD
Use
rob
ject
.isA
ccou
ntV
alid
pdad
min
user
show
user
_nam
e
ivad
min
_use
r_ge
tbyd
n()
PD
Use
rco
nstr
ucto
rpd
admi
nus
ersh
ow-d
ndn
ivad
min
_use
r_ge
tcn
()P
DU
ser
obje
ct.g
etFi
rstN
ame
pdad
min
user
show
user
_nam
e
ivad
min
_use
r_ge
tdes
crip
tion
()P
DU
ser
obje
ct.g
etD
escr
ipti
onpd
admi
nus
ersh
owus
er_n
ame
ivad
min
_use
r_ge
tdis
able
tim
ein
t()
PD
Pol
icy
obje
ct.g
etA
cctD
isab
leT
imeI
nte
rval
pdad
min
poli
cyge
tdi
sabl
e-ti
me-i
nter
val
[-us
erus
er_n
ame]
ivad
min
_use
r_ge
tdn
()P
DU
ser
obje
ct.g
etR
gyN
ame
pdad
min
user
show
user
_nam
e
ivad
min
_use
r_ge
tid
()P
DU
ser
obje
ct.g
etId
pdad
min
user
show
user
_nam
e
ivad
min
_use
r_ge
tmax
lgn
fail
s()
PD
Pol
icy
obje
ct.g
etM
axFa
iled
Log
ins
pdad
min
poli
cyge
tma
x-lo
gin-
fail
ures
[-us
erus
er_n
ame]
302 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Tabl
e39
.M
appi
ngbe
twee
nad
min
istr
atio
nC
AP
I,Ja
vam
etho
ds,
and
the
com
man
dlin
ein
terf
ace
(con
tinue
d)
CA
PI
Java
Cla
ssan
dM
eth
odC
omm
and
Lin
eE
qu
ival
ent
ivad
min
_use
r_ge
tmax
pw
dag
e()
PD
Pol
icy
obje
ct.g
etM
axP
wd
Age
pdad
min
poli
cyge
tma
x-pa
sswo
rd-a
ge[-
user
user
_nam
e]
ivad
min
_use
r_ge
tmax
pw
dre
pch
ars(
)P
DP
olic
yob
ject
.get
Max
Pw
dR
epC
har
spd
admi
npo
licy
get
max-
pass
word
-rep
eate
d-ch
ars
[-us
erus
er_n
ame]
ivad
min
_use
r_ge
tmem
ber
ship
s()
PD
Use
rob
ject
.get
Gro
up
spd
admi
nus
ersh
ow-g
roup
sus
er_n
ame
ivad
min
_use
r_ge
tmin
pw
dal
ph
as()
PD
Pol
icy
obje
ct.g
etM
inP
wd
Alp
has
pdad
min
poli
cyge
tmi
n-pa
sswo
rd-a
lpha
s[-
user
user
_nam
e]
ivad
min
_use
r_ge
tmin
pw
dle
n()
PD
Pol
icy
obje
ct.g
etM
inP
wd
Len
pdad
min
poli
cyge
tmi
n-pa
sswo
rd-l
engt
h[-
user
user
_nam
e]
ivad
min
_use
r_ge
tmin
pw
dn
onal
ph
as()
PD
Pol
icy
obje
ct.g
etM
inP
wd
Non
Alp
has
pdad
min
poli
cyge
tmi
n-pa
sswo
rd-n
on-a
lpha
s[-
user
user
_nam
e]
ivad
min
_use
r_ge
tpas
swor
dva
lid
()P
DU
ser
obje
ct.is
Pas
swor
dV
alid
pdad
min
user
show
user
_nam
e
ivad
min
_use
r_ge
tpw
dsp
aces
()P
DP
olic
yob
ject
.pw
dS
pac
esA
llow
edpd
admi
npo
licy
get
pass
word
-spa
ces
[-us
erus
er_n
ame]
ivad
min
_use
r_ge
tsn
()P
DU
ser
obje
ct.g
etL
astN
ame
pdad
min
user
show
user
_nam
e
ivad
min
_use
r_ge
tsso
use
r()
PD
Use
rob
ject
.isS
SO
Use
rpd
admi
nus
ersh
owus
er_n
ame
ivad
min
_use
r_ge
ttod
acce
ss()
PD
Pol
icy
obje
ct.g
etA
cces
sib
leD
ays
PD
Pol
icy
obje
ct.g
etA
cces
sSta
rtT
ime
PD
Pol
icy
obje
ct.g
etA
cces
sEn
dT
ime
pdad
min
poli
cyge
tto
d-ac
cess
-use
rus
er_n
ame
ivad
min
_use
r_im
por
t2()
PD
Use
r.im
por
tUse
rpd
admi
nus
erim
port
[-gs
ouse
r]us
er_n
ame
dn
ivad
min
_use
r_li
st()
PD
Use
r.lis
tUse
rspd
admi
nus
erli
stpa
tter
nma
x_re
turn
ivad
min
_use
r_li
stb
ydn
()P
DU
ser.l
istU
sers
pdad
min
user
list
-dn
patt
ern
max_
retu
rn
ivad
min
_use
r_se
tacc
exp
dat
e()
PD
Pol
icy.
setA
cctE
xpD
ate
PD
Pol
icy
obje
ct.s
etA
cctE
xpD
ate
pdad
min
poli
cyse
tac
coun
t-ex
piry
-dat
e[u
nlim
ited
|ab
solu
te_t
ime
|un
set]
[-us
erus
er_n
ame]
ivad
min
_use
r_se
tacc
oun
tval
id()
PD
Use
r.set
Acc
oun
tVal
idP
DU
ser
obje
ct.s
etA
ccou
ntV
alid
pdad
min
user
modi
fyus
er_n
ame
acco
unt-
vali
d[y
es|
no]
ivad
min
_use
r_se
tdes
crip
tion
()P
DU
ser.s
etD
escr
ipti
onP
DU
ser
obje
ct.s
etD
escr
ipti
onpd
admi
nus
ermo
dify
user
_nam
ede
scri
ptio
nde
scri
ptio
n
ivad
min
_use
r_se
tdis
able
tim
ein
t()
PD
Pol
icy.
setA
cctD
isab
leT
ime
PD
Pol
icy
obje
ct.s
etA
cctD
isab
leT
ime
pdad
min
poli
cyse
tdi
sabl
e-ti
me-i
nter
val
[num
ber
|un
set
|di
sabl
e][-
user
user
_nam
e]
Appendix C. Administration C API, Java method, and command line equivalents 303
Tabl
e39
.M
appi
ngbe
twee
nad
min
istr
atio
nC
AP
I,Ja
vam
etho
ds,
and
the
com
man
dlin
ein
terf
ace
(con
tinue
d)
CA
PI
Java
Cla
ssan
dM
eth
odC
omm
and
Lin
eE
qu
ival
ent
ivad
min
_use
r_se
tmax
lgn
fail
s()
PD
Pol
icy.
setM
axFa
iled
Log
ins
PD
Pol
icy
obje
ct.s
etM
axFa
iled
Log
ins
pdad
min
poli
cyse
tma
x-lo
gin-
fail
ures
[num
ber
|un
set]
[-us
erus
er_n
ame]
ivad
min
_use
r_se
tmax
pw
dag
e()
PD
Pol
icy.
setM
axP
wd
Age
PD
Pol
icy
obje
ct.s
etM
axP
wd
Age
pdad
min
poli
cyse
tma
x-pa
sswo
rd-a
ge[u
nset
|re
lati
ve_t
ime]
[-us
erus
er_n
ame]
ivad
min
_use
r_se
tmax
pw
dre
pch
ars(
)P
DP
olic
y.se
tMax
Pw
dR
epC
har
sP
DP
olic
yob
ject
.set
Max
Pw
dR
epC
har
spd
admi
npo
licy
set
max-
pass
word
-rep
eate
d-ch
ars
[num
ber
|un
set]
[-us
erus
er_n
ame]
ivad
min
_use
r_se
tmin
pw
dal
ph
as()
PD
Pol
icy.
setM
inP
wd
Alp
has
PD
Pol
icy
obje
ct.s
etM
inP
wd
Alp
has
pdad
min
poli
cyse
tmi
n-pa
sswo
rd-a
lpha
s[n
umbe
r|
unse
t][-
user
user
_nam
e]
ivad
min
_use
r_se
tmin
pw
dle
n()
PD
Pol
icy.
setM
inP
wd
Len
PD
Pol
icy
obje
ct.s
etM
inP
wd
Len
pdad
min
poli
cyse
tmi
n-pa
sswo
rd-l
engt
h[n
umbe
r|
unse
t][-
user
user
_nam
e]
ivad
min
_use
r_se
tmin
pw
dn
onal
ph
as()
PD
Pol
icy.
setM
inP
wd
Non
Alp
has
PD
Pol
icy
obje
ct.s
etM
inP
wd
Non
Alp
has
pdad
min
poli
cyse
tmi
n-pa
sswo
rd-n
on-a
lpha
s[n
umbe
r|
unse
t][-
user
user
_nam
e]
ivad
min
_use
r_se
tpas
swor
d()
PD
Use
r.set
Pas
swor
dP
DU
ser
obje
ct.s
etP
assw
ord
pdad
min
user
modi
fyus
er_n
ame
pass
word
pass
word
ivad
min
_use
r_se
tpas
swor
dva
lid
()P
DU
ser.s
etP
assw
ord
Val
idP
DU
ser
obje
ct.s
etP
assw
ord
Val
idpd
admi
nus
ermo
dify
user
_nam
epa
sswo
rd-v
alid
[yes
|no
]
ivad
min
_use
r_se
tpw
dsp
aces
()P
DP
olic
y.se
tPw
dS
pac
esA
llow
edP
DP
olic
yob
ject
.set
Pw
dS
pac
esA
llow
edpd
admi
npo
licy
set
pass
word
-spa
ces
[yes
|no
|un
set]
[-us
erus
er_n
ame]
ivad
min
_use
r_se
tsso
use
r()
PD
Use
r.set
SS
OU
ser
PD
Use
rob
ject
.set
SS
OU
ser
pdad
min
user
modi
fyus
er_n
ame
gsou
ser
[yes
|no
]
ivad
min
_use
r_se
ttod
acce
ss()
PD
Pol
icy.
setT
odA
cces
sP
DP
olic
yob
ject
.set
Tod
Acc
ess
pdad
min
poli
cyse
tto
d-ac
cess
tod_
valu
e-u
ser
user
_nam
e
304 IBM Tivoli Access Manager: Administration C API Developer’s Reference
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 CorporationNorth Castle DriveArmonk, NY 10504-1785U.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-0032, 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.
© Copyright IBM Corp. 2000, 2003 305
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 78758U.S.A.
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.
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, whichillustrate 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.
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:
306 IBM Tivoli Access Manager: Administration C API Developer’s Reference
AIXDB2IBMIBM logoOS/390SecureWayTivoliTivoli logoUniversal DatabaseWebSpherez/OSzSeries
Lotus is a registered trademark of Lotus Development Corporation and/or IBMCorporation.
Domino is a trademark of International Business Machines Corporation and LotusDevelopment Corporation in the United States, other countries, or both.
Microsoft and Windows are trademarks of Microsoft Corporation in the UnitedStates, 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 307
308 IBM Tivoli Access Manager: Administration C API Developer’s Reference
Index
Aaccess control list entries, table 29access control list entry types 28access control lists, table 28account functions, table 19accounts 18action group functions, table 30, 31action groups
overview 30adding development systems 4ADK 3ADK component 3administration API
compilers supported 4installing 3shared libraries 2
administration tasks 43any-authenticated 28any-other 28API differences 293application developer kit (ADK) 3application development kit (ADK) 3application, deploying 5applications, building 3audit log 34audit records 34azn_creds_get_pac() function 9
Bbuilding applications 3
Ccleanup of the Administration API 15commands, pdadmin 2commands, svrsslcfg 2compilers tested 4components 2constants
deprecated 287container objects 24creating LDAP users 9creating objects 9creating objects, example 10creating Privilege Attribute Certificate data 9creating protected objects 191
Ddelegating user credentials 8deleting a security context 16demonstration program 4deploying an application 5deprecated constants 287deprecated functions 287
ivadmin_cfg_configureserver() 287ivadmin_group_addmember() 287ivadmin_group_create() 287
deprecated functions (continued)ivadmin_group_delete() 287ivadmin_group_import() 287ivadmin_group_removemember() 287ivadmin_protobj_get() 287ivadmin_protobj_list2() 287ivadmin_user_create() 287ivadmin_user_create2() 287ivadmin_user_delete() 287ivadmin_user_getauthmech () 287ivadmin_user_import() 287ivadmin_user_setauthmech () 287
detecting errors 13development systems, adding 4
Eerror codes 14error conditions 10error message modifiers 15error messages, text 14errors, detecting 13establishing security contexts 7examples
creating objects 10functions that read values 11ivadmin_context_delete() 16modifying the maximum password age 10program 4returned data types 11set operations 10setting account expiration dates 10
extended action functions, table 31extended actions, overview 31
Ffiles, installation directories 3freeing memory 15functions
azn_creds_get_pac() 9deprecated 287ivadmin_acl_attrdelkey() 48ivadmin_acl_attrdelval() 49ivadmin_acl_attrget() 50ivadmin_acl_attrlist() 51ivadmin_acl_attrput() 52ivadmin_acl_create() 53ivadmin_acl_delete() 54ivadmin_acl_get() 55ivadmin_acl_getanyother() 56ivadmin_acl_getdescription() 57ivadmin_acl_getgroup() 58ivadmin_acl_getid() 59ivadmin_acl_getunauth() 60ivadmin_acl_getuser() 61ivadmin_acl_list() 62ivadmin_acl_listgroups() 63ivadmin_acl_listusers() 64ivadmin_acl_removeanyother() 65
© Copyright IBM Corp. 2000, 2003 309
functions (continued)ivadmin_acl_removegroup() 66ivadmin_acl_removeunauth() 67ivadmin_acl_removeuser() 68ivadmin_acl_setanyother() 69ivadmin_acl_setdescription() 71ivadmin_acl_setgroup() 72ivadmin_acl_setunauth() 74ivadmin_acl_setuser() 76ivadmin_action_create_in_group() 80ivadmin_action_create() 78ivadmin_action_delete_from_group() 83ivadmin_action_delete() 82ivadmin_action_getdescription 84ivadmin_action_getid() 85ivadmin_action_gettype() 86ivadmin_action_group_create() 87ivadmin_action_group_delete() 88ivadmin_action_group_list() 89ivadmin_action_list_in_group() 91ivadmin_action_list() 90ivadmin_cfg_addreplica() 92ivadmin_cfg_chgreplica() 93ivadmin_cfg_configureserver2() 94ivadmin_cfg_renewservercert() 96ivadmin_cfg_rmvreplica() 97ivadmin_cfg_setapplicationcert() 98ivadmin_cfg_setkeyringpwd() 99ivadmin_cfg_setlistening() 100ivadmin_cfg_setport() 101ivadmin_cfg_setssltimeout() 102ivadmin_cfg_unconfigureserver() 103ivadmin_context_cleardelcred() 104ivadmin_context_create() 8, 105ivadmin_context_createdefault 8ivadmin_context_createdefault() 7, 8, 107ivadmin_context_delete() 16, 108ivadmin_context_getaccexpdate() 109ivadmin_context_getdisabletimeint() 110ivadmin_context_getmaxlgnfails() 111ivadmin_context_getmaxpwdage() 112ivadmin_context_getmaxpwdrepchars() 113ivadmin_context_getminpwdalphas() 114ivadmin_context_getminpwdlen() 116ivadmin_context_getminpwdnonalphas() 115ivadmin_context_getpwdspaces() 117ivadmin_context_gettodaccess() 118ivadmin_context_getuserreg() 119ivadmin_context_setaccexpdate() 120ivadmin_context_setdelcred() 9, 121ivadmin_context_setdisabletimeint() 122ivadmin_context_setmaxlgnfails 123ivadmin_context_setmaxpwdage() 124ivadmin_context_setmaxpwdrepchars() 125ivadmin_context_setminpwdalphas() 126ivadmin_context_setminpwdlen() 128ivadmin_context_setminpwdnonalphas() 127ivadmin_context_settodaccess() 130ivadmin_free() 15, 131ivadmin_group_addmembers() 132ivadmin_group_create2() 133ivadmin_group_delete2() 135ivadmin_group_get() 136ivadmin_group_getbydn() 137ivadmin_group_getcn() 138ivadmin_group_getdescription() 139ivadmin_group_getdn 140
functions (continued)ivadmin_group_getid() 141ivadmin_group_getmembers() 142ivadmin_group_import2() 143ivadmin_group_list() 144ivadmin_group_listbydn() 145ivadmin_group_removemembers() 147ivadmin_group_setdescription() 148ivadmin_message_getcount() 15ivadmin_objectspace_create() 149ivadmin_objectspace_delete() 151ivadmin_objectspace_list() 152ivadmin_pop_attach() 153ivadmin_pop_attrdelkey() 154ivadmin_pop_attrdelval() 155ivadmin_pop_attrget() 156ivadmin_pop_attrlist() 157ivadmin_pop_attrput() 158ivadmin_pop_create() 159ivadmin_pop_delete() 160ivadmin_pop_detach() 161ivadmin_pop_find() 162ivadmin_pop_get() 163ivadmin_pop_getanyothernw() 164ivadmin_pop_getauditlevel() 165ivadmin_pop_getdescription() 166ivadmin_pop_getid() 167ivadmin_pop_getipauth() 168ivadmin_pop_getqop() 169ivadmin_pop_gettod() 170ivadmin_pop_getwarnmode() 172ivadmin_pop_list() 173ivadmin_pop_removeipauth() 174ivadmin_pop_setanyothernw_forbidden() 176ivadmin_pop_setanyothernw() 34, 175ivadmin_pop_setauditlevel() 177ivadmin_pop_setdescription() 178ivadmin_pop_setipauth_forbidden() 180ivadmin_pop_setipauth() 34, 179ivadmin_pop_setqop() 181ivadmin_pop_settod() 182ivadmin_pop_setwarnmode() 184ivadmin_protobj_attachacl() 185ivadmin_protobj_attrdelkey() 186ivadmin_protobj_attrdelval() 187ivadmin_protobj_attrget() 188ivadmin_protobj_attrlist() 189ivadmin_protobj_attrput() 190ivadmin_protobj_create() 191ivadmin_protobj_delete() 192ivadmin_protobj_detachacl() 193ivadmin_protobj_get2() 194ivadmin_protobj_getacl() 196ivadmin_protobj_getdesc() 197ivadmin_protobj_getid() 198ivadmin_protobj_getpolicyattachable() 199ivadmin_protobj_getpop() 200ivadmin_protobj_gettype() 201ivadmin_protobj_list3() 202ivadmin_protobj_listbyacl() 204ivadmin_protobj_setdesc() 205ivadmin_protobj_setname() 206ivadmin_protobj_setpolicyattachable() 207ivadmin_protobj_settype() 208ivadmin_response_getcode() 14, 209ivadmin_response_getcount() 14, 210ivadmin_response_getmessage() 14, 211
310 IBM Tivoli Access Manager: Administration C API Developer’s Reference
functions (continued)ivadmin_response_getmodifier() 15, 212ivadmin_response_getok() 13, 213ivadmin_server_gettasklist() 214ivadmin_server_performtask() 216ivadmin_server_replicate() 218ivadmin_ssocred_create() 219ivadmin_ssocred_delete() 220ivadmin_ssocred_get() 221ivadmin_ssocred_getid() 222ivadmin_ssocred_getssopassword() 223ivadmin_ssocred_getssouser() 224ivadmin_ssocred_gettype() 225ivadmin_ssocred_getuser() 226ivadmin_ssocred_list() 227ivadmin_ssocred_set() 228ivadmin_ssogroup_addres() 229ivadmin_ssogroup_create() 230ivadmin_ssogroup_delete() 231ivadmin_ssogroup_get() 232ivadmin_ssogroup_getdescription() 233ivadmin_ssogroup_getid() 234ivadmin_ssogroup_getresources() 235ivadmin_ssogroup_list() 236ivadmin_ssogroup_removeres() 237ivadmin_ssoweb_create() 238ivadmin_ssoweb_delete() 239ivadmin_ssoweb_get() 240ivadmin_ssoweb_getdescription() 241ivadmin_ssoweb_getid() 242ivadmin_ssoweb_list() 243ivadmin_user_create3() 9, 17, 244ivadmin_user_delete2() 17, 246ivadmin_user_get() 247ivadmin_user_getaccexpdate() 248ivadmin_user_getaccountvalid() 249ivadmin_user_getbydn() 250ivadmin_user_getcn() 251ivadmin_user_getdescription() 252ivadmin_user_getdisabletimeint() 253ivadmin_user_getdn() 254ivadmin_user_getid() 255ivadmin_user_getmaxlgnfails() 256ivadmin_user_getmaxpwdage() 257ivadmin_user_getmaxpwdrepchars() 258ivadmin_user_getmemberships() 259ivadmin_user_getminpwdalphas() 260ivadmin_user_getminpwdlen() 261ivadmin_user_getminpwdnonalphas() 262ivadmin_user_getpasswordvalid() 263ivadmin_user_getpwdspaces() 264ivadmin_user_getsn() 265ivadmin_user_getssouser() 266ivadmin_user_gettodaccess() 267ivadmin_user_import2() 268ivadmin_user_list() 12, 269ivadmin_user_listbydn() 271ivadmin_user_setaccexpdate() 10, 272ivadmin_user_setaccountvalid() 273ivadmin_user_setdescription() 274ivadmin_user_setdisabletimeint() 275ivadmin_user_setmaxlgnfails() 276ivadmin_user_setmaxpwdage() 10, 277ivadmin_user_setmaxpwdrepchars() 278ivadmin_user_setminpwdalphas() 279ivadmin_user_setminpwdlen() 280ivadmin_user_setminpwdnonalphas() 281
functions (continued)ivadmin_user_setpassword() 282ivadmin_user_setpasswordvalid() 283ivadmin_user_setpwdspaces() 284ivadmin_user_setssouser() 285ivadmin_user_settodaccess() 286
functions ivadmin_context_setpwdspaces() 129functions, deprecated
ivadmin_cfg_configureserver() 287ivadmin_group_addmember() 287ivadmin_group_create() 287ivadmin_group_delete() 287ivadmin_group_import() 287ivadmin_group_removemember() 287ivadmin_protobj_get() 287ivadmin_protobj_list2() 287ivadmin_user_create() 287ivadmin_user_create2() 287ivadmin_user_delete() 287ivadmin_user_getauthmech () 287ivadmin_user_import() 287ivadmin_user_setauthmech () 287
Ggetting administration tasks 43getting objects 11group attributes, table 21group functions, table 21groups
access control list entry type 28overview 17
IIBM Global Security Toolkit 3IBM SecureWay Directory client 3initialization of response objects 13installation 3installation directories 3installation requirements 3ivadmin_acl object 28ivadmin_acl_attrdelkey() function 48ivadmin_acl_attrdelval() function 49ivadmin_acl_attrget() function 50ivadmin_acl_attrlist() function 51ivadmin_acl_attrput() function 52ivadmin_acl_create() function 53ivadmin_acl_delete() function 54ivadmin_acl_get() function 55ivadmin_acl_getanyother() function 56ivadmin_acl_getdescription() function 57ivadmin_acl_getgroup() function 58ivadmin_acl_getid() function 59ivadmin_acl_getunauth() function 60ivadmin_acl_getuser() function 61ivadmin_acl_list() function 62ivadmin_acl_listgroups() function 63ivadmin_acl_listusers() function 64ivadmin_acl_removeanyother() function 65ivadmin_acl_removegroup() function 66ivadmin_acl_removeunauth() function 67ivadmin_acl_removeuser() function 68ivadmin_acl_setanyother() function 69ivadmin_acl_setdescription() function 71ivadmin_acl_setgroup() function 72
Index 311
ivadmin_acl_setunauth() function 74ivadmin_acl_setuser() function 76ivadmin_action_create_in_group() function 80ivadmin_action_create() function 78ivadmin_action_delete_from_group() function 83ivadmin_action_delete() function 82ivadmin_action_getdescription() function 84ivadmin_action_getid() function 85ivadmin_action_gettype() function 86ivadmin_action_group_create() function 87ivadmin_action_group_delete() function 88ivadmin_action_group_list() function 89ivadmin_action_list_in_group() function 91ivadmin_action_list() function 90ivadmin_cfg_addreplica() function 92ivadmin_cfg_chgreplica() function 93ivadmin_cfg_configureserver() deprecated function 287ivadmin_cfg_configureserver2() function 94ivadmin_cfg_renewservercert() function 96ivadmin_cfg_rmvreplica() function 97ivadmin_cfg_setapplicationcert() function 98ivadmin_cfg_setkeyringpwd() function 99ivadmin_cfg_setlistening() function 100ivadmin_cfg_setport() function 101ivadmin_cfg_setssltimeout() function 102ivadmin_cfg_unconfigureserver() function 103ivadmin_context object 8, 15ivadmin_context_cleardelcred() function 104ivadmin_context_create() deprecated function 287ivadmin_context_create() function 8, 105ivadmin_context_createdefault() function 7, 8, 107ivadmin_context_delete() function 16, 108ivadmin_context_getaccexpdate() function 109ivadmin_context_getdisabletimeint() function 110ivadmin_context_getmaxlgnfails() function 111ivadmin_context_getmaxpwdage() function 112ivadmin_context_getmaxpwdrepchars() function 113ivadmin_context_getminpwdalphas() function 114ivadmin_context_getminpwdlen() function 116ivadmin_context_getminpwdnonalphas() function 115ivadmin_context_getpwdspaces() function 117ivadmin_context_gettodaccess() function 118ivadmin_context_getuserreg() function 119ivadmin_context_setaccexpdate() function 120ivadmin_context_setdelcred() function 9, 121ivadmin_context_setdisabletimeint() function 122ivadmin_context_setmaxlgnfails() function 123ivadmin_context_setmaxpwdage() function 10, 124ivadmin_context_setmaxpwdrepchars() function 125ivadmin_context_setminpwdalphas() function 126ivadmin_context_setminpwdlen() function 128ivadmin_context_setminpwdnonalphas() function 127ivadmin_context_setpwdspaces() function 129ivadmin_context_settodaccess() functions 130IVADMIN_FALSE 13ivadmin_free() function 15, 131ivadmin_group_addmember() deprecated function 287ivadmin_group_addmembers() function 132ivadmin_group_create() deprecated function 287ivadmin_group_create2() function 133ivadmin_group_delete() deprecated function 287ivadmin_group_delete2() function 135ivadmin_group_get() function 136ivadmin_group_getbydn() function 137ivadmin_group_getcn() function 138ivadmin_group_getdescription() function 139ivadmin_group_getdn() function 140
ivadmin_group_getid() function 141ivadmin_group_getmembers() function 142ivadmin_group_import() deprecated function 287ivadmin_group_import2() function 143ivadmin_group_list() function 144ivadmin_group_listbydn() function 145ivadmin_group_removemember() deprecated function 287ivadmin_group_removemembers() function 147ivadmin_group_setdescription() function 148ivadmin_message_getcount() function 15ivadmin_objectspace_create() function 149ivadmin_objectspace_delete() function 151ivadmin_objectspace_list() function 152ivadmin_pop object 33ivadmin_pop_attach() function 153ivadmin_pop_attrdelkey() function 154ivadmin_pop_attrdelval() function 155ivadmin_pop_attrget() function 156ivadmin_pop_attrlist() function 157ivadmin_pop_attrput() function 158ivadmin_pop_create() function 159ivadmin_pop_delete() function 160ivadmin_pop_detach() function 161ivadmin_pop_find() function 162ivadmin_pop_get() function 163ivadmin_pop_getanyothernw() function 164ivadmin_pop_getauditlevel() function 165ivadmin_pop_getdescription() function 166ivadmin_pop_getid() function 167ivadmin_pop_getipauth() function 168ivadmin_pop_getqop() function 169ivadmin_pop_gettod() function 170ivadmin_pop_getwarnmode() function 172ivadmin_pop_list() function 173ivadmin_pop_removeipauth() function 174ivadmin_pop_setanyothernw_forbidden() function 176ivadmin_pop_setanyothernw() function 34, 175ivadmin_pop_setauditlevel() function 177ivadmin_pop_setdescription function() 178ivadmin_pop_setipauth_forbidden() function 180ivadmin_pop_setipauth() function 34, 179ivadmin_pop_setqop() function 181ivadmin_pop_settod() function 182ivadmin_pop_setwarnmode() function 184ivadmin_protobj_attachacl() function 185ivadmin_protobj_attrdelkey() function 186ivadmin_protobj_attrdelval() function 187ivadmin_protobj_attrget() function 188ivadmin_protobj_attrlist() function 189ivadmin_protobj_attrput() function 190ivadmin_protobj_create() function 191ivadmin_protobj_delete() function 192ivadmin_protobj_detachacl() function 193ivadmin_protobj_get() deprecated function 287ivadmin_protobj_get2() function 194ivadmin_protobj_getacl() function 196ivadmin_protobj_getdesc() function 197ivadmin_protobj_getid() function 198ivadmin_protobj_getpolicyattachable() function 199ivadmin_protobj_getpop() function 200ivadmin_protobj_gettype() function 201ivadmin_protobj_list2() deprecated function 287ivadmin_protobj_list3() function 202ivadmin_protobj_listbyacl() function 204ivadmin_protobj_setdesc() function 205ivadmin_protobj_setname() function 206ivadmin_protobj_setpolicyattachable() function 207
312 IBM Tivoli Access Manager: Administration C API Developer’s Reference
ivadmin_protobj_settype() function 208ivadmin_response object 8, 10, 13, 15IVADMIN_RESPONSE_ERROR 15ivadmin_response_getcode() function 14, 209ivadmin_response_getcount() function 14, 210ivadmin_response_getmessage() function 14, 211ivadmin_response_getmodifier() function 15, 212ivadmin_response_getok() function 13, 213IVADMIN_RESPONSE_INFO 15IVADMIN_RESPONSE_WARNING 15ivadmin_server_gettasklist() function 214ivadmin_server_performtask() function 216ivadmin_server_replicate() function 218ivadmin_ssocred_create() function 219ivadmin_ssocred_delete() function 220ivadmin_ssocred_get() function 221ivadmin_ssocred_getid() function 222ivadmin_ssocred_getssopassword() function 223ivadmin_ssocred_getssouser() function 224ivadmin_ssocred_gettype() function 225ivadmin_ssocred_getuser() function 226ivadmin_ssocred_list() function 227ivadmin_ssocred_set() function 228ivadmin_ssogroup_addres() function 229ivadmin_ssogroup_create() function 230ivadmin_ssogroup_delete() function 231ivadmin_ssogroup_get() function 232ivadmin_ssogroup_getdescription() function 233ivadmin_ssogroup_getid() function 234ivadmin_ssogroup_getresources() function 235ivadmin_ssogroup_list() function 236ivadmin_ssogroup_removeres() function 237ivadmin_ssoweb_create() function 238ivadmin_ssoweb_delete() function 239ivadmin_ssoweb_get() function 240ivadmin_ssoweb_getdescription() function 241ivadmin_ssoweb_getid() function 242ivadmin_ssoweb_list() function 243IVADMIN_TRUE 13ivadmin_user_create() deprecated function 287ivadmin_user_create2() deprecated function 287ivadmin_user_create3() function 9, 17, 244ivadmin_user_delete() deprecated function 287ivadmin_user_delete2() function 17, 246ivadmin_user_get() function 247ivadmin_user_getaccexpdate() function 248ivadmin_user_getaccountvalid() function 249ivadmin_user_getauthmech () deprecated function 287ivadmin_user_getbydn() function 250ivadmin_user_getcn() function 251ivadmin_user_getdescription() function 252ivadmin_user_getdisabletimeint() function 253ivadmin_user_getdn() function 254ivadmin_user_getid() function 255ivadmin_user_getmaxlgnfails() function 256ivadmin_user_getmaxpwdage() function 257ivadmin_user_getmaxpwdrepchars() function 258ivadmin_user_getmemberships() function 259ivadmin_user_getminpwdalphas() function 260ivadmin_user_getminpwdlen() function 261ivadmin_user_getminpwdnonalphas() function 262ivadmin_user_getpasswordvalid() function 263ivadmin_user_getpwdspaces() function 264ivadmin_user_getsn() function 265ivadmin_user_getssouser() function 266ivadmin_user_gettodaccess() function 267ivadmin_user_import() deprecated function 287
ivadmin_user_import2() function 268ivadmin_user_list() function 12, 269ivadmin_user_listbydn() function 271ivadmin_user_setaccexpdate() function 10, 272ivadmin_user_setaccountvalid() function 273ivadmin_user_setauthmech () deprecated function 287ivadmin_user_setdescription() function 274ivadmin_user_setdisabletimeint() function 275ivadmin_user_setmaxlgnfails() function 276ivadmin_user_setmaxpwdage() function 277ivadmin_user_setmaxpwdrepchars() function 278ivadmin_user_setminpwdalphas() function 279ivadmin_user_setminpwdlen() function 280ivadmin_user_setminpwdnonalphas() function 281ivadmin_user_setpassword() function 282ivadmin_user_setpasswordvalid() function 283ivadmin_user_setpwdspaces() function 284ivadmin_user_setssouser() function 285ivadmin_user_settodaccess() function 286
LLDAP users, creating 9libraries, linking 4libraries, shared 2linking libraries 4listing object information 12
Mmemory, freeing 15modifying values for objects 10
Nnotification wait time 44
Oobject information, listing 12object values, reading 11objects
creating 9, 10getting 11initialization of response objects 13ivadmin_acl 28ivadmin_context 8, 15ivadmin_pop 33ivadmin_response 8, 10, 13, 15modifying values 10PDProtObject 24PDProtObjectSpace 23setting values 10
Ppassword functions, table 20, 21passwords 20pdadmin command line utility 2performing administration tasks 43Privilege Attribute Certificate data, creating 9protected object attributes 25protected object functions, table 24, 25protected object policies 33
administering 33
Index 313
protected object policies (continued)defined 23
protected object policy (POP) 23protected object policy extended attributes, table 35protected object policy objects 33protected object policy objects, table 33protected object policy settings 34protected object policy settings, table 35protected object space functions, table 24protected object spaces 23protected objects 23, 24
Rreading object values 11registry, user 3related publications xvreplica databases, notification threads 44replica databases, notifying of updates 43, 44requirements, for installation 3resource objects 24response objects, initialization 13returned error conditions 10rsp 13
Ssecure domain 3Secure Sockets Layer (SSL) 1security context, deleting 16security contexts, establishing
backward compatibility 8delegating user credentials 8examples
ivadmin_context_createdefault 8overview 7required input parameters 8returned objects 8
secUser 17servers and databases, table 45set operations, example operations 10setting object values 10shared libraries 2shutdown of the Administration API 15software requirements 3SSL 1svrsslcfg command line utility 2
Ttypes, returned by get functions 11
Uunauthenticated 28user account functions, table 19user accounts 18user credentials, delegating 8user functions, table 18user password functions, table 20, 21user passwords 20user registry 3
differences xviii, 289maximum values 291, 292
user registry users, creating 9
users 17, 28users, creating for user registry 9using the administration API 7
Wwait time 44warning attribute 34
314 IBM Tivoli Access Manager: Administration C API Developer’s Reference
����
Printed in U.S.A.
SC32-1142-01