Security setup for the agent

APF Authorization

${AGENT_HLQ}.SKMGMOD0 contains modules linked with AC(1). Ensure that the agent fetches these modules from an APF authorized library. If a STEPLIB concatenation is used, then ensure that all STEPLIB data sets are on the APF list.

In addition, the module KMGPRACF needs to be added to the AUTHTSF table of SYS1.PARMLIB(IKJTSOxx).

For more details and examples, refer to the APF autorization chapter.

Dataset access

Check the DD-names in the ${AGENT_STC_NAME} procedure. The UKO Agent user ID ${AGENT_STC_USER} needs READ access to at least the following data sets:

• ${AGENT_RUNLIB} to access the load modules to run the agent
• ${TCPIP_HLQ}.SEZATCP for TCP/IP related functions
• ${ZOS_PARMLIB} to access the agent configuration parameters

If you specified additional datasets in the STEPLIB concatenation, the agent needs access to those as well.

Agent started task

You must define a STARTED class profile for the agent started task so that the agent is started as a z/OS started task.

Below, see an example of a RACF command setting up the ${AGENT_STC_USER} userid.

RDEFINE STARTED ${AGENT_STC_NAME}.* UACC(NONE) STDATA(USER(${AGENT_STC_USER}) +
    PRIVILEGED(NO) TRUSTED(NO) TRACE(YES))

SETROPTS RACLIST(STARTED) GENERIC(STARTED) REFRESH

APPL class access

When a client user logs on to the UKO agent, a check for the KMGPRACF resource is done in the APPL class. If KMGPRACF is defined in the APPL class, then the client user ID needs READ access.

/* Create and permit APPL class profile */
RDEFINE APPL KMGPRACF UACC(NONE)
PERMIT KMGPRACF CLASS(APPL) ID(${UKO_AGENT_CLIENT_USER}) ACC(READ)
SETROPTS RACLIST(APPL) REFRESH

FACILITY class access

The UKO Agent ${AGENT_STC_USER} ID must have READ access to KMG.EKMF.KMGPRACF in the FACILITY class to run an agent.

RDEFINE FACILITY KMG.EKMF.KMGPRACF UACC(NONE) OWNER(${AGENT_STC_GROUP})
PERMIT KMG.EKMF.KMGPRACF CLASS(FACILITY) ID(${AGENT_STC_GROUP}) ACCESS(READ)

SETROPTS RACLIST(FACILITY) REFRESH

An ${UKO_AGENT_CLIENT_USER} must be given permission to be used with a UKO agent running under the specific task user ID ${AGENT_STC_USER}. Therefore, every ${UKO_AGENT_CLIENT_USER} must have access to the KMG.EKMF.KMGPRACF.${AGENT_STC_USER} profile in the FACILITY class. While UKO only has one client user ID, there may be multiple client user IDs for the EKMF Workstation.

RDEFINE FACILITY KMG.EKMF.KMGPRACF.* UACC(NONE) OWNER(${AGENT_STC_GROUP})
RDEFINE FACILITY KMG.EKMF.KMGPRACF.${AGENT_STC_USER} UACC(NONE) OWNER(${AGENT_STC_GROUP})
PERMIT KMG.EKMF.KMGPRACF.${AGENT_STC_USER} CLASS(FACILITY) ID(${UKO_AGENT_CLIENT_GROUP}) ACCESS(READ)

SETROPTS RACLIST(FACILITY) REFRESH

SMF logging

Create a KMG.EKMF.SMF in the FACILITY class and grant access to the ${AGENT_STC_GROUP} for SMF logging. This is required even if SMF logging is not enabled. To enable SMF logging, the ${AGENT_STC_USER} needs READ access to KMG.EKMF.SMF and AUDIT(ALL(READ)) must be applied to the profile to force SMF records to be written by RACF, when a resource is accessed.

RDEFINE FACILITY KMG.EKMF.SMF UACC(NONE) AUDIT(ALL(READ))
PERMIT KMG.EKMF.SMF CLASS(FACILITY) ID(${AGENT_STC_GROUP}) ACCESS(READ)

SETROPTS RACLIST(FACILITY) REFRESH

XFACILIT class setup

The Agent requires access to KMG.WEBCLIENT.${UKO_AGENT_CLIENT_USER} in the XFACILIT class. The ${UKO_AGENT_CLIENT_USER} must match the value specified for the &WEBCLIENT parameter in the agent configuration options.

RDEFINE XFACILIT KMG.WEBCLIENT.${UKO_AGENT_CLIENT_USER}
PERMIT KMG.WEBCLIENT.${UKO_AGENT_CLIENT_USER} CLASS(XFACILIT) +
    ACC(READ) ID(${AGENT_STC_GROUP})
SETROPTS RACL(XFACILIT) REFRESH

If ICSF keystore policy checking is active and the CSF.PKDS.TOKEN.CHECK.DEFAULT.LABEL resource in XFACILIT class is defined, the CSF-PKDS-DEFAULT resource in CSFKEYS class must also be defined and the Agent's ${AGENT_STC_USER} needs access.

Additional security for EKMF Workstation access

The EKMF Workstation user ID must be part of the ${UKO_AGENT_CLIENT_GROUP}.

A ${UKO_AGENT_CLIENT_USER} can specify that the EKMF audit records are not written to SMF. This is only required for the initial setup. Both the ${AGENT_STC_USER} and ${UKO_AGENT_CLIENT_USER} need READ access to KMG.EKMF.AUDITOFF to allow the EKMF client to disable logging to SMF.

RDEFINE FACILITY KMG.EKMF.AUDITOFF UACC(NONE) 
PERMIT KMG.EKMF.AUDITOFF CLASS(FACILITY) ID(${AGENT_STC_GROUP}) ACCESS(READ)
PERMIT KMG.EKMF.AUDITOFF CLASS(FACILITY) ID(${UKO_AGENT_CLIENT_GROUP}) ACCESS(READ)
SETROPTS RACLIST(FACILITY) REFRESH

The configureSAFSecurityProfiles sub-step of the configureSecurity step of the agent example workflow will define those additioal profiles if you set the property WORKSTATION_ACCESS_REQUIRED=true.

In addition, the ${AGENT_STC_USER} needs access to ${DB_JCC_SSID}.BATCH in the DSNR class.

RDEFINE DSNR ${DB_JCC_SSID}.BATCH UACC(NONE)
PERMIT ${DB_JCC_SSID}.BATCH CLASS(DSNR) ACCESS(READ) ID(${AGENT_STC_USER})
SETROPTS RACLIST(DSNR) REFRESH

Access to ICSF functions in CSFSERV class

To be able to call ICSF, the UKO Agent ${AGENT_STC_USER} ID needs READ access to the following profiles in the CSFSERV class:

• CSFCRC
• CSFDEC
• CSFDSG
• CSFDSV
• CSFEDH
• CSFENC
• CSFIQF
• CSFKDMR
• CSFKDMW
• CSFKDSL
• CSFKIM
• CSFKRC2
• CSFKRD
• CSFKRR2
• CSFKRW
• CSFKRW2
• CSFKYT
• CSFKYT2
• CSFMGN
• CSFMVR
• CSFOWH
• CSFPKG
• CSFPKI
• CSFPKRC
• CSFPKRD
• CSFPKRR
• CSFPKRW
• CSFPKX
• CSFPRR2
• CSFRNGL
• CSFSAD
• CSFSAE
• CSFSYI
• CSFSYI2
• CSFSYX

It is recommended that you establish a generic profile to protect all the CSFSERV resources that are not in use. If this has not been done yet, you could use for example the following command

RDEFINE CSFSERV ** UACC(NONE)

After that, you need to grant access to each required ICSF resource. For example, to grant access to the CSFDSG service:

RDEFINE CSFSERV CSFDSG UACC(NONE)
PERMIT CSFDSG CLASS(CSFSERV) ACCESS(READ) ID(${AGENT_STC_GROUP})

This has to be repeated for all required ICSF resources. At the end, issue a REFRESH command:

SETROPTS RACLIST(CSFSERV) REFRESH

ACPs that need to be enabled for the Agent

In addition, the following Access Control Points (ACPs) must be enabled in the crypto adapter:

• 000E
• 000F
• 0010
• 0011
• 0012
• 001D
• 0021
• 0022
• 0023
• 003B, 003C ^[1]
• 00F4
• 00FD
• 0100
• 0101
• 0103
• 0104
• 0106
• 012A
• 012B
• 012E
• 012F
• 0144
• 01FF
• 0235
• 023D
• 0275
• 02B4
• 02B9
• 0311 ^[2]
• 0329
• 0360
• 0362
• 0367

The following ACPs are required if your installation uses the feature of importing existing CKDS keys:

• 00F5
• 00FC
• 0130
• 0131
• 0327
• 02B3
• 0105
• 023E