You are on page 1of 414

IBM Tivoli Access Manager for e-business

Administration C API Developer Reference


V ersion 5.1

SC32-1357-00

IBM Tivoli Access Manager for e-business

Administration C API Developer Reference


V ersion 5.1

SC32-1357-00

Note: Before using this information and the product it supports, read the information in Appendix D, Notices, on page 379.

First Edition (November 2003) This edition applies to version 5, release 1, modification 0 of IBM Tivoli Access Manager (product number 5724-C08) and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright International Business Machines Corporation 2000, 2003. All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Who should read this book . . What this book contains . . . Publications . . . . . . . Release information . . . Base information . . . . Web security information . Developer references . . . Technical supplements. . . Related publications . . . Accessing publications online Accessibility . . . . . . . Contacting software support . Conventions used in this book . Typeface conventions . . . User registry differences . . Operating system differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi . xi . xiii . xiii . xiii . xiv . xiv . xv . xv xviii . xix . xix . xix . xix . xix . xx

Chapter 1. Introducing the administration API . . . . . . . . . . . . . . . . . . . 1


Administration API overview . . . . . . . . . . . . Administration API components . . . . . . . . . . . Administration API shared libraries . . . . . . . . . Administration API application development kit . . . . . Building applications with the administration API . . . . . Software requirements . . . . . . . . . . . . . Linking required libraries . . . . . . . . . . . . Tested compilers . . . . . . . . . . . . . . . Administration API example program . . . . . . . . . Deploying an administration API application . . . . . . Gathering problem determination information . . . . . . Enabling tracing on the policy server . . . . . . . . Enabling tracing on a system using the runtime component Gathering trace and message logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 2 2 3 3 3 4 4 5 5 5 6 6 6

Chapter 2. Using the administration API . . . . . . . . . . . . . . . . . . . . . . 7


Establishing security contexts . . . . Required input parameters . . . Handling of character data . . . Returned objects . . . . . . . Example code . . . . . . . . Backward compatibility . . . . . Delegating user credentials . . . Creating objects . . . . . . . . Setting object values . . . . . . Getting objects . . . . . . . . Reading object values . . . . . . Listing object information . . . . Handling errors . . . . . . . . Evaluating a response object . . . Obtaining error message text . . Obtaining error codes . . . . . Obtaining error message modifiers Cleaning up and shutting down . . Freeing memory . . . . . . . Deleting a security context . . .
Copyright IBM Corp. 2000, 2003

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . .

. 7 . 8 . 8 . 8 . 9 . 9 . 9 . 10 . 11 . 12 . 12 . 13 . 14 . 14 . 15 . 15 . 16 . 16 . 16 . 17

iii

Chapter 3. Administering users and groups . . . . . . . . . . . . . . . . . . . . 19


Administering Administering Administering Administering Administering users . . . . user accounts . user passwords . groups . . . . group attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 20 22 23 24

Chapter 4. Administering protected objects and protected object spaces . . . . . . . 25


Administering protected object spaces . Administering protected objects . . . Administering protected object attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 . 26 . 27

Chapter 5. Administering access control . . . . . . . . . . . . . . . . . . . . . 29


Administering Administering Administering Administering Administering access control lists . . . access control list entries . access control list extended action groups . . . . extended actions . . . . . . . . . . . attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 30 32 32 33

Chapter 6. Administering protected object policies . . . . . . . . . . . . . . . . . 35


Administering protected object policy objects . . . . . Administering protected object policy settings . . . . . Administering protected object policy extended attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 . 36 . 37

Chapter 7. Administering authorization rules . . . . . . . . . . . . . . . . . . . 39 Chapter 8. Administering single signon resources . . . . . . . . . . . . . . . . . 41


Administering Web resources . . Administering resource groups . . Administering resource credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 . 42 . 43

Chapter 9. Administering domains . . . . . . . . . . . . . . . . . . . . . . . . 45 Chapter 10. Configuring application servers. . . . . . . . . . . . . . . . . . . . 47


Configuring application servers. Administering replicas. . . . Certificate maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 . 48 . 48

Chapter 11. Administering servers . . . . . . . . . . . . . . . . . . . . . . . . 49


Getting and performing administration tasks . . . . . . . . Notifying replica databases when the master authorization database Notifying replica databases automatically . . . . . . . . Notifying replica databases manually . . . . . . . . . . Setting the maximum number of notification threads . . . . Setting the notification wait time . . . . . . . . . . . Administrating servers and database notification . . . . . . . . . . . is updated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 49 50 50 50 50 51

Chapter 12. Administration C API reference . . . . . . . . . . . . . . . . . . . . 53


ivadmin_accessOutdata_getAccessResult() ivadmin_accessOutdata_getPermInfo() . ivadmin_accessOutdata_getResponseInfo() ivadmin_acl_attrdelkey() . . . . . . ivadmin_acl_attrdelval() . . . . . . ivadmin_acl_attrget() . . . . . . . ivadmin_acl_attrlist() . . . . . . . ivadmin_acl_attrput() . . . . . . . ivadmin_acl_create() . . . . . . . ivadmin_acl_delete() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 55 56 57 58 59 60 61 62 63

iv

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_acl_get() . . . . . . . ivadmin_acl_getanyother() . . . . ivadmin_acl_getdescription() . . . ivadmin_acl_getgroup() . . . . . ivadmin_acl_getid() . . . . . . . ivadmin_acl_getunauth() . . . . . ivadmin_acl_getuser() . . . . . . ivadmin_acl_list() . . . . . . . ivadmin_acl_listgroups() . . . . . ivadmin_acl_listusers() . . . . . ivadmin_acl_removeanyother() . . . ivadmin_acl_removegroup() . . . . ivadmin_acl_removeunauth() . . . ivadmin_acl_removeuser() . . . . ivadmin_acl_setanyother() . . . . ivadmin_acl_setdescription() . . . . ivadmin_acl_setgroup() . . . . . ivadmin_acl_setunauth() . . . . . ivadmin_acl_setuser() . . . . . . ivadmin_action_create() . . . . . ivadmin_action_create_in_group() . . ivadmin_action_delete() . . . . . ivadmin_action_delete_from_group() . ivadmin_action_getdescription() . . ivadmin_action_getid() . . . . . ivadmin_action_gettype() . . . . . ivadmin_action_group_create() . . . ivadmin_action_group_delete() . . . ivadmin_action_group_list() . . . . ivadmin_action_list() . . . . . . ivadmin_action_list_in_group() . . . ivadmin_authzrule_create() . . . . ivadmin_authzrule_delete() . . . . ivadmin_authzrule_get() . . . . . ivadmin_authzrule_getdescription() . ivadmin_authzrule_getfailreason() . ivadmin_authzrule_getid() . . . . ivadmin_authzrule_getruletext() . . ivadmin_authzrule_list() . . . . . ivadmin_authzrule_setdescription() . ivadmin_authzrule_setfailreason() . ivadmin_authzrule_setruletext() . . ivadmin_cfg_addreplica2() . . . . ivadmin_cfg_chgreplica2() . . . . ivadmin_cfg_configureserver3() . . ivadmin_cfg_getvalue() . . . . . ivadmin_cfg_removevalue() . . . ivadmin_cfg_renewservercert() . . ivadmin_cfg_rmvreplica2() . . . . ivadmin_cfg_setapplicationcert2(). . ivadmin_cfg_setkeyringpwd2() . . ivadmin_cfg_setlistening2() . . . . ivadmin_cfg_setport2() . . . . . ivadmin_cfg_setssltimeout2() . . . ivadmin_cfg_setsvrpwd() . . . . ivadmin_cfg_setvalue() . . . . . ivadmin_cfg_unconfigureserver() . . ivadmin_context_cleardelcred() . . ivadmin_context_create3() . . . . ivadmin_context_createdefault2() . . ivadmin_context_createlocal() . . .

. 64 . 65 . 66 . 67 . 68 . 69 . 70 . 71 . 72 . 73 . 74 . 75 . 76 . 77 . 78 . 80 . 81 . 83 . 85 . 87 . 89 . 90 . 91 . 92 . 93 . 94 . 95 . 96 . 97 . 98 . 99 . . . . . . . . . . . . . . . . . . . . . . . . . . 100 . . . . . . . . . . . . . . . . . . . . . . . . . . 101 . . . . . . . . . . . . . . . . . . . . . . . . . . 102 . . . . . . . . . . . . . . . . . . . . . . . . . . 103 . . . . . . . . . . . . . . . . . . . . . . . . . . 104 . . . . . . . . . . . . . . . . . . . . . . . . . . 105 . . . . . . . . . . . . . . . . . . . . . . . . . . 106 . . . . . . . . . . . . . . . . . . . . . . . . . . 107 . . . . . . . . . . . . . . . . . . . . . . . . . . 108 . . . . . . . . . . . . . . . . . . . . . . . . . . 109 . . . . . . . . . . . . . . . . . . . . . . . . . . 110 . . . . . . . . . . . . . . . . . . . . . . . . . . 111 . . . . . . . . . . . . . . . . . . . . . . . . . . 112 . . . . . . . . . . . . . . . . . . . . . . . . . . 113 . . . . . . . . . . . . . . . . . . . . . . . . . . 115 . . . . . . . . . . . . . . . . . . . . . . . . . . 117 . . . . . . . . . . . . . . . . . . . . . . . . . . 119 . . . . . . . . . . . . . . . . . . . . . . . . . . 120 . . . . . . . . . . . . . . . . . . . . . . . . . . 121 . . . . . . . . . . . . . . . . . . . . . . . . . . 122 . . . . . . . . . . . . . . . . . . . . . . . . . . 123 . . . . . . . . . . . . . . . . . . . . . . . . . . 124 . . . . . . . . . . . . . . . . . . . . . . . . . . 125 . . . . . . . . . . . . . . . . . . . . . . . . . . 126 . . . . . . . . . . . . . . . . . . . . . . . . . . 128 . . . . . . . . . . . . . . . . . . . . . . . . . . 130 . . . . . . . . . . . . . . . . . . . . . . . . . . 131 . . . . . . . . . . . . . . . . . . . . . . . . . . 132 . . . . . . . . . . . . . . . . . . . . . . . . . . 134 . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Contents

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

ivadmin_context_delete() . . . . . ivadmin_context_domainismanagement() ivadmin_context_getaccexpdate() . . . ivadmin_context_getcodeset() . . . . ivadmin_context_getdisabletimeint() . . ivadmin_context_getdomainid() . . . ivadmin_context_getmaxlgnfails() . . ivadmin_context_getmaxpwdage() . . ivadmin_context_getmaxpwdrepchars() . ivadmin_context_getmgmtdomainid() . ivadmin_context_getmgmtsvrhost() . . ivadmin_context_getmgmtsvrport() . . ivadmin_context_getminpwdalphas() . ivadmin_context_getminpwdnonalphas() ivadmin_context_getminpwdlen() . . ivadmin_context_getpwdspaces() . . . ivadmin_context_gettodaccess() . . . ivadmin_context_getuserid() . . . . ivadmin_context_getuserreg() . . . . ivadmin_context_hasdelcred() . . . . ivadmin_context_setaccexpdate() . . . ivadmin_context_setdelcred() . . . . ivadmin_context_setdisabletimeint() . . ivadmin_context_setmaxlgnfails() . . . ivadmin_context_setmaxpwdage() . . ivadmin_context_setmaxpwdrepchars() . ivadmin_context_setminpwdalphas() . ivadmin_context_setminpwdnonalphas() ivadmin_context_setminpwdlen() . . . ivadmin_context_setpwdspaces() . . . ivadmin_context_settodaccess() . . . ivadmin_domain_create() . . . . . ivadmin_domain_delete() . . . . . ivadmin_domain_get() . . . . . . ivadmin_domain_getdescription() . . ivadmin_domain_getid(). . . . . . ivadmin_domain_list() . . . . . . ivadmin_domain_setdescription() . . . ivadmin_free() . . . . . . . . . ivadmin_group_addmembers() . . . ivadmin_group_create2() . . . . . ivadmin_group_delete2() . . . . . ivadmin_group_get() . . . . . . . ivadmin_group_getbydn() . . . . . ivadmin_group_getcn() . . . . . . ivadmin_group_getdescription() . . . ivadmin_group_getdn() . . . . . . ivadmin_group_getid() . . . . . . ivadmin_group_getmembers() . . . . ivadmin_group_import2() . . . . . ivadmin_group_list() . . . . . . . ivadmin_group_listbydn() . . . . . ivadmin_group_removemembers() . . ivadmin_group_setdescription() . . . ivadmin_objectspace_create() . . . . ivadmin_objectspace_delete() . . . . ivadmin_objectspace_list() . . . . . ivadmin_pop_attach() . . . . . . ivadmin_pop_attrdelkey() . . . . . ivadmin_pop_attrdelval() . . . . . ivadmin_pop_attrget() . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 180 181 182 183 184 185 186 187 188 189 191 193 194 195 197 198 199 200 201 202

vi

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_pop_attrlist() . . . . . . ivadmin_pop_attrput() . . . . . . ivadmin_pop_create(). . . . . . . ivadmin_pop_delete() . . . . . . ivadmin_pop_detach() . . . . . . ivadmin_pop_find() . . . . . . . ivadmin_pop_get() . . . . . . . ivadmin_pop_getanyothernw() . . . ivadmin_pop_getauditlevel() . . . . ivadmin_pop_getdescription() . . . . ivadmin_pop_getid() . . . . . . . ivadmin_pop_getipauth() . . . . . ivadmin_pop_getqop() . . . . . . ivadmin_pop_gettod() . . . . . . ivadmin_pop_getwarnmode() . . . . ivadmin_pop_list() . . . . . . . ivadmin_pop_removeipauth() . . . . ivadmin_pop_setanyothernw(). . . . ivadmin_pop_setanyothernw_forbidden() ivadmin_pop_setauditlevel() . . . . ivadmin_pop_setdescription() . . . . ivadmin_pop_setipauth() . . . . . ivadmin_pop_setipauth_forbidden() . . ivadmin_pop_setqop() . . . . . . ivadmin_pop_settod() . . . . . . ivadmin_pop_setwarnmode() . . . . ivadmin_protobj_access() . . . . . ivadmin_protobj_attachacl() . . . . ivadmin_protobj_attachauthzrule() . . ivadmin_protobj_attrdelkey() . . . . ivadmin_protobj_attrdelval() . . . . ivadmin_protobj_attrget() . . . . . ivadmin_protobj_attrlist() . . . . . ivadmin_protobj_attrput() . . . . . ivadmin_protobj_create() . . . . . ivadmin_protobj_delete() . . . . . ivadmin_protobj_detachacl() . . . . ivadmin_protobj_detachauthzrule() . . ivadmin_protobj_exists() . . . . . . ivadmin_protobj_get3() . . . . . . ivadmin_protobj_getaclid() . . . . . ivadmin_protobj_getauthzruleid() . . ivadmin_protobj_getdesc() . . . . . ivadmin_protobj_geteffaclid() . . . . ivadmin_protobj_geteffauthzruleid() . . ivadmin_protobj_geteffpopid() . . . . ivadmin_protobj_getid() . . . . . . ivadmin_protobj_getpolicyattachable() . ivadmin_protobj_getpopid() . . . . ivadmin_protobj_gettype() . . . . . ivadmin_protobj_list3() . . . . . . ivadmin_protobj_listbyacl() . . . . . ivadmin_protobj_listbyauthzrule() . . ivadmin_protobj_multiaccess() . . . . ivadmin_protobj_setdesc() . . . . . ivadmin_protobj_setpolicyattachable() . ivadmin_protobj_settype() . . . . . ivadmin_response_getcode() . . . . ivadmin_response_getcount() . . . . ivadmin_response_getmessage() . . . ivadmin_response_getmodifier() . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

203 204 205 207 208 209 210 211 212 213 214 215 216 217 219 220 221 222 223 224 225 226 227 228 229 231 232 234 235 236 237 238 239 240 241 242 243 244 245 246 248 249 250 251 252 253 254 255 256 257 258 260 261 262 264 265 266 267 268 269 270

Contents

vii

ivadmin_response_getok() . . . . ivadmin_server_gettasklist() . . . ivadmin_server_performtask() . . . ivadmin_server_replicate() . . . . ivadmin_ssocred_create() . . . . ivadmin_ssocred_delete() . . . . ivadmin_ssocred_get() . . . . . ivadmin_ssocred_getid() . . . . . ivadmin_ssocred_getssopassword() . ivadmin_ssocred_getssouser() . . . ivadmin_ssocred_gettype() . . . . ivadmin_ssocred_getuser() . . . . ivadmin_ssocred_list() . . . . . ivadmin_ssocred_set() . . . . . ivadmin_ssogroup_addres() . . . ivadmin_ssogroup_create() . . . . ivadmin_ssogroup_delete() . . . . ivadmin_ssogroup_get() . . . . . ivadmin_ssogroup_getdescription() . ivadmin_ssogroup_getid() . . . . ivadmin_ssogroup_getresources() . . ivadmin_ssogroup_list . . . . . ivadmin_ssogroup_removeres() . . ivadmin_ssoweb_create() . . . . ivadmin_ssoweb_delete() . . . . ivadmin_ssoweb_get() . . . . . ivadmin_ssoweb_getdescription() . . ivadmin_ssoweb_getid() . . . . . ivadmin_ssoweb_list() . . . . . ivadmin_user_create3() . . . . . ivadmin_user_delete2() . . . . . ivadmin_user_get() . . . . . . ivadmin_user_getaccexpdate() . . . ivadmin_user_getaccountvalid() . . ivadmin_user_getbydn() . . . . . ivadmin_user_getcn() . . . . . . ivadmin_user_getdescription() . . . ivadmin_user_getdisabletimeint() . . ivadmin_user_getdn() . . . . . ivadmin_user_getid() . . . . . . ivadmin_user_getmaxlgnfails() . . ivadmin_user_getmaxpwdage() . . ivadmin_user_getmaxpwdrepchars(). ivadmin_user_getmemberships() . . ivadmin_user_getminpwdalphas() . ivadmin_user_getminpwdlen() . . ivadmin_user_getminpwdnonalphas() ivadmin_user_getpasswordvalid() . ivadmin_user_getpwdspaces() . . . ivadmin_user_getsn() . . . . . . ivadmin_user_getssouser() . . . . ivadmin_user_gettodaccess() . . . ivadmin_user_import2() . . . . . ivadmin_user_list() . . . . . . ivadmin_user_listbydn() . . . . . ivadmin_user_setaccexpdate() . . . ivadmin_user_setaccountvalid() . . ivadmin_user_setdescription() . . . ivadmin_user_setdisabletimeint() . . ivadmin_user_setmaxlgnfails() . . . ivadmin_user_setmaxpwdage() . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

271 272 274 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 329 331 332 333 334 335 336

viii

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_setmaxpwdrepchars() . ivadmin_user_setminpwdalphas() . ivadmin_user_setminpwdlen() . . . ivadmin_user_setminpwdnonalphas() ivadmin_user_setpassword() . . . ivadmin_user_setpasswordvalid() . ivadmin_user_setpwdspaces() . . . ivadmin_user_setssouser() . . . . ivadmin_user_settodaccess() . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

337 338 339 340 341 342 343 344 345

Appendix A. Deprecated APIs . . . . . . . . . . . . . . . . . . . . . . . . . 347 Appendix B. User registry differences . . . . . . . . . . . . . . . . . . . . . . 349 Appendix C. Administration API equivalents . . . . . . . . . . . . . . . . . . . 353 Appendix D. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383

Contents

ix

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Preface
IBM Tivoli Access Manager (Tivoli Access Manager) is the base software that is required to run applications in the IBM Tivoli Access Manager product suite. It enables the integration of IBM Tivoli Access Manager applications that provide a wide range of authorization and management solutions. Sold as an integrated solution, these products provide an access control management solution that centralizes network and application security policy for e-business applications. Note: IBM Tivoli Access Manager is the new name of the previously released software entitled Tivoli SecureWay Policy Director. Also, for users familiar with the Tivoli SecureWay Policy Director software and documentation, the management server is now referred to as the policy server. This reference contains information about how to use Tivoli Access Manager C administration API to enable an application to programmatically perform Tivoli Access Manager administration tasks. This document describes the C implementation of the Tivoli Access Manager administration API. See the IBM Tivoli Access Manager for e-business Administration Java Classes Developer Reference for information regarding the Java implementation of these APIs. Information on the pdadmin command line interface (CLI) can be found in the IBM Tivoli Access Manager for e-business Command Reference.

Who should read this book


This reference is for application programmers implementing programs in the C programming language to administer the users and objects associated with the IBM Tivoli Access Manager product. Readers should be familiar with the following: v PC and UNIX operating systems v Database architecture and concepts v Security management v Internet protocols, including HTTP, TCP/IP, File Transfer Protocol (FTP), and Telnet v The user registry that Tivoli Access Manager is configured to use v Lightweight Directory Access Protocol (LDAP) and directory services, if used by your user registry v Authentication and authorization If you are enabling Secure Sockets Layer (SSL) communication, you also should be familiar with SSL protocol, key exchange (public and private), digital signatures, cryptographic algorithms, and certificate authorities.

What this book contains


This 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 also covers building applications with the API and deploying an administration API program. Chapter 2, Using the administration API, on page 7 Each application that uses the administration API must perform certain tasks necessary for API initialization, shut down, cleanup, memory management, and error handling. This chapter describes the supported functions for establishing security contexts, creating objects, setting object values, reading object values, listing object information, deleting objects, handling errors, administrating policies, cleaning up, and shutting down. Chapter 3, Administering users and groups, on page 19 The administration API provides a collection of methods for administering Tivoli Access Manager users and groups. This chapter describes the tasks that those functions accomplish. It describes the supported functions for administering users, user accounts, user passwords, groups, group attributes, and the policies associated with users. Chapter 4, Administering protected objects and protected object spaces, on page 25 This chapter describes the administration API functions that are used to administer protected object spaces and protected objects. It describes the supported functions for administering protected object spaces, protected objects, and protected object attributes. Chapter 5, Administering access control, on page 29 This chapter describes the administration API functions that are used to administer access control. It describes the supported functions for administering access control lists, access control list permissions, access control list extended attributes, extended actions, and action groups. Chapter 6, Administering protected object policies, on page 35 This chapter describes the administration API functions that are used to create, modify, examine, and delete protected object policies. It also discusses attaching or detaching protected objects from protected object policies. It describes the supported functions for administering protected object policy objects, protected object policy settings, and protected object policy extended attributes. Chapter 7, Administering authorization rules, on page 39 This chapter provides instructions for using the administration API to create, delete, list, and modify authorization rules. Chapter 8, Administering single signon resources, on page 41 This chapter provides instructions for using the administration API to create, modify, or delete web resources, resource groups, and resource credentials. Chapter 9, Administering domains, on page 45 This chapter provides instructions for using the administration API to create, delete, list, and modify Tivoli Access Manager policy server domains. Chapter 11, Administering servers, on page 49 This chapter provides information about getting and performing administration tasks and notifying the replica database when the master authorization database is updated. Chapter 10, Configuring application servers, on page 47 This chapter provides instructions for using the administration API to configure servers, modify server configurations, administer replicas, and perform certificate maintenance. Chapter 12, Administration C API reference, on page 53

xii

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

This chapter provides detailed information about specific commands in the administration API. Appendix A, Deprecated APIs, on page 347 This appendix provides a list of the APIs that have been deprecated in this version of Tivoli Access Manager. Appendix B, User registry differences, on page 349 This appendix outlines the differences in behavior of the APIs based on the user registry being used by Tivoli Access Manager. Appendix C, Administration API equivalents, on page 353 This appendix shows the mapping that exists between the Administration C APIs, the Administration Java classes and methods, and the command line interface (CLI). Appendix D, Notices, on page 379 This appendix provides copyright, legal, and trademark information.

Publications
Review the descriptions of the Tivoli Access Manager library, the prerequisite publications, and the related publications to determine which publications you might find helpful. After you determine the publications you need, refer to the instructions for accessing publications online. Additional information about the IBM Tivoli Access Manager for e-business product itself can be found at: http://www.ibm.com/software/tivoli/products/access-mgr-e-bus/ The Tivoli Access Manager library is organized into the following categories: v Release information v Base information v Web security information on page xiv v Developer references on page xiv v Technical supplements on page xv

Release information
v IBM Tivoli Access Manager for e-business Read This First (GI11-4155-00) Provides information for installing and getting started using Tivoli Access Manager. v IBM Tivoli Access Manager for e-business Release Notes (GI11-4156-00) Provides late-breaking information, such as software limitations, workarounds, and documentation updates.

Base information
v IBM Tivoli Access Manager Base Installation Guide (SC32-1362-00) Explains how to install and configure the Tivoli Access Manager base software, including the Web Portal Manager interface. This book is a subset of IBM Tivoli Access Manager for e-business Web Security Installation Guide and is intended for use with other Tivoli Access Manager products, such as IBM Tivoli Access Manager for Business Integration and IBM Tivoli Access Manager for Operating Systems.
Preface

xiii

v IBM Tivoli Access Manager Base Administration Guide (SC32-1360-00) Describes the concepts and procedures for using Tivoli Access Manager services. Provides instructions for performing tasks from the Web Portal Manager interface and by using the pdadmin command.

Web security information


v IBM Tivoli Access Manager for e-business Web Security Installation Guide (SC32-1361-00) Provides installation, configuration, and removal instructions for the Tivoli Access Manager base software as well as the Web Security components. This book is a superset of IBM Tivoli Access Manager Base Installation Guide. v IBM Tivoli Access Manager Upgrade Guide (SC32-1369-00) Explains how to upgrade from Tivoli SecureWay Policy Director Version 3.8 or previous versions of Tivoli Access Manager to Tivoli Access Manager Version 5.1. v IBM Tivoli Access Manager for e-business WebSEAL Administration Guide (SC32-1359-00) Provides background material, administrative procedures, and technical reference information for using WebSEAL to manage the resources of your secure Web domain. v IBM Tivoli Access Manager for e-business IBM WebSphere Application Server Integration Guide (SC32-1368-00) Provides installation, removal, and administration instructions for integrating Tivoli Access Manager with IBM WebSphere Application Server. v IBM Tivoli Access Manager for e-business IBM WebSphere Edge Server Integration Guide (SC32-1367-00) Provides installation, removal, and administration instructions for integrating Tivoli Access Manager with the IBM WebSphere Edge Server application. v IBM Tivoli Access Manager for e-business Plug-in for Web Servers Integration Guide (SC32-1365-00) Provides installation instructions, administration procedures, and technical reference information for securing your Web domain using the plug-in for Web servers. v IBM Tivoli Access Manager for e-business BEA WebLogic Server Integration Guide (SC32-1366-00) Provides installation, removal, and administration instructions for integrating Tivoli Access Manager with BEA WebLogic Server. v IBM Tivoli Access Manager for e-business IBM Tivoli Identity Manager Provisioning Fast Start Guide (SC32-1364-00) Provides an overview of the tasks related to integrating Tivoli Access Manager and Tivoli Identity Manager and explains how to use and install the Provisioning Fast Start collection.

Developer references
v IBM Tivoli Access Manager for e-business Authorization C API Developer Reference (SC32-1355-00) Provides reference material that describes how to use the Tivoli Access Manager authorization C API and the Tivoli Access Manager service plug-in interface to add Tivoli Access Manager security to applications.

xiv

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

v IBM Tivoli Access Manager for e-business Authorization Java Classes Developer Reference (SC32-1350-00) Provides reference information for using the Java language implementation of the authorization API to enable an application to use Tivoli Access Manager security. v IBM Tivoli Access Manager for e-business Administration C API Developer Reference (SC32-1357-00) Provides reference information about using the administration API to enable an application to perform Tivoli Access Manager administration tasks. This document describes the C implementation of the administration API. v IBM Tivoli Access Manager for e-business Administration Java Classes Developer Reference (SC32-1356-00) Provides reference information for using the Java language implementation of the administration API to enable an application to perform Tivoli Access Manager administration tasks. v IBM Tivoli Access Manager for e-business Web Security Developer Reference (SC32-1358-00) Provides administration and programming information for the cross-domain authentication service (CDAS), the cross-domain mapping framework (CDMF), and the password strength module.

Technical supplements
v IBM Tivoli Access Manager for e-business Command Reference (SC32-1354-00) Provides information about the command line utilities and scripts provided with Tivoli Access Manager. v IBM Tivoli Access Manager Error Message Reference (SC32-1353-00) Provides explanations and recommended actions for the messages produced by Tivoli Access Manager. v IBM Tivoli Access Manager for e-business Problem Determination Guide (SC32-1352-00) Provides problem determination information for Tivoli Access Manager. v IBM Tivoli Access Manager for e-business Performance Tuning Guide (SC32-1351-00) Provides performance tuning information for an environment consisting of Tivoli Access Manager with the IBM Tivoli Directory server as the user registry.

Related publications
This section lists publications related to the Tivoli Access Manager library. The Tivoli Software Library provides a variety of Tivoli publications such as white papers, datasheets, demonstrations, redbooks, and announcement letters. The Tivoli Software 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 terms related 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 page http://www.ibm.com/software/tivoli/library/

IBM Global Security Kit


Tivoli Access Manager provides data encryption through the use of the IBM Global Security Kit (GSKit) Version 7.0. GSKit is included on the IBM Tivoli Access Manager Base CD for your particular platform, as well as on the IBM Tivoli Access Manager
Preface

xv

Web Security CDs, the IBM Tivoli Access Manager Web Administration Interfaces CDs, and the IBM Tivoli Access Manager Directory Server CDs. The GSKit package provides the iKeyman key management utility, gsk7ikm, which is used to create key databases, public-private key pairs, and certificate requests. The following document is available on the Tivoli Information Center Web site in the same section as the IBM Tivoli Access Manager product documentation: v IBM Global Security Kit Secure Sockets Layer and iKeyman Users Guide (SC32-1363-00) Provides information for network or system security administrators who plan to enable SSL communication in their Tivoli Access Manager environment.

IBM Tivoli Directory Server


IBM Tivoli Directory Server, Version 5.2, is included on the IBM Tivoli Access Manager Directory Server CD for the desired operating system. Note: IBM Tivoli Directory Server is the new name for the previously released software known as: v IBM Directory Server (Version 4.1 and Version 5.1) v IBM SecureWay Directory Server (Version 3.2.2) IBM Directory Server Version 4.1, IBM Directory Server Version 5.1, and IBM Tivoli Directory Server Version 5.2 are all supported by IBM Tivoli Access Manager Version 5.1. Additional information about IBM Tivoli Directory Server can be found at: http://www.ibm.com/software/network/directory/library/

IBM DB2 Universal Database

IBM DB2 Universal Database Enterprise Server Edition, Version 8.1 is provided on the IBM Tivoli Access Manager Directory Server CD and is installed with the IBM Tivoli Directory Server software. DB2 is required when using IBM Tivoli Directory Server, z/OS, or OS/390 LDAP servers as the user registry for Tivoli Access Manager. Additional information about DB2 can be found at: http://www.ibm.com/software/data/db2/

IBM WebSphere Application Server


IBM WebSphere Application Server, Advanced Single Server Edition 5.0, is included on the IBM Tivoli Access Manager Web Administration Interfaces CD for the desired operating system. WebSphere Application Server enables the support of both the Web Portal Manager interface, which is used to administer Tivoli Access Manager, and the Web Administration Tool, which is used to administer IBM Tivoli Directory Server. IBM WebSphere Application Server Fix Pack 2 is also required by Tivoli Access Manager and is provided on the IBM Tivoli Access Manager WebSphere Fix Pack CD. Additional information about IBM WebSphere Application Server can be found at: http://www.ibm.com/software/webservers/appserv/infocenter.html

xvi

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

IBM Tivoli Access Manager for Business Integration


IBM Tivoli Access Manager for Business Integration, available as a separately orderable product, provides a security solution for IBM MQSeries, Version 5.2, and IBM WebSphere MQ for Version 5.3 messages. IBM Tivoli Access Manager for Business Integration allows WebSphere MQSeries applications to send data with privacy and integrity by using keys associated with sending and receiving applications. Like WebSEAL and IBM Tivoli Access Manager for Operating Systems, IBM Tivoli Access Manager for Business Integration, is one of the resource managers that use the services of IBM Tivoli Access Manager. Additional information about IBM Tivoli Access Manager for Business Integration can be found at: http://www.ibm.com/software/tivoli/products/access-mgr-bus-integration/ The following documents associated with IBM Tivoli Access Manager for Business Integration Version 5.1 are available on the Tivoli Information Center Web site: v IBM Tivoli Access Manager for Business Integration Administration Guide (SC23-4831-01) v IBM Tivoli Access Manager for Business Integration Problem Determination Guide (GC23-1328-00) v IBM Tivoli Access Manager for Business Integration Release Notes (GI11-0957-01) v IBM Tivoli Access Manager for Business Integration Read This First (GI11-4202-00)

IBM Tivoli Access Manager for WebSphere Business Integration Brokers


IBM Tivoli Access Manager for WebSphere Business Integration Brokers, available as part of IBM Tivoli Access Manager for Business Integration, provides a security solution for WebSphere Business Integration Message Broker, Version 5.0 and WebSphere Business Integration Event Broker, Version 5.0. IBM Tivoli Access Manager for WebSphere Business Integration Brokers operates in conjunction with Tivoli Access Manager to secure JMS publish/subscribe applications by providing password and credentials-based authentication, centrally-defined authorization, and auditing services. Additional information about IBM Tivoli Access Manager for WebSphere Integration Brokers can be found at: http://www.ibm.com/software/tivoli/products/access-mgr-bus-integration/ The following documents associated with IBM Tivoli Access Manager for WebSphere Integration Brokers, Version 5.1 are available on the Tivoli Information Center Web site: v IBM Tivoli Access Manager for WebSphere Business Integration Brokers Administration Guide (SC32-1347-00) v IBM Tivoli Access Manager for WebSphere Business Integration Brokers Release Notes (GI11-4154-00) v IBM Tivoli Access Manager for Business Integration Read This First (GI11-4202-00)

IBM Tivoli Access Manager for Operating Systems


IBM Tivoli Access Manager for Operating Systems, available as a separately orderable product, provides a layer of authorization policy enforcement on UNIX systems in addition to that provided by the native operating system. IBM Tivoli

Preface

xvii

Access Manager for Operating Systems, like WebSEAL and IBM Tivoli Access Manager for Business Integration, is one of the resource managers that use the services of IBM Tivoli Access Manager. Additional information about IBM Tivoli Access Manager for Operating Systems can be found at: http://www.ibm.com/software/tivoli/products/access-mgr-operating-sys/ The following documents associated with IBM Tivoli Access Manager for Operating Systems Version 5.1 are available on the Tivoli Information Center Web site: 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) 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)

IBM Tivoli Identity Manager


IBM Tivoli Identity Manager Version 4.5, available as a separately orderable product, enables you to centrally manage users (such as user IDs and passwords) and provisioning (that is providing or revoking access to applications, resources, or operating systems.) Tivoli Identity Manager can be integrated with Tivoli Access Manager through the use of the Tivoli Access Manager Agent. Contact your IBM account representative for more information about purchasing the Agent. Additional information about IBM Tivoli Identity Manager can be found at: http://www.ibm.com/software/tivoli/products/identity-mgr/

Accessing publications online


The publications for this product are available online in Portable Document Format (PDF) or Hypertext Markup Language (HTML) format, or both in the Tivoli software library: http://www.ibm.com/software/tivoli/library To locate product publications in the library, click the Product manuals link on the left side of the library page. Then, locate and click the name of the product on the Tivoli software information center page. Product publications include release notes, installation guides, users guides, administrators guides, and developers references. Note: To ensure proper printing of PDF publications, select the Fit to page check box in the Adobe Acrobat Print window (which is available when you click File Print).

xviii

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

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

Contacting software support


Before contacting IBM Tivoli Software Support with a problem, refer to the IBM Tivoli Software Support site by clicking the Tivoli support link at the following Web site: http://www.ibm.com/software/support/ If you need additional help, contact software support by using the methods described 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 v Telephone numbers, depending on the country in which you are located v A list of information you should gather before contacting customer support

Conventions used in this book


This reference uses several conventions for special terms and actions and for operating system-dependent commands and paths.

Typeface conventions
The following typeface conventions are used in this reference: Bold Lowercase commands or mixed case commands that are difficult to distinguish from surrounding text, keywords, parameters, options, names of Java classes, and objects are in bold. Variables, titles of publications, and special words or phrases that are emphasized are in italic.

Italic

Monospace Code examples, command lines, screen output, file and directory names that are difficult to distinguish from surrounding text, system messages, text that the user must type, and values for arguments or command options are in monospace.

User registry differences


Tivoli Access Manager supports a number of different user registries. In most cases, the behavior of Tivoli Access Manager is the same regardless of what user registry is in use. However, there are several cases where the processing of a given function differs based on what user registry is being used. A note similar to the following highlights these differences: User registry difference: This text would describe the different behavior based on the user registry in use.

Preface

xix

See Appendix B, User registry differences, on page 349 for a complete list of known differences.

Operating system differences


This book uses the UNIX convention for specifying environment variables and for directory notation. When using the Windows command line, replace $variable with %variable% for environment variables and replace each forward slash (/) with a backslash (\) in directory paths. If you are using the bash shell on a Windows system, you can use the UNIX conventions.

xx

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Chapter 1. Introducing the administration API


The IBM Tivoli Access Manager (Tivoli Access Manager) administration API component provides a set of functions for the administration of Tivoli Access Manager users and data objects. The API provides a way for applications to administer users, groups, protected objects, access control lists, protected object policies, and Web resources. You can use the Tivoli Access Manager application developer kit (ADK) component to enable your application to programmatically administer Tivoli Access Manager users and data. This chapter contains the following topics: v Administration API overview v Administration API components on page 2 v Building applications with the administration API on page 3 v Administration API example program on page 5 v 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 Environment must be recompiled using the Tivoli Access Manager libraries. Backward compatibility is maintained on all the other supported platforms.

Administration API overview


You can use the administration API to administer the following types of objects: v Policies v Users v Groups v Access control lists (ACLs) v Extended ACL actions v Protected object policies (POPs) v Protected objects v Protected object spaces v Authorization rules v Domains v Web resources v Web resource groups v 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 defines data types to represent each object type. The API includes the function calls necessary for manipulating each of the data types. The administration API communicates directly with the Tivoli Access Manager policy server component. The API establishes an authenticated, Secure Sockets
Copyright IBM Corp. 2000, 2003

Layer (SSL) session with the Tivoli Access Manager policy server process. When the SSL session is established, the API can send administration requests to the policy server. The Tivoli Access Manager policy server component services these requests in the same manner that it would service any other incoming requests. System administrators also can use the pdadmin and svrsslcfg command line interfaces to accomplish Tivoli Access Manager administration tasks. The administration API functions map closely to these commands. Appendix C, Administration API equivalents, on page 353 describes the commands that match administration API functions. Some administration API functions do not have a pdadmin or svrsslcfg command line equivalent.

Administration API components


The administration API consists of the following components: v The administration API shared library v v v v The administration API header file The administration API library to link against (Microsoft Windows only) A demonstration application Makefiles for the demonstration application

Note: The administration APIs are 32-bit only. When running on operating systems that support 64-bit addressing, ensure that the administration APIs are invoked in 32-bit compatibility mode. The administration API shared libraries are distributed in the Tivoli Access Manager runtime environment for each platform. The remainder of the administration API components are distributed in the Tivoli Access Manager ADK component. The following sections provide more information about the shared libraries and ADK.

Administration API shared libraries


The administration API shared library is distributed in the Tivoli Access Manager runtime environment component. The administration APIs are 32-bit only. When running on operating systems that support 64-bit addressing, ensure that the administration APIs are invoked in 32-bit compatibility mode. Table 1 lists the names of the shared libraries on each platform.
Table 1. Shared libraries Platform Solaris Operating Environment IBM AIX

Shared Library Name libpdadminapi.so libpdadminapi.a libpdadminapi.sl pdadminapi.dll libpdadminapi.so

Hewlett-Packard HP-UX Microsoft Windows Linux

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Note: Due to a compiler problem, existing Tivoli SecureWay Policy Director, Version 3.8 applications compiled on the Sun Solaris Operating Environment must be recompiled using the Tivoli Access Manager libraries. Backward compatibility is maintained on all the other supported platforms.

Administration API application development kit


The ADK files are installed as part of the Tivoli Access Manager ADK component package. 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 Tivoli Access Manager installation directory) for each file.
Table 2. Administration API application developer kit files Suggested Directory include File to Install ivadminapi.h File Description The C header file containing the administration API function declarations. The C header file containing the prototypes and declarations for the functions, variables, and attributes that are deprecated in this version of Tivoli Access Manager. Avoid including this header file as the symbols provided in it will be removed in a future release of the product. lib admin_demo pdadminapi.lib pdadminapi_demo.c Makefile README.pdadminapi The library against which to link on the Microsoft Windows platform. This ADK provides a demonstration program and a sample makefile for each supported platform. You can place the demonstration program in any directory. The readme file explains how to build the demonstration program.

include

ivadmin_deprecated.h

Building applications with the administration API


To develop applications that use the Tivoli Access Manager administration API, you must install the required software and then link using the proper libraries.

Software requirements
You must install and configure an Tivoli Access Manager secure domain. If you do not have an Tivoli Access Manager secure domain installed, install one before beginning application development. The minimum installation consists of a single system with the following Tivoli Access Manager base components installed: v Tivoli Access Manager runtime environment v Tivoli Access Manager policy server v Tivoli Access Manager ADK

Chapter 1. Introducing the administration API

All systems in the Tivoli Access Manager secure domain that have the runtime environment installed must have the IBM Global Security Toolkit (GSKit) component installed on them as well. If the policy server is using an LDAP or Lotus Domino server as the user registry, the IBM SecureWay Directory client also must be installed on the system. For detailed installation instructions, refer to the section of the IBM Tivoli Access Manager Base Installation Guide relating to your operating system platform. If you already have an Tivoli Access Manager secure domain installed and want to add a development system to the domain, the minimum Tivoli Access Manager installation consists of the following components: v Tivoli Access Manager runtime environment v Tivoli Access Manager ADK

Linking required libraries


To compile applications that use the administration API, you must install the Tivoli Access Manager Application Developer Kit (ADK) component on the build machine. When compiling your application on Windows systems, make sure that you add the include directory for the Windows library to the compiler command line. When linking your application, specify the directory containing the administration API shared library if it is not in the default location. You must explicitly link against the shared library.

Tested compilers
IBM has tested the use of the Tivoli Access Manager Application Developer Kit (ADK) component with the compilers listed in Table 3. Previous versions of the compilers listed are not supported. Compilers on other supported platforms have not been tested.
Table 3. Compilers tested with Tivoli Access Manager Operating system platform tested IBM AIX 5.1 IBM AIX 5.2 Sun Solaris Operating Environment 8 Sun Solaris Operating Environment 9 Hewlett-Packard HP-UX 11.0 Hewlett-Packard HP-UX 11i Red Hat Enterprise Linux for xSeries SuSE Linux Enterprise Server 8 for pSeries and zSeries United Linux 1.0 Microsoft Windows 2000 Advanced Server Microsoft Windows 2003 Advanced Server Tested compiler IBM VisualAge C/C++ 5.0 Sun Forte 6.1 Ansi C/3.30 aC++ GNU GCC 3.2

Microsoft Visual C/C++ 6.0.5

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Administration API example program


The Tivoli Access Manager administration API ADK includes source for an example program that demonstrates use of the administration API. The example program demonstrates how to perform the following tasks: v Initialize an administration API security context v Display an error message v Create a new Tivoli Access Manager user v Set a user account to be valid v Change the password of the new user v Create a new group v Add the new user to the group v Delete a group v Delete a user v Delete the administration API security context See the sample makefile supplied with the sample program for build instructions specific to each supported operating system platform.

Deploying an administration API application


Applications that have been developed with the Tivoli Access Manager administration API must be run on systems that are configured as part of an Tivoli Access Manager secure domain. To run an administration API application, you must have installed the Tivoli Access Manager runtime environment. The Tivoli Access Manager runtime environment requires that the IBM SecureWay Directory client be installed on the application deployment system if an LDAP or Lotus Domino server is being used as the user registry. Administration API applications use the SSL protocol to communicate with the Tivoli Access Manager policy server. IBM Global Security Toolkit provides the necessary SSL support. The IBM Global Security Toolkit is installed as part of the product installation. Note: The Tivoli Access Manager runtime environment installation enforces installation of the required software. For installation instructions, see the appropriate section in the IBM Tivoli Access Manager Base Installation Guide for your operating system.

Gathering problem determination information


When developing an administration application, you might encounter a problem with Tivoli Access Manager. To assist Tivoli support personnel in diagnosing your problem, gather problem determination information relating to your error. Tivoli Access Manager components can be configured to log information to one or more trace files. You can enable tracing for the policy server, or any system using the Tivoli Access Manager runtime environment.

Chapter 1. Introducing the administration API

Enabling tracing on the policy server


To enable tracing on the policy server, edit the /etc/routing file, located in the installation directory for the Tivoli Access Manager policy server, and uncomment the last line. Shut down and restart the policy server daemon, pdmgrd.

Enabling tracing on a system using the runtime component


To enable tracing on the system where the error is occurring, edit the /etc/routing file, located in the installation directory for the Tivoli Access Manager runtime component, and uncomment the last line. Restart the application that encountered the error, or re-enter the pdadmin command that failed. After the failure occurs again, gather the trace logs as outlined in the next section.

Gathering trace and message logs


Trace and message log files for the policy server and Tivoli Access Manager runtime environment are usually written to the /log directory in the Tivoli Access Manager installation directory. However, if the Tivoli Common Directory is being used, the log files are located under the HPD directory in the Tivoli Common Directory. To determine the names of the trace log files, you need to determine the process identifier (PID) of the Tivoli Access Manager policy or authorization server. This information is recorded in files called ivmgrd.pid and ivacld.pid. To determine the PID for the policy server, check the contents of the ivmgrd.pid file:
cat ivmgrd.pid

Similarly, check the ivacld.pid file for the PID of the authorization server. After determining the PID, look in the AM_BASE/log directory for trace files with names of the form trace__pdmgrd.PID_trace_utf8.log for the policy server, or trace__pdacld.PID_trace_utf8.log for the authorization server. Also collect the following message files in the same directory:
msg__verbose.log msg__notice.log msg__fatal.log msg__warning.log msg__error.log

For a more complete discussion on messages, logging, and tracing, see the IBM Tivoli Access Manager for e-business Problem Determination Guide.

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Chapter 2. Using the administration API


Each application that uses the administration API must perform certain tasks necessary 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 10 v Setting object values on page 11 v v v v v Getting objects on page 12 Reading object values on page 12 Listing object information on page 13 Handling errors on page 14 Cleaning up and shutting down on page 16

Establishing security contexts


To use the administration API, you must first establish a Secure Sockets Layer (SSL) connection between the administration API application and the IBM Tivoli Access Manager (Tivoli Access Manager) policy server. The administration API refers to this connection as a security context. The security context provides for the secure transfer of requests and data between the administration API application and the Tivoli Access Manager policy server. Call the function ivadmin_context_createdefault2() to create a context with the default SSL configuration. The default SSL configuration is the SSL configuration used by the Tivoli Access Manager policy server. The function ivadmin_context_createdefault2() automatically accesses the following Tivoli Access Manager policy server configuration information: v SSL key-ring file location v SSL key-ring stash file location v Tivoli Access Manager policy server host name v Tivoli Access Manager policy server listening port When ivadmin_context_createdefault2() is run on the same system as the Tivoli Access Manager policy server, the preceding information is obtained from Tivoli Access Manager configuration files. When ivadmin_context_createdefault2() is run on another system in the Tivoli Access Manager secure domaina system that does not run the Tivoli Access Manager policy serverthe preceding information is obtained from stored information that was provided by the system administrator when the Tivoli Access Manager runtime environment was configured. There are two other functions that can be used for creating a security context. The ivadmin_context_create3() function creates a security context using the SSL
Copyright IBM Corp. 2000, 2003

configuration information provided with the function call, instead of using the same SSL configuration as the policy server. The ivadmin_context_createlocal() function creates a local context. Unlike other security contexts, a local context does not establish communication with any servers. A local context only can be used for manipulating configuration files using the ivadmin_cfg_* functions. A security context should be deleted using the ivadmin_context_delete() function when no longer needed. Free any storage associated with the security context, including the context pointer, using the ivadmin_free() function. This following sections further describe how to create a security context.

Required input parameters


You must provide the following information as input parameters when you call ivadmin_context_createdefault2(): v The administrative user ID to use when authenticating The user ID is the Tivoli Access Manager user ID. Tivoli Access Manager uses the underlying user registry to maintain this information. v The password for the administrator The administrative user ID and password must be established before calling ivadmin_context_createdefault2(). The user account and password are established during initial configuration of the Tivoli Access Manager runtime environment. v The domain name The name of the domain to which the administrative user ID belongs.

Handling of character data


Tivoli Access Manager internally represents all character data in Unicode Transformation Format 8 (UTF-8). Using UTF-8 ensures that character data is handled exactly the same regardless of what language or code page is used by the policy server, the authorization server, the user registry, or an application. The handling of character data is determined by the security context. The codeset option on the ivadmin_context_create3() and ivadmin_context_createlocal() functions can be used to indicate how character data is handled. The codeset option of IVADMIN_CODESET_LOCAL indicates that input character data is encoded using the current code page and must be converted to UTF-8 by Tivoli Access Manager before use. Output character data is converted back into the local code page before being returned. (This is the default handling of character data if the security context was created with a function other than ivadmin_context_create3() and ivadmin_context_createlocal() and the local code page is not UTF-8.) The codeset option of IVADMIN_CODESET_UTF8 indicates that the character data is already encoded in UTF-8 and that no input or output translation needs to be performed. If the local code page is UTF-8, no conversion of character data is performed by Tivoli Access Manager, regardless of how the security context was created.

Returned objects
The function ivadmin_context_createdefault2() returns the following data: v A pointer to a context object of type ivadmin_context

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

The context object contains all the information necessary to establish an SSL connection 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 by administration API function calls.

Example code
The following code fragment shows an example call of ivadmin_context_createdefault2() with the administrative user sec_master:
ivadmin_context ctx; ivadmin_response rsp; unsigned long status; status = ivadmin_context_createdefault2("sec_master", sec_masterpwd, domain_id, &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 compatibility
The administration API provides one other function that can create a context: ivadmin_context_create3(). This function provides backward compatibility with applications developed using older versions of Tivoli Access Manager. Applications should use the ivadmin_context_createdefault2() function to create a security context. The function ivadmin_context_create3() only provides a subset of the functions available in ivadmin_context_createdefault2(). It does not automatically determine the SSL configuration for the Tivoli Access Manager policy server and you must manually supply the necessary SSL configuration information.

Delegating user credentials


Each security context has a set of user credentials. The Tivoli Access Manager policy server examines these credentials when it is deciding whether to allow or deny a request for access to Tivoli Access Manager data. The credentials associated with a security context are those of the user specified to the ivadmin_context_create3() or ivadmin_context_createdefault2() function. You can use the administration API function ivadmin_context_setdelcred() to specify an alternative user credential to be used by the Tivoli Access Manager policy server to make access decisions. The specified credentials accompany all access requests in the secure context until the credentials are cleared and set again. The user must previously have authenticated and established credentials before the credentials can be delegated. To call ivadmin_context_setdelcred(), you must supply the following input parameters: v Privilege Attribute Certificate (PAC) data v PAC length You can use the Tivoli Access Manager authorization API function azn_creds_get_pac() to create PAC data from a credential. For more information

Chapter 2. Using the administration API

about establishing and using user credentials, see the IBM Tivoli Access Manager for e-business Authorization C API Developer Reference. You can call the function ivadmin_context_cleardelcred() to clear the delegated credentials. The ivadmin_context_hasdelcred() function can be used to determine if a context has set a delegated credential. See the following reference pages for information on these functions: v ivadmin_context_setdelcred() on page 159 v ivadmin_context_cleardelcred() on page 131 v ivadmin_context_hasdelcred() on page 157

Creating objects
You can use the administration API to create Tivoli Access Manager objects that are needed 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 context v Initialization values for data specific to the object, such as a users ID v 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 to ivadmin_user_create3():
unsigned long ivadmin_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 // );

input input input input input input input input input

security context Tivoli Access Manager user ID user registry distinguished name user registry common name user registry attribute surname user registry attribute password Number of user registry group memberships user registry group memberships SSO credentials policy (true/false) input - password policy enforced at creation (true/false) output - response object

Administration API functions that create objects return error conditions within an ivadmin_response object. For example, the administration API provides functions to create the following objects in Table 4.
Table 4. Creating objects Function ivadmin_acl_create() ivadmin_action_create() Description Creates a new access control list. Creates a new Tivoli Access Manager action.

10

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Table 4. Creating objects (continued) Function ivadmin_action_group_create() ivadmin_authzrule_create() ivadmin_domain_create() ivadmin_group_create2() ivadmin_objectspace_create() ivadmin_pop_create() ivadmin_protobj_create() ivadmin_ssocred_create() ivadmin_ssogroup_create() ivadmin_ssoweb_create() ivadmin_user_create3() Description Creates a new Tivoli Access Manager action group. Creates a new authorization rule. Creates a new secure domain. Creates a new Tivoli Access Manager group. Creates a new Tivoli Access Manager protected object space. Creates a new protected object policy. Creates a new protected object. Creates a single signon credential. Creates a single signon group resource. Creates a single signon Web resource. Creates a Tivoli Access Manager user.

Setting object values


You can use the administration API to set values within the data objects from the user 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, call ivadmin_user_setaccexpdate() to set an account expiration date for the user. v To modify values for existing objects For example, to modify the maximum password age for all user accounts, call ivadmin_context_setmaxpwdage(). To perform a set operation, you must have a valid context established between the administration 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 ivadmin_user_setdescription() ivadmin_user_setaccexpdate() ivadmin_context_setminpwdlen() Description Sets the description for the specified user Sets the expiration date for the specified user account Sets the minimum password length for all user accounts

Chapter 2. Using the administration API

11

Table 5. Example set operations (continued) Function ivadmin_acl_setuser() ivadmin_pop_setauditlevel() ivadmin_protobj_settype() Description Sets the entry for the user in the specified access control list Sets the audit reporting level for the specified protected object policy Sets the protected object type

Getting objects
The administration API defines a number of data types to contain Tivoli Access Manager data. You can use the administration API to obtain objects of each of the defined data types. You can then use administration API functions to examine the values contained in each object. The administration API get operations send a request to the Tivoli Access Manager policy 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 returns data describing the requested object to the client application through a secure communications channel. The application then constructs a copy of the object in local memory from the returned data. 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 by API get functions.
Table 6. Example data types returned by get functions Function ivadmin_acl_get() ivadmin_pop_get() ivadmin_user_get() ivadmin_group_get() ivadmin_protobj_get2() ivadmin_domain_get() ivadmin_authzrule_get() ivadmin_ssocred_get() ivadmin_ssogroup_get() ivadmin_ssoweb_get() Data Type Returned ivadmin_acl ivadmin_pop ivadmin_ldapuser ivadmin_ldapgroup ivadmin_protobj ivadmin_domain ivadmin_authzrule ivadmin_ssocred ivadmin_ssogroup ivadmin_ssoweb Object Description Access control list Protected object policy User information Group information Protected object Domain Authorization rule Resource credential Resource group Single signon Web resource

Reading object values


When you have established a context and obtained an object through a get operation, you can use the administration API to perform read operations on the data contained in the object. For example, when the application has obtained an ivadmin_ldapuser object, the application can use API functions to read the users distinguished name.

12

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Character data obtained from the object is returned in the codeset specified in the security context. For performance reasons, the administration API does not send read requests directly to the Tivoli Access Manager policy server. Performance is optimized by completing one get transaction through the security context to obtain the relevant object and then querying the contents of the object after it is stored on the local system. Table 7 shows some example operations that read values from a returned object.
Table 7. Example read operations Function ivadmin_user_getcn() ivadmin_user_getdn() ivadmin_user_getsn() ivadmin_group_getdescription() ivadmin_acl_getuser() ivadmin_pop_getauditlevel() Description Gets the common name from the specified ivadmin_ldapuser object. Gets the distinguished name from the specified ivadmin_ldapuser object. Gets the surname of the user from the specified ivadmin_ldapuser object. Gets the description entry for the group from the ivadmin_ldapgroup object. Gets the actions defined for a user from the ivadmin_acl object. Gets the audit level defined for the protected object policy (POP) from the ivadmin_pop object. Gets the identifier for the access control list (ACL) that is attached to the protected object from the ivadmin_protobj object. Gets the name of the domain from the ivadmin_domain object. Gets the ID of the specified authorization rule from the ivadmin_authzrule object. Gets the type of single signon resource associated with the credential from the ivadmin_ssocred object.

ivadmin_protobj_getaclid()

ivadmin_domain_getid() ivadmin_authzrule_getid() ivadmin_ssocred_gettype()

Listing object information


Some administrative tasks require the application to obtain a list of objects of one specific type. For example, an administrator might need to review the list of existing 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 take the following actions: v Communicate with the policy server through the secure context v 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 in local memory. Instead, they obtain an array of pointers to the relevant data type, or
Chapter 2. Using the administration API

13

to character data (which are names of listed items.) This enables list operations to extract only the important data from much larger data structures and return it to the client application. The client application must free all the data associated with the 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 form of an array of pointers to character strings:
unsigned long ivadmin_user_list( ivadmin_context ctx, const char *pattern, unsigned long maxreturn, unsigned long *count, char ***userids, ivadmin_response *rsp );

// // // // // //

input - Context to policy server input - Search pattern input - Maximum number of returned items output - Count of returned item output - Array of pointers to userIDs output - Response object

Use the ivadmin_free() function to free the memory used by the list when it is no longer needed. You must free the data associated with each character pointer and the array of pointers. Should the list operation encounter an error, the count is set to zero and the array of pointers is set to NULL.

Handling errors
The way an administration API call indicates that an error occured depends on how the API returns information. For the purposes of error handling, the administration 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 code to determine if the API was successful. If the API was unsuccessful and a response object is available, check the response object for additional information, as described in Evaluating a response object. Regardless of whether a return code is provided or not, if an administration API call was not successful, any output or return values are set to indicate that no information was returned: pointer arguments are set to NULL and counts and numeric values are set to zero.

Evaluating a response object


Many administration API calls return a pointer to an object of type ivadmin_response. ivadmin_response *rsp; Objects of type ivadmin_response are referred to as response objects and provide additional information regarding the operation. The response objects are initialized by the administration API to NULL.

14

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

If a response object is returned, examine the contents to obtain further information about the error. Use the ivadmin_response_getok() function to examine a response object. This function returns an unsigned long integer. This return value corresponds to one of the following constants, which are defined in ivadminapi.h:
#define IVADMIN_FALSE #define IVADMIN_TRUE 0 1

v If the call encountered an error, the response object contains the constant IVADMIN_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 use additional administration API functions to obtain information about the error. See the following sections for more information.

Obtaining error message text


To 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) from an 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 268 v ivadmin_response_getmessage() on page 269

Obtaining error codes


Use the following steps to display an Tivoli Access Manager value code that corresponds to each message that can be displayed with ivadmin_response_getmessage(). When you know the meaning of a particular value code, you can use this information to develop application logic specific to the particular error condition.
Chapter 2. Using the administration API

15

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); } 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 modifiers


Some administration API calls return a modifier that categorizes the returned message as one of the following types: v Information v Warning v Error The modifiers are defined as constants (unsigned longs):
#define IVADMIN_RESPONSE_INFO #define IVADMIN_RESPONSE_WARNING #define IVADMIN_RESPONSE_ERROR 0 1 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 specified message:
unsigned long = modifier; modifier = ivadmin_response_getmodifier(ivadmin_response rsp, unsigned long index);

Cleaning up and shutting down


Cleanup and shutdown of the administration API consists of freeing the memory and deleting the security contexts.

Freeing memory
The administration API provides the function ivadmin_free() for freeing memory that has been allocated by administration API calls. All memory that has been allocated by administration API calls must be freed using this function.
void ivadmin_free(void *p);

16

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

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 12. v An ivadmin_response object containing error information See Handling errors on page 14. You also must free character strings and array pointers that have been created by an administration API list function. Use the ivadmin_free function to free this memory as well. See Listing object information on page 13. for additional information on list operations.

Deleting a security context


The administration API application must close the connection, or security context, to the Tivoli Access Manager policy server before exiting. The context must be deleted so that the client system and the Tivoli Access Manager policy server can free the SSL resources. The administration API provides the function ivadmin_context_delete(). This function 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 the ivadmin_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);

Chapter 2. Using the administration API

17

18

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Chapter 3. Administering users and groups


The administration API provides a collection of functions for administering IBM Tivoli Access Manager (Tivoli Access Manager) users and groups. This chapter describes the tasks that those functions accomplish. Information about Tivoli Access Manager users and groups is stored in the user registry. You can use the administration API to both modify and access user and group settings in the user registry. The administration API provides functions to administer both individual user settings and global user settings. Tivoli Access Manager provides the pdadmin command line interface (CLI) that accomplishes many of the same user and group administration tasks. Application developers who have previously used the pdadmin command to manage an Tivoli Access Manager secure domain will find the administration API functions straightforward to implement. This chapter displays the pdadmin command line equivalent for each of the administration API function calls. You can review the output from the pdadmin command line equivalents to better understand the types of information returned by the administration APIs. See theIBM Tivoli Access Manager Base Administration Guide for detailed information on the pdadmin command. This chapter contains the following topics: v v v v v Administering Administering Administering Administering Administering users user accounts on page 20 user passwords on page 22 groups on page 23 group attributes on page 24

Administering users
The administration API provides functions for creating, accessing, deleting, and listing Tivoli Access Manager user information within the user registry. The function ivadmin_user_create3() creates a user in the user registry used by the Tivoli Access Manager policy server. Note: When a user definition already exists in the user registry, use the ivadmin_user_import2() function instead. The ivadmin_user_import2() function imports an existing user definition from the user registry into Tivoli Access Manager and allows the user definition to be managed by Tivoli Access Manager. Use the ivadmin_user_delete2() function to delete a user from Tivoli Access Manager. Table 8 on page 20 lists the user administration functions.

Copyright IBM Corp. 2000, 2003

19

User registry difference: Leading and trailing blanks in a user name do not make the name unique when using an LDAP or Active Directory user registry. However, leading and trailing blanks do make the user name unique when using a Domino server as a user registry. To keep name processing consistent regardless of what user registry is being used, do not define user names with leading or trailing blanks.
Table 8. Administrating users Function ivadmin_user_create3() ivadmin_user_delete2() ivadmin_user_import2() Description Creates the specified user. Deletes the specified user. Creates an Tivoli Access Manager user by importing an existing user from the user registry. Lists Tivoli Access Manager users. Lists users by using the user registrys distinguished name.

ivadmin_user_list() ivadmin_user_listbydn()

Administering user accounts


When a user account has been created in the user registry, you can set and get different pieces of information about the user. You must create a security context between the calling application and the Tivoli Access Manager policy server before you can access the user registry. You can obtain the user registry information for a user object by specifying either the user ID or the user distinguished name. Call the ivadmin_user_* group of API functions to establish security policies that apply to one specific Tivoli Access Manager user. Call the ivadmin_context_* group of API functions to establish security policies that apply to all Tivoli Access Manager users. When a policy is set for a specific user account by an ivadmin_user_* API call, and the same policy is set globally for all users by an ivadmin_context_* API call, the policy for the specific user account takes priority and is used. This is true regardless of whether the policy for the specific user is more or less restrictive than the global policy. Note: When both an ivadmin_user_* command and an ivadmin_context_* command exist with similar functionality, they are combined and alphabetized under the ivadmin_context_* command as shown in Table 9 on page 21. This section describes the API calls that you can use to modify or access the following data: v Account expiration date v Account disablement time interval v Maximum number of failed logins v Time of day access v User registry type v User objects

20

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

v v v v

User account-valid status User names (distinguished names, common names, and surnames) User descriptions Group memberships
Function Description Gets the account expiration date for user accounts. Gets the time to disable user accounts when the maximum number of login failures is exceeded. Gets the maximum number of failed logins allowed for user accounts. Gets the time of day access policy for user accounts. Determines which type of user registry is configured for the Tivoli Access Manager policy server. Sets the account expiration date for user accounts. Sets the time to disable for user accounts when the maximum number of login failures is exceeded. Sets the maximum number of failed logins allowed for user accounts. Sets the time of day access for the account for user accounts. Gets the user object. Takes userID (character string) as an input parameter. Returns an object of type ivadmin_ldapuser. This object contains a number of user registry attributes for the specified user. Returns the account-valid indicator for the specified user object. Gets the user object by using the distinguished name in the user registry. Returns an object of type ivadmin_ldapuser. Returns the common name attribute from the specified user. Returns the user description as a character string. Returns the distinguished name from the specified user. Lists the groups in which the specified user is a member. Returns the surname attribute for the specified user. Returns a setting that indicates if the user account has single signon capabilities. Enables or disables the specified user account.
Chapter 3. Administering users and groups

Table 9. Administrating user accounts

ivadmin_context_getaccexpdate() ivadmin_user_getaccexpdate() ivadmin_context_getdisabletimeint() ivadmin_user_getdisabletimeint() ivadmin_context_getmaxlgnfails() ivadmin_user_getmaxlgnfails() ivadmin_context_gettodaccess() ivadmin_user_gettodaccess() ivadmin_context_getuserreg()

ivadmin_context_setaccexpdate() ivadmin_user_setaccexpdate() ivadmin_context_setdisabletimeint() ivadmin_user_setdisabletimeint() ivadmin_context_setmaxlgnfails() ivadmin_user_setmaxlgnfails() ivadmin_context_settodaccess() ivadmin_user_settodaccess() ivadmin_user_get()

ivadmin_user_getaccountvalid() ivadmin_user_getbydn()

ivadmin_user_getcn() ivadmin_user_getdescription() ivadmin_user_getdn() ivadmin_user_getmemberships() ivadmin_user_getsn() ivadmin_user_getssouser() ivadmin_user_setaccountvalid()

21

Table 9. Administrating user accounts (continued) Function ivadmin_user_setdescription() ivadmin_user_setssouser() Description Sets the user description. Enables or disables the single signon capabilities of the Tivoli Access Manager user.

Administering user passwords


You can manage user access by setting password attributes. You can specify policies 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 or access password data and policies. Call the ivadmin_user_* group of API functions to establish security policies that apply to one specific Tivoli Access Manager user. Call the ivadmin_context_* group of API functions to establish security policies that apply to all Tivoli Access Manager users. When a policy is set for a specific user password by an ivadmin_user_* API call, and the same policy is set globally for all users by an ivadmin_context_* API call, the policy for the specific user password takes priority and is used. This is true regardless of whether the policy for the specific user password is more or less restrictive than the global policy. Note: When both a ivadmin_user_* command and a ivadmin_context_* command exist with similar functionality, they are combined and alphabetized under the ivadmin_context_* command in Table 10.
Table 10. Administrating user passwords Function ivadmin_context_getmaxpwdage() ivadmin_user_getmaxpwdage() ivadmin_context_getmaxpwdrepchars() ivadmin_user_getmaxpwdrepchars() ivadmin_context_getminpwdalphas() ivadmin_user_getminpwdalphas() ivadmin_context_getminpwdlen() ivadmin_user_getminpwdlen() ivadmin_context_setminpwdnonalphas() ivadmin_user_getminpwdnonalphas() ivadmin_context_getpwdspaces() ivadmin_user_getpwdspaces() ivadmin_context_setmaxpwdage() ivadmin_user_setmaxpwdage() ivadmin_context_setmaxpwdrepchars() ivadmin_user_setmaxpwdrepchars() Description Gets the maximum password age for user accounts. Gets the maximum number of repeated characters allowed in a password for user accounts. Gets the minimum number of alphabetic characters allowed in a password for user accounts. Gets the minimum password length for user accounts. Gets the minimum number of nonalphabetic characters allowed in a password for user accounts. Gets policy for whether spaces are allowed in passwords for user accounts. Sets the maximum password age for user accounts. Sets the maximum number of repeated characters allowed in a password for user accounts.

22

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Table 10. Administrating user passwords (continued) Function ivadmin_context_setminpwdalphas() ivadmin_user_setminpwdalphas() ivadmin_context_setminpwdlen() ivadmin_user_setminpwdlen() ivadmin_context_setminpwdnonalphas() ivadmin_user_setminpwdnonalphas() ivadmin_context_setpwdspaces() ivadmin_user_setpwdspaces() ivadmin_user_getpasswordvalid() ivadmin_user_setpassword() ivadmin_user_setpasswordvalid() Description Sets the minimum number of alphabetic characters allowed in a password for user accounts. Sets the minimum password length for user accounts. Sets the minimum number of nonalphabetic characters allowed in a password for user accounts. Sets policy for whether spaces are allowed in passwords for user accounts. Returns the enabled indicator for the users password. Sets the users password. Enables or disables the Tivoli Access Manager users password.

Administering groups
The administration API provides functions for creating, deleting, and listing the members 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 the group administration functions. User registry difference: Leading and trailing blanks in a group name do not make the name unique when using an LDAP or Active Directory user registry. However, leading and trailing blanks do make the group name unique when using a Domino server as a user registry. To keep name processing consistent regardless of what user registry is being used, do not define group names with leading or trailing blanks.
Table 11. Administering groups Function ivadmin_group_create2() ivadmin_group_import2() Creates a group. Creates an Tivoli Access Manager group by importing an existing group from the user registry. Deletes the specified group. Lists group names that match the specified pattern. Group names can be Tivoli Access Manager or user registry names. Description

ivadmin_group_delete2() ivadmin_group_list()

Chapter 3. Administering users and groups

23

Administering group attributes


The administration API allows you to administer the attributes of a group. Table 12 lists the group attribute administration functions.
Table 12. Administering group attributes Function ivadmin_group_get() ivadmin_group_getbydn() ivadmin_group_getcn() ivadmin_group_getdescription() ivadmin_group_getdn() ivadmin_group_getid() ivadmin_group_listbydn() ivadmin_group_setdescription() ivadmin_group_getmembers() ivadmin_group_addmembers() Description Gets the group object for the specified group name. Gets the group object for the specified distinguished name. Returns the group common name attribute for the specified group. Returns the group description. Returns the group distinguished name for the specified group. Returns the group ID for the specified group. Lists groups that match the specified pattern for distinguished names. Sets the group description. Lists the members of the group. Adds the specified users to the specified group. User registry difference: Attempting to add a duplicate user to a group is handled differently depending on what user registry is being used. See Appendix B, User registry differences, on page 349 for details. Removes the specified users from the specified group.

ivadmin_group_removemembers()

24

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Chapter 4. Administering protected objects and protected object spaces


You can use the administration API to create, modify, examine, list, and delete IBM Tivoli Access Manager (Tivoli Access Manager) protected objects. These protected objects represent resources that must be secured to enforce your security policy. You can specify the security policy by applying access control lists (ACLs), protected object policies (POPs), and authorization rules to the protected objects. Tivoli Access Manager protected objects exist within a virtual hierarchy known as a protected object space. Tivoli Access Manager provides several protected object spaces by default. You can use the administration API to define new regions of the protected object space and to define and secure resources that are specific to a third-party application. This chapter describes the administration API functions that you can use to administer 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 protected objects in the IBM Tivoli Access Manager Base Administration Guide. For an introduction to the use of ACLs, POPs, and authorization rules to secure protected objects, see the chapters about using access control policies, protected object policies, and authorization rules in the IBM Tivoli Access Manager Base Administration Guide. This chapter contains the following topics: v Administering protected object spaces v Administering protected objects on page 26 v Administering protected object attributes on page 27

Administering protected object spaces


You can use the administration API to create and administer a user-defined protected object space. You can use this protected object space to define a resource hierarchy that is specific to a third-party application that uses Tivoli Access Manager authorization services to enforce a security policy. User-defined object spaces created with the administration API are dynamic because they can be updated while Tivoli Access Manager is running. Table 13 on page 26 lists the methods available for administering protected object spaces. Note: For an introduction to the creation of protected object spaces, see the protected object space information in the IBM Tivoli Access Manager Base Administration Guide.

Copyright IBM Corp. 2000, 2003

25

Table 13. Administering protected object spaces Function ivadmin_objectspace_create() ivadmin_objectspace_delete() ivadmin_objectspace_list() Description Creates an Tivoli Access Manager protected object space. Deletes the specified Tivoli Access Manager protected object space. Lists the Tivoli Access Manager protected object spaces.

Administering protected objects


Define protected objects that reflect the resources that your security policy protects. Tivoli Access Manager defines two types of protected objects: container objects and resource objects. Understand these concepts before creating and administering protected 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 object hierarchy, which allows ACLs to be attached at the various points indicated by the forward slash character. After you create a protected object, you can specify a security policy for it by defining and attaching ACLs, POPs, authorization rules, or any combination of these entities. For more information about these Tivoli Access Manager security concepts, see the IBM Tivoli Access Manager Base Administration Guide. Use caution when implementing protected objects programmatically. In many cases, the protected object hierarchy is manually designed, built, and tested by a security expert. Carefully review the hierarchy to ensure that the security policy is correctly enforced. If you choose to build protected object hierarchies programmatically, be sure to test and review the settings for each object before deploying the security environment. Table 14 lists the methods available to administer protected objects.
Table 14. Administering protected objects Function ivadmin_protobj_attachacl() ivadmin_protobj_attachauthzrule() ivadmin_protobj_create() ivadmin_protobj_delete() ivadmin_protobj_detachacl() ivadmin_protobj_detachauthzrule() Description Attaches the specified access control list to the specified protected object. Attaches an authorization rule to the specified protected object. Creates a Tivoli Access Manager protected object. Deletes the specified Tivoli Access Manager protected object. Detaches the access control list from the specified protected object. Detaches an authorization rule from the specified protected object.

26

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Table 14. Administering protected objects (continued) Function ivadmin_protobj_get3() ivadmin_protobj_getaclid() ivadmin_protobj_geteffaclid() ivadmin_protobj_getpopid() ivadmin_protobj_geteffpopid() ivadmin_protobj_getauthzruleid() Description Gets the specified protected object. Gets the name of the ACL attached to the specified protected object. Gets the name of the ACL in effect for the specified protected object. Gets the name of the POP attached to the specified protected object. Gets the name of the POP in effect for the specified protected object. Gets the name of the authorization rule object that is attached to the specified protected object. Gets the name of the authorization rule object that is in effect for the specified protected object. Gets the description of the specified protected object. Gets the name of the specified protected object. Indicates whether a protected object policy or access control list can be attached to the specified protected object. Indicates whether a protected object exists. Indicates whether a specific action to a specific object is permitted. Indicates whether the specified actions to the specified objects are permitted. Gets the name of the protected object policy for the specified protected object. Returns the protected objects contained under the specified directory. Returns a list of protected objects that have the specified access control list attached. Sets the description field of the specified protected object. Sets whether a protected object policy or access control list can be attached to the specified protected object. Sets the type field of the specified protected object. Lists the protected objects that have the specified authorization rule attached.

ivadmin_protobj_geteffauthzruleid()

ivadmin_protobj_getdesc() ivadmin_protobj_getid() ivadmin_protobj_getpolicyattachable()

ivadmin_protobj_exists() ivadmin_protobj_access() ivadmin_protobj_multiaccess() ivadmin_protobj_getpopid() ivadmin_protobj_list3() ivadmin_protobj_listbyacl() ivadmin_protobj_setdesc() ivadmin_protobj_setpolicyattachable()

ivadmin_protobj_settype() ivadmin_protobj_listbyauthzrule()

Administering protected object attributes


The attributes for a protected object can be created, set, queried, and deleted.

Chapter 4. Administering protected objects and protected object spaces

27

Table 15 describes the methods for administering protected object attributes.


Table 15. Administering protected object attributes Function ivadmin_protobj_attrdelkey() Description Deletes the specified extended attribute (name and values) from the specified protected object. Deletes the specified value from the specified extended attribute key in the specified protected object. Returns the values associated with the specified extended attribute for the specified protected object. Lists all the extended attributes associated with the specified protected object. Creates an extended attribute with the specified name and value, if it does not already exist, and adds the attribute to the specified protected object. If the attribute specified already exists, the specified value is added to the existing attribute.

ivadmin_protobj_attrdelval()

ivadmin_protobj_attrget()

ivadmin_protobj_attrlist() ivadmin_protobj_attrput()

28

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Chapter 5. Administering access control


You can use the administration API to create, modify, examine, list, and delete IBM Tivoli Access Manager (Tivoli Access Manager) access control lists (ACLs). You can also use the administration API to attach ACLs to Tivoli Access Manager protected objects and to detach ACLs from protected objects. Each ACL might contain entries for specific users and groups. You can use the administration API to set ACL entries for users and groups that already exist in the Tivoli Access Manager secure domain. You also can use the administration API to set ACL entries for the default user categories any-other and unauthenticated. ACL entries consist of one or more permissions. These permissions specify actions that the owner of the entry is allowed to perform. Tivoli Access Manager provides a number of default permissions. You can use the administration API to define additional extended actions. You also can use the administration API to group the extended actions into action groups. Understand the construction and use of ACLs before using the administration API ACL functions. The proper use of ACLs is key to successfully implementing a security policy. For more information, see the chapter about using access control lists in the IBM Tivoli Access Manager Base Administration Guide. This chapter contains the following topics: v v v v v Administering Administering Administering Administering Administering access control lists access control list entries on page 30 access control list extended attributes on page 32 extended actions on page 33 action groups on page 32

Administering access control lists


ACLs enable you to grant or restrict specific users and groups access to protected resources. The administration API enables you to: v Create and delete ACLs v Retrieve or change information associated with an ACL v List the user, group, any-other, and unauthenticated entries that are included in the ACL v List all defined ACLs. The name of an ACL can be of any length. The following characters are allowed in an ACL name: v Alphanumeric characters defined in the locale v The underscore (_) character v The hyphen (-) character You specify the user entries that belong in each ACL. You also specify the permissions or actions that each user is allowed to perform.

Copyright IBM Corp. 2000, 2003

29

You can specify permissions or actions based on group membership, rather than individual user identity, to expedite administration tasks. The administration API defines the ivadmin_acl data type to contain a retrieved ACL. You can use administration API functions to extract information from the ivadmin_acl object. Be sure that you understand how to define an ACL policy before using the administration API ACL functions. For more information, see the section about ACL entry syntax in the IBM Tivoli Access Manager Base Administration Guide. Table 16 describes the methods for administering ACLs.
Table 16. Administering access control lists Function ivadmin_acl_create() ivadmin_acl_delete() ivadmin_acl_get() ivadmin_acl_getdescription() ivadmin_acl_getid() ivadmin_acl_list() ivadmin_acl_listgroups() ivadmin_acl_listusers() ivadmin_acl_setdescription() Description Creates a new ACL. Deletes the specified ACL. Returns the specified ACL. Returns the description of the specified ACL. Returns the name of the specified ACL. Returns the names of all the defined ACLs. Returns a list of group names included in the specified ACL. Returns a list of the user names included in the specified ACL. Sets or modifies the description for the specified ACL.

Administering access control list entries


You must create an ACL object before you can administer ACL entries for the object. To create an ACL object, see ivadmin_acl_create() on page 62. The administration API can be used to specify entries for each of the following ACL entry types: v Users v Groups v 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 Tivoli Access Manager secure domain but that does not have a separate entry in the ACL. The type unauthenticated applies to all user identities that are unknown to Tivoli Access Manager. Unknown users cannot authenticate into the Tivoli Access Manager secure domain. Be sure that you understand ACL entry syntax, ACL entry types, ACL ID attributes, and ACL permission (action) attributes before you use the administration API functions in this section.

30

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Tivoli Access Manager supports 18 default actions. For a list of the default Tivoli Access Manager actions, see the section about default Tivoli Access Manager permissions for actions in the IBM Tivoli Access Manager Base Administration Guide. For more information, see the section about ACL entry syntax in the IBM Tivoli Access Manager Base Administration Guide. Table 17 lists the methods for administering ACL entries.
Table 17. Administering access control list entries Function ivadmin_acl_getanyother() ivadmin_acl_getunauth() Description Returns the actions defined in the entry for the user type any-other in the specified ACL. Returns the actions (permissions) defined in the entry for the user type unauthenticated in the specified ACL. Returns the actions (permissions) defined in the entry for the specified user in the specified ACL. Returns the actions (permissions) defined in the entry for the specified group in the specified ACL. Removes the ACL entry for the any-other user from the specified ACL. Removes the ACL entry for the specified group from the specified ACL. Removes the ACL entry for the unauthenticated user from the specified ACL. Removes the ACL entry for the specified user from the specified ACL. Sets or modifies the ACL entry for the any-other user in the ACL. Call this function to specify permissions for all authenticated users that do not have a separate user or group entry in the specified ACL. ivadmin_acl_setgroup() ivadmin_acl_setunauth() Sets or modifies the ACL entry for the specified group in the specified ACL. Sets the ACL entry for the unauthenticated user in the specified ACL. Call this function to specify permissions for those users that have not been authenticated. ivadmin_acl_setuser() Sets the entry for the specified user in the specified ACL. Use this to specify the actions that a user is permitted to perform.

ivadmin_acl_getuser()

ivadmin_acl_setuser()

ivadmin_acl_removeanyother() ivadmin_acl_removegroup() ivadmin_acl_removeunauth() ivadmin_acl_removeuser() ivadmin_acl_setanyother()

Chapter 5. Administering access control

31

Administering access control list extended attributes


Extended attributes for an ACL can be obtained, set, and deleted. Table 18 lists the methods available for administering ACL extended attributes.
Table 18. Administering access control list extended attributes Function ivadmin_acl_attrdelkey() ivadmin_acl_attrdelval() ivadmin_acl_attrget() Description Deletes the specified extended attribute key from the specified ACL. Deletes the specified value from the specified extended attribute key in the specified ACL. Gets the extended attribute values for the specified extended attribute key from the specified ACL. Lists the extended attribute keys associated with the specified ACL. Creates an extended attribute with the specified name and value, if it does not already exist, and adds the attribute to the specified ACL. If the attribute specified already exists, the specified value is added to the existing attribute.

ivadmin_acl_attrlist() ivadmin_acl_attrput()

Administering action groups


You can use the administration API to create, examine, and delete new action groups. Each action group can contain up to 32 actions. The default action group, referred to as the primary action group, contains the 18 predefined Tivoli Access Manager actions. Thus, you can create up to 14 new actions to the primary group. When you need to create more than 32 actions, you can use the administration API to define a new action group. Tivoli Access Manager supports up to 32 action groups. For more information about action groups, see the section about creating extended ACL actions and action groups in the IBM Tivoli Access Manager Base Administration Guide. Table 19 lists the methods for administering action groups.
Table 19. Administering action groups Function ivadmin_action_create_in_group() Description Defines a new action (permission) code in the specified action group. Call this function to add an action code to a user-defined extended action group. Deletes an action (permission) code from the specified action group. Creates a new action group with the specified name. Deletes the specified action group and all the actions that belong to the specified group. Lists all the defined action group names.

ivadmin_action_delete_from_group() ivadmin_action_group_create() ivadmin_action_group_delete() ivadmin_action_group_list()

32

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Table 19. Administering action groups (continued) Function ivadmin_action_list_in_group() Description Lists all the defined action (permission) codes from the specified action group.

Administering extended actions


Tivoli Access Manager provides a default set of actions (permissions) that belong to the primary action group that can be granted to users or groups. You can use the administration API to define new, extended actions that supplement the set of default actions. Each of the extended actions can belong to the primary action group or to a custom action group. Extended actions are typically defined to support actions that are specific to a third-party application. For more information about extended actions, see the section about creating extended ACL actions and action groups in the IBM Tivoli Access Manager Base Administration Guide. Table 20 lists the methods for administering extended actions.
Table 20. Administering extended actions Function ivadmin_action_create() ivadmin_action_delete() ivadmin_action_getdescription() ivadmin_action_getid() ivadmin_action_gettype() ivadmin_action_list() Description Defines a new action (permission)codein the specified action group. Deletes an action (permission) code from the specified action group. Returns the description for the specified action. Returns the code for the specified action. Returns the type for the specified action. Lists all the defined action (permission) codes for the specified action group.

Chapter 5. Administering access control

33

34

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Chapter 6. Administering protected object policies


You can use the administration API to create, modify, examine, and delete IBM Tivoli Access Manager (Tivoli Access Manager) protected object policies (POPs). You can also use the Administration API to attach or detach POPs from protected objects. You can use POPs to impose additional conditions on operations that are permitted by an access control list (ACL) policy. These additional conditions are enforced regardless of the user or group identities specified in the ACL entries. Examples of additional conditions include the following: v v v v v Specifying the quality of protection Writing a report record to the auditing service Requiring an authentication strength level Restricting access to a specific time period Enabling or disabling warning mode, which allows an administrator to validate security policy

Be sure that you understand Tivoli Access Manager POPs before using the administration API to administer POPs. For more information, see the chapter about using POPs in the IBM Tivoli Access Manager Base Administration Guide. This chapter contains the following topics: v Administering protected object policy objects v Administering protected object policy settings on page 36 v Administering protected object policy extended attributes on page 37

Administering protected object policy objects


POP objects are administered in a similar way to ACL policies. You can create and configure 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 retrieved POP. You can use administration API functions to extract data from the ivadmin_pop objects. You do not need to know the internal structure of the ivadmin_pop data type. Table 21 lists the methods for administering protected object policy objects.
Table 21. Administering protected object policy objects Function ivadmin_pop_create() ivadmin_pop_delete() ivadmin_pop_detach() ivadmin_pop_find() Description Creates a POP object with the default values. Deletes the specified POP. Detaches a POP from the specified protected object. Finds and lists all protected objects that have the specified POP attached.

Copyright IBM Corp. 2000, 2003

35

Table 21. Administering protected object policy objects (continued) Function ivadmin_pop_get() ivadmin_pop_list() Description Gets the specified POP object. Call this function to get an object of type ivadmin_pop. Lists all POP objects.

Administering protected object policy settings


You 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 POP object, see ivadmin_pop_create() on page 205. You can use administration API functions to specify the following POP attributes: v Authentication levels v Quality of Protection (QOP) requirements v Auditing levels v Time of day access restrictions v Warning mode settings Authentication levels specify whether additional or alternative authentication is required to access a protected object. The additional authentication is also called step-up authentication. This means that an additional authentication step is required, in order to access resources that require more restrictive access policies. When using step-up authentication, you can either filter users based on IP address or you can specify step-up authentication for all users, regardless of IP address. Call ivadmin_pop_setanyothernw() or ivadmin_pop_setipauth() to specify step-up authentication policy for objects requiring authentication-sensitive authorization. When using step-up authentication, you can either filter users based on IP address or you can specify step-up authentication for all users, regardless of IP address. Call ivadmin_pop_setanyothernw() or ivadmin_pop_setipauth() when you want to 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, see the section about authentication strength POP policy (step-up) in the IBM Tivoli Access Manager for e-business Web Security Developer Reference. The quality of protection (QOP) level is not enforced internally by Tivoli Access Manager. Applications that set the quality of protection can enforce it. Audit levels specify what operations generate an audit record. This value is used internally by Tivoli Access Manager and also can be used by applications to generate their audit records. The time of day access setting is used to control access to a protected object based on the time when the access occurs. The warning mode enables a security administrator to troubleshoot the authorization policy set on the protected object space.

36

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

When you set the warning attribute to yes, any action is possible by any user on the object where the POP is attached. Any access to an object is permitted even if the ACL policy attached to the object is set to deny this access. Audit records are generated that capture the results of all ACL policies with warning mode set throughout the object space. The audit log shows the outcome of an authorization decision as it would have been made if the warning attribute had been set to no. Table 22 lists the methods for administering protected object policy settings.
Table 22. Administering protected object policy settings Function ivadmin_pop_getanyothernw() Description Gets the anyothernw, or any other network, setting for the IP authentication level from the specified POP. Gets the audit level for the specified POP. Gets the description of the specified POP. Gets the IP endpoint authentication setting in the specified POP. Gets the name of the specified POP. Gets the quality of protection (QOP) level for the specified POP. Gets the time of day range for the specified POP. Gets the warning mode value from the specified POP. Removes the ipauth access setting for authentication level from the specified POP. Sets the anyothernw setting for authentication level from the specified POP. Sets the anyothernw access setting to forbidden for the specified POP. Sets the audit level for the specified POP. Sets the description of the specified POP. Sets the ipauth setting for authentication level in the specified POP. Sets the ipauth setting for authentication level to forbidden in the specified POP. Sets the quality of protection level for the specified POP. Sets the time of day range for the specified POP. Sets the warning mode for the specified POP.

ivadmin_pop_getauditlevel() ivadmin_pop_getdescription() ivadmin_pop_getipauth() ivadmin_pop_getid() ivadmin_pop_getqop() ivadmin_pop_gettod() ivadmin_pop_getwarnmode() ivadmin_pop_removeipauth() ivadmin_pop_setanyothernw() ivadmin_pop_setanyothernw_forbidden() ivadmin_pop_setauditlevel() ivadmin_pop_setdescription() ivadmin_pop_setipauth() ivadmin_pop_setipauth_forbidden() ivadmin_pop_setqop() ivadmin_pop_settod() ivadmin_pop_setwarnmode()

Administering protected object policy extended attributes


You can use the administration API to set, modify, or remove extended attributes in a POP.

Chapter 6. Administering protected object policies

37

Table 23 lists the methods for administering protected object policy extended attributes
Table 23. Administering protected object policy extended attributes Function ivadmin_pop_attrdelkey() ivadmin_pop_attrdelval() ivadmin_pop_attrget() ivadmin_pop_attrlist() ivadmin_pop_attrput() Description Deletes the specified extended attribute from the specified POP. Deletes the specified value from the specified extended attribute key in the specified POP. Gets the values for the specified extended attribute from the specified POP. Lists the extended attributes associated with the specified POP. Sets the value for the specified extended attribute in the specified POP.

38

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Chapter 7. Administering authorization rules


Authorization rules are conditions or standards contained in an authorization policy that are used to make access decisions based upon attributes such as user, application, and environment context. Authorization rules are defined to specify conditions that must be met before access to a protected object is permitted. A rule is created using a number of boolean conditions that are based on data supplied to the authorization engine within the user credential, from the resource manager application, or from the encompassing business environment. A Tivoli Access Manager authorization rule is a policy type similar to an access control list (ACL) or a protected object policy (POP). The rule is stored as a text rule within a rule policy object and is attached to a protected object in the same way and with the same constraints as ACLs and POPs. The Tivoli Access Manager administration API provides functions to create, delete, modify, list, and get authorization rules For more information on authorization rules, see the IBM Tivoli Access Manager Base Administration Guide. Use the functions shown in Table 24 to administer authorization rule objects.
Table 24. Administering authorization rules Function ivadmin_authzrule_create() ivadmin_authzrule_delete() ivadmin_authzrule_get() ivadmin_authzrule_getid() ivadmin_authzrule_getdescription() ivadmin_authzrule_getfailreason() ivadmin_authzrule_getruletext() ivadmin_authzrule_list() ivadmin_authzrule_setdescription() ivadmin_authzrule_setruletext() ivadmin_authzrule_setfailreason() Description Creates the specified authorization rule object. Deletes the specified authorization rule object. Gets the specified authorization rule object. Gets the ID for the specified authorization rule. Gets the description for the specified authorization rule. Gets the fail reason, if any, for the specified authorization rule. Gets the rule text for the specified authorization rule. Lists all of the registered authorization rules. Sets the description for the specified authorization rule. Sets the authorization rule text. Sets the authorization rule fail reason.

Copyright IBM Corp. 2000, 2003

39

40

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Chapter 8. Administering single signon resources


You can use the administration API to administer resources that enable an IBM Tivoli Access Manager (Tivoli Access Manager) user to obtain single signon (SSO) capability across more than one Web server. This capability requires the use of Tivoli Access Manager WebSEAL junctions. You can use the administration API to create, modify, examine, and delete the following types of resources: v Administering Web resources v Administering resource groups v Administering resource credentials Be sure that you understand Tivoli Access Manager single signon support before you use the administration API to administer single signon resources. For more information about administering single signon capability across junctioned Web server resources, see the section about user registry resource management commands in the IBM Tivoli Access Manager Base Administration Guide and the section about using global signon (GSO) in the IBM Tivoli Access Manager for e-business Web Security Developer Reference. This chapter contains the following topics: v Administering Web resources v Administering resource groups on page 42 v Administering resource credentials on page 43

Administering Web resources


A Web resource is a Web server that serves as the backend of an Tivoli Access Manager WebSEAL junction. An application on the joined Web server can require users to authenticate specifically to the application. The authentication information, such as user name and password, often differs from the authentication information used by Tivoli Access Manager. The junctioned Web server thus requires an authenticated Tivoli Access Manager user to log in again, using the user name and password specific to the application on the joined Web server. You can use the administration API to configure Tivoli Access Manager so that Tivoli Access Manager users need to authenticate only one time. You must define a Web resource (server) and then define a user-specific resource credential that contains 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 Administering resource credentials on page 43. Note: The administration API does not perform all WebSEAL junction configuration tasks through the API. Use the pdadmin commands to modify the junction definitions. For more information, see the IBM Tivoli Access Manager for e-business WebSEAL Administration Guide.
Copyright IBM Corp. 2000, 2003

41

Table 25 lists the methods for administering Web resources.


Table 25. Administering Web resources Function ivadmin_ssoweb_create() ivadmin_ssoweb_delete() ivadmin_ssoweb_get() ivadmin_ssoweb_getdescription() ivadmin_ssoweb_getid() ivadmin_ssoweb_list() Description Creates a single signon Web resource. Deletes the specified single signon Web resource. Returns the specified single signon Web resource. Returns the description of the specified single signon Web resource. Returns the name (identifier) of the specified single signon Web resource. Returns a list of all of the single signon Web resource names.

Administering resource groups


A resource group is a group of Web servers, all of which have been junctioned to an Tivoli Access Manager WebSEAL server and all of which use the same set of user IDs and passwords. You can use the administration API to create resource groups. You can then create a single resource credential for all the resources in the resource group. This enables you to simplify the management of Web resources by grouping similar Web resources into resource groups. You can also use the administration API to add more Web resources, when necessary, to an existing resource group. Table 26 lists the methods for administering resource groups.
Table 26. Administering resource groups Function ivadmin_ssogroup_addres() ivadmin_ssogroup_create() ivadmin_ssogroup_delete() ivadmin_ssogroup_get() ivadmin_ssogroup_getdescription() ivadmin_ssogroup_getid() ivadmin_ssogroup_getresources() Description Adds a single signon resource to a single signon resource group. Creates a single signon group resource. Deletes a single signon group resource. Returns the specified single signon group resource. Returns the description of the single signon group resource. Returns the name of the single signon group resource. Returns a list of the member single signon resource names for the specified single signon group. Returns a list of all of the single signon group resource names.

ivadmin_ssogroup_list

42

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Table 26. Administering resource groups (continued) Function ivadmin_ssogroup_removeres() Description Removes a single signon resource from the specified single signon resource group.

Administering resource credentials


A resource credential provides a user ID and password for a single signon user-specific resource, such as a Web server or a group of Web servers. The Web resource or group of Web resources must exist before you can apply resource credentials to it. Resource credential information is stored in the users Tivoli Access Manager entry in the user registry. You can use the administration API to create, modify, examine, and delete resource credentials. Table 27 lists the methods for administering credentials.
Table 27. Administering credentials Function ivadmin_ssocred_create() ivadmin_ssocred_delete() ivadmin_ssocred_get() ivadmin_ssocred_getid() ivadmin_ssocred_getssopassword() ivadmin_ssocred_getssouser() Description Creates a single signon credential. Deletes a single signon credential. Returns the specified single signon credential. Returns the name of the single signon resource associated with this credential. Returns the password associated with this single signon credential. Returns the name of the resource user associated with the specified single signon credential. Returns the type of the single signon resource associated with the specified single signon credential. Returns the name of the Tivoli Access Manager user associated with this single signon credential. Returns the list of single signon credentials for the specified user. Modifies a single signon credential.

ivadmin_ssocred_gettype()

ivadmin_ssocred_getuser()

ivadmin_ssocred_list() ivadmin_ssocred_set()

Chapter 8. Administering single signon resources

43

44

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Chapter 9. Administering domains


A Tivoli Access Manager policy server domain consists of all the physical resources that require protection along with the associated security policy used to protect those resources. Any security policy implemented in a domain affects only those resources in that domain. Multiple domains can exist simultaneously within a Tivoli Access Manager installation. Data is securely partitioned between domains. A user or process must authenticate to a specific domain in order to access data contained within it. Each Tivoli Access Manager installation contains a single management domain. A user must be authenticated to the management domain in order to create, delete, list or modify other domains. The authorization API provides functions that can be used to manage domains. For more information on the management of domains, see the IBM Tivoli Access Manager Base Administration Guide. Table 28 lists the methods for administering domains.
Table 28. Administering domains Function ivadmin_domain_create() ivadmin_domain_delete() ivadmin_domain_get() ivadmin_domain_getdescription() ivadmin_domain_getid() ivadmin_domain_list() Description Creates a new Tivoli Access Manager domain. Deletes the specified Tivoli Access Manager domain. Gets the specified Tivoli Access Manager domain object. Gets the description for the specified Tivoli Access Manager domain. Gets the name of the specified Tivoli Access Manager domain. Lists the names of all the Tivoli Access Manager domains, with the exception of the management domain. Changes the description for the specified Tivoli Access Manager domain.

ivadmin_domain_setdescription()

Copyright IBM Corp. 2000, 2003

45

46

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Chapter 10. Configuring application servers


You can use the administration API to configure and unconfigure authorization and administration API servers, modify configuration parameters, administer replicas, and perform certificate maintenance. These APIs are used by the svrsslcfg command line utility instead of the pdadmin command line utility. The svrsslcfg utility is used to perform the necessary configuration steps that allow an application to use a secure sockets layer (SSL) connection for communicating with the policy server or the authorization server. It is not intended to do all of the configuration that may be required to ensure a correctly functioning application. For more information about the svrsslcfg utility, see the section about using svrsslcfg in the IBM Tivoli Access Manager for e-business Command Reference. Note: The local host name is used to build a unique name for the application. In some cases, depending on the TCP/IP configuration, the host name is not always consistent and might result in look-up failures. For example, the operating system might return the fully qualified host name while another machine might just return the host name. If this happens in your network, use the following format to specify the server name to the command line interface:
server_name/desired_host_name

For the API, these parameters are separate. There, desired_host_name should be specified for the host_name parameter. This chapter contains the following topics: v Configuring application servers v Administering replicas on page 48 v Certificate maintenance on page 48

Configuring application servers


Use the configuration commands to enable an application server (an application that uses the authorization or administration API) to communicate with the policy server or the authorization server. An administrative user identity (for example, sec_master) and password must be specified for connecting to the policy server.
Table 29. Configuring application servers Function ivadmin_cfg_configureserver3() Description Configures an application server by updating the configuration file and creating the key-ring file. Sets or resets the enable-listening parameter in the configuration file. Changes the listening port number of the application and updates the port number in the configuration file. Unconfigures an application server.

ivadmin_cfg_setlistening2() ivadmin_cfg_setport2()

ivadmin_cfg_unconfigureserver()

Copyright IBM Corp. 2000, 2003

47

Administering replicas
Table 30. Administering replicas Function ivadmin_cfg_addreplica2() ivadmin_cfg_chgreplica2() ivadmin_cfg_rmvreplica2() Description Adds a replica entry to the configuration file. Changes parameters of a replica entry in the configuration file. Removes a replica entry from the configuration file.

Certificate maintenance
Only use ivadmin_cfg_renewservercert() when the certificate has been compromised or when the automatic certificate refresh logic fails.
Table 31. Certificate maintenance Function ivadmin_cfg_renewservercert() Description Renews the server SSL certificate.

48

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Chapter 11. Administering servers


You can use the administration API to get a list of tasks from the server, send a specific task to an authorization server, and notify replica databases, either automatically or manually, when the master authorization database is updated. This chapter contains the following topics: v Getting and performing administration tasks v 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 tasks


You can send an administration task to a server. You also can request a list of all supported administration tasks from a server. The caller must have credentials with sufficient permission to perform the task. For more information, see the IBM Tivoli Access Manager for e-business Authorization C API Developer Reference.

Notifying replica databases when the master authorization database is updated


When an administrator makes security policy changes, the policy server makes adjustments to the master authorization database to reflect these changes. To ensure that these changes also are dispersed to any authorization servers with replica 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 intervals for updates. By default, polling is disabled. For more information about polling the master authorization database, see the cache-refresh-interval option described in the IBM Tivoli Access Manager for e-business Authorization C API Developer Reference. v Enable the policy server to notify authorization servers each time that the master authorization database is updated. This automatic process is recommended for environments where database changes are infrequent. For more information, see Notifying replica databases automatically on page 50. v Notify authorization servers, on demand, after you make updates to the master authorization database. This manual process is recommended for environments where database changes are frequent and involve substantial changes. For instructions, see Notifying replica databases manually on page 50. 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 on the policy server. For more information, see Setting the maximum number of notification threads on page 50 and Setting the notification wait time on page 50.

Copyright IBM Corp. 2000, 2003

49

Notifying replica databases automatically


You can enable the policy server to send notifications to authorization servers each time that the master authorization database is updated. In turn, the authorization servers automatically request a database update from the policy server. To enable automatic database updates, edit the ivmgrd.conf file on the policy server 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 setting is recommended for environments where the master database is changed infrequently. To turn off automatic notification, specify no.

Notifying replica databases manually


When the master authorization database is updated, you can use the ivadmin_server_replicate() function to send notification to application servers that are configured to receive database update notifications. You can indicate that a specific server receive update notifications, or specify NULL, which notifies all configured authorization servers in the secure domain. If you specify a server name, you are notified whether the server was replicated successfully or if a failure occurred. If you do not specify a server name, return codes indicate whether or not the policy server started notifying authorization servers in your secure domain. Note that unless you specify the server-name option, you are not notified when an authorization servers database was replicated successfully.

Setting the maximum number of notification threads


When the master authorization database is updated, this update is announced to replica databases through the use of notification threads. Each replica then has the responsibility of downloading the new data from the master authorization database. You can edit the ivmgrd.conf file to set a value for the maximum number of notification threads. This number is calculated based on the number of replica databases in your secure domain. For example, if you have 10 replica databases and want to notify them of master database changes simultaneously, specify a value 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 time


There is a time delay between when the policy server updates the master authorization database and when notification is sent to database replicas. If you added auto-database-update-notify = yes to the ivmgrd.conf file as described in Notifying replica databases automatically on page 50, you can set this period of time. To do so, edit the notifier-wait-time value in the ivmgrd.conf file. For example, if you are making batch changes to the master authorization database, it is advisable to wait until all changes have been made before policy changes are sent to database replicas. Therefore, you might decide to increase the default value from 15 seconds to 25 seconds as shown:
[ivmgrd] notifier-wait-time = 25

50

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

By editing the value for this attribute, the policy server is prevented from sending individual replica notifications for each of a series of database changes.

Administrating servers and database notification


Table 32. Administrating servers and database notification Function ivadmin_server_gettasklist() ivadmin_server_performtask() ivadmin_server_replicate() Description Gets the list of tasks from the server. Sends a command to an authorization server. Notifies authorization servers to receive database updates.

Chapter 11. Administering servers

51

52

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Chapter 12. Administration C API reference


The APIs in this chapter are presented alphabetically by name. Refer to Conventions used in this book on page xix for a description of the conventions used to illustrate commands.

Copyright IBM Corp. 2000, 2003

53

ivadmin_accessOutdata_getAccessResult()
Interprets the result from the ivadmin_protobj_access() and ivadmin_protobj_multiaccess() functions and returns the access result, which indicates whether a specified user is permitted the specified access to the specified object.

Syntax
unsigned long ivadmin_accessOutdata_getAccessResult( ivadmin_accessOutdata outdata);

Parameters
Input outdata Pointer to an ivadmin_Outdata structure previously returned from either the ivadmin_protobj_access() or ivadmin_protobj_multiaccess() function.

Description
Indicate whether the user has the specified access to the specified object. Free this structure when it is no longer needed.

Return Values
Returns the following values: AZN_C_PERMITTED Indicates the user has the necessary access. AZN_C_NOT_PERMITTED Indicates the user does not have the necessary access.

54

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_accessOutdata_getPermInfo()
Interprets the result from the ivadmin_protobj_access() and ivadmin_protobj_multiaccess() functions and returns the permission information, if any, associated with an access request to an object.

Syntax
azn_attrlist_h_t ivadmin_accessOutdata_getPermInfo( ivadmin_accessOutdata outdata);

Parameters
Input outdata Pointer to an ivadmin_Outdata structure previously returned from either the ivadmin_protobj_access() or ivadmin_protobj_multiaccess() function.

Description
Returns the supplemental permission information (azn_attrlist_h_t structure) associated with the specified ivadmin_Outdata object. Free this structure when it is no longer needed.

Return Values
Returns the supplemental permission information (azn_attrlist_h_t structure) associated with the specified ivadmin_Outdata object.

Chapter 12. Administration C API reference

55

ivadmin_accessOutdata_getResponseInfo()
Returns the response information associated with an access request for an object.

Syntax
ivadmin_response ivadmin_accessOutdata_getResponseInfo( ivadmin_accessOutdata outdata);

Parameters
Input outdata Pointer to an ivadmin_Outdata structure previously returned from either the ivadmin_protobj_access() or ivadmin_protobj_multiaccess() function.

Description
Returns the response information associated with the a specific access request to a specific object. Free this structure when it is no longer needed.

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

56

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_acl_attrdelkey()
Deletes the specified extended attribute key from the specified access control list.

Syntax
unsigned long ivadmin_acl_attrdelkey( ivadmin_context ctx, char *aclid, char *attr_key, ivadmin_response *rsp );

Parameters
Input ctx aclid attr_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. The context used to communicate with the Tivoli Access Manager policy server. The name of the access control list. The extended attribute to delete.

Description
Deletes the specified extended attribute key from the specified access control list. Command line equivalent:
pdadmin acl modify ACL_name delete attribute attribute_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

57

ivadmin_acl_attrdelval()
Deletes the specified value from the specified extended attribute key in the specified access control list.

Syntax
unsigned long ivadmin_acl_attrdelval( ivadmin_context ctx, char *aclid, char *attr_key, char *attr_value, ivadmin_response *rsp );

Parameters
Input ctx aclid attr_key attr_value The context used to communicate with the Tivoli Access Manager policy server. The name of the access control list. The extended attribute key. The 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.

Description
Deletes the specified value from the specified extended attribute key in the specified access control list. Command line equivalent:
pdadmin acl modify ACL_name delete attribute attribute_name attribute_value

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

58

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_acl_attrget()
Gets the extended attribute value for the specified extended attribute key from the specified access control list.

Syntax
unsigned long ivadmin_acl_attrget( ivadmin_acl acl, char *attr_key, unsigned long *count, char ***attr_value );

Parameters
Input acl attr_key Output count attr_value The number of values returned. Zero is returned if an error occurs. An array of pointers to the values returned. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. The ivadmin_acl object. This object contains the access control list. The attribute key to look up.

Description
Gets the extended attribute values for the specified extended attribute key from the specified access control list. Command line equivalent:
pdadmin acl show ACL_name attribute attribute_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

59

ivadmin_acl_attrlist()
Lists the extended attribute keys associated with the specified access control list.

Syntax
unsigned long ivadmin_acl_attrlist( ivadmin_acl acl, unsigned long *count, char ***attr_list );

Parameters
Input acl Output count attr_list The number of extended attributes returned. Zero is returned if an error occurs. An array of pointers to the extended attributes returned. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. The ivadmin_acl object. This object contains the access control list.

Description
Lists the extended attribute keys associated with the specified access control list. Command line equivalent:
pdadmin acl list ACL_name attribute

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

60

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_acl_attrput()
Sets the extended attribute value for the specified extended attribute key in the specified access control list.

Syntax
unsigned long ivadmin_acl_attrput( ivadmin_context ctx, char *aclid, char *attr_key, char *attr_value, ivadmin_response *rsp );

Parameters
Input ctx aclid attr_key attr_value 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the access control list. The extended attribute key for which you want to set a value. The value to set.

Description
Sets the extended attribute value for the specified extended attribute key in the specified access control list. Command line equivalent:
pdadmin acl modify ACL_name set attribute attribute_name attribute_value

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

61

ivadmin_acl_create()
Creates a new access control list.

Syntax
unsigned long ivadmin_acl_create( ivadmin_context ctx, const char *aclid, ivadmin_response *rsp );

Parameters
Input ctx aclid The context used to communicate with the Tivoli Access Manager policy server. The name of the access control list to be created. The name can be of any length. The following characters are valid in an ACL name. v Alphanumeric characters defined in the locale v The underscore (_) character v 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.

Description
Creates a new access control list (ACL). This function creates a new ACL policy in the Tivoli Access Manager ACL database. It does not create the specific ACL entries. Command line equivalent:
pdadmin acl create ACL_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

62

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_acl_delete()
Deletes the specified access control list.

Syntax
unsigned long ivadmin_acl_delete( ivadmin_context ctx, const char *aclid, ivadmin_response *rsp );

Parameters
Input ctx aclid 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the access control list.

Description
Deletes the specified access control list. Command line equivalent:
pdadmin acl delete ACL_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

63

ivadmin_acl_get()
Returns the specified access control list.

Syntax
unsigned long ivadmin_acl_get( ivadmin_context ctx, const char *aclid, ivadmin_acl *acl, ivadmin_response *rsp );

Parameters
Input ctx aclid Output acl rsp Returned access control list. Free this memory when it is no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed. The context used to communicate with the Tivoli Access Manager policy server. The name of the access control list.

Description
Returns the specified access control list. Command line equivalent:
pdadmin acl show ACL_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

64

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_acl_getanyother()
Returns the actions (permissions) defined in the entry for the user any-other in the specified access control list.

Syntax
const char * ivadmin_acl_getanyother( ivadmin_acl acl );

Parameters
Input acl Pointer to the access control list.

Description
Returns the actions defined in the entry for the user any-other in the specified access control list. You must call the ivadmin_acl_get() function to obtain the ivadmin_acl object before using this function to obtain the actions defined for the any-other user type. Free this character string when it is no longer needed. Each action is represented by a single alphabetic character. Default actions are provided in the primary action group by Tivoli Access Manager. These default actions, such as A for add, or v for view, are listed in the IBM Tivoli Access Manager Base Administration Guide. Actions in the primary action group are always returned first, followed by the actions defined in other action groups. For example, if the entry contains the add and view actions from the primary action group, along with the P, D, and q actions from the AdminGroup action group, and the b and V actions 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 Values
Returns the actions defined in the entry for the user any-other in the specified access control list.

Chapter 12. Administration C API reference

65

ivadmin_acl_getdescription()
Returns the description of the specified access control list.

Syntax
const char * ivadmin_acl_getdescription( ivadmin_acl acl );

Parameters
Input acl Pointer to the access control list.

Description
Returns the description of the specified access control list. You must call the ivadmin_acl_get() function to obtain the ivadmin_acl object before using ivadmin_acl_getdescription(). Do not free this entry. This is data maintained in the access control list structure. Command line equivalent:
pdadmin acl show ACL_name

The description is part of the information returned by the pdadmin acl show command.

Return Values
Returns the description of the specified access control list. The maximum length for a description is 1024 characters.

66

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_acl_getgroup()
Returns the actions (permissions) defined in the entry for the specified group in the specified access control list.

Syntax
const char * ivadmin_acl_getgroup( ivadmin_acl acl, const char *groupid );

Parameters
Input acl groupid Pointer to the access control list. The name of the group for which you want the actions.

Description
Returns the actions (permissions) defined in the entry for the specified group in the specified access control list. You must call the ivadmin_acl_get() function to obtain the ivadmin_acl object before using the ivadmin_acl_getgroup() function to obtain the actions defined for the group. Free this entry when it is no longer needed. Each action is represented by a single alphabetic character. Default actions are provided in the primary action group by Tivoli Access Manager. These default actions, such as A for add, or v for view, are listed in the IBM Tivoli Access Manager Base Administration Guide. Actions in the primary action group are always returned first, followed by the actions defined in other action groups. For example, if the entry contains the add and view actions from the primary action group, along with the P, D, and q actions from the AdminGroup action group, and the b and V actions 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 Values
Returns the actions (permissions) defined in the entry for the specified group in the specified access control list.

Chapter 12. Administration C API reference

67

ivadmin_acl_getid()
Returns the name of the specified access control list.

Syntax
const char * ivadmin_acl_getid( ivadmin_acl acl );

Parameters
Input acl Pointer to the access control list.

Description
Returns the name of the specified access control list. You must call the ivadmin_acl_get() function to obtain the ivadmin_acl object before using this function. Do not free the returned name. This is data maintained in the ivadmin_acl structure. Command line equivalent:
pdadmin acl show ACL_name

The access control list name is part of the information returned by the pdadmin command.

Return Values
Returns the name of the specified access control list. There is no limit to the length of the name.

68

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_acl_getunauth()
Returns the actions (permissions) defined in the entry for the user unauthenticated in the specified access control list.

Syntax
const char * ivadmin_acl_getunauth( ivadmin_acl acl );

Parameters
Input acl Pointer to the access control list.

Description
Returns the actions (permissions) defined in the entry for the user unauthenticated in the specified access control list. You must call the ivadmin_acl_get() function to obtain the ivadmin_acl object before using the ivadmin_get_unauth() function to obtain the actions defined for all unauthenticated users. Free the returned actions when they are no longer needed. Each action is represented by a single alphabetic character. Default actions are provided in the primary action group by Tivoli Access Manager. These default actions, such as A for add, or v for view, are listed in the IBM Tivoli Access Manager Base Administration Guide. Actions in the primary action group are always returned first, followed by the actions defined in other action groups. For example, if the entry contains the add and view actions from the primary action group, along with the P, D, and q actions from the AdminGroup action group, and the b and V actions 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 Values
Returns the actions (permissions) defined in the entry for the user unauthenticated in the specified access control list.

Chapter 12. Administration C API reference

69

ivadmin_acl_getuser()
Returns the actions (permissions) defined in the entry for the specified user in the specified access control list.

Syntax
const char * ivadmin_acl_getuser( ivadmin_acl acl, const char * userid );

Parameters
Input acl userid Pointer to the access control list. The name of the user entry from which you want to get the list of defined actions.

Description
Returns the actions (permissions) defined in the entry for the specified user in the specified access control list. You must call the ivadmin_acl_get() function to obtain the ivadmin_acl object before using ivadmin_acl_getuser() to obtain the actions defined for the user. Free this character string when no longer needed. Each action is represented by a single alphabetic character. Default actions are provided in the primary action group by Tivoli Access Manager. These default actions, such as A for add, or v for view, are listed in the IBM Tivoli Access Manager Base Administration Guide. Actions in the primary action group are always returned first, followed by the actions defined in other action groups. For example, if the entry contains the add and view actions from the primary action group, along with the P, D, and q actions from the AdminGroup action group, and the b and V actions 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 Values
Returns the actions (permissions) defined in the entry for the specified user in the specified access control list.

70

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_acl_list()
Returns the names of all the defined access control lists.

Syntax
unsigned long ivadmin_acl_list( ivadmin_context ctx, unsigned long *count, char ***aclids, ivadmin_response *rsp );

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server.

Output count aclids The number of access control list names returned. Zero is returned if an error occurs. An array of pointers to the access control list names returned. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

rsp

Description
Returns the names of all of the defined access control lists. If no access control lists exist, or an error is encountered, NULL is returned. Command line equivalent:
pdadmin acl list

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

71

ivadmin_acl_listgroups()
Returns a list of group names included in the specified access control list.

Syntax
unsigned long ivadmin_acl_listgroups( ivadmin_acl acl, unsigned long *count, char ***groupids );

Parameters
Input acl Output count groupids The number of group names returned. Zero is returned if an error occurs. An array of pointers to the group names returned. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. Pointer to the access control list.

Description
Returns a list of group names included in the specified access control list. You must call the ivadmin_acl_get() function to obtain the ivadmin_acl object before using this function. Command line equivalent:
pdadmin acl show ACL_name

The list of group names is part of the information returned by this pdadmin command.

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

72

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_acl_listusers()
Returns a list of the user names included in the specified access control list.

Syntax
unsigned long ivadmin_acl_listusers( ivadmin_acl acl, unsigned long *count, char ***userids );

Parameters
Input acl Output count userids The number of user names returned. Zero is returned if an error occurs. An array of pointers to the user names returned. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. Pointer to the access control list.

Description
Returns a list of the user names included in the specified access control list. You must call the ivadmin_acl_get() function to obtain the ivadmin_acl object before using 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 Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

73

ivadmin_acl_removeanyother()
Removes the access control list entry for the user any-other from the specified access control list.

Syntax
unsigned long ivadmin_acl_removeanyother( ivadmin_context ctx, const char *aclid, ivadmin_response *rsp );

Parameters
Input ctx aclid 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the access control list.

Description
Removes the access control list entry for the user any-other from the specified access control list. Command line equivalent:
pdadmin acl modify ACL_name remove any-other

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

74

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_acl_removegroup()
Removes the access control list entry for the specified group from the specified access control list.

Syntax
unsigned long ivadmin_acl_removegroup( ivadmin_context ctx, const char *aclid, const char *groupid, ivadmin_response *rsp );

Parameters
Input ctx aclid groupid The context used to communicate with the Tivoli Access Manager policy server. The name of the access control list. The 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.

Description
Removes the access control list entry for the specified group from the specified access control list. Command line equivalent:
pdadmin acl modify ACL_name remove group group_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

75

ivadmin_acl_removeunauth()
Removes the access control list entry for the user unauthenticated from the specified access control list.

Syntax
unsigned long ivadmin_acl_removeunauth( ivadmin_context ctx, const char *aclid, ivadmin_response *rsp );

Parameters
Input ctx aclid 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the access control list.

Description
Removes the access control list entry for the user unauthenticated from the specified access control list. Command line equivalent:
pdadmin acl modify ACL_name remove unauthenticated

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

76

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_acl_removeuser()
Removes the access control list entry for the specified user from the specified access control list.

Syntax
unsigned long ivadmin_acl_removeuser( ivadmin_context ctx, const char *aclid, const char *userid, ivadmin_response *rsp );

Parameters
Input ctx aclid userid The context used to communicate with the Tivoli Access Manager policy server. The name of the access control list. 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.

Description
Removes the access control list entry for the specified user from the specified access control list. Command line equivalent:
pdadmin acl modify ACL_name remove user user_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

77

ivadmin_acl_setanyother()
Sets or modifies the access control list entry for the user any-other in the access control list.

Syntax
unsigned long ivadmin_acl_setanyother( ivadmin_context ctx, const char *aclid, const char *actions, ivadmin_response *rsp );

Parameters
Input ctx aclid actions The context used to communicate with the Tivoli Access Manager policy server. Access control list name. The new permissions for this access control list entry. This is a string consisting of single-letter permission codes. Each action is represented by a single alphabetic character. Default actions are provided in the primary action group by Tivoli Access Manager. These default actions, such as A for add, or v for view, are listed in the IBM Tivoli Access Manager Base Administration Guide. Actions in the primary action group can be specified first without the name of the action group. Otherwise, the action group name must precede them. Actions in other action groups must always be preceded with the action group name, which is enclosed in brackets ([ ]). For example, to set an entry so that it contains the add and view actions from the primary action group, along with the P, B, and J actions from the Admin2 action group, and the b and C actions from the Auditors action group, 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.

Description
Sets or modifies the access control list entry for the user any-other in the access control list. Command line equivalent:

78

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

pdadmin acl modify ACL_name set any-other perms

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

79

ivadmin_acl_setdescription()
Set or modify the description for the specified access control list.

Syntax
unsigned long ivadmin_acl_setdescription( ivadmin_context ctx, const char *aclid, const char *description, ivadmin_response *rsp );

Parameters
Input ctx aclid 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. The context used to communicate with the Tivoli Access Manager policy server. Access control list name. New description.

Description
Set or modify the description for the specified access control list. Command line equivalent:
pdadmin acl modify ACL_name description description

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

80

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_acl_setgroup()
Sets or modifies the access control list entry for the specified group in the specified access control list.

Syntax
unsigned long ivadmin_acl_setgroup( ivadmin_context ctx, const char *aclid, const char *groupid, const char *actions, ivadmin_response *rsp );

Parameters
Input ctx aclid groupid actions The context used to communicate with the Tivoli Access Manager policy server. Access control list name. The access control list entry for this group is set. The new permissions for this access control list entry. This is a string consisting of single-letter permission codes. Each action is represented by a single alphabetic character. Default actions are provided in the primary action group by Tivoli Access Manager. These default actions, such as A for add, or v for view, are listed in the IBM Tivoli Access Manager Base Administration Guide. Actions in the primary action group can be specified first without the name of the action group. Otherwise, the action group name must precede them. Actions in other action groups must always be preceded with the action group name, which is enclosed in brackets ([ ]). For example, to set an entry so that it contains the add and view actions from the primary action group, along with the P, B, and J actions from the Admin2 action group, and the b and C actions from the Auditors action group, 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.

Chapter 12. Administration C API reference

81

Description
Sets or modifies the access control list (ACL) entry for the specified group in the specified access control list. The Tivoli Access Manager user registry must contain an entry for the specified group before you can call this function to add an entry for the group to an ACL. Command line equivalent:
pdadmin acl modify ACL_name set group group_name perms

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

82

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_acl_setunauth()
Sets the access control list entry for the user unauthenticated in the specified access control list.

Syntax
unsigned long ivadmin_acl_setunauth( ivadmin_context ctx, const char *aclid, const char *actions, ivadmin_response *rsp );

Parameters
Input ctx aclid actions The context used to communicate with the Tivoli Access Manager policy server. Access control list name. The new permissions for this access control list entry. This is a string consisting of single-letter permission codes. Each action is represented by a single alphabetic character. Default actions are provided in the primary action group by Tivoli Access Manager. These default actions, such as A for add, or v for view, are listed in the IBM Tivoli Access Manager Base Administration Guide. Actions in the primary action group can be specified first without the name of the action group. Otherwise, the action group name must precede them. Actions in other action groups must always be preceded with the action group name, which is enclosed in brackets ([ ]). For example, to set an entry so that it contains the add and view actions from the primary action group, along with the P, B, and J actions from the Admin2 action group, and the b and C actions from the Auditors action group, 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.

Description
Sets the access control list entry for the user unauthenticated in the specified access control list. Command line equivalent:
Chapter 12. Administration C API reference

83

pdadmin acl modify ACL_name set unauthenticated perms

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

84

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_acl_setuser()
Sets the entry for the specified user in the specified access control list.

Syntax
unsigned long ivadmin_acl_setuser( ivadmin_context ctx, const char *aclid, const char *userid, const char *actions, ivadmin_response *rsp );

Parameters
Input ctx aclid userid actions The context used to communicate with the Tivoli Access Manager policy server. Access control list name. The access control list entry for this user is set. The new permissions for this access control list entry. This is a string consisting of single-letter permission codes. Each action is represented by a single alphabetic character. Default actions are provided in the primary action group by Tivoli Access Manager. These default actions, such as A for add, or v for view, are listed in the IBM Tivoli Access Manager Base Administration Guide. Actions in the primary action group can be specified first without the name of the action group. Otherwise, the action group name must precede them. Actions in other action groups must always be preceded with the action group name, which is enclosed in brackets ([ ]). For example, to set an entry so that it contains the add and view actions from the primary action group, along with the P, B, and J actions from the Admin2 action group, and the b and C actions from the Auditors action group, 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.

Description
Call 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 default Tivoli Access Manager permissions for actions in the IBM Tivoli Access Manager
Chapter 12. Administration C API reference

85

Base Administration Guide. The Tivoli Access Manager user registry must contain an entry for the specified user before you can use this function to add an entry for the user to an access control list (ACL). Command line equivalent:
pdadmin acl modify ACL_name set user user_name perms

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

86

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_action_create()
Defines a new action (permission) code in the primary action group.

Syntax
unsigned long ivadmin_action_create( ivadmin_context ctx, const char *actionid, const char *description, const char *type, ivadmin_response *rsp );

Parameters
Input ctx actionid The context used to communicate with the Tivoli Access Manager policy server. Action identifier. This must be a single-letter code that does not conflict with existing permission codes. The input is left as a string for future expansion. Description of a permission code. This description appears in the Tivoli Access Manager Web Portal Manager. Label for action category. This label appears in the Tivoli Access Manager Web Portal Manager.

description type

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.

Description
Defines a new action (permission) code in the primary action group. Each action group can contain 32 action codes. The default action group contains the 18 predefined Tivoli Access Manager action codes. Thus, you can call ivadmin_action_create() to add up to 14 new action codes to the primary group. Actions codes consist of one alphabetic character (az or AZ). Actions codes are case-sensitive. Each action code only can be used once within an action group. Be sure that you do not attempt to redefine the default Tivoli Access Manager action codes when adding new codes to the primary group. Command line equivalent:
pdadmin action create name description action_type

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful.

Chapter 12. Administration C API reference

87

IVADMIN_FALSE Defined as 0. The function encountered an error.

88

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_action_create_in_group()
Defines a new action (permission) code in the specified action group.

Syntax
unsigned long ivadmin_action_create_in_group( ivadmin_context ctx, const char *actionid, const char *description, const char *type, const char *groupname, ivadmin_response *rsp );

Parameters
Input ctx actionid The context used to communicate with the Tivoli Access Manager policy server. Action identifier. This must be a single-letter code that does not conflict with existing permission codes. The input is left as a string for future expansion. Description of the permission code. This appears in the Tivoli Access Manager Web Portal Manager. Label for the action category. This appears in the Tivoli Access Manager Web Portal Manager. Name of the action group in which to create the action.

description type groupname 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.

Description
Defines a new action (permission) code in the specified action group. Call this function to add an action code to a user-defined extended action group. Actions codes consist of one alphabetic character (az or AZ). Actions codes are case-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 Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.
Chapter 12. Administration C API reference

89

ivadmin_action_delete()
Deletes an action (permission) code from the primary action group.

Syntax
unsigned long ivadmin_action_delete( ivadmin_context ctx, const char *actionid, ivadmin_response *rsp );

Parameters
Input ctx actionid The context used to communicate with the Tivoli Access Manager policy server. Action identifier. This must be a single-letter code that identifies the permission 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.

Description
Deletes an action (permission) code from the primary action group. Command line equivalent:
pdadmin action delete name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

90

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_action_delete_from_group()
Deletes an action (permission) code from the specified action group.

Syntax
unsigned long ivadmin_action_delete_from_group( ivadmin_context ctx, const char *actionid, const char *groupname, ivadmin_response *rsp );

Parameters
Input ctx actionid groupname 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. The context used to communicate with the Tivoli Access Manager policy server. Action identifier. This must be a single-letter code that identifies the permission to delete. Name of the action group from which to delete the action.

Description
Deletes an action (permission) code from the specified action group. Command line equivalent:
pdadmin action delete name action_group_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

91

ivadmin_action_getdescription()
Returns the description for the specified action.

Syntax
const char * ivadmin_action_getdescription( ivadmin_action action );

Parameters
Input action Pointer to the action.

Description
Returns 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 the description for each action.

Return Values
Returns the description for the specified action. The maximum length for a description is 1024 characters.

92

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_action_getid()
Returns the action identifier for the specified action.

Syntax
const char * ivadmin_action_getid( ivadmin_action action );

Parameters
Input action Pointer to the action.

Description
Returns 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 code for each action.

Return Values
Returns the single character action identifier for the specified action, or NULL if an error occurred.

Chapter 12. Administration C API reference

93

ivadmin_action_gettype()
Returns the type, or label, for the action category associated with the specified action.

Syntax
const char * ivadmin_action_gettype( ivadmin_action action );

Parameters
Input action Pointer to the action.

Description
Returns the type, or label, of the action category associated with 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 type for each action.

Return Values
Returns the type, or label, of the action category associated with the specified action. There is no limit to the length of the label.

94

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_action_group_create()
Creates a new action group with the specified name.

Syntax
unsigned long ivadmin_action_group_create( ivadmin_context ctx, const char *groupname, ivadmin_response *rsp );

Parameters
Input ctx groupname 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. The context used to communicate with the Tivoli Access Manager policy server. Name of the new action group.

Description
Creates a new action group with the specified name. Tivoli Access Manager supports a maximum of 32 action groups. Command line equivalent:
pdadmin action group create action_group_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

95

ivadmin_action_group_delete()
Deletes the specified action group and all the actions that belong to the specified group.

Syntax
unsigned long ivadmin_action_group_delete( ivadmin_context ctx, const char *groupname, ivadmin_response *rsp );

Parameters
Input ctx groupname 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. The context used to communicate with the Tivoli Access Manager policy server. Name of the action group to delete.

Description
Deletes the specified action group and all of the actions that belong to the specified group. Command line equivalent:
pdadmin action group delete action_group_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

96

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_action_group_list()
Lists all the defined action group names.

Syntax
unsigned long ivadmin_action_group_list( ivadmin_context ctx, unsigned long *count, char ***names, ivadmin_response *rsp );

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server.

Output count names The number of action group names returned. Zero is returned if an error occurs. An array of pointers to the action group names returned. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

rsp

Description
Lists all the defined action group names. Command line equivalent:
pdadmin action group list

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

97

ivadmin_action_list()
Lists all the defined action (permission) codes from the primary action group.

Syntax
unsigned long ivadmin_action_list( ivadmin_context ctx, unsigned long *count, ivadmin_action **actions, ivadmin_response *rsp );

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server.

Output count actions The number of actions returned. Zero is returned if an error occurs. An array of pointers to the actions returned. You must free the data referenced by each pointer, as well as the array of pointers when they are no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

rsp

Description
Lists all the defined action (permission) codes from the primary action group. Use this function to obtain an opaque list of actions. You can then use additional functions to obtain information from each action (ivadmin_action). For example, you can use ivadmin_action_getdescription() to obtain a description for the specified ivadmin_action object. Command line equivalent:
pdadmin action list

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

98

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_action_list_in_group()
Lists all the defined action (permission) codes from the specified action group.

Syntax
unsigned long ivadmin_action_list_in_group( ivadmin_context ctx, const char *actiongroup, unsigned long *count, ivadmin_action **actions, ivadmin_response *rsp );

Parameters
Input ctx actiongroup Output count actions The number of actions returned. Zero is returned if an error occurs. An array of pointers to the actions returned. You must free the data referenced by each pointer, as well as the array of pointers when they are no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed. The context used to communicate with the Tivoli Access Manager policy server. Name of the action group to list.

rsp

Description
Lists all the defined action (permission) codes from the specified action group. Command line equivalent:
pdadmin action list action_group_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

99

ivadmin_authzrule_create()
Creates the specified authorization rule object.

Syntax
unsigned long ivadmin_authzrule_create( ivadmin_context ctx, const char *ruleid, const char *ruledesc, const char *ruletext, const char *failreason, ivadmin_response *rsp );

Parameters
Input ctx ruleid ruledesc ruletext failreason The context used to communicate with the Tivoli Access Manager policy server. Name of the authorization rule to create. Description of the rule. Can be NULL. Rule text in XSL format. String representing a fail reason code. If authorization is denied as a result of this rules evaluation, but other authorization checks (such as POP or ACL) are successful, this reason code is returned to the application making the authorization check. Can be NULL.

Output rsp The response object. Indicates the success or failure of the function and might contain informational, warning or error information. Free this object when it is no longer needed.

Description
Creates an authorization rule. An authorization rule can be attached to a protected object, which enables user credential and application context attributes to be compared against the rule when attempting to authorize access to the protected object. Command line equivalent:
pdadmin authzrule create rulename ruletext [ -desc description ] [ -failreason failreason ]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

100

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_authzrule_delete()
Deletes the specified authorization rule object.

Syntax
unsigned long ivadmin_authzrule_delete( ivadmin_context ctx, const char *ruleid, ivadmin_response *rsp );

Parameters
Input ctx ruleid Output rsp The response object. Indicates the success or failure of the function and might contain informational, warning or error information. Free this object when it is no longer needed. The context used to communicate with the Tivoli Access Manager policy server. Name of the authorization rule to delete.

Description
Deletes an authorization rule. Command line equivalent:
pdadmin authzrule delete rulename

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

101

ivadmin_authzrule_get()
Gets the specified authorization rule object.

Syntax
unsigned long ivadmin_authzrule_get( ivadmin_context ctx, const char *ruleid, ivadmin_authzrule *rule, ivadmin_response *rsp );

Parameters
Input ctx ruleid Output rule rsp The authorization rule object. Free this object when it is no longer needed. The response object. Indicates the success or failure of the function and might contain informational, warning or error information. Free this object when it is no longer needed. The context used to communicate with the Tivoli Access Manager policy server. Name of the authorization rule to return.

Description
Returns the specified authorization rule object. Command line equivalent:
pdadmin authzrule show rulename

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

102

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_authzrule_getdescription()
Gets the description for the specified authorization rule.

Syntax
const char * ivadmin_authzrule_getdescription( ivadmin_authzrule rule );

Parameters
Input rule Pointer to the authorization rule object.

Description
Gets the description from the specified authorization rule object. You must call the ivadmin_authzrule_get() function to obtain an ivadmin_authzrule object before using this function. Do not free the character string that is returned. This data is maintained in the ivadmin_authzrule object. Command line equivalent:
pdadmin authzrule show rulename

The description is part of the information returned by the pdadmin command.

Return Values
The description for the specified authorization rule.

Chapter 12. Administration C API reference

103

ivadmin_authzrule_getfailreason()
Gets the fail reason, if any, for the specified authorization rule.

Syntax
const char * ivadmin_authzrule_getfailreason( ivadmin_authzrule rule );

Parameters
Input rule Pointer to the authorization rule object.

Description
Gets the fail reason from the specified authorization rule object. You must call the ivadmin_authzrule_get() function to obtain an ivadmin_authzrule object before using this function. Do not free the character string that is returned. This data is maintained in the ivadmin_authzrule object. Command line equivalent:
pdadmin authzrule show rulename

The fail reason is part of the information returned by the pdadmin command.

Return Values
The fail reason, if any, for the specified authorization rule. Returns an empty string if there is no fail reason.

104

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_authzrule_getid()
Gets the ID for the specified authorization rule.

Syntax
const char * ivadmin_authzrule_getid( ivadmin_authzrule rule );

Parameters
Input rule Pointer to the authorization rule object.

Description
Gets the rule name (ID) from the specified authorization rule object. You must call the ivadmin_authzrule_get() function to obtain an ivadmin_authzrule object before using this function. Do not free the character string that is returned. This data is maintained in the ivadmin_authzrule object. Command line equivalent:
pdadmin authzrule show rulename

The rule name is part of the information returned by the pdadmin command.

Return Values
The name of the specified authorization rule.

Chapter 12. Administration C API reference

105

ivadmin_authzrule_getruletext()
Gets the rule text for the specified authorization rule.

Syntax
const char * ivadmin_authzrule_getruletext( ivadmin_authzrule rule );

Parameters
Input rule Pointer to the authorization rule object.

Description
Gets the rule text from the specified authorization rule object. You must call the ivadmin_authzrule_get() function to obtain an ivadmin_authzrule object before using this function. Do not free the character string that is returned. This data is maintained in the ivadmin_authzrule object. Command line equivalent:
pdadmin authzrule show rulename

The rule text is part of the information returned by the pdadmin command.

Return Values
The rule text, in XSL format, for the specified authorization rule.

106

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_authzrule_list()
Lists the names of all of the registered authorization rules.

Syntax
unsigned long ivadmin_authzrule_list( ivadmin_context ctx, unsigned long *count, char ***ruleids, ivadmin_response *rsp );

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server.

Output count ruleids The number of authorization rule strings returned. Zero is returned if an error occurs. An array of pointers to the authorization rule strings returned. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

rsp

Description
Returns a list of the names of all of the registered authorization rules. Command line equivalent:
pdadmin authzrule list

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

107

ivadmin_authzrule_setdescription()
Modifies the authorization rule description.

Syntax
unsigned long ivadmin_authzrule_setdescription( ivadmin_context ctx, const char *ruleid, const char *description, ivadmin_response *rsp );

Parameters
Input ctx ruleid description The context used to communicate with the Tivoli Access Manager policy server. Name of the authorization rule. New description. Cannot be NULL. An empty string can be specified to clear the description.

Output rsp The response object. Indicates the success or failure of the function and might contain informational, warning or error information. Free this object when it is no longer needed.

Description
Set or modify the description for the specified authorization rule. Command line equivalent:
pdadmin authzrule modify rulename description description

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

108

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_authzrule_setfailreason()
Modifies the authorization rule fail reason.

Syntax
unsigned long ivadmin_authzrule_setruletext( ivadmin_context ctx, const char *ruleid, const char *failreason, ivadmin_response *rsp );

Parameters
Input ctx ruleid failreason The context used to communicate with the Tivoli Access Manager policy server. Name of the authorization rule. The new fail reason code. If authorization is denied as a result of this rules evaluation, but other authorization checks (such as POP or ACL) are successful, this reason code is returned to the application making the authorization check. Cannot be NULL. An empty string can be specified to clear the fail reason code.

Output rsp The response object. Indicates the success or failure of the function and might contain informational, warning or error information. Free this object when it is no longer needed.

Description
Sets or modifies the fail reason for the specified authorization rule Command line equivalent:
pdadmin authzrule modify rulename failreason failreason

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

109

ivadmin_authzrule_setruletext()
Modifies the authorization rule text.

Syntax
unsigned long ivadmin_authzrule_setruletext( ivadmin_context ctx, const char *ruleid, const char *ruletext, ivadmin_response *rsp );

Parameters
Input ctx ruleid ruletext Output rsp The response object. Indicates the success or failure of the function and might contain informational, warning or error information. Free this object when it is no longer needed. The context used to communicate with the Tivoli Access Manager policy server. Name of the authorization rule. New text for the rule, in XSL format.

Description
Sets or modifies the rule text for the specified authorization rule. Command line equivalent:
pdadmin authzrule modify rulename ruletext ruletext

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

110

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_cfg_addreplica2()
Adds a replica entry to the configuration file. A replica entry is the host name, port number, and rank of an ivacld server with which the application server might communicate.

Syntax
unsigned long ivadmin_cfg_addreplica2( ivadmin_context ctx, const char *cfg_file_name, const char *ivacld_host, int ivacld_port, int ivacld_rank, ivadmin_response *rsp );

Parameters
Input ctx cfg_file_name ivacld_host ivacld_port Specifies the local context created by the ivadmin_context_createlocal() function. Specifies the configuration file to use. Unless the configuration file is in the current directory, this must be a fully qualified path name. Specifies the TCP host name of the ivacld server. Specifies the listening port number of the ivacld replica server. This is the port number on which the ivacld server listens for requests. Specifies the replica order of preference among other replicas.

ivacld_rank Output rsp

Specifies the response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

Description
Command line equivalent:
svrsslcfg -add_replica -f cfg_file -h host_name [-p port] [-k rank]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

111

ivadmin_cfg_chgreplica2()
Changes parameters of a replica entry in the configuration file. A replica entry is the host name, port number, and rank of an ivacld server with which the application server might communicate.

Syntax
unsigned long ivadmin_cfg_chgreplica2( ivadmin_context ctx, const char *cfg_file_name, const char *ivacld_host, int ivacld_port, int ivacld_rank, ivadmin_response *rsp );

Parameters
Input ctx cfg_file_name ivacld_host ivacld_port Specifies the local context created by the ivadmin_context_createlocal() function. Specifies the configuration file to use. Unless the configuration file is in the current directory, this must be a fully qualified path name. Specifies the TCP host name of the ivacld server. Specifies the listening port number of the ivacld replica server. This is the port number on which the ivacld server listens for requests. Specifies the replica order of preference among other replicas.

ivacld_rank Output rsp

Specifies the response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

Description
Command line equivalent:
svrsslcfg -chg_replica -f cfg_file -h host_name [-p port] [-k rank]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

112

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_cfg_configureserver3()
Configures an application server.

Syntax
unsigned long ivadmin_cfg_configureserver3( ivadmin_context ctx, const char *cfg_file_name, const char *kdb_dir_name, const char *application_name, const char *host_name, ivadmin_cfg_servermode server_mode, const char *server_pwd, int enable_listening, int listening_port, int enable_refresh, int kdb_pwd_life, int ssl_timeout, const char *appl_cert, unsigned long group_count, const char **groups, const char *description, ivadmin_response *rsp);

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server. The application server will be defined in the domain to which this context is authenticated. The configuration file to use. Unless the configuration file is in the current directory, this must be a fully qualified path name. The keyring database directory. The name for the application or server. The application_name and host_name combination must be unique, as this combination is used to uniquely identify the application. host_name server_mode The Tivoli Access Manager server mode. The data type ivadmin_cfg_servermode is an enumerated data type. Enumerated values are (1) local and (2) remote. server_pwd The password for the application server. If NULL or an empty password is specified, a random password will automatically be generated for the server account. The host name on which the application runs.

cfg_file_name kdb_dir_name application_name

enable_listening The listening-enabled flag in the configuration file. Specify IVADMIN_TRUE to enable listening and IVADMIN_FALSE to disable listening. listening_port enable_refresh The TCP/IP port on which the application listens. The certificate automatic refresh support setting. Specify IVADMIN_TRUE to enable or IVADMIN_FALSE to disable.

Chapter 12. Administration C API reference

113

kdb_pwd_life ssl_timeout appl_cert

The keyring database password life, specified in days. If it is 0, a default of 183 days is used. The Secure Sockets Layer (SSL) session timeout value in seconds. If it is 0, a default of 7200 is used. The name of the file that contains a base-64 encoded SSL certificate. This is an optional parameter. If specified, the certificate is stored in the keyring database using a label of APPL_LDAP_CERT. Typical use of this parameter is to store the certificate authority certificate that the application uses when it authenticates directly to the user registry. Do not confuse this certificate with the certificate that is used to authenticate with the Tivoli Access Manager policy server. The certificate specified by this parameter does not participate in authentication with the policy server; it is strictly for application use and allows the application to use a single keyring database for all SSL certificates.

group_count groups description

The number of groups of which the application server should be made a member. A list of groups of which the application server should be made a member. Description of the application server. Cannot be NULL, but can be the empty string.

Output rsp The response object. Indicates the success or failure of the function and might contain informational, warning or error information. Free this object when it is no longer needed.

Description
Configures an authorization API server by updating the configuration file and creating the keyring database. The combination of the application_name and host_name must be unique, as this combination is used to uniquely identify the application. Command line equivalent:
svrsslcfg config -f cfg_file_name -d kdb_dir_name -n server_name \ -s server_mode -r listening_port -P admin_pwd [-S server_pwd] \ [-A admin_ID] [-t ssl_timeout] [-e kbd_pwd_life] [-l listening_mode]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

114

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_cfg_getvalue()
Returns a value associated with a specific key in a specific stanza of the specified configuration file.

Syntax
unsigned long ivadmin_cfg_getvalue( ivadmin_context ctx, const char *cfg_file_name, const char *stanza, const char *key, int *count, char ***values ivadmin_response *rsp );

Parameters
Input ctx cfg_file_name Specifies the local context created by the ivadmin_context_createlocal() function. Specifies the configuration file to be examined. This value can be a fully qualified path name to a configuration file or a reference to a Tivoli Access Manager configuration file. A reference to a Tivoli Access Manager configuration file is indicated by using one of the following constants: IVADMIN_CFG_CFGFILE_AMRTE Tivoli Access Manager runtime configuration file IVADMIN_CFG_CFGFILE_AMMGRD Tivoli Access Manager policy server configuration file IVADMIN_CFG_CFGFILE_AMACLD Tivoli Access Manager authorization server configuration file IVADMIN_CFG_CFGFILE_AMPROXY Tivoli Access Manager proxy server configuration file stanza Specifies the name of the stanza under which the input key is located. This value can be a user-defined stanza name, or a reference to a Tivoli Access Manager stanza. Stanzas used by Tivoli Access Manager components are listed in the appendices of the IBM Tivoli Access Manager Base Administration Guide. The following constants can be used: IVADMIN_CFG_STANZA_SSL SSL entries IVADMIN_CFG_STANZA_POLICY_SVR Tivoli Access Manager policy server entries key Specifies the name of the key whose value is to be returned. This value can be a user-defined key name or a reference to a Tivoli Access Manager key. Keys used by Tivoli Access Manager

Chapter 12. Administration C API reference

115

components are listed in the appendices of the IBM Tivoli Access Manager Base Administration Guide. The following constants can be used: IVADMIN_CFG_KEY_POLICY_SVR Tivoli Access Manager policy server host name and port IVADMIN_CFG_KEY_SSL_KEYFILE SSL keyfile path IVADMIN_CFG_KEY_SSL_STASHFILE SSL stashfile path IVADMIN_CFG_KEY_SSL_PASSWORD SSL password Output count values The number of values returned. Zero is returned if no value is associated with the key or if an error occurs. An array of pointers to the values returned. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed.. Specifies the response object. Indicates the success or failure of the function. Contains zero or more error, informational, and warning messages. Free this object when it is no longer needed.

rsp

Description
Returns the value of a specific key from a specific stanza in a configuration file. All data is returned in an array of character strings, because some keys might be multivalued. The caller must have the necessary operating system permissions to read the configuration file or database. Command line equivalent:
pdadmin config show config-file stanza key

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

116

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_cfg_removevalue()
Removes a value associated with a specific key in a specific stanza of the specified configuration file.

Syntax
unsigned long ivadmin_cfg_removevalue( ivadmin_context ctx, const char *cfg_file_name, const char *stanza, const char *key, int count, char **values ivadmin_response *rsp );

Parameters
Input ctx cfg_file_name Specifies the local context created by the ivadmin_context_createlocal() function. Specifies the configuration file to be examined. This value can be a fully qualified path name to a configuration file or a reference to a Tivoli Access Manager configuration file. A reference to a Tivoli Access Manager configuration file is indicated by using one of the following constants: IVADMIN_CFG_CFGFILE_AMRTE Tivoli Access Manager runtime configuration file IVADMIN_CFG_CFGFILE_AMMGRD Tivoli Access Manager policy server configuration file IVADMIN_CFG_CFGFILE_AMACLD Tivoli Access Manager authorization server configuration file IVADMIN_CFG_CFGFILE_AMPROXY Tivoli Access Manager proxy server configuration file stanza Specifies the name of the stanza under which the input key is located. This value can be a user-defined stanza name, or a reference to a Tivoli Access Manager stanza. Stanzas used by Tivoli Access Manager components are listed in the appendices of the IBM Tivoli Access Manager Base Administration Guide. The following constants can be used: IVADMIN_CFG_STANZA_SSL SSL entries IVADMIN_CFG_STANZA_POLICY_SVR Tivoli Access Manager policy server entries key Specifies the name of the key whose value is to be modified. This value can be a user-defined key name or a reference to a Tivoli Access Manager key. Keys used by Tivoli Access Manager

Chapter 12. Administration C API reference

117

components are listed in the appendices of the IBM Tivoli Access Manager Base Administration Guide. The following constants can be used: IVADMIN_CFG_KEY_POLICY_SVR Tivoli Access Manager policy server host name and port IVADMIN_CFG_KEY_SSL_KEYFILE SSL keyfile path IVADMIN_CFG_KEY_SSL_STASHFILE SSL stashfile path IVADMIN_CFG_KEY_SSL_PASSWORD SSL password count values The number of items in the values input array. Array of character pointers to configuration values to be removed from the input key.

Output rsp Specifies the response object. Indicates the success or failure of the function. Contains zero or more error, informational, or warning messages. Free this object when it is no longer needed.

Description
Removes the specified values from a specific key in a configuration file. If the key and values parameters are NULL, the entire stanza is removed. If only the values parameter is NULL, the specified key is removed. The caller must have the necessary operating system permissions to modify the configuration file or database. Command line equivalents: To remove a value:
pdadmin config modify keyvalue remove config-file stanza key value

To remove a key:
pdadmin config modify keyvalue remove config-file stanza key

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

118

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_cfg_renewservercert()
Renews the server Secure Sockets Layer (SSL) certificate.

Syntax
unsigned long ivadmin_cfg_renewservercert( ivadmin_context ctx, const char *cfg_file_name, const char *server_name, const char *host_name, ivadmin_response *rsp );

Parameters
Input ctx cfg_file_name server_name host_name Output rsp Specifies the response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed. Specifies the context to use when communicating with the Tivoli Access Manager policy server. Specifies the configuration file to use. Unless the configuration file is in the current directory, this must be a fully qualified path name. Specifies the unique server name. Specifies the host name on which the application will run.

Description
Use this API to refresh the certificate used to authenticate with the policy server if it has expired or been compromised. The application must be stopped before using this API. Command line equivalent:
svrsslcfg -chgcert -f cfg_file -n server_name [-A admin_id] -P admin_pwd

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

119

ivadmin_cfg_rmvreplica2()
Removes a replica entry from the configuration file. A replica entry is the host name, port number, and rank of an ivacld server with which te application server might communicate.

Syntax
unsigned long ivadmin_cfg_rmvreplica2( ivadmin_context ctx, const char *cfg_file_name, const char *ivacld_host, ivadmin_response *rsp );

Parameters
Input ctx cfg_file_name ivacld_host Output rsp Specifies the response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed. Specifies the local context created by the ivadmin_context_createlocal() function. Specifies the configuration file to use. Unless the configuration file is in the current directory, this must be a fully qualified path name. Specifies the TCP host name of the ivacld server.

Description
Removes a replica entry from the configuration file. Command line equivalent:
svrsslcfg -chg_replica -f cfg_file -h host_name [-p port] [-k rank]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

120

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_cfg_setapplicationcert2()
Replaces the optional application certificate authority certificate and the optional Secure Sockets Layer (SSL) certificate in the keyring database.

Syntax
unsigned long ivadmin_cfg_setapplicationcert2( ivadmin_context ctx, const char *cfg_file_name, const char *appl_cert, ivadmin_response *rsp );

Parameters
Input ctx cfg_file_name appl_cert Specifies the local context created by the ivadmin_context_createlocal() function. Specifies the configuration file to use. Unless the configuration file is in the current directory, this must be a fully qualified path name. Specifies the name of the file that contains a base-64 encoded SSL certificate. This is an optional parameter. If specified, the certificate is stored in the keyring database using a label of APPL_LDAP_CERT. Typical use of this parameter is to store the certificate authority certificate that the application uses when it authenticates directly to the user registry. Do not confuse this certificate with the certificate that is used to authenticate with the Tivoli Access Manager policy server. The certificate specified by this parameter does not participate in authentication with the policy server; it is strictly for application use and allows the application to use a single keyring database for all SSL certificates. Output rsp Specifies the response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

Description
The application must be stopped prior to invoking this API. Command line equivalent:
svrsslcfg -modify -f cfg_file [-t timeout] [-C cert_file] [-l listening_mode]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.
Chapter 12. Administration C API reference

121

ivadmin_cfg_setkeyringpwd2()
Refreshes or changes the keyring database password.

Syntax
unsigned long ivadmin_cfg_setkeyringpwd2( ivadmin_context ctx, const char *cfg_file_name, int kdb_pwd_life, ivadmin_response *rsp );

Parameters
Input ctx cfg_file_name kdb_pwd_life Specifies the local context created by the ivadmin_context_createlocal() function. Specifies the configuration file to use. Unless the configuration file is in the current directory, this must be a fully qualified path name. Specifies the keyring database password life in days. If 0, a default of 183 days is used.

Output rsp Specifies the response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

Description
Use this API to refresh or change the keyring database random password. A new random password is created in the stash file. The application must be stopped to execute this API. Command line equivalent:
svrsslcfg -chgcert -f cfg_file -n server_name [-A admin_id] -P admin_pwd

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

122

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_cfg_setlistening2()
Sets or resets the enable-listening parameter in the configuration file. This flag determines whether the application server will listen for communications from the policy server.

Syntax
unsigned long ivadmin_cfg_setlistening( ivadmin_context ctx, const char *cfg_file_name, int enable_listening, ivadmin_response *rsp );

Parameters
Input ctx cfg_file_name Specifies the local context created by the ivadmin_context_createlocal() function. Specifies the configuration file to use. Unless the configuration file is in the current directory, this must be a fully qualified path name.

enable_listening Sets the listening-enabled flag in the configuration file. Output rsp Specifies the response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

Description
The listening port in the configuration file must be nonzero to enable listening. Otherwise, an invalid parameter error is returned. The application must be stopped and restarted after calling this API. Command line equivalent:
svrsslcfg -chgcert -f cfg_file -modify -l yes

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

123

ivadmin_cfg_setport2()
Changes the listening port number of the application and updates the port number in the configuration file. The application server uses this port to communicate with the policy server.

Syntax
unsigned long ivadmin_cfg_setport2( ivadmin_context ctx, const char *cfg_file_name, int listening_port, ivadmin_response *rsp );

Parameters
Input ctx cfg_file_name listening_port Output rsp Specifies the response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed. Specifies the local context created by the ivadmin_context_createlocal() function. Specifies the configuration file to use. Unless the configuration file is in the current directory, this must be a fully qualified path name. Specifies the TCP/IP port on which the application listens.

Description
The server must be stopped and restarted to activate this change. If the port is set to 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 Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

124

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_cfg_setssltimeout2()
Changes the Secure Sockets Layer (SSL) timeout value in the configuration file.

Syntax
unsigned long ivadmin_cfg_setssltimeout2( ivadmin_context ctx, const char *cfg_file_name, int ssl_timeout, ivadmin_response *rsp );

Parameters
Input ctx cfg_file_name ssl_timeout Specifies the local context created by the ivadmin_context_createlocal() function. Specifies the configuration file to use. Unless the configuration file is in the current directory, this must be a fully qualified path name. Specifies the SSL session timeout value in seconds. If 0 is specified, a default of 7200 is used.

Output rsp Specifies the response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

Description
The application must be stopped and restarted to activate this change. Command line equivalent:
svrsslcfg -modify -f cfg_file [-t timeout] [-C cert_file] [-l listening_mode]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

125

ivadmin_cfg_setsvrpwd()
Sets the password on the specified server.

Syntax
unsigned long ivadmin_cfg_setsvrpwd( ivadmin_context ctx, const char *cfg_file_name, const char *newpassword, ivadmin_response *rsp );

Parameters
Input ctx cfg_file_name Specifies the context to use when communicating with the Tivoli Access Manager policy server. Specifies the configuration file to be examined. This value can be a fully qualified path name to a configuration file or a reference to a Tivoli Access Manager configuration file. A reference to a Tivoli Access Manager configuration file is indicated by using one of the following constants: IVADMIN_CFG_CFGFILE_AMRTE Tivoli Access Manager runtime configuration file IVADMIN_CFG_CFGFILE_AMMGRD Tivoli Access Manager policy server configuration file IVADMIN_CFG_CFGFILE_AMACLD Tivoli Access Manager authorization server configuration file IVADMIN_CFG_CFGFILE_AMPROXY Tivoli Access Manager proxy server configuration file newpassword Output rsp Specifies the response object. Indicates the success or failure of the function. Contains zero or more error, informational, and warning messages. Free this object when it is no longer needed. Specifies the new password to be set.

Description
Updates the password of the server user account. Upon successful update of the user registry, the local configuration is updated. The caller must have the necessary Tivoli Access Manager permissions to modify the password in the user registry as well as the necessary operating system permissions to modify the configuration file or database. Command line equivalent:
svrsslcfg -chgcert -f cfg_file -n server_name [-A admin_id] -P admin_pwd

126

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

127

ivadmin_cfg_setvalue()
Sets a value associated with a specific key in a specific stanza of the specified configuration file.

Syntax
unsigned long ivadmin_cfg_setvalue( ivadmin_context ctx, const char *cfg_file_name, const char *stanza, const char *key, int count, char **values, int append, int obfuscated_db, ivadmin_response *rsp );

Parameters
Input ctx cfg_file_name Specifies the local context created by the ivadmin_context_createlocal() function. Specifies the configuration file to use. This value can be a fully qualified path name to a configuration file or a reference to a Tivoli Access Manager configuration file. A reference to a Tivoli Access Manager configuration file is indicated by using one of the following constants: IVADMIN_CFG_CFGFILE_AMRTE Tivoli Access Manager runtime configuration file IVADMIN_CFG_CFGFILE_AMMGRD Tivoli Access Manager policy server configuration file IVADMIN_CFG_CFGFILE_AMACLD Tivoli Access Manager authorization server configuration file IVADMIN_CFG_CFGFILE_AMPROXY Tivoli Access Manager proxy server configuration file stanza Specifies the name of the stanza under which the input key is located. This value can be a user-defined stanza name, or a reference to a Tivoli Access Manager stanza. Stanzas used by Tivoli Access Manager components are listed in the appendices of the IBM Tivoli Access Manager Base Administration Guide. The following constants can be used: IVADMIN_CFG_STANZA_SSL SSL entries IVADMIN_CFG_STANZA_POLICY_SVR Tivoli Access Manager policy server entries key Specifies the name of the key whose value is to be set. This value can be a user-defined key name or a reference to a Tivoli Access Manager key. Keys used by Tivoli Access Manager components are

128

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

listed in the appendices of the IBM Tivoli Access Manager Base Administration Guide. The following constants can be used: IVADMIN_CFG_KEY_POLICY_SVR Tivoli Access Manager policy server host name and port IVADMIN_CFG_KEY_SSL_KEYFILE SSL keyfile path IVADMIN_CFG_KEY_SSL_STASHFILE SSL stashfile path IVADMIN_CFG_KEY_SSL_PASSWORD SSL password count values append Specifies the number of values to set. Array of character pointers to configuration values that are to be set for the specified key. Specifies whether or not the values should be appended to the current values associated with the key. If true, values are appended to the current values associated with the key. Any duplicate values are ignored. Otherwise, the input values replace any existing values for the key. Specifies whether or not the value should be obfuscated. If true, the key is placed in the obfuscated section of the configuration file. Otherwise, the key is placed in the non-obfuscated section.

obfuscated_db

Output rsp Specifies the response object. Indicates the success or failure of the function. Contains zero or more error, informational, and warning messages. Free this object when it is no longer needed.

Description
Sets the value of a specific key in a configuration file. If obfuscation is requested, the configuration file identified by the file key in the configuration-database stanza is updated. The caller must have the necessary operating system permissions to modify the configuration file, otherwise, IVADMIN_FALSE is returned. Command line equivalent:
pdadmin config modify keyvalue set [-obfuscate] config-file stanza key value pdadmin config modify keyvalue append [-obfuscate] config-file stanza key value

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

129

ivadmin_cfg_unconfigureserver()
Unconfigures an application server.

Syntax
unsigned long ivadmin_cfg_unconfigureserver( ivadmin_context ctx, const char *cfg_file_name, const char *server_name, const char *host_name, ivadmin_response *rsp );

Parameters
Input ctx cfg_file_name server_name Specifies the context to use when communicating with the Tivoli Access Manager policy server. Specifies the configuration file to use. Unless the configuration file is in the current directory, this must be a fully qualified path name. Specifies the name for the application or server. The server_name and host_name combination is used to uniquely identify the application. Specifies the host name on which the application runs.

host_name Output rsp

Specifies the response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

Description
This function reports success even if the server was not configured. This command destroys 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 function. Command line equivalent:
svrsslcfg unconfig -f cfg_file_name -n server_name \ [-P admin_password] [-A admin_ID]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

130

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_context_cleardelcred()
Clears the delegated credential for the context.

Syntax
unsigned long ivadmin_context_cleardelcred( ivadmin_context ctx, ivadmin_response *rsp );

Parameters
Input ctx The context used 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.

Description
Clears the delegated credential for the context.

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

131

ivadmin_context_create3()
Creates a security context for communicating with the Tivoli Access Manager policy server.

Syntax
unsigned long ivadmin_context_create3( const char *userid, const char *pwd, const char *domain, const char *codeset, const char *serverhost, unsigned long port, const char *keyringfile, const char *keyringstashfile, const char *configfile, ivadmin_context *ctx, ivadmin_response *rsp );

Parameters
Input userid Administrator user name to authenticate as. This user must have the appropriate administration authority to perform the desired administrative operations. Cannot be NULL. Administrator password. Cannot be NULL. Name of the domain to authenticate to. If this argument is IVADMIN_DOMAIN_MANAGEMENT, then the management domain is used. If this argument is IVADMIN_DOMAIN_LOCAL, then the local domain is used. These constants are defined in the ivadminapi.h file. If NULL is specified, the domain is obtained from the ssl-local-domain key in the ssl stanza of the specified configfile. codeset Character codeset. Indicates how the application encodes its character data. Cannot be NULL. The following constants are defined in the ivadminapi.h file: IVADMIN_CODESET_UTF8 Character data is encoded in UTF-8. IVADMIN_CODESET_LOCAL Character data is encoded in the local code page serverhost Policy server host name or IP address. If NULL is specified, the host name is obtained from the master-host key in the manager stanza in the specified configfile. Policy server listening port number. If NULL is specified, the port number is obtained from the master-port key in the manager stanza in the specified configfile. Fully qualified path name to the Secure Sockets Layer (SSL) keyring file which contains the public key of the Tivoli Access

pwd domain

port

keyringfile

132

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Manager policy server. If NULL is specified, the keyring file name is obtained from the ssl-keyfile key in the ssl stanza in the specified configfile. keyringstashfile Fully qualified path name to the stash file which contains the password used to access the keyring file. If NULL is specified, the keyring stash file name is obtained from the ssl-keyfile-stash key in the ssl stanza in the specified configfile. configfile Fully qualified path name to a local configuration file. If NULL is specified, the pd.conf file is used. The content of this configuration file is used to determine the values for any arguments that were not explicitly specified as input.

Output ctx rsp The new context. This is used to send administration requests to the policy server. Free this object when it is no longer needed. The response object. Indicates the success or failure of the function and might contain informational, warning or error information. Contains zero or more error, informational, and warning messages. Free this object when it is no longer needed.

Description
The context represents a connection to the Tivoli Access Manager policy server. To successfully create a context, the Tivoli Access Manager policy server must be available and the authentication must be successful. Command line equivalent:
pdadmin login [ -a admin_id [ -p password ] [ -d domain | -m ] ]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

133

ivadmin_context_createdefault2()
Creates a security context for communicating with the Tivoli Access Manager policy server using the default Secure Sockets Layer (SSL) configuration.

Syntax
unsigned long ivadmin_context_createdefault2( const char *userid, const char *pwd, const char *domainid, ivadmin_context *ctx, ivadmin_response *rsp );

Parameters
Input userid Administrator user name to authenticate as. This user must have the appropriate administrative authority to perform the desired administrative operations. Administrator password. Name of the domain to authenticate to. If this argument is IVADMIN_DOMAIN_MANAGEMENT, then the management domain is used. If this argument is IVADMIN_DOMAIN_LOCAL, then the local domain is used. These constants are defined in ivadminapi.h. If this argument is NULL, then the local domain is used.

pwd domainid

Output ctx The new context. This is used to send administration requests to the Tivoli Access Manager policy server. Free this object when it is no longer needed. The response object. Indicates the success or failure of the function and might contain informational, warning or error information. Free this object when it is no longer needed.

rsp

Description
The context represents a connection to the Tivoli Access Manager policy server. To successfully create a context, the Tivoli Access Manager policy server must be available and the authentication must be successful. The security context defined by this function treats character data as being encoded in the local codeset. Character data subsequently supplied to Tivoli Access Manager using this security context is converted to UTF-8 from the local codeset and data returned is converted from UTF-8 back to the local codeset. To have character data treated as UTF-8, create the security context using the ivadmin_context_create3() function and specify the appropriate value for the codeset parameter. Command line equivalent:
pdadmin login [ -a admin_id [ -p password ] [ -d domain | -m ] ]

134

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

135

ivadmin_context_createlocal()
Create a context used for local administration operations.

Syntax
unsigned long ivadmin_context_createlocal( const char *userid, const char *pwd, const char *domain, const char *codeset, ivadmin_context *ctx, ivadmin_response *rsp );

Parameters
Input userid pwd domain codeset Character codeset. Indicates how the application encodes its character data. Cannot be NULL. The following constants are defined in the ivadminapi.h file: IVADMIN_CODESET_UTF8 Character data is encoded in UTF-8. IVADMIN_CODESET_LOCAL Character data is encoded in the local code page Output ctx rsp The new context. This is used to send administration requests to the policy server. Free this object when it is no longer needed. The response object. Indicates the success or failure of the function and might contain zero or more informational, warning, andr error messages. Free this object when it is no longer needed. This argument is ignored. This argument is ignored This argument is ignored

Description
The context represents the authentication required to perform local Tivoli Access Manager administrative tasks. Local tasks are those tasks that do not require communication with the Tivoli Access Manager policy server. Command line equivalent:
pdadmin login -l

The pdadmin command always uses the local code page.

Return Values
Returns the following Boolean values:

136

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

137

ivadmin_context_delete()
Deletes a security context and frees any resources associated with the context. This includes deleting any connections with the Tivoli Access Manager policy server.

Syntax
unsigned long ivadmin_context_delete( ivadmin_context ctx, ivadmin_response *rsp );

Parameters
Input ctx The security context to delete. This could be a context used for communicating with the Tivoli Access Manager policy server or a local context.

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.

Description
Deletes the security context and any resources associated with that context. This function must be called before exiting the application. Deletes the connection with the Tivoli Access Manager policy server (if one exists) and frees Secure Sockets Layer (SSL) resources. The security context is not usable after this call. After deleting the context, free the context memory using the ivadmin_free function.

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

138

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_context_domainismanagement()
Indicates whether or not the specified context is authenticated to the management domain.

Syntax
unsigned long ivadmin_context_domainismanagement( ivadmin_context ctx );

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server.

Description
Returns whether or not the specified context is authenticated to the management domain. You must call the ivadmin_context_create3() or ivadmin_context_createdefault2() function to obtain an ivadmin_context object before using this function. Command line equivalent:
pdadmin context show

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The context is authenticated to the management domain. IVADMIN_FALSE Defined as 0. The context is not authenticated to the management domain.

Chapter 12. Administration C API reference

139

ivadmin_context_getaccexpdate()
Gets the account expiration date for all user accounts.

Syntax
unsigned long ivadmin_context_getaccexpdate( ivadmin_context ctx, unsigned long *seconds, unsigned long *unlimited, unsigned long *unset, ivadmin_response *rsp );

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server.

Output seconds Returned date and time of the expiration of all user accounts. This is the number of seconds since 00:00:00 Universal time, 1 January 1970 (same as time_t). Returned 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 is set 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.

unlimited

Description
Gets the account expiration date for all user accounts. Command line equivalent:
pdadmin policy get account-expiry-date

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

140

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_context_getcodeset()
Gets the character codeset associated with the specified security context.

Syntax
const char * ivadmin_context_getcodeset( ivadmin_context ctx );

Parameters
Input ctx Pointer to the context whose codeset is returned.

Description
Returns IVADMIN_CODESET_UTF8 if character data is encoded in UTF-8, or IVADMIN_CODESET_LOCAL if character data is encoded in the local code page. You must call the ivadmin_context_create3(), ivadmin_context_createdefault2(), or ivadmin_context_createlocal() function to obtain an ivadmin_context object before using this function. Do not free the character data string that is returned. This data is maintained in the ivadmin_context object. No command line equivalent, as the pdadmin command always uses the local code page.

Return Values
Returns the codeset that is in effect for this context. Valid return values are IVADMIN_CODESET_LOCAL and IVADMIN_CODESET_UTF8. These constants are defined in the ivadminapi.h file.

Chapter 12. Administration C API reference

141

ivadmin_context_getdisabletimeint()
Gets the time to disable user accounts when the maximum number of login failures is exceeded. This setting applies to all user accounts.

Syntax
unsigned long ivadmin_context_getdisabletimeint( ivadmin_context ctx, unsigned long *seconds, unsigned long *disable, unsigned long *unset, ivadmin_response *rsp );

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server.

Output seconds disable Disable the user account for the specified number of seconds if the maximum number of login failures is exceeded. Disable the user account if the maximum number of login failures is exceeded. 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 is set 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.

Description
Gets the time to disable user accounts if the maximum number of login failures has been exceeded. This setting applies to all user accounts. Command line equivalent:
pdadmin policy get disable-time-interval

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

142

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_context_getdomainid()
Gets the name of the domain associated with the specified context. This domain is the one chosen for this context when the context was created.

Syntax
const char * ivadmin_context_getdomainid( ivadmin_context ctx );

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server.

Description
Gets the domain name from the specified context object. You must call the ivadmin_context_create3() or ivadmin_context_createdefault2() function to obtain an ivadmin_context object before using this function. Do not free the character string that is returned. This data is maintained in the ivadmin_context object. Command line equivalent:
pdadmin context show

Return Values
The name of the domain to which the specified context is authenticated.

Chapter 12. Administration C API reference

143

ivadmin_context_getmaxlgnfails()
Gets the maximum number of login failures allowed for each user account.

Syntax
unsigned long ivadmin_context_getmaxlgnfails( ivadmin_context ctx, unsigned long *failures, unsigned long *unset, ivadmin_response *rsp );

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server.

Output failures unset Maximum number of login failures allowed. Policy ignored and not enforced if set to true. If set to false, the policy is set 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.

Description
Gets the maximum number of login failures allowed for each user account. Command line equivalent:
pdadmin policy get max-login-failures

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

144

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_context_getmaxpwdage()
Gets the maximum password age for all user accounts.

Syntax
unsigned long ivadmin_context_getmaxpwdage( ivadmin_context ctx, unsigned long *seconds, unsigned long *unset, ivadmin_response *rsp );

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server.

Output seconds unset Returned maximum lifetime, in seconds, before expiration of password. Policy ignored and not enforced if set to true. If set to false, the policy is set 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.

Description
Gets the maximum password age for all user accounts. Command line equivalent:
pdadmin policy get max-password-age

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

145

ivadmin_context_getmaxpwdrepchars()
Gets the maximum number of repeated characters allowed in a password for each user account.

Syntax
unsigned long ivadmin_context_getmaxpwdrepchars( ivadmin_context ctx, unsigned long *chars, unsigned long *unset, ivadmin_response *rsp );

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server.

Output chars unset Maximum number of repeated characters allowed. Policy ignored and not enforced if set to true. If set to false, the policy is set 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.

Description
Gets the maximum number of repeated characters allowed in a password for each user account. Command line equivalent:
pdadmin policy get max-password-repeated-chars

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

146

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_context_getmgmtdomainid()
Gets the name of the management domain.

Syntax
const char * ivadmin_context_getmgmtdomainid( ivadmin_context ctx );

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server.

Description
Gets the name of the management domain from the specified context object. You must call the ivadmin_context_create3() or ivadmin_context_createdefault2() function to obtain an ivadmin_context object before using this function. Do not free the character string that is returned. This data is maintained in the ivadmin_context object. There is no explicit command line equivalent. To login to the management domain, use the -m flag on pdadmin invocation, or use the login subcommand specifying m.

Return Values
The name of the management domain.

Chapter 12. Administration C API reference

147

ivadmin_context_getmgmtsvrhost()
Gets the name of the host system running the policy server with which this context has a communication session.

Syntax
const char * ivadmin_context_getmgmtsvrhost( ivadmin_context ctx );

Parameters
Input ctx Pointer to the context whose policy server host name is returned.

Description
Gets the policy server host name from the specified context object. You must call the ivadmin_context_create3() or ivadmin_context_createdefault2() function to obtain an ivadmin_context object before using this function. Do not free the character string that is returned. This data is maintained in the ivadmin_context object.

Return Values
The name of the host system which is running the policy server with which this context has a communication session.

148

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_context_getmgmtsvrport()
Gets the TCP/IP port of the policy server with which this context has a communication session.

Syntax
unsigned long ivadmin_context_getmgmtsvrport( ivadmin_context ctx );

Parameters
Input ctx Pointer to the context whose policy server port is returned.

Description
Gets the policy server port number from the specified context object. You must call the ivadmin_context_create3() or ivadmin_context_createdefault2() function to obtain an ivadmin_context object before using this function.

Return Values
The TCP/IP port of the policy server with which this context has a communication session.

Chapter 12. Administration C API reference

149

ivadmin_context_getminpwdalphas()
Gets the minimum number of alphabetic characters allowed in a password for each user account.

Syntax
unsigned long ivadmin_context_getminpwdalphas( ivadmin_context ctx, unsigned long *chars, unsigned long *unset, ivadmin_response *rsp );

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server.

Output chars unset Minimum number of alphabetic characters allowed. Policy ignored and not enforced if set to true. If set to false, the policy is set 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.

Description
Gets the minimum number of alphabetic characters allowed in a password for each user account. Command line equivalent:
pdadmin policy get min-password-alphas

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

150

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_context_getminpwdnonalphas()
Gets the minimum number of nonalphabetic characters allowed in a password for each user account.

Syntax
unsigned long ivadmin_context_getminpwdnonalphas( ivadmin_context ctx, unsigned long *chars, unsigned long *unset, ivadmin_response *rsp );

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server.

Output chars unset Minimum number of nonalphabetic characters allowed. Policy ignored and not enforced if set to true. If set to false, the policy is set 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.

Description
Gets the minimum number of nonalphabetic characters allowed in a password for each user account. Command line equivalent:
pdadmin policy get min-password-non-alphas

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

151

ivadmin_context_getminpwdlen()
Gets the minimum password length for all user accounts.

Syntax
unsigned long ivadmin_context_getminpwdlen( ivadmin_context ctx, unsigned long *length, unsigned long *unset, ivadmin_response *rsp );

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server.

Output length unset The minimum allowed password length. Policy ignored and not enforced if set to true. If set to false, the policy is set 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.

Description
Gets the minimum password length for all user accounts. Command line equivalent:
pdadmin policy get min-password-length

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

152

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_context_getpwdspaces()
Gets whether spaces are allowed in passwords for all user accounts.

Syntax
unsigned long ivadmin_context_getpwdspaces( ivadmin_context ctx, unsigned long *allowed, unsigned long *unset, ivadmin_response *rsp );

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server.

Output allowed Indicates 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 is set 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.

Description
Gets whether spaces are allowed in passwords for all user accounts. Command line equivalent:
pdadmin policy get password-spaces

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

153

ivadmin_context_gettodaccess()
Gets the global time of day access policy.

Syntax
unsigned long ivadmin_context_gettodaccess( ivadmin_context ctx, unsigned long *days, unsigned long *start, unsigned long *end, unsigned long *reference, unsigned long *unset, ivadmin_response *rsp );

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server.

Output days start end reference unset A bitmap of the days for the time of day access policy. The minutes after midnight for the start of the time range. The minutes after midnight for the end of the time range. The time zone: Coordinated Universal Time (UTC) or local. Policy ignored and not enforced if set to true. If set to false, the policy is set 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.

Description
Gets the global time of day access policy Command line equivalent:
pdadmin policy get todaccess

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

154

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_context_getuserid()
Gets the name of the user for which the specified context has authenticated. This user ID is the one specified for this context when the context was created.

Syntax
const char * ivadmin_context_getuserid( ivadmin_context ctx );

Parameters
Input ctx Pointer to the context whose userid is returned.

Description
Gets the user name from the specified context object. You must call the ivadmin_context_create3() or ivadmin_context_createdefault2() function to obtain an ivadmin_context object before using this function. Do not free the character string that is returned. This data is maintained in the ivadmin_context object. Command line equivalent:
pdadmin context show

Return Values
The name of the user that the specified context is authenticated as.

Chapter 12. Administration C API reference

155

ivadmin_context_getuserreg()
Returns an indicator of which type of user registry is configured for the Tivoli Access Manager policy server.

Syntax
unsigned long ivadmin_context_getuserreg( ivadmin_context ctx, unsigned long *registry, ivadmin_response *rsp );

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server.

Output registry Pointer a registry type indicator (IVADMIN_CONTEXT_DCEUSERREG or IVADMIN_CONTEXT_LDAPUSERREG). The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

rsp

Description
Returns an indicator of which type of user registry is configured for this Tivoli Access 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 Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

156

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_context_hasdelcred()
Returns an indicator whether or not the specified context has a delegated credential set.

Syntax
unsigned long ivadmin_context_hasdelcred( ivadmin_context ctx );

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server.

Description
Returns an indicator whether the specified context has a delegated credential associated with it. A delegated credential is associated with a context using the ivadmin_context_setdelcred() function and is removed from a context using the ivadmin_context_cleardelcred() function.:

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The context has a delegated credential. IVADMIN_FALSE Defined as 0. The context does not have a delegated credential.

Chapter 12. Administration C API reference

157

ivadmin_context_setaccexpdate()
Sets the account expiration date for all user accounts.

Syntax
unsigned long ivadmin_context_setaccexpdate( ivadmin_context ctx, unsigned long seconds, unsigned long unlimited, unsigned long unset, ivadmin_response *rsp );

Parameters
Input ctx seconds The context used to communicate with the Tivoli Access Manager policy server. Date and time of the expiration of all user accounts. This is the number of seconds since 00:00:00 Universal time, 1 January 1970 (same as time_t). Do 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 is set 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.

unlimited

Description
Sets the account expiration date for all user accounts. Command line equivalent:
pdadmin policy set account-expiry-date {unlimited | absolute_time | unset}

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

158

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_context_setdelcred()
Sets the delegated credential for the context based on the specified Privilege Attribute Certificate (PAC).

Syntax
unsigned long ivadmin_context_setdelcred( ivadmin_context ctx, const unsigned char* pacValue, const unsigned long pacLength, ivadmin_response *rsp );

Parameters
Input ctx pacValue pacLength 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. The context used to communicate with the Tivoli Access Manager policy server. The credential PAC data. The credential PAC length.

Description
Sets the delegated credential for the context based on the specified PAC. Only one credential can be delegated at a time. If a delegated credential already exists for this context, it is overwritten.

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

159

ivadmin_context_setdisabletimeint()
Sets the time to disable each user account when the maximum number of login failures is exceeded.

Syntax
unsigned long ivadmin_context_setdisabletimeint( ivadmin_context ctx, unsigned long seconds, unsigned long disable, unsigned long unset, ivadmin_response *rsp );

Parameters
Input ctx seconds disable The context used to communicate with the Tivoli Access Manager policy server. Disable the user account for the specified number of seconds when the maximum number of login failures is exceeded. Disable the user account when the maximum number of login failures is exceeded. 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 is set 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.

Description
Sets the time to disable each user account when the maximum number of login failures is exceeded. Command line equivalent:
pdadmin policy set disable-time-interval {number | unset | disable}

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

160

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_context_setmaxlgnfails()
Sets the maximum number of login failures allowed for each user account.

Syntax
unsigned long ivadmin_context_setmaxlgnfails( ivadmin_context ctx, unsigned long failures, unsigned long unset, ivadmin_response *rsp );

Parameters
Input ctx failures unset The context used to communicate with the Tivoli Access Manager policy server. Maximum number of login failures allowed. Policy ignored and not enforced if set to true. If set to false, the policy is set 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.

Description
Sets the maximum number of login failures allowed for each user account. Command line equivalent:
pdadmin policy set max-login-failures number | unset

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

161

ivadmin_context_setmaxpwdage()
Sets the maximum password age for all user accounts.

Syntax
unsigned long ivadmin_context_setmaxpwdage( ivadmin_context ctx, unsigned long seconds, unsigned long unset, ivadmin_response *rsp );

Parameters
Input ctx seconds unset The context used to communicate with the Tivoli Access Manager policy server. Maximum lifetime, in seconds, before expiration of a password. Policy ignored and not enforced if set to true. If set to false, the policy is set 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.

Description
Sets the maximum password age for all user accounts. Command line equivalent:
pdadmin policy set max-password-age {unset | relative_time}

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

162

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_context_setmaxpwdrepchars()
Sets the maximum number of repeated characters allowed in a password for each user account.

Syntax
unsigned long ivadmin_context_setmaxpwdrepchars( ivadmin_context ctx, unsigned long chars, unsigned long unset, ivadmin_response *rsp );

Parameters
Input ctx chars unset The context used to communicate with the Tivoli Access Manager policy server. Maximum number of repeated characters allowed. Policy ignored and not enforced if set to true. If set to false, the policy is set 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.

Description
Sets the maximum number of repeated characters allowed in a password for each user account. Command line equivalent:
pdadmin policy set max-password-repeated-chars number | unset

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

163

ivadmin_context_setminpwdalphas()
Sets the minimum number of alphabetic characters allowed in a password for each user account.

Syntax
unsigned long ivadmin_context_setminpwdalphas( ivadmin_context ctx, unsigned long chars, unsigned long unset, ivadmin_response *rsp );

Parameters
Input ctx chars unset The context used to communicate with the Tivoli Access Manager policy server. Minimum number of alphabetic characters allowed. Policy ignored and not enforced if set to true. If set to false, the policy is set 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.

Description
Sets the minimum number of alphabetic characters allowed in a password for each user account. Command line equivalent:
pdadmin policy set min-password-alphas {unset | number}

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

164

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_context_setminpwdnonalphas()
Sets the minimum number of nonalphabetic characters allowed in a password for each user account.

Syntax
unsigned long ivadmin_context_setminpwdnonalphas( ivadmin_context ctx, unsigned long chars, unsigned long unset, ivadmin_response *rsp );

Parameters
Input ctx chars unset The context used to communicate with the Tivoli Access Manager policy server. Minimum number of nonalphabetic characters allowed. Policy ignored and not enforced if set to true. If set to false, the policy is set 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.

Description
Sets the minimum number of nonalphabetic characters allowed in a password for each user account. Command line equivalent:
pdadmin policy set min-password-non-alphas {unset | number}

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

165

ivadmin_context_setminpwdlen()
Sets the minimum password length for each user account.

Syntax
unsigned long ivadmin_context_setminpwdlen( ivadmin_context ctx, unsigned long length, unsigned long unset, ivadmin_response *rsp );

Parameters
Input ctx length unset The context used to communicate with the Tivoli Access Manager policy server. Minimum allowed password length to be set. Policy ignored and not enforced if set to true. If set to false, the policy is set 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.

Description
Sets the minimum password length for each user account. Command line equivalent:
pdadmin policy set min-password-length {unset | number}

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

166

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_context_setpwdspaces()
Sets whether spaces are allowed in passwords for all user accounts.

Syntax
unsigned long ivadmin_context_setpwdspaces( ivadmin_context ctx, unsigned long allowed, unsigned long unset, ivadmin_response *rsp );

Parameters
Input ctx allowed The context used to communicate with the Tivoli Access Manager policy server. Indicates 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 is set 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.

Description
Sets whether spaces are allowed in passwords for all user accounts. Command line equivalent:
pdadmin policy set password-spaces {yes | no | unset}

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

167

ivadmin_context_settodaccess()
Sets the global time of day access policy.

Syntax
unsigned long ivadmin_context_settodaccess( ivadmin_context ctx, unsigned long days, unsigned long start, unsigned long end, unsigned long reference, unsigned long unset, ivadmin_response *rsp );

Parameters
Input ctx days start end reference unset The context used to communicate with the Tivoli Access Manager policy server. A bitmap of the days for the time of day policy. The minutes after midnight for the start of the time range. The minutes after midnight for the end of the time range. The time zone: Coordinated Universal Time (UTC) or local. Policy ignored and not enforced if set to true. If set to false, the policy is set 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.

Description
Sets the global yime of day access policy. Command line equivalent:
pdadmin policy set todaccess todaccess_string

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

168

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_domain_create()
Creates a new domain

Syntax
unsigned long ivadmin_domain_create(ivadmin_context ctx, const char *domainid, const char *adminid, const char *password, const char *description, ivadmin_response *rsp);

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server. This context must be authenticated to the management domain. Name of the domain to create. Name of the domain administrator. Cannot be NULL or an empty string. The initial password for the specified adminid account in the new domain. Description of the new domain. Cannot be NULL.

domainid adminid password description Output rsp

The response object. Indicates the success or failure of the function and might contain informational, warning or error information. Free this object when it is no longer needed.

Description
Creates a new domain with the specified description. If this domain had been created earlier and then deleted without deleting the associated user and group data from the user registry, those users and groups will be available automatically after this API is invoked. In that case, a special response message will be returned to indicate that is the case. Command line equivalent:
pdadmin domain create domain_name domain_admin domain_admin_password [ -desc description ]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

169

ivadmin_domain_delete()
Deletes a domain

Syntax
unsigned long ivadmin_domain_delete(ivadmin_context ctx, const char *domainid, unsigned long registry, ivadmin_response *rsp);

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server. This context must be authenticated to the management domain. Name of the domain to delete. Indicates whether to delete the domains user and group data from the user registry as well as from Tivoli Access Manager. Supported values are IVADMIN_TRUE and IVADMIN_FALSE. If a domains user and group data is not deleted from the user registry, those users and groups will be available automatically if the domain is recreated.

domainid registry

Output rsp The response object. Indicates the success or failure of the function and might contain informational, warning or error information. Free this object when it is no longer needed.

Description
Deletes a domain. If the registry argument is IVADMIN_TRUE, the domains user and group data will also be removed from the user registry. If a domains user and group data is not deleted from the user registry, those users and groups will be available automatically if the domain is created again. Command line equivalent:
pdadmin domain delete domain_name [-registry]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

170

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_domain_get()
Gets the specified domain object

Syntax
unsigned long ivadmin_domain_get( ivadmin_context ctx, const char *domainid, ivadmin_domain *domain, ivadmin_response *rsp);

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server. This context must be authenticated to the management domain. Name of the domain to return.

domainid Output domain rsp

The domain object. Free this object when it is no longer needed. The response object. Indicates the success or failure of the function and might contain informational, warning or error information. Free this object when it is no longer needed.

Description
Gets a domain. Command line equivalent:
pdadmin domain show domain_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

171

ivadmin_domain_getdescription()
Gets the description for the specified domain.

Syntax
const char * ivadmin_domain_getdescription( ivadmin_domain domain );

Parameters
Input domain Pointer to the domain object.

Description
Gets the description from the specified domain object. You must call the ivadmin_domain_get() function to obtain an ivadmin_domain object before using this function. Do not free the character string that is returned. This data is maintained in the ivadmin_domain object. Command line equivalent:
pdadmin domain show domain_name

The description is part of the information returned by the pdadmin command.

Return Values
Returns the description associated with the domain, or an empty string if the domain has no description.

172

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_domain_getid()
Gets the name of the specified domain.

Syntax
const char * ivadmin_domain_getid( ivadmin_domain domain );

Parameters
Input domain Pointer to the domain object.

Description
Gets the name from the specified domain object. You must call the ivadmin_domain_get() function to obtain an ivadmin_domain object before using this function. Do not free the character string that is returned. This data is maintained in the ivadmin_domain object. Command line equivalent:
pdadmin domain show domain_name

The domain name is part of the information returned by the pdadmin command.

Return Values
The name of the specified domain.

Chapter 12. Administration C API reference

173

ivadmin_domain_list()
Lists the names of all the domains, not including the management domain.

Syntax
unsigned long ivadmin_domain_list( ivadmin_context ctx, unsigned long *count, char ***domainids, ivadmin_response *rsp );

Parameters
Input ctx The context used to communicate with the policy server. This context must be authenticated to the management domain.

Output count Number of domain identifiers returned. Can be zero if no domains other than the management domain exist, or an error is encountered. Array of pointers to domain names. Free each domain name and the array of pointers when they are no longer needed. The response object. Indicates the success or failure of the function and might contain informational, warning or error information. Free this object when it is no longer needed.

domainids rsp

Description
Lists the names of all the domains, except the management domain. Command line equivalent:
pdadmin domain list

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

174

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_domain_setdescription()
Changes the description for the specified domain.

Syntax
unsigned long ivadmin_domain_setdescription( ivadmin_context ctx, const char *domainid, const char *description, ivadmin_response *rsp );

Parameters
Input ctx domainid description Output rsp The response object. Indicates the success or failure of the function and might contain informational, warning or error information. Free this object when it is no longer needed. The context used to communicate with the policy server. This context must be authenticated to the management domain. Name of the domain. Cannot be NULL or an empty string. The new description. Cannot be NULL.

Description
Changes the description for the specified domain. Command line equivalent:
pdadmin domain modify domain_name description description

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

175

ivadmin_free()
Frees the memory that has been allocated to the specified object.

Syntax
void ivadmin_free( void p* );

Parameters
Input p Pointer to the object to be freed.

Description
Frees the memory that has been allocated to the specified object. Use this function to free all memory that has been allocated by the administration API functions. There is no command line equivalent for this function.

176

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_group_addmembers()
Adds the specified users to the specified group.

Syntax
unsigned long ivadmin_group_addmembers( ivadmin_context ctx, const char *groupid, unsigned long user_count, const char **users, ivadmin_response *rsp );

Parameters
Input ctx groupid user_count users 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. The context used to communicate with the Tivoli Access Manager policy server. Group name. The number of users to be added to the group. New member user names.

Description
Adds the specified users to the specified group. Tivoli Access Manager does not support 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 handled differently depending on what user registry is being used. See Appendix B, User registry differences, on page 349 for details.

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

177

ivadmin_group_create2()
Creates a group.

Syntax
unsigned long ivadmin_group_create2( ivadmin_context ctx, const char *groupid, const char *dn, const char *cn, const char *group_container, ivadmin_response *rsp );

Parameters
Input ctx groupid dn cn group_container Container object within the management object space. Can be NULL to indicate 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. The context used to communicate with the Tivoli Access Manager policy server. Group name. User registry distinguished name. User registry common name attribute.

Description
Creates a new Tivoli Access Manager group by creating a new group in the user registry with the specified name, distinguished name, and common name. User registry difference: Leading and trailing blanks in a group name do not make the name unique when using an LDAP or Active Directory user registry. However, leading and trailing blanks do make the group name unique when using a Domino server as a user registry. To keep name processing consistent regardless of what user registry is being used, do not define group names with leading or trailing blanks. Command line equivalent:
pdadmin group create group_name dn cn

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful.

178

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

179

ivadmin_group_delete2()
Deletes the specified group.

Syntax
unsigned long ivadmin_group_delete2( ivadmin_context ctx, const char *groupid, unsigned long registry, ivadmin_response *rsp );

Parameters
Input ctx groupid registry The context used to communicate with the Tivoli Access Manager policy server. Group name. Indicates whether to delete the group 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.

Description
Deletes the specified group. Deletes all Tivoli Access Manager information about the group and optionally deletes the user registry contents. Command line equivalent:
pdadmin group delete [registry] group_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

180

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_group_get()
Gets the specified group object.

Syntax
unsigned long ivadmin_group_get( ivadmin_context ctx, const char *groupid, ivadmin_ldapgroup *group, ivadmin_response *rsp );

Parameters
Input ctx groupid Output group rsp Returned group. Free the memory for this ivadmin_ldapgroup object when it is no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed. The context used to communicate with the Tivoli Access Manager policy server. Group name.

Description
Gets the group object for the specified group name. Free the memory for this ivadmin_ldapgroup object when it is no longer needed. Command line equivalent:
pdadmin group show group-name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

181

ivadmin_group_getbydn()
Returns a group user using the user registry distinguished name for identification.

Syntax
unsigned long ivadmin_group_getbydn( ivadmin_context ctx, const char *dn, ivadmin_ldapgroup *group, ivadmin_response *rsp );

Parameters
Input ctx dn Output group rsp Returned group. Free this memory when no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed. The context used to communicate with the Tivoli Access Manager policy server. User registry distinguished name of group.

Description
Returns a group user using the user registry DN for identification. Free the memory for this ivadmin_ldapgroup object when it is no longer needed. User registry difference: The maximum length of the distinguished name varies depending on the user registry being used. See Appendix B, User registry differences, on page 349 to determine the maximum length in your environment. Command line equivalent:
pdadmin group show-dn dn

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

182

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_group_getcn()
Returns the user registry common name attribute for the specified group.

Syntax
const char * ivadmin_group_getcn( ivadmin_ldapgroup group );

Parameters
Input group Pointer to the group structure.

Description
Returns the user registry common name attribute from the specified group object. Do not free this memory. This data is maintained in the ivadmin_ldapgroup structure. User registry difference: The maximum length of the common name varies depending on the user registry being used. See Appendix B, User registry differences, on page 349 to determine 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 the pdadmin group show command.

Return Values
Returns the user registry common name attribute for the specified group.

Chapter 12. Administration C API reference

183

ivadmin_group_getdescription()
Returns the user registry description for the specified group.

Syntax
const char * ivadmin_group_getdescription( ivadmin_ldapgroup group );

Parameters
Input group Pointer to the group structure.

Description
Returns the user registry description for the specified group. Do not free this memory. This data is maintained in the ivadmin_ldapgroup structure. Command line equivalent:
pdadmin group show group-name

The description is part of the information returned by the pdadmin group show command.

Return Values
Returns the user registry description for the specified group. The maximum length of a description is 1024 characters.

184

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_group_getdn()
Returns the user registry distinguished name for the specified group.

Syntax
const char * ivadmin_group_getdn( ivadmin_ldapgroup group );

Parameters
Input group Pointer to the group structure.

Description
Returns the user registry distinguished name for the specified group. Do not free this memory. This data is maintained in the ivadmin_ldapgroup structure. User registry difference: The maximum length of the distinguished name varies depending on the user registry being used. See Appendix B, User registry differences, on page 349 to determine 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 the pdadmin group show command.

Return Values
Returns the user registry distinguished name for the specified group.

Chapter 12. Administration C API reference

185

ivadmin_group_getid()
Returns the group name from the specified group object.

Syntax
const char * ivadmin_group_getid( ivadmin_ldapgroup group );

Parameters
Input group Pointer to the group structure.

Description
Returns the group name from the specified group object. Do not free this memory. This data is maintained in the ivadmin_ldapgroup structure. Command line equivalent:
pdadmin group show group-name

The group name is part of the information returned by the pdadmin group show command.

Return Values
Returns the group name from the specified group object. The maximum length of a group name is 256 characters.

186

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_group_getmembers()
Lists the user names of the members of the specified group.

Syntax
unsigned long ivadmin_group_getmembers( ivadmin_context ctx, const char *groupid, unsigned long *count, char ***userids, ivadmin_response *rsp );

Parameters
Input ctx groupid Output count userids The number of user names returned. Zero is returned if an error occurs. An array of pointers to the user names returned. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed. The context used to communicate with the Tivoli Access Manager policy server. Group name.

rsp

Description
Lists the user names of the members of the specified group. Command line equivalent:
pdadmin group show-members group_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

187

ivadmin_group_import2()
Creates an Tivoli Access Manager group by importing a group that already exists in the user registry.

Syntax
unsigned long ivadmin_group_import2( ivadmin_context ctx, const char *groupid, const char *dn, const char *group_container, ivadmin_response *rsp );

Parameters
Input ctx groupid dn group_container Container object within the management object space. Can be NULL to indicate 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. The context used to communicate with the Tivoli Access Manager policy server. Group name. User registry distinguished name.

Description
Creates an Tivoli Access Manager group by importing a group that already exists in the user registry. Command line equivalent:
pdadmin group import group_name dn

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

188

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_group_list()
Lists the names of the Tivoli Access Manager groups.

Syntax
unsigned long ivadmin_group_list( ivadmin_context ctx, const char *pattern, unsigned long maxreturn, unsigned long *count, char ***groupids, ivadmin_response *rsp );

Parameters
Input ctx pattern maxreturn The context used to communicate with the Tivoli Access Manager policy server. Pattern match for group names. IVADMIN_ALLPATTERN indicates all groups. Maximum number to return. IVADMIN_MAXRETURN indicates unlimited. This number can also be limited by the user registry server so the maximum returned is really the minimum of the server configuration and this value.

Output count groupids The number of group names returned. Zero is returned if an error occurs. An array of pointers to the group names returned. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

rsp

Description
Lists the Tivoli Access Manager groups. Returns the list of group names whose name matches the pattern specified. The order returned is the order created. Command line equivalent:
pdadmin group list pattern max_return

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful.

Chapter 12. Administration C API reference

189

IVADMIN_FALSE Defined as 0. The function encountered an error.

190

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_group_listbydn()
Returns the list of user registry distinguished names whose user registry common name attribute matches the pattern specified.

Syntax
unsigned long ivadmin_group_listbydn( ivadmin_context ctx, const char *pattern, unsigned long maxreturn, unsigned long *count, char ***dns, ivadmin_response *rsp );

Parameters
Input ctx pattern maxreturn The context used to communicate with the Tivoli Access Manager policy server. Pattern match for common name attribute. IVADMIN_ALLPATTERN indicates all users. Maximum number to return. IVADMIN_MAXRETURN indicates unlimited. This number can also be limited by the user registry server so that the maximum returned is really the minimum of the server configuration and this value.

Output count dns The number of user registry distinguished names returned. Zero is returned if an error occurs. An array of pointers to the user registry distinguished names returned. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

rsp

Description
Returns the list of user registry distinguished names whose user registry common name attributes match the pattern specified. User registry difference: The maximum length of the distinguished name varies depending on the user registry being used. See Appendix B, User registry differences, on page 349 to determine the maximum length in your environment. Command line equivalent:
pdadmin group list-dn pattern max_return

Chapter 12. Administration C API reference

191

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

192

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_group_removemembers()
Removes the specified users from the specified group.

Syntax
unsigned long ivadmin_group_removemembers( ivadmin_context ctx, const char *groupid, unsigned long user_count, const char **users, ivadmin_response *rsp );

Parameters
Input ctx groupid user_count users 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. The context used to communicate with the Tivoli Access Manager policy server. Group name. Number of user names to remove. Member user names to remove.

Description
Removes 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 ... )

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

193

ivadmin_group_setdescription()
Changes the description for the specified group.

Syntax
unsigned long ivadmin_group_setdescription( ivadmin_context ctx, const char *groupid, const char *description, ivadmin_response *rsp );

Parameters
Input ctx groupid 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. The context used to communicate with the Tivoli Access Manager policy server. Group name. New description.

Description
Changes the description for the specified group. Command line equivalent:
pdadmin group modify group_name description description

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

194

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_objectspace_create()
Creates an Tivoli Access Manager protected object space.

Syntax
unsigned long ivadmin_objectspace_create( ivadmin_context ctx, const char *objspaceid, unsigned long type, const char *description, ivadmin_response *rsp );

Parameters
Input ctx objspaceid type 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the object space to create. The type of object space to create. A description for the object space.

Description
Creates an Tivoli Access Manager protected object space. You must specify as the input parameter type, the object space type for each new object space. The object space type is used by the Tivoli Access Manager Web Portal Manager to display an appropriate icon with the object. Note: The root of the new protected object space automatically has the ispolicyattachable attribute set to true. For more information, see ivadmin_protobj_setpolicyattachable() on page 265. The supported object types are in Table 33.
Table 33. Supported object types Variable Name IVADMIN_PROTOBJ_TYPE_UNKNOWN IVADMIN_PROTOBJ_TYPE_DOMAIN IVADMIN_PROTOBJ_TYPE_FILE IVADMIN_PROTOBJ_TYPE_PROGRAM IVADMIN_PROTOBJ_TYPE_DIR IVADMIN_PROTOBJ_TYPE_JNCT IVADMIN_PROTOBJ_TYPE_WEBSEAL_SVR Value 0 1 2 3 4 5 6 Description Unknown Secure domain File Executable program Directory Junction WebSEAL server

Chapter 12. Administration C API reference

195

Table 33. Supported object types (continued) Variable Name IVADMIN_PROTOBJ_TYPE_NETSEAL_SVR IVADMIN_PROTOBJ_TYPE_EXTERN_AUTH_SVR IVADMIN_PROTOBJ_TYPE_HTTP_SVR IVADMIN_PROTOBJ_TYPE_NON_EXIST_OBJ IVADMIN_PROTOBJ_TYPE_CONTAINER IVADMIN_PROTOBJ_TYPE_LEAF IVADMIN_PROTOBJ_TYPE_PORT IVADMIN_PROTOBJ_TYPE_APP_CONTAINER IVADMIN_PROTOBJ_TYPE_APP_LEAF IVADMIN_PROTOBJ_TYPE_MGMT_OBJ IVADMIN_PROTOBJ_TYPE_NETSEAL_NET Value 7 8 9 10 11 12 13 14 15 16 17 Description Unused Unused Unused Nonexistent object Container object Leaf object Port Application container object Application leaf object Management object Unused

Command line equivalent:


pdadmin objectspace create objectspace_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

196

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_objectspace_delete()
Deletes the specified Tivoli Access Manager protected object space.

Syntax
unsigned long ivadmin_objectspace_delete( ivadmin_context ctx, const char *objspaceid, ivadmin_response *rsp );

Parameters
Input ctx objspaceid 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the object space to delete.

Description
Deletes the specified Tivoli Access Manager protected object space. Command line equivalent:
pdadmin objectspace delete objectspace_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

197

ivadmin_objectspace_list()
Lists the names of all the Tivoli Access Manager protected object spaces.

Syntax
unsigned long ivadmin_objectspace_list( ivadmin_context ctx, unsigned long *count, char ***objspace_list, ivadmin_response *rsp );

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server.

Output count objspace_list The number of object space names returned. Zero is returned if an error occurs. An array of pointers to the names of the object spaces returned. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

rsp

Description
Lists all the Tivoli Access Manager protected object spaces. Command line equivalent:
pdadmin objectspace list

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

198

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_pop_attach()
Attaches a protected object policy (POP) to the specified protected object.

Syntax
unsigned long ivadmin_pop_attach( ivadmin_context ctx, char *popid, char *objid, ivadmin_response *rsp );

Parameters
Input ctx popid objid 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object policy to attach. The name of the protected object.

Description
Attaches a protected object policy to the specified protected object. Be sure that the protected object exists in the protect object space before attempting to attach a POP. Command line equivalent:
pdadmin attach object_name pop_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

199

ivadmin_pop_attrdelkey()
Deletes the specified extended attribute from the specified protected object policy (POP).

Syntax
unsigned long ivadmin_pop_attrdelkey( ivadmin_context ctx, char *popid, char *attr_key, ivadmin_response *rsp );

Parameters
Input ctx popid attr_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. The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object policy. The extended attribute to delete.

Description
Deletes the specified extended attribute from the specified protected object policy. Command line equivalent:
pdadmin pop modify pop_name delete attribute attribute_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

200

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_pop_attrdelval()
Deletes the specified value from the specified extended attribute key in the specified protected object policy (POP).

Syntax
unsigned long ivadmin_pop_attrdelval( ivadmin_context ctx, char *popid, char *attr_key, char *attr_value, ivadmin_response *rsp );

Parameters
Input ctx popid attr_key attr_value 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object policy. The extended attribute containing the value that is to be deleted. The value to delete from the extended attribute.

Description
Deletes the specified value from the specified extended attribute key in the specified protected object policy. Command line equivalent:
pdadmin pop modify pop_name delete attribute attribute_name attribute_value

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

201

ivadmin_pop_attrget()
Gets the values for the specified extended attribute from the specified protected object policy.

Syntax
unsigned long ivadmin_pop_attrget( ivadmin_pop pop, char *attr_key, unsigned long *count, char ***attr_value );

Parameters
Input pop attr_key Output count attr_value The number of values returned. Zero is returned if an error occurs. An array of pointers to the extended attribute values returned. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. The protected object policy to be accessed. The extended attribute to get.

Description
Gets the values for the specified extended attribute from the specified protected object policy. The value returned is in the same format as when it was created using the ivadmin_pop_attrput() function. If an error occurs, NULL is returned. Command line equivalent:
pdadmin pop show pop_name attribute

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

202

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_pop_attrlist()
Lists the extended attributes associated with the specified protected object policy.

Syntax
unsigned long ivadmin_pop_attrlist( ivadmin_pop pop, unsigned long *count, char ***attr_list );

Parameters
Input pop Output count attr_list The number of extended attributes returned. Zero is returned if an error occurs. An array of pointers to the extended attributes returned. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. The protected object policy.

Description
Lists the extended attributes associated with the specified protected object policy. If an error occurs, NULL is returned. Command line equivalent:
pdadmin pop list pop_name attribute

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

203

ivadmin_pop_attrput()
Sets the value for the specified extended attribute in the specified protected object policy.

Syntax
unsigned long ivadmin_pop_attrput( ivadmin_context ctx, char *popid, char *attr_key, char *attr_value, ivadmin_response *rsp );

Parameters
Input ctx popid attr_key attr_value 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object policy. The extended attribute for which a value must be set. The value to set.

Description
Sets the value for the specified extended attribute in the specified protected object policy. Command line equivalent:
pdadmin modify pop_name set attribute attribute_name attribute_value

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

204

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_pop_create()
Creates a protected object policy object.

Syntax
unsigned long ivadmin_pop_create( ivadmin_context ctx, const char *popid, ivadmin_response *rsp );

Parameters
Input ctx popid 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object policy to create.

Description
Creates a protected object policy object with the default values seen in Table 34.
Table 34. Protected object policy default values Attribute Name Description none Default Value

Warning mode no Audit level Quality of protection Time of day access IP endpoint authentication method policy Any other cetwork none none sun, mon, tue, wed, thu, fri, sat:anytime:local 0

For more information about creating POPs, see the section about creating and deleting protected object policies in the IBM Tivoli Access Manager Base Administration Guide. Command line equivalent:
pdadmin pop create pop_name

Chapter 12. Administration C API reference

205

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

206

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_pop_delete()
Deletes the specified protected object policy.

Syntax
unsigned long ivadmin_pop_delete( ivadmin_context ctx, const char *popid, ivadmin_response *rsp );

Parameters
Input ctx popid 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object policy to delete.

Description
Deletes the specified protected object policy. Command line equivalent:
pdadmin pop delete pop_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

207

ivadmin_pop_detach()
Detaches a protected object policy (POP) from the specified protected object.

Syntax
unsigned long ivadmin_pop_detach( ivadmin_context ctx, char *objid, ivadmin_response *rsp );

Parameters
Input ctx objid 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. The context used to communicate with the Tivoli Access Manager policy server. The protected object to detach from.

Description
Detaches a protected object policy from the specified protected object. Command line equivalent:
pdadmin pop detach pop_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

208

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_pop_find()
Finds and lists the names of all protected objects that have the specified protected object policy attached.

Syntax
unsigned long ivadmin_pop_find( ivadmin_context ctx, char *popid, unsigned long *count, char ***obj_list, ivadmin_response *rsp );

Parameters
Input ctx popid Output count obj_list The number of protected objects returned. Zero is returned if an error occurs. An array of pointers to the protected objects returned. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed. The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object policy to find.

rsp

Description
Finds and lists all protected objects that have the specified protected object policy attached. Command line equivalent:
pdadmin pop find pop_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

209

ivadmin_pop_get()
Gets the specified protected object policy object.

Syntax
unsigned long ivadmin_pop_get( ivadmin_context ctx, char *popid, ivadmin_pop *pop, ivadmin_response *rsp );

Parameters
Input ctx popid Output pop rsp The protected object policy that is returned. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed. The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object policy to get.

Description
Gets the specified protected object policy object. Call this function to get an object of 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 Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

210

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_pop_getanyothernw()
Gets the anyothernw, or any other network, setting for the IP authentication level from the specified protected object policy.

Syntax
unsigned long ivadmin_pop_getanyothernw( ivadmin_pop pop unsigned long *level, );

Parameters
Input pop level The name of the protected object policy. Returns the authentication level associated with anyothernw.

Description
Returns the anyothernw, or any other network, setting for the authentication level from the specified protected object policy (POP). Command line equivalent:
pdadmin pop show pop_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

211

ivadmin_pop_getauditlevel()
Gets the audit level for the specified protected object policy.

Syntax
unsigned long ivadmin_pop_getauditlevel( ivadmin_pop pop );

Parameters
Input pop The protected object policy.

Description
Gets 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 Values
Audit level is specified as an unsigned long. The following audit levels are defined:
#define #define #define #define #define #define IVADMIN_AUDIT_NONE IVADMIN_AUDIT_PERMIT IVADMIN_AUDIT_DENY IVADMIN_AUDIT_ERROR IVADMIN_AUDIT_ADMIN IVADMIN_AUDIT_ALL (0) (1) (2) (4) (8) (15)

Descriptions for the audit levels can be found in Table 35.


Table 35. Descriptions of audit levels Audit Value none permit deny error admin all Auditing is disabled. Audit all requests on a protected object that result in successful access. Audit all requests on a protected object that result in denial of access. Audit all internally generated error messages when access to the protected object is denied. Not implemented. Audit success, error, and failure for all events. Description

212

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_pop_getdescription()
Gets the description of the specified protected object policy.

Syntax
const char* ivadmin_pop_getdescription( ivadmin_pop pop );

Parameters
Input pop The protected object policy.

Description
Gets the description of the specified protected object policy. You must call ivadmin_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 Values
Gets the description of the specified protected object policy. There is no limit to the length of the description.

Chapter 12. Administration C API reference

213

ivadmin_pop_getid()
Gets the name of the specified protected object policy.

Syntax
const char* ivadmin_pop_getid( ivadmin_pop pop );

Parameters
Input pop The protected object policy.

Description
Gets the name of the specified protected object policy. You must call ivadmin_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 Values
Gets the name of the specified protected object policy. There is no limit to the name of the policy.

214

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_pop_getipauth()
Gets the IP endpoint authentication setting in the specified protected object policy.

Syntax
unsigned long ivadmin_pop_getipauth( ivadmin_pop pop, unsigned long *count, unsigned long **network, unsigned long **netmask, unsigned long **authMethod, );

Parameters
Input pop Output count network netmask authMethod The number of settings retrieved. The array of network addresses. The array of netmasks. The array of authentication levels associated with the network. The protected object policy.

Description
Gets the IP endpoint authentication settings in the specified protected object policy. You must call ivadmin_pop_get() to obtain an ivadmin_pop object before calling this function. Command line equivalent:
pdadmin pop show pop_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

215

ivadmin_pop_getqop()
Gets the quality of protection level for the specified protected object policy.

Syntax
const char* ivadmin_pop_getqop( ivadmin_pop pop );

Parameters
Input pop The protected object policy.

Description
Gets 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 pdadmin command.

Return Values
Gets the quality of protection level for the specified protected object policy. The following levels are defined: v none v integrity v privacy

216

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_pop_gettod()
Gets the time of day range for the specified protected object policy.

Syntax
unsigned long ivadmin_pop_gettod( ivadmin_pop pop, unsigned long *days, unsigned long *start, unsigned long *end, unsigned long *reference );

Parameters
Input pop Output days start end reference A bitmap of the days. The minutes for the start of the range. The minutes for the end of the range. The time reference; either Universal Time Coordinated (UTC) or local. The protected object policy.

Description
Gets 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 pdadmin command. The following values are defined for time of day settings:
#define #define #define #define #define #define #define #define #define #define #define #define #define #define #define IVADMIN_TIME_LOCAL (0) IVADMIN_TIME_UTC (1) IVADMIN_TOD_ANY (0) IVADMIN_TOD_SUN (1) IVADMIN_TOD_MON (2) IVADMIN_TOD_TUE (4) IVADMIN_TOD_WED (8) IVADMIN_TOD_THU (16) IVADMIN_TOD_FRI (32) IVADMIN_TOD_SAT (64) IVADMIN_TOD_ALL (127) IVADMIN_TOD_WEEKDAY (62) IVADMIN_TOD_WEEKEND (65) IVADMIN_TOD_MINUTES (60) IVADMIN_TOD_OCLOCK (3600)

Return Values
Returns the following Boolean values:

Chapter 12. Administration C API reference

217

IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

218

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_pop_getwarnmode()
Gets the warning mode value from the specified protected object policy.

Syntax
unsigned long ivadmin_pop_getwarnmode( ivadmin_pop pop );

Parameters
Input pop The protected object policy.

Description
Gets 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 pdadmin command.

Return Values
Returns the warning mode set for this protected object policy.

Chapter 12. Administration C API reference

219

ivadmin_pop_list()
Lists the names of all protected object policy objects.

Syntax
unsigned long ivadmin_pop_list( ivadmin_context ctx, unsigned long *count, char ***poplist, ivadmin_response *rsp );

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server.

Output count poplist The number of protected object policies returned. Zero is returned if an error occurs. An array of pointers to the protected object policies returned. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

rsp

Description
Lists all protected object policy objects. Command line equivalent:
pdadmin pop list

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

220

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_pop_removeipauth()
Removes the IP endpoint authentication settings from the specified protected object policy.

Syntax
unsigned long ivadmin_pop_removeipauth( ivadmin_context ctx, char *popid, char *network, char *netmask, ivadmin_response *rsp );

Parameters
Input ctx popid network netmask 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object policy. The network address to delete. The netmask address.

Description
Removes the IP endpoint authentication settings from the specified protected object policy. Command line equivalent:
pdadmin pop modify pop_name set ipauth remove network netmask

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

221

ivadmin_pop_setanyothernw()
Sets the anyothernw, or any other network, setting for the IP authentication level from the specified protected object policy.

Syntax
unsigned long ivadmin_pop_setanyothernw( ivadmin_context ctx, char *popid, unsigned long level, ivadmin_response *rsp );

Parameters
Input ctx popid 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object policy. The authentication level to associate with anyothernw.

Description
Sets the anyothernw, or any other network, setting for the authentication level from the specified protected object policy (POP). If controlling access by IP address is not important, use the anyothernw setting to set the authentication level for all IP 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 Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

222

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_pop_setanyothernw_forbidden()
Sets the anyothernw, or any other network, access setting to forbidden for the specified protected object policy.

Syntax
unsigned long ivadmin_pop_setanyothernw_forbidden( ivadmin_context ctx, char *popid, ivadmin_response *rsp );

Parameters
Input ctx popid 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object policy.

Description
Sets the anyothernw, or any other network, access setting to forbidden for the specified protected object policy. Command line equivalent:
pdadmin pop modify pop_name set ipauth anyothernw forbidden

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

223

ivadmin_pop_setauditlevel()
Sets the audit level for the specified protected object policy.

Syntax
unsigned long ivadmin_pop_setauditlevel( ivadmin_context ctx, char *popid, unsigned long audit_level, ivadmin_response *rsp );

Parameters
Input ctx popid audit_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. The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object policy. The new audit level for the protected object policy.

Description
Sets 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 are defined:
#define #define #define #define #define #define IVADMIN_AUDIT_NONE (0) IVADMIN_AUDIT_PERMIT (1) IVADMIN_AUDIT_DENY (2) IVADMIN_AUDIT_ERROR (4) IVADMIN_AUDIT_ADMIN (8) IVADMIN_AUDIT_ALL (15)

Table 35 on page 212 lists audit levels and their descriptions.

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

224

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_pop_setdescription()
Sets the description of the specified protected object policy.

Syntax
unsigned long ivadmin_pop_setdescription( ivadmin_context ctx, char *popid, char *desc, ivadmin_response *rsp );

Parameters
Input ctx popid desc 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object policy. The new description for the protected object policy.

Description
Sets the description of the specified protected object policy. Command line equivalent:
pdadmin pop modify pop_name set description description

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

225

ivadmin_pop_setipauth()
Sets the IP endpoint authentication setting in the specified protected object policy.

Syntax
unsigned long ivadmin_pop_setipauth( ivadmin_context ctx, char *popid, unsigned long network, unsigned long netmask, unsigned long authMethod, ivadmin_response *rsp );

Parameters
Input ctx popid network netmask authMethod 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object policy. The network address. The netmask address. The authentication level to associate with the network.

Description
Sets 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 Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

226

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_pop_setipauth_forbidden()
Sets the IP endpoint authentication setting to forbidden in the specified protected object policy.

Syntax
unsigned long ivadmin_pop_setipauth_forbidden( ivadmin_context ctx, char *popid, unsigned long network, unsigned long netmask, ivadmin_response *rsp );

Parameters
Input ctx popid network netmask 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object policy. The network address. The netmask address.

Description
Sets the ipauth setting for the authentication level to forbidden in the specified protected object policy. Command line equivalent:
pdadmin pop modify pop_name set ipauth add network netmask forbidden

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

227

ivadmin_pop_setqop()
Sets the quality of protection level for the specified protected object policy.

Syntax
unsigned long ivadmin_pop_setqop( ivadmin_context ctx, char *popid, char *qop_level, ivadmin_response *rsp );

Parameters
Input ctx popid qop_level The context used to communicate with the Tivoli Access Manager policy server. Name of the protected object policy The new quality of protection level to set. The following string values are supported: v none v integrity v 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.

Description
Sets the quality of protection level for the specified protected object policy. The following string values are supported: v none v integrity v privacy Command line equivalent:
pdadmin pop modify pop_name set qop [none|integrity|privacy]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

228

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_pop_settod()
Sets the time of day range for the specified protected object policy.

Syntax
unsigned long ivadmin_pop_settod( ivadmin_context ctx, char *popid, unsigned long days, unsigned long start, unsigned long end, unsigned long reference, ivadmin_response *rsp );

Parameters
Input ctx popid days start end reference 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object policy. A bitmap of the days. The minutes for the start of the range. The minutes for the end of the range. The time zone: Universal Time Coordinated (UTC) or local.

Description
Sets 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 #define #define #define #define #define #define #define #define #define #define #define #define #define #define IVADMIN_TIME_LOCAL (0) IVADMIN_TIME_UTC (1) IVADMIN_TOD_ANY (0) IVADMIN_TOD_SUN (1) IVADMIN_TOD_MON (2) IVADMIN_TOD_TUE (4) IVADMIN_TOD_WED (8) IVADMIN_TOD_THU (16) IVADMIN_TOD_FRI (32) IVADMIN_TOD_SAT (64) IVADMIN_TOD_ALL (127) IVADMIN_TOD_WEEKDAY (62) IVADMIN_TOD_WEEKEND (65) IVADMIN_TOD_MINUTES (60) IVADMIN_TOD_OCLOCK (3600)

Chapter 12. Administration C API reference

229

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

230

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_pop_setwarnmode()
Sets the warning mode for the specified protected object policy.

Syntax
unsigned long ivadmin_pop_setwarnmode( ivadmin_context ctx, char *popid, unsigned long warn_mode, ivadmin_response *rsp );

Parameters
Input ctx popid warn_mode The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object policy. The 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.

Description
Sets the warning mode for the specified protected object policy. Command line equivalent:
pdadmin pop modify pop_name set warning [on | off].

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

231

ivadmin_protobj_access()
Returns whether the specified access of the specified protected object is permitted by the user authenticated by the specified security context.

Syntax
unsigned long ivadmin_protobj_access( ivadmin_context ctx, const char *objid, const char *permission_str, azn_attrlist_h_t *app_context, ivadmin_accessOutdata *outdata, ivadmin_response *rsp );

Parameters
Input ctx objid permission_str Specifies the context to use when communicating with the Tivoli Access Manager policy server. Specifies the identifier of the object. Specifies the permission string describing the access requested. For more information, see Using access control policies in IBM Tivoli Access Manager Base Administration Guide. Specifies the application context. See the description of the azn_decision_access_allowed_ext() function in the IBM Tivoli Access Manager for e-business Authorization C API Developer Reference for information on application contexts.

app_context

Output outdata Specifies a pointer to an ivadmin_accessOutdata object. This object is populated with output data for the specified object access request. See Enabling the return of permission information in the IBM Tivoli Access Manager for e-business Authorization C API Developer Reference for information on the data contained within this object. Free this structure when it is no longer needed. Specifies the response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

rsp

Description
Returns whether the user identified by the specified security context is permitted the specified access on the specified object. To check multiple accesses or multiple objects with a single function, use the ivadmin_protobj_multiaccess() function. Information is returned in an ivadmin_accessOutdata structure. The following information is returned: access result Either AZN_C_PERMITTED or AZN_C_NOT_PERMITTED. Use the ivadmin_accessOutdata_getAccessResult() function to extract this data.

response information An ivadmin_response object indicating the success or failure of the

232

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

operation. Use the ivadmin_accessOutdata_getResponseInfo() function to extract the response object. permission information An azn_attrlist_h_t structure containing supplemental permission information. Use the ivadmin_accessOutdata_getPermInfo() function to extract the permission information. See the IBM Tivoli Access Manager for e-business Authorization C API Developer Reference for more information on permissions and the azn_attrlist_h_t structure. Command line equivalent:
pdadmin object access object_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

233

ivadmin_protobj_attachacl()
Attaches the specified access control list (ACL) to the specified protected object.

Syntax
unsigned long ivadmin_protobj_attachacl( ivadmin_context ctx, const char *objid, const char *aclid, ivadmin_response *rsp);

Parameters
Input ctx objid aclid 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object. The name of the access control list.

Description
Attaches the specified access control list to the specified protected object. If the specified protected object already has an ACL attached, this function replaces that ACL with the new one. Understand Tivoli Access Manager ACLs before using this function. For more information about ACLs, see the chapter about using access control policies in the IBM Tivoli Access Manager Base Administration Guide. Command line equivalent:
pdadmin acl attach object_name ACL_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

234

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_protobj_attachauthzrule()
Attaches the specified authorization rule to the specified protected object.

Syntax
unsigned long ivadmin_protobj_attachauthzrule( ivadmin_context ctx, const char *objid, const char *authzruleid, ivadmin_response *rsp );

Parameters
Input ctx objid authzruleid Output rsp The response object. Indicates the success or failure of the function and might contain informational, warning or error information. Free this object when it is no longer needed. Specifies the context to use when communicating with the Tivoli Access Manager policy server. Name of the protected object. Name of the authorization rule.

Description
Attaches the specified authorization rule to the specified protected object. If the specified protected object already has an authorization rule attached, this function replaces that authorization rule with the new one. Command line equivalent:
pdadmin authzrule attach object_name rule_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

235

ivadmin_protobj_attrdelkey()
Deletes the specified extended attribute (name and value) from the specified protected object.

Syntax
unsigned long ivadmin_protobj_attrdelkey( ivadmin_context ctx, const char *objid, const char *attr_name, ivadmin_response *rsp );

Parameters
Input ctx objid attr_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. The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object. The name of the extended attribute to delete.

Description
Deletes the specified extended attribute (name and value) from the specified protected object. Command line equivalent:
pdadmin object modify object_name delete attribute_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

236

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_protobj_attrdelval()
Deletes the specified value from the specified extended attribute key in the specified protected object.

Syntax
unsigned long ivadmin_protobj_attrdelval( ivadmin_context ctx, char *popid, char *attr_key, char *attr_value, ivadmin_response *rsp );

Parameters
Input ctx popid attr_key attr_value The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object. The name of the extended attribute. The 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.

Description
Deletes the specified value from the specified extended attribute key in the specified protected object. Command line equivalent:
pdadmin object modify object_name delete attribute_name attribute_value

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

237

ivadmin_protobj_attrget()
Returns the value associated with the specified extended attribute for the specified protected object.

Syntax
unsigned long ivadmin_protobj_attrget( ivadmin_protobj protobj, const char *attr_key, unsigned long *count, char ***attr_value );

Parameters
Input protobj attr_key count attr_value Tivoli Access Manager protected object structure. The extended attribute to access. The number of values returned. Zero is returned if an error occurs. An array of pointers to the extended attribute values returned. You must free the character data referenced by each pointer, as well as the array of pointers 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.

Description
Returns the value associated with the specified extended attribute for the specified protected object. Command line equivalent:
pdadmin object show object_name attribute attribute_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

238

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_protobj_attrlist()
Lists all the extended attributes associated with the specified protected object.

Syntax
unsigned long ivadmin_protobj_attrlist( ivadmin_protobj protobj, unsigned long *count, char ***attrs_list );

Parameters
Input protobj Output count attrs_list The number of extended attributes returned. Zero is returned if an error occurs. An array of pointers to the extended attributes returned. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed. Tivoli Access Manager protected object structure.

rsp

Description
Lists all the extended attributes associated with the specified protected object. Command line equivalent:
pdadmin object list object_name attribute

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

239

ivadmin_protobj_attrput()
Creates an extended attribute, with the specified name and value, and adds it to the specified protected object.

Syntax
unsigned long ivadmin_protobj_attrput( ivadmin_context ctx, const char *objid, const char *attr_name, const char *attr_value, ivadmin_response *rsp );

Parameters
Input ctx objid attr_name attr_value 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object. The name of the extended attribute. The value for the extended attribute.

Description
Creates an extended attribute, with the specified name and value, and adds it to the specified protected object. Command line equivalent:
pdadmin object modify object_name set attribute attribute_name attribute_value

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

240

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_protobj_create()
Creates an Tivoli Access Manager protected object.

Syntax
unsigned long ivadmin_protobj_create( ivadmin_context ctx, const char *objid, unsigned long type, const char *description, ivadmin_response *rsp );

Parameters
Input ctx objid The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object to create. The name can be of any length and contain any character. Forward slash (/) characters are interpreted as part of the object hierarchy, which allows ACLs to be attached at the various points indicated by the forward slash character. The type of protected object to create. The description of the protected object.

type 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.

Description
You must specify, as a parameter to ivadmin_protobj_create(), an object space type for each new object space. The object space type is used by the Tivoli Access Manager Web Portal Manager to display an appropriate icon with the object. Table 33 on page 195 lists the supported object types. Command line equivalent:
pdadmin object create object_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

241

ivadmin_protobj_delete()
Deletes the specified Tivoli Access Manager protected object.

Syntax
unsigned long ivadmin_protobj_delete( ivadmin_context ctx, const char *objid, ivadmin_response *rsp );

Parameters
Input ctx objid 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object to delete.

Description
Deletes the specified Tivoli Access Manager protected object. Command line equivalent:
pdadmin object delete object_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

242

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_protobj_detachacl()
Detaches the access control list (ACL) from the specified protected object.

Syntax
unsigned long ivadmin_protobj_detachacl( ivadmin_context ctx, const char *objid, ivadmin_response *rsp );

Parameters
Input ctx objid 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object.

Description
Detaches the access control list from the specified protected object. Because only one access control list at a time can be attached to an object, the currently attached access control list is detached. Understand Tivoli Access Manager ACLs before using this function. For more information about ACLs, see the chapter about using access control policies in the IBM Tivoli Access Manager Base Administration Guide. Command line equivalent:
pdadmin acl detach object_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

243

ivadmin_protobj_detachauthzrule()
Detaches the authorization rule from the specified protected object.

Syntax
unsigned long ivadmin_protobj_detachauthzrule( ivadmin_context ctx, const char *objid, ivadmin_response *rsp );

Parameters
Input ctx objid Output rsp The response object. Indicates the success or failure of the function and might contain informational, warning or error information. Free this object when it is no longer needed. Specifies the context to use when communicating with the Tivoli Access Manager policy server. Name of the protected object.

Description
Detaches the authorization rule from the specified protected object. Because only one authorization rule at a time can be attached to an object, the currently attached authorization rule is detached. Command line equivalent:
pdadmin authzrule detach object_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error. Returns IVADMIN_FALSE if no authorization was attached to the protected object.

244

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_protobj_exists()
Returns an indication whether the specified protected object exists.

Syntax
unsigned long ivadmin_protobj_exists( ivadmin_context ctx, const char *objid, unsigned long *exists, ivadmin_response *rsp );

Parameters
Input ctx objid Output exists Indicates whether or not the object exists. IVADMIN_TRUE The protected object exists. IVADMIN_FALSE The protected object does not exist rsp The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed. The context used to communicate with the Tivoli Access Manager policy server. The parent directory within the protected object space.

Description
Indicates whether the protected object exists in the policy database or as an object maintained by an administration service. Command line equivalent:
pdadmin object exists object_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

245

ivadmin_protobj_get3()
Returns the specified protected object.

Syntax
unsigned long ivadmin_protobj_get3( 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 );

Parameters
Input ctx objid indata Specifies the context to use when communicating with the Tivoli Access Manager policy server. Specifies the object name. Specifies pass-through data that allows additional information to be communicated to the server. If a NULL is specified, it is ignored. For non-null inputs, a valid address for an azn_attrlist_h_t structure is expected. It is also assumed that the caller created this azn_attrlist_h_t structure using the azn_attrlist_create () function. When this data is no longer required, free the associated memory using the azn_attrlist_delete() function.

Output obj outdata Specifies the returned object. Specifies pass-through data that allows the server to communicate additional information to the caller. When the data is no longer required, free the associated memory using azn_attrlist_delete(). The number of result strings returned. Zero is returned if an error occurs. An array of pointers to the result strings returned. The result strings are the message strings returned by the task. These are typically output to a command line interface (CLI) or log output and contain information about the success or failure of the task. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. Specifies the response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

resultcount results

rsp

Description
Command line equivalent:
pdadmin object show object_name

246

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

247

ivadmin_protobj_getaclid()
Returns the identifier of the access control list (ACL), if any, that is attached to the specified protected object.

Syntax
ivadmin_acl ivadmin_protobj_getaclid( ivadmin_protobj protobj);

Parameters
Input protobj Pointer to protected object.

Description
Returns the identifier of the access control list that is attached to the specified protected object. Do not free this string. This data is maintained as part of the ivadmin_protobj object. Command line equivalent:
pdadmin object show object_name

The identifier of the attached ACL is part of the information returned by this pdadmin object show command.

Return Values
Returns the identifier of the access control list that is attached to the specified protected object. If no access control list is attached to the protected object, the empty string is returned.

248

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_protobj_getauthzruleid()
Gets the identifier of the authorization rule, if any, that is attached to the specified protected object.

Syntax
ivadmin_authzrule ivadmin_protobj_getauthzruleid( ivadmin_protobj protobj );

Parameters
Input protobj Pointer to protected object.

Description
Gets the identifier of the authorization rule that is attached to the specified protected object. Do not free this string. This data is maintained as part of the ivadmin_protobj object. Command line equivalent:
pdadmin object show object_name

The identifier of the attached authorization rule is part of the information returned by this pdadmin object show command.

Return Values
Returns the identifier of the authorization rule that is attached to the specified protected object. The empty string is returned if no authorization rule is attached to the object.

Chapter 12. Administration C API reference

249

ivadmin_protobj_getdesc()
Gets the description of the specified protected object.

Syntax
const char * ivadmin_protobj_getdesc( ivadmin_protobj protobj );

Parameters
Input protobj Pointer to the protected object.

Description
Gets the description of the specified protected object. You must call ivadmin_protobj_get3() before calling this function. Do not free this string. This data is maintained in the ivadmin_protobj object. Command line equivalent:
pdadmin object show object_name

The description is part of the information returned by this pdadmin command.

Return Values
Gets the description of the specified protected object. There is no limit to the length of the description.

250

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_protobj_geteffaclid()
Returns the identifier of the access control list (ACL) that is in effect for the specified protected object. The effective ACL might be attached to the protected object, or it might be inherited from an object higher in the protected object space.

Syntax
ivadmin_acl ivadmin_protobj_geteffaclid( ivadmin_protobj protobj);

Parameters
Input protobj Pointer to protected object structure.

Description
Returns the identifier of the access control list that is attached to the specified protected object. Do not free the returned string. This data is maintained in the ivadmin_protobj object. Command line equivalent:
pdadmin object show object_name

The identifier of the effective ACL is part of the information returned by this pdadmin object show command.

Return Values
Returns the identifier of the access control list that is in effect for the specified protected object.

Chapter 12. Administration C API reference

251

ivadmin_protobj_geteffauthzruleid()
Gets the identifier of the authorization rule that is in effect for the specified protected object. The effective authorization rule might be attached to the protected object, or be inherited from an object higher in the protected object space.

Syntax
ivadmin_authzrule ivadmin_protobj_geteffauthzruleid( ivadmin_protobj protobj );

Parameters
Input protobj Pointer to the protected object.

Description
Gets the identifier of the authorization rule that is in effect for the specified protected object. Do not free the returned string. This data is maintained in the ivadmin_protobj object. Command line equivalent:
pdadmin object show object_name

The identifier of the authorization rule in effect is part of the information returned by this pdadmin object show command.

Return Values
Returns the identifier of the authorization rule that is in effect for the specified protected object, or the empty string if no authorization rule is in effect for the object.

252

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_protobj_geteffpopid()
Returns the identifier of the protected object policy (POP) that is in effect for the specified protected object. The effective POP might be attached to the protected object, or be inherited from an object higher in the protected object space.

Syntax
ivadmin_pop ivadmin_protobj_geteffpopid( ivadmin_protobj protobj );

Parameters
Input protobj Pointer to the protected object.

Description
Returns the identifier of the protected object policy in effect for the specified protected object. Do not free the returned string. This data is maintained in the ivadmin_protobj object. Command line equivalent:
pdadmin object show object_name

The identifier of the protected object policy in effect is part of the information returned by this pdadmin object show command.

Return Values
Returns the identifier of the protected object policy in effect for the specified protected object.

Chapter 12. Administration C API reference

253

ivadmin_protobj_getid()
Gets the name of the specified protected object.

Syntax
const char * ivadmin_protobj_getid( ivadmin_protobj protobj );

Parameters
Input protobj Pointer to the protected object structure.

Description
Gets the name of the specified protected object. You must call ivadmin_protobj_get2() before calling this function. Do not free this string. This data is maintained in the protected object structure ivadmin_protobj. Command line equivalent:
pdadmin object show object_name

The protected object name is part of the information returned by this pdadmin command.

Return Values
Gets the name of the specified protected object. There is no limit to the length of the name.

254

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_protobj_getpolicyattachable()
Gets the isPolicyAttachable attribute of the specified protected object.

Syntax
unsigned long ivadmin_protobj_getpolicyattachable( ivadmin_protobj protobj );

Parameters
Input protobj The protected object structure.

Description
Gets the isPolicyAttachable attribute of the specified protected object. The isPolicyAttachable attribute of a protected object indicates whether a protected object policy (POP) can be attached to that protected object. The default value of this attribute is yes. Command line equivalent:
pdadmin object show object_name

The protected object isPolicyAttachable attribute is part of the information returned by this pdadmin command.

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. Indicates that isPolicyAttachable is true. IVADMIN_FALSE Defined as 0. Indicates that isPolicyAttachable is false.

Chapter 12. Administration C API reference

255

ivadmin_protobj_getpopid()
Returns the identifier of the protected object policy (POP), if any, for the specified protected object.

Syntax
ivadmin_pop ivadmin_protobj_getpopid( ivadmin_protobj protobj );

Parameters
Input protobj Pointer to the protected object.

Description
Gets the identifier of the protected object policy that is attached to the specified protected object. Do not free this string. This data is maintained as part of the ivadmin_protobj object. Command line equivalent:
pdadmin object show object_name

The identifier of the attached protected object policy is part of the information returned by this pdadmin object show command.

Return Values
Returns the identifier of the protected object policy that is attached to the specified protected object.

256

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_protobj_gettype()
Returns the type of the specified protected object.

Syntax
unsigned long ivadmin_protobj_gettype( ivadmin_protobj protobj );

Parameters
Input protobj Pointer to protected object structure.

Description
Returns 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 pdadmin command.

Return Values
Returns the type of the specified protected object. Table 33 on page 195 in the description of the ivadmin_objectspace_create() function enumerates the types, values, and their descriptions.

Chapter 12. Administration C API reference

257

ivadmin_protobj_list3()
Returns the protected objects in the specified directory, not including subdirectories.

Syntax
unsigned long ivadmin_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 );

Parameters
Input ctx objid indata Specifies the context to use when communicating with the Tivoli Access Manager policy server. Specifies the parent object name. Specifies pass-through data that allows additional information to be communicated to the server. If a NULL is specified, it is ignored. For non-null inputs, a valid address for an azn_attrlist_h_t structure is expected. It is also assumed that the caller created this azn_attrlist_h_t structure using the azn_attrlist_create() function. When this data is no longer required, free the associated memory using the azn_attrlist_delete() function.

Output objcount objs The number of object names returned. Zero is returned if an error occurs. An array of pointers to the list of object names that exist directly below the specified parent object. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. Specifies pass-through data that allows the server to communicate additional information to the caller. When the data is no longer required, free the associated memory using the azn_attrlist_delete() function. The number of result strings returned. Zero is returned if an error occurs. An array of pointers to the result strings returned. The result strings are the message strings returned by the task. These are typically output on a command line interface (CLI) or log output and contain information about the success or failure of the task. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed.

outdata

resultcount results

258

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

rsp

Specifies the response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

Description
Returns the protected objects in the specified directory, not including subdirectories. If an error occurs, NULL is returned. Command line equivalent:
pdadmin object list object_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

259

ivadmin_protobj_listbyacl()
Returns a list of protected objects that have the specified access control list attached.

Syntax
unsigned long ivadmin_protobj_listbyacl( ivadmin_context ctx, const char *aclid, unsigned long *count, char ***objids, ivadmin_response *rsp );

Parameters
Input ctx aclid count objids The context used to communicate with the Tivoli Access Manager policy server. The name of the access control list. The number of protected objects returned. Zero is returned if an error occurs. An array of pointers to the protected objects returned. You must free the character data referenced by each pointer, as well as the array of pointers 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.

Description
Returns a list of protected objects which have the specified access control list attached. Command line equivalent:
pdadmin acl find ACL_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

260

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_protobj_listbyauthzrule()
Returns a list of protected objects that have the specified authorization rule attached.

Syntax
unsigned long ivadmin_protobj_listbyauthzrule( ivadmin_context ctx, const char *authzruleid, unsigned long *count, char ***objids, ivadmin_response *rsp );

Parameters
Input ctx authzruleid Output count objids Number of protected objects returned. If an error is encountered, zero is returned. An array of pointers to protected objects returned. You must free the protected objects referenced by each pointer, as well as the array of pointers when they are no longer needed. The response object. Indicates the success or failure of the function and might contain informational, warning or error information. Free this object when it is no longer needed. Specifies the context to use when communicating with the Tivoli Access Manager policy server. Name of the authorization rule.

rsp

Description
Returns a list of protected objects that have the specified authorization rule attached. Free each protected object name pointer and the array of pointers when no longer needed. Command line equivalent:
pdadmin authzrule find rule_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

261

ivadmin_protobj_multiaccess()
Determines whether the user authenticated in the specified security context has the specified accesses to the specified objects.

Syntax
unsigned long ivadmin_protobj_access( ivadmin_context ctx, const char *objids[], const char *permission_strs[], azn_attrlist_h_t *app_contexts[], ivadmin_accessOutdata *outdata[], int count ivadmin_response *rsp );

Parameters
Input ctx objids Specifies the context to use when communicating with the Tivoli Access Manager policy server. Specifies the identifiers of the objects.

permission_strs Specifies the permission strings describing the accesses requested. For more information, see Using access control policies in IBM Tivoli Access Manager Base Administration Guide. app_contexts Specifies the application contexts. See the description of the azn_decision_access_allowed_ext() function in the IBM Tivoli Access Manager for e-business Authorization C API Developer Reference for information on application contexts. Specifies the number of objects to which access is being requested.

count Output outdata

Specifies an array of pointers to ivadmin_accessOutdata objects. These objects are populated with output data for each object access request. See Enabling the return of permission information in the IBM Tivoli Access Manager for e-business Authorization C API Developer Reference for information on the data contained within these objects. Free each element and the array of pointers when they are no longer needed. Specifies the response object. Indicates the success or failure of the function. The response object for the entire operation might indicate success even though one or more individual requests might have failed. Contains zero or more error, informational, or warning messages. Free this object when it is no longer needed.

rsp

Description
Given a group of objects and a group of requested accesses, returns whether the user specified in the input context is permitted the specified accesses on each object. Use the ivadmin_protobj_access() function to manipulate a single object.

262

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

An array of ivadmin_accessOutdata objects is returned, each of which contains information for one access request. The following information is returned in each object: access result Either AZN_C_PERMITTED or AZN_C_NOT_PERMITTED. Use the ivadmin_accessOutdata_getAccessResult() function to extract this data.

response information An ivadmin_response object indicating the success or failure of the operation. Use the ivadmin_accessOutdata_getResponseInfo() function to extract the response object. permission information An azn_attrlist_h_t structure containing supplemental permission information. Use the ivadmin_accessOutdata_getPermInfo() function to extract the permission information. See the IBM Tivoli Access Manager for e-business Authorization C API Developer Reference for more information on permissions and the azn_attrlist_h_t structure. Command line equivalent:
pdadmin object access object_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

263

ivadmin_protobj_setdesc()
Sets the description field of the specified protected object.

Syntax
unsigned long ivadmin_protobj_setdesc( ivadmin_context ctx, const char *objid, const char *description, ivadmin_response *rsp );

Parameters
Input ctx objid 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object for which a new description is to be set. The new description for the protected object.

Syntax
Sets the description field of the specified protected object. Command line equivalent:
pdadmin object modify object_name description new_description

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

264

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_protobj_setpolicyattachable()
Sets the isPolicyAttachable attribute of the specified protected object.

Syntax
unsigned long ivadmin_protobj_setpolicyattachable( ivadmin_context ctx, const char *objid, unsigned long flag, ivadmin_response *rsp );

Parameters
Input ctx objid flag The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object. The flag containing the value of the isPolicyAttachable attribute. The possible 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.

Description
Sets the isPolicyAttachable attribute of the specified protected object. The isPolicyAttachable attribute of a protected object indicates whether a protected object policy (POP) can be attached to that protected object. The default value of this attribute is yes. Command line equivalent:
pdadmin object modify object_name isPolicyAttachable [yes | no]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

265

ivadmin_protobj_settype()
Sets the type field of the specified protected object.

Syntax
unsigned long ivadmin_protobj_settype( ivadmin_context ctx, const char *objid, unsigned long type, ivadmin_response *rsp );

Syntax
Input ctx objid type 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the protected object. The new type for the object.

Description
Sets the type field of the specified protected object. Command line equivalent:
pdadmin object modify object_name type new_type

Table 33 on page 195 lists the supported object types.

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

266

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_response_getcode()
Returns the message code.

Syntax
unsigned long ivadmin_response_getcode( ivadmin_response rsp, unsigned long index );

Parameters
Input rsp The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed. Zero-based index of the message code requested.

index

Description
Returns the error or warning code associated with the message.

Return Values
Returns the error or warning code associated with the message.

Chapter 12. Administration C API reference

267

ivadmin_response_getcount()
Returns the number of messages in the response object.

Syntax
unsigned long ivadmin_response_getcount( ivadmin_response rsp );

Parameters
Input rsp The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

Description
Returns the number of messages in the response object.

Return Values
Returns the number of messages in the response object.

268

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_response_getmessage()
Returns the message text from the specified index location in the response object.

Syntax
const char * ivadmin_response_getmessage( ivadmin_response rsp, unsigned long index );

Parameters
Input rsp The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed. Zero-based index of message text requested.

index

Description
Returns 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 Values
Returns the message text from the specified index location in the response object.

Chapter 12. Administration C API reference

269

ivadmin_response_getmodifier()
Returns the message modifier from the specified index location in the response object.

Syntax
unsigned long ivadmin_response_getmodifier( ivadmin_response rsp, unsigned long index );

Parameters
Input rsp The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed. Zero-based index of the message modifier requested.

index

Description
Returns the message modifier from the specified index location in the response object. The modifier can be either an error, a warning, or information. The following values are defined:
#define IVADMIN_RESPONSE_INFO #define IVADMIN_RESPONSE_WARNING #define IVADMIN_RESPONSE_ERROR 0 1 2

Return Values
Returns the message modifier from the specified index location in the response object.

270

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_response_getok()
Returns a Boolean indicator of the success of the operation.

Syntax
unsigned long ivadmin_response_getok( ivadmin_response rsp );

Parameters
Input rsp The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

Description
Returns a Boolean indicator of the success of the operation.

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

271

ivadmin_server_gettasklist()
Gets the list of tasks from the server.

Syntax
unsigned long ivadmin_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 );

Parameters
Input ctx server Specifies the context to use when communicating with the Tivoli Access Manager policy server. Specifies the name of the server to notify of a database update. This parameter is optional. If NULL is specified, all servers configured to receive database update notifications are notified. Specifies pass-through data that allows additional information to be communicated to the server. If NULL is specified, it is ignored. For non-null inputs, a valid address for an azn_attrlist_h_t structure is expected. It is also assumed that the caller created this azn_attrlist_h_t structure using the azn_attrlist_create() function. When this data is no longer required, free the associated memory using the azn_attrlist_delete() function.

indata

Output taskcount tasks The number of task strings returned. Zero is returned if an error occurs. 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. Specifies pass-through data that allows the server to communicate additional information to the caller. When the data is no longer required, free the associated memory by using the azn_attrlist_delete() function. The number of result strings returned. Zero is returned if an error occurs. An array of pointers to the result strings returned. The result strings are the message strings returned by the task. These are typically output on a command line interface (CLI) or log output and contain information about the success or failure of the task. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed.

outdata

resultcount results

272

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

rsp

Specifies the response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

Description
Gets 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 Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

273

ivadmin_server_performtask()
Sends a command to an authorization server.

Syntax
unsigned long ivadmin_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 );

Parameters
Input ctx server Specifies the context to use when communicating with the Tivoli Access Manager policy server. Specifies the name of server to notify of database update. This parameter is optional. If NULL is specified, all servers configured to receive database update notifications will be notified. Specifies the task to perform. Specifies pass-through data that allows additional information to be communicated to the server. If NULL is specified, it is ignored. For non-null inputs, a valid address for an azn_attrlist_h_t structure is expected. It is also assumed that the caller created this azn_attrlist_h_t structure using the azn_attrlist_create() function. When this data is no longer required, free the associated memory by using the azn_attrlist_delete() function.

task indata

Output outdata Pass-through data that allows the server to communicate additional information to the caller. When the data is no longer required, free the associated memory by using the azn_attrlist_delete() function. The number of result strings returned. Zero is returned if an error occurs. An array of pointers to the result strings returned. The result strings are the message strings returned by the task. These are typically output on a command line interface (CLI) or log output and contain information about the success or failure of the task. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. Specifies the response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

resultcount results

rsp

274

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Description
Sends a command to the authorization server. Command line equivalent:
pdadmin server task server_name task_to_perform

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

275

ivadmin_server_replicate()
Notify authorization servers to receive database updates.

Syntax
unsigned long ivadmin_server_replicate( ivadmin_context ctx, const char *server, ivadmin_response *rsp );

Parameters
Input ctx server Specifies the context to use when communicating with the Tivoli Access Manager policy server. Specifies the name of the server to notify of a database update. This parameter is optional. If NULL is specified, all servers configured to receive database update notifications are notified.

Output rsp Specifies the response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

Description
Notify authorization servers to receive database updates. If a server name is specified, but is not configured to receive database updates, an error message is displayed. If no server name is specified, the process of notifying all configured servers is initiated, but error messages are not displayed for individual servers. The caller must have the authority to perform server administration tasks on the policy server. (The azn_operation_server_admin permission is required on the policy server object.) Command line equivalent:
pdadmin server replicate [server-name]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. If a server is specified, this indicates the successful notification and database replication by that server. If no server is specified, this indicates that the policy server has begun to notify each authorization server. In this case, a return code of IVADMIN_TRUE is not an indication of successful notification or replication for any one of the servers. IVADMIN_FALSE Defined as 0. If a server is specified, this indicates the a failure of the notification and database replication by that server. If no server is specified, this indicates that a failure has occurred in requesting that the policy server begin notifying each authorization server.

276

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_ssocred_create()
Creates a single signon credential.

Syntax
unsigned long ivadmin_ssocred_create( ivadmin_context ctx, const char *ssoid, unsigned long ssotype, const char *userid, const char *ssouserid, const char *ssopassword, ivadmin_response *rsp );

Parameters
Input ctx ssoid ssotype The context used to communicate with the Tivoli Access Manager policy server. Single signon resource name with which the single signon credential is associated. This resource must already exist. Single signon resource type. The following types are defined: v IVADMIN_SSOCRED_SSOWEB v IVADMIN_SSOCRED_SSOGROUP User ID associated with the single signon credential. The user name that this user uses to access the specified resource. The password that this user uses to access the specified resource.

userid ssouserid ssopassword 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.

Description
Creates 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 Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

277

ivadmin_ssocred_delete()
Deletes a single signon credential.

Syntax
unsigned long ivadmin_ssocred_delete( ivadmin_context ctx, const char *ssoid, unsigned long ssotype, const char *userid, ivadmin_response *rsp );

Parameters
Input ctx ssoid ssotype The context used to communicate with the Tivoli Access Manager policy server. Single signon resource name with which the single signon credential is associated. Single signon resource type. The following types are defined: v IVADMIN_SSOCRED_SSOWEB v IVADMIN_SSOCRED_SSOGROUP The user ID associated with the single signon credential.

userid 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.

Description
Deletes a single signon credential. Command line equivalent:
pdadmin rsrccred delete resource_name rsrctype {web | group} user user_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

278

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_ssocred_get()
Returns the specified single signon credential.

Syntax
unsigned long ivadmin_ssocred_get( ivadmin_context ctx, const char *ssoid, unsigned long ssotype, const char *userid, ivadmin_ssocred *ssocred, ivadmin_response *rsp );

Parameters
Input ctx ssoid ssotype The context used to communicate with the Tivoli Access Manager policy server. Single signon resource name with which the single signon credential is associated. Single signon resource type. The following types are defined: v IVADMIN_SSOCRED_SSOWEB v IVADMIN_SSOCRED_SSOGROUP The user name associated with the single signon credential.

userid Output ssocred rsp

Returned single signon credential. Free this credential when it is no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

Description
Returns the specified single signon credential. Specify the single signon credential type when using this function. The following single signon credential types are defined:
#define IVADMIN_SSOCRED_SSOWEB #define IVADMIN_SSOCRED_SSOGROUP 0 1

Command line equivalent:


pdadmin rsrccred show resource_name rsrctype {web | group} user user_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.
Chapter 12. Administration C API reference

279

ivadmin_ssocred_getid()
Returns the name of the single signon resource associated with this credential.

Syntax
const char * ivadmin_ssocred_getid( ivadmin_ssocred ssocred );

Parameters
Input ssocred Pointer to the single signon credential.

Description
Returns the name of the single signon resource associated with this credential. You must call ivadmin_ssocred_get() to obtain an ivadmin_ssocred object before calling this function. Do not free this string. This data is maintained in the single signon credential structure (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 pdadmin command.

Return Values
Returns the name of the single signon resource associated with this credential. User registry difference: The maxmum length of the name is dependent on the user registry being used. See Appendix B, User registry differences, on page 349 to determine the maximum length for your environment.

280

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_ssocred_getssopassword()
Returns the password associated with this single signon credential.

Syntax
const char * ivadmin_ssocred_getssopassword( ivadmin_ssocred ssocred );

Parameters
Input ssocred Pointer to the single signon credential.

Description
Returns the password associated with this single signon credential. You must call ivadmin_ssocred_get() to obtain an ivadmin_ssocred object before calling this function. Do not free this string. This data is maintained in the single signon credential structure (ivadmin_ssocred).

Return Values
Returns the password associated with this single signon credential. There is no limit to the length of the password.

Chapter 12. Administration C API reference

281

ivadmin_ssocred_getssouser()
Returns the name of the user associated with the specified single signon credential.

Syntax
const char * ivadmin_ssocred_getssouser( ivadmin_ssocred ssocred );

Parameters
Input ssocred Pointer to the single signon credential.

Description
Returns the name of the user associated with the specified single signon credential. You must call ivadmin_ssocred_get() to obtain an ivadmin_ssocred object before calling this function. Do not free this string. This data is maintained in the single signon credential structure (ivadmin_ssocred).

Return Values
Returns the name of the user associated with the specified single signon credential. User registry difference: The maxmum length of the name is dependent on the user registry being used. See Appendix B, User registry differences, on page 349 to determine the maximum length for your environment.

282

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_ssocred_gettype()
Returns the type of the single signon resource associated with the specified single signon credential.

Syntax
unsigned long ivadmin_ssocred_gettype( ivadmin_ssocred ssocred );

Parameters
Input ssocred Pointer to the single signon credential.

Description
Returns the type of the single signon resource associated with the specified single signon 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 Values
Returns the type of the single signon resource associated with the specified single signon credential. You must call ivadmin_ssocred_get () to obtain an ivadmin_ssocred object before calling this function. The defined types are:
#define IVADMIN_SSOCRED_SSOWEB #define IVADMIN_SSOCRED_SSOGROUP 0 1

Do not free the resource credential type (integer) when it is no longer needed. This data is maintained in the ivadmin_ssocred object.

Chapter 12. Administration C API reference

283

ivadmin_ssocred_getuser()
Returns the name of the user associated with this single signon credential.

Syntax
const char * ivadmin_ssocred_getuser( ivadmin_ssocred ssocred );

Parameters
Input ssocred Pointer to the single signon credential.

Description
Returns the name of the user associated with this single signon credential. You must call ivadmin_ssocred_get() to obtain an ivadmin_ssocred object before calling this function. Do not free this string. This data is maintained in the single signon credential structure (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 Values
Returns the name of the user associated with this single signon credential. User registry difference: The maxmum length of the name is dependent on the user registry being used. See Appendix B, User registry differences, on page 349 to determine the maximum length for your environment.

284

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_ssocred_list()
Returns the list of single signon credentials for the specified user.

Syntax
unsigned long ivadmin_ssocred_list( ivadmin_context ctx, const char *userid, unsigned long *count, ivadmin_ssocred **ssocreds, ivadmin_response *rsp );

Parameters
Input ctx userid The context used to communicate with the Tivoli Access Manager policy server. The user ID of the user for whom the single signon credentials are to be retrieved.

Output count ssocreds Number of single signon credentials returned. Zero is returned if an error occurs. Array of pointers to single signon credentials. You must free the data referenced by each pointer, as well as the array of pointers when they are no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

rsp

Description
Returns the list of single signon credentials for the specified user. Command line equivalent:
pdadmin rsrccred list user user_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

285

ivadmin_ssocred_set()
Creates or modifies a single signon credential.

Syntax
unsigned long ivadmin_ssocred_set( ivadmin_context ctx, const char *ssoid, unsigned long ssotype, const char *userid, const char *ssouserid, const char *ssopassword, ivadmin_response *rsp );

Parameters
Input ctx ssoid ssotype The context used to communicate with the Tivoli Access Manager policy server. Single signon resource name with which the single signon credential is associated. Single signon resource type. The following types are defined: v IVADMIN_SSOCRED_SSOWEB v IVADMIN_SSOCRED_SSOGROUP User name associated with the single signon credential. The user name that the user (as specified by the input parameter userid) uses to access the specified resource. The password that this user uses to access the specified resource.

userid ssouserid ssopassword 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.

Description
Creates 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 Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

286

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_ssogroup_addres()
Adds a single signon resource to a single signon resource group.

Syntax
unsigned long ivadmin_ssogroup_addres( ivadmin_context ctx, const char *ssogroupid, const char *ssoid, ivadmin_response *rsp );

Parameters
Input ctx ssogroupid ssoid 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. The context used to communicate with the Tivoli Access Manager policy server. Single signon resource group name. New member single signon resource name.

Description
Adds a single signon resource to a single signon resource group. Tivoli Access Manager 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 Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

287

ivadmin_ssogroup_create()
Creates a single signon group resource.

Syntax
unsigned long ivadmin_ssogroup_create( ivadmin_context ctx, const char *ssogroupid, const char *description, ivadmin_response *rsp );

Parameters
Input ctx ssogroupid 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. The context used to communicate with the Tivoli Access Manager policy server. Single signon group resource name. Description of the single signon group resource.

Description
Creates a single signon group resource. Command line equivalent:
pdadmin rsrcgroup create resource_group_name [-desc description]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

288

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_ssogroup_delete()
Deletes a single signon group resource.

Syntax
unsigned long ivadmin_ssogroup_delete( ivadmin_context ctx, const char *ssogroupid, ivadmin_response *rsp );

Parameters
Input ctx ssogroupid 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. The context used to communicate with the Tivoli Access Manager policy server. Single signon group resource name.

Description
Deletes a single signon group resource. Command line equivalent:
pdadmin rsrcgroup delete resource_group_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

289

ivadmin_ssogroup_get()
Returns the specified single signon group resource.

Syntax
unsigned long ivadmin_ssogroup_get( ivadmin_context ctx, const char *ssogroupid, ivadmin_ssogroup *ssogroup, ivadmin_response *rsp );

Parameters
Input ctx ssogroupid Output ssogroup Returned single signon group resource. Free the memory containing the returned single signon group resource when it is no longer needed The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed. The context used to communicate with the Tivoli Access Manager policy server. Single signon group resource name.

rsp

Description
Returns the specified single signon group resource. The ivadmin_ssogroup object contains the resource group name, the resource group description, and a list of the names of the resource group members. The resource group members are the individual Web resources (servers). Command line equivalent:
pdadmin rsrcgroup show resource_group_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

290

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_ssogroup_getdescription()
Returns the description of the single signon group resource.

Syntax
const char * ivadmin_ssogroup_getdescription( ivadmin_ssogroup ssogroup );

Parameters
Input ssogroup Pointer to the single signon group resource.

Description
Returns the description of the single signon group resource. You must call ivadmin_ssogroup_get() to obtain an ivadmin_ssogroup object before calling this function. Do not free this string. This data is maintained in the single signon group resource structure. Command line equivalent:
pdadmin rsrcgroup show resource_group_name

The description is part of the information returned by the pdadmin command.

Return Values
Returns the description of the single signon group resource. The maximum length of the description is 1024 characters.

Chapter 12. Administration C API reference

291

ivadmin_ssogroup_getid()
Returns the name of the single signon group resource.

Syntax
const char * ivadmin_ssogroup_getid( ivadmin_ssogroup ssogroup );

Parameters
Input ssogroup Pointer to the single signon group resource.

Description
Returns the name of the single signon group resource. You must call ivadmin_ssogroup_get() to obtain an ivadmin_ssogroup object before calling this function. Do not free this string. This data is maintained in the single signon group resource structure. Command line equivalent:
pdadmin rsrcgroup show resource_group_name

The name is part of the information returned by the pdadmin command.

Return Values
Returns the name of the single signon group resource. User registry difference: The maxmum length of the name is dependent on the user registry being used. See Appendix B, User registry differences, on page 349 to determine the maximum length for your environment.

292

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_ssogroup_getresources()
Returns a list of the member single signon resource names for the specified single signon group.

Syntax
unsigned long ivadmin_ssogroup_getresources( ivadmin_ssogroup ssogroup, unsigned long *count, char *** ssoids );

Parameters
Input ssogroup Output count ssoids The number of single signon resource names returned. Zero is returned if an error occurs. An array of pointers to the single signon resource names returned. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. Pointer to the single signon group resource.

Description
Returns 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 Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

293

ivadmin_ssogroup_list
Returns a list of all the single signon group resource names.

Syntax
unsigned long ivadmin_ssogroup_list( ivadmin_context ctx, unsigned long *count, char ***ssogroupids, ivadmin_response *rsp );

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server.

Output count ssogroupids The number of single signon group resource names returned. Zero is returned if an error occurs. An array of pointers to the single signon group resource names returned. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

rsp

Description
Returns a list of all of the single signon group resource names. Command line equivalent:
pdadmin rsrcgroup list

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

294

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_ssogroup_removeres()
Removes a single signon resource from the specified single signon resource group.

Syntax
unsigned long ivadmin_ssogroup_removeres( ivadmin_context ctx, const char *ssogroupid, const char *ssoid, ivadmin_response *rsp );

Parameters
Input ctx ssogroupid ssoid 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. The context used to communicate with the Tivoli Access Manager policy server. single signon resource group name. The member single signon resource name to remove.

Description
Removes 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 Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

295

ivadmin_ssoweb_create()
Creates a single signon Web resource.

Syntax
unsigned long ivadmin_ssoweb_create( ivadmin_context ctx, const char *ssowebid, const char *description, ivadmin_response *rsp );

Parameters
Input ctx ssowebid 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. The context used to communicate with the Tivoli Access Manager policy server. The single signon Web resource name. The description of the single signon Web resource.

Description
Creates a single signon Web resource. The name of the Web server does not need to match the junction. You can use this function call before joining the Web server to the Tivoli Access Manager WebSEAL server. Command line equivalent:
pdadmin rsrc create resource_name [-desc description]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

296

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_ssoweb_delete()
Deletes the specified single signon Web resource.

Syntax
unsigned long ivadmin_ssoweb_delete( ivadmin_context ctx, const char *ssowebid, ivadmin_response *rsp );

Parameters
Input ctx ssowebid 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. The context used to communicate with the Tivoli Access Manager policy server. The name of the single signon Web resource to delete.

Description
Deletes the specified single signon Web resource. Command line equivalent:
pdadmin rsrc delete resource_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

297

ivadmin_ssoweb_get()
Returns the specified single signon Web resource.

Syntax
unsigned long ivadmin_ssoweb_get( ivadmin_context ctx, const char *ssowebid, ivadmin_ssoweb *ssoweb, ivadmin_response *rsp );

Parameters
Input ctx ssowebid Output ssoweb The returned single signon Web resource. Free the memory for the single signon Web resource (ivadmin_ssoweb) when it is no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed. The context used to communicate with the Tivoli Access Manager policy server. The name of the single signon Web resource to get.

rsp

Description
Returns the specified single signon Web resource. Command line equivalent:
pdadmin rsrc show resource_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

298

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_ssoweb_getdescription()
Returns the description of the specified single signon Web resource.

Syntax
const char * ivadmin_ssoweb_getdescription( ivadmin_ssoweb ssoweb );

Parameters
Input ssoweb Pointer to single signon Web resource.

Description
Returns the description of the specified single signon Web resource. You must call ivadmin_ssoweb_get() to obtain an ivadmin_ssoweb object before calling this function. Do not free this string. This data is maintained in the single signon Web resource structure (ivadmin_ssoweb). Command line equivalent:
pdadmin rsrc show resource_name

The description is part of the information returned by the pdadmin command.

Return Values
Returns the description of the specified single signon Web resource. The maximum length of the description is 1024 characters.

Chapter 12. Administration C API reference

299

ivadmin_ssoweb_getid()
Returns the name (identifier) of the specified single signon Web resource.

Syntax
const char * ivadmin_ssoweb_getid( ivadmin_ssoweb ssoweb );

Parameters
Input ssoweb Pointer to single signon Web resource.

Description
Returns the name (identifier) of the specified single signon Web resource. You must call ivadmin_ssoweb_get() to obtain an ivadmin_ssoweb object before calling this function. Do not free this string. This data is maintained in the single signon Web resource structure (ivadmin_ssoweb). Command line equivalent:
pdadmin rsrc show resource_name

The name is part of the information returned by the pdadmin command.

Return Values
Returns the name, or identifier, of the specified single signon Web resource. User registry difference: The maxmum length of the name is dependent on the user registry being used. See Appendix B, User registry differences, on page 349 to determine the maximum length for your environment.

300

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_ssoweb_list()
Returns a list of all the single signon Web resource names.

Syntax
unsigned long ivadmin_ssoweb_list( ivadmin_context ctx, unsigned long *count, char ***ssowebids, ivadmin_response *rsp );

Parameters
Input ctx The context used to communicate with the Tivoli Access Manager policy server.

Output count ssowebids The number of single signon Web resource names returned. Zero is returned if an error occurs. An array of pointers to the single signon Web resource names returned. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

rsp

Description
Returns a list of all the single signon Web resource names. Command line equivalent:
pdadmin rsrc list

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

301

ivadmin_user_create3()
Creates a user in the directory used by the Tivoli Access Manager policy server and initially associates that user with one or more groups.

Syntax
unsigned long ivadmin_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 );

Parameters
Input ctx userid dn cn sn pwd group_count groups ssouser The context used to communicate with the Tivoli Access Manager policy server. Tivoli Access Manager user name. User registry distinguished name. User registry attribute common name. User registry attribute surname. User registry attribute password. The number of groups to which the user initially belongs. The initial user registry groups to which the user belongs. Specify NULL to indicate no initial group membership. The user is capable of having single signon credentials. Supported values are IVADMIN_TRUE and IVADMIN_FALSE. nopwdpolicy Password policy is not enforced during creation. This has no effect on password 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.

Description
Creates a user in the user registry used by the Tivoli Access Manager policy server. Accounts are created invalid by default. Use ivadmin_user_setaccountvalid() to enable the account.

302

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

User registry difference: Leading and trailing blanks in a user name do not make the name unique when using an LDAP or Active Directory user registry. However, leading and trailing blanks do make the user name unique when using a Domino server as a user registry. To keep name processing consistent regardless of what user registry is being used, do not define user names with leading or trailing 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 Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

303

ivadmin_user_delete2()
Deletes the Tivoli Access Manager user and optionally deletes the user from the user registry.

Syntax
unsigned long ivadmin_user_delete2( ivadmin_context ctx const char *userid, unsigned long registry ivadmin_response *rsp );

Parameters
Input ctx userid registry The context used to communicate with the Tivoli Access Manager policy server. Tivoli Access Manager user name. Delete 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.

Description
Deletes Tivoli Access Manager information about the user from the user registry. The optional pdadmin parameter -registry causes the entire user object to be deleted from the user registry. Command line equivalent:
pdadmin user delete [-registry] user_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

304

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_get()
Gets the user object for the specified user.

Syntax
unsigned long ivadmin_user_get( ivadmin_context ctx, const char *userid, ivadmin_ldapuser *user, ivadmin_response *rsp );

Parameters
Input ctx userid Output user rsp Returned user. Free this memory when no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed. The context used to communicate with the Tivoli Access Manager policy server. Tivoli Access Manager user name.

Description
Gets the user object for the specified user. Free the memory used by the ivadmin_ldapuser object when it is no longer needed. Command line equivalent:
pdadmin user show user_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

305

ivadmin_user_getaccexpdate()
Gets the account expiration date for the specified user.

Syntax
unsigned long ivadmin_user_getaccexpdate( ivadmin_context ctx, const char *userid, unsigned long *seconds, unsigned long *unlimited, unsigned long *unset, ivadmin_response *rsp );

Parameters
Input ctx userid seconds The context used to communicate with the Tivoli Access Manager policy server. User name. Returned 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). Returns 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 is set 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.

unlimited

Description
Gets the account expiration date for the specified user. Command line equivalent:
pdadmin policy get account-expiry-date [-user user_name]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

306

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_getaccountvalid()
Returns the account-valid indicator from the specified user object.

Syntax
unsigned long ivadmin_user_getaccountvalid( ivadmin_ldapuser user );

Parameters
Input user Pointer to the user structure.

Description
Returns 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 pdadmin command.

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

307

ivadmin_user_getbydn()
Obtains an Tivoli Access Manager user object by using the user registry distinguished name.

Syntax
unsigned long ivadmin_user_getbydn( ivadmin_context ctx, const char *dn, ivadmin_ldapuser *user, ivadmin_response *rsp );

Parameters
Input ctx dn Output user rsp Returned user. Free the memory for this object when it is no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed. The context used to communicate with the Tivoli Access Manager policy server. User registry distinguished name of the user.

Description
Obtains an Tivoli Access Manager user object by using the user registry distinguished name. User registry difference: The maxmum length of the distinguished name is dependent on the user registry being used. See Appendix B, User registry differences, on page 349 to determine the maximum length for your environment. Command line equivalent:
pdadmin user show-dn dn

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

308

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_getcn()
Returns the user registry common name attribute from the specified user object.

Syntax
const char * ivadmin_user_getcn( ivadmin_ldapuser user );

Parameters
Input user Pointer to the user structure.

Description
Returns 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 the ivadmin_ldapuser object. Command line equivalent:
pdadmin user show user_name

The user registry common name for the user is part of the information returned by the pdadmin command.

Return Values
Returns the user registry common name attribute from the specified user object. User registry difference: The maxmum length of the common name is dependent on the user registry being used. See Appendix B, User registry differences, on page 349 to determine the maximum length for your environment.

Chapter 12. Administration C API reference

309

ivadmin_user_getdescription()
Returns the user description from the specified user object.

Syntax
const char * ivadmin_user_getdescription( ivadmin_ldapuser user );

Parameters
Input user Pointer to the user structure.

Description
Returns the user description from the specified user object. Do not free the character string that is returned. This data is maintained in the ivadmin_ldapuser object. Command line equivalent:
pdadmin user show user_name

The user description is part of the information returned by the pdadmin command.

Return Values
Returns the user description from the specified user object. The maximum length of the description is 1024 characters.

310

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_getdisabletimeint()
Gets the amount of time to disable the specified user account if the maximum number of login failures is exceeded.

Syntax
unsigned long ivadmin_user_getdisabletimeint( ivadmin_context ctx, const char *userid, unsigned long *seconds, unsigned long *disable, unsigned long *unset, ivadmin_response *rsp );

Parameters
Input ctx userid Output seconds disable Disable the user account for the specified number of seconds if the maximum number of login failures is exceeded. Disable the user account if the maximum number of login failures is exceeded. 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 is set 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. The context used to communicate with the Tivoli Access Manager policy server. User name.

Description
Gets the amount of time to disable each user account if the maximum number of login failures is exceeded. Command line equivalent:
pdadmin policy get disable-time-interval [-user user_name]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

311

ivadmin_user_getdn()
Returns the user registry distinguished name from the specified user object.

Syntax
const char * ivadmin_user_getdn( ivadmin_ldapuser user );

Parameters
Input user Pointer to the user structure.

Description
Returns the user registry distinguished name from the specified user object. Do not free the character string that is returned. This data is maintained in the ivadmin_ldapuser object. Command line equivalent:
pdadmin user show user_name

The user registry distinguished name for the user is part of the information returned by the pdadmin command.

Return Values
Returns the user registry distinguished name from the specified user object. User registry difference: The maxmum length of the distinguished name is dependent on the user registry being used. See Appendix B, User registry differences, on page 349 to determine the maximum length for your environment.

312

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_getid()
Returns the user name from the specified user object.

Syntax
const char * ivadmin_user_getid( ivadmin_ldapuser user );

Parameters
Input user Pointer to the user structure.

Description
Returns the user name from the specified user object. Do not free the character string that is returned. This data is maintained in the ivadmin_ldapuser object. Command line equivalent:
pdadmin user show user_name

The user name (login identifier) is part of the information returned by the pdadmin command.

Return Values
Returns the user name from the specified user object. The maximum length of the name is 256 characters.

Chapter 12. Administration C API reference

313

ivadmin_user_getmaxlgnfails()
Gets the maximum number of login failures allowed for the specified user account.

Syntax
unsigned long ivadmin_user_getmaxlgnfails( ivadmin_context ctx, const char *userid, unsigned long *failures, unsigned long *unset, ivadmin_response *rsp );

Parameters
Input ctx userid Output failures unset Maximum number of login failures allowed. Policy ignored and not enforced if set to true. If set to false, the policy is set 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. The context used to communicate with the Tivoli Access Manager policy server. User name.

Description
Gets 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 Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

314

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_getmaxpwdage()
Gets the maximum password age for the specified user account.

Syntax
unsigned long ivadmin_user_getmaxpwdage( ivadmin_context ctx, const char *userid, unsigned long *seconds, unsigned long *unset, ivadmin_response *rsp );

Parameters
Input ctx userid Output seconds unset Returned maximum lifetime, in seconds, before expiration of the password. Policy ignored and not enforced if set to true. If set to false, the policy is set 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. The context used to communicate with the Tivoli Access Manager policy server. User name.

Description
Gets the maximum password age for the specified user account. Command line equivalent:
pdadmin policy get max-password-age [-user user_name]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

315

ivadmin_user_getmaxpwdrepchars()
Gets the maximum number of repeated characters allowed in a password for the specified user account.

Syntax
unsigned long ivadmin_user_getmaxpwdrepchars( ivadmin_context ctx, const char *userid, unsigned long *chars, unsigned long *unset, ivadmin_response *rsp );

Parameters
Input ctx userid Output chars unset Maximum number of repeated characters allowed. Policy ignored and not enforced if set to true. If set to false, the policy is set 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. The context used to communicate with the Tivoli Access Manager policy server. User name.

Description
Gets the maximum number of repeated characters allowed in a password for the specified user account. Command line equivalent:
pdadmin policy get max-password-repeated-chars [-user user_name]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

316

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_getmemberships()
Gets the groups in which the specified user is a member.

Syntax
unsigned long ivadmin_user_getmemberships( ivadmin_context ctx, const char *userid, unsigned long *count, char ***groupids, ivadmin_response *rsp );

Parameters
Input ctx userid Output count groupids The number of group names returned. Zero is returned if an error occurs. An array of pointers to the group names returned. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed. The context used to communicate with the Tivoli Access Manager policy server. Tivoli Access Manager user name.

rsp

Description
Gets the groups in which the specified user is a member. Command line equivalent:
pdadmin user show-groups user_name

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

317

ivadmin_user_getminpwdalphas()
Gets the minimum number of alphabetic characters allowed in a password for the specified user account.

Syntax
unsigned long ivadmin_user_getminpwdalphas( ivadmin_context ctx, const char *userid, unsigned long *chars, unsigned long *unset, ivadmin_response *rsp );

Parameters
Input ctx userid Output chars unset Minimum number of alphabetic characters allowed. Policy ignored and not enforced if set to true. If set to false, the policy is set 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. The context used to communicate with the Tivoli Access Manager policy server. User name.

Description
Gets the minimum number of alphabetic characters allowed in a password for the specified user account. Command line equivalent:
pdadmin policy get min-password-alphas [-user user_name]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

318

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_getminpwdlen()
Gets the minimum password length for the specified user account.

Syntax
unsigned long ivadmin_user_getminpwdlen( ivadmin_context ctx, const char *userid, unsigned long *length, unsigned long *unset, ivadmin_response *rsp );

Parameters
Input ctx userid Output length unset Returned minimum allowed password length. Policy ignored and not enforced if set to true. If set to false, the policy is set 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. The context used to communicate with the Tivoli Access Manager policy server. User name.

Description
Gets the minimum password length for the specified user account. Command line equivalent:
pdadmin policy get min-password-length [-user user_name]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

319

ivadmin_user_getminpwdnonalphas()
Gets the minimum number of nonalphabetic characters allowed in a password for the specified user account.

Syntax
unsigned long ivadmin_user_getminpwdnonalphas( ivadmin_context ctx, const char *userid, unsigned long *chars, unsigned long *unset, ivadmin_response *rsp );

Parameters
Input ctx userid Output chars unset Minimum number of nonalphabetic characters allowed. Policy ignored and not enforced if set to true. If set to false, the policy is set 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. The context used to communicate with the Tivoli Access Manager policy server. User name.

Description
Gets the minimum number of nonalphabetic characters allowed in a password for the specified user account. Command line equivalent:
pdadmin policy get min-password-non-alphas [-user user_name]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

320

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_getpasswordvalid()
Returns the password valid indicator.

Syntax
unsigned long ivadmin_user_getpasswordvalid( ivadmin_ldapuser user );

Parameters
Input user Pointer to the user structure.

Description
Returns the password valid indicator. Supported values are IVADMIN_TRUE and IVADMIN_FALSE. Command line equivalent:
pdadmin user show user_name

The password valid status is part of the information returned by the pdadmin command.

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. Indicates that the password is valid. IVADMIN_FALSE Defined as 0. Indicates that the password has expired.

Chapter 12. Administration C API reference

321

ivadmin_user_getpwdspaces()
Gets whether spaces are allowed in passwords for the specified user account.

Syntax
unsigned long ivadmin_user_getpwdspaces( ivadmin_context ctx, const char *userid, unsigned long *allowed, unsigned long *unset, ivadmin_response *rsp );

Parameters
Input ctx userid Output allowed Indicates 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 is set 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. The context used to communicate with the Tivoli Access Manager policy server. User name.

Description
Gets whether spaces are allowed in passwords for the specified user account. Command line equivalent:
pdadmin policy get password-spaces [-user user_name]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

322

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_getsn()
Returns the user registry surname attribute for the specified user.

Syntax
const char * ivadmin_user_getsn( ivadmin_ldapuser user );

Parameters
Input user Pointer to the user structure.

Description
Returns the user registry surname attribute for the specified user. Do not free the character string that is returned. This data is maintained in the ivadmin_ldapuser structure. Command line equivalent:
pdadmin user show user_name

The user registry surname for the user is part of the information returned by the pdadmin command.

Return Values
Returns the user registry surname attribute for the specified user. User registry difference: The maxmum length of the surname attribute is dependent on the user registry being used. See Appendix B, User registry differences, on page 349 to determine the maximum length for your environment.

Chapter 12. Administration C API reference

323

ivadmin_user_getssouser()
Returns a setting that indicates if the user account has single signon capabilities.

Syntax
unsigned long ivadmin_user_getssouser( ivadmin_ldapuser user );

Parameters
Input user Pointer to the user structure.

Description
Returns 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 the pdadmin command.

Return Values
The following values are returned: IVADMIN_TRUE Defined as 1. Indicates that the user account is single signon capable. IVADMIN_FALSE Defined as 0. Indicates that the user account is not single signon capable.

324

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_gettodaccess()
Gets the time of day access policy for the specified user.

Syntax
unsigned long ivadmin_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 );

Parameters
Input ctx userid Output days start end reference unset A bitmap of the days for the time of day access policy. The minutes after midnight for the start of the time range. The minutes after midnight for the end of the time range. The time zone: Universal Time Coordinated (UTC) or local. Policy ignored and not enforced if set to true. If set to false, the policy is set 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. The context used to communicate with the Tivoli Access Manager policy server User registry user name.

Description
Gets the time of day access policy for the specified user. Command line equivalent:
pdadmin policy get todaccess -user userID

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

325

ivadmin_user_import2()
Creates an Tivoli Access Manager user by importing an existing user in the user registry.

Syntax
unsigned long ivadmin_user_import2( ivadmin_context ctx, const char *userid, const char *dn, const char *groupid, unsigned long ssouser, ivadmin_response *rsp );

Parameters
Input ctx userid dn groupid ssouser The context used to communicate with the Tivoli Access Manager policy server. User name. User registry distinguished name. The initial user registry group to which the user belongs. This value can be NULL to indicate no initial group membership. 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.

Description
Creates an Tivoli Access Manager user by importing an existing user in the user registry. Accounts are created invalid by default. You must use ivadmin_user_setaccountvalid() to enable the account. Command line equivalent:
pdadmin user import [-gsouser] user_name dn

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

326

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_list()
Lists the names of the Tivoli Access Manager users that match the specified pattern.

Syntax
unsigned long ivadmin_user_list( ivadmin_context ctx, const char *pattern, unsigned long maxreturn, unsigned long *count, char ***userids, ivadmin_response *rsp );

Parameters
Input ctx pattern maxreturn The context used to communicate with the Tivoli Access Manager policy server. Pattern match for user names. IVADMIN_ALLPATTERN indicates all users. Maximum number to return. IVADMIN_MAXRETURN indicates unlimited. This number can be limited by the user registry server so that the maximum returned is really the minimum of the server configuration and this value.

Output count userids The number of user names returned. Zero is returned if an error occurs. An array of pointers to the user names returned. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

rsp

Description
Lists the names of the Tivoli Access Manager users in the user registry that match the specified pattern. Returns an array of pointers to character strings containing the user IDs. The following constants are defined:
#define IVADMIN_MAXRETURN 0 #define IVADMIN_ALLPATTERN "*"

Command line equivalent:


pdadmin user list pattern max_return

Return Values
Returns the following Boolean values:
Chapter 12. Administration C API reference

327

IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

328

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_listbydn()
Returns the list of user registry distinguished names whose user registry common name attribute matches the pattern specified.

Syntax
unsigned long ivadmin_user_listbydn( ivadmin_context ctx, const char *pattern, unsigned long maxreturn, unsigned long *count, char ***dns, ivadmin_response *rsp );

Parameters
Input ctx pattern maxreturn The context used to communicate with the Tivoli Access Manager policy server. Pattern match for user registry common name attribute. IVADMIN_ALLPATTERN indicates all users. Maximum number to return. IVADMIN_MAXRETURN indicates unlimited. This number can be limited by the user registry server so that the maximum returned is really the minimum of the server configuration and this value.

Output count dns The number of user registry distinguished names returned. Zero is returned if an error occurs. An array of pointers to the user registry distinguished names returned. You must free the character data referenced by each pointer, as well as the array of pointers when they are no longer needed. The response object. Indicates the success or failure of the function. Contains error information. Free this object when it is no longer needed.

rsp

Description
Returns the list of user registry distinguished names whose user registry common name attribute matches the pattern specified. Returns an array of pointers to character strings containing each users distinguished name. Command line equivalent:
pdadmin user list-dn pattern max_return

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful.

Chapter 12. Administration C API reference

329

IVADMIN_FALSE Defined as 0. The function encountered an error.

330

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_setaccexpdate()
Sets the account expiration date for specified user.

Syntax
unsigned long ivadmin_user_setaccexpdate( ivadmin_context ctx, const char *userid, unsigned long seconds, unsigned long unlimited, unsigned long unset, ivadmin_response *rsp );

Parameters
Input ctx userid seconds The context used to communicate with the Tivoli Access Manager policy server. User name. Date and time of the expiration of specified user account. This is the number of seconds since 00:00:00 Universal time, 1 January 1970 (same as time_t). Do not expire specified user account and ignore the 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 is set 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.

unlimited

Description
Sets the account expiration date for specified user. Command line equivalent:
pdadmin policy set account-expiry-date {unlimited | absolute_time | unset} \ [-user user_name]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

331

ivadmin_user_setaccountvalid()
Enables or disables the specified Tivoli Access Manager user account.

Syntax
unsigned long ivadmin_user_setaccountvalid( ivadmin_context ctx, const char *userid, unsigned long valid, ivadmin_response *rsp );

Parameters
Input ctx userid valid The context used to communicate with the Tivoli Access Manager policy server. User name. 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.

Description
Enables or disables the specified Tivoli Access Manager user account. Use this function 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 Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

332

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_setdescription()
Modifies the user description.

Syntax
unsigned long ivadmin_user_setdescription( ivadmin_context ctx, const char *userid, const char *description, ivadmin_response *rsp );

Parameters
Input ctx userid 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. The context used to communicate with the Tivoli Access Manager policy server. User name. New description.

Description
Modifies the user description. The description is an arbitrary text string. For example:
Diana Lucas, Credit Dept HCUS

Command line equivalent:


pdadmin user modify user_name description description

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

333

ivadmin_user_setdisabletimeint()
Sets the time to disable the specified user account when the maximum number of login failures is exceeded.

Syntax
unsigned long ivadmin_user_setdisabletimeint( ivadmin_context ctx, const char *userid, unsigned long seconds, unsigned long disable, unsigned long unset, ivadmin_response *rsp );

Parameters
Input ctx userid seconds disable The context used to communicate with the Tivoli Access Manager policy server. User name. Disable the user account for the specified number of seconds when the maximum number of login failures is exceeded. Disable the user account when the maximum number of login failures is exceeded. 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 is set 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.

Description
Sets the time to disable the specified user account when the maximum number of login failures is exceeded. Command line equivalent:
pdadmin policy set disable-time-interval {number | unset | disable} \ [-user user_name]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

334

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_setmaxlgnfails()
Sets the maximum number of login failures allowed for the specified user account.

Syntax
unsigned long ivadmin_user_setmaxlgnfails( ivadmin_context ctx, const char *userid, unsigned long failures, unsigned long unset, ivadmin_response *rsp );

Parameters
Input ctx userid failures unset The context used to communicate with the Tivoli Access Manager policy server. User name. Maximum number of login failures allowed. Policy ignored and not enforced if set to true. If set to false, the policy is set 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.

Description
Set 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 Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

335

ivadmin_user_setmaxpwdage()
Sets the maximum password age for the specified user account.

Syntax
unsigned long ivadmin_user_setmaxpwdage( ivadmin_context ctx, const char *userid, unsigned long seconds, unsigned long unset, ivadmin_response *rsp );

Parameters
Input ctx userid seconds unset The context used to communicate with the Tivoli Access Manager policy server. User name. Maximum lifetime, in seconds, before expiration of password. Policy ignored and not enforced if set to true. If set to false, the policy is set 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.

Description
Sets 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 Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

336

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_setmaxpwdrepchars()
Sets the maximum number of repeated characters allowed in a password for the specified user account.

Syntax
unsigned long ivadmin_user_setmaxpwdrepchars( ivadmin_context ctx, const char *userid, unsigned long chars, unsigned long unset, ivadmin_response *rsp );

Parameters
Input ctx userid chars unset The context used to communicate with the Tivoli Access Manager policy server. User name. Maximum number of repeated characters allowed. Policy ignored and not enforced if set to true. If set to false, the policy is set 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.

Description
Sets the maximum number of repeated characters allowed in a password for the specified user account. Command line equivalent:
pdadmin policy set max-password-repeated-chars number | unset [-user user_name]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

337

ivadmin_user_setminpwdalphas()
Sets the minimum number of alphabetic characters allowed in a password for the specified user account.

Syntax
unsigned long ivadmin_user_setminpwdalphas( ivadmin_context ctx, const char *userid, unsigned long chars, unsigned long unset, ivadmin_response *rsp );

Parameters
Input ctx userid chars unset The context used to communicate with the Tivoli Access Manager policy server. User name. Minimum number of alphabetic characters allowed. Policy ignored and not enforced if set to true. If set to false, the policy is set 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.

Description
Sets the minimum number of alphabetic characters allowed in a password for the specified user account. Command line equivalent:
pdadmin policy set min-password-alphas {unset | number}[-user user_name]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

338

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_setminpwdlen()
Sets the minimum password length for the specified user account.

Syntax
unsigned long ivadmin_user_setminpwdlen( ivadmin_context ctx, const char *userid, unsigned long length, unsigned long unset, ivadmin_response *rsp );

Parameters
Input ctx userid length unset The context used to communicate with the Tivoli Access Manager policy server. User name. Minimum allowed password length to be set. Policy ignored and not enforced if set to true. If set to false, the policy is set 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.

Description
Sets the minimum password length for the specified user account. Command line equivalent:
pdadmin policy set min-password-length {unset | number} [-user user_name]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

339

ivadmin_user_setminpwdnonalphas()
Sets the minimum number of nonalphabetic characters allowed in a password for the specified user account.

Syntax
unsigned long ivadmin_user_setminpwdnonalphas( ivadmin_context ctx, const char *userid, unsigned long chars, unsigned long unset, ivadmin_response *rsp );

Parameters
Input ctx userid chars unset The context used to communicate with the Tivoli Access Manager policy server. User name. Minimum number of nonalphabetic characters allowed. Policy ignored and not enforced if set to true. If set to false, the policy is set 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.

Description
Sets the minimum number of nonalphabetic characters allowed in a password for the specified user account. Command line equivalent:
pdadmin policy set min-password-non-alphas {unset | number} [-user user_name]

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

340

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_setpassword()
Modifies the user password.

Syntax
unsigned long ivadmin_user_setpassword( ivadmin_context ctx, const char *userid, const char *pwd, ivadmin_response *rsp );

Parameters
Input ctx userid pwd 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. The context used to communicate with the Tivoli Access Manager policy server. User name. New password.

Description
Modifies the user password. If the user that is having its password set is the same user that created the security context, ctx, no further authorization checks are performed. Command line equivalent:
pdadmin user modify user_name password password

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

341

ivadmin_user_setpasswordvalid()
Expires the Tivoli Access Manager account password.

Syntax
unsigned long ivadmin_user_setpasswordvalid( ivadmin_context ctx, const char *userid, unsigned long valid, ivadmin_response *rsp );

Parameters
Input ctx userid valid The context used to communicate with the Tivoli Access Manager policy server. User name. 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.

Description
Expires the Tivoli Access Manager account password. This forces the user to change the password at the next login attempt. Command line equivalent:
pdadmin user modify user_name password-valid {yes | no}

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

342

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_setpwdspaces()
Sets whether spaces are allowed in passwords for the specified user account.

Syntax
unsigned long ivadmin_user_setpwdspaces( ivadmin_context ctx, const char *userid, unsigned long allowed, unsigned long unset, ivadmin_response *rsp );

Parameters
Input ctx userid allowed The context used to communicate with the Tivoli Access Manager policy server. User name. Indicates 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 is set 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.

Description
Sets 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 Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

343

ivadmin_user_setssouser()
Enables or disables the single sign on capabilities of an Tivoli Access Manager user.

Syntax
unsigned long ivadmin_user_setssouser( ivadmin_context ctx, const char *userid, unsigned long ssouser, ivadmin_response *rsp );

Parameters
Input ctx userid ssouser The context used to communicate with the Tivoli Access Manager policy server. User name. 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.

Description
Enables 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 Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

344

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_settodaccess()
Sets the time of day access policy for the specified user.

Syntax
unsigned long ivadmin_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 );

Parameters
Input ctx userid days start end reference unset The context used to communicate with the Tivoli Access Manager policy server. User registry user name. A bitmap of the days for the time of day access policy. The minutes after midnight for the start of the time range. The minutes after midnight for the end of the time range. The time zone: Universal Coordinated Time (UTC) or local. Policy ignored and not enforced if set to true. If set to false, the policy is set 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.

Description
Sets the time of day access policy for the specified user. Command line equivalent:
pdadmin policy set todaccess todaccess_string -user userID

Return Values
Returns the following Boolean values: IVADMIN_TRUE Defined as 1. The function was successful. IVADMIN_FALSE Defined as 0. The function encountered an error.

Chapter 12. Administration C API reference

345

346

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Appendix A. Deprecated APIs


The APIs listed in Table 36 have been deprecated in IBM Tivoli Access Manager (Tivoli Access Manager) Version 5.1. The ivadmin_deprecated.h header file contains the prototypes and definitions for these deprecated APIs. Avoid including this header file because the symbols it declares are not supported. Instead, change existing applications to use any replacement APIs listed in the table.
Table 36. APIs deprecated in Tivoli Access Manager Version 5.1 Deprecated API ivadmin_cfg_addreplica ivadmin_cfg_chgreplica ivadmin_cfg_configureserver2 ivadmin_cfg_rmvreplica ivadmin_cfg_setapplicationcert ivadmin_cfg_setkeyringpwd ivadmin_cfg_setlistening ivadmin_cfg_setport ivadmin_cfg_setssltimeout ivadmin_context_create2 ivadmin_context_createdefault ivadmin_protobj_get2 ivadmin_protobj_getacl ivadmin_protobj_getauthzrule ivadmin_protobj_getpop ivadmin_protobj_setname Replacement API ivadmin_cfg_addreplica2 ivadmin_cfg_chgreplica2 ivadmin_cfg_configureserver3 ivadmin_cfg_rmvreplica2 ivadmin_cfg_setapplicationcert2 ivadmin_cfg_setkeyringpwd2 ivadmin_cfg_setlistening2 ivadmin_cfg_setport2 ivadmin_cfg_setssltimeout2 ivadmin_context_create3 ivadmin_context_createdefault2 ivadmin_protobj_get3 ivadmin_protobj_getaclid ivadmin_acl_get ivadmin_protobj_getauthzruleid ivadmin_authzrule_get ivadmin_protobj_getpopid ivadmin_pop_get None

The APIs listed in Table 37 were deprecated in previous versions of Tivoli Access Manager and Tivoli SecureWay Policy Director.
Table 37. APIs deprecated in previous versions of Tivoli Access Manager and Tivoli SecureWay Policy Director Deprecated API ivadmin_cfg_configureserver ivadmin_context_create ivadmin_group_addmember ivadmin_group_removemember ivadmin_user_create2 ivadmin_user_getauthmech ivadmin_user_setauthmech ivadmin_group_create
Copyright IBM Corp. 2000, 2003

Replacement API ivadmin_cfg_configureserver3 ivadmin_context_create3 ivadmin_group_addmembers ivadmin_group_removemembers ivadmin_user_create3 None None ivadmin_group_create3

347

Table 37. APIs deprecated in previous versions of Tivoli Access Manager and Tivoli SecureWay Policy Director (continued) Deprecated API ivadmin_group_delete ivadmin_group_import ivadmin_protobj_get ivadmin_protobj_list2 ivadmin_user_create ivadmin_user_delete ivadmin_user_import Replacement API ivadmin_group_delete2 ivadmin_group_import2 ivadmin_protobj_get3 ivadmin_protobj_list3 ivadmin_user_create3 ivadmin_user_delete2 ivadmin_user_import2

The following constants have been deprecated in previous versions of Tivoli Access Manager and Tivoli SecureWay Policy Director. v IVADMIN_USER_DCEAUTHMETH v IVADMIN_USER_LDAPAUTHMETH The ivadmin_deprecated.h header file contains the definitions for these deprecated constants. Avoid including this header file because the symbols it declares are not supported.

348

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Appendix B. User registry differences


The following user registry differences are known to exist in this version of IBM Tivoli Access Manager (Tivoli Access Manager.) 1. When Tivoli Access Manager is using either Microsoft Active Directory or a Lotus Domino server as its user registry, only a single domain is supported. Use an LDAP user registry if you wish to take advantage of the multi-domain support in Tivoli Access Manager. 2. Tivoli Access Manager does not support cross domain group membership or universal groups when using Microsoft Active Directory as its user registry. Importing such groups into Tivoli Access Manager is not supported. 3. When the Tivoli Access Manager policy server is using either Microsoft Active Directory or a Lotus Domino server as its user registry, existing Tivoli SecureWay Policy Director, Version 3.8 clients are not able to connect to the policy server. Either use a different user registry or upgrade the clients to Tivoli Access Manager. 4. Users created in a Lotus Domino server or Microsoft Active Directory user registry are automatically given the capability to own single signon credentials and this capability can not be removed. When using an LDAP user registry, this capability must be explicitly granted to a user and subsequently can be removed. 5. 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 Tivoli Access Manager secure domain. However, when using a Lotus Domino server as a user registry, leading and trailing blanks are significant. To ensure that processing is consistent regardless of what user registry is being used, define users and groups in the user registry without leading or trailing blanks in their names. 6. The forward slash character (/) should be avoided in user and group names defined using distinguished name strings. The forward slash character is treated differently in different user registries: Lotus Domino server Users and groups can not be created with names using a distinguished name string containing a forward slash character. To avoid the problem, either do not use a forward slash character or define 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 Directory Users and groups can be created with names using a distinguished name string containing a forward slash character. However, subsequent operations on the object might fail as some Active Directory functions interpret the forward slash character as a separator between the object name and the host name. To avoid the problem, do not use a forward slash character to define the user. 7. When using a multi-domain Microsoft Active Directory user registry, multiple users and groups can be defined with the same short name as long as they
Copyright IBM Corp. 2000, 2003

349

8.

9.

10.

11.

reside in different domains. However, the full name of the user or group, including the domain suffix, must always be specified to Tivoli Access Manager. 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 group membership. If a user with the same name is created at some later time, the new user automatically inherits the old group membership and might be given inappropriate permissions. It is strongly recommended that the user be removed from all groups before the user is deleted. This problem does not occur when using the other supported user registries. Attempting to add a single duplicate user to a group does not produce an error when an LDAP user registry is being used. However, an error is properly reflected when using Lotus Domino server or Microsoft Active Directory. The Tivoli Access Manager authorization API provides a credentials attribute entitlements service. This service is used to retrieve user attributes from a user registry. When this service is used with an LDAP user registry, the retrieved attributes can be either string or binary data. However, when this service is used with a Microsoft Active Directory or Lotus Domino user registry, the retrieved attributes can be either string, binary or integer data. The maximum lengths of various names associated with Tivoli Access Manager vary depending on the user registry being used. See Table 38 for a comparison of the maximum lengths allowed and the recommended maximum length to use to ensure compatibility with all the user registries supported by Tivoli Access Manager.
Maximum length of: LDAP 256 128 128 1024 Microsoft Active Directory 64 64 64 2048 Lotus Domino server 960 65535 960 255 Recommended maximum value 64 64 64 This value is user registry-specific and must be changed when changing user registries. This value is user registry-specific and must be changed when changing user registries. 256 1024 256 1024 1024 1024

Table 38. Maximum lengths for names based on user registry

First name (LDAP CN) Middle name Last name (surname) Registry UID (LDAP DN)

Tivoli Access Manager user identity

256

2048 - 1 length_of_ domain_name

200 - 4 length_of_ domain_name

User password User description Group name Group description

unlimited 1024 256 1024

256 1024

unlimited 1024

350

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Table 38. Maximum lengths for names based on user registry (continued) Maximum length of: Single signon resource name Single signon resource description Single signon user ID Single signon password Single signon group name Single signon group description Action name Action description, action type Object name, object space name, ACL name, POP name Object description, object space description, ACL description, POP description LDAP 240 1024 Microsoft Active Directory 256 1024 Lotus Domino server 256 1024 Recommended maximum value 240 1024

240 unlimited 240 1024

256 256 256 1024

256 unlimited 256 1024

240 256 240 1024

1 unlimited

1 unlimited

1 unlimited

unlimited

unlimited

unlimited

unlimited

unlimited

unlimited

Even though some names can be of unlimited length, excessive lengths can result in policy that is difficult to manage and might result in poor system performance. Choose maximum values that are logical for your environment.

Appendix B. User registry differences

351

352

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Appendix C. Administration API equivalents


This appendix shows the mapping that exists between the administration C API functions, the administration Java classes and methods, the command line interface (CLI), and Web Portal Manager. 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 achieve the same effect as a single C API function. Information about the administration Java classes and methods can be found in the IBM Tivoli Access Manager for e-business Administration Java Classes Developer Reference. Information about the pdadmin command line interface can be found in the IBM Tivoli Access Manager for e-business Command Reference. Information on Web Portal Manager can be found in its online help and in the IBM Tivoli Access Manager Base Administration Guide.

Copyright IBM Corp. 2000, 2003

353

354
Java Class and Method PDAcl.deleteAttribute PDAcl object.deleteAttribute pdadmin acl modify acl_name delete attribute attribute_name pdadmin acl modify acl_name delete attribute attribute_name attribute_value pdadmin acl show acl_name attribute attribute_name pdadmin acl list acl_name attribute pdadmin acl modify acl_name set attribute attribute_name attribute_value pdadmin acl create acl_name pdadmin acl delete acl_name pdadmin acl show acl_name pdadmin acl show any-other pdadmin acl show acl_name pdadmin acl show acl_name pdadmin acl show acl_name pdadmin acl show acl_name PDAcl.deleteAttributeValue PDAcl object.deleteAttributeValue Command Line Equivalent Web Portal Manager Equivalent ACL List ACL select ACL name Extended Attribute tab select attribute Delete ACL List ACL click ACL name Extended Attribute tab select attributes Delete ACL List ACL click ACL name Extended Attribute tab ACL List ACL click ACL name Extended Attribute tab ACL List ACL click ACL name Extended Attribute tab Create ACL Create ACL ACL List ACL select ACL names Delete ACL List ACL click ACL name ACL List ACL click ACL name ACL List ACL click ACL name ACL List ACL click ACL name ACL List ACL click ACL name ACL List ACL click ACL name PDAcl object.getAttributeValues PDAcl object.getAttributeNames PDAcl.setAttributeValue PDAcl object.setAttributeValue PDAcl.createAcl PDAcl.deleteAcl PDAcl constructor PDAcl object.getPDAclEntryAnyOther PDAcl object.getDescription PDAcl object.getPDAclEntriesGroup PDAcl object.getId PDAcl object.getPDAclEntryUnAuth

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager

C API

ivadmin_acl_attrdelkey()

ivadmin_acl_attrdelval()

ivadmin_acl_attrget()

ivadmin_acl_attrlist()

ivadmin_acl_attrput()

ivadmin_acl_create()

ivadmin_acl_delete()

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_acl_get()

ivadmin_acl_getanyother()

ivadmin_acl_getdescription()

ivadmin_acl_getgroup()

ivadmin_acl_getid()

ivadmin_acl_getunauth()

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager (continued) Java Class and Method PDAcl object.getPDAclEntriesUser pdadmin acl show acl_name pdadmin acl list pdadmin acl show acl_name pdadmin acl show acl_name pdadmin acl modify acl_name remove any-other pdadmin acl modify acl_name remove group group_name pdadmin acl modify acl_name remove unauthenticated pdadmin acl modify acl_name remove user user_name pdadmin acl modify acl_name set any-other perms pdadmin acl modify acl_name description description pdadmin acl modify acl_name set group group_name perms ACL List ACL ACL List ACL click ACL name ACL List ACL click ACL name ACL List ACL click ACL name select Any-other ACL Entry Delete ACL List ACL click ACL name select Group ACL Entry Delete ACL List ACL click ACL name select Unauthenticated ACL Entry Delete ACL List ACL click ACL name select User ACL Entry Delete ACL List ACL click ACL name click Any-other Permissions select permissions Apply ACL List ACL click ACL name modify Description Set ACL List ACL click ACL name Create choose Entry Type Group specify name of group select permissions Apply PDAcl.listAcls PDAcl object.getPDAclEntriesGroup PDAcl object.getPDAclEntriesUser PDAcl.removePDAclEntryAnyOther PDAcl object.removePDAclEntryAnyOther PDAcl.removePDAclEntryGroup PDAcl object.removePDAclEntryGroup PDAcl.removePDAclEntryUnAuth PDAcl object.removePDAclEntryUnAuth Command Line Equivalent Web Portal Manager Equivalent ACL List ACL click ACL name

C API

ivadmin_acl_getuser()

ivadmin_acl_list()

ivadmin_acl_listgroups()

ivadmin_acl_listusers()

ivadmin_acl_removeanyother()

ivadmin_acl_removegroup()

ivadmin_acl_removeunauth()

ivadmin_acl_removeuser()

PDAcl.removePDAclEntryUser PDAcl object.removePDAclEntryUser PDAcl.setPDAclEntryAnyOther PDAcl object.setPDAclEntryAnyOther

ivadmin_acl_setanyother()

ivadmin_acl_setdescription()

PDAcl.setDescription PDAcl object.setDescription PDAcl.setPDAclEntryGroup PDAcl object.setPDAclEntryGroup

Appendix C. Administration API equivalents

ivadmin_acl_setgroup()

355

356
Java Class and Method PDAcl.setPDAclEntryUnAuth PDAcl object.setPDAclEntryUnAuth pdadmin acl modify acl_name set unauthenticated perms pdadmin acl modify acl_name set user user_name perms Command Line Equivalent Web Portal Manager Equivalent ACL List ACL click ACL name Create choose Entry Type Unauthenticated select permissions Apply ACL List ACL click ACL name Create choose Entry Type User specify name of User select permissions Apply ACL List Action Groups click primary Action Group Create fill in form Create ACL List Action Groups click Action Group Create fill in form Create ACL List Action Groups select primary action group select actions Delete pdadmin action delete name pdadmin action delete name action_group_name pdadmin action list pdadmin action list pdadmin action list pdadmin action group create action_group_name pdadmin action group delete action_group_name pdadmin action group list ACL List Action Groups click Action Group select actions Delete ACL List Action Groups click primary action group ACL List Action Groups click primary action group ACL List Action Groups click primary action group ACL Create Action Group ACL List Action Groups select action groups Delete ACL List Action Groups PDAcl.setPDAclEntryUser PDAcl object.setPDAclEntryUser PDAction.createAction pdadmin action create name description action_type pdadmin action create name description action_type action_group_name PDAction.createAction PDAction.deleteAction PDAction.deleteAction PDAction object.getDescription PDAction object.getId PDAction object.getType PDActionGroup.createActionGroup PDActionGroup.deleteActionGroup PDActionGroup.listActionGroups

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager (continued)

C API

ivadmin_acl_setunauth()

ivadmin_acl_setuser()

ivadmin_action_create()

ivadmin_action_create_in_group()

ivadmin_action_delete()

ivadmin_action_delete_from_group()

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_action_getdescription()

ivadmin_action_getid()

ivadmin_action_gettype()

ivadmin_action_group_create()

ivadmin_action_group_delete()

ivadmin_action_group_list()

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager (continued) Java Class and Method PDAction.listActions pdadmin action list pdadmin action list action_group_name pdadmin authzrule create rule_name rule_text [ desc description ] [ failreason failreason ] pdadmin authzrule delete rule_name pdadmin authzrule show rule_name pdadmin authzrule show rule_name pdadmin authzrule show rule_name pdadmin authzrule show rule_name pdadmin authzrule show rule_name pdadmin authzrule list pdadmin authzrule modify rule_name description description pdadmin authzrule modify rule_name failreason failreason PDAction.listActions PDAuthzRule.createAuthzRule Command Line Equivalent Web Portal Manager Equivalent ACL List Action Groups click primary action group ACL List Action Groups click Action Group AuthzRule Create AuthzRule

C API

ivadmin_action_list()

ivadmin_action_list_in_group()

ivadmin_authzrule_create()

ivadmin_authzrule_delete()

PDAuthzRule.deleteAuthzRule

AuthzRule List AuthzRule select AuthzRule names Delete AuthzRule List AuthzRule click AuthzRule name AuthzRule List AuthzRule click AuthzRule name AuthzRule List AuthzRule click AuthzRule name AuthzRule List AuthzRule click AuthzRule name AuthzRule List AuthzRule click AuthzRule name AuthzRule List AuthzRule click AuthzRule name AuthzRule List AuthzRule click AuthzRule name General tab modify fields Apply AuthzRule List AuthzRule click AuthzRule name General tab modify fields Apply

ivadmin_authzrule_get() PDAuthzRule object.getDescription PDAuthzRule object.getFailReason PDAuthzRule object.getID PDAuthzRule object.getRuleText PDAuthzRule.listAuthzRules PDAuthzRule.setDescription PDAuthzRule object.setDescription

PDAuthzRule constructor

ivadmin_authzrule_getdescription()

ivadmin_authzrule_getfailreason()

ivadmin_authzrule_getid()

ivadmin_authzrule_getruletext()

ivadmin_authzrule_list()

ivadmin_authzrule_setdescription()

Appendix C. Administration API equivalents

ivadmin_authzrule_setfailreason()

PDAuthzRule.setFailReason PDAuthzRule object.setFailReason

357

358
Java Class and Method PDAuthzRule.setRuleText PDAuthzRule object.setRuleText pdadmin authzrule modify rule_name ruletext ruletext svrsslcfg -add_replica -f cfg_file -h host_name [-p port] [-k rank] svrsslcfg -chg_replica -f cfg_file -h host_name [-p port] [-k rank] svrsslcfg -config -f cfg_file -d kdb_dir_name -n server_name ... pdadmin config show config_file stanza pdadmin config modify keyvalue remove config_file stanza key [ value ] svrsslcfg -chgcert -f cfg_file -n server_name [-A admin_ID] -P admin_pwd svrsslcfg -rmv_replica -f cfg_file -h host_name [-p port] [-k rank] svrsslcfg -modify -f cfg_file [-t timeout] [-C cert_file] [-l listening_mode] svrsslcfg -chgpwd -f cfg_file -n server_name [-A admin_ID] [-P admin_pwd] svrsslcfg -f cfg_file -modify -l yes Not supported.. Command Line Equivalent Web Portal Manager Equivalent AuthzRule List AuthzRule click AuthzRule name General tab modify fields Apply PDAppSvrConfig.addPDServer PDAppSvrConfig.changePDServer Not supported. PDAppSvrConfig.configureAppSvr Not supported. Not supported at this time. Not supported at this time. Not supported. Not supported. PDAppSvrConfig.replaceAppSvrCert Not supported. PDAppSvrConfig.removePDServer Not supported. Not supported at this time. Not supported. Not applicable. Not supported. PDAppSvrConfig.setAppSvrListening Not supported.

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager (continued)

C API

ivadmin_authzrule_setruletext()

ivadmin_cfg_addreplica2()

ivadmin_cfg_chgreplica2()

ivadmin_cfg_configureserver3()

ivadmin_cfg_getvalue()

ivadmin_cfg_removevalue()

ivadmin_cfg_renewservercert()

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_cfg_rmvreplica2()

ivadmin_cfg_setapplicationcert2()

ivadmin_cfg_setkeyringpwd2()

ivadmin_cfg_setlistening2()

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager (continued) Java Class and Method PDAppSvrConfig.setAppSvrPort svrsslcfg -config -f cfg_file -d kdb_dir_name -n server_name ... svrsslcfg -modify -f cfg_file -t timeout [-C cert_file] [-l listening_mode] pdadmin config modify svrpassword config_file password Not supported. Not supported. Command Line Equivalent Web Portal Manager Equivalent

C API

ivadmin_cfg_setport2()

ivadmin_cfg_setssltimeout2()

Not supported at this time.

ivadmin_cfg_setsvrpwd()

Not supported at this time.

Not supported.

ivadmin_cfg_setvalue()

Not supported at this time.

pdadmin config modify Not supported. keyvalue { set | append } [ obfuscate ] config_file stanza key value svrsslcfg -unconfig -f cfg_file -n server_name [-A admin_ID] -P admin_pwd Not applicable. Not applicable. Not applicable. Not applicable. Not applicable. pdadmin context show pdadmin policy get account-expiry-date Not applicable. pdadmin policy get disable-time-interval pdadmin context show Not supported.

ivadmin_cfg_unconfigureserver()

PDAppSvrConfig.unconfigureAppSvr

ivadmin_context_cleardelcred() PDContext constructor PDContext constructor Not supported at this time. PDContext object.close PDContext object.domainIsManagement PDPolicy object.getAcctExpDate

PDContext object.clearDelegatedCred

Not applicable. Not applicable. Not applicable. Not applicable. Not applicable. Not supported. User Show Global User Policy Account Expiration Date Not applicable. User Show Global User Policy Disable Time Interval Not supported.

ivadmin_context_create3()

ivadmin_context_createdefault2()

ivadmin_context_createlocal()

ivadmin_context_delete()

ivadmin_context_domainismanagement()

ivadmin_context_getaccexpdate()

ivadmin_context_getcodeset()

PDContext object.getLocale PDPolicy object.getAcctDisableTimeInterval

Appendix C. Administration API equivalents

ivadmin_context_getdisabletimeint()

ivadmin_context_getdomainid()

PDContext object.getDomainid

359

360
Java Class and Method PDPolicy object.getMaxFailedLogins pdadmin policy get max-login-failures pdadmin policy get max-password-age pdadmin policy get max-password-repeatedchars pdadmin login m Not supported at this time. Not supported at this time. pdadmin policy get min-password-alphas pdadmin policy get min-password-length pdadmin policy get min-password-non-alphas pdadmin policy get password-spaces pdadmin policy get tod-access User Show Global User Policy Minimum Password Alphas User Show Global User Policy Minimum Password Length User Show Global User Policy Minimum Password Non-Alphas User Show Global User Policy Password Spaces Allowed User Show Global User Policy Time of Day Access PDPolicy object.getMaxPwdAge PDPolicy object.getMaxPwdRepChars Command Line Equivalent Web Portal Manager Equivalent User Show Global User Policy Max Login Failures User Show Global User Policy Max Password Age User Show Global User Policy Max Password Repeated Characters Initial login. PDDomain.getMgmtDomainName Not supported at this time. Not supported at this time. PDPolicy object.getMinPwdAlphas PDPolicy object.getMinPwdLen PDPolicy object.getMinPwdNonAlphas PDPolicy object.pwdSpacesAllowed PDPolicy PDPolicy PDPolicy PDPolicy PDContext object.getUserid PDUser.getUserRgy PDContext object.hasDelegatedCred object.getAccessibleDays object.getAccessStartTime object.getAccessEndTime object.getAccessTimezone pdadmin context show pdadmin admin show configuration Not applicable. Not supported. Not supported. Not applicable.

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager (continued)

C API

ivadmin_context_getmaxlgnfails()

ivadmin_context_getmaxpwdage()

ivadmin_context_getmaxpwdrepchars()

ivadmin_context_getmgmtdomainid()

ivadmin_context_getmgmtsvrhost()

ivadmin_context_getmgmtsvrport()

ivadmin_context_getminpwdalphas()

ivadmin_context_getminpwdlen()

ivadmin_context_getminpwdnonalphas()

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_context_getpwdspaces()

ivadmin_context_gettodaccess()

ivadmin_context_getuserid()

ivadmin_context_getuserreg()

ivadmin_context_hasdelcred()

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager (continued) Java Class and Method PDPolicy.setAcctExpDate PDPolicy object.setAcctExpDate pdadmin policy set account-expiry-date [unlimited | absolute_time | unset] Not applicable. pdadmin policy set disable-time-interval [number | unset | disable] pdadmin policy set max-login-failures [number | unset] pdadmin policy set max-password-age [relative_time | unset] pdadmin policy set max-password-repeatedchars [number | unset] pdadmin policy set min-password-alphas [number | unset] pdadmin policy set min-password-length [number | unset] pdadmin policy set max-password-non-alphas [number | unset] pdadmin policy set password-spaces [yes | no | unset] pdadmin policy set tod-access todaccess_value Not applicable. User Show Global User Policy Show Global User Policy Apply User Show Global User Policy Max Login Failures Apply User Show Global User Policy Max Password Age Apply User Show Global User Policy Max Password Repeated Characters Apply User Show Global User Policy Minimum Password Alphas Apply User Show Global User Policy Minimum Password Length Apply User Show Global User Policy Minimum Password Non-Alphas Apply User Show Global User Policy Password Spaces Allowed Apply User Show Global User Policy Time of Day Access Apply Command Line Equivalent Web Portal Manager Equivalent User Show Global User Policy Account Expiration Date Apply

C API

ivadmin_context_setaccexpdate()

ivadmin_context_setdelcred() PDPolicy.setAcctDisableTime PDPolicy object.setAcctDisableTime

PDContext object.setDelegatedCred

ivadmin_context_setdisabletimeint()

ivadmin_context_setmaxlgnfails()

PDPolicy.setMaxFailedLogins PDPolicy object.setMaxFailedLogins PDPolicy.setMaxPwdAge PDPolicy object.setMaxPwdAge PDPolicy.setMaxPwdRepChars PDPolicy object.setMaxPwdRepChars PDPolicy.setMinPwdAlphas PDPolicy object.setMinPwdAlphas PDPolicy.setMinPwdLen PDPolicy object.setMinPwdLen PDPolicy.setMinPwdNonAlphas PDPolicy object.setMinPwdNonAlphas PDPolicy.setPwdSpacesAllowed PDPolicy object.setPwdSpacesAllowed PDPolicy.setTodAccess PDPolicy object.setTodAccess

ivadmin_context_setmaxpwdage()

ivadmin_context_setmaxpwdrepchars()

ivadmin_context_setminpwdalphas()

ivadmin_context_setminpwdlen()

ivadmin_context_setminpwdnonalphas()

ivadmin_context_setpwdspaces()

Appendix C. Administration API equivalents

ivadmin_context_settodaccess()

361

362
Java Class and Method PDDomain.createDomain pdadmin domain create domain_name domain_admin domain_admin_pwd [ desc description ] pdadmin domain delete domain_name pdadmin domain show domain_name pdadmin domain show domain_name pdadmin domain showdomain_name pdadmin domain list pdadmin domain modify domain_name description description Not applicable. pdadmin group modify group_name add (user_name1 user_name2 ...) pdadmin group create group_name dn cn pdadmin group delete [-registry] group_name Secure Domain Create Secure Domain Command Line Equivalent Web Portal Manager Equivalent PDDomain.deleteDomain Secure Domain List Secure Domain select Secure Domain names Delete Secure Domain List Secure Domain click Secure Domain name Secure Domain List Secure Domain click Secure Domain name Secure Domain List Secure Domain click Secure Domain name Secure Domain List Secure Domain Secure Domain List Secure Domain click Secure Domain name modify description Apply Not applicable. Group Search Groups enter pattern and maximum results Search click group name Members tab Add Group Create Group Group Search Groups enter pattern and maximum results Search select group names Delete PDDomain constructor PDDomain object.getDescription PDDomain object.getId PDDomain.listDomains PDDomain.setDescription PDDomain object.setDescription Not applicable. PDGroup.addMembers PDGroup object.addMembers PDGroup.createGroup PDGroup.deleteGroup

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager (continued)

C API

ivadmin_domain_create()

ivadmin_domain_delete()

ivadmin_domain_get()

ivadmin_domain_getdescription()

ivadmin_domain_getid()

ivadmin_domain_list()

ivadmin_domain_setdescription()

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_free()

ivadmin_group_addmembers()

ivadmin_group_create2()

ivadmin_group_delete2()

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager (continued) Java Class and Method PDGroup constructor pdadmin group show group_name Command Line Equivalent Web Portal Manager Equivalent Group Search Groups enter pattern and maximum results Search click group name Not supported. Group Search Groups enter pattern and maximum results Search click group name Group Search Groups enter pattern and maximum results Search click group name Group Search Groups enter pattern and maximum results Search click group name pdadmin group show group_name pdadmin group show group_name Group Search Groups enter pattern and maximum results Search click group name pdadmin group show-members group_name Group Search Groups enter pattern and maximum results Search click group name Members tab pdadmin group import group_name dn pdadmin group list pattern max_return pdadmin group list-dn pattern max_return Group Import Group Group Search Groups enter pattern and maximum results Search Not supported.

C API

ivadmin_group_get()

ivadmin_group_getbydn() pdadmin group show-dn dn pdadmin group show group_name Will not be supported.

PDGroup constructor

ivadmin_group_getcn()

ivadmin_group_getdescription() pdadmin group show group_name

PDGroup object.getDescription

ivadmin_group_getdn()

PDGroup object.getRgyName

ivadmin_group_getid()

PDGroup object.getId

ivadmin_group_getmembers()

PDGroup object.getMembers

ivadmin_group_import2() PDGroup.listGroups

PDGroup.importGroup

ivadmin_group_list()

Appendix C. Administration API equivalents

ivadmin_group_listbydn()

PDGroup.listGroups

363

364
Java Class and Method PDGroup.removeMembers PDGroup object.removeMembers pdadmin group modify group_name remove (user_name1 user_name2 ...) pdadmin group modify group_name description description Command Line Equivalent Web Portal Manager Equivalent Group Search Groups enter pattern and maximum results Search click group name Members tab select user names Remove Group Search Groups enter pattern and maximum results Search click group name enter Description Apply Object Space Create Object Space Object Space Browse Object Space click object space name Delete Object Space Browse Object Space POP List POP click POP name Attach tab Attach pdadmin pop attach object_name pop_name pdadmin pop modify pop_name delete attribute attribute_name pdadmin pop modify pop_name delete attribute attribute_name attribute_value pdadmin pop show pop_name attribute pdadmin pop list pop_name attribute POP List POP click POP name Extended Attributes tab select attributes Delete POP List POP click POP name Extended Attributes tab select attributes Delete POP List POP click POP name Extended Attributes tab POP List POP click POP name Extended Attributes tab PDGroup.setDescription PDGroup object.setDescription PDProtObjectSpace.createProtObjectSpace PDProtObjectSpace.deleteProtObjectSpace pdadmin objectspace create objectspace_name pdadmin objectspace delete objectspace_name pdadmin objectspace list PDProtObjectSpace.listProtObjectSpaces PDProtObject.attachPop PDProtObject object.attachPop PDPop.deleteAttribute PDPop object.deleteAttribute PDPop.deleteAttributeValue PDPop object.deleteAttributeValue PDPop object.getAttributeValues PDPop object.getAttributeNames

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager (continued)

C API

ivadmin_group_removemembers()

ivadmin_group_setdescription()

ivadmin_objectspace_create()

ivadmin_objectspace_delete()

ivadmin_objectspace_list()

ivadmin_pop_attach()

ivadmin_pop_attrdelkey()

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_pop_attrdelval()

ivadmin_pop_attrget()

ivadmin_pop_attrlist()

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager (continued) Java Class and Method PDPop.setAttributeValue PDPop object.setAttributeValue pdadmin pop modify pop_name set attribute attribute_name attribute_value pdadmin pop create pop_name pdadmin pop delete pop_name pdadmin pop detach object_name pdadmin pop find pop_name pdadmin pop show pop_name pdadmin pop show pop_name pdadmin pop show pop_name pdadmin pop show pop_name pdadmin pop show pop_name pdadmin pop show pop_name pdadmin pop show pop_name pdadmin pop list pdadmin pop modify pop_name set ipauth remove network netmask Command Line Equivalent Web Portal Manager Equivalent POP List POP click POP name Extended Attributes tab Create POP Create POP POP List POP select POP names Delete POP List POP click POP name Attach tab select object Detach POP List POP click POP name Attach tab POP List POP click POP name POP List POP click POP name POP List POP click POP name POP List POP click POP name POP List POP click POP name POP List POP click POP name POP List POP click POP name POP List POP POP List POP click POP name IP Auth tab select IP auth entries Delete

C API

ivadmin_pop_attrput()

ivadmin_pop_create() PDPop.deletePop PDProtObject.detachPop PDProtObject object.attachPop PDProtObject.listProtObjectsByPop PDPop constructor PDPop object.getAuditLevel PDPop object.getDescription PDPop object.getId PDPop object.getQOP PDPop object.getTodAccessInfo PDPop object.getWarningMode PDPop.listPops PDPop.removeIPAuthInfo PDPop object.removeIPAuthInfo

PDPop.createPop

ivadmin_pop_delete()

ivadmin_pop_detach()

ivadmin_pop_find()

ivadmin_pop_get()

ivadmin_pop_getauditlevel()

ivadmin_pop_getdescription()

ivadmin_pop_getid()

ivadmin_pop_getqop()

ivadmin_pop_gettod()

ivadmin_pop_getwarnmode()

ivadmin_pop_list()

Appendix C. Administration API equivalents

ivadmin_pop_removeipauth()

365

366
Java Class and Method PDPop.setuthInfo pdadmin pop modify pop_name set ipauth anyothernw authentication_level pdadmin pop modify pop_name set ipauth anyothernw forbidden Command Line Equivalent Web Portal Manager Equivalent POP List POP click POP name IP Auth tab Create select Any Other Network check box, enter the authentication level Create POP List POP click POP name IP Auth tab Create select Any Other Network check box, select Forbidden check box Create POP List POP click POP name General tab select Audit Level check box Apply POP List POP click POP name General tab Apply POP List POP click POP name IP Auth tab Create enter the network, net mask, and authentication level Apply pdadmin pop modify pop_name set ipauth add network netmask authentication_level pdadmin pop modify pop_name set ipauth add network netmask forbidden POP List POP click POP name IP Auth tab Create enter the network and net mask, select Forbidden check box Apply pdadmin pop modify pop_name set qop [none | integrity | privacy] pdadmin pop modify pop_name set tod-access tod_value POP List POP click POP name General tab Apply POP List POP click POP name General tab Apply PDPop.setIPAuthInfo PDPop.setAuditLevel PDPop object.setAuditLevel pdadmin pop modify pop_name set audit-level [all | none | audit_level_list] pdadmin pop modify pop_name set description description PDPop.setDescription PDPop object.setDescription PDPop.setIPAuthInfo PDPop object.setIPAuthInfo PDPop.setIPAuthInfo PDPop object.setIPAuthInfo PDPop.setQOP PDPop object.setQOP PDPop.setTodAccessInfo PDPop object.setTodAccessInfo .

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager (continued)

C API

ivadmin_pop_setanyothernw()

ivadmin_pop_setanyothernw_forbidden()

ivadmin_pop_setauditlevel()

ivadmin_pop_setdescription()

ivadmin_pop_setipauth()

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_pop_setipauth_forbidden()

ivadmin_pop_setqop()

ivadmin_pop_settod()

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager (continued) Java Class and Method PDPop.setWarningMode PDPop object.setWarningMode pdadmin pop modify pop_name set warning [ on | off ] pdadmin object access object_name pdadmin acl attach object_name acl_name pdadmin authzrule attach object_name rule_name pdadmin object modify object_name delete attribute_name Not supported. ACL List ACL click ACL name Attach tab Attach AuthzRule List AuthzRule click AuthzRule name Attach tab Attach Object Space Browse Object Space expand and click on object name Extended Attributes tab select attribute Delete Object Space Browse Object Space expand and click on object name Extended Attributes tab select attribute Delete pdadmin object modify object_name delete attribute_name attribute_value pdadmin object show object_name attribute attribute_name pdadmin object list object_name attribute Object Space Browse Object Space expand and click on object name Extended Attributes tab Object Space Browse Object Space expand and click on object name Extended Attributes tab pdadmin object modify object_name set attribute attribute_name attribute_value Object Space Browse Object Space expand and click on object name Extended Attributes tab Create PDProtObject.access PDProtObject.attachAcl PDProtObject object.attachAcl PDProtObject.attachAuthzRule PDProtObject object.attachAuthzRule PDProtObject.deleteAttribute PDProtObject object.deleteAttribute Command Line Equivalent Web Portal Manager Equivalent POP List POP click POP name General tab Apply

C API

ivadmin_pop_setwarnmode()

ivadmin_protobj_access()

ivadmin_protobj_attachacl()

ivadmin_protobj_attachauthzrule()

ivadmin_protobj_attrdelkey()

ivadmin_protobj_attrdelval()

PDProtObject.deleteAttributeValue PDProtObject object.deleteAttributeValue

ivadmin_protobj_attrget()

PDProtObject object.getAttributeValues

ivadmin_protobj_attrlist()

PDProtObject object.getAttributeNames

Appendix C. Administration API equivalents

ivadmin_protobj_attrput()

PDProtObject.setAttributeValue PDProtObject object.setAttributeValue

367

368
Java Class and Method PDProtObject.createProtObject pdadmin object create object_name Command Line Equivalent Web Portal Manager Equivalent Object Space Create Object Select the Can Policy be attached to this object check box on the Protected Object Properties window. Note: The type field is not supported. PDProtObject.deleteProtObject pdadmin object delete object_name Object Space Browse Object Space expand and click on object name General tab Delete ACL List ACL click ACL name Attach tab select object names Detach AuthzRule List AuthzRule click AuthzRule name Attach tab select object names Detach pdadmin authzrule detach object_name pdadmin object exists object_name pdadmin object show object_name Not supported. Object Space Browse Object Space expand and click on object name General tab pdadmin object show object_name Object Space Browse Object Space expand and click on object name General tab pdadmin object show object_name Object Space Browse Object Space expand and click on object name General tab PDProtObject.detachAcl PDProtObject object.detachAcl PDProtObject.detachAuthzRule PDProtObject object.detachAuthzRule pdadmin acl detach object_name PDProtObject.exists PDProtObject constructor PDProtObject object.getAcl PDProtObject object.getAuthzRule

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager (continued)

C API

ivadmin_protobj_create()

ivadmin_protobj_delete()

ivadmin_protobj_detachacl()

ivadmin_protobj_detachauthzrule()

ivadmin_protobj_exists()

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_protobj_get3()

ivadmin_protobj_getaclid()

ivadmin_protobj_getauthzruleid()

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager (continued) Java Class and Method PDProtObject object.getDescription pdadmin object show object_name Command Line Equivalent Web Portal Manager Equivalent Object Space Browse Object Space expand and click on object name General tab Object Space Browse Object Space expand and click on object name General tab Object Space Browse Object Space expand and click on object name General tab Object Space Browse Object Space expand and click on object name General tab Object Space Browse Object Space expand and click on object name General tab pdadmin object show object_name pdadmin object show object_name Object Space Browse Object Space expand and click on object name General tab pdadmin object show object_name Object Space Browse Object Space expand and click on object name General tab pdadmin object show object_name Object Space Browse Object Space expand and click on object name General tab pdadmin object list directory_name Object Space Browse Object Space expand and click on object name

C API

ivadmin_protobj_getdesc()

ivadmin_protobj_geteffaclid() pdadmin object show object_name

PDProtObject object.getEffectuveAclId

ivadmin_protobj_geteffauthzruleid() pdadmin object show object_name

PDProtObject object.getEffectuveAuthzRuleId

ivadmin_protobj_geteffpopid()

PDProtObject object.getEffectuvePopId

pdadmin object show object_name

ivadmin_protobj_getid()

PDProtObject object.getId

ivadmin_protobj_getpolicyattachable()

PDProtObject object.isPolicyAttachable

ivadmin_protobj_getpopid()

PDProtObject object.getPopId

ivadmin_protobj_gettype()

Will not be supported.

Appendix C. Administration API equivalents

ivadmin_protobj_list3()

PDProtObject.listProtObjects

369

370
Java Class and Method PDProtObject.listProtObjectsByAcl pdadmin acl find acl_name pdadmin authzrule find rule_name pdadmin object access object_name pdadmin object modify object_name description description pdadmin object modify object_name name name conflict_resolution resolution_modifier pdadmin object modify object_name isPolicyAttachable [yes | no] pdadmin object modify object_name type type Not applicable. Not applicable. Not applicable. Not applicable. Not applicable. pdadmin server listtasks server_name pdadmin server task server_name task_to_perform pdadmin server replicate server_name PDProtObject.listProtObjectsByAuthzRule Command Line Equivalent Web Portal Manager Equivalent ACL List ACL click ACL name Attach tab AuthzRule List AuthzRule click AuthzRule name Attach tab Not supported. Object Space Browse Object Space expand and click on object name General tab Apply Not supported. PDProtObject.multiAccess PDProtObject.setDescription PDProtObject object.setDescription Will not be supported. PDProtObject.setPolicyAttachable PDProtObject object.setPolicyAttachable Object Space Browse Object Space expand and click on object name General tab Apply Not supported. Not applicable. Not applicable. Not applicable. Not applicable. Not applicable. Not supported. Not supported. Will not be supported. Not applicable. Not applicable. Not applicable. Not applicable. Not applicable. PDServer.getTaskList PDServer.performTask PDServer.serverReplicate Not supported.

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager (continued)

C API

ivadmin_protobj_listbyacl()

ivadmin_protobj_listbyauthzrule()

ivadmin_protobj_multiaccess()

ivadmin_protobj_setdesc()

ivadmin_protobj_setname()

ivadmin_protobj_setpolicyattachable()

ivadmin_protobj_settype()

ivadmin_response_getcode()

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_response_getcount()

ivadmin_response_getmessage()

ivadmin_response_getmodifier()

ivadmin_response_getok()

ivadmin_server_gettasklist()

ivadmin_server_performtask()

ivadmin_server_replicate()

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager (continued) Java Class and Method PDSSOCred.createSSOCred pdadmin rsrccred create resource_name rsrcuser resource_userid rsrcpwd resource_pwd rsrctype [web | group] user user_name pdadmin rsrccred delete resource_name rsrctype [web | group] user user_name pdadmin rsrccred show resource_name rsrctype [web | group] user user_name pdadmin rsrccred show resource_name rsrctype [web | group] user user_name Not applicable. Not applicable. pdadmin rsrccred show resource_name rsrctype [web | group] user user_name pdadmin rsrccred show resource_name rsrctype [web | group] user user_name pdadmin rsrccred list user user_name Command Line Equivalent Web Portal Manager Equivalent User Search Users Search click user name click GSO Credentials tab click Create

C API

ivadmin_ssocred_create()

ivadmin_ssocred_delete()

PDSSOCred.deleteSSOCred

User Search Users Search click user name click GSO Credentials tab select GSO Credentials Delete User Search Groups Search click user name click GSO Credentials tab User Search Groups Search click user name click GSO Credentials tab Not applicable. Not applicable. User Search Groups Search click user name click GSO Credentials tab User Search Groups Search click user name click GSO Credentials tab User Search Users Search click user name click GSO Credentials tab

ivadmin_ssocred_get()

PDSSOCred constructor

ivadmin_ssocred_getid()

PDSSOCred object.getResourceName

ivadmin_ssocred_getssopassword() PDSSOCred object.getResourceUser PDSSOCred object.getResourceType

PDSSOCred object.getResourcePassword

ivadmin_ssocred_getssouser()

ivadmin_ssocred_gettype()

ivadmin_ssocred_getuser()

PDSSOCred object.getUser

Appendix C. Administration API equivalents

ivadmin_ssocred_list()

PDSSOCred object.listAndShowSSOCreds PDSSOCred object.listSSOCreds

371

372
Java Class and Method PDSSOCred.setSSOCred PDSSOCred object.setSSOCred. pdadmin rsrccred modify resource_name rsrctype [web | group] [-rsrcuser resource_userid] [-rsrcpwd resource_pwd] user user_name pdadmin rsrcgroup modify resource_group_name add rsrcname resource_name Command Line Equivalent Web Portal Manager Equivalent User Search Users Search click user name click GSO Credentials tab click Create PDSSOResourceGroup.addSSOResource PDSSOResourceGroup objectaddSSOResource PDSSOResourceGroup.createSSOResourceGroup pdadmin rsrcgroup create resource_group_name [-desc description] PDSSOResourceGroup.deleteSSOResourceGroup pdadmin rsrcgroup delete resource_group_name PDSSOResourceGroup constructor pdadmin rsrcgroup show resource_group_name pdadmin rsrcgroup show resource_group_name pdadmin rsrcgroup show resource_group_name pdadmin rsrcgroup show resource_group_name pdadmin rsrcgroup list pdadmin rsrcgroup modify resource_group_name remove rsrcname resource_name GSO Resource List GSO Groups click GSO resource group Add GSO Resource Create GSO Group GSO Resource List GSO Groups select GSO resource groups Delete GSO Resource List GSO Groups click GSO resource group GSO Resource List GSO Groups click GSO resource group GSO Resource List GSO Groups click GSO resource group GSO Resource List GSO Groups click GSO resource group GSO Resource List GSO Groups GSO Resource List GSO Groups click GSO resource group select members Remove PDSSOResourceGroup object.getDescription PDSSOResourceGroup object.getId PDSSOResourceGroup object.getSSOResources PDSSOResourceGroup.listSSOResourceGroups PDSSOResourceGroup.removeSSOResource PDSSOResourceGroup object.removeSSOResource.

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager (continued)

C API

ivadmin_ssocred_set()

ivadmin_ssogroup_addres()

ivadmin_ssogroup_create()

ivadmin_ssogroup_delete()

ivadmin_ssogroup_get()

ivadmin_ssogroup_getdescription()

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_ssogroup_getid()

ivadmin_ssogroup_getresources()

ivadmin_ssogroup_list()

ivadmin_ssogroup_removeres()

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager (continued) Java Class and Method PDSSOResource.createSSOResource pdadmin rsrc create resource_name [-desc description] pdadmin rsrc delete resource_name pdadmin rsrc show resource_name pdadmin rsrc show resource_name pdadmin rsrc show resource_name pdadmin rsrc list pdadmin user create [-gsouser] [-no-password-policy] user_name dn cn sn pwd ( group1 group2 ... ) pdadmin user delete [-registry] user_name Command Line Equivalent Web Portal Manager Equivalent GSO Resource Create GSO

C API

ivadmin_ssoweb_create()

ivadmin_ssoweb_delete() PDSSOResource constructor PDSSOResource object.getDescription PDSSOResource object.getId PDSSOResource.listSSOResources PDUser.createUser

PDSSOResource.deleteSSOResource

GSO Resource List GSO select GSO resources Delete GSO Resource List GSO click GSO resource GSO Resource List GSO click GSO resource GSO Resource List GSO click GSO resource GSO Resource List GSO User Create User

ivadmin_ssoweb_get()

ivadmin_ssoweb_getdescription()

ivadmin_ssoweb_getid()

ivadmin_ssoweb_list()

ivadmin_user_create3()

ivadmin_user_delete2()

PDUser.deleteUser

User Search Users enter pattern and maximum results Search select user names Delete pdadmin user show user_name pdadmin user get account-expiry-date [-user user_name ] pdadmin user show user_name pdadmin user show-dn dn User Search Users enter pattern and maximum results Search click user name User Search Users enter pattern and maximum results Search click user name Policy tab User Search Users enter pattern and maximum results Search click user name User Search Users enter pattern and maximum results Search click user name

ivadmin_user_get()

PDUser constructor

ivadmin_user_getaccexpdate()

PDPolicy object.getAcctExpDate

ivadmin_user_getaccountvalid()

PDUser object.isAccountValid

Appendix C. Administration API equivalents

ivadmin_user_getbydn()

PDUser constructor

373

374
Java Class and Method PDUser object.getFirstName pdadmin user show user_name pdadmin user show user_name pdadmin policy get disable-time-interval [-user user_name] pdadmin user show user_name pdadmin user show user_name pdadmin policy get max-login-failures [-user user_name] pdadmin policy get max-password-age [-user user_name] pdadmin policy get max-password-repeatedchars [-user user_name] pdadmin user show-groups user_name Command Line Equivalent Web Portal Manager Equivalent User Search Users enter pattern and maximum results Search click user name User Search Users enter pattern and maximum results Search click user name User Search Users enter pattern and maximum results Search click user name Policy tab User Search Users enter pattern and maximum results Search click user name User Search Users enter pattern and maximum results Search click user name User Search Users enter pattern and maximum results Search click user name Policy tab User Search Users enter pattern and maximum results Search click user name Policy tab User Search Users enter pattern and maximum results Search click user name Policy tab User Search Users enter pattern and maximum results Search click user name Groups tab PDUser object.getDescription PDPolicy object.getAcctDisableTimeInterval PDUser object.getRgyName PDUser object.getId PDPolicy object.getMaxFailedLogins PDPolicy object.getMaxPwdAge PDPolicy object.getMaxPwdRepChars PDUser object.getGroups

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager (continued)

C API

ivadmin_user_getcn()

ivadmin_user_getdescription()

ivadmin_user_getdisabletimeint()

ivadmin_user_getdn()

ivadmin_user_getid()

ivadmin_user_getmaxlgnfails()

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_getmaxpwdage()

ivadmin_user_getmaxpwdrepchars()

ivadmin_user_getmemberships()

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager (continued) Java Class and Method PDPolicy object.getMinPwdAlphas pdadmin policy get min-password-alphas [-user user_name] pdadmin policy get min-password-length [-user user_name] pdadmin policy get min-password-non-alphas [-user user_name] pdadmin user show user_name pdadmin policy get password-spaces [-user user_name] pdadmin user show user_name pdadmin user show user_name pdadmin policy get tod-access -user user_name pdadmin user import [-gsouser] user_name dn pdadmin user list pattern max_return Command Line Equivalent Web Portal Manager Equivalent User Search Users enter pattern and maximum results Search click user name Policy tab User Search Users enter pattern and maximum results Search click user name Policy tab User Search Users enter pattern and maximum results Search click user name Policy tab User Search Users enter pattern and maximum results Search click user name User Search Users enter pattern and maximum results Search click user name Policy tab User Search Users enter pattern and maximum results Search click user name User Search Users enter pattern and maximum results Search click user name User Search Users enter pattern and maximum results Search click user name Policy tab User Import User User Search Users enter pattern and maximum results Search PDUser.listUsers

C API

ivadmin_user_getminpwdalphas()

ivadmin_user_getminpwdlen()

PDPolicy object.getMinPwdLen

ivadmin_user_getminpwdnonalphas()

PDPolicy object.getMinPwdNonAlphas

ivadmin_user_getpasswordvalid()

PDUser object.isPasswordValid

ivadmin_user_getpwdspaces()

PDPolicy object.pwdSpacesAllowed

ivadmin_user_getsn()

PDUser object.getLastName

ivadmin_user_getssouser()

PDUser object.isSSOUser

ivadmin_user_gettodaccess()

PDPolicy object.getAccessibleDays PDPolicy object.getAccessStartTime PDPolicy object.getAccessEndTime PDUser.importUser

ivadmin_user_import2()

Appendix C. Administration API equivalents

ivadmin_user_list()

375

376
Java Class and Method PDUser.listUsers pdadmin user list-dn pattern max_return pdadmin policy set account-expiry-date [unlimited | absolute_time | unset] [-user user_name] pdadmin user modify user_name account-valid [yes | no] pdadmin user modify user_name description description pdadmin policy set disable-time-interval [number | unset | disable] [-user user_name] pdadmin policy set max-login-failures [number | unset] [-user user_name] pdadmin policy set max-password-age [unset | relative_time] [-user user_name] pdadmin policy set max-password-repeatedchars [number | unset] [-user user_name] PDPolicy.setAcctExpDate PDPolicy object.setAcctExpDate Not supported. User Search Users enter pattern and maximum results Search click user name Policy tab User Search Users enter pattern and maximum results Search click user name General tab User Search Users enter pattern and maximum results Search click user name General tab User Search Users enter pattern and maximum results Search click user name Policy tab User Search Users enter pattern and maximum results Search click user name Policy tab User Search Users enter pattern and maximum results Search click user name Policy tab User Search Users enter pattern and maximum results Search click user name Policy tab Command Line Equivalent Web Portal Manager Equivalent PDUser.setAccountValid PDUser object.setAccountValid PDUser.setDescription PDUser object.setDescription PDPolicy.setAcctDisableTime PDPolicy object.setAcctDisableTime PDPolicy.setMaxFailedLogins PDPolicy object.setMaxFailedLogins PDPolicy.setMaxPwdAge PDPolicy object.setMaxPwdAge PDPolicy.setMaxPwdRepChars PDPolicy object.setMaxPwdRepChars

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager (continued)

C API

ivadmin_user_listbydn()

ivadmin_user_setaccexpdate()

ivadmin_user_setaccountvalid()

ivadmin_user_setdescription()

ivadmin_user_setdisabletimeint()

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_user_setmaxlgnfails()

ivadmin_user_setmaxpwdage()

ivadmin_user_setmaxpwdrepchars()

Table 39. Mapping between administration C API, Java methods, the command line interface, and Web Portal Manager (continued) Java Class and Method PDPolicy.setMinPwdAlphas PDPolicy object.setMinPwdAlphas pdadmin policy set min-password-alphas [number | unset] [-user user_name] pdadmin policy set min-password-length [number | unset] [-user user_name] pdadmin policy set min-password-non-alphas [number | unset] [-user user_name] pdadmin user modify user_name password password pdadmin user modify user_name password-valid [yes | no] pdadmin policy set password-spaces [yes | no | unset] [-user user_name] pdadmin user modify user_name gsouser [yes | no] pdadmin policy set tod-access tod_value -user user_name Command Line Equivalent Web Portal Manager Equivalent User Search Users enter pattern and maximum results Search click user name Policy tab User Search Users enter pattern and maximum results Search click user name Policy tab User Search Users enter pattern and maximum results Search click user name Policy tab User Search Users enter pattern and maximum results Search click user name General tab User Search Users enter pattern and maximum results Search click user name General tab User Search Users enter pattern and maximum results Search click user name Policy tab User Search Users enter pattern and maximum results Search click user name General tab User Search Users enter pattern and maximum results Search click user name Policy tab

C API

ivadmin_user_setminpwdalphas()

ivadmin_user_setminpwdlen()

PDPolicy.setMinPwdLen PDPolicy object.setMinPwdLen

ivadmin_user_setminpwdnonalphas()

PDPolicy.setMinPwdNonAlphas PDPolicy object.setMinPwdNonAlphas

ivadmin_user_setpassword()

PDUser.setPassword PDUser object.setPassword

ivadmin_user_setpasswordvalid()

PDUser.setPasswordValid PDUser object.setPasswordValid

ivadmin_user_setpwdspaces()

PDPolicy.setPwdSpacesAllowed PDPolicy object.setPwdSpacesAllowed

ivadmin_user_setssouser()

PDUser.setSSOUser PDUser object.setSSOUser

Appendix C. Administration API equivalents

ivadmin_user_settodaccess()

PDPolicy.setTodAccess PDPolicy object.setTodAccess

377

378

IBM Tivoli Access Manager for e-business: Administration C API Developer 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 in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the users responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106-0032, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product 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 it believes appropriate without incurring any obligation to you.
Copyright IBM Corp. 2000, 2003

379

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation 2Z4A/101 11400 Burnet Road Austin, TX 78758 U.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 material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. All statements regarding IBMs future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing, or distributing application programs conforming to IBMs application programming interfaces. If you are viewing this information softcopy, the photographs and color illustrations may not appear.

Trademarks
The following terms are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both:

380

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

AIX DB2 IBM IBM logo OS/390 SecureWay Tivoli Tivoli logo Universal Database WebSphere z/OS zSeries Lotus is a registered trademark of Lotus Development Corporation and/or IBM Corporation. Domino is a trademark of International Business Machines Corporation and Lotus Development Corporation in the United States, other countries, or both. Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks 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 other countries. Other company, product, and service names may be trademarks or service marks of others.

Appendix D. Notices

381

382

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Index A
access control list entries, table 31 access control list entry types 30 access control lists, table 30 account functions, table 21, 22 accounts 20 action group functions, table 32, 33 action groups overview 32 adding development systems 4 ADK 3 ADK component 3 administration API compilers supported 4 installing 3 shared libraries 2 administration tasks 49 any-authenticated 30 any-other 30 API differences 353 application developer kit (ADK) 3 application development kit (ADK) 3 application, deploying 5 applications, building 3 audit log 37 audit records 37 authorization rules administering 39 functions 39 azn_creds_get_pac() function 9 deprecated functions 347 ivadmin_cfg_addreplica() 347 ivadmin_cfg_chgreplica() 347 ivadmin_cfg_configureserver() 347 ivadmin_cfg_configureserver2() 347 ivadmin_cfg_rmvreplica() 347 ivadmin_cfg_setapplicationcert() 347 ivadmin_cfg_setkeyringpwd() 347 ivadmin_cfg_setlistening() 347 ivadmin_cfg_setport() 347 ivadmin_cfg_setssltimeout() 347 ivadmin_context_create2() 347 ivadmin_context_createdefault() 347 ivadmin_group_addmember() 347 ivadmin_group_create() 347 ivadmin_group_delete() 348 ivadmin_group_import() 348 ivadmin_group_removemember() 347 ivadmin_protobj_get() 348 ivadmin_protobj_get2() 347 ivadmin_protobj_getacl() 347 ivadmin_protobj_getauthzrule() 347 ivadmin_protobj_getpop() 347 ivadmin_protobj_list2() 348 ivadmin_protobj_setname() 347 ivadmin_user_create() 348 ivadmin_user_create2() 347 ivadmin_user_delete() 348 ivadmin_user_getauthmech () 347 ivadmin_user_import() 348 ivadmin_user_setauthmech () 347 detecting errors 15 development systems, adding 4 domains administering 45 functions for administering 45 management 45

B
building applications 3

C
cleanup of the Administration API 16 code page 8 commands, pdadmin 2 commands, svrsslcfg 2 compilers tested 4 components 2 constants deprecated 348 container objects 26 creating LDAP users 10 creating objects 10 creating objects, example 10 creating Privilege Attribute Certificate data creating protected objects 241

E
error codes 15 error conditions 10 error message modifiers 16 error messages, text 15 errors, detecting 15 establishing security contexts 7 examples creating objects 10 functions that read values 13 ivadmin_context_delete() 17 modifying the maximum password age program 5 returned data types 12 set operations 11 setting account expiration dates 11 extended action functions, table 33 extended actions, overview 33

11

D
delegating user credentials 9 deleting a security context 17 demonstration program 5 deploying an application 5 deprecated constants 348 Copyright IBM Corp. 2000, 2003

383

F
files, installation directories 3 freeing memory 16 functions azn_creds_get_pac() 9 deprecated 347 ivadmin_accessOutdata_getAccessResult() 54 ivadmin_accessOutdata_getPermInfo() 55 ivadmin_accessOutdata_getResponseInfo() 56 ivadmin_acl_attrdelkey() 57 ivadmin_acl_attrdelval() 58 ivadmin_acl_attrget() 59 ivadmin_acl_attrlist() 60 ivadmin_acl_attrput() 61 ivadmin_acl_create() 62 ivadmin_acl_delete() 63 ivadmin_acl_get() 64 ivadmin_acl_getanyother() 65 ivadmin_acl_getdescription() 66 ivadmin_acl_getgroup() 67 ivadmin_acl_getid() 68 ivadmin_acl_getunauth() 69 ivadmin_acl_getuser() 70 ivadmin_acl_list() 71 ivadmin_acl_listgroups() 72 ivadmin_acl_listusers() 73 ivadmin_acl_removeanyother() 74 ivadmin_acl_removegroup() 75 ivadmin_acl_removeunauth() 76 ivadmin_acl_removeuser() 77 ivadmin_acl_setanyother() 78 ivadmin_acl_setdescription() 80 ivadmin_acl_setgroup() 81 ivadmin_acl_setunauth() 83 ivadmin_acl_setuser() 85 ivadmin_action_create_in_group() 89 ivadmin_action_create() 87 ivadmin_action_delete_from_group() 91 ivadmin_action_delete() 90 ivadmin_action_getdescription 92 ivadmin_action_getid() 93 ivadmin_action_gettype() 94 ivadmin_action_group_create() 95 ivadmin_action_group_delete() 96 ivadmin_action_group_list() 97 ivadmin_action_list_in_group() 99 ivadmin_action_list() 98 ivadmin_authzrule_create() 100 ivadmin_authzrule_delete() 101 ivadmin_authzrule_get() 102 ivadmin_authzrule_getdescription() 103 ivadmin_authzrule_getfailreason() 104 ivadmin_authzrule_getid() 105 ivadmin_authzrule_getruletext() 106 ivadmin_authzrule_list() 107 ivadmin_authzrule_setdescription() 108 ivadmin_authzrule_setfailreason() 109 ivadmin_authzrule_setruletext() 110 ivadmin_cfg_addreplica2() 111 ivadmin_cfg_chgreplica2() 112 ivadmin_cfg_configureserver3() 113 ivadmin_cfg_getvalue() 115 ivadmin_cfg_removevalue() 117 ivadmin_cfg_renewservercert() 119 ivadmin_cfg_rmvreplica2() 120 ivadmin_cfg_setapplicationcert2() 121 ivadmin_cfg_setkeyringpwd2() 122

functions (continued) ivadmin_cfg_setlistening2() 123 ivadmin_cfg_setport2() 124 ivadmin_cfg_setssltimeout2() 125 ivadmin_cfg_setsvrpwd() 126 ivadmin_cfg_setvalue() 128 ivadmin_cfg_unconfigureserver() 130 ivadmin_context_cleardelcred() 131 ivadmin_context_create3() 9, 132 ivadmin_context_createdefault2 9 ivadmin_context_createdefault2() 7, 9, 134 ivadmin_context_createlocal() 136 ivadmin_context_delete() 17, 138 ivadmin_context_domainismanagement() 139 ivadmin_context_getaccexpdate() 140 ivadmin_context_getcodeset() 141 ivadmin_context_getdisabletimeint() 142 ivadmin_context_getdomainid() 143 ivadmin_context_getmaxlgnfails() 144 ivadmin_context_getmaxpwdage() 145 ivadmin_context_getmaxpwdrepchars() 146 ivadmin_context_getmgmtdomainid() 147 ivadmin_context_getmgmtsvrhost() 148 ivadmin_context_getmgmtsvrport() 149 ivadmin_context_getminpwdalphas() 150 ivadmin_context_getminpwdlen() 152 ivadmin_context_getminpwdnonalphas() 151 ivadmin_context_getpwdspaces() 153 ivadmin_context_gettodaccess() 154 ivadmin_context_getuserid() 155 ivadmin_context_getuserreg() 156 ivadmin_context_hasdelcred() 157 ivadmin_context_setaccexpdate() 158 ivadmin_context_setdelcred() 9, 159 ivadmin_context_setdisabletimeint() 160 ivadmin_context_setmaxlgnfails 161 ivadmin_context_setmaxpwdage() 162 ivadmin_context_setmaxpwdrepchars() 163 ivadmin_context_setminpwdalphas() 164 ivadmin_context_setminpwdlen() 166 ivadmin_context_setminpwdnonalphas() 165 ivadmin_context_settodaccess() 168 ivadmin_domain_delete() 170 ivadmin_domain_get() 171 ivadmin_domain_getdescription() 172 ivadmin_domain_getid() 173 ivadmin_domain_list() 174 ivadmin_domain_setdescription() 175 ivadmin_donain_create() 169 ivadmin_free() 16, 176 ivadmin_group_addmembers() 177 ivadmin_group_create2() 178 ivadmin_group_delete2() 180 ivadmin_group_get() 181 ivadmin_group_getbydn() 182 ivadmin_group_getcn() 183 ivadmin_group_getdescription() 184 ivadmin_group_getdn 185 ivadmin_group_getid() 186 ivadmin_group_getmembers() 187 ivadmin_group_import2() 188 ivadmin_group_list() 189 ivadmin_group_listbydn() 191 ivadmin_group_removemembers() 193 ivadmin_group_setdescription() 194 ivadmin_message_getcount() 16 ivadmin_objectspace_create() 195

384

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

functions (continued) ivadmin_objectspace_delete() 197 ivadmin_objectspace_list() 198 ivadmin_pop_attach() 199 ivadmin_pop_attrdelkey() 200 ivadmin_pop_attrdelval() 201 ivadmin_pop_attrget() 202 ivadmin_pop_attrlist() 203 ivadmin_pop_attrput() 204 ivadmin_pop_create() 205 ivadmin_pop_delete() 207 ivadmin_pop_detach() 208 ivadmin_pop_find() 209 ivadmin_pop_get() 210 ivadmin_pop_getanyothernw() 211 ivadmin_pop_getauditlevel() 212 ivadmin_pop_getdescription() 213 ivadmin_pop_getid() 214 ivadmin_pop_getipauth() 215 ivadmin_pop_getqop() 216 ivadmin_pop_gettod() 217 ivadmin_pop_getwarnmode() 219 ivadmin_pop_list() 220 ivadmin_pop_removeipauth() 221 ivadmin_pop_setanyothernw_forbidden() 223 ivadmin_pop_setanyothernw() 36, 222 ivadmin_pop_setauditlevel() 224 ivadmin_pop_setdescription() 225 ivadmin_pop_setipauth_forbidden() 227 ivadmin_pop_setipauth() 36, 226 ivadmin_pop_setqop() 228 ivadmin_pop_settod() 229 ivadmin_pop_setwarnmode() 231 ivadmin_protobj_access() 232 ivadmin_protobj_attachacl() 234 ivadmin_protobj_attachauthzrule() 235 ivadmin_protobj_attrdelkey() 236 ivadmin_protobj_attrdelval() 237 ivadmin_protobj_attrget() 238 ivadmin_protobj_attrlist() 239 ivadmin_protobj_attrput() 240 ivadmin_protobj_create() 241 ivadmin_protobj_delete() 242 ivadmin_protobj_detachacl() 243 ivadmin_protobj_detachauthzrule() 244 ivadmin_protobj_exists() 245 ivadmin_protobj_get3() 246 ivadmin_protobj_getaclid() 248 ivadmin_protobj_getauthzruleid() 249 ivadmin_protobj_getdesc() 250 ivadmin_protobj_geteffaclid() 251 ivadmin_protobj_geteffauthzruleid() 252 ivadmin_protobj_geteffpopid() 253 ivadmin_protobj_getid() 254 ivadmin_protobj_getpolicyattachable() 255 ivadmin_protobj_getpopid() 256 ivadmin_protobj_gettype() 257 ivadmin_protobj_list3() 258 ivadmin_protobj_listbyacl() 260 ivadmin_protobj_listbyauthzrule() 261 ivadmin_protobj_multiaccess() 262 ivadmin_protobj_setdesc() 264 ivadmin_protobj_setpolicyattachable() 265 ivadmin_protobj_settype() 266 ivadmin_response_getcode() 16, 267 ivadmin_response_getcount() 15, 16, 268 ivadmin_response_getmessage() 15, 269

functions (continued) ivadmin_response_getmodifier() 16, 270 ivadmin_response_getok() 15, 271 ivadmin_server_gettasklist() 272 ivadmin_server_performtask() 274 ivadmin_server_replicate() 276 ivadmin_ssocred_create() 277 ivadmin_ssocred_delete() 278 ivadmin_ssocred_get() 279 ivadmin_ssocred_getid() 280 ivadmin_ssocred_getssopassword() 281 ivadmin_ssocred_getssouser() 282 ivadmin_ssocred_gettype() 283 ivadmin_ssocred_getuser() 284 ivadmin_ssocred_list() 285 ivadmin_ssocred_set() 286 ivadmin_ssogroup_addres() 287 ivadmin_ssogroup_create() 288 ivadmin_ssogroup_delete() 289 ivadmin_ssogroup_get() 290 ivadmin_ssogroup_getdescription() 291 ivadmin_ssogroup_getid() 292 ivadmin_ssogroup_getresources() 293 ivadmin_ssogroup_list() 294 ivadmin_ssogroup_removeres() 295 ivadmin_ssoweb_create() 296 ivadmin_ssoweb_delete() 297 ivadmin_ssoweb_get() 298 ivadmin_ssoweb_getdescription() 299 ivadmin_ssoweb_getid() 300 ivadmin_ssoweb_list() 301 ivadmin_user_create3() 10, 19, 302 ivadmin_user_delete2() 19, 304 ivadmin_user_get() 305 ivadmin_user_getaccexpdate() 306 ivadmin_user_getaccountvalid() 307 ivadmin_user_getbydn() 308 ivadmin_user_getcn() 309 ivadmin_user_getdescription() 310 ivadmin_user_getdisabletimeint() 311 ivadmin_user_getdn() 312 ivadmin_user_getid() 313 ivadmin_user_getmaxlgnfails() 314 ivadmin_user_getmaxpwdage() 315 ivadmin_user_getmaxpwdrepchars() 316 ivadmin_user_getmemberships() 317 ivadmin_user_getminpwdalphas() 318 ivadmin_user_getminpwdlen() 319 ivadmin_user_getminpwdnonalphas() 320 ivadmin_user_getpasswordvalid() 321 ivadmin_user_getpwdspaces() 322 ivadmin_user_getsn() 323 ivadmin_user_getssouser() 324 ivadmin_user_gettodaccess() 325 ivadmin_user_import2() 326 ivadmin_user_list() 14, 327 ivadmin_user_listbydn() 329 ivadmin_user_setaccexpdate() 11, 331 ivadmin_user_setaccountvalid() 332 ivadmin_user_setdescription() 333 ivadmin_user_setdisabletimeint() 334 ivadmin_user_setmaxlgnfails() 335 ivadmin_user_setmaxpwdage() 11, 336 ivadmin_user_setmaxpwdrepchars() 337 ivadmin_user_setminpwdalphas() 338 ivadmin_user_setminpwdlen() 339 ivadmin_user_setminpwdnonalphas() 340 Index

385

functions (continued) ivadmin_user_setpassword() 341 ivadmin_user_setpasswordvalid() 342 ivadmin_user_setpwdspaces() 343 ivadmin_user_setssouser() 344 ivadmin_user_settodaccess() 345 functions ivadmin_context_setpwdspaces() functions, deprecated ivadmin_cfg_addreplica() 347 ivadmin_cfg_chgdreplica() 347 ivadmin_cfg_configureserver() 347 ivadmin_cfg_configureserver2() 347 ivadmin_cfg_rmvdreplica() 347 ivadmin_cfg_setapplicationcert() 347 ivadmin_cfg_setkeyringpwd() 347 ivadmin_cfg_setlistening() 347 ivadmin_cfg_setport() 347 ivadmin_cfg_setssltmeout() 347 ivadmin_context_create2() 347 ivadmin_context_createdefault() 347 ivadmin_group_addmember() 347 ivadmin_group_create() 347 ivadmin_group_delete() 348 ivadmin_group_import() 348 ivadmin_group_removemember() 347 ivadmin_protobj_get() 348 ivadmin_protobj_get2() 347 ivadmin_protobj_getacl() 347 ivadmin_protobj_getauthzrule() 347 ivadmin_protobj_getpop() 347 ivadmin_protobj_list2() 348 ivadmin_protobj_setname() 347 ivadmin_user_create() 348 ivadmin_user_create2() 347 ivadmin_user_delete() 348 ivadmin_user_getauthmech () 347 ivadmin_user_import() 348 ivadmin_user_setauthmech () 347

167

G
getting administration tasks 49 getting objects 12 group attributes, table 24 group functions, table 23 groups access control list entry type 30 overview 19

I
IBM Global Security Toolkit 4 IBM SecureWay Directory client 4 initialization of response objects 14 installation 3 installation directories 3 installation requirements 3 ivadmin_accessOutdata_getAccessResult() function 54 ivadmin_accessOutdata_getPermInfo() function 55 ivadmin_accessOutdata_getResponseInfo() function 56 ivadmin_acl object 30 ivadmin_acl_attrdelkey() function 57 ivadmin_acl_attrdelval() function 58 ivadmin_acl_attrget() function 59 ivadmin_acl_attrlist() function 60 ivadmin_acl_attrput() function 61

ivadmin_acl_create() function 62 ivadmin_acl_delete() function 63 ivadmin_acl_get() function 64 ivadmin_acl_getanyother() function 65 ivadmin_acl_getdescription() function 66 ivadmin_acl_getgroup() function 67 ivadmin_acl_getid() function 68 ivadmin_acl_getunauth() function 69 ivadmin_acl_getuser() function 70 ivadmin_acl_list() function 71 ivadmin_acl_listgroups() function 72 ivadmin_acl_listusers() function 73 ivadmin_acl_removeanyother() function 74 ivadmin_acl_removegroup() function 75 ivadmin_acl_removeunauth() function 76 ivadmin_acl_removeuser() function 77 ivadmin_acl_setanyother() function 78 ivadmin_acl_setdescription() function 80 ivadmin_acl_setgroup() function 81 ivadmin_acl_setunauth() function 83 ivadmin_acl_setuser() function 85 ivadmin_action_create_in_group() function 89 ivadmin_action_create() function 87 ivadmin_action_delete_from_group() function 91 ivadmin_action_delete() function 90 ivadmin_action_getdescription() function 92 ivadmin_action_getid() function 93 ivadmin_action_gettype() function 94 ivadmin_action_group_create() function 95 ivadmin_action_group_delete() function 96 ivadmin_action_group_list() function 97 ivadmin_action_list_in_group() function 99 ivadmin_action_list() function 98 ivadmin_authzrule_create() function 100 ivadmin_authzrule_delete() function 101 ivadmin_authzrule_get() function 102 ivadmin_authzrule_getdescription() function 103 ivadmin_authzrule_getfailreason() function 104 ivadmin_authzrule_getid() function 105 ivadmin_authzrule_getruletext() function 106 ivadmin_authzrule_list() function 107 ivadmin_authzrule_setdescription() function 108 ivadmin_authzrule_setfailreason() function 109 ivadmin_authzrule_setruletext() function 110 ivadmin_cfg_addreplica() deprecated function 347 ivadmin_cfg_addreplica2() function 111 ivadmin_cfg_chgreplica() deprecated function 347 ivadmin_cfg_chgreplica2() function 112 ivadmin_cfg_configureserver() deprecated function 347 ivadmin_cfg_configureserver2() deprecated function 347 ivadmin_cfg_configureserver3() function 113 ivadmin_cfg_getvalue() function 115 ivadmin_cfg_removevalue() function 117 ivadmin_cfg_renewservercert() function 119 ivadmin_cfg_rmvreplica() deprecated function 347 ivadmin_cfg_rmvreplica2() function 120 ivadmin_cfg_setapplicationcert() deprecated function 347 ivadmin_cfg_setapplicationcert2() function 121 ivadmin_cfg_setkeyringpwd() deprecated function 347 ivadmin_cfg_setkeyringpwd2() function 122 ivadmin_cfg_setlistening() deprecated function 347 ivadmin_cfg_setlistening2() function 123 ivadmin_cfg_setport() deprecated function 347 ivadmin_cfg_setport2() function 124 ivadmin_cfg_setssltimeout() deprecated function 347 ivadmin_cfg_setssltimeout2() function 125 ivadmin_cfg_setsvrpwd() function 126

386

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

ivadmin_cfg_setvalue() function 128 ivadmin_cfg_unconfigureserver() function 130 ivadmin_context object 8, 17 ivadmin_context_cleardelcred() function 131 ivadmin_context_create() deprecated function 347 ivadmin_context_create2() deprecated function 347 ivadmin_context_create3() function 9, 132 ivadmin_context_createdefault() deprecated function 347 ivadmin_context_createdefault2() function 7, 9, 134 ivadmin_context_createlocal() function 136 ivadmin_context_delete() function 17, 138 ivadmin_context_domainismanagement() function 139 ivadmin_context_getaccexpdate() function 140 ivadmin_context_getcodeset() function 141 ivadmin_context_getdisabletimeint() function 142 ivadmin_context_getdomainid() function 143 ivadmin_context_getmaxlgnfails() function 144 ivadmin_context_getmaxpwdage() function 145 ivadmin_context_getmaxpwdrepchars() function 146 ivadmin_context_getmgmtdomainid() function 147 ivadmin_context_getmgmtsvrhost() function 148 ivadmin_context_getmgmtsvrport() function 149 ivadmin_context_getminpwdalphas() function 150 ivadmin_context_getminpwdlen() function 152 ivadmin_context_getminpwdnonalphas() function 151 ivadmin_context_getpwdspaces() function 153 ivadmin_context_gettodaccess() function 154 ivadmin_context_getuserid() function 155 ivadmin_context_getuserreg() function 156 ivadmin_context_hasdelcred() function 157 ivadmin_context_setaccexpdate() function 158 ivadmin_context_setdelcred() function 9, 159 ivadmin_context_setdisabletimeint() function 160 ivadmin_context_setmaxlgnfails() function 161 ivadmin_context_setmaxpwdage() function 11, 162 ivadmin_context_setmaxpwdrepchars() function 163 ivadmin_context_setminpwdalphas() function 164 ivadmin_context_setminpwdlen() function 166 ivadmin_context_setminpwdnonalphas() function 165 ivadmin_context_setpwdspaces() function 167 ivadmin_context_settodaccess() functions 168 ivadmin_domain_create() function 169 ivadmin_domain_delete() function 170 ivadmin_domain_get() function 171 ivadmin_domain_getdescription() function 172 ivadmin_domain_getid() function 173 ivadmin_domain_list() function 174 ivadmin_domain_setdescription() function 175 IVADMIN_FALSE 15 ivadmin_free() function 16, 176 ivadmin_group_addmember() deprecated function 347 ivadmin_group_addmembers() function 177 ivadmin_group_create() deprecated function 347 ivadmin_group_create2() function 178 ivadmin_group_delete() deprecated function 348 ivadmin_group_delete2() function 180 ivadmin_group_get() function 181 ivadmin_group_getbydn() function 182 ivadmin_group_getcn() function 183 ivadmin_group_getdescription() function 184 ivadmin_group_getdn() function 185 ivadmin_group_getid() function 186 ivadmin_group_getmembers() function 187 ivadmin_group_import() deprecated function 348 ivadmin_group_import2() function 188 ivadmin_group_list() function 189 ivadmin_group_listbydn() function 191

ivadmin_group_removemember() deprecated function 347 ivadmin_group_removemembers() function 193 ivadmin_group_setdescription() function 194 ivadmin_message_getcount() function 16 ivadmin_objectspace_create() function 195 ivadmin_objectspace_delete() function 197 ivadmin_objectspace_list() function 198 ivadmin_pop object 35 ivadmin_pop_attach() function 199 ivadmin_pop_attrdelkey() function 200 ivadmin_pop_attrdelval() function 201 ivadmin_pop_attrget() function 202 ivadmin_pop_attrlist() function 203 ivadmin_pop_attrput() function 204 ivadmin_pop_create() function 205 ivadmin_pop_delete() function 207 ivadmin_pop_detach() function 208 ivadmin_pop_find() function 209 ivadmin_pop_get() function 210 ivadmin_pop_getanyothernw() function 211 ivadmin_pop_getauditlevel() function 212 ivadmin_pop_getdescription() function 213 ivadmin_pop_getid() function 214 ivadmin_pop_getipauth() function 215 ivadmin_pop_getqop() function 216 ivadmin_pop_gettod() function 217 ivadmin_pop_getwarnmode() function 219 ivadmin_pop_list() function 220 ivadmin_pop_removeipauth() function 221 ivadmin_pop_setanyothernw_forbidden() function 223 ivadmin_pop_setanyothernw() function 36, 222 ivadmin_pop_setauditlevel() function 224 ivadmin_pop_setdescription function() 225 ivadmin_pop_setipauth_forbidden() function 227 ivadmin_pop_setipauth() function 36, 226 ivadmin_pop_setqop() function 228 ivadmin_pop_settod() function 229 ivadmin_pop_setwarnmode() function 231 ivadmin_protobj_access() function 232 ivadmin_protobj_attachacl() function 234 ivadmin_protobj_attachauthzrule() function 235 ivadmin_protobj_attrdelkey() function 236 ivadmin_protobj_attrdelval() function 237 ivadmin_protobj_attrget() function 238 ivadmin_protobj_attrlist() function 239 ivadmin_protobj_attrput() function 240 ivadmin_protobj_create() function 241 ivadmin_protobj_delete() function 242 ivadmin_protobj_detachacl() function 243 ivadmin_protobj_detachauthzrule() function 244 ivadmin_protobj_exists() function 245 ivadmin_protobj_get() deprecated function 348 ivadmin_protobj_get2() deprecated function 347 ivadmin_protobj_get3() function 246 ivadmin_protobj_getacl() deprecated function 347 ivadmin_protobj_getaclid() function 248 ivadmin_protobj_getauthzrule() deprecated function 347 ivadmin_protobj_getauthzruleid() function 249 ivadmin_protobj_getdesc() function 250 ivadmin_protobj_geteffaclid() function 251 ivadmin_protobj_geteffauthzruleid() function 252 ivadmin_protobj_geteffpopid() function 253 ivadmin_protobj_getid() function 254 ivadmin_protobj_getpolicyattachable() function 255 ivadmin_protobj_getpop() deprecated function 347 ivadmin_protobj_getpopid() function 256 ivadmin_protobj_gettype() function 257 Index

387

ivadmin_protobj_list2() deprecated function 348 ivadmin_protobj_list3() function 258 ivadmin_protobj_listbyacl() function 260 ivadmin_protobj_listbyauthzrule() function 261 ivadmin_protobj_multiaccess() function 262 ivadmin_protobj_setdesc() function 264 ivadmin_protobj_setname() deprecated function 347 ivadmin_protobj_setpolicyattachable() function 265 ivadmin_protobj_settype() function 266 ivadmin_response object 9, 10, 14, 17 IVADMIN_RESPONSE_ERROR 16 ivadmin_response_getcode() function 16, 267 ivadmin_response_getcount() function 15, 16, 268 ivadmin_response_getmessage() function 15, 269 ivadmin_response_getmodifier() function 16, 270 ivadmin_response_getok() function 15, 271 IVADMIN_RESPONSE_INFO 16 IVADMIN_RESPONSE_WARNING 16 ivadmin_server_gettasklist() function 272 ivadmin_server_performtask() function 274 ivadmin_server_replicate() function 276 ivadmin_ssocred_create() function 277 ivadmin_ssocred_delete() function 278 ivadmin_ssocred_get() function 279 ivadmin_ssocred_getid() function 280 ivadmin_ssocred_getssopassword() function 281 ivadmin_ssocred_getssouser() function 282 ivadmin_ssocred_gettype() function 283 ivadmin_ssocred_getuser() function 284 ivadmin_ssocred_list() function 285 ivadmin_ssocred_set() function 286 ivadmin_ssogroup_addres() function 287 ivadmin_ssogroup_create() function 288 ivadmin_ssogroup_delete() function 289 ivadmin_ssogroup_get() function 290 ivadmin_ssogroup_getdescription() function 291 ivadmin_ssogroup_getid() function 292 ivadmin_ssogroup_getresources() function 293 ivadmin_ssogroup_list() function 294 ivadmin_ssogroup_removeres() function 295 ivadmin_ssoweb_create() function 296 ivadmin_ssoweb_delete() function 297 ivadmin_ssoweb_get() function 298 ivadmin_ssoweb_getdescription() function 299 ivadmin_ssoweb_getid() function 300 ivadmin_ssoweb_list() function 301 IVADMIN_TRUE 15 ivadmin_user_create() deprecated function 348 ivadmin_user_create2() deprecated function 347 ivadmin_user_create3() function 10, 19, 302 ivadmin_user_delete() deprecated function 348 ivadmin_user_delete2() function 19, 304 ivadmin_user_get() function 305 ivadmin_user_getaccexpdate() function 306 ivadmin_user_getaccountvalid() function 307 ivadmin_user_getauthmech () deprecated function 347 ivadmin_user_getbydn() function 308 ivadmin_user_getcn() function 309 ivadmin_user_getdescription() function 310 ivadmin_user_getdisabletimeint() function 311 ivadmin_user_getdn() function 312 ivadmin_user_getid() function 313 ivadmin_user_getmaxlgnfails() function 314 ivadmin_user_getmaxpwdage() function 315 ivadmin_user_getmaxpwdrepchars() function 316 ivadmin_user_getmemberships() function 317 ivadmin_user_getminpwdalphas() function 318

ivadmin_user_getminpwdlen() function 319 ivadmin_user_getminpwdnonalphas() function 320 ivadmin_user_getpasswordvalid() function 321 ivadmin_user_getpwdspaces() function 322 ivadmin_user_getsn() function 323 ivadmin_user_getssouser() function 324 ivadmin_user_gettodaccess() function 325 ivadmin_user_import() deprecated function 348 ivadmin_user_import2() function 326 ivadmin_user_list() function 14, 327 ivadmin_user_listbydn() function 329 ivadmin_user_setaccexpdate() function 11, 331 ivadmin_user_setaccountvalid() function 332 ivadmin_user_setauthmech () deprecated function 347 ivadmin_user_setdescription() function 333 ivadmin_user_setdisabletimeint() function 334 ivadmin_user_setmaxlgnfails() function 335 ivadmin_user_setmaxpwdage() function 336 ivadmin_user_setmaxpwdrepchars() function 337 ivadmin_user_setminpwdalphas() function 338 ivadmin_user_setminpwdlen() function 339 ivadmin_user_setminpwdnonalphas() function 340 ivadmin_user_setpassword() function 341 ivadmin_user_setpasswordvalid() function 342 ivadmin_user_setpwdspaces() function 343 ivadmin_user_setssouser() function 344 ivadmin_user_settodaccess() function 345

L
LDAP users, creating 10 libraries, linking 4 libraries, shared 2 linking libraries 4 listing object information 13

M
management domain 45 memory, freeing 16 modifying values for objects 11

N
notification wait time 50

O
object information, listing 13 object values, reading 12 objects creating 10 getting 12 initialization of response objects ivadmin_acl 30 ivadmin_context 8, 17 ivadmin_pop 35 ivadmin_response 9, 10, 14, 17 modifying values 11 PDProtObject 26 PDProtObjectSpace 25 setting values 11

14

388

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

P
password functions, table 22, 23 passwords 22 pdadmin command line utility 2 performing administration tasks 49 Privilege Attribute Certificate data, creating 9 protected object attributes 27 protected object functions, table 26, 27 protected object policies 35 administering 35 defined 25 protected object policy (POP) 25 protected object policy extended attributes 37 protected object policy extended attributes, table protected object policy objects 35 protected object policy objects, table 35, 36 protected object policy settings 36 protected object policy settings, table 37 protected object space functions, table 26 protected object spaces 25 protected objects 25, 26

U
unauthenticated 30 Unicode Transformation Format 8 8 user account functions, table 21, 22 user accounts 20 user credentials, delegating 9 user functions, table 20 user password functions, table 22, 23 user passwords 22 user registry 4 differences xix, 349 maximum values 350, 351 user registry users, creating 10 users 19, 30 users, creating for user registry 10 using the administration API 7 UTF-8 8

38

W
wait time 50 warning attribute 37

R
reading object values 12 registry, user 4 related publications xv replica databases, notification threads 50 replica databases, notifying of updates 49, 50 requirements, for installation 3 resource objects 26 response objects, initialization 14 returned error conditions 10 rsp 14

S
secure domain 3 Secure Sockets Layer (SSL) 1 security context, deleting 17 security contexts, establishing backward compatibility 9 delegating user credentials 9 examples ivadmin_context_createdefault2 9 overview 7 required input parameters 8 returned objects 8 secUser 19 servers and databases, table 51 set operations, example operations 11 setting object values 11 shared libraries 2 shutdown of the Administration API 16 software requirements 3 SSL 1 svrsslcfg command line utility 2

T
types, returned by get functions 12

Index

389

390

IBM Tivoli Access Manager for e-business: Administration C API Developer Reference

Printed in USA

SC32-1357-00