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
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 |
- 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
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.
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:
|
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:
Or, more specifically:component.component.component.component...
Example:qualifier1=node1.qualifier2=node2.qualifier3=node3...
IDNFILTER('OU=Class 1 Certificate.O=BobCA, Inc.SP=New York.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 issuerOU=Class 1 Certificate.O=BobCA, Inc.SP=New York.C=US
and you want all certificates issued byBobCA
to be selected by this filter, specify:
Without the data set containing the certificate, you need to enter the following to produce the same result:IDNFILTER('O=BobCA')
IDNFILTER('O=BobCA, Inc.SP=New York.C=US')
Note: The attribute values, such as State/Province, of the issuer distinguished name on a certificate can be displayed or generated differently asST
,SP
, orS
, depending on the software that is used. For RACF IDNFILTER strings, use theSP
attribute instead ofST
orS
, even when existing certificates are displayed withST
orS
. IBM recommends that you use the RACDCERT CHECKCERT or RACDCERT LIST command to display the mapped certificate before you create the IDNFILTER and debugging unsuccessful filter values.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 preceding list. 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:
Or, more specifically:component.component.component.component...
For example:qualifier1=node1.qualifier2=node2.qualifier3=node3...
SDNFILTER('CN=Bob Cook.OU=BobsAccounting.O=BobsMart.SP=New York')
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 subjectCN=Bob Cook.OU=BobsAccounting.O=BobsMart.SP=New York
and you want all certificates for anyone inBobsAccounting
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.SP=New York')
Note: The attribute values, such as State/Province, of the subject distinguished name on a certificate can be displayed or generated differently asST
,SP
, orS
, depending on the software that is used. For RACF SDNFILTER strings, use theSP
attribute instead ofST
orS
, even when existing certificates are displayed withST
orS
. IBM recommends that you use the RACDCERT CHECKCERT or RACDCERT LIST command to display the mapped certificate before you create the SDNFILTER and debugging unsuccessful filter values.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:
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:variable-name1=&variable-name1.variable-name2=&variable-name2...
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 forCRITERIA(APPLID=&APPLID.SYSID=&SYSID)
&
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:
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 APPLIDAPPLID=BANKU.SYSID=SYSA
=
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
|