This section covers the following topics:
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.
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:
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.
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.
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.
To make use of USR1071N
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.
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. | |||
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.
To make use of USR2071N
Copy the subprogram USR2071N from library SYSEXT to the
library SYSTEM or to the steplib library or to any application in the
server environment.
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: |
|
user-id |
I | A32 | User ID. | |
password |
I | A128 | User ID's password.
Note: |
|
newpassw |
I | A128 | User ID's new password.
Note: |
|
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. | |
To make use of USR2072N
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.
Using a DEFINE DATA
statement, specify the following parameters:
| Parameter | I/O | Format | Description | |
|---|---|---|---|---|
password |
I | A128 | User ID's password.
Note: |
|
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.
To make use of USR4371N
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.
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. | |
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.
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.
To make use of USR9171N
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.
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 | ||||
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.
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.
To make use of USR2074N
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.
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. | |
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 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.
Proceed as described in the corresponding steps of the Natural for Mainframes installation documentation; see Installing Natural on z/OS.
DSNRLIThis step applies to Natural for Db2 users only.
ADALNKR instead of ADALNKRefer to Considerations for Mainframe Natural RPC Servers with Replicas in Starting a Natural RPC Server.
BROKER
instead of NATETB23See Provide Access to the EntireX Broker Stub on Mainframe in Setting Up a Natural RPC Environment.
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.
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.
(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.
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'
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
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:
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.
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.
Turn on the Natural logon option according to your application environment.
Set the RPC user ID and the RPC password to the SAF user ID and SAF password according to your application environment.
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:
A Natural security logon is performed for the Natural RPC user ID without password or password phrase check.
All work files with a DDNAME that does not
start with CM are opened with the Natural RPC user ID.
All Adabas databases are opened with the Natural RPC user ID (applies to Adabas external security only).
If an ETID is specified in the NSC user
profile, this ETID is used in the Adabas open request.
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:
All work files with a DDNAME that does not
start with CM are closed.
All Adabas databases are closed.
The following topics are covered below:
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.
Proceed as described in the corresponding steps of the Natural for Mainframes installation documentation; see Installing the Natural CICS Interface on z/OS.
For further information, refer to the relevant Adabas documentation (applies to Adabas external security users only).
CICSETB
instead of NATETB23See Providing Access to the EntireX Broker Stub on Mainframe in Setting Up a Natural RPC Environment.
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.
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.
XUSER=YESIf 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.
PROGRAM entry for the
RPC server front-end
Refer to the corresponding step in Installing the Natural CICS Interface on z/OS.
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.
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.
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.)
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
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:
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.
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.
Turn on the Natural logon option according to your application environment.
Set the RPC user ID and the RPC password according to your application environment.
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:
A Natural security logon is performed for the Natural RPC user ID without password or password phrase check.
All CICS resources are accessed with the Natural RPC user ID.
All Adabas databases are opened with the Natural RPC user ID (applies to Adabas external security only).
If an ETID is specified in the NSC user
profile, this ETID is used in the Adabas open request.
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:
All CICS resources are closed.
All Adabas databases are closed.
The connection to Db2 is closed (applies to Natural for Db2 users only).
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.
Natural RPC fully supports EntireX Security on the client side and on the server 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.
To make use of USR2071N
Copy the subprogram USR2071N from library
SYSEXT to the library SYSTEM or to the steplib
library or to any application in the server environment.
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: |
|
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. | |
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 or not.
LOGON |
An EntireX Broker With Notes:
|
LOGOFF |
An EntireX Broker LOGOFF function is
executed to the broker-id named.
|
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.
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.
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.
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.
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.
To make use of USR2072N
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.
Using a DEFINE
DATA statement, specify the following parameter:
| Parameter | I/O | Format | Description |
|---|---|---|---|
password |
I | A32 | User ID's password. |
In the calling program on the client side, specify the following statement:
CALLNAT 'USR2072' password
See also the
Syntax
Description of the CALLNAT statement.
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])
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:
Specify SRVUSER='*TRUSTED' in the startup of the
Natural RPC server.
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.