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:
Fieldname Constant | Format of Returned Data | Description
--- | --- | ---
VERSION | Binary | ACEE Version code
INSTALLATIONDATA | Character | Contents of the Installation Data field
USERDATA | Character | Contents of the user data field
USERID | Character | Contents of the ACEE Userid field
GROUP | Character | Contents of the ACEE Group Field
SPECIAL | Bit | Special Attribute
AUTOMATIC | Bit | Automatic Attribute
OPERATIONS | Bit | Operations Attribute
AUDITOR | Bit | Auditor Attribute
LOG | Bit | Logging on for most operations
PRIVILEGED | Bit | Started task with privileged flag
RACF | Bit | RACF defined user flag
ALTER | Bit | Alter authority flag
CONTROL | Bit | Control authority flag
UPDATE | Bit | Update authority flag
READ | Bit | Read authority flag
NONE | Bit | None authority flag
GROUPLISTCONTAINS | Bit | Group list contents flag
DATE | Date | RACINIT Date
STCNAME | Character | Started task name
TERMINAL | Character | Terminal ID
DEFINEUSERS | Bit | Authorized to define users
PROTECTDASD | Bit | Authorized to protect DASD
PROTECTTAPE | Bit | Authorized to protect tape
PROTECTTERMINALS | Bit | Authorized to protect Terminals
APPLICATIONLEVEL | Binary | Application Level
PORTOFENTRYLEVEL | Binary | Port of entry level
PORTOFENTRYDATA | Character | Port of entry data
CLASSAUTHORIZATIONS | Binary | Class authorizations
APPLICATION | Character | Application name
APPLICATIONDATA | Character | Application data
USERNAME | Character | User name field
SURROGATEUSERID | Character | Surrogate userid
GROUPLIST | Group List | A list of groups
### 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:
Name Constant | Returned Value
--- | ---
PRODUCT | Return the name of the security product. (e.g. RACF, ACF2, or "UNKNOWN SECURITY PRODUCT").
MODE | Returns the CA-ACF2 operating mode: QUIET LOG WARN ABORT OFF This value is only valid for systems running CA-ACF2.
RELEASE | Causes Shadow/REXX to return the release and version number of CA-ACF2, CA-TOP SECRET, or RACF. For RACF and CA-TOP SECRET systems, this is a three-character string of the form v.r where v is the version number and r is the release number.
### 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: The SWSECURE request is being made either by an /*ATH rule, or by a /*WWW rule which is defined in the Master WWW Ruleset. The WWWRUNAUTHFORMATS startup parameter is set to "ALL". The WWWRUNAUTHLOCATION startup parameter is set to "ANYWHERE". 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