Understanding the SB+ Security API

Document options Document options requiring JavaScript are not displayed Rate this page Help us improve this content

Level: Intermediate

Ehab AbuShmais (ehaba@us.ibm.com), Advanced Technical Services Engineer, IBM

29 Mar 2007

In the past, accessing U2 SB+ for UniData and UniVerse security from outside of SB+ security screens was difficult. But now, you can use a new function, SH.SEC.API, to talk to SB+ security using routine calls when outside of SB+ security screens and reports. SB+ Release 5.4.0 makes it significantly easier for the system administrator to maintain SB+ security. This article teaches you how to implement this API and includes detailed programming examples.

Introduction

SB+, IBM® SystemBuilder, is a cross-platform, complete and powerful rapid application development and deployment environment that enables developers to focus on what they know best: their application, their business and their users. SB+ lets you quickly design IBM U2 data server structures and develop applications using a comprehensive developer interface. And, you there's no need to handwrite code.

SB+ provides a comprehensive security system. Within the SB+ security system, you can define users and groups of users within a hierarchy of parent-child relationships while logged onto SB+ but only using SB+ security screens. Any attempt to amend or create SB+ user or group security records outside of SB+ configuration screens results in security violation and security record corruption. However, SB+ Version 5.4.0 implements a security API for applications developed in SB+. This API integrates the settings in the application with SB+ user and group security, thus enabling users with appropriate permissions to update SB+ user and group security records from outside of SB+ configuration screens.

This article teaches you how to use the SH.SEC.API function to access, control and manage SB+ security when outside of SB+ security setup screens and reports using BASIC programs. As of version 5.4.1 of SB+, there are 12 available options that can be passed through PARAM (in other words, the subroutine call includes 12 options), as described in Table 1 below.

This capability does require:

1. The user initiating this program be in the SB+ ROOT group
2. A control flag be set to 1 for the subroutine to take the effect: SB.CONTROL <15,16>
   To set this flag, edit the DMCONT file and the SB.CONTROL record, or set the value equal to 1 through a BASIC program.
   
   Note: If this flag is not set the user subroutine will not be invoked.

Additional notes:

1. When executing this routine, an SB+ message is sent to all the other ROOT group members informing them of this. This message contains details about the subroutine: which user ran the security API, as well as the date and time it was run, and from what IP address.
2. Changes through this function are tracked by Sarbanes Oxley Reports (SOX).
3. To adhere to SB+ standard conventions, you should use uppercase user and group IDs when creating new ones. The developer is responsible for this validation as well as any information that goes into the record.
4. When running any SH.SEC.API parameters in a program to amend security, the API respects record locking. This means the record cannot be opened in SB+ security setup screens while the API program is trying to amend the same record. In this case, a record locked message is displayed.

Examples of the available API options

PARAM 1: Create a new user record in SB+ security

The following BASIC program uses the SH.SEC.API to create a new userid in SB+ based on a record from another file. The idea is to collect all the relevant information to create a new SB+ userid, using a customized interface, and store it on a file that this program can access. To help you build a customized interface, we provide you with the user record definition layout that SB+ expects. As a developer you are responsible for all field validation within your customized user and group security screen. For your convenience, the complete user definition layout is included at the end of this document. The requirements for creating a new user record using SH.SEC.API are provided in Table 2: User Definitions Record Layout.

The following attributes are the minimum requirements for creating a new user record: 1-5, 10, 15, 16, 21, 27 (including all multi-values), and 28

The following steps are necessary to successfully test the following example:

1. Create a file and call it SEC.FILE.
2. Copy DMSECURITY "~SB" for the TO: prompt type (SEC.FILE BASE) and press Enter.
3. Amend the record BASE by changing line 4, "password", to XXXX.
4. Run the program example below.

The program example will create a new user called "NEWUSER" based on the record BASE from the file SEC.FILE with password XXXX. The password will be changed and encrypted after first logon with this userid. The user will be prompted to change the password from XXXX to a new password.

				
$INCLUDE DMSKELCODE COMMON                                   
$INCLUDE DMSKELCODE STANDARD.EQU                             
OPEN "SEC.FILE" TO MYFILE ELSE STOP                                    
READ RECORD FROM MYFILE,"BASE" ELSE RECORD = ""                  
VALUE = "~NEWUSER"                                                
PARAM = 1                                                         
CALL SH.SEC.API

PARAM 2: Amend an existing user record in SB+ security

Note: The user record must exist and must have no null flags. Validation will fail and you will not be able to amend an existing user record if any of the user flags are not set.

				
$INCLUDE DMSKELCODE COMMON                        
$INCLUDE DMSKELCODE STANDARD.EQU                  
*                                                 
READ RECORD FROM F.PASS,"~NEWUSER" ELSE RECORD ="" 
RECORD<3> = "FIRSTNAME"                           
PARAM = 2                                         
CALL SH.SEC.API  

PARAM 3: Delete a user record from SB+ security

				
$INCLUDE DMSKELCODE COMMON        
$INCLUDE DMSKELCODE STANDARD.EQU  
VALUE = "~NEWUSER"                     
PARAM = 3                              
CALL SH.SEC.API                        

PARAM 11: Create a new SB+ group record

The minimum requirement for creating a new SB+ group is a record with the first three attributes from Table 3: Group Definitions Record Layout at the end of this document.

1. Type = "G"
2. Description
3. Parent Group Code

				
$INCLUDE DMSKELCODE COMMON                      
$INCLUDE DMSKELCODE STANDARD.EQU                
OPEN "SEC.FILE" TO MYFILE ELSE STOP             
READ RECORD FROM MYFILE,"BASEG" ELSE RECORD = ""
KEY = "NEWGROUP"                             
PARAM = 11                                     
CALL SH.SEC.API

PARAM 12: Amend an existing SB+ group record

				
$INCLUDE DMSKELCODE COMMON                        
$INCLUDE DMSKELCODE STANDARD.EQU
READ RECORD FROM F.PASS, "NEWGRP" ELSE RECORD = ""
RECORD<2> = "NEW DESCRIPTION"                     
PARAM = 12                                        
CALL SH.SEC.API                                   

PARAM 13: Delete an existing group record

				
$INCLUDE DMSKELCODE COMMON                          
$INCLUDE DMSKELCODE STANDARD.EQU                    
KEY = "NEWGRP"                                      
PARAM = 13                                          
CALL SH.SEC.API                                     

PARAM 15: Retrieve all restricted account access for a group

				
$INCLUDE DMSKELCODE COMMON                      
$INCLUDE DMSKELCODE STANDARD.EQU 
KEY = "ROOT"                 
PARAM = 15                   
CALL SH.SEC.API               
CRT "VALUE IS:  ":VALUE         

PARAM 16: Retrieve all unrestricted account access for a group

				
$INCLUDE DMSKELCODE COMMON                      
$INCLUDE DMSKELCODE STANDARD.EQU      
KEY = "ROOT"                 
PARAM = 16                  
CALL SH.SEC.API               
CRT "VALUE IS:  ":VALUE

PARAM 17: Retrieve allowed processes

				
$INCLUDE DMSKELCODE COMMON                      
$INCLUDE DMSKELCODE STANDARD.EQU    
KEY = "ROOT"                 
PARAM = 17                  
CALL SH.SEC.API               
CRT "VALUE IS:  ":VALUE

PARAM18: Retrieve disallowed processes

				
$INCLUDE DMSKELCODE COMMON                      
$INCLUDE DMSKELCODE STANDARD.EQU     
KEY = "ROOT"                 
PARAM = 18                    
CALL SH.SEC.API               
CRT "VALUE IS: ":VALUE

PARAM 19: Retrieve allowed menu options

				
$INCLUDE DMSKELCODE COMMON                      
$INCLUDE DMSKELCODE STANDARD.EQU      
KEY = "ROOT"                 
PARAM = 19                    
CALL SH.SEC.API               
CRT "VALUE IS: ":VALUE

PARAM 20: Retrieve disallowed menu options

				
$INCLUDE DMSKELCODE COMMON                      
$INCLUDE DMSKELCODE STANDARD.EQU    
KEY = "ROOT"                 
PARAM = 20                    
CALL SH.SEC.API               
CRT "VALUE IS: ":VALUE

Table 1. The 12 available options for SH.SEC.API

Conclusion

Hopefully, this article enables you to take full advantage of the new SB+ security API. It provided an explanation of the new feature, descriptions of the 12 options within the feature, and examples for each. You've gained knowledge about the background of the SB+ Security API and its power to give you, as a developer, the ability to customize your own security front end to communicate with SB+ security. Now, you know how to enable the SB+ Security API in your environment and how to deploy each of the security API's option.

Resources

• "Enable C++ applications for Web services using XML-RPC" (developerWorks, June 2006) is a step-by-step guide to exposing C++ methods as services.
  
  
• In the Architecture area on developerWorks, get the resources you need to advance your skills in the architecture arena.
  
  
• Browse the technology bookstore for books on these and other technical topics.
  
  
• developerWorks Information Management zone: Learn more about DB2. Find technical documentation, how-to articles, education, downloads, product information, and more.
  
  
• Stay current with developerWorks technical events and webcasts.
  
  

• Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
  
  
• Build your next development project with IBM trial software, available for download directly from developerWorks.

• Check out developerWorks blogs and get involved in the developerWorks community.
  
  

About the author

		Ehab AbuShmais is an SB+ software engineer with 11 years of experience in SB+ products support, engineering, and consulting. Ehab is the author of the book Building Applications Using IBM SB+ GUI. Ehab has a Bachelor of Science in Information Systems Engineering from Southern Polytechnic State University, and a Master of Science in Computer Information Systems from University of Denver.

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Share this.... Digg this story del.icio.us Slashdot it!

Back to top