IBM Platform Symphony 7.1 Interim Fix Readme File

Abstract

Some APIs in EGO 1.2.3 is not supported in EGO 3.1. Platform Symphony 7.1 uses EGO 3.1.

 

Description

Some APIs in EGO 1.2.3 are not supported in EGO 3.1. This document outlines how to use the new header files from EGO 3.1 to replace the APIs from EGO 1.2.3 so that you can use the APIs with Platform Symphony 7.1.

Notes:

The use of RBAC (Role Based Access Control) features using EGO 3.1 API is not supported outside of what is contained in this document. For long term compatibility, RESTful APIs will be provided for better integration with Platform Symphony.  

Readme file for: IBM® Platform Symphony

Product/Component Release: 7.1

Update Name: Interim Fix 343141

Fix ID: sym-7.1-build343141-jpmc

Publication date: 18 May 2015

 

Contents:

1.     Download location

2.     Example API usage

3.   List of new APIs

4.   Copyright and trademark information 

1.   Download location

Download interim fix 343141 from the following location: http://www.ibm.com/eserver/support/fixes/.

 

2.   Example API usage

All the header files for EGO 3.1 APIs are in the package egoapi.tar, the sample codes are in cmd/egoconsole.c, the samples include:

       How to get roles of a user.

       How to get the service list.

     How to create a role that can create/modify/delete a user or assign/unassign roles to a user.

     How to create a user.

       How to assign a role to a user.

       How to un-assign a role from a user.

       How to delete a user.

 

To run the sample:

1: Decompress the package egoapi.tar.

2: Enter the cmd directory

2.1 update the EGO_TOP in Makefile to the directory that the Symphony cluster is installed.

2.2 Run "make", binary egocmd will be created.

3: Source the environment of the Symphony cluster, and then run command "egocmd" to test the sample.

 

3.   List of new APIs

int

ego_getrbacroles4users(ego_handle_t *handle,

      ego_rbac_user_t *user,

      ego_rbac_role_assignments_t *rolesbyusers,

      int indirectNeeded)

Description

Gets a list of roles for a user.

Parameters

handle[IN]: handle from the API vem_open()

user[IN]:

  user.username: The user name (for example, Admin)

  user.usertype: The user type. Set this to 0.

rolesbyusers[OUT]: The output for this call.

  rolesbyusers.rolesC: The number of roles.

  rolesbyusers.rolesV: The details of the roles.

indirectNeeded[IN]: Whether the system should list indirect context inherited from the parent. Use 1 for yes, and 0 for no. This is similar to the parameter -a for the egosh user roles4user command.

Returns

The number of roles for this user.

 

int

ego_getroleidbyname(ego_handle_t *handle,

      char *rolename,

      char **roleid)

Description

Gets the role ID by role name.

Parameters

handle[IN]: handle from the API vem_open()

rolename[IN]: The name of the role.

          For CLUSTER_ADMIN, the name is "Cluster Admin".

          For CONSUMER_ADMIN, the name is "Consumer Admin".

          For CONSUMER_USER, the name is "Consumer User".

roleid[OUT]: The role ID for the role.

Returns

0: successfully returned the role ID.

-1: failed to return the role ID.

 

int

ego_getusers4rbacroles(ego_handle_t *handle,

      char *role,

      ego_rbac_role_assignments_t *rolesbyusers,

      int indirectNeeded)

Description

Gets a list of users for a role.

Parameters

handle[IN]: handle from the API vem_open()

role[IN]: The role ID from ego_getroleidbyname.

rolesbyusers[OUT]: The output for the call.

  rolesbyusers.rolesC: The number of users

  rolesbyusers.rolesV: The details of the users.

 

indirectNeeded[IN]: Whether the system should list indirect context inherited from the parent. Use 1 for yes, and 0 for no. This is similar to the parameter -a for the egosh user users4role command.

Returns

The number of users for this role.

 

int

ego_adduserrole(ego_handle_t *handle,

      ego_rbac_role_assignments_t *addedroles,

      ego_rbac_update_error_t *updateerrors)

Description

Assigns a role to a user.

Parameters

handle[IN]: handle from the API vem_open()

addedroles[IN]:

  addedroles.rolesC:  The number of roles to be assigned to the user. Set this to 1.

  addedroles.rolesV[0].roleid: The role ID from ego_getroleidbyname.

  addedroles.rolesV[0].rolename: Not applicable. Leave this blank.

  addedroles.rolesV[0].username: The user name that will be assigned this role.

  addedroles.rolesV[0].usertype: The user type. Set this to 0.

  addedroles.rolesV[0].context:  The consumer name.

updateerrors[OUT]: The output of this call.

  updateerrors.updateerrorC: The number of errors.

  updateerrors.updateerrorV: The details of the errors.

Returns

0: successfully assigns the role to the user.

-1: failed to assign the role to the user.

 

int

ego_deleteuserrole(ego_handle_t *handle,

      ego_rbac_role_assignments_t *removedroles,

      ego_rbac_update_error_t *updateerrors)

Description

Unassign a role from a user.

Parameters

handle[IN]: handle from the API vem_open()

removedroles[IN]:

  removedroles.rolesC: The number of roles to be unassigned from the user. Set this to 1.

  removedroles.rolesV[0].roleid: The role ID from ego_getroleidbyname.

  removedroles.rolesV[0].rolename: Not applicable. Leave this blank.

  removedroles.rolesV[0].username: The user name that will be unassigned this role.

  removedroles.rolesV[0].usertype: The user type. Set this to 0.

  removedroles.rolesV[0].context: The consumer name.

updateerrors[OUT]: The output of this call.

  updateerrors.updateerrorC: The number of errors.

  updateerrors.updateerrorV: The details of the errors.

Returns

0: successfully unassigns the role from the user.

-1: failed to unassign the role from the user.

 

int

ego_updaterolepermission(ego_handle_t * handle,

              ego_rbac_role_permissions_t * addedPerms,

              ego_rbac_role_permissions_t * removedPerms,

              ego_rbac_update_error_t * updateerrors);

Description

Update multiple role permissions

Parameters

handle[IN]: handle from the API vem_open()

addedPerms[IN]:

    addedPerms.permsC: The number of permissions to be added. Set this to 1.

    addedPerms.permsV[0]->roleid: The role ID from ego_getroleidbyname.

addedPerms.permsV[0]->permlist: The permission list.

addedPerms.permsV[0]->roles4assignment: Not applicable. Leave this blank.

removedPerms[IN]:

    removedPerms.permsC: The number of permissions to be removed. Set this to 1.

    removedPerms.permsV[0]->roleid: The role ID from ego_getroleidbyname.

removedPerms.permsV[0]->permlist: The permission list.

removedPerms.permsV[0]->roles4assignment: Not applicable. Leave this blank.

updateerrors[OUT]: The output of this call.

  updateerrors.updateerrorC: The number of errors.

  updateerrors.updateerrorV: The details of the errors.

Returns

0: successfully to update the role.

-1: failed to update the role.

 

int

ego_roleadd(ego_handle_t *handle,

      ego_rbac_role_baseinfo_t *rolebaseinfo,

      ego_rbac_permlist_t *rolepermlist)

Description

Add a new role

Parameters

handle[IN]: handle from the API vem_open()

rolebaseinfo[IN]:

rolebaseinfo.roleid: Not applicable. Leave this blank.

rolebaseinfo.rolename: The name of the role.

rolebaseinfo.description: The description of the role.

rolebaseinfo.roles4assignment: Not applicable. Leave this blank.

rolepermlist[IN]:

    rolepermlist.permidsC: The number of permission ID.

    rolepermlist.permidsV: The permission ID list.

Returns

0: successfully to add the role.

-1: failed to add the role.

 

int

ego_rolemodify(ego_handle_t *handle,

      ego_rbac_role_baseinfo_t *rolebaseinfo,

      ego_rbac_permlist_t *rolepermlist)

Description

Modify an existing role

Parameters

handle[IN]: handle from the API vem_open()

rolebaseinfo[IN]:

rolebaseinfo.roleid: The role ID from ego_getroleidbyname.

rolebaseinfo.rolename: The name of the role.

rolebaseinfo.description: The description of the role.

rolebaseinfo.roles4assignment: Not applicable. Leave this blank.

rolepermlist[IN]:

    rolepermlist.permidsC: The number of permission ID.

    rolepermlist.permidsV: The permission ID list.

Returns

0: successfully to modify the role.

-1: failed to modify the role.

 

int

ego_roledel(ego_handle_t *handle,

      const char *rolename,

      int enforced)

Description

Delete an existing role.

Parameters

handle[IN]: handle from the API vem_open()

rolename[IN]: The role ID from ego_getroleidbyname.

enforced[IN]:

1: The role will be deleted no matter there is user assigned with it or not.

0: The role can only be deleted when there is no user assigned with it

Returns

0: successfully to delete the role.

-1: failed to delete the role.

 

int

esc_sec_queryservice (char *name,

esc_service_info_reply_t *reply,

esc_security_def_t *sec)

Description

Get service information.

Parameters

name[IN]: The specified service name for the service information. If it is NULL, the information of all the services will be returned.

reply[OUT]: The output for this call.

sec[IN]: The security information that used to get service information.

 sec.username: The user name.

 sec.password: The password.

 sec.credential: The credential.

Returns

0: successfully to get the service information.

-1: failed to get the service information.

  

4.   Copyright and trademark information

© Copyright IBM Corporation 2015

U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

IBM®, the IBM logo and ibm.com® are trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at "Copyright and trademark information" at www.ibm.com/legal/copytrade.shtml.