z/OS Security Server RACF Callable Services
Previous topic | Next topic | Contents | Contact z/OS | Library | PDF


Usage notes

z/OS Security Server RACF Callable Services
SA23-2293-00

  1. This service is intended for use by z/OS application servers, to programmatically request the fulfillment of an X.509 V.3 certificate request.
  2. An audit record will be created as a result of invoking this service which will indicate the success or failure of the attempt.
  3. For GENCERT, the certificate generation provider is designated by the first four characters of the CertPlist SignWith value, SAF: for SAF requests, PKI: for PKI Services requests. For EXPORT, the caller designates the certificate generation provider indirectly by providing the Certificate ID returned by the provider. For all other functions, PKI Services is used exclusively. There is no SAF equivalent for these functions.
  4. TheCertPlist for the PREREGISTER, GENCERT REQCERT, REQDETAILS, MODIFYREQS, VERIFY, REQRENEW, GENRENEW, and CERTDETAILS functions consists of triplets which consist of field name, field length, and data. The field name is a fixed field, 12 characters in length, and the field name must be left-aligned, and padded with blanks. The data length is also a fixed width field of 4 bytes which contain an integer which represents the length of the following field data.
  5. The R_PKIServ service requires the caller to preallocate the 57-byte storage area that will hold the certificate ID returned on a successful GENCERT, REQRENEW, GENRENEW, or REQCERT. When successful, RACF® will update the first byte with the actual length of the CertID. The entire 57 areas must be provided for EXPORT even if the actual CertId is smaller than that.
  6. The R_PKIServ service requires the caller to preallocate the storage that will hold the certificate being extracted through the EXPORT function code. On successful certificate retrieval, RACF will update the CertAnchorLen field with the actual length of the certificate. If the storage area is too small to hold the certificate, then RACF will fail the request and update the CertAnchorLen field in the EXPORT request-specific parameter list as supplied by the caller of this service. The caller is responsible for releasing and obtaining a new area of virtual storage that is the size as specified by RACF, and retrying the EXPORT operation.
    Note: The retry might have to be performed more than once.
  7. The R_PKIServ service requires the caller to preallocate the storage that will hold the results list being retrieved through the QUERYREQS, QUERYCERTS, and QRECOVER function codes. On success, RACF will update the ResultsListLen field with the actual length of the data returned. If the storage area is too small to hold the data, then RACF will fail the request and update the ResultsListLen field in the request-specific parameter list as supplied by the caller of this service. The caller is responsible for releasing and obtaining a new area of virtual storage that is the size as specified by RACF, and retrying the operation.
  8. The R_PKIServ service requires the caller to preallocate the storage that will hold the summary list being retrieved through the VERIFY, REQDETAILS, and CERTDETAILS function codes. On success, RACF will update the SumListLen field with the actual length of the data returned. If the storage area is too small to hold the data, then RACF will fail the request and update the SumListLen field in the request-specific parameter list as supplied by the caller of this service. The caller is responsible for releasing and obtaining a new area of virtual storage that is the size as specified by RACF, and retrying the operation.
  9. The R_PKIServ service requires the caller to preallocate the storage that will hold the CertPlist being retrieved through the VERIFY, REQDETAILS, and CERTDETAILS function codes. On success, RACF will update the CertPListLen field with the actual length of the data returned. If the storage area is too small to hold the data, then RACF will fail the request and update the CertPListLen field in the request-specific parameter list as supplied by the caller of this service. The caller is responsible for releasing and obtaining a new area of virtual storage that is the size as specified by RACF, and retrying the operation.
  10. The actual values for the eyecatchers in the function-specific parameters lists and the DiagInfo field in the CertPlist for GENCERT, MODIFYREQS, GENRENEW, REQRENEW, and REQCERT invocations are determined by the caller.
  11. For PREREGISTER, GENCERT, REQCERT, GENRENEW, REQRENEW, and MODIFYREQS CertPlist field errors (reason codes 48, 52, 56, and 76), RACF will update the DiagInfo field with the name of the field in error. The length will also be updated.
  12. For MODIFYREQS and MODIFYCERTS state change errors (reason code 72), RACF will update the CertIds or SerialNums field with the list of Certificate IDs or Serial Numbers that could not be updated. The length field will also be updated to reflect the size of the data being returned.
  13. For GENCERT and REQCERT PKI Services requests, the special user IDs that start with lowercase 'irr' may not be specified for the CertPlist field UserId.
  14. For PREREGISTER, GENCERT, REQCERT, GENRENEW, REQRENEW, and MODIFYREQS certificate generation errors (reason code 60) RACF will update the DiagInfo field with a product-specific diagnostic message. For SAF requests, the message will have the following format: error-description (message-ID), where message-ID is the RACDCERT error message ID that is closely related to this error: 
    No matching certificate was found for "SignWith" (IRRD107I)
"PublicKey" encoding does not have a valid signature (IRRD112I)
"PublicKey" encoding is not valid (IRRD104I)
"PublicKey" encoding contains an unsupport encryption algorithm (IRRD118I)
"PublicKey" extension not permitted for CERTAUTH certificate (IRRD126I)
"Label" specified is already in use (IRRD111I)
"SignWith" requires a certificate with an associated private key (IRRD128I)
Certificate cannot be added.  Serial number for this CA already in use (IRRD109I)
SignWith key is an ICSF key.  ICSF is not operational (IRRD135I)
Subject's name exceeds the maximum allowed characters, which is 255 (IRRD131I)
    Additionally, for successful certificate generation (reason code 0), RACF may also update the DiagInfo field with one of the following informational diagnostic messages: 
    Inconsistency detected.  Signing certificate is not trusted (IRRD132I)
Inconsistency detected.  Signing certificate's date range is incorrect (IRRD113I)

    RACF may also issue its own diagnostic messages when acting as an RA for PKI Services.

    For further information see z/OS Security Server RACF Command Language Reference and z/OS Security Server RACF Messages and Codes. It is expected that other security products that may be installed in place of RACF have their own product-specific diagnostic data.

  15. For GENCERT, REQCERT, PREREGISTER, and MODIFYREQS, RACF forms the subject's distinguished name in the following order:
    • SerialNumber
    • UnstructAddr
    • UnstructName
    • EmailAddr
    • Mail (formally Email)
    • DNQualifier
    • Uid
    • CommonName
    • Title
    • DomainName
    • OrgUnits (in the order that they appear in the CertPlist)
    • Start of change Business Category End of change
    • Org
    • Start of change Jurisdiction Locality End of change
    • Start of change Jurisdiction StateProv End of change
    • Start of change Jurisdiction Country End of change
    • Street
    • Locality
    • StateProv
    • PostalCode
    • Country
    Except as noted below, only those portions of the name specified in the CertPlist will appear in the certificate. For GENCERT and REQCERT, if no name fields are specified in the CertPlist, the name is taken directly from the PublicKey field. For SCEPREQ, the name is always taken from the initial PKCS #10 request.
  16. Different certificate generation providers may produce certificates with different extension values. To determine what certificate extensions will be created by a given provider, see the provider's supporting documentation, z/OS Security Server RACF Security Administrator's Guide, and z/OS Security Server RACF Command Language Reference, or z/OS Cryptographic Services PKI Services Guide and Reference.
  17. For GENCERT and REQCERT, if CommonName is specified with a null value (length 0), RACF will use the PGMRNAME field from the RACF user profile as determined by the UserID field for this request. If PGMRNAME is null, the common name will be of the form of RACF User ID:<user's-racf-identity>, for example RACF UserID:JOHNDOE. The above formula is also used for SAF requests if none of the subject's distinguished name fields are specified (CommonName, Title, OrgUnit, Org, Locality, StateProv, or Country) and the PublicKey field contains no information.
  18. For PREREGISTER, GENCERT, REQCERT, GENRENEW, REQRENEW, and MODIFYREQS, all CertPlist fields specified must have a non-zero length except for CommonName, which may be null for GENCERT and REQCERT only.
  19. For PREREGISTER, GENCERT, REQCERT, GENRENEW, REQRENEW, and MODIFYREQS, OrgUnit, HostIdMap, AuthInfoAcc, Critical, KeyUsage, and ExtKeyUsage may be repeated, where applicable. For all other CertPlist fields if multiple occurrences are found, the last one will be used.
  20. For GENCERTand REQCERT, the PublicKey must be either a Netscape Navigator key, a Microsoft Internet Explorer key, or a true PKCS #10 certificate request.
  21. For successful EXPORTs where the CertId is not "PKICACERT", the certificate returned in the CertAnchor area is either a base64 encoded DER X509 certificate, a base64 encoded DER PKCS #7 certificate chain, or a DER PKCS #12 certificate package. The base64 data is wrapped with the standard "-----BEGIN CERTIFICATE-----" header and "-----END CERTIFICATE-----" footer. For RACF requests, the returned certificate is always X.509. For PKI Services requests, if the key was not generated by PKI Services, the returned certificate will be packaged as a PKCS #7 certificate chain if at least one hierarchy certificate can be located under the CERTAUTH category and either subsequent access checking is not being performed or the access check user ID has CONTROL authority to IRR.DIGTCERT.EXPORT in the FACILITY Class or is RACF SPECIAL. Otherwise, an X.509 certificate is returned. If the key was generated by PKI Services, the returned certificate will be packaged as a PKCS #12 package with its issuer's certificate. The return code will indicate which format is being returned.

    For successful EXPORTs where the CertId is "PKICACERT", the certificate returned in the CertAnchor area is either the DER-encoded X.509 PKI Services CA certificate or a DER-encoded PKCS #7 certificate chain containing the PKI Services CA and RA certificate. The reason code will indicate which is being returned.

  22. For PREREGISTER, GENCERT, REQCERT, GENRENEW, REQRENEW, and MODIFYREQS no validity checking is done for the following fields: AltEmail, AltDomain, AltURI. Additionally, AltPAddr, Mail (formerly Email), EmailAddr, NotifyEmail, and HostIdMap are checked form only (AltPAddr must be in dotted decimal form as per IP Version 4. Mail, Emailaddr, NotifyEmail, and HostIdMap must be in <subject-id>@<host-name>form).
  23. For MODIFYREQS, if a modification plist (CertPlist) is specified, all the existing extension request values (KeyUsage, ExtKeyUsage, AltIPAddr, AltURI, AltEmail, AltDomain, HostIdMap, CertPolicies, AuthInfoAcc, and Critical) and validity period values are completely replaced by the new values. Thus if the intent is to alter just one field, the unchanged fields must also be provided. The subject's distinguished name fields work slightly differently. If no subject's distinguished name fields are specified in the modification plist, the existing values are retained. If any subject's distinguished name fields are specified, the name is completely replaced by the values specified.
  24. For REQDETAILS, the subject name fields are not returned in the CertPlist if the request has a status of “Preregistered” or if the subject distinguished name does not conform to RACF name standards regarding RDN qualifiers and order. See usage note 15 for more information.
  25. Start of change SAF return code 8, RACF return code 8, RACF reason code 4 indicates a problem with the value specified for either the Number_parameters or Attributes parameter; or the memory required for parameter storage exceeds system application limits. End of change
  26. The R_PKIServ callable service creates SMF type 80 records, with event codes of 69, 70, 72, 73, 74, and 89. RACF audits the invocations of this callable service under the following circumstances:
    1. UAUDIT is in effect for the user
    2. The user has SPECIAL authority and SETROPTS SAUDIT is in effect
    3. The request is successful and SETROPTS AUDIT(USER) is in effect
    4. The request fails due to insufficient authorization

    For detailed information about the SMF records produced, see z/OS Security Server RACF Macros and Interfaces.

  27. For GENCERT and REQCERT, if the CertPlist fields Email and NotifyEmail are specified together, they must have the same value. Otherwise, the service will fail with reason code 76. For GENRENEW and REQRENEW, if the CertPlist field NotifyEmail is specified and the subject's distinguished name being renewed contains the MAIL attribute, the two values must be the same. Otherwise, the service will fail with reason code 76. In either case "NotifyEmail" is returned in the DiagInfo area as the field name in error.
  28. For MODIFYREQS, if a modification parameter list (CertPlist) is specified and it contains the field Email and NotifyEmail was specified on the original request, the new Email value will replace the old NotifyEmail value.
  29. For PREREGISTER, GENCERT, REQCERT and MODIFYREQS, if the CertPlist field Subject Alternative Name contains multiple otherName entries, each entry should contain a unique object identifier, though R_PKIServ will not check for the duplication.
  30. The supported characters in the CertPlist values are:
    1. Printable string:
      • Country
      • SerialNumber
      • DNQualifier
      • Start of change JurisdictionCountry End of change
    2. IA5 string (Basic Latin):
      • DomainName
      • Mail / Email
      • NotifyEmail
      • EmailAddr
      • AltEmail
      • AltDomain
      • AltURI
      • AuthInfoAcc
      • HostIdMap
    3. Basic Latin and Latin-1 supplement:
      • CommonName
      • Title
      • OrgUnit
      • Org
      • Street
      • Locality
      • StateProv
      • PostalCode
      • UID
      • UnstructName
      • UnstructAddr
      • EmailAddr
      • Start of change BusinessCategory End of change
      • Start of change JurisdictionLocality End of change
      • Start of change JurisdictionStateProv End of change
Parent topic: R_PKIServ (IRRSPX00): Request public key infrastructure (PKI) services

Go to the previous page Go to the next page

Notices | Terms of use | Support | Contact z/OS | zFavorites



Copyright IBM Corporation 1990, 2014