Parameters

X'01'

Create an ACEE.

X'02'

Delete an ACEE.

X'03'

Purge all managed ACEEs.

X'04'

Register a certificate

X'05'

Deregister a certificate

X'06'

Query a certificate

X'07'

Generate an IDT from an ACEE

The name of a 9-byte area that consists of a 1-byte length field followed by the name of the application to be used if verifying the user's authority to access the application. This saves the application from having to do a separate authorization check. When using certificate mapping profiles, the application name is also used as part of the additional criteria in determining a user ID when a certificate is passed to initACEE.

When using the Generate an IDT from ACEE function, the application name is used as one of the qualifiers to locate a profile in the IDTDATA class. For the Generate an IDT from ACEE function, the APPL_id parameter must be specified with a length between 1-8.

It must be specified in uppercase. If not specified, the length must equal zero.

While the format of the data structure pointed to by ENVR_in is known to the initACEE invokers, the content of the object itself is determined by the external security product.

The input for this parameter can be the output from a previous initACEE with the ENVR_out parameter specified, or from RACROUTE REQUEST=VERIFY or REQUEST=EXTRACT, with the ENVROUT parameter specified.

If ENVR_in is not specified, the ENVR object length must equal 0, or the end of the parameter list must be indicated by the setting of the high order bit in the address of a previous parameter. ENVR_in should not be specified when requesting that an ENVR object be returned (INTA_ENVR_RET).

For more information about the ENVR data structure, see z/OS Security Server RACROUTE Macro Reference.

While the format of the data structure pointed to by ENVR_out itself is known to the initACEE invokers, the content of the object itself is determined by the external security product.

The ENVR object storage area can be supplied by the caller or obtained by RACF. If supplied by the caller, it must be on a doubleword boundary and be associated with the job step task. If RACF obtains the storage area, it is on a doubleword boundary and is associated with the job step task. The storage is allocated based on the mode of the caller (LOC=ANY for 31-bit callers and LOC=24 for 24-bit callers).

Storage for the ENVR object is obtained and freed in the subpool and key specified by the caller in the ENVR_out data structure. For additional details on specifying the ENVR object storage area length and address, see Table 4.

Since the ENVR object length is returned to the caller, the ENVR object can be moved from one storage area to another. It is intended for use on subsequent initACEEs with the ENVR_in parameter, or on RACROUTE REQUEST=VERIFY with the ENVRIN parameter, as input when rebuilding a user's security environment. It should not be saved for a long period or passed to another system that does not share the same RACF database.

If the Attributes parameter indicates that an ENVR object should be returned (INTA_ENVR_RET), then this parameter must be specified with at a minimum the values for the subpool and key fields.

For more information about the ENVR data structure, see z/OS Security Server RACROUTE Macro Reference.

• TSO user ID
• z/OS® UNIX user identifier (UID) of user
• z/OS UNIX group identifier (GID) of current group
• Home directory path name
• Initial program path name
• User limits (when OUSP version is greater than 0)

If the Attributes parameter indicates that an OUSP should be returned (INTA_USP and INTA_OUSP_RET), then this parameter must be specified. If the Attributes do not indicate that an OUSP should be returned, then the fullword must equal 0, or the end of the parameter list must be indicated by the setting of the high order bit in the address of a previous parameter.

If the function code indicates that an ACEE is to be created, and the RACF_userid parameter is specified, X500name can supply the name of a fullword containing the address of the X500 name pair to be associated with the ACEE. The X500 name pair should previously have been obtained, along with the RACF user ID, by querying a certificate using initACEE. Both the issuer's name and subject's name must be supplied, and the length of each must be in the range 1 to 255 to prevent a parameter list error. If a valid X500 name pair is supplied, the ACEE created will point to a copy of the name pair, and it will subsequently be used in auditing.

Variable names should be meaningful to the caller of initACEE. Making the 3 character prefix associated with the product calling initACEE part of the variable name will ensure that it is unique. For example, assume RACF implemented a server that calls initACEE for its clients. It will pass a variable, IRRSLVL, which has 2 values. The values are LOW and HIGH. LOW is if the user is accessing the server from the internet and HIGH is if the user is accessing the server from the intranet. The variable_list containing the variable name and its value, LOW or HIGH, is passed to initACEE, along with the certificate supplied by the user. The value of the variable will be used as additional criteria in selecting which user ID the certificate maps to. All callers of initACEE should document their variable names, and the values they pass for each name, in their product documentation.

All value names and values should be uppercase. Do not specify the APPLID or SYSID criteria values in the variable_list. These are determined from the APPL_id parameter and MVS control; blocks, respectively. If they are specified in the variable_list, that specification will be ignored.

This parameter is ignored unless the certificate parameter is specified, and the function code indicates that an ACEE is to be created, or that the certificate is to be queried to find a user ID. If the certificate is defined to RACF in the DIGTCERT class, additional criteria will not be used, and the variable_list values will be ignored. If the certificate is not defined in the DIGTCERT class, the values in the variable list will be used along with APPL_id and SYSID to look for an associated user ID using the DIGTNMAP and DIGTCRIT classes if these classes are active and have been RACLISTed with SETROPTS.

The name of a 4-byte area containing the ALET for the ACEE named by the ACEE2_ptr parameter. The 4-byte area must be in the primary address space. This parameter is only supported by function code X’07’.

The name of a 4-byte area that contains the ACEE address. This parameter may be qualified by the ALET specified in ACEE2_ALET.

This parameter is only supported by function code X’07’.

The name of a fullword containing the address of an Identity Token Area for the generation of an Identity Token for the specified ACEE.

The IDT is returned in the buffer pointed to by the IDTA buffer pointer. The IDT length is set in the IDTA IDT length field. More IDTA parameter details are described in z/OS Security Server RACF Callable Services in Appendix G.

The IDTA is mapped by SAF macro IRRPIDTA.

An IDT generated by initACEE will contain an AMR claim value of “saf-acee” which indicates the IDT was generated from an existing security environment. In order to authenticate a user with an IDT with the “saf-acee” AMR claim with RACROUTE REQ=VERIFY the target system must have the required support installed.