RACDCERT MAP (Create mapping)

Purpose

Use the RACDCERT MAP command to define a user ID mapping, also called a certificate name filter. Defining a mapping results in the creation of a profile in the DIGTNMAP class. DIGTNMAP profiles are used as filters when a user attempts to access the system using a digital certificate. A user ID is found by comparing the issuer's distinguished name and subject's distinguished name from the certificate with the filter values used to create the DIGTNMAP profile. The user ID is specified with the ID keyword or specified in DIGTCRIT profiles if MULTIID is specified. When you specify MAP, you must specify IDNFILTER, SDNFILTER, or both.

See UTF-8 and BMP character restrictions for information about how UTF-8 and BMP characters in certificate names and labels are processed by RACDCERT functions.

Issuing options

The following table identifies the eligible options for issuing the RACDCERT MAP command:

As a RACF® TSO command?	As a RACF operator command?	With command direction?	With automatic command direction?	From the RACF parameter library?
Yes	No	No. (See rules.)	No. (See rules.)	No
Rules: The following rules apply when issuing this command. The RACDCERT command cannot be directed to a remote system using the AT or ONLYAT keyword. The updates made to the RACF database by RACDCERT are eligible for propagation with automatic direction of application updates based on the RRSFDATA profiles AUTODIRECT.target-node.DIGTMAP.APPL and AUTODIRECT.target-node.DIGTCRIT.APPL, where target-node is the remote node to which the update is to be propagated.

Authorization required

To issue the RACDCERT MAP command, you must have the SPECIAL attribute or sufficient authority to the IRR.DIGTCERT.MAP resource in the FACILITY class for your intended purpose.

Table 1. Authority required for the RACDCERT MAP function
IRR.DIGTCERT.MAP
Access level	Purpose
READ	Create a mapping associated with your own user ID.
UPDATE	Create a mapping associated with another user ID or MULTIID.

Activating your changes

If the DIGTNMAP or DIGTCRIT class is RACLISTed, refresh the classes to activate your changes.

Example:

SETROPTS RACLIST(DIGTNMAP, DIGTCRIT) REFRESH

Related commands

To alter a user ID mapping, see RACDCERT ALTMAP.
To delete a user ID mapping, see RACDCERT DELMAP.
To list a user ID mapping, see RACDCERT LISTMAP.

The RACDCERT MAP command is unrelated to the RACMAP MAP command.

Syntax

For the key to the symbols used in the command syntax diagrams, see Syntax of RACF commands and operands. The complete syntax of the RACDCERT MAP command is:


RACDCERT MAP[(data-set-name)]
[ ID(mapping-owner) \| MULTIID ] [ SDNFILTER('subject's-distinguished-name-filter') ] [ IDNFILTER('issuer's-distinguished-name-filter') ] [ CRITERIA(criteria-profile-name-template) ] [ WITHLABEL('label-name') ] [ TRUST \| NOTRUST ]

If you specify more than one RACDCERT function, only the last specified function is processed. Extraneous keywords that are not related to the function being performed are ignored.

If you do not specify a RACDCERT function, LIST is the default function.

For information on issuing this command as a RACF TSO command, refer to RACF TSO commands.

Parameters

MAP

MAP(data-set-name)

A data set name can be specified with the MAP keyword. The data-set-name value is the name of the data set that contains a certificate. The certificate provides a model for the filter names specified with SDNFILTER and IDNFILTER. The subject's distinguished name is used beginning with the value specified by SDNFILTER. The issuer's distinguished name is used beginning with the value specified by IDNFILTER. Using a model certificate is optional but can reduce the chance of typographical errors when entering long filters for SDNFILTER or IDNFILTER.

The model certificate used with the MAP keyword can have an issuer's distinguished name or subject's distinguished name that exceeds 255 characters. However, the portion of each used in the filter to associate a user ID with the certificate cannot exceed 255 characters.

See RACDCERT ADD for acceptable certificate formats.

The data-set-name value has the same characteristics (for example, RECFM) as the data set that can be specified with the ADD and CHECKCERT keywords. The issuer of the RACDCERT command must have READ access to the data set containing the data-set-name.

ID(mapping-owner) | MULTIID

Specifies the user ID to be associated with the new mapping. If you do not specify ID or MULTIID, the default is ID, and mapping-owner defaults to the user ID of the command issuer. If more than one keyword is specified, the last specified keyword is processed and the others are ignored by TSO command parse processing.

ID(mapping-owner): Specifies the user ID to be associated with the mapping.
MULTIID: Specifies that additional criteria is used to determine the user ID to be associated with the mapping. You must also specify the CRITERIA keyword.

IDNFILTER('issuer's-distinguished-name-filter')

Specifies the significant portion of the issuer's distinguished name that is used as a filter when associating a user ID with a certificate. For an explanation of how filter values are used to associate a user ID with a digital certificate, see "Certificate name filtering" in z/OS Security Server RACF Security Administrator's Guide.

When specified without data-set-name on the MAP keyword, you must specify the entire portion of the distinguished name to be used as a filter.

The format of the issuer's-distinguished-name-filter is similar to the output displayed when a certificate is listed with RACDCERT. It is an X.509 distinguished name in an address type format:

component.component.component.component…

Or, more specifically:

qualifier1=node1.qualifier2=node2.qualifier3=node3…

Example:

IDNFILTER('OU=Class 1 Certificate.O=BobCA, Inc.L=internet.C=US')

Restriction: The filter name cannot contain the ¢ character (X'4A').

The IDNFILTER value is limited to 1024 characters and must begin with a prefix found in the following list, followed by an equal sign (X'7E'). Each component should be separated by a period (X'4B'). The case, blanks, and punctuation displayed when the digital certificate information is listed must be maintained in the IDNFILTER. Because digital certificates only contain characters available in the ASCII character set, the same characters should be used for the IDNFILTER value. Valid prefixes are:

Country: Specified as C=
State/Province: Specified as SP=
Locality: Specified as L=
Organization: Specified as O=
Organizational Unit: Specified as OU=
Title: Specified as T=
Common Name: Specified as CN=

When specified along with data-set-name on the MAP keyword, the issuer's-distinguished-name-filter must correspond to a starting point within the issuer's distinguished name found in the certificate contained in the data set. You should specify enough of the name to precisely identify the starting point for the filter. For example, if the certificate in the data set has the issuer OU=Class 1 Certificate.O=BobCA, Inc.L=internet.C=US and you want all certificates issued by BobCA to be selected by this filter, specify:

IDNFILTER('O=BobCA')

Without the data set containing the certificate, you need to enter the following to produce the same result:

IDNFILTER('O=BobCA, Inc.L=internet.C=US')

IDNFILTER is optional if SDNFILTER is specified. If IDNFILTER is not specified, only the subject's name is used as a filter. If IDNFILTER is specified and only a portion of the issuer's name is to be used as the filter, SDNFILTER must not be specified.

If both IDNFILTER and SDNFILTER are specified, the IDNFILTER value does not need to begin with a valid prefix from the list above. This allows the use of certificates from a certificate authority that chooses to include nonstandard data in the issuer's distinguished name.

SDNFILTER('subject's-distinguished-name-filter')

Specifies the significant portion of the subject's distinguished name that is used as a filter when associating a user ID with a certificate. For an explanation of how filter values are used to associate a user ID with a digital certificate, see "Certificate name filtering" in z/OS Security Server RACF Security Administrator's Guide.

When specified without data-set-name on the MAP keyword, you must specify the entire portion of the distinguished name to be used as the filter.

The format of the subject's-distinguished-name-filter is similar to the output displayed when a certificate is listed with RACDCERT. It is an X.509 distinguished name in an address type format:

component.component.component.component…

Or, more specifically:

qualifier1=node1.qualifier2=node2.qualifier3=node3…

For example:

SDNFILTER('CN=Bob Cook.OU=BobsAccounting.O=BobsMart.L=internet')

Restriction: The filter name cannot contain the ¢ character (X'4A').

The SDNFILTER value is limited to 1024 characters and must begin with a prefix found in the following list, followed by an equal sign (X'7E'). Each component should be separated by a period (X'4B'). The case, blanks, and punctuation displayed when the digital certificate information is listed must be maintained in the SDNFILTER. Because digital certificates only contain characters available in the ASCII character set, the same characters should be used for the SDNFILTER value. Valid prefixes are:

Country: Specified as C=
State/Province: Specified as SP=
Locality: Specified as L=
Organization: Specified as O=
Organizational Unit: Specified as OU=
Title: Specified as T=
Common Name: Specified as CN=

When specified along with data-set-name on the MAP keyword, the subject's-distinguished-name-filter must correspond to a starting point within the subject's distinguished name found in the certificate contained in the data set. You should specify enough of the name to precisely identify the starting point for the filter. For example, if the certificate in the data set has the subject CN=Bob Cook.OU=BobsAccounting.O=BobsMart.L=internet and you want all certificates for anyone in BobsAccounting to be selected by this filter, specify:

SDNFILTER('OU=BobsAcc')

Without the data set containing the certificate, you need to enter the following to produce the same result:

SDNFILTER('OU=BobsAccounting.O=BobsMart.L=internet')

SDNFILTER is optional if IDNFILTER is specified. If SDNFILTER is not specified, only the issuer's name is used as a filter. SDNFILTER must not be specified with IDNFILTER unless the value of IDNFILTER will result in the entire issuer's name being used in the filter. Note that subject's name can be partial but cannot be used in a filter that contains only a partial issuer's name.

CRITERIA(criteria-profile-name-template)

When specified with MULTIID, it indicates a dynamic user ID mapping. The user ID associated with this mapping profile is based not only on the issuer's distinguished name and the subject's distinguished name found in the certificate, but also on additional criteria. The criteria-profile-name-template specifies the additional criteria in the form of a profile name containing one or more variable names, separated by free-form text. These variable names begin with an ampersand (&) and end with a period. The free-form text should identify the variables contained in the template:

variable-name1=&variable-name1.variable-name2=&variable-name2…

For example, if the application identity and system identifier are to be considered in determining the user ID associated with this mapping, the CRITERIA keyword should be specified as follows:

CRITERIA(APPLID=&APPLID.SYSID=&SYSID)

The RACF-defined criteria are the application ID (APPLID) and the system-identifier (SYSID). When a user presents a certificate to the system for identification, the identity of the application (as well as the system the user is trying to access) being accessed becomes part of the criteria. The application passes its identity to RACF, and RACF determines the system-identifier. The system-identifier is the 4-character value specified for the SID parameter of the SMFPRMxx member of SYS1.PARMLIB. These values are substituted for &APPLID and &SYSID in the criteria.

Once the substitution is made, the fully expanded criteria template is used as a resource name to find a matching profile defined in the DIGTCRIT class using the RDEFINE command. For example, if the application being accessed is BANKU on system SYSA, the template is:

APPLID=BANKU.SYSID=SYSA

You should define a profile in the DIGTCRIT class using the RDEFINE command for this name. The user ID to be associated with these certificates must be specified as the APPLDATA. While the DIGTCRIT profile name can be discrete, generic profiles can be used if you have generic profile checking active for the DIGTCRIT class. A DIGTCRIT profile name of APPLID=BANKU.* allows the certificates to be used on any system, rather than just system SYSA. While generic characters such as * and % can be used when defining the DIGTCRIT class profiles, they should not be used in the template name specified with the CRITERIA keyword.

Criteria names other than APPLID and SYSID are allowed, but are effective in certificate name filtering if the application supplies these criteria names and their associated values to RACF when the user attempts to access the application using a certificate. SYSID is determined by RACF, but APPLID must be specified with the initACEE callable service. Criteria names, such as APPLID and SYSID, should only be specified on RACDCERT if the application instructs you to do so.

A maximum of 255 characters can be entered when specifying the CRITERIA keyword. The values can be entered in any case, but are made uppercase by the RACDCERT command because they must match uppercase profile names in the DIGTCRIT class to be effective. When specifying the criteria value, the maximum length for profile names in the DIGTCRIT class is 246 characters.

The CRITERIA keyword can only be set for MULTIID.

WITHLABEL('label-name')

Specifies the label that is assigned to this mapping. If specified, it must be unique to the user ID with which the mapping is associated. If WITHLABEL is not specified, a label is generated in the same manner as issuing the WITHLABEL keyword for the RACDCERT ADD command.

Up to 32 characters can be specified for label-name. It can contain imbedded blanks and mixed-case characters, and is stripped of leading and trailing blanks. If a single quotation mark is intended to be part of the label-name, use two single quotation marks together for each single quotation mark within the string, and enclose the entire string within single quotation marks.

TRUST | NOTRUST

When specified with MAP, indicates whether this mapping can be used to associate a user ID to a certificate presented by a user accessing the system. If neither TRUST nor NOTRUST is specified, the default is TRUST.

Examples


Example 1	Operation	User RACFADM with SPECIAL authority requests the addition of a new mapping profile that will associate the user ID WEBUSER with all digital certificates issued by VeriSign for Class 1 Individual Subscribers. A certificate is not readily available in a data set.
	Known	User RACFADM has SPECIAL authority.
	Command	`RACDCERT ID(WEBUSER) MAP IDNFILTER('OU=VeriSign Class 1 Individual Subscriber.O=VeriSign, Inc..L=Internet') WITHLABEL('Savings Account')`
	Output	None.

Example 2	Operation	User RACFADM with SPECIAL authority requests the addition of a new mapping profile that will associate all members of department BWVA, who have VeriSign Class 1 Individual subscriber certificates, with the user ID BWVAUSR. All members of the department have the organizational unit BWVA (OU`=`BWVA) as the second node of the subject name in their certificates. A certificate belonging to one of the department member is available in the data set JJONES.DEPTCERT. The use of the certificates should not be allowed until the network administrator gives his approval, so this mapping is currently not trusted.
	Known	User RACFADM has SPECIAL authority to profile IRR.DIGTCERT.MAP in the FACILITY class.
	Command	`RACDCERT ID(BWVAUSR) MAP('JJONES.DEPTCERT') IDNFILTER('OU=VeriSign Class 1') NOTRUST SDNFILTER('OU=BWVA') WITHLABEL('BWVA USERS')`
	Output	None.

Example 3	Operation	User CERTADM with ALTER authority to profile IRR.DIGTCERT.MAP in the FACILITY class has received a digital certificate and placed it in the data set `CERTADM.MODEL.CERT`. BobsBank has contracted VeriSign, Inc. to create certificates like the one received. These certificates will be installed on the workstations of each bank teller, and used to access the banking application BANKAPP. All certificates must map to the user ID BANKU which has access to the data sets containing the banking data. CERTADM uses this function to display the issuer's name and subject name from the certificate.
	Known	User CERTADM has ALTER authority to profiles IRR.DIGTCERT.MAP in the FACILITY class.
	Commands	`RDEF DIGTCRIT BOBS.APPLID1=BANKAPP APPLDATA('BANKU') RACDCERT MULTIID MAP(MODEL.CERT) IDNFILTER('OU=') SDNFILTER('CN=') CRITERIA(BOBS.APPLID1=&APPLID) WITHLABEL('Bobs Tellers')`
	Output	None.