Previous Topic
Table Of Contents
Parent Topic
Next Topic

SWSECURE Function

Related Topics

Web Server API Function Index

	May be used in Shadow/REXX
	May be used from Other REXX Interpreters
	High-Level Language entry point name is SWSCPSC

This function provides a set of subfunctions which perform six types of security authorization processing. 

The SWSECURE function has one required parameter, which must be followed with various other parameter arguments, depending on the requested function. 

The Operation Argument

The first argument of the SWSECURE function specifies the operation which is to be performed. The first argument can be one of the following values: 

D

Used to verify data set access privileges.

F

Used to fetch information about a logged-on user.

I

Used to return information about the security product installed on your MVS system.

R

Used to request generalized resource rule validation.

P

Enables you to validate a userid and password and/or set a new userid.

Verifying Data Set Access

You can verify that the current user has authorization to access a data set. The current user, for Web transactions is the Effective Userid.

Coding Data Set Access Requests

Issue the version of SWSECURE shown below to verify data set access privileges:

var = SWSECURE('D','dsname','accesstype','volser')

The arguments shown above, are coded as follows:

dsname

This argument specifies the dataset to be checked. The argument must be present or the function request is rejected.

 

accesstype

Use the accesstype argument to specify the type of data set access you want to check. If you omit the accesstype argument, Shadow/REXX uses a default of R (Read access).

The access type argument can be specified as one of:

• 'A' - Verify Alter access to a data set.
• 'C' - Verify Control access to a data set.
• 'R' - Verify Read access to a data set.
• 'U' - Verify Update access to a data set.

volser

The volser argument supplies the volser number to be validated. If you do not specify a volser, the argument is blank by default.

Return Values

The function returns the string "ALLOW" if the specified type of access to the data set is allowed.

If the logon is not processed successfully, Shadow/REXX returns the error  message generated by the MVS security subsystem, or if no message is returned by RACF, ACF/2, TopSecret, one of the following messages: 

      RESOURCE NOT PROTECTED BY RACF
      RESOURCE ACCESS DENIED BY RACF

Top

Fetching Logon ID Field Data

You can retrieve security subsystem information about the current user. The current user for Web transactions is the Effective Userid.

Note: The Shadow OS/390 Web Server uses the MVS SAF router interface for processing all security verification requests. This function will only operate correctly for field values which are available on the ACEE control block. Because many security products build only a skeletal ACEE block, some or all of the values may be unavailable if the underlying security subsystem product is other than RACF. 

Coding Fetch Data Requests

Issue the version of SWSECURE shown below to fetch field data from the current user's ACEE: 

var = SWSECURE('F','fieldname') 

The fieldname argument is required. One of the following character constants may be coded:

Return Values

• Shadow/REXX does the following conversions depending on field format: 
  • Binary fields are converted to signed decimal values without leading zeros or blanks. The number zero is returned as 0. 
  • Character fields are returned as is, possibly truncated to the Shadow/REXX defined maximum valid string length. 
  • Date fields are converted to the form yyyy/mm/dd with leading zeros kept (so that the result is always exactly ten non-blank characters). A zero date field is returned as the string ****/**/**. 
  • Bit fields are converted to a 0 (FALSE or off) or a 1 (TRUE or on). 
  • The group list field inquiry is handled separately. The function returns a integer count of the number of group entries found in the list. Each individual group name is returned as a separate entry in the external data queue.

Top

Requesting Security Product Information

To retrieve information about the security product itself (if any) on your system using this form of the SWSECURE function:  

Coding Information Requests

Issue the version of SWSECURE shown below to retrieve information about the security subsystem in use:

var = SWSECURE('I', 'name')

The name argument is required. Code one of the constant values shown below:

Return Values

The function returns a string with the requested information. If the information cannot be obtained, a NULL string is returned.

Generalized Resource Rule Checks

You can request that the Effective Userid for a Web transaction be validated against a security subsystem generalized resource rule.

Coding Generalized Resource Rule Checks

To request generalized resource rule validation, use this form of SWSECURE:

var = SWSECURE('R',class,resource,requestcode)

This function call verifies that the current user has access to a generalized resource. Code each argument as follows:

class

The generalized resource class name (type name for ACF2). SAF processing is used for all resource rule checks. If your security subsystem is ACF2, you must define the ACF2 resource type as a SAF class name.

 

resource

The 1-to-39 byte resource entity name.

 

requestcode

The requestcode argument specifies the type of access to be verified. If you omit this argument, Shadow/REXX uses the default value R (Read access). systems, the request code can be:

The request code can be specified as one of:

• 'A' - Verify Alter access to resource
• 'C' - Verify Control access to resource
• 'R' - Verify Read access to resource
• 'U' - Verify Update access to resource

Returned Values

For any of the three security products, if the specified access to the resource is allowed, Shadow/REXX returns the string ALLOW. 

If the logon is not processed successfully, Shadow/REXX returns the error  message generated by the MVS security subsystem, or if no message is returned by RACF, ACF/2, TopSecret, one of the following messages:  

  RESOURCE NOT PROTECTED BY RACF
  RESOURCE ACCESS DENIED BY RACF

Top

Validating a Userid and Password

This form of request causes the indicated Userid and password to be verified and logged onto the system. If the userid and password are valid an ACEE is created and made active for the current subtask. It remains active until explicitly reset, as described in the warning box. 

A logon processed using SWSECURE is handled internally in the same way as client logons performed using browser-prompted userid/password information (i.e.the encoded userid and password information passed for the 'Basic' authentication scheme via the HTTP 'Authorization:' request header.)  If any authorization data was passed by the browser it is 'hidden' when the SWSECURE request completes successfully.  If the browser information was previously used, during the course of the transaction, to perform a client logon, a logoff of that userid is performed internally and is not restored even if the SWSECURE request fails. 

You can perform a SWSECURE logon operation without supplying a password on the request if all the following conditions are met: 

1. The SWSECURE request is being made either by an /*ATH rule, or by a /*WWW rule which is defined in the Master WWW Ruleset.
2. The WWWRUNAUTHFORMATS startup parameter is set to "ALL".
3. The WWWRUNAUTHLOCATION startup parameter is set to "ANYWHERE".
4. You are not requesting that the password be changed (no new password is specified for the SWSECURE request.

NOTE: If the SWSECURE Password Validation request fails for any reason (i.e. userid unknown, password invalid, new password invalid, etc.) the server's Web Transaction Default Userid is always made active for the current task. This applies even if some other userid was active before the failing password validation request. When you successfully perform a logon operation from within a Web transaction task, the newly logged on userid is handled internally as any other client logon, with the following exception: the newly   logged-on userid remains permanently in effect for the Web transaction (even across all URL RESCAN operations) until explicitly reset. The userid is only deactivated when:  Another SWSECURE Password Validation request is performed, or A /*WWW rule is matched which has RUNAUTH(proxy-id) or RUNAUTH(NONE) coded on the rule header, or The Web transaction ends. Trace records generated following an SWSECURE logon operation reflect this userid persistence quality by including the text "Runauth(SWSECURE-Client-Logon)".

Coding Password Validation Requests

To validate a userid and password, use this form of the SWSECURE function:

var = SWSECURE('P','userid','password','newpassword')

The arguments shown above, are coded as follows:

userid

The userid to be validated

 

password

The password associated with the userid

 

newpassword

The new password value to be associated with the userid.

 

If you omit the newpassword argument, SWSECURE validates the userid and password. If you specify newpassword, SWSECURE changes the password.

Return Values

For all three security products, if the password was correct (and a new password was assigned if specified), the returned value is the string ALLOW. 

If the logon is not processed successfully, Shadow/REXX returns the error  message generated by the MVS security subsystem, or if no message is returned by RACF, ACF/2, TopSecret, one of the following messages: 

     INVALID SECURITY ENVIRONMENT
     USER PROFILE NOT DEFINED TO RACF
     PASSWORD IS NOT AUTHORIZED
     PASSWORD HAS EXPIRED
     USER NOT DEFINED TO THE GROUP
     REJECTED BY INSTALLATION EXIT
     ACCESS HAS BEEN REVOKED
     RACF IS NOT ACTIVE
     GROUP ACCESS HAS BEEN REVOKED
     NOT AUTHORIZED TO USE THIS TERMINAL
     INVALID DAY OR TIME OF DAY
     TERMINAL CANNOT BE USED
     NOT AUTHORIZED TO USE APPLICATION

Note: For CA-ACF2, invalid password attempt calls increase the invalid password violation counter for the specified user ID. 

Top