RACF HELP FOR: RACDCERT


   
   
 FUNCTION  
 RACDCERT (RACF DIGITAL CERTIFICATE)  
 ___________________________________  
   
   
   
   
 Purpose  
   
   
 RACDCERT is used to install and maintain digital certificates, key  
 rings, and certificate mappings in RACF, and RACDCERT should be used fo  
 all maintenance of the DIGTCERT, DIGTRING, and DIGTNMAP class profiles  
 and related USER profile fields.  
   
   
 The RACDCERT command is a RACF TSO command used to:  
   
   
  *  List information about the existing certificates for a specified  
     RACF defined user ID, or your own user ID.  
   
   
  *  Add a certificate definition and associate it with a specified  
     RACF defined user ID, or your own user ID, and set the TRUST  
     flag.  
   
   
  *  Alter the TRUST flag or the LABEL name for an existing definition.  
   
   
  *  Delete a definition.  
   
   
  *  List a certificate contained in a data set and determine if it is  
     associated with a RACF-defined user ID.  
   
   
  *  Add or remove a certificate from a key ring.  
   
   
  *  Create, delete, or list a key ring.  
   
   
  *  Generate a public/private key pair and certificate  
   
   
  *  Write a certificate to a data set.  
   
   
  *  Create a certificate request.  
   
   
  *  Create, alter, delete, or list a user ID mapping  
   
   
   
   
 Additional keywords on the RACDCERT command allow some information  
 about the certificate or key ring to be listed, the label and status  
 flag to be altered, and the certificate or key ring to be deleted.  
   
   
 To facilitate the altering and deleting of a certificate definition,  
 you need to enter the minimum amount of information needed to uniquely  
 identify the definition to be changed.  If only one certificate is  
 defined for the user ID, then only the ID is required.  If more than  
 one certificate is defined to the user ID, the LABEL or SERIALNUMBER  
 is also required.  If the SERIALNUMBER is not unique for the user ID,  
 the ISSUERSDN is also required.  
   
   
   
   
 Issuing Options  
   
   
 The following table identifies the eligible options for issuing the  
 RACDCERT command:  
   
   
 +--------------------------------------------------------------------+  
 |Table 1. How the RACDCERT Command Can be Issued                     |  
 +------------+--------------+--------------+--------------+----------+  
 |            |              |              | With         | From the |  
 |As a RACF   | As a RACF    |              | Automatic    | RACF     |  
 |TSO         | Operator     | With Command | Command      | Parameter|  
 |Command?    | Command?     | Direction?   | Direction?   | Library? |  
 +------------+--------------+--------------+--------------+----------+  
 |Yes         | No           | See Note     | See Note     | No       |  
 +------------+--------------+--------------+--------------+----------+  
   
   
 Note:  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.DIGTCERT.APPL and  
        AUTODIRECT.target-node.DIGTRING.APPL, where target-node is the  
        remote node to which the update is to be propagated.  
   
   
   
   
 Authorization Required  
   
   
 To issue the RACDCERT command, you must have one of the following  
 authorities:  
   
   
  *  SPECIAL  
   
   
  *  Sufficient authority to resource IRR.DIGTCERT.function in the  
     FACILITY  class, as described in Table 2, Table 3, Table 4, and  
     Table 5.  
   
   
   
   
 Authority required for the RACDCERT Functions: The authorities  
 required to perform the various RACDCERT functions are summarized in  
 Table 2.  The authorities listed are to the resource  
 IRR.DIGTCERT.function in the FACILITY class.  
   
   
 +--------------------------------------------------------------------+  
 |Table 2. RACDCERT Authority Checks                                  |  
 +--------+-------------------+-------------------+-------------------+  
 |FUNCTION| READ              | UPDATE            | CONTROL           |  
 +--------+-------------------+-------------------+-------------------+  
 |ADD     | Add a certificate | Add a certificate | Add a certificate |  
 |        | to one's own user | for someone else. | authority or site |  
 |        | ID.               |                   | certificate.      |  
 +--------+-------------------+-------------------+-------------------+  
 |ADDRING | Create a key ring | Create a key ring | Not applicable.   |  
 |        | for one's own user| for another user  |                   |  
 |        | ID.               | ID.               |                   |  
 +--------+-------------------+-------------------+-------------------+  
 |ALTER   | Change the trust  | Change the trust  | Change the trust  |  
 |        | status or label of| status or label of| status or label of|  
 |        | one's own         | someone else's    | a certificate     |  
 |        | certificate.      | certificate.      | authority or site |  
 |        |                   |                   | certificate.      |  
 +--------+-------------------+-------------------+-------------------+  
 |ALTMAP  | Alter a mapping   | Alter a mapping   | Not applicable.   |  
 |        | associated with   | with another user |                   |  
 |        | one's own user ID.| ID or MULTIID.    |                   |  
 +--------+-------------------+-------------------+-------------------+  
 |CONNECT | See Table 4.      | See Table 4.      | See Table 5.      |  
 +--------+-------------------+-------------------+-------------------+  
 |DELETE  | Delete one's own  | Delete the        | Delete a          |  
 |        | certificate.      | certificate of    | certificate       |  
 |        |                   | someone else.     | authority or site |  
 |        |                   |                   | certificate.      |  
 +--------+-------------------+-------------------+-------------------+  
 |DELMAP  | Delete a mapping  | Delete a mapping  | Not applicable.   |  
 |        | associated with   | with another user |                   |  
 |        | one's own user ID.| ID or MULTIID.    |                   |  
 +--------+-------------------+-------------------+-------------------  
 |DELRING | Delete one's own  | Delete the key    | Not applicable.   |  
 |        | key ring.         | ring of someone   |                   |  
 |        |                   | else.             |                   |  
 +--------+-------------------+-------------------+-------------------+  
 |EXPORT  | Export one's own  | Export the        | Export a SITE or  |  
 |        | certificate.      | certificate of    | CERTAUTH          |  
 |        |                   | another user.     | certificate.      |  
 +--------+-------------------+-------------------+-------------------+  
 |GENCERT | See Table 3.      | See Table 3.      | See Table 3.      |  
 +--------+-------------------+-------------------+-------------------+  
 |GENREQ  | Generate a request| Generate a request| Generate a request|  
 |        | based on one's own| based on the      | based on a SITE or|  
 |        | certificate.      | certificate of    | CERTAUTH          |  
 |        |                   | another user.     | certificate.      |  
 +--------+-------------------+-------------------+-------------------+  
 |LIST    | List one's own    | List the          | List certificate  |  
 |        | certificate.      | certificate of    | authority or site |  
 |        |                   | someone else.     | certificates.     |  
 +--------+-------------------+-------------------+-------------------+  
 |LISTMAP | List mapping      | List mapping      | Not applicable.   |  
 |        | information for   | information for   |                   |  
 |        | one's own user    | another user ID   |                   |  
 |        | ID.               | or MULTIID.       |                   |  
 +--------+-------------------+-------------------+-------------------+  
 |LISTRING| See one's own key | See the key ring  | Not applicable.   |  
 |        | ring.             | of someone else.  |                   |  
 +--------+-------------------+-------------------+-------------------+  
 |MAP     | Create a mapping  | Create a mapping  | Not applicable.   |  
 |        | associated with   | with another user |                   |  
 |        | one's own user ID.| ID or MULTIID.    |                   |  
 +--------+-------------------+-------------------+-------------------  
 |REMOVE  | Delete a          | Delete a          | Delete a          |  
 |        | certificate from  | certificate       | certificate from  |  
 |        | one's own key     | authority or site | the ring of       |  
 |        | ring.             | certificate from  | another.          |  
 |        |                   | one's own ring.   |                   |  
 +--------+-------------------+-------------------+-------------------+  
   
   
   
   
   
   
 SYNTAX  
 RACDCERT Syntax  
   
   
 The complete syntax of the RACDCERT command is:  
   
   
 +------------+-------------------------------------------------------+  
 | RACDCERT   |                                                       |  
 +------------+-------------------------------------------------------+  
 |            |  ID(userid) | MULTIID | SITE | CERTAUTH               |  
 +------------+-------------------------------------------------------+  
 |            |  LIST                                                 |  
 |            |           (LABEL('label-name'))                       |  
 |            |         | (SERIALNUMBER(serial-number)                |  
 |            |            ISSUERSDN('issuer's-dist-name'))           |  
 +------------+-------------------------------------------------------+  
 |            | | ADD(data-set-name)                                  |  
 |            |          TRUST|NOTRUST                                |  
 |            |          WITHLABEL('label-name')                      |  
 |            |          PASSWORD('pkcs12-password')                  |  
 |            |          ICSF                                         |  
 +------------+-------------------------------------------------------+  
 |            | | CHECKCERT(data-set-name)                            |  
 |            |          PASSWORD('pkcs12-password')                  |  
 |            |                                                       |  
 +------------+-------------------------------------------------------+  
 |            | | ALTER                                               |  
 |            |           (LABEL('label-name'))                       |  
 |            |         | (SERIALNUMBER(serial-number)                |  
 |            |            ISSUERSDN('issuer's-dist-name'))           |  
 |            |            TRUST | NOTRUST                            |  
 |            |            NEWLABEL('label-name')                     |  
 +------------+-------------------------------------------------------+  
 |            | | DELETE                                              |  
 |            |           (LABEL('label-name'))                       |  
 |            |         | (SERIALNUMBER((serial-number)               |  
 |            |            ISSUERSDN('issuer's-dist-name'))           |  
 |            |                                                       |  
 +------------+-------------------------------------------------------+  
 |            | | GENCERT(request-data-set-name)                      |  
 |            |           SUBJECTSDN(CN('common-name')                |  
 |            |                          T('title')                   |  
 |            |                          OU('organizational-unit-     |  
 |            |                               name1'                  |  
 |            |                              ,'organizational-unit-   |  
 |            |                                name2'                 |  
 |            |                                )                      |  
 |            |                          O('organization-name')       |  
 |            |                          L('locality')                |  
 |            |                          SP('state-or-province')      |  
 |            |                          C('country')                 |  
 |            |                          )                            |  
 |            |           SIZE(key-size)                              |  
 |            |           NOTBEFORE( DATE(yyyy-mm-dd)  TIME(hh:mm:ss))|  
 |            |           NOTAFTER( DATE(yyyy-mm-dd)  TIME(hh:mm:ss)) |  
 |            |           WITHLABEL('label-name')                     |  
 |            |           SIGNWITH(CERTAUTH|SITE LABEL('label-name')  |  
 |            |           ICSF                                        |  
 +------------+-------------------------------------------------------+  
 |            | | EXPORT(LABEL('label-name'))                         |  
 |            |           DSN(output-data-set-name)                   |  
 |            |           FORMAT(CERTDER|CERTB64)                     |  
 +------------+-------------------------------------------------------+  
 |            | | GENREQ(LABEL('label-name'))                         |  
 |            |           DSN(output-data-set-name)                   |  
 +------------+-------------------------------------------------------+  
 |            | | CONNECT(ID(userid)  | SITE | CERTAUTH               |  
 |            |           LABEL('label-name')                         |  
 |            |           RING(ring-name)                             |  
 |            |           DEFAULT                                     |  
 |            |           USAGE(PERSONAL | SITE | CERTAUTH))          |  
 +------------+-------------------------------------------------------+  
 |            | | REMOVE(ID(USER-ID) | SITE | CERTAUTH                |  
 |            |           LABEL('label-name')                         |  
 |            |           RING(ring-name))                            |  
 +------------+-------------------------------------------------------+  
 |            | | ADDRING(ring-name)                                  |  
 +------------+-------------------------------------------------------+  
 |            | | DELRING(ring-name)                                  |  
 +------------+-------------------------------------------------------+  
 |            | | LISTRING(ring-name)                                 |  
 |            |                                                       |  
 +------------+-------------------------------------------------------+  
 |            | | MAP(data-set-name)                                  |  
 |            |           SDNFILTER('subject's-distinguished-         |  
 |            |           name-filter')                               |  
 |            |           IDNFILTER('issuer's-distinguished-          |  
 |            |           name-filter')                               |  
 |            |           CRITERIA(criteria-profile-name-             |  
 |            |           template)                                   |  
 |            |           WITHLABEL('label-name')                     |  
 |            |           TRUST | NOTRUST                             |  
 +------------+-------------------------------------------------------+  
 |            | | ALTMAP(LABEL('label-name'))                         |  
 |            |           NEWCRITERIA(criteria-profile-               |  
 |            |           name-template')                             |  
 |            |           NEWLABEL('label-name')                      |  
 |            |           TRUST | NOTRUST                             |  
 +------------+-------------------------------------------------------+  
 |            | | DELMAP(LABEL('label-name'))                         |  
 +------------+-------------------------------------------------------+  
 |            | | LISTMAP(LABEL('label-name'))                        |  
 +------------+-------------------------------------------------------+  
   
   
   
   
 Note:  For information on issuing this command as a RACF TSO command,  
        refer to Chapter 3, "RACF TSO Commands" in the OS/390  
        Security Server (RACF) Command Language Reference.  
   
   
   
   
 OPERANDS  
 Parameters  
   
   
 On the RACDCERT command, you can specify the ID, MULTIID, SITE, or  
 CERTAUTH keywords to identify the user ID that will be associated with  
 the RACDCERT command.  ID, CERTAUTH, and SITE can be specified with the  
 keywords LIST, ADD, DELETE, GENCERT, GENREQ, and EXPORT.  The ID and  
 MULTIID keywords can be specified with the keywords MAP, ALTMAP, DELMAP  
 and LISTMAP.  The ID keyword can also be specified with the keywords  
 ADDRING, DELRING, LISTRING, CONNECT, and REMOVE.  The function CHECKCER  
 will ignore the keywords ID, MULTIID, CERTAUTH, and SITE.  
   
   
 If more than one function keyword is specified, the last one specified  
 is processed and the others ignored.  Extraneous keywords that are not  
 related to the function that is being performed are ignored.  
   
   
 If the DIGTCERT or DIGTNMAP class is RACLISTed, whenever you perform a  
 RACDCERT ADD, ALTER, DELETE, MAP, ALTMAP, or DELMAP, you should refresh  
 the class with the RACF TSO command:  
   
   
 SETROPTS RACLIST(DIGTCERT, DIGTNMAP) REFRESH  
   
   
 When a certificate is ALTERed or DELETEd, the certificate must be  
 uniquely identified with:  
   
   
  *  the ID keyword, which defaults to the current user ID, and  
  *  the LABEL or SERIALNUMBER or SERIALNUMBER and ISSUERDSN  
     combination.   If the user ID has only one certificate installed,  
     this information is optional.  
   
   
   
   
 When issuing RACDCERT LIST, rather than listing all certificates  
 assigned to a user, the LABEL or SERIALNUMBER or SERIALNUMBER and  
 ISSUERSDN combination can also be used to uniquely identify a  
 certificate.  
   
   
   ID(userid) |  
   MULTIID |  
   CERTAUTH |  
   SITE  
     specifies the user ID associated with the certificate, key ring,  
     or certificate mapping.  If more than one of these keywords is  
     specified, the last one specified will be processed, and the others  
     will be ignored as part of TSO command parsing.  If none of these  
     keywords are specified, the default value is to set the ID  
     keyword to the user ID of the user issuing the command.  If neither  
     keyword is specified, the default is ID.  
   
   
     For certificate management you can specify a specific user ID's  
     certificate, a certificate authority certificate, or a site  
     certificate through the ID(userid), CERTAUTH, or SITE keyword  
     respectively.  For ring management, you can only specify a user ID  
     associated with the key ring because only user IDs can have key  
     rings.  
   
   
     When ID or MULTIID is specified with a mapping function keyword  
     (MAP, ALTMAP, LISTMAP, or DELMAP), it indicates the type of mapping  
     that is being processed.  When ID is specified, the DIGTNMAP profil  
     created by the MAP keyword is associated with the specified user ID  
     MULTIID mapping profiles associate a certificate to a user ID  
     through profiles created in the DIGTCRIT class using the RDEFINE  
     command.  
   
   
     The DELETE, DELRING and DELMAP keywords for RACDCERT support the  
     specification of a non-existent user ID in order to allow residual  
     certificate information related to the user ID to be deleted.  
     Normally, when a user profile is deleted with the DELUSER command,  
     related DIGTCERT, DIGTRING, and DIGTNMAP profiles are deleted as  
     part of DELUSER processing.  For example, if you issue the DELUSER  
     command from a down-level (Version 2` Release 7 or earlier) that  
     does not fully support the current level of digital certificate  
     information, profiles might not be deleted.  The residual DIGTCERT,  
     DIGTRING, and DIGTNMAP profiles can be removed from the system by  
     specifying the user IDs with the DELETE, DELRING, or DELMAP  
     keywords.  
   
   
   
   
   LIST  
   LIST(SERIALNUMBER(serial-number) ISSUERSDN('issuer's-dist-name'))  
   LIST(LABEL('label-name'))  
     displays the digital certificate information, including  
     certificate authority and site certificate information. For  
     each digital certificate defined, the following information  
     is displayed:  
   
   
     *  Serial number  
     *  Issuer's distinguished name  
     *  Label  
     *  Status  
     *  Validity dates  
     *  Private key size  
     *  Type of private key (ICSF or DER-encoded key), or NONE if  
        there is no private key  
     *  Rings  
     *  Up to 256 bytes of the subject's name, as found in the  
        certificate itself  
   
   
         If the RACDCERT command is issued with no other keywords, it  
         lists the command issuer's digital certificate information.  If  
         the RACDCERT command is issued with the ID keyword and no other  
         keywords, it lists the digital certificate information  
         associated with the user ID specified with the ID keyword.  
   
   
         Note that the issuer's distinguished name and the subject's  
         distinguished name can contain blanks.  If the name displayed i  
         the output is subsequently entered with the ISSUERSDN keyword,  
         the blanks must be included.  In the output of LIST, the  
         characters '>' and '<' are used as delimiters to mark the  
         beginning and the end of the serial number, issuer's name and  
         subject's name.  When information continues to the next line,  
         '<' appears in column 79 of the output, and '>' appears in  
         column 9 of the continuation line.  
   
   
         If the user has only one certificate, or if all certificates ar  
         to be displayed, the SERIALNUMBER and ISSUERSDN keywords, or th  
         LABEL keyword, and their associated values can be omitted.  If  
         the user has more than one certificate the LABEL, SERIALNUMBER,  
         or SERIALNUMBER and ISSUERSDN can be used to select which  
         certificate to list.  When specifying the issuer's distinguishe  
         name, or the label, the mixed-case characters and blanks  
         displayed when the digital certificate information is listed  
         must be maintained in the ISSUERSDN or the LABEL keyword.  
   
   
         For a description of label-name, see the description of the  
         WITHLABEL keyword for the ADD function.  
   
   
         Note: Original RACF digital certificate support did not allow  
         for labels to be specified.  These certificates display "No  
         label assigned" in the label field when listed.  
   
   
   
   
   ADD(data-set-name)  
     specifies that a digital certificate is to be defined.  The  
     specified data set must contain the digital certificate.  Each user  
     ID can be associated with more than one digital certificate but the  
     must be added individually.  The specified data set should contain  
     only one digital certificate.  The command reads the certificate  
     from the data set, updates the user's profile, and creates the  
     DIGTCERT profile.  The digital certificate must be in one of the  
     following formats:  
   
   
     1.  A single DER encoded X.509 certificate.  
     2.  A Privacy Enhanced Mail (PEM) encoded X.509 certificate. If  
         the input is in this format, only the Originator Certificate  
         is used.  
     3.  One or more X.509 certificates contained within a PKCS#7 DER  
         encoding. If the input is in this format, only the first  
         certificate in the PKCS#7 encoding is used.  
     4.  A Base64 encoded certificate.  
     5.  One or more X.509 certificates and private keys contained  
         within a PKCS#12 DER encoding.  If the input is in this  
         format, only the first user certificate and private key is  
         used.  PKCS#12 is also known as Private Information  
         Exchange (PFX).  The obsolete PFX V0.02 standard is  
         not supported.  Note that a package is one or more X.509  
         certificates encoded under the new PKCS standard.  
   
   
   
   
   
   
     Note the following additional details regarding RACDCERT's  
     certificate processing:  
   
   
     1.  All fields as defined for X.509 version 1 certificates must be  
         present and must have a length greater than zero (non-null).  
     2.  X.509 certificates with version numbers greater than 3 are not  
         supported.  
     3.  Except for key usage or basic constraint extensions, X.509  
         Version 3 certificates with critical extensions are not  
         supported.  Noncritical extensions are ignored.  
     4.  Subject and issuer names can contain only the following string  
         types:  
   
   
         *   T61STRING - TAG 20  
         *   PRINTABLESTRING - TAG 19  
         *   IA5STRING - TAG 22  
         *   VISIBLESTRING - TAG 26  
         *   GENERALSTRING - TAG 27  
   
   
     5.  The length of the serial number plus the length of the  
         issuer's name cannot exceed 245.  
     6.  Care must be taken when transporting the different certificate  
         encodings to and from an OS/390 system.  The BER encoded  
         X.509, PKCS#7, and PKCS#12 formats are binary and must be  
         transported in their exact binary format.  Do not perform any  
         ASCII to EBCDIC translations on these formats.  PEM and  
         Base64, however, are text-based protocols and thus should be  
         transported as text.  If transporting from an ASCII  
         system, the ASCII to EBCDIC translation must be performed for  
         the PEM format and Base64 format certificate.  
   
   
   
   
     The data set containing the digital certificate or certificate  
     package must be cataloged, and cannot be a PDS or a PDS member.  
     The RECFM expected by RACDCERT is VB.  When the ADD keyword is  
     specified, RACDCERT dynamically allocates and opens the specified  
     data set, and reads the certificate from it as binary data.  
   
   
     The ADD keyword also supports site and certificate authority  
     certificates in its processing, and replacement certificates can  
     be processed.  This allows certificate renewals or certificate  
     request completions to be processed.  This means that:  
   
   
     *   RACDCERT ADD can no longer be used to change a label.  If  
         RACDCERT ADD is issued more than once for a given certificate,  
         RACDCERT ADD flags the extraneous ADD, issues an informational  
         message, and does not add the certificate to the RACF database.  
         However, if WITHLABEL specifies the same label and the internal  
         label is the same (if one exists), or WITHLABEL is not  
         specified, an informational message is not issued and the  
         certificate is re-added.  
   
   
     *   If the certificate that is being added has the same subject's  
         distinguished name, issuer's distinguished name, and public key  
         as an existing certificate, and the certificate being added is  
         not a duplicate, ADD processing checks the validity dates and  
         times of the certificate.  If the certificate being added passe  
         the signature and date validity checks, if the end date and tim  
         on the certificate being added is later than that of the  
         existing certificate, and if the certificate is not expired,  
         the certificate is replaced.  
   
   
     *   If the public key of the certificate being added matches that  
         of another certificate for the user, the certificate is not a  
         duplicate so there is a private key associated with the  
         certificate in the RACF database, and the certificate is not  
         expired, the certificate is replaced.  
   
   
         Note: When a certificate is being replaced, a new label can be  
         specified.  
   
   
   
   
     PKCS#12 certificate packages can be processed.  These certificates  
     are encrypted when received and must be decrypted before being adde  
     to the RACF database.  The decryption process requires the password  
     that was used when the PKCS #12 certificate package was encrypted.  
     This password is specified with the PASSWORD keyword.  A PKCS#12  
     certificate package can contain more than one certificate.  RACDCER  
     ADD only processes the first certificate in the PKCS#12 certificate  
     package that has a private key.  
   
   
     When adding a certificate package that contains a private key, and  
     ICSF is being used to store private keys, ADD creates an ICSF key  
     label in the format  
     IRR.DIGTCERT.userid.cvtsname.ebcdic-stck-value, where userid is  
     the owning user ID, cvtsname is the system name, as taken from the  
     CVT, and ebcdic-stck-value is an EBCDIC version of the current  
     store clock value.  If the key is associated with a certificate  
     authority certificate, the user ID is set to CERTIFAUTH.  If the  
     key is encrypted.  This associated with a site certificate, the  
     userid is set to SITECERTIF.  
   
   
     Note: The issuer of the RACDCERT command must have READ access to  
     the data-set-name data set to prevent an authorization abend from  
     occurring when the data set is read.  
   
   
     TRUST|NOTRUST  
         when specified with the ADD operand, indicates whether the  
         status of the certificate being added is trusted or not  
         trusted.  
   
   
         For a personal certificate, TRUST indicates that the  
         certificate can be used to authenticate a user ID.  For a  
         site certificate, TRUST indicates that a certificate is  
         acceptable without authentication.  For a certificate  
         authority certificate, TRUST indicates that the certificate  
         authority can be used to authenticate other certificates.  
   
   
         When a certificate is trusted, it can be used by RACF for  
         its intended purpose (map to a user ID, or treat as a  
         trusted certificate authority or trusted site).  
   
   
         For a certificate authority certificate, a trusted  
         certificate is one that can be used to authenticate a  
         user's certificate by indicating that the entity identified  
         in the certificate (for example, the certificate authority)  
         can issue certificates that this system honors.  This  
         implies that a user can gain access to the system based on  
         the information contained in the certificate if the user's  
         certificate was signed by a trusted certificate authority.  
   
   
         For site certificates, a trusted certificate is one  
         indicating that the entity identified in the certificate  
         (for example, the site) can gain access to the system based  
         on information contained within the certificate.  Since the  
         authority that issued the certificate might not be defined  
         to the system as a certificate authority, this certificate  
         information might not be able to be authenticated.  
   
   
         TRUST should only be specified if the command issuer knows:  
   
   
         *   This is a valid certificate for this user, site, or  
             certificate authority.  
         *   The private key related to this certificate has not been  
             compromised.  
   
   
         If TRUST or NOTRUST are not specified, the trust status is  
         determined from other information.  
   
   
         If the certificate's signature can be verified, the  
         certificate has not expired, and the certificate's validity  
         date range is within the validity date range of the  
         certifying authority's certificate, the trust status is set  
         to the trust status of the certifying authority's  
         certificate.  For self-signed certificates the certificate  
         being added is set to TRUST.  
   
   
         If the certificate has expired, has an incorrect validity date  
         range, or cannot be verified because it either has an unknown  
         encryption algorithm or RACF cannot locate its certifying  
         authority's certificate, the status is set to NOTRUST.  
   
   
         If the certificate's signature is incorrect, the certificate is  
         not added.  
   
   
         This keyword is unrelated to the trusted attribute as defined i  
         the started procedures table (ICHRIN03).  
   
   
   
   
     WITHLABEL('label-name')  
         specifies the label to be associated with the certificate.  Up  
         to 32 characters can be specified.  The label-name can contain  
         blanks and mixed case characters.  
   
   
         This label is used as a "handle" instead of the serial number  
         and issuer's distinguished name.  It can be used to store a  
         descriptive text.  
   
   
         If the value specified in WITHLABEL already exists, RACDCERT  
         returns a message indicating that the label has already been  
         used.  The certificate is not added.  
   
   
         If the user did not specify WITHLABEL, and the data set being  
         processed is PKCS#12, the label is extracted from the PKCS#12  
         package and truncated to 32 characters if required.  
   
   
   
   
     PASSWORD('pkcs12-password')  
         specifies the password that is associated with the PKCS#12  
         certificate package.  This keyword is required if the data set  
         is PKCS#12 and it must not be specified if the data set is not  
         PKCS#12.  
   
   
         Note: The password specified will be visible on the screen,  
         so care should be taken to prevent it from being viewed  
         when entered.  Because PKCS#12 passwords do not follow the  
         normal TSO/E rules for password content, they cannot be  
         suppressed as they normally would be.  
   
   
         The 'pkcs12-password' can be up to 255 characters in length,  
         is case sensitive, and can contain blanks.  
   
   
     ICSF  
         specifies that RACF should attempt to store the private key  
         associated with this certificate in ICSF.  This includes when  
         the key is introduced to RACF by issuing the ADD keyword for  
         PKCSX12 certificate packages, and when an existing certificate  
         profile containing a private key is replaced by issuing the ADD  
         keyword for non-PKCSX12 data sets.  If a private key already  
         exists, it is stored in ICSF anyway.  
   
   
         This keyword is ignored if no private key is involved.  If the  
         ICSF keyword is not specified, or is specified but ICSF is not  
         configured for PKA operations, the key is stored in the RACF  
         database as a non-ICSF key and no error message is displayed.  
         If the key is stored in ICSF, RACF stores a label (which refers  
         to the key) in the RACF database.  
   
   
   
   
   CHECKCERT(data-set-name)  
     specifies that a digital certificate, contained in the data set  
     data-set-name is to be evaluated to see if it has already been  
     added to the RACF database, and associated with a user ID.  
   
   
     CHECKCERT lists the certificate in the specified data set.  If the  
     certificate request is made by a user with proper authority,  
     information in the RACF database pertaining to that certificate is  
     also displayed.  Additionally, an authority check is performed by  
     data management when the data set is opened.  
   
   
     The CHECKCERT keyword also supports the evaluation of site  
     certificates and certificate authority certificates.  It indicates  
     if the certificate is defined and to whom it is defined after  
     checking the resource IRR.DIGTCERT.LIST in the FACILITY class.  
     READ authority is required if the certificate is associated with  
     the user issuing the command.  UPDATE authority is required if the  
     certificate is associated with a user other than the issuer of the  
     command.  CONTROL authority is required if the certificate is a  
     certificate authority or a site certificate.  
   
   
     The CHECKCERT keyword can be used on the same set of certificate  
     packages that is allowed by RACDCERT ADD.  See the ADD keyword  
     on the RACDCERT command for more information.  
   
   
     CHECKCERT ignores the ID() parameter.  
   
   
     Note that the issuer of the RACDCERT command must have READ access  
     to the data-set-name data set to prevent an authorization abend fro  
     occurring when the data set is read.  
   
   
     PASSWORD('pks12-password')  
         specifies the password that is associated with the PKCS#12  
         certificate package.  It is required if the data set contains  
         a PKCS#12 certificate package and it must not be specified if  
         the data set contents are not PKCS#12.  
   
   
         Note: The password specified will be visible on the screen,  
         so care should be taken to prevent it from being viewed  
         when entered.  Because PKCS#12 passwords do not follow the  
         normal TSO/E rules for password content, they cannot be  
         suppressed as they normally would be.  
   
   
         The 'pks12-password' can be up to 255 characters in length, is  
         case sensitive, and can contain blanks.  
   
   
   
   
   ALTER(SERIALNUMBER(serial-number) ISSUERSDN('issuer's-dist-name'))  
   ALTER(LABEL('label-name'))  
     specifies that the status or the label of a digital certificate is  
     to be changed for the specified user ID, certificate authority  
     certificate, or site certificate.  The TRUST, NOTRUST, or NEWLABEL  
     keyword must be specified with the ALTER operand.  If the user has  
     only one certificate, the SERIALNUMBER and ISSUERSDN keywords, or  
     the LABEL keyword, and their associated values can be omitted.  If  
     the user has more than one certificate the LABEL, SERIALNUMBER, or  
     SERIALNUMBER and ISSUERSDN must be used to select which certificate  
     to alter.  When specifying the issuer's distinguished name or the  
     label, the case and blanks displayed when the digital certificate  
     information is listed must be maintained in the ISSUERSDN or the  
     LABEL keyword.  
   
   
     For a description of label-name, see the description of the  
     WITHLABEL keyword for the ADD function.  
   
   
     Note that the only alterable certificate information is the TRUST  
     status or the label of a certificate.  
   
   
   
   
     TRUST|NOTRUST  
         when specified with the ALTER operand, indicates whether the  
         status of the certificate being altered is TRUST or NOTRUST.  I  
         neither TRUST nor NOTRUST is specified with the ALTER operand,  
         no change to the status of the certificate is attempted.  
   
   
         For a personal certificate, TRUST indicates that the certificat  
         can be used to authenticate a user ID.  For a site certificate,  
         TRUST indicates that a certificate is acceptable without  
         authentication.  For a certificate authority certificate, TRUST  
         indicates that the certificate authority can be used to  
         authenticate other certificates.  
   
   
         When a certificate is trusted, it can be used by RACF for its  
         intended purpose (map to a user ID, or treat as a trusted  
         certificate authority or trusted site).  The status of the  
         certificate should only be changed to TRUST if the command  
         issuer knows that this is a valid certificate, and that the  
         private key related to this certificate has not been  
         compromised.  
   
   
         Except for certificate authority certificates, which might stil  
         be used by RACF to authenticate the signatures of other  
         certificates added to RACF, a certificate that is not trusted i  
         not used by RACF.  The status of a certificate should be change  
         to NOTRUST if it is suspected that the certificate's private ke  
         has been compromised.  
   
   
         This keyword is unrelated to the trusted attribute as defined i  
         the started procedures table (ICHRIN03).  
   
   
   
   
     NEWLABEL('new-label-name')  
         specifies the label replacing the previous label (if there was  
         one specified) that is assigned to a certificate.  See the  
         WITHLABEL subkeyword on the ADD keyword for information on  
         label rules.  
   
   
         If new-label-name is the same as label-name, no message is  
         returned.  
   
   
   
   
   DELETE(SERIALNUMBER(serial-number) ISSUERSDN('issuer's-dist-name'))  
   DELETE(LABEL('label-name'))  
     specifies that the digital certificate is to be deleted for the  
     specified user ID, certificate authority certificate, or site  
     certificate.  If the user has only one certificate, the SERIALNUMBE  
     and ISSUERSDN keywords, or the LABEL keyword, and their associated  
     values can be omitted.  If the user has more than one certificate  
     the LABEL, SERIALNUMBER, or SERIALNUMBER and ISSUERSDN must be used  
     to select which certificate to delete.  When specifying the issuer'  
     distinguished name or the label, the mixed-case characters and  
     blanks displayed when the digital certificate information is listed  
     must be maintained in the ISSUERSDN or the LABEL keyword.  
   
   
     The DELETE keyword also supports site and certificate authority  
     certificates, and the deletion of the private key and other  
     certificate data that is stored when the certificate was created.  
   
   
     For a description of label-name, see the description of the  
     WITHLABEL keyword for the ADD function.  
   
   
   
   
   GENCERT(request-data-set-name)  
     creates a digital certificate and potentially a public/private key  
     pair.  Request-data-set-name is the name of an optional data set  
     that contains the PKCS#10 certificate request data.  The request  
     data contains the user's generated public key and X.509  
     distinguished name.  The request data must be signed, DER-encoded,  
     and then Base64 encoded according to the PKCS#10 standard.  
   
   
     If request-data-set-name is specified, RACDCERT does not generate a  
     key pair because this data set contains the user's public key.  
   
   
     Request-data-set-name has characteristics (for example, RECFM)  
     identical to the data set that can be specified on the ADD and  
     CHECKCERT functions.  If request-data-set-name is specified,  
     SIGNWITH must also be specified because the request-data-set-name  
     data set does not contain a private key.  If SIGNWITH is not  
     specified, an informational message is issued.  Note that the  
     issuer of the RACDCERT command must have READ access to the  
     request-data-set-name data set to prevent an authorization abend  
     from occurring when the data set is read.  
   
   
     The certificate that GENCERT creates contains one certificate  
     extension field.  This field, with OID= {2 16 840 1 113730 1 13},  
     is a comment field that contains the value "Created by OS/390  
     Security Server." The subkeywords of the GENCERT function specify  
     the information that is to be contained within the certificate  
     that is being created.  
   
   
     Authority Required for the GENCERT Function: The GENCERT function  
     allows a certificate to be generated and signed.  Effective  
     controls on the user ID that is being associated with the  
     certificate and what certificate is being used to sign the  
     generated certificate are essential.  
   
   
     RACF performs two checks that determine the authority required for  
     the GENCERT command:  
   
   
     1.  How the certificate is being signed, specified with the  
         SIGNWITH keyword.  
   
   
         Users with SPECIAL authority can use the SIGNWITH keyword with  
         any value.  Users without SPECIAL authority must have  
         authority to the IRR.DIGTCERT.GENCERT resource in the FACILITY  
         class.  If SIGNWITH is specified without the CERTAUTH or SITE  
         keyword, the certificate is signed with the certificate  
         identified with the LABEL keyword for the user who is issuing  
         the RACDCERT command.  This requires READ access to the  
         resource IRR.DIGTCERT.GENCERT in the FACILITY class.  If  
         either SIGNWITH(CERTAUTH...) or SIGNWITH(SITE) is specified,  
         CONTROL authority is required to the resource  
         IRR.DIGTCERT.GENCERT in the FACILITY class.  
   
   
         Not specifying SIGNWITH indicates that the certificate is to  
         be self-signed.  The signing key is owned by the certificate  
         itself.  Thus the authority needed for signing is determined  
         by what type of certificate is being generated.  Generating a  
         self-signed certificate for one's self requires READ access to  
         the resource IRR.DIGTCERT.GENCERT in the FACILITY class.  
         Generating a self-signed certificate for another user requires  
         UPDATE access to the resource IRR.DIGTCERT.GENCERT in the  
         FACILITY class.  Generating a self-signed certificate for  
         either SITE or CERTAUTH requires CONTROL access to  
         IRR.DIGTCERT.GENCERT in the FACILITY class.  
   
   
     2.  What type of certificate is being generated, which is  
         specified  with the ID(), SITE or CERTAUTH keywords.  
   
   
         Users with SPECIAL authority can generate a digital  
         certificate for any RACF-defined user or for any certificate  
         authority or site certificate.  Users without SPECIAL  
         authority can generate certificate authority or site  
         certificates if they have CONTROL authority to the resource  
         IRR.DIGTCERT.ADD in the FACILITY class.  Users without SPECIAL  
         authority can generate certificates for other users if they  
         have UPDATE authority to the resource IRR.DIGTCERT.ADD in the  
         FACILITY class.  Users without SPECIAL authority can generate  
         certificates for themselves if they have READ authority to the  
         resource IRR.DIGTCERT.ADD in the FACILITY class.  
   
   
   
   
   
   
 +--------------------------------------------------------------------+  
 |Table 3. Authority Require To Generate a Certificate                |  
 +--------+-------------------+--------------------+------------------+  
 |SIGNWITH| Own Certificate   | Someone Else's     | SITE or CERTAUTH |  
 |        |                   | Certificate        | Certificate      |  
 +--------+-------------------+--------------------+------------------+  
 |SIGNWITH| READ authority to | UPDATE authority   | CONTROL authority|  
 |one's   | IRR.DIGTCERT.ADD  | to                 | to               |  
 |own     | and READ authority| IRR.DIGTCERT.ADD   | IRR.DIGTCERT.ADD |  
 |certific| to                | and READ authority | and READ authorit|  
 |ate     | IRR.DIGTCERT.GENCE| to IRR.DIGTCERT.GEN| y to             |  
 |        | RT                | CERT               | IRR.DIGTCERT.GENC|  
 |        |                   |                    | ERT  
 +--------+-------------------+--------------------+------------------+  
 |SIGNWITH| READ authority to | UPDATE authority   | CONTROL authority|  
 |a SITE  | IRR.DIGTCERT.ADD  | to                 | to               |  
 |or      | and CONTROL       | IRR.DIGTCERT.ADD   | IRR.DIGTCERT.ADD |  
 |CERTAUTH| authority to      | and CONTROL        | and CONTROL      |  
 |certific| IRR.DIGTCERT.GENCE| authority to       | authority to     |  
 |ate     | RT                | IRR.DIGTCERT.GENCER| IRR.DIGTCERT.GENC|  
 |        |                   | T                  | ERT              |  
 +--------+-------------------+--------------------+------------------+  
 |SIGNWITH| READ authority to | UPDATE authority   | CONTROL authority|  
 |not     | IRR.DIGTCERT.ADD  | to                 | to               |  
 |specifie| and READ authority| IRR.DIGTCERT.ADD   | IRR.DIGTCERT.ADD |  
 |d       | to                | and UPDATE         | and CONTROL      |  
 |        | IRR.DIGTCERT.GENCE| authority to       | authority to     |  
 |        | RT                | IRR.DIGTCERT.GENCER| IRR.DIGTCERT.GENC|  
 |        |                   | T                  | ERT              |  
 +--------+-------------------+--------------------+------------------+  
   
   
   
   
     SUBJECTSDN  
         specifies the subject's X.509 distinguished name, which  
         consists of the following components:  
   
   
         Common Name              Specified with the CN subkeyword.  
         Title                    Specified with the T subkeyword.  
         Organizational Unit      Specified with the OU subkeyword.  
                                  Multiple values can be specified for  
                                  the organizational unit.  
         Organization             Specified with the O subkeyword.  
         Locality                 Specified with the L subkeyword.  
         State/Province           Specified with the SP subkeyword.  
         Country                  Specified with the C subkeyword.  
   
   
         SUBJECTSDN completely overrides the values contained in the  
         certificate request in the data set specified with the GENCERT  
         keyword.  
   
   
         Each of the elements in SUBJECTSDN is limited to 64  
         characters.  The subkeyword name (such as CN or OU) is not  
         counted as a part of this 64 character limit.  Each of the  
         SUBJECTSDN subkeywords can be specified only once.  If the  
         certificate being created is a self-signed certificate, the  
         total length of the subject's distinguished name must be 229  
         characters or less.  For non-self-signed certificates, the  
         length of the subject's distinguished name is limited to 255  
         characters.  These lengths refer to the X.509 encoded lengths  
         with the X.509 identifiers (such as C= and CN=) included.  
   
   
         If the SUBJECTSDN name is too long, an informational message  
         is issued and the certificate is not added.  
   
   
         Any printable character that can be mapped to an ASCII  
         character can be specified.  Characters that cannot be mapped,  
         such as the X'4A' (cent sign), are X'00' and are shown by  
         RACDCERT LIST as blanks.  
   
   
         If SUBJECTSDN and request-data-set-name are not specified, the  
         programmer name data from the ID() user (either specified or  
         defaulted), or the programmer name from the SITE or CERTAUTH  
         anchor user IDs (irrsitec or irrcerta) is used as the common  
         name (CN).  If the programmer name is all blanks (X'40'),  
         nulls (X'00'), pound signs (X'7B'), or X'FF' characters, the  
         common name is set to the user ID that is to be associated  
         with this certificate.  
   
   
     SIZE(key-size)  
         specifies the size of the private key expressed in decimal  
         bits.  Valid values range from 512 to 999,999, with the  
         default being 1024.  RACF does not enforce a limit on the SIZE  
         value other than the 512 lower and 999,999 upper limits.  If  
         the SIZE specified is too large to be handled by RACF's key  
         generation code, an informational message is issued and  
         processing stops.  The maximum key size is determined by  
         United States export regulations and is controlled by non-RACF  
         code in OS/390.  
   
   
         Currently, the standard sizes of a key are:  
   
   
         Size   Description  
         512    Low-strength key.  
         768    Medium-strength key.  
         1024   High-strength key.  
   
   
         If the GENCERT function creates a public/private key pair and  
         ICSF is being used to store private keys, GENCERT creates an  
         ICSF key label in the format  
         IRR.DIGTCERT.user-id.cvtsname.ebcdic-stck-value, where userid  
         is the owning user ID, cvtsname is the system name as taken  
         from the CVT, and ebcdic-stck-value is an EBCDIC version of  
         the current store clock value.  If the key is associated with  
         a certificate authority certificate, userid is set to  
         CERTIFAUTH.  If the key is associated with a site certificate,  
         then userid is set to SITECERTIF.  Access to ICSF keys is  
         controlled by profiles in the CSFKEYS and CSFSERV classes.  
         See for more information.  
   
   
     NOTBEFORE(DATE(yyyy-mm-dd) TIME(hh:mm:ss))  
         specifies the local date and time from which the certificate  
         is valid.  If DATE(yyyy-mm-dd) is not specified, it defaults  
         to the current local date.  If TIME(hh:mm:ss) is not  
         specified, it defaults to TIME (00:00:00).  Note that yyyy  
         must be in the range 1950 to 2040.  
   
   
         The time and date values are stored in the certificate as a  
         universal time coordinated (UTC) value.  The calculated UTC  
         value can be incorrect if the NOTBEFORE/NOTAFTER date and time  
         values represent a time that has a different local offset from  
         UTC.  
   
   
         Note that the use of the date format yyyy-mm-dd is valid.  
         However, to aid installations familiar with the existing RACF  
         date format, the value can be specified in the format  
         yyyy/mm/dd.  
   
   
     NOTAFTER(DATE(yyyy-mm-dd) TIME(hh:mm:ss))  
         specifies the local date and time after which the certificate  
         is no longer valid.  If DATE(yyyy-mm-dd) is not specified it  
         defaults to one year from the NOTBEFORE(DATE()) value.  If  
         TIME(hh:mm:ss) is not specified, it defaults to  
         TIME(23:59:59).  Note that yyyy must be in the range 1950 to  
         2040 if specified, and 1951 to 2041 if defaulted.  
   
   
         The time and date values are stored in the certificate as a  
         universal time coordinated (UTC) value.  The calculated UTC  
         value can be incorrect if the NOTBEFORE/NOTAFTER date and time  
         value represent a time that has a different local offset from  
         UTC.  
   
   
         The NOTBEFORE value must be earlier than the NOTAFTER value or  
         an informational message is issued.  
   
   
         Note the use of the date format yyyy-mm-dd is valid.  However,  
         to aid installations familiar with the existing RACF date  
         format, the value can be specified as yyyy/mm/dd.  
   
   
     WITHLABEL('label-name')  
         specifies the label assigned to this certificate.  If  
         specified, this must be unique to the user ID with which the  
         certificate is associated.  If not specified, it defaults in  
         the same manner as the WITHLABEL keyword on the RACDCERT ADD  
         command.  
   
   
         The label-name is stripped of leading and trailing blanks.  
         If a single quotation mark is intended to be part of the  
         label-name, you must use two single quotation marks  
         together for each single quotation mark within the string,  
         and the entire string must then be enclosed within single  
         quotation marks.  
   
   
         See the WITHLABEL subkeyword on the ADD keyword for  
         information on label rules.  
   
   
   
   
     SIGNWITH(CERTAUTH LABEL('label-name'))  
     SIGNWITH(SITE LABEL('label-name'))  
     SIGNWITH(LABEL('label-name'))  
         specifies the certificate with a private key that are signing  
         the certificate.  If not specified, the default is to sign the  
         certificate with the private key of the certificate that is  
         being generated.  This creates a "self-signed" certificate.  
   
   
         If SIGNWITH is specified, it must refer to a certificate that  
         has a private key associated with it.  If no private key is  
         associated with the certificate, an informational message is  
         issued and processing stops.  If request-data-set-name is  
         specified on the GENCERT keyword, SIGNWITH keyword is also  
         required.  
   
   
         Note that self-signed certificates are always trusted, while  
         all other certificates are created with the trust status of  
         the certificate specified in the SIGNWITH keyword.  If the  
         certificate specified in the SIGNWITH keyword is not trusted,  
         an informational message is issued, but the certificate is  
         still generated.  
   
   
     ICSF  
         specifies that RACF should attempt to store the private key  
         associated with this certificate in ICSF.  This includes when  
         the key is generated by RACF through GENCERT without a  
         request-data-set-name and when an existing certificate profile  
         containing a private key is replaced by GENCERT with  
         request-data-set-name.  
   
   
         This keyword is ignored if no private key is involved.  If the  
         ICSF keyword is not specified, or is specified but ICSF is not  
         configured for PKA operations, the key is stored in the RACF  
         database as a non-ICSF key and no error message is displayed.  
         If the key is stored in ICSF, RACF stores a label (which refers  
         to the key) in the RACF database.  
   
   
   
   
   EXPORT(LABEL('label-name'))  
     writes a certificate to a data set.  Label-name identifies the  
     certificate that is being exported.  
   
   
     DSN(output-data-set-name)  
         specifies output-data-set-name, the data set that is to  
         contain the certificate or certificate request.  The data set  
         output-data-set-name is deleted and reallocated if it exists.  
         If you specify EXPORT, DSN must also be specified.  
   
   
     FORMAT(format-type)  
         specifies the format of the exported certificate. Valid values  
         are:  
   
   
         CERTDER        DER encoded X.509 certificate.  
         CERTB64        DER encoded X.509 certificate which has been  
                        encoded using base64.  
   
   
         CERTB64 is the default.  
   
   
   
   
   GENREQ(LABEL('label-name'))  
     creates a PKCS#10 base64-encoded certificate request and writes it  
     to a data set.  This request contains the subject's distinguished  
     name and public key, and is signed with the private key associated  
     with the specified certificate.  Typically, these requests are  
     sent to a certificate authority however, they can also be imported  
     into (and signed by) RACF using the GENCERT keyword with a  
     request-data-set-name.  
   
   
     GENREQ requires that the certificate have a private key associated  
     with it.  If no private key is associated with the certificate, an  
     informational message is issued and processing stops.  Label-name  
     identifies the certificate.  
   
   
     DSN(output-data-set-name)  
         specifies output-data-set-name, the data set that is to  
         contain the certificate or certificate request.  The data set  
         output-data-set-name is deleted and reallocated if it exists.  
         If you specify GENREQ, DSN must also be specified.  
   
   
   
   
   CONNECT(ID(userid) LABEL('label-name') RING(ring-name))  
   CONNECT(SITE LABEL('label-name') RING(ring-name))  
   CONNECT(CERTAUTH LABEL('label-name') RING(ring-name))  
     specifies that an existing digital certificate is being added to  
     an existing key ring.  This certificate must be added to the RACF  
     database by a RACDCERT ADD or RACDCERT GENCERT command prior to  
     issuing the CONNECT command.  ID(userid) indicates that the  
     certificate being added to the key ring is a user certificate, and  
     userid is the user ID that is associated with this certificate.  
     If the ID keyword is not specified, it defaults to the value  
     specified or the default value on the RACDCERT command.  SITE  
     indicates that the certificate being added to the key ring is a  
     site certificate.  CERTAUTH indicates that the certificate being  
     added to the key ring is a certificate authority certificate.  
   
   
     Authority Required for the CONNECT Function: The USAGE keyword  
     allows a certificate to be connected to a ring and used in a  
     manner that differs from the certificate's original use.  For  
     example, a certificate that is a personal certificate, could be  
     used as a certificate authority certificate.  
   
   
     The USAGE keyword is powerful, and must be controlled. The rules fo  
     connection are shown in Table 4, which shows the access control  
     checks that are performed when connecting to one's own key ring, an  
     Table 5, which shows the access control checks that are performed  
     when connecting to someone else's key ring.  
   
   
 +--------------------------------------------------------------------+  
 |Table 4. Authority Required to Connect to One's Own Key Ring        |  
 +----------+-------------------+-------------------+-----------------+  
 |USAGE     | Own Certificate   | Someone Else's    | SITE or CERTAUTH|  
 |          |                   | Certificate       | Certificate     |  
 +----------+-------------------+-------------------+-----------------+  
 |PERSONAL  | READ authority to | UPDATE authority  | UPDATE authority|  
 |          | IRR.DIGTCERT.CONNE| to                | to              |  
 |          | CT                | IRR.DIGTCERT.CONNE| IRR.DIGTCERT.CON|  
 |          |                   | CT                | NECT            |  
 +----------+-------------------+-------------------+-----------------+  
 |SITE/CERTA| CONTROL authority | CONTROL authority | UPDATE authority|  
 |UTH       | to                | to                | to              |  
 |          | IRR.DIGTCERT.ADD  | IRR.DIGTCERT.ADD  | IRR.DIGTCERT.CON|  
 |          | and READ          | and UPDATE        | NECT            |  
 |          | authority to      | authority to      |                 |  
 |          | IRR.DIGTCERT.CONNE| IRR.DIGTCERT.CONNE|                 |  
 |          | CT                | CT                |                 |  
 +----------+-------------------+-------------------+-----------------+  
   
   
   
   
 +--------------------------------------------------------------------+  
 |Table 5. Authority Required To Connect to Someone Else's Key Ring   |  
 +---------+-------------------+-------------------+------------------+  
 |USAGE    | Own Certificate   | Someone Else's    | SITE or CERTAUTH |  
 |         |                   | Certificate       | Certificate      |  
 +---------+-------------------+-------------------+------------------+  
 |PERSONAL | CONTROL authority | CONTROL authority | CONTROL authority|  
 |         | to                | to                | to               |  
 |         | IRR.DIGTCERT.CONNE| IRR.DIGTCERT.CONNE| IRR.DIGTCERT.CONN|  
 |         | CT                | CT                | CT               |  
 +---------+-------------------+-------------------+------------------+  
 |SITE/CERT| CONTROL authority | CONTROL authority | CONTROL authority|  
 |AUTH     | to                | to                | to               |  
 |         | IRR.DIGTCERT.ADD  | IRR.DIGTCERT.ADD  | IRR.DIGTCERT.CONN|  
 |         | and CONTROL       | and CONTROL       | ECT              |  
 |         | authority to      | authority to      |                  |  
 |         | IRR.DIGTCERT.CONNE| IRR.DIGTCERT.CONNE|                  |  
 |         | CT                | CT                |                  |  
 +---------+-------------------+-------------------+------------------+  
   
   
     See the USAGE subkeyword on the RACDCERT command for additional  
     information on the authority required to change a certificate's  
     usage.  
   
   
     LABEL('label-name')  
         specifies the certificate that is being added to the key ring.  
         When specifiying the CONNECT keyword, LABEL must also be  
         specified.  
   
   
     RING(ring-name)  
         specifies the ring to which this certificate is being added.  
         When specifiying the CONNECT keyword, RING must also be  
         specified.  
   
   
     DEFAULT  
         specifies if the certificate is the default certificate for  
         the ring.  Only one certificate within the key ring can be the  
         default certificate.  If a default certificate already exists,  
         its DEFAULT status is removed, and the specified certificate  
         becomes the default certificate.  If you want the specified  
         certificate to be the default, DEFAULT must be explicitly  
         specified.  
   
   
         If you have a key ring with a default certificate and you want  
         to remove the default status of the certificate without  
         defining another certificate as the default certificate,  
         CONNECT the certificate again without specifying the DEFAULT  
         keyword.  
   
   
     USAGE(PERSONAL)  
     USAGE(SITE)  
     USAGE(CERTAUTH)  
         specifies how this certificate is used within the specified  
         ring.  If no usage is specified, the usage is the same as the  
         certificate that is being connected.  
   
   
         The USAGE keyword allows the altering of the trust policy  
         within the confines of a specific key ring.  For example, a  
         CERTAUTH certificate connected with USAGE(PERSONAL) can be  
         used to demote a certificate authority certificate in order to  
         insure that it is not used as a certificate authority in this  
         ring.  It can be used as a personal certificate if a private  
         key is present.  However, typically, one would not be present.  
         Consequently, connecting a CERTAUTH certificate as  
         USAGE(PERSONAL) is a way of marking it NOTRUST for this key  
         ring only.  Also, a personal certificate connected with  
         USAGE(CERTAUTH) can be used to promote an ordinary user  
         certificate to a certificate authority certificate.  It can  
         then be used to authenticate user certificates for this key  
         ring only.  
   
   
         For the sake of consistency, other certificate and USAGE  
         variations are supported.  However, there is currently no  
         practical application for them.  
   
   
         When using the USAGE keyword to change the usage of a  
         certificate, such as is done when a PERSONAL certificate is  
         being used as a SITE or CERTAUTH certificate, RACDCERT must  
         ensure that you have the ability to define a SITE or CERTAUTH  
         certificate by authenticating that the command issuer has  
         CONTROL authority to the resource IRR.DIGTCERT.ADD in the  
         FACILITY class.  This ensures that a user cannot bypass the  
         installation security policy through the use of USAGE.  
   
   
   
   
   REMOVE(ID(userid) LABEL('label-name') RING(ring-name))  
   REMOVE(SITE LABEL('label-name') RING(ring-name))  
   REMOVE(CERTAUTH LABEL('label-name') RING(ring-name))  
     specifies that a digital certificate is being removed from a key  
     ring.  ID(userid) indicates that the certificate being removed is  
     a user certificate, and userid is the user ID that is associated  
     with this certificate.  If the ID keyword is not specified, it  
     defaults to the value that is specified or defaulted to on the  
     RACDCERT command.  SITE indicates that this is a site certificate,  
     and CERTAUTH indicates that this is a certificate authority  
     certificate.  
   
   
     LABEL('label-name')  
         identifies the certificate that is being removed from the key  
         ring.  When specifiying the REMOVE keyword, LABEL must also be  
         specified.  
   
   
     RING(ring-name)  
         identifies the ring from which this certificate is being  
         removed.  When specifiying the REMOVE keyword, RING must also  
         be specified.  
   
   
   
   
   ADDRING(ring-name)  
     specifies the creation of a key ring.  Ring-name is the name of  
     the key ring being created.  This key ring must not already exist  
     for this user.  Key ring names become RACF profiles in the  
     DIGTRING class, and can contain only characters that are allowed  
     in RACF profile names.  Although asterisks are allowed in  
     ring-names, a single asterisk is not allowed.  
   
   
     Lower case characters are permitted.  A key ring name can be up to  
     237 characters in length.  Since only user IDs can have key rings,  
     neither "CERTAUTH" nor "SITE" can be specified with ADDRING.  
   
   
   DELRING(ring-name)  
     specifies the deletion of a key ring.  Ring-name is the name of  
     the key ring.  Since only user IDs can have key rings, neither  
     "CERTAUTH" nor "SITE" can be specified with DELRING.  
   
   
     Note that when a DELUSER command is issued against a user ID, all  
     of the key rings that are owned by that user ID are also deleted.  
   
   
   LISTRING  
   LISTRING(ring-name | *)  
     specifies listing a key ring.  Ring-name is the name of the key  
     ring.  To list all rings that are associated with a particular  
     user, LISTRING (*) must be specified.  For each certificate in the  
     ring, the following information is displayed:  
   
   
     *   The ring name,  
     *   The owner of the certificate (ID(name), CERTAUTH, or SITE)  
     *   The label assigned to the certificate,  
     *   The DEFAULT status of the certificate within the ring, and  
     *   The usage within the ring.  
   
   
   
   
     Since only user IDs can have key rings, neither "CERTAUTH" nor  
     "SITE" can be specified with LISTRING.  
   
   
   MAP  
   MAP(data-set-name)  
     specifies that a certificate name filter is to be defined.  It  
     results in the creation of a profile in the DIGTNMAP class.  
     DIGTNMAP profiles are used as filters when a user attempts to acces  
     the system using a digital certificate.  The 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.  This user ID is specified with the  
     ID keyword or specified in DIGTCRIT profiles if MULTIID is  
     specified.  When you specify MAP, you must also specify IDNFILTER,  
     SDNFILTER, or both.  
   
   
     A data set name can be specified with the MAP keyword.  
     Data-set-name 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 the ADD keyword for acceptable certificate formats.  
   
   
     Data-set-name has the same characteristics (for example,  
     RECFM) as the dataset 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.  
   
   
     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 OS/390  
         Security Server (RACF) Security Administrator's Guide.  
   
   
         When specified without data-set-name, 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:  
   
   
              an address type format:  
   
   
                       component.component.component.component...  
   
   
              Or, more specifically:  
   
   
                       qualifier1=node1.qualifier2=node2....qualifiern=  
                       noden  
   
   
              For example:  
   
   
                       IDNFILTER('OU=Class 1 Certificate.O=BobsCertAuth,  
                       Inc.L=internet.C=US')  
         The value specified for IDNFILTER must begin with a prefix foun  
         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.  
         Since 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 for 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  
          following issuer:  
   
   
                  OU=Class 1 Certificate.O=BobsCertAuth, Inc.L=  
                  internet.C=US  
   
   
          and you want all certificates issued by  
   
   
                  BobsCertAuth  
   
   
          to be selected by this filter, you must specify:  
   
   
                  IDNFILTER('O=BobsCertAuth')  
   
   
           Without the data set containing the certificate, you need  
           to enter the following to produce the same result:  
   
   
                  IDNFILTER('O=BobsCertAuth, Inc.L=internet.C=US')  
   
   
           A maximum of 255 characters can be entered for IDNFILTER.  
           When a starting point value is specified for a certificate  
           contained in a data set, there cannot be more than 255  
           characters between the starting point and the end of the  
           issuer's name in the certificate.  
   
   
           IDNFILTER is optional if SDNFILTER is specified.  If IDNFILTE  
           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 lis  
           above.  This allows the use of certificates from a certificat  
           authority that chooses to include non-standard data in the  
           issuer's distinguished name.  
   
   
     SDNFILTER('subject's-distinguished-name-filter')  
         specifies the significant portion of the subject's distinguishe  
         name.  This is the part of the name that will be 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 I  
         with a digital certificate, see OS/390 Security Server (RACF)  
         Security Administrator's Guide.  
   
   
         When specified without data-set-name for 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 simila  
         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....qualifiern=  
                  noden  
   
   
              For example:  
   
   
                  SDNFILTER('CN=Bob  
                  Smith.OU=BobsAccountingDept.O=BobsMart.L=internet')  
   
   
         The value specified for SDNFILTER must begin with a prefix foun  
         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.  
         Since 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 for the MAP keyword, th  
         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 ha  
         the following subject:  
   
   
                  CN=Bob Smith.OU=BobsAccountingDept.O=BobsMart.L=  
                  internet  
   
   
          and you want all certificates for anyone in  
   
   
                  BobsAccountingDept  
   
   
         to be selected by this filter, you must specify:  
   
   
                  SDNFILTER('OU=BobsAcc')  
   
   
         Without the data set containing the certificate, you need  
         to enter the following to produce the same result:  
   
   
                  SDNFILTER('OU=BobsAccountingDept.O=BobsMart.L  
                  =internet')  
   
   
         A maximum of 255 characters can be entered for SDNFILTER.  
         When a starting point value is specified for a certificate  
         contained in a data set, there cannot be more than 255  
         characters between the starting point and ending point of  
         the subject's name in the certificate.  
   
   
         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.  A subject's name cannot be used in a filter tha  
         contains only a partial issuer's name. Note that the subject's  
         name can be partial.  
   
   
     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 freeform text.  These  
         variable names begin with an ampersand (&) and end with a  
         period.  The freeform text should identify the variables  
         contained in the template:  
   
   
                  variable-name1=-name1.variable-name2=-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).  The SYSID user ID is determined  
         by RACF, while the APPLID user ID must be supplied on InitACEE.  
         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 par  
         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 SI  
         parameter of the SMFPRMxx member of SYS1.PARMLIB.  This value  
         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 activ  
         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. However, criteria names should not be specified on  
         RACDCERT unless you are instructed to do so in documentation fo  
         the application.  
   
   
         A maximum of 255 characters can be entered when specifying the  
         CRITERIA keyword.  The values can be entered in any case, but  
         are made upper case by the RACDCERT command because they must  
         match upper case profile names in the DIGTCRIT class to be  
         effective.  When specifying the criteria value, note that the  
         maximum profile name length in the DIGTCRIT class is 246.  No  
         criteria can be associated with a user ID (specified with the I  
         keyword or defaulted to the command issuer's user ID), nor with  
         a certificate authority or site certificate.  
   
   
         Note that 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 keywor  
         for the RACDCERT ADD command.  
   
   
         Up to 32 characters can be specified for label-name.  It can  
         contain embedded 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, you must use two  
         single quotation marks together for each single quotation mark  
         within the string, and the entire string must then be enclosed  
         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 use  
         accessing the system.  If neither TRUST nor NOTRUST is  
         specified, the default is TRUST.  
   
   
   ALTMAP  
   ALTMAP(LABEL('label-name'))  
     changes the label, trust status, or criteria associated with the  
     mapping identified by label-name.  Specifying label name is require  
     if more than one mapping is associated with the user ID.  If  
     NEWLABEL, NEWCRITERIA, or TRUST/NOTRUST is not specified, the  
     mapping is not altered.  
   
   
     NEWCRITERIA(criteria-profile-name-template)  
         when specified with ALTMAP and MULTIID, NEWCRITERIA changes the  
         template associated with this mapping.  New DIGTCRIT profiles  
         must be created to match the new template profile names.  
         NEWCRITERIA can only be set for MULTIID.  
   
   
     NEWLABEL('new-label-name')  
         when specified with ALTMAP, NEWLABEL changes the label of  
         the mapping identified by label-name for the user ID or  
         MULTIID specified to a new-label-name.  If new-label-name  
         is the same as label-name, the label is not changed and no  
         message is issued.  
   
   
      TRUST | NOTRUST  
          when specified with ALTMAP, indicates whether this mapping  
          can be used to associate a user ID to a certificate  
          presented by a user accessing the system.  
   
   
   DELMAP  
   DELMAP(LABEL('label-name'))  
     deletes the mapping identified by label-name for the  
     specified user ID.  Specificying label name is required if  
     more than one mapping is associated with the user ID.  Note  
     that mappings might also be deleted as part of DELUSER processing.  
   
   
   LISTMAP  
   LISTMAP(LABEL('label-name'))  
     The LISTMAP keyword lists information about the mapping  
     identified by label-name for the user ID specified.  To  
     list all mappings associated with the user ID, do not  
     specify LABEL.  
   
   
      Consider the following command:  
   
   
          RACDCERT ID(NET1ID) LISTMAP  
   
   
      This user ID has one mapping associated with it.  
   
   
      Consider the following command:  
   
   
          RACDCERT MULTIID LISTMAP(LABEL('NewAPPL ID Mapping'))  
   
   
      This user ID has several mappings associated with it, but only the  
      one with this label name will be listed.  
   
   
      Note that it is also possible for LISTMAP to encounter an error in  
      locating filter information in a DIGTNMAP profile. For example, if  
      a previous RACDCERT command did not complete successfully due to a  
      system failure, or the issuer attentioning out of the command, the  
      user profile may still indicate that a filter exists, but the  
      DIGTNMAP profile is not there.  If the DIGTNMAP information is not  
      found, the LISTMAP output will contain the text:  
   
   
             Filter with label label-name not found.  
   
   
      If this text is present in the LISTMAP output, a RACDERT DELMAP  
      specifying this label can be issued to remove the residual filter  
      information from the user's profile.  
 READY  
 END