Using Security

This section covers the following topics:

Using Natural RPC with Natural Security

Natural RPC also supports Natural Security in client/server environments, where security may be active on either (or both) sides.

For general information, refer to the Natural Security documentation.

For information on how to control the use of Natural RPC (Remote Procedure) calls in a client/server environment, see Protecting Natural RPC Servers and Services in the Natural Security documentation.

Client Side

The client must send logon data together with the RPC request. The logon data includes a user ID, password or password phrase, and a library.

  • User ID and password or password phrase are used to perform the authentication of the client on the Natural RPC server side.

  • The library is used to perform a Natural Security protected logon to the requested library.

The following applies to Natural RPC clients only. For EntireX RPC clients that access a Natural Security protected Natural RPC server, refer to the EntireX Developer’s Kit documentation.

To send logon data to the Natural RPC server, the Logon option must be used. See Operating a Natural RPC Environment, Using the Logon Option. The logon data parts are established as follows:

  1. The user ID and password or password phrase:

    If the client runs under Natural Security

    The user ID and password or password phrase from the Natural Security logon on the client are used and passed to the Natural RPC server.

    If you want to use a different user ID and/or password or password phrase for the Natural Security logon on the server side, you can use the application programming interface USR1071N (for passwords of up to 8 characters) or the application programming interface USR9171N (for password phrases of 9 to 128 characters).

    Note:
    You can disallow the use of USR1071N or USR9171N in the Natural RPC restrictions part of the Session Parameters restrictions of the Natural Security library profile.

    If the client does not run under Natural Security

    To specify the user ID and password or password phrase that are passed to the Natural RPC server, the client must call application programming interface USR1071N (for passwords of up to 8 characters) or the application programming interface USR9171N (for password phrases of 9 to 128 characters) before the first RPC request is sent.

  2. The library:

    By default, the name of the library to which the client is currently logged on is used. If you want to pass another library name to the Natural RPC server, you may use the application programming interface USR4008N.

If impersonation without password check is active for the Natural RPC server (field Impersonation described in the section Components of an RPC Server Profile in the Natural Security documentation is set to A), the client may optionally pass an ETID to the Natural RPC server. This ETID will be used by the Natural RPC server to access Adabas on behalf of the client. To specify an ETID on the Natural RPC client side, you may use the application programming interface USR4371N.

USR1071N

The application programming interface USR1071N is provided in the library SYSEXT. It is used to specify the user ID and password that are passed to the Natural RPC server.

Start of instruction setTo make use of USR1071N

  1. Copy the subprogram USR1071N and the program USR1071P from library SYSEXT to the library SYSTEM in the system file FNAT in the server environment. For more information, see Using a Natural API in the SYSEXT Utility documentation.

  2. Using a DEFINE DATA statement, specify the following parameters:

    Parameter I/O Format Description
    USERID I A08 User ID to be used.
    PASSWORD I A08 Password to validate the user ID. This password is not validated on the client side.
    MIXEDCASE I A01 Mixed case option for password (optional).
    Y Allow mixed case password.
    N Convert passwords to upper case.

  3. In the calling program on the client side, specify the following statement:

    FETCH RETURN 'USR1071P' USERID PASSWORD [MIXEDCASE]

Alternatively, you can invoke USR1071P from the command line, and enter the user ID and password in the displayed window.

For more information, see the USR1071T text object in the system library SYSEXT.

Note:
Two samples are provided to call USR1071N: USR1071P, which is passing just user ID and password, and USR1071X (extended version), which in addition enables the user to set/retrieve various data.

USR2071N

Start of instruction setTo make use of USR2071N

  1. Copy the subprogram USR2071N from library SYSEXT to the library SYSTEM or to the steplib library or to any application in the server environment.

  2. Using a DEFINE DATA statement, specify the following parameters:

    Parameter I/O Format Description
    function I A08 Function code; possible values are:
    LOGON Logon to EntireX Broker.
    LOGOFF Logoff from EntireX Broker.
    broker-id I A192 Broker ID.

    Note:
    For compatibility reasons broker-id is defined with BY VALUE RESULT to support existing callers which pass an A8 or A32 field for the broker-id. The sample USR2071P provided in the library SYSEXT supports up to 32 characters.

    user-id I A32 User ID.
    password I A128 User ID's password.

    Note:
    For compatibility reasons password is defined with BY VALUE RESULT to support existing callers which pass an A32 field for the password. The sample USR2071P provided in the library SYSEXT supports up to 32 characters.

    newpassw I A128 User ID's new password.

    Note:
    For compatibility reasons newpassw is defined with BY VALUE RESULT to support existing callers which pass an A32 field for the newpassw. The sample USR2071P provided in the library SYSEXT supports up to 32 characters.

    rc O N04 Return value:
    0 OK
    1 invalid function code
    9999 EntireX Broker error (see message)
    message O A80 Message text returned by EntireX Broker.

USR2072N

Start of instruction setTo make use of USR2072N

  1. Copy the subprogram USR2072N and optionally program USR2072P from library SYSEXT to the library SYSTEM or to the steplib library or to any application in the server environment.

  2. Using a DEFINE DATA statement, specify the following parameters:

    Parameter I/O Format Description
    password I A128 User ID's password.

    Note:
    For compatibility reasons password is defined with BY VALUE RESULT to support existing callers which pass an A32 field for the password. The sample USR2072P provided in the library SYSEXT supports up to 32 characters.

USR4371N

The application programming interface USR4371N is provided in the library SYSEXT. It is used to specify the user ID and the ETID that are passed to the Natural RPC server.

Start of instruction setTo make use of USR4371N

  1. Copy the subprogram USR4371N and the program USR4371P from library SYSEXT to the library SYSTEM in the system file FNAT in the client environment. For more information, see Using a Natural API in the SYSEXT Utility documentation.

  2. Using a DEFINE DATA statement, specify the following parameters:

    Parameter I/O Format Description
    USERID I A08 User ID to be used.
    ETID I A08 ETID to be used.

  3. In the calling program on the client side, specify the following statement: 

    FETCH RETURN 'USR4371P' USERID ETID

Alternatively, you can invoke USR4371P from the command line, and enter the user ID and ETID in the displayed window.

For more information, see the text object USR4371T in the system library SYSEXT.

USR9171N

The application programming interface USR9171N is provided in the library SYSEXT. You can use it to specify the user ID and password phrase that are passed to the Natural RPC server.

Start of instruction setTo make use of USR9171N

  1. Copy the subprogram USR9171N and the program USR9171P from library SYSEXT to the library SYSTEM in the system file FNAT in the server environment. For more information, see Using a Natural API in the SYSEXT Utility documentation.

  2. Using a DEFINE DATA statement, specify the following parameters:

    Parameter I/O Format Description
    USERID I A32 User ID to be used.
    PASSWORD_PHRASE I A128 Case-sensitive password phrase to validate the user ID. This password phrase is not validated on the client side.
    MSG-TEXT O A79 Message text if PRC is not 0.
    PRC O N04 Return Value
    0 OK
    4 Internal Error
    2x Error in write handling
    3x Error in read handling
    9999 Invalid function code

  3. In the calling program on the client side, specify the following statement: 

    FETCH RETURN 'USR9171P' USERID PASSWORD_PHRASE MSG-TEXT PRC

You may alternatively invoke USR9171P from the command line and enter USERID and PASSWORD_PHRASE in the displayed window.

For a more detailed description, see the USR9171T text object in the system library SYSEXT.

Server Side

If Natural Security is installed on the server side and AUTO=ON is not specified, a Natural logon with user ID and password is required. It is recommended to use the Natural profile parameter STACK to pass the Natural system command LOGON. If AUTO=ON is specified the contents of *INIT-USER is used for an internal logon as usual.

To enforce the Logon option - that is, if you want a server to accept only requests from clients where the Logon option is set - set the keyword subparameter LOGONRQ of profile parameter RPC or parameter macro NTRPC to ON for the server. If the Logon option is not enforced, client request without logon data are accepted and executed in the server library or one of its steplibs. This allows you to provide public as well as secured services.

If the client passes logon data, the user ID and password from the client are verified against the corresponding user security profile on the server, and the logon to the requested library and the execution of the subprogram are performed according to the corresponding Natural Security library and user profile definitions on the server.

After the execution of the subprogram, the library used before the CALLNAT request is updated again on the server. In the case of a conversational RPC, the first CALLNAT request within the conversation sets the library ID on the server, and the CLOSE CONVERSATION statement resets the library ID on the server to the one used before the conversation was opened.

As part of the Natural RPC Restrictions in the library profiles of Natural Security, a server session option Close all databases is provided. It causes all databases which have been opened by remote subprograms contained in the library to be closed when a Natural logon/logoff to/from the libraries is performed. This means that each client uses its own database session.

If the Close all databases option is set, it is also possible to use a client specific ETID for all Adabas accesses which are executed by the server for this client. In this case, you should start the Natural RPC server with ETID=OFF and define an appropriate ETID in the user profile for each client that needs an ETID, for example, by specifying the ETID *USER. Please note that in this case two clients with the same name cannot issue two concurrent requests with Adabas calls.

Changing Password

It is possible to change the Natural Security password on the Natural RPC server via a Natural RPC service request. For this purpose, the application programming interface USR2074N is provided in the library SYSEXT.

Start of instruction setTo make use of USR2074N

  1. Copy the subprogram USR2074N, and optionally program USR2074P, from library SYSEXT to the library SYSTEM or to the steplib library or to any application in the server environment.

  2. Using a DEFINE DATA statement, specify the following parameters:

    Parameter I/O Format Description
    USERID I A08 User ID to be used.
    PASSWORD I A08 Password to validate the user ID. This password is not validated on the client side.
    NEWPASSWORD I A08 New password for the user ID. This password is not validated on the client side.
    NODE-NAME I A192 Name of the server node to be addressed.
    SERVER-NAME I A32 Name of the server to be addressed.
    PROTOCOL I A1 The transport protocol to address the server node. Valid value:
    B EntireX Broker.
    RC O I2 Return value:
    0 OK, MESSAGE contains a confirmation message.
    1 Error from RPC or server node, MESSAGE contains the error message.
    2 Error from the interface, MESSAGE contains the error message.
    3 Natural Security error, MESSAGE# contains the Natural error number and MESSAGE contains the corresponding message text.
    MESSAGE# O N4 Message number returned.
    MESSAGE O A80 Message text returned.

  3. In the calling program on the client side, specify the following statement:

    CALLNAT 'USR2074N' user-id password newpassword node-name server-name protocol rc message# message

You may alternatively use program USR2074P from library SYSEXT. Invoke USR2074P from the command line and enter the required data in the displayed window. In this case, all input except for the passwords are converted into upper case. For the passwords, you have the option to enter them in mixed case or not.

Impersonation (z/OS Batch Mode)

Purpose of Impersonation

Impersonation is an optional feature on the Natural RPC server side and is only available if the Natural RPC server runs under Natural Security. The impersonation feature is controlled by the Security Profiles for Natural RPC Servers. See the field Impersonation described under the heading Components of an RPC Server Profile in the section Protecting Natural RPC Servers and Services in the Natural Security documentation.

Impersonation in z/OS batch mode requires the use of the Natural RPC server front-end under z/OS and uses the SAF interface provided by z/OS.

If impersonation is active for the Natural RPC server, a client request that uses the Logon option is from the perspective of the operating system executed under the user ID that the client passes in the LOGON data (called Natural RPC user ID). Impersonation assumes that access to the operating system on which a Natural RPC server is running is controlled by an SAF-compliant external security system. User authentication (verification of the Natural RPC user ID and password or password phrase) is performed by this external security system. After successful authentication, the user's identity is established for the operating system (that is, an ACEE is created and linked to the TCB under which the current client request is executed). Any subsequent authorization checks will be performed based on this identity. This means that all accesses to resources that are controlled by the SAF compliant external security system are authorized for this identity. This applies especially to accesses to work files and to databases.

Impersonation does not turn off Natural Security. After successful authentication of the user's identity by the external security system, a Natural Security logon takes place using the same LOGON data but without password or password phrase verification.

To start a Natural RPC server using impersonation, see Starting a Natural Server Using the RPC Server Front-End in Starting a Natural RPC Server.

Note:
Without impersonation, a client request that uses the Logon option is from the perspective of the operating system executed with the user ID under which the Natural RPC server has been started.

Steps to Activate Impersonation (Server Side)

  1. Install RPC server front-end

    Proceed as described in the corresponding steps of the Natural for Mainframes installation documentation; see Installing Natural on z/OS.

  2. Link Natural z/OS batch nucleus with Db2 interface DSNRLI

    This step applies to Natural for Db2 users only.

  3. Use reentrant Adabas batch link routine ADALNKR instead of ADALNK

    Refer to Considerations for Mainframe Natural RPC Servers with Replicas in Starting a Natural RPC Server.

  4. Use EntireX Broker Stub BROKER instead of NATETB23

    See Provide Access to the EntireX Broker Stub on Mainframe in Setting Up a Natural RPC Environment.

  5. Define all required RPC server-specific Natural profile parameters

    Refer to Set the RPC Server-Specific Natural Parameters in Setting Up a Natural RPC Environment. The parameters are either defined in the Natural parameter module or in the CMPRMIN dataset. The parameter PARM= of the JCL EXEC statement is not used to provide Natural profile parameters.

  6. Define an RPC server profile in Natural Security

    Define an RPC server profile in Natural Security (NSC) for the server name that is used by the RPC server (SRVNAME) and activate the impersonation.

    Refer to Security Profiles for Natural RPC Servers in Protecting Natural RPC Servers and Services of the Natural Security documentation.

  7. Check SAF definitions

    (This step applies to Natural for Db2 users only.)

    If the SAF resource class DSNR is active, you must check whether you need the following SAF definitions:

    RDEFINE DSNR (subsys.RRSAF) OWNER(DB2owner)

    PERMIT subsys.RRSAF CLASS(DSNR) ID(DB2group) ACCESS(READ)

    where subsys is your Db2 subsystem ID.

    Each user who wants to access Db2 must be a member of group DB2group.

    For further information, refer to the relevant Db2 documentation of IBM.

  8. Create user exit NATRPC02

    (This step applies to Natural for Db2 users only.)

    Create the Natural RPC user exit NATRPC02 with a call to NATPLAN to set the required Db2 plan.

    Make sure that you use a NATPLAN of your current Natural for Db2 version.

    Sample NATRPC02: 

    DEFINE DATA PARAMETER
  1 SUBPROGRAM (A8) BY VALUE END-DEFINE
FETCH RETURN 'NATPLAN' 'planname'

  9. Start Natural RPC server front-end

    Start the Natural RPC server front-end.

    Refer to Starting a Natural RPC Server Using the RPC Server Front-End in Starting a Natural RPC Server.

    Make sure you have added all required load libraries to your STEPLIB concatenation. You will especially need the following:

    • Natural load library

    • EntireX load library

    • Adabas load library (if you use the Adabas link routine ADAUSER)

    • Db2 load library (if you want to access Db2)

    The impersonation is successfully activated if you see the following messages:

    • In the job log:

      RPC0010 Authorized environment for impersonation established

    • In the RPC trace file:

      M *** Server is running under NSC with impersonation

Steps to Use Impersonation (Client Side)

The client must send logon data together with the RPC request as it is already done for a standard Natural Security (NSC) protected Natural RPC server. In contrast to a standard Natural RPC server, the user ID must also be a valid SAF user ID and the password or password phrase must be the corresponding SAF password or password phrase. User ID and password or password phrase are validated by the Natural RPC server against the external security system on the z/OS system under which the server is executing. After successful authentication of the client’s identity by the external security system, the user ID is validated by NSC according to the defined rules. The password or password phrase is ignored. Therefore, it is not required to set the NSC password to your SAF password.

When the field Impersonation described in the section Components of an RPC Server Profile in the Natural Security documentation is set to A, no password or password phrase is used to authenticate the client against the external security system. This setting may be appropriate if the client has already been authenticated by the EntireX Broker.

Depending on the kind of client, the logon data are set differently:

Natural Clients

  1. Turn on the logon option in the Service Directory Maintenance function or in the keyword subparameter DFS of profile parameter RPC or parameter macro NTRPC.

    Alternatively, you can use the USR2007N to turn it on.

    Refer to Using the Logon Option in Operating a Natural RPC Environment.

  2. Set the SAF user ID and the SAF password or password phrase, using the application programming interface USR1071N for password or the application programming interface USR9171N for password phrase.

    If your client runs under Natural Security (NSC) and the user ID and password of NSC are identical to the SAF user ID and the SAF password, then USR1071N is not required.

EntireX RPC Clients

  1. Turn on the Natural logon option according to your application environment.

  2. Set the RPC user ID and the RPC password to the SAF user ID and SAF password according to your application environment.

Rules for Impersonation

  • Impersonation takes place at the start of each non-conversational CALLNAT and at the start of each conversation.

  • The authentication of the Natural RPC user ID and password or password phrase is performed by the external security system. The password on the FSEC system file is not used.

  • After successful authentication, the Natural RPC user ID is established for the operating system (user is impersonated).

  • After successful impersonation:

    1. A Natural security logon is performed for the Natural RPC user ID without password or password phrase check.

    2. All work files with a DDNAME that does not start with CM are opened with the Natural RPC user ID.

    3. All Adabas databases are opened with the Natural RPC user ID (applies to Adabas external security only).

    4. If an ETID is specified in the NSC user profile, this ETID is used in the Adabas open request.

    5. The Db2 connection is opened with the Natural RPC user ID (applies to Natural for Db2 users only).

  • At the end of each non-conversational CALLNAT and at the end of each conversation, the Natural RPC user ID is logged off from the operating system.

  • After log off:

    1. All work files with a DDNAME that does not start with CM are closed.

    2. All Adabas databases are closed.

Impersonation (CICS)

The following topics are covered below:

Purpose of Impersonation

Impersonation is an optional feature on the Natural RPC server side and is only available if the Natural RPC server runs under Natural Security. The impersonation feature is controlled by the Security Profiles for Natural RPC Servers. See the field Impersonation described under the heading Components of an RPC Server Profile in the section Protecting Natural RPC Servers and Services in the Natural Security documentation.

Impersonation under CICS requires the use of the Natural RPC server front-end under CICS and uses the interface provided by CICS.

If impersonation is active for the Natural RPC server, a client request that uses the Logon Option is from the perspective of CICS executed under the user ID that the client passes in the LOGON data (called Natural RPC user ID). Impersonation under CICS uses the CICS option to start a CICS task under a given user ID. After a client request has arrived the Natural RPC server front-end starts a new CICS task using the USERID() option of the EXEC CICS START TRANSID() command, where USERID is the Natural RPC user ID. The User authentication (verification of the Natural RPC user ID and password or password phrase) is performed by CICS, typically by using the underlying external security system. After successful authentication, the user's identity is established for the CICS task. Any subsequent authorization checks will be performed based on this identity. This means that all accesses to resources that are controlled by CICS are authorized for this identity. This applies especially to accesses to CICS resources and to databases. By default, the newly established CICS task runs with the same CICS transaction ID with which you started the RPC server front-end. You can use the RPCSFEX1 user exit to set a request-specific transaction ID.

Impersonation does not turn off Natural Security. After successful authentication of the user's identity by CICS, a Natural Security logon takes place using the same LOGON data without password or password phrase verification.

To start a Natural RPC server using impersonation, see Starting a Natural Server Using the RPC Server Front-End (CICS only) in Starting a Natural RPC Server.

Note:
Without impersonation, a client request that uses the Logon option is from the perspective of the operating system executed with the user ID with which the Natural RPC server has been started.

Steps to Activate Impersonation (Server Side)

  1. Install the RPC server front-end under CICS

    Proceed as described in the corresponding steps of the Natural for Mainframes installation documentation; see Installing the Natural CICS Interface on z/OS.

  2. Install the Adabas link routine for Adabas external security

    For further information, refer to the relevant Adabas documentation (applies to Adabas external security users only).

  3. Use EntireX Broker Stub CICSETB instead of NATETB23

    See Providing Access to the EntireX Broker Stub on Mainframe in Setting Up a Natural RPC Environment.

  4. Define all required RPC server-specific Natural profile parameters

    Refer to Set the RPC Server-Specific Natural Parameters in Setting Up a Natural RPC Environment.

    The parameters are either defined in the Natural parameter module or together with the transaction ID.

  5. Define an RPC Server Profile in Natural Security

    Define an RPC Server Profile in Natural Security (NSC) for the server name that is used by the RPC server (SRVNAME) and activate the impersonation.

    Refer toSecurity Profiles for Natural RPC Servers in Protecting Natural RPC Servers and Services of the Natural Security documentation.

  6. If CICS startup parameter XUSER=YES

    If the CICS startup parameter XUSER=YES is specified you must define surrogate users for each client user:

    RDEFINE SURROGATE userid1.DFHSTART UACC(NONE) OWNER(userid1) PERMIT userid1.DFHSTART CLASS(SURROGATE) ID(userid2) ACCESS(READ)

    where

    userid1 is the user ID of the client,

    userid2 is the user ID under which the Natural RPC server front-end is started.

    For further information, refer to the relevant CICS documentation of IBM.

  7. Define a CICS PROGRAM entry for the RPC server front-end

    Refer to the corresponding step in Installing the Natural CICS Interface on z/OS.

  8. Define a CICS TRANSACTION entry for the transaction ID that invokes the RPC server front-end.

    Refer to the corresponding step in Installing the Natural CICS Interface on z/OS.

  9. Define a DB2TRAN and DB2ENTRY entry

    (This step applies to Natural for Db2 users only.)

    Define a DB2TRAN and DB2ENTRY entry for the transaction ID that invokes the RPC server front-end.

  10. Start the Roll Server

    Start the Roll Server for the subsystem used by the Natural RPC server.

    (This step applies only if the NCMDIR macro parameter ROLLSRV is set to YES.)

  11. Start the Natural RPC server front-end under CICS

    Refer to Starting a Natural RPC Server Using the RPC Server Front-End (CICS only) in Starting a Natural RPC Server.

    The impersonation is successfully activated if you see the following message in the RPC trace file:

    M *** Server is running under NSC with impersonation

Steps to Use Impersonation (Client Side)

The client must send logon data together with the RPC request as it is already done for a standard Natural Security (NSC) protected Natural RPC server. In contrast to a standard Natural RPC server, the user ID must also be a valid CICS user ID and the password or password phrase must be the corresponding password or password phrase of the external security system. User ID and password or password phrase are validated by CICS against the external security system on the z/OS system under which CICS is executing. After successful authentication of the client’s identity by the external security system, the user ID is validated by Natural Security according to the defined rules. The password or password phrase is ignored. Therefore, it is not required to set the NSC password to your SAF password.

When the field Impersonation described in the section Components of an RPC Server Profile in the Natural Security documentation is set to A, no password or password phrase is used to validate the client against the external security system. This setting may be appropriate if the client has already been authenticated by the EntireX Broker.

Depending on the kind of client, the logon data are set differently:

Natural Clients

  1. Turn on the logon option

    Turn on the logon option in the Service Directory Maintenance function or in the keyword subparameter DFS of profile parameter RPC or parameter macro NTRPC.

    Alternatively, you can use the application programming interface USR2007N to turn it on.

    Refer to Using the Logon Option in Operating a Natural RPC Environment.

  2. Set user ID and password or password phrase

    Set the user ID and the password, using application programming interface USR1071P. To set the password phrase use application programming interface USR9171P.

    If your client runs under Natural Security (NSC) and the user ID and password of NSC are identical to the user ID and password on the server side, then USR1071P is not required.

EntireX RPC Clients

  1. Turn on the Natural logon option

    Turn on the Natural logon option according to your application environment.

  2. Set RPC user ID and password

    Set the RPC user ID and the RPC password according to your application environment.

Rules for Impersonation

  • Impersonation takes place at the start of each non-conversational CALLNAT and at the start of each conversation.

  • The optional RPCSFEX1 user exit is called to set a request-specific CICS transaction ID.

  • The authentication of the Natural RPC user ID and password or password phrase are performed by CICS. The password on the FSEC system file is not used.

  • After successful authentication, the Natural RPC user ID is established for CICS (user is impersonated).

  • After successful impersonation:

    1. A Natural security logon is performed for the Natural RPC user ID without password or password phrase check.

    2. All CICS resources are accessed with the Natural RPC user ID.

    3. All Adabas databases are opened with the Natural RPC user ID (applies to Adabas external security only).

    4. If an ETID is specified in the NSC user profile, this ETID is used in the Adabas open request.

    5. The Db2 connection is opened with the Natural RPC user ID (applies to Natural for Db2 users only).

  • At the end of each non-conversational CALLNAT and at the end of each conversation, the Natural RPC user ID is logged off from CICS.

  • After log off:

    1. All CICS resources are closed.

    2. All Adabas databases are closed.

    3. The connection to Db2 is closed (applies to Natural for Db2 users only).

RPCSFEX1 - User Exit for Impersonation under CICS

By default, the CICS transaction ID with which the impersonated RPC request is executed is the same as the CICS transaction ID used to start the RPC server front-end. You can set a request-specific transaction ID with the RPCSFEX1 user exit.

The RPCSFEX1 user exit is called when the logon data of a client is evaluated after an RPC request has been received. The logon data is then used to set the CICS transaction ID under which the impersonated RPC request executes.

You must link RPCSFEX1 to the RPC server front-end for CICS and call the user exit by using the following standard conventions:

RPCSFEX1 is called using standard conventions:

Register Contents
15 Entry address of NATSFEX1
14 Return address of Natural RPC server front-end
13 Address of a save area of 18 words
1 Address of a parameter list

The parameter list contains the following addresses:

Address Parameter I/O Natural Data Format/Length
1 CICS transaction ID I/O A04
2 EntireX user ID of client I A32
3 RPC user ID of client I A8
4 RPC password of client I A8
5 Name of the Natural library where to execute the RPC request on the Natural RPC server I A8
6 Name of the subprogram to be executed on the Natural RPC server I A8

You can only modify the CICS transaction ID with the user exit.

Using Natural RPC with EntireX Security

Natural RPC fully supports EntireX Security on the client side and on the server side.

EntireX Security on the Client Side

To logon to and logoff from the EntireX Broker, the Natural Application Programming Interface USR2071N is provided. To logon to EntireX Broker, you use the logon function of USR2071N and pass your user ID and password to the selected EntireX Broker. After a successful logon, the security token returned is saved by Natural and passed to the EntireX Broker on each subsequent call. The Logon option is fully transparent to the Natural application.

If EntireX Security is installed or if AUTOLOGON=NO is specified in the EntireX Broker attribute file, you must invoke USR2071N with the logon function before the very first remote CALLNAT execution.

You are recommended to invoke USR2071N with the logoff function as soon as you no longer intend to use a remote CALLNAT.

Start of instruction setTo make use of USR2071N

  1. Copy the subprogram USR2071N from library SYSEXT to the library SYSTEM or to the steplib library or to any application in the server environment.

  2. Using a DEFINE DATA statement, specify the following parameters:

    Parameter I/O Format Description
    function I A08

    Function code; possible values are:
    LOGON Logon to EntireX Broker
    LOGOFF  Logoff from EntireX Broker
    broker-id I A192 Broker ID.

    Note:
    For compatibility reasons broker-id is defined with BY VALUE RESULT to support existing callers which pass an A8 or A32 field for the broker-id. The sample USR2071P provided in the library SYSEXT supports up to 32 characters.

    user-id  I A32 User ID.
    password  I A32 User ID's password.
    newpassw  I A32 User ID's new password.
    rc      O N04

    Return value:
    0 OK
    1 invalid function code
    9999 EntireX Broker error (see message)
    message O A80 Message text returned by EntireX Broker.

  3. In the calling program on the client side, specify the following statement: 

    CALLNAT 'USR2071N' function broker-id user-id password newpassword rc message

    See also the Syntax Description of the CALLNAT statement.

You may alternatively invoke USR2071P from the command line and enter User ID and password in the displayed window. In this case, all input except for the passwords is converted into upper case. For the passwords, you have the option to enter them in mixed case. On Linux and Windows, you also have the option to enter the input parameters User ID and Broker ID in mixed case.

Functionality:

LOGON

An EntireX Broker LOGON function is executed to the named broker-id with the user-id and the password passed. After a successful LOGON call, the client can communicate with the EntireX Broker broker-id as usual.

With newpassw the client user can change her/his password via the EntireX Security features.

Notes:

  • If a successful logon has been performed, the user ID used in this LOGON will be passed to the named EntireX Broker on all subsequent remote procedure CALLNATs which are routed via this EntireX Broker.

    Without an explicit LOGON, the current contents of system variable *USER is used. The same applies if you have issued a LOGON to EntireX Broker 1, but your remote procedure CALLNAT is routed via EntireX Broker 2.

  • It is possible to concurrently log on to multiple EntireX Brokers. For each LOGON, a different user ID may be used.

  • The user ID used for the LOGON to the EntireX Broker may be different from the Natural user ID under which the client application runs.

  • An internal re-logon is done after an EntireX Broker timeout has occurred, if the original LOGON was done without a password (the password used in the LOGON is not saved). If no internal re-logon is possible after a timeout has occurred, the client has to explicitly reissue the LOGON.

  • At the end of the Natural session, an implicit LOGOFF is executed to all EntireX Brokers to which a logon has been performed.

LOGOFF An EntireX Broker LOGOFF function is executed to the broker-id named.

Special Considerations when the Client Request is Executed on the Server Side:

If an RPC client request is executed on the Natural RPC server side, a logon to the EntireX Broker, using the Application Programming Interface USR2071N, must also be performed before executing the RPC client request. The logon data of the Natural RPC server itself are not used for RPC client requests.

If the RPC client request is sent to the same EntireX Broker where the Natural RPC server is registered, the user ID must be different from the value of the keyword subparameter SRVUSER.

EntireX Security on the Server Side

If the value of keyword subparameter ACIVERS of profile parameter RPC or parameter macro NTRPC is 2 or higher, the server will log on to the EntireX Broker at the session start using the LOGON function. The user ID is the same as the user ID defined by SRVUSER.

If EntireX Security has been installed and if the EntireX trusted user ID feature is not available, there are two alternative ways to specify the required password:

These alternatives are described below.

Setting SRVUSER='*NSC'

If Natural Security is installed on the server, you can set the keyword subparameter SRVUSER of profile parameter RPC or parameter macro NTRPC to '*NSC' to specify that the current Natural Security user ID which was used when the server was started is used for the LOGON in conjunction with the accompanying Natural Security password. In this case, the value set for ACIVERS must be at least 4.

Note:

The password defined with the application programming interface USR2072N is ignored.

If Natural is running under Natural SAF Security, you must not set SRVUSER='*NSC' because the password defined in Natural Security is typically not a valid password for the logon to a secured EntireX Broker node. In this case, you must set SRVUSER='*USER' and define the password by using USR2072N.

Using Application Programming Interface USR2072N to Specify a Password

The Application Programming Interface USR2072N enables you to specify a password which is used for the LOGON in conjunction with keyword subparameter SRVUSER of profile parameter RPC or parameter macro NTRPC.

Start of instruction setTo make use of USR2072N

  1. Copy the subprogram USR2072N and optionally program USR2072P from library SYSEXT to the library SYSTEM or to the steplib library or to any application in the server environment.

  2. Using a DEFINE DATA statement, specify the following parameter:

    Parameter I/O Format Description
    password I A32 User ID's password.

  3. In the calling program on the client side, specify the following statement: 

    CALLNAT 'USR2072' password

    See also the Syntax Description of the CALLNAT statement.

  4. The calling program must be executed before the Natural RPC server has started its initialization. To accomplish this, put the name of the calling program on the Natural stack when starting the server. For this purpose, you may also use the program USR2072P from library SYSEXT. In this case, the password is converted into upper case by default. You have the option to enter the password in mixed case by passing the mixed case option Y as second parameter. 

    STACK=(LOGON server-library;USR2072P password [Y])

EntireX Security on the Server Side using Trusted User IDs (z/OS only)

The EntireX trusted user ID feature of EntireX Security is only available for transport method NET. If you want to use transport method TCP with trusted user IDs, you can use the RACF PassTicket functionality.

When using the RACF PassTicket functionality, the Natural RPC server generates a PassTicket for its own user ID and passes this ID and the generated PassTicket to the secured EntireX Broker for authentication, instead of providing a user ID and password in the logon to the secured EntireX Broker. The server's own user ID is taken from the ACEE of the Natural RPC server task. The PassTicket is generated for this user ID and the default batch application name MVSsmf-id by using the R_GenSec service routine IRRSGS00 (see also the z/OS Security Server RACF documentation from IBM).

The following steps are required to use trusted user IDs for transport method TCP:

  1. Specify SRVUSER='*TRUSTED' in the startup of the Natural RPC server.

  2. Define the following in RACF:

    SETROPTS CLASSACT(PTKTDATA) RACLIST(PTKTDATA)
RDEF PTKTDATA MVSsmf-id                    OWNER(#SECADM)  UACC(NONE)
     SSIGNON(KEYENCRYPTED(XXXXXXXXXXXXXXXX))                              
RDEF PTKTDATA IRRPTAUTH.MVSsmf-id.*        OWNER(#SECADM)  UACC(NONE)
PERMIT  IRRPTAUTH.MVSsmf-id.*   CL(PTKTDATA) ID(user-id) ACCESS(UPDATE)

    where:

    smf-id is the SMF system identifier of the MVS system in which the application runs. The SMF identifier is located in the SMFPRMxx member of SYS1.PARMLIB and is specified by the SID value.

    user-id is the user ID of the RPC server task or the user ID of the CICS task when running under CICS.