Parameters

Work_area
The name of a 1024-byte work area for SAF. The work area must be in the primary address space.
ALET
The name of a word containing the ALET for the following parameter. Each parameter must have an ALET specified. Each ALET can be different. The words containing the ALETs must be in the primary address space.
SAF_Return_Code
The name of a fullword in which the SAF router returns the SAF return code.
RACF_Return_Code
The name of a fullword in which the service routine stores the return code.
RACF_Reason_Code
The name of a fullword in which the service routine stores the reason code.
Number_parameters
Specifies the name of a fullword that contains the number of parameters that follow in the non-request specific portion of the R_PKIServ callable service invocation. If the CA_domain parameter is specified, Number_parameters must be set to 6. Otherwise, Number_parameters must be set to 5.
Function_code
The name of a 2-byte area containing the function code. The function code has one of the following values:
End user functions:
  • X'0001'-Generate a basic X.509V3 certificate using the application-provided data pointed to by the function-specific parameter list (Function name GENCERT).
  • X'0002'-Extract certificate by certificate request ID (Function name EXPORT).
  • X'0009'-Submit a request for a X.509V3 certificate using the application provided data pointed to by the function-specific parameter list. Similar to function 1, except that the request would be pending the approval of the PKI Services administrator (Function name REQCERT).
  • X'000A'-Verify that certificate was issued by this PKI Services CA and return certificate fields (Function name VERIFY).
  • X'000B'-Revoke a PKI Services certificate (Function name REVOKE).
  • X'000C'-Generate a renewal PKI Services certificate (Function name GENRENEW).
  • X'000D'-Request a renewal certificate from PKI Services (Function name REQRENEW).
  • X'000E' -Get an Online Certificate Status Protocol (OCSP) response from the PKI Services responder (Function name RESPOND).
  • X'000F' -Submit a request to PKI Services using SCEP (Function name SCEPREQ).
  • X'0011'-List certificates whose key pairs were generated by PKI services for a particular requester. The requester is identified by the email address and pass phrase provided when generating the certificates and key pairs. (Function name QRECOVER).
Administrative functions-
  • X'0003'-Query PKI Services for certificate requests (Function name QUERYREQS).
  • X'0004'-Get detailed information pertaining to one PKI Services certificate request (Function name REQDETAILS).
  • X'0005'-Modify PKI Services certificate requests (Function name MODIFYREQS).
  • X'0006'-Query PKI Services issued certificates (Function name QUERYCERTS).
  • X'0007'-Get detailed information pertaining to one PKI Services issued certificate (Function name CERTDETAILS).
  • X'0008'-Modify PKI Services issued certificates (Function name MODIFYCERTS).
  • X'0010'-Preregister a user (Function name PREREGISTER).
Attributes
The name of a 4-byte area containing bit settings that direct the function to be performed. This is a reserved field that must be specified. The bit settings are mapped as follows:
  • Functions GENCERT (X'0001')
    • - x'80000000' - Do not return control until the certificate has been generated. The request will be purged if unsuccessful for any reason.
    • - x'C0000000' - Indicate the request is an Enrollment over Secure Transport (EST) request.
    • - x'E0000000' - Indicate the request is an Enrollment over Secure Transport (EST) request that needs to have a preregistration record.
  • GENRENEW (X'000C')
    • - x'40000000' - Indicate the request is an Enrollment over Secure Transport (EST) request.
  • Functions EXPORT (X'0002')
    • - x'80000000' - Indicate a DER-encoded PKCS#7 package which only contains the end-entity certificate is to be returned for Enrollment over Secure Transport (EST) request.
  • All other bit positions are reserved and must be set to zero.
Log_string
The name of an area that consists of a 1-byte length field followed by character data to be included in any audit records that are created as a result of the R_PKIServ invocation. The first eight bytes of the Log_string data specified on a GENCERT and RENEW request is also used as application data(ApplData) to be stored with the certificate. If not specified, the length must equal 0.
Parmlist_version
The name of a 4-byte input value which contains the version number for the following input field, Function_parmlist. To take full advantage of the support provided by this release, this field should be set to 1 for the EXPORT, Start of changeQUERYCERTS, and CERTDETIALS functions, and should be set to 2 for theEnd of change MODIFYCERTS and MODIFYREQS functions. For all other functions this field must be set to 0.
Function_parmlist
Specifies the name of the function code specific parameter list for the Function_code specified:
Table 1. Function_parmlist for GENCERT
Field Attributes Usage Description
Eyecatcher 8 characters In Eyecatcher, 8 characters left-aligned blank filled. Actual value set by invoker, for example 'GENCERT'.
CertPlistLen 4-byte length In Describes the length in bytes of the certificate generation plist.
CertPlist Address of In The name of the area which is the CertGen request parameter list. This area maps the specific name, length, address/data values which are used in satisfying the certificate request for the specified user. Also, see Table 2.
Certid Address of In/Out Points to a 57-byte area, in which the first byte will contain the actual length on return of the certificate request ID. The storage address specified must be obtained by the caller, and freed by the caller. The returned certificate request ID is used to extract the completed certificate, if the request has been accepted by RACF®.
The GENCERT and REQCERT functions have in essence two connected parameter list areas; the function-specific parameter list as defined above and the CertGen request parameter list (CertPlist) containing specific certificate field information. CertPlist is a list of ordered triplets that consists of name, length, and data value. The field name is a fixed 12-character field, case sensitive, left-aligned, and padded with blanks. The length field is a binary 4-byte value, which qualifies the length of the data item. Note that all data values are EBCDIC character data unless otherwise indicated. The following table describes the valid certificate request fields:
Table 2. CertPlist for GENCERT and REQCERT
Field name Max length Description
DiagInfo 80 bytes (exactly) EyeCatcher to identify this request in virtual storage for diagnostic reasons. For certificate generation warnings and errors, RACF will update the field with diagnostic information. The length will be updated as well. Required field must be the first field in the CertPlist.
SerialNumber 64 bytes Serial number, or registration number, of the subject device. Optional. No default. Only valid with PKI Services requests.
UnstructAddr 64 bytes Unstructured address of the subject device. Optional. No default. Only valid with PKI Services requests.
UnstructName 64 bytes Unstructured name of the subject device. Optional. No default. Only valid with PKI Services requests.
EmailAddr 64 bytes Subject’s email address for distinguished name EMAIL= attribute. Optional. No default. Only valid with PKI Services requests.
Mail or Email 64 bytes Subject’s email address for distinguished name MAIL= attribute. Optional. No default. Only valid with PKI Services requests. (Field name “Email” is deprecated, use “Mail”)
DNQualifier 64 bytes Subject’s Distinguished Name Qualifier. Optional. No default. Only valid with PKI Services requests.
Uid 64 bytes Subject’s login ID. Optional. No default. Only valid with PKI Services requests.
CommonName 64 bytes Subject's common name. Optional. No default, except in the following situation: If specified with a null value (length 0). RACF will use the PGMRNAME field from the RACF user profile as determined by the User ID field for this request. If PGMRNAME is null, the common name will be of the form of RACF UserID:(user's-racf-identify), for example RACF UserID:JSWEENY
Title 64 bytes Subject's Title. Optional. No default.
DomainName 64 bytes Subject’s Domain Name containing all the domain components in the form of domain-component-1.domain-component-2.domain-component-3…domain-component-n. Optional. No default. Only valid with PKI Services requests.
OrgUnit 64 bytes Subject's Organizational Unit. Note that this field may be repeated. RACF concatenates in the order of appearance to construct the hierarchy of organizational units. Optional. No default.
Org 64 bytes Subject's Organization. Optional. No default.
Street 64 bytes Subject's street address. Optional. No default. Only valid with PKI Services requests.
Locality 64 bytes Subject's City or Locality. Optional. No default.
StateProv 64 bytes Subject's State/Providence. Optional. No default.
PostalCode 64 bytes Subject's postal code or postal code. Optional. No default. Only valid with PKI Services requests.
Country 2 bytes Subject's Country. Optional. No default.
KeyUsage 20 bytes One of 'handshake' | 'dataencrypt' | 'certsign' | 'docsign' | 'digitalsignature' | 'digitalsig' | 'nonrepudiation' | 'keyencipherment' | 'keyenciph' | 'keyencrypt' | 'dataencipherment' | 'dataenciph' | 'keyagreement' | 'keyagree' | 'keycertsign' | 'crlsign' (not case sensitive, no quotes). Note that this field may be repeated to request multiple usages. Optional. No default.
ExtKeyUsage 20 bytes One of 'serverauth' | 'clientauth' | 'codesigning' | 'emailprotection' | 'timestamping' | 'ocspsigning' | 'mssmartcardlogon' | 'cmcca' | 'cmcra' | 'cmcas' | 'pkinitkdc' | 'pkinitclientauth' (not case sensitive, no quotes). Note this field may be repeated to request multiple usages. Optional. No default. Only valid with PKI Services requests.
NotBefore 2 bytes Number of days from today's date that the certificate becomes valid. Range 0-30. Validity checked by RACF. Optional. Default is 0.
NotAfter 4 bytes Number of days from today's date that the certificate expires. Range 1–9999. The number of days in the validity period is calculated as NotAfter minus NotBefore, therefore the NotAfter value must be greater than the NotBefore value. Validity checked by RACF. Optional. Default is 365.
AltIPAddr 45 bytes IP address in IPv4 or IPv6 format for subject alternate name extension. Optional. No default. Note that this field may be repeated in the PKI Services requests.
AltURI 255 bytes Uniform Resource Identifier for subject alternate name extension. Optional. No default. Note that this field may be repeated in the PKI Services requests.
AltEmail 100 bytes Email address for subject alternate name extension. Optional. No default. Note that this field may be repeated in the PKI Services requests.
AltDomain 100 bytes Domain Name for subject alternate name extension. Optional. No default. Note that this field may be repeated in the PKI Services requests.
AltOther 255 bytes Other Name for subject alternate name extension. Optional. No default. Only valid with PKI Services requests.
NotifyEmail 64 bytes Email address for notification purposes. Its value is copied from the Requestor field when Keysize is specified. Optional. No default. Only valid with PKI Services requests.
PublicKey 65535 bytes PKCS #10 or Netscape Navigator certificate request or CMP CertReqMsg structure containing the public key to be certified. This is base 64 encoded DER. Required field if KeySize is not specified.
KeySize 4 bytes Size of the key in bits if key pair is to be generated by PKI services. Range 512–4096 for RSA keys; For NISTECC keys: 192, 224, 256, 384 and 521; for BPECC keys: 160, 192, 224, 256, 320, 384 and 512. Required field if PublicKey is not specified. Only valid with PKI Services requests.
KeyAlg 10 bytes Algorithm of the key if the key pair is to be generated by PKI Services. The acceptable values are ‘RSA’, ‘NISTECC’ and ‘BPECC’. Optional. Default to RSA. Only valid with PKI Services requests.
SignWith 45 bytes For SAF this is the label of z/OS® certificate authority certificate to sign the completed certificate request. Format: SAF:CERTAUTH/<ca-cert-label> or SAF:/<ca-cert-label>, where ca-cert-label is the certificate label under CERTAUTH or the caller's User ID. May also be used to indicate that PKI Services should process the request rather than SAF. In this case, the format is PKI: (exactly 4 characters). Required field.
HostIdMap 100 bytes HostIdMapping extension entry in the form of an email address, for example, gumby@plpsc.pok.ibm.com. The rightmost '@' is used to delineate the subjectId from the hostName. Optional. No default. Only valid with PKI Services requests. Note that this field may be repeated.
Requestor 32 bytes Name of the person submitting the request. If KeySize is specified, this is a required field in the form of an email address. Otherwise, it is an optional field derived from the UnstructuredName if not specified. If UnstructName is not specified, Requestor will be derived from CommonName. If CommonName is also not specified, Requestor will be derived from the first RDN of the subject's name. Only valid with PKI Services requests.
PassPhrase 32 bytes Value to be used for challenge or response when retrieving the certificate through function EXPORT. If KeySize is specified, this is a required field. Otherwise, it is optional. No default. Only valid with PKI Services requests.
UserId 8 bytes Subject's RACF UserID. If not specified, the User ID is taken from the ACEE. For SAF requests, this is the User ID that will own the certificate. For SAF requests, this is the User ID that will own the certificate. For PKI requests, the User ID is used only to determine the Common Name when CommonName is specified without a value.
Label 32 bytes Up to 32 mixed case characters that may be used as the 'handle'. Optional. Default is that one will be generated and added to the user's list of certificates. Only valid with SAF requests.
CertPolicies 32 bytes Blank-separated array of non-repeating policy numbers, range 1 - 99, for the CertificatePolicies extension. These correspond to the policy numbers defined during PKI Services configuration. Each value must be one or two digits with no leading zeros. Optional. No default. Only valid with PKI Services requests.
AuthInfoAcc 255 bytes A comma-separated two-part string specifying information used to create the AuthorityInfoAccess extension. The two-part string identifies the accessMethod and accessLocation. The accessMethod is one of 'OCSP' | 'IdentrusOCSP' (not case sensitive, no quotes). The accessLocation is a URI in the form URI=access-url or URL=access-url. Optional. No default. Only valid with PKI Services requests. Note that this field may be repeated.
Critical 32 bytes Name of a certificate extension to be marked critical. One of 'BasicConstraints' | 'KeyUsage' | 'ExtKeyUsage' | 'SubjectAltName' | 'AltEmail' | 'AltIPAddr' | 'AltDomain' | 'AltURI' | 'HostIdMappings' | 'HostIdMap' | 'CertificatePolicies' | 'CertPolicies' (not case sensitive, no quotes). Optional. The BasicConstraints and KeyUsage extensions are always marked critical even if not specified. Only valid with PKI Services requests. Note this field may be repeated.
CustomExt 1024 bytes Customized extension in the form of a comma-separated four-part string. The first part is the OID of the extension. The second part is the critical flag – ‘C’(critical) or ‘N’(non-critical), the third part is the encode type – ‘INT’(integer), ‘IA5’(IA5 string), ‘PRT’(printable string), ‘BMP’(BMP string) , ‘OCT’(Octet string) or ‘UTF’(UTF8 string), the last part is the value. The critical flag and the encode type are not case sensitive. Note ‘C’(critical) is allowed only if KeySize is not specified. Optional. No default. Only valid with PKI Services requests. This field may be repeated. For more information, see Forming the CustomExt value for CertPlist for the R_PKIServ callable service in z/OS Cryptographic Services PKI Services Guide and Reference.
BusinessCat 64 bytes Subject's business category. Optional. No default. Only valid with PKI Services requests.
Note: It is recommended that this field be used only in requests for Extended Verification certificates.
JurCountry 2 bytes Subject's Jurisdiction Country. Optional. No default. Only valid with PKI Services requests.
Note: It is recommended that this field be used only in requests for Extended Verification certificates.
JurStateProv 64 bytes Subject's Jurisdiction State/Province. Optional. No default. Only valid with PKI Services requests.
Note: It is recommended that this field be used only in requests for Extended Verification certificates.
JurLocality 64 bytes Subject's Jurisdiction Locality. Optional. No default. Only valid with PKI Services requests.
Note: It is recommended that this field be used only in requests for Extended Verification certificates.
Table 3. Function_parmlist for EXPORT
Field Attributes Usage Description
Eyecatcher 8 characters In Eyecatcher, 8 characters left-aligned blank filled. Actual value set by invoker, for example 'EXPORT'.
CertAnchorLen 4-byte length In/Out 4-byte area that is the length of the pre-allocated storage of the Cert Anchor area on input to EXPORT. RACF will update this value with the actual length of the certificate returned. If the storage area as specified by the cert anchor address is too small, RACF will set a failing return or reason code and update the length field to the size required. The caller must allocate a larger area.
CertAnchor Address of In/Out The address of the storage area in which the R_PKIServ service stores the certificate that is specified by the CertID parameter if the service was able to successfully retrieve the completed certificate. If the caller has supplied an area that is too small, (based in the CertAnchorLen), this service fails the request, and updates the CertAnchorLen field to indicate the actual storage required to store the certificate.
CertId Address of In Points to a 57-byte area, in which the first byte will contain the actual length of the input certificate request ID or serial number that will be used to locate the certificate to be exported.

For PKI Services requests where PassPhrase was specified on the GENCERT, the user-provided pass phrase must be appended to the actual CertId value and included here. The leading length byte must account for the additional length.

For PKI Services requests where SCEP is enabled in the PKI Services daemon, the constant value “PKICACERT” can be specified to retrieve the CA certificate or CA/RA certificate pair. No PassPhrase is used in this case.

For PKI Services where Enroll Over Secure Transport (EST) is enabled in the PKI Services daemon, the constant value "PKICACHAIN" can be specified to retrieve the CA certificate and its issuing certificates. No PassPhrase is used in this case.

If the KeyID value is specified, a serial number is expected instead of a request ID. The serial number is a 16-byte value in the form of printable EBCDIC (HEX) with leading 0's (for example, 0000000000001A5F).
KeyId Address of In Points to a 41-byte area. The first byte will contain the length of the KeyId. The KeyID value, which is a 40-byte hash of the public key generated by PKI Services, will begin at the second byte of this value.
  • When exporting a recovery certificate for a PKI Services key generated certificate, the value of the first bye must be 40 (hexadecimal value 28). The 40-byte KeyId value must start in the second byte of this area. The minimum Parmlist_Version value to make use of this function is 1.
  • When exporting a previously exported certificate, the value of the first bye must be 40 (hexadecimal value 28). A KeyId value comprised of 40 bytes of zero (hexadecimal value 0) must follow, beginning at the second byte of this area. The minimum Parmlist_Version value to make use of this function is 2.
  • In all other cases, the value of the first byte must be zero.
Table 4. Function_parmlist for QUERYREQS
Field Attributes Usage Description
Start of changeEyecatcherEnd of change Start of change8 charactersEnd of change Start of changeInEnd of change Start of changeEyecatcher, 8 characters left-aligned blank filled. Actual value set by invoker, for example, ' QUERYRQS 'End of change
ResultsListLen 4-byte length In/Out 4–byte area that is the length of the pre-allocated storage of the Results List area on input to QUERYREQS. RACF will update this value with the actual length of the data returned. If the storage area as specified by the Results List address is too small, RACF will set a failing return or reason code and update the length field to the size required. The caller must allocate a larger area.
ResultsList Address of In/Out The address of the storage area in which the R_PKIServ service stores the results of the query if the service was able to successfully retrieve the data. If the caller has supplied an area that is too small, (based in the ResultsListLen), this service fails the request, and updates the ResultsListLen field to indicate the actual storage required to store the data.
CertId Address of In Points to a 57-byte area, in which the first byte will contain the actual length of the input certificate request ID that will be used as a starting point for this query. Only requests located after this request will be returned. If the first byte is zero (x'00'), then the query will start with the first request.
NumEntries 4-byte numeric In/Out Input value indicating the maximum number of entries that should be returned in the ResultsList area. Zero indicates no limit. Updated to indicate the number of entries actually returned.
CriteriaStatus 4-byte numeric In Value indicating the request status to use as search criteria.
  • X'00000000' - return all requests,
  • X'00000001' - return requests pending approval only,
  • X'00000002' - return requests that have been approved only,
  • X'00000003' - return completed requests only,
  • X'00000004 - return all rejected requests only,
  • X00000005 - return rejected requests in which the client has been notified only,
  • X'00000006' - return preregistered requests only.
CriteriaDays 4-byte numeric In Value indicating the recent activity time period to use as additional search criteria. The time period is the number of days in the past that should be scanned for requests that have been created or modified. If zero (x'00000000'), recent activity will not be used as additional search criteria.
CriteriaName Address of In Points to a 33-byte area, in which the first byte will contain the actual length of the input requestor's name to be used as additional search criteria. If the first byte is zero (x'00'), then the requestor's name will not be used as additional search criteria.

The QUERYREQS function returns results in the ResultsList area provided by the caller. The ResultsList has the following format:

Table 5. ResultsList for QUERYREQS
Length Value
1-byte length Entry 1's certificate request ID, max 56 bytes
1-byte length Entry 1's requestor's name, max 32 bytes
1-byte length Entry 1's subject's distinguished name, max 255 bytes
1-byte length Entry 1's issuer's distinguished name, max 255 bytes
1-byte length Entry 1's validity period in local time. Format YYYY/MM/DD HH:MM:SS - YYYY/MM/DD HH:MM:SS. Zero bytes for requests with a status of “Preregistered”, otherwise exactly 41 bytes.
1-byte length Entry 1's keyUsage value, max 64 bytes (one or more of 'handshake' | 'dataencrypt' | 'certsign' | 'docsign' | 'digitalsig' | 'keyencrypt' | 'keyagree' | 'keycertsign' | 'crlsign' or "not specified" )
1-byte length Entry 1's status, max 32 bytes (one of "Preregistered", "Pending Approval", "Approved", "Completed", "Rejected", or "Rejected, User Notified")
1-byte length Entry 1's creation date in YYYY/MM/DD form, exactly 10 bytes
1-byte length Entry 1's last modified date in YYYY/MM/DD form, exactly 10 bytes
1-byte length Entry 1's ApplData value from the GENCERT or REQCERT invocation, max 8 bytes
1-byte length Entry 1's serial number if certificate has been issued, max 16 bytes
1-byte length Entry 1's previous serial number if this is a renewal request, max 16 bytes
1-byte length Entry 1's ExtKeyUsage value, max 255 bytes (one or more of 'serverauth' | 'clientauth' | 'codesigning' | 'emailprotection' | 'timestamping' | 'ocspsigning' | 'mssmartcardlogon' | 'cmcca' | 'cmcra' | 'cmcas' | 'pkinitkdc' | 'pkinitclientauth' or "not specified").
1-byte length Entry 1's query timestamp. Format YYYY/MM/DD HH:MM:SS, 19 bytes
1-byte length Entry 1's required number of approvals, 2 bytes. The following entries of approver, action and timestamp will be repeated for the same number of times as the required number of approvals
1-byte length Entry 1's first approver RACF User ID, max 8 bytes
1-byte length Entry 1's first action performed, one of 'approved' | 'approved with modification' | 'rejected'
1-byte length Entry 1's first approval timestamp with format YYYY/MM/DD HH:MM:SS, 19 bytes
… …
1-byte length Entry 1's last approver RACF User ID, max 8 bytes
1-byte length Entry 1's last action performed, one of 'approved' | 'approved with modification' | 'rejected'
1-byte length Entry 1's last approval timestamp with format YYYY/MM/DD HH:MM:SS, 19 bytes
1-byte length Entry 2's certificate request ID, max 56 bytes
1-byte length Entry 2's requestor's name, max 32 bytes
1-byte length Entry 2's subject's distinguished name, max 255 bytes
1-byte length Entry 2's issuer's distinguished name, max 255 bytes
1-byte length Entry 2's validity period in local time. Format YYYY/MM/DD HH:MM:SS - YYYY/MM/DD HH:MM:SS. Zero bytes for requests with a status of “Preregistered”, otherwise exactly 41 bytes.
1-byte length Entry 2's keyUsage value, max 64 bytes (one or more of 'handshake' |'dataencrypt |, 'certsign' |'docsign' |'digitalsig' | 'keyencrypt' | 'keyagree' | 'keycertsign' | 'crlsign' or "not specified")
1-byte length Entry 2's status, max 32 bytes (one of "Preregistered", "Pending Approval", "Approved", "Completed", "Rejected", or "Rejected, User Notified")
1-byte length Entry 2's creation date in YYYY/MM/DD form, exactly 10 bytes
1-byte length Entry 2's last modified date in YYYY/MM/DD form, exactly 10 bytes
1-byte length Entry 2's ApplData value from the GENCERT or REQCERT invocation, max 8 bytes
1-byte length Entry 2's serial number if certificate has been issued, max 16 bytes
1-byte length Entry 2's previous serial number if this is a renewal request, max 16 bytes
1-byte length Entry 2's ExtKeyUsage value, max 255 bytes (one or more of 'serverauth' | 'clientauth' | 'codesigning' | 'emailprotection' | 'timestamping' | 'ocspsigning' | 'mssmartcardlogon' | 'cmcca' | 'cmcra' | 'cmcas' | 'pkinitkdc' | 'pkinitclientauth' or "not specified").
1-byte length Entry 2's query timestamp. Format YYYY/MM/DD HH:MM:SS, 19 bytes
1-byte length Entry 2's required number of approvals, 2 bytes. The following entries of approver, action and timestamp will be repeated for the same number of times as the required number of approvals
1-byte length Entry 2's first approver RACF User ID, max 8 bytes
1-byte length Entry 2's first action performed, one of 'approved' | 'approved with modification' | 'rejected'
1-byte length Entry 2's first approval timestamp with format YYYY/MM/DD HH:MM:SS, 19 bytes
… …
1-byte length Entry 2's last approver RACF User ID, max 8 bytes
1-byte length Entry 2's last action performed, one of 'approved' | 'approved with modification' | 'rejected'
1-byte length Entry 2's last approval timestamp with format YYYY/MM/DD HH:MM:SS, 19 bytes
⋮
Length, continued Value, continued
1-byte length Entry n's certificate request ID, max 56 bytes
1-byte length Entry n's requestor's name, max 32 bytes
1-byte length Entry n's subject's distinguished name, max 255 bytes
1-byte length Entry n's issuer's distinguished name, max 255 bytes
1-byte length Entry n's validity period in local time. Format YYYY/MM/DD HH:MM:SS - YYYY/MM/DD HH:MM:SS. Zero bytes for requests with a status of “Preregistered”, otherwise exactly 41 bytes.
1-byte length Entry n's keyUsage value, max 64 bytes (one or more of 'handshake' |'dataencrypt' |'certsign' |'docsign' |'digitalsig' | 'keyencrypt' | 'keyagree' | 'keycertsign' | 'crlsign' or "not specified")
1-byte length Entry n's status, max 32 bytes (one of "Preregistered", "Pending Approval", "Approved", "Completed", "Rejected", or "Rejected, User Notified")
1-byte length Entry n's creation date in YYYY/MM/DD form, exactly 10 bytes
1-byte length Entry n's last modified date in YYYY/MM/DD form, exactly 10 bytes
1-byte length Entry n's ApplData value from the GENCERT or REQCERT n's last modified date in YYYY/MM/DD invocation, max 8 bytes
1-byte length Entry n's serial number if certificate has been issued, max 16 bytes
1-byte length Entry n's previous serial number if this is a renewal request, max 16 bytes
1-byte length Entry n's ExtKeyUsage value, max 255 bytes (one or more of 'serverauth' | 'clientauth' | 'codesigning' | 'emailprotection' | 'timestamping' | 'ocspsigning' | 'mssmartcardlogon' | 'cmcca' | 'cmcra' | 'cmcas' | 'pkinitkdc' | 'pkinitclientauth' or "not specified").
1-byte length Entry n's query timestamp. Format YYYY/MM/DD HH:MM:SS, 19 bytes
1-byte length Entry n's required number of approvals, 2 bytes. The following entries of approver, action and timestamp will be repeated for the same number of times as the required number of approvals
1-byte length Entry n's first approver RACF User ID, max 8 bytes
1-byte length Entry n's first action performed, one of 'approved' | 'approved with modification' | 'rejected'
1-byte length Entry n's first approval timestamp with format YYYY/MM/DD HH:MM:SS, 19 bytes
… …
1 byte length Entry n's last action performed, one of 'approved' | 'approved with modification' | 'rejected'
1 byte length Entry n's last approver RACF User ID, max 8 bytes
1 byte length Entry n's last action performed, one of 'approved' | 'approved with modification' | 'rejected'
1 byte length Entry n's last approval timestamp with format YYYY/MM/DD HH:MM:SS, 19 bytes
Table 6. Function_parmlist for REQDETAILS
FIELD ATTRIBUTES USAGE DESCRIPTION
Eyecatcher 8 characters In Eyecatcher, 8 characters left-aligned blank filled. Actual value set by invoker, for example, ' REQDTAIL'
SumListLen 4-byte length In/Out 4-byte area that is the length of the pre-allocated storage of the Summary List area on input to REQDETAILS. RACF will update this value with the actual length of the data returned. If the storage area as specified by the Summary List address is too small, RACF will set a failing return/reason code and update the length field to the size required. The caller must allocate a larger area.
SumList Address of In/Out The address of the storage area in which the R_PKIServ service stores the results of the query if the service was able to successfully retrieve the data. If the caller has supplied an area which is too small, (based in the SummaryListLen), this service fails the request, and updates the SummaryListLen field to indicate the actual storage required to store the data. Also, see Table 7.
CertPlistLen 4-byte length In/Out 4-byte area that is the length of the pre-allocated storage of the certificate generation plist area on input to REQDETAILS. RACF will update this value with the actual length of the data returned. If the storage area as specified by the Results List address is too small, RACF will set a failing return/reason code and update the length field to the size required. The caller must allocate a larger area.
CertPlist Address of In/Out The address of the storage area in which the R_PKIServ service stores the results of the query if the service was able to successfully retrieve the data. If the caller has supplied an area which is too small, (based in the CertPlistLen), this service fails the request, and updates the CertPlistLen field to indicate the actual storage required to store the data. This area maps some of the specific name, length, address/data values which were used when generating the original certificate request on GENCERT. Also, see Table 8.
CertId Address of In Points to a 57-byte area, in which the first byte will contain the actual length of the input certificate request ID from which details are to be extracted
The REQDETAILS function returns QUERYREQS style summary data in the SumList area provided by the caller. The SumList has the following format:
Table 7. SumList for REQDETAILS
Length Value
1-byte length Entry's certificate request ID, max 56 bytes
1-byte length Entry's requestor's name, max 32 bytes
1-byte length Entry's subject's distinguished name, max 255 bytes
1-byte length Entry's issuer's distinguished name, max 255 bytes
1-byte length Entry's validity period in local time. Format YYYY/MM/DD HH:MM:SS - YYYY/MM/DD HH:MM:SS. Zero bytes for requests with a status of “Preregistered”, otherwise exactly 41 bytes
1-byte length Entry's keyUsage value, max 64 bytes (one or more of 'handshake'| 'dataencrypt'|, 'certsign'| 'docsign' | 'digitalsig' | 'keyencrypt' | 'keyagree' | 'keycertsign' | 'crlsign' or "not specified")
1-byte length Entry's status, max 32 bytes (one of "Pending Approval", "Approved", "Completed", "Rejected", or "Rejected, User Notified")
1-byte length Entry's creation date in YYYY/MM/DD form, exactly 10 bytes
1-byte length Entry's last modified date in YYYY/MM/DD form, exactly 10 bytes
1-byte length Entry's ApplData value from the GENCERT or REQCERT invocation, max 8 bytes
1-byte length Entry's serial number if certificate has been issued, max 16 bytes
1-byte length Entry's previous serial number if this is a renewal request, max 16 bytes
1-byte length Entry's last action comment, max 64 bytes
1-byte length Entry's pass phrase provided when the certificate request was made, max 32 bytes
1-byte length Entry's notification email address, max 64 bytes
1-byte length Entry's ExtKeyUsage value, max 255 bytes (one or more of 'serverauth' | 'clientauth' | 'codesigning' | 'emailprotection' | 'timestamping' | 'ocspsigning' | 'cmcca' | 'cmcra' | 'cmcas' | 'pkinitkdc' | 'pkinitclientauth' or "not specified").
1-byte length Entry’s certificate request fingerprints - 40 byte SHA1 hash (printable EBCDIC) followed by 32 byte MD5 hash (printable EBCDIC), Exactly 72 bytes if available. Zero bytes if unavailable.
1–byte length Entry’s certificate request fingerprints - 64 byte SHA256 hash (printable EBCDIC) followed by 128 byte SHA512 hash (printable EBCDIC). Exactly 192 bytes if available. Zero bytes if unavailable.
1–byte length
Entry’s request signature algorithm, max 32 bytes, one of
'sha-1WithRSAEncryption' , 'sha-224WithRSAEncryption' ,
'sha-256WithRSAEncryption' , 'sha-384WithRSAEncryption' ,
'sha-512WithRSAEncryption' , 'sha256WithRSAPSS' , 'sha-384WithRSAPSS' , 'sha-512WithRSAPSS' , 'md-5WithRSAEncryption' ,
'md-2WithRSAEncryption' ,
'id-dsa-with-sha1' , 'id-dsa-with-sha224' ,
'id-dsa-with-sha256' ,  'ecdsa-with-sha1' ,
'ecdsa-with-sha224' , 'ecdsa-with-sha256' ,
'ecdsa-with-sha384' or 'ecdsa-with-sha512'.
Zero bytes if unavailable.
1–byte length Entry’s Key type, max 16 bytes, one of 'RSA', 'DSA', 'BPECC' or 'NISTECC'. Zero bytes if unavailable.
1–byte length Entry ’s Key size, max 8 bytes. Zero bytes if unavailable.
1–byte length Entry's query timestamp. Format YYYY/MM/DD HH:MM:SS, 19 bytes
1–byte length Entry's required number of approvals, 2 bytes. The following entries of approver, action, comment and timestamp will be repeated for the same number of times as the required number of approvals
1–byte length Entry's first approver RACF User ID, max 8 bytes
1–byte length Entry's first action performed, one of 'approved' | 'approved with modification' | 'rejected'
1–byte length Entry's first approval timestamp with format YYYY/MM/DD HH:MM:SS, 19 bytes
1–byte length Entry's first action comment. max 64 bytes.
… …
1–byte length Entry's last approver RACF User ID, max 8 bytes
1–byte length Entry's last action performed, one of 'approved' | 'approved with modification' | 'rejected'
1–byte length Entry's last approval timestamp with format YYYY/MM/DD HH:MM:SS, 19 bytes
1–byte length Entry's last action comment. max 64 bytes.
Additionally, the REQDETAILS function returns GENCERT style certificate field name/value pairs in the CertPlist area. This is the list of fields that may be returned. They are also the fields that may be modified by function MODIFYREQS. The fields and their values are conditionally present, depending on the values of the original GENCERT request. Multiple OrgUnits and HostIdMaps are returned in the order they were originally specified. Fields other than OrgUnit and HostIdMap are not returned in any specific order. Like GENCERT, the CertPlist returned is a list of ordered triplets which consists of name, length and data value. The field name is a fixed 12-character field, case sensitive, left-aligned, and padded with blanks, the length field is a binary four byte value, which qualifies the length of the data item.
Note: All data values are EBCDIC character data unless otherwise indicated. Also, NotBefore and NotAfter are replaced with StartDate and EndDate.
Table 8. CertPlist for REQDETAILS
Field name Max length Description
SerialNumber 64 bytes Serial number of the subject device or registration number of the subject.
UnstructAddr 64 bytes Unstructured address of the subject device.
UnstructName 64 bytes Unstructured name of the subject device.
EmailAddr 64 bytes Subject’s email address for distinguished name EMAIL= attribute.
Mail 64 bytes Subject’s email address for distinguished name MAIL= attribute.
DNQualifier 64 bytes Subject’s Distinguished Name Qualifier.
Uid 64 bytes Subject’s login ID.
CommonName 64 bytes Subject's common name.
Title 64 bytes Subject's title.
DomainName 64 bytes Subject’s Domain Name containing all the domain components.
OrgUnit 64 bytes Subject's Organization Unit. Note this field may be repeated.
Org 64 bytes Subject's Organization.
Street 64 bytes Subject's street address.
Locality 64 bytes Subject's City or Locality.
StateProv 64 bytes Subject's State or Province.
PostalCode 64 bytes Subject's zip code or postal code.
Country 2 bytes Subject's Country.
KeyUsage 20-bytes KeyUsage extension entry. One of 'handshake' | 'dataencrypt' | 'certsign' | 'docsign' | 'digitalsig' | 'keyencrypt' | 'keyagree' | 'keycertsign' | 'crlsign (not case sensitive, no quotes). Note this field may be repeated.
ExtKeyUsage 20 bytes One of 'serverauth' | 'clientauth' | 'codesigning' | 'emailprotection' | 'timestamping' | 'ocspsigning' |'mssmartcardlogon' | 'cmcca' | 'cmcra' | 'cmcas' | 'pkinitkdc' | 'pkinitclientauth'. Note this field may be repeated.
StartDate 10 bytes Data certificate becomes valid in YYYY/MM/DD form.
EndDate 10 bytes Last date that the certificate is valid in YYYY/MM/DD form.
AltIPAddr 45 bytes IP address in IPv4 or IPv6 format for subject alternative name extension. Note that this field may be repeated.
AltURI 255 bytes Uniform Resource Identifier for subject alternative name extension. Note that this field may be repeated.
AltEmail 100 bytes Email address for subject alternative name extension. Note that this field may be repeated.
AltDomain 100 bytes Domain Name for subject alternative name extension. Note that this field may be repeated.
AltOther 255 bytes Other Name for subject alternative name extension. Note this field may be repeated.
HostIdMap 100 bytes HostIdMapping extension entry. Note this field may be repeated.
AutoRenew 1 byte Indicates whether the automatic renewal of certificates is enabled. Either ‘Y’ or ‘N’ (case sensitive, no quotes).
CustomExt 1024 bytes Customized extension in the form of a comma-separated four-part string. The first part is the OID of the extension, the second part is the critical flag – ‘C’(critical) or ‘N’(non-critical) , the third part is the encode type – ‘INT’(integer in printable hexadecimal format), ‘IA5’(IA5 string), ‘PRT’(printable string), ‘BMP’(BMP string) , ‘OCT’(Octet string) or ‘UTF’(UTF8 string), the last part is the value. Note that this field may be repeated.
BusinessCat 64 bytes Subject's business category. Optional. No default. Only valid with PKI Services requests.
Note: It is recommended that this field be used only in requests for Extended Verification certificates.
JurCountry 2 bytes Subject's Jurisdiction Country. Optional. No default. Only valid with PKI Services requests.
Note: It is recommended that this field be used only in requests for Extended Verification certificates.
JurStateProv 64 bytes Subject's Jurisdiction State/Province. Optional. No default. Only valid with PKI Services requests.
Note: It is recommended that this field be used only in requests for Extended Verification certificates.
JurLocality 64 bytes Subject's Jurisdiction Locality. Optional. No default. Only valid with PKI Services requests.
Note: It is recommended that this field be used only in requests for Extended Verification certificates.
Table 9. Function_parmlist for MODIFYREQS
Field Attributes Usage Description
Eyecatcher 8 characters In Eyecatcher, 8 characters left-aligned blank filled. Actual value set by invoker, for example, ' MODREQS '
Action 4-byte value In 4-byte binary value indicating the action to take against the requests.
  • X'00000001' - Approve with possible modifications as specified
  • X'00000002' - Reject
  • X'00000003' -Delete from request database
Comment Address of In Points to a 65-byte area, in which the first byte will contain the actual length of the comment associated with this action. If the first byte is zero (x'00'), no comment will be recorded.
CertIdsLen 4-byte length In/Out Describes the length in bytes of the input certificate request ID list. May be modified by RACF on output if a smaller list is being returned.
CertIds Address of In/Out Points to an area containing 1 or more certificate request Ids that are to be modified by this request. Each certificate request ID occupies a maximum of 57 bytes, in which the first byte will contain the actual length of the certificate request ID. If any requests cannot be modified because their states or contents changed, or action performed by an unauthorized person, or the same person attempts to approve the same request more than once, RACF will return a shortened list containing those requested IDs that couldn't be modified. The ErrList field will contain the corresponding error description.
CertPlistLen 4-byte length In Describes the length in bytes of the certificate modification plist. A zero indicates no modification plist.
CertPlist Address of In Points to the area which is the certificate modification parameter list. This area maps the specific name, length, address/data values which are used to replace the existing values in the certificate request. The format is the same as the Certificate Request Plist defined under GENCERT (DiagInfo must be the first field.), except that the modifiable fields are those listed. The certificate modification plist is optional and is valid for the "Approve" action only and only when the CertIds list contains exactly one Certificate ID. For all other cases, it is ignored. If no modification plist is specified for "Approve", the request is approved as is. See usage notes, 23, for a description of the processing that performed when a modification plist is specified.
ErrListLen 4-byte length In/Out The 4-byte length of the pre-allocated storage for the ErrList parameter. This value may be modified by RACF on output to reflect the total length of the data returned in the ErrList parameter for certain reason and return codes. See Table 6. If the value is zero upon input, the ErrList parameter will be ignored. The minimum Parmlist_Version for the use of this parameter is 1.
ErrList Address of In/Out Points to a pre-allocated storage buffer that RACF will use to return error results for requests that could not be modified for certain reason and return codes. See Table 6. On output, each error result will occupy a maximum of 101 bytes; a 1-byte length field, followed by up to 100 bytes of error description text. Each error result corresponds to a certificate request ID returned in the CertIds parameter. This parameter is ignored if the ErrListLen parameter is set to a value of zero. The minimum Parmlist_version for the use of this parameter is 1
QueryTime Address of In Points to a 20-byte area, in which the first byte is the length of a 19-byte value in the form of YYYY/MM/DD HH:MM:SS indicating the timestamp when the query was made before modification. If no value is supplied, the current time will be used. Only valid with action X'00000001' – Approve with possible modifications. The minimum Parmlist_version for the use of this parameter is 2.

The MODIFYREQS modification plist (CertPlist) Structure. Like GENCERT, the CertPlist is a list of ordered triplets which consists of name, length and data value. The field name is a fixed 12-character field, case sensitive, left-aligned, and padded with blanks, the length field is a binary four byte value, which qualifies the length of the data item. Note that all data values are EBCDIC character data unless otherwise indicated. Note that NotBefore and NotAfter are replaced with StartDate and EndDate. See GENCERT for more information about the other individual fields

Table 10. CertPlist for MODIFYREQS
Field name Max length Description
DiagInfo 80 bytes (exactly) Diagnostic information area. Must be first field in the CertPlist. For certificate generation warnings and errors, RACF will update this field with diagnostic information. The length will be updated as well. Required field.
SerialNumber 64 bytes Serial number of the subject device. Optional. No default.
UnstructAddr 64 bytes Unstructured address of the subject device. Optional. No default.
UnstructName 64 bytes Unstructured name of the subject device. Optional. No default.
EmailAddr 64 bytes Subject’s email address for distinguished name EMAIL= attribute. Optional. No default.
Mail or Email 64 bytes Subject’s email address for distinguished name MAIL= attribute. Optional. No default. (Field name “Email” is deprecated, use “Mail”)
DNQualifier 64 bytes Subject’s Distinguished Name Qualifier. Optional. No default.
Uid 64 bytes Subject’s login ID. Optional. No default.
CommonName 64 bytes Subject's common name. Optional.
Title 64 bytes Subject's title. Optional.
DomainName 64 bytes Subject’s Domain Name containing all the domain components in the form of domain-component-1.domain-component-2.domain-component-3…domain-component-n. Optional. No default.
OrgUnit 64 bytes Subject's Organizational Unit. Note this field may be repeated. Optional.
Org 64 bytes Subject's Organization. Optional.
Street 64 bytes Subject's street address. Optional
Locality 64 bytes Subject's City or Locality. Optional.
StateProv 64 bytes Subject's State or Province. Optional.
PostalCode 64 bytes Subject's Zip or postal code. Optional.
Country 2 bytes Subject's Country. Optional.
KeyUsage 20 bytes KeyUsage extension entry. One of 'handshake' | 'dataencrypt' | 'certsign' | 'docsign' 'digitalsignature' | 'digitalsig' | 'nonrepudiation' | 'keyencipherment' | 'keyenciph' | 'keyencrypt' | 'dataencipherment' | 'dataenciph' | 'keyagreement' | 'keyagree' | 'keycertsign' | 'crlsign' (not case sensitive, no quotes). Note this field may be repeated. Optional.
ExtKeyUsage 20 bytes One of 'serverauth' | 'clientauth' | 'codesigning' | 'emailprotection' | 'timestamping' | 'ocspsigning' | 'mssmartcardlogon' | 'cmcca' | 'cmcra' | 'cmcas' | 'pkinitkdc' | 'pkinitclientauth' (not case sensitive, no quotes). Note this field may be repeated to request multiple usages. Optional, no default.
StartDate 10 bytes Date certificate becomes valid in YYYY/MM/DD form. Must be a valid date within the range 1970/01/01 through 9997/12/31. Required.
EndDate 10 bytes Last date that the certificate is valid in YYYY/MM/DD form. Must be a valid date within the range of today through 9997/12/31 and must not be before StartDate. Required.
AltIPAddr 45 bytes IP address in IPv4 or IPv6 format for subject alternative name extension. Optional. There is no default. Note that this field may be repeated.
AltURI 255 bytes Uniform Resource Identifier for subject alternative name extension. Optional. There is no default. Note that this field may be repeated.
AltEmail 100 bytes Email address for subject alternative name extension. Optional. There is no default. Note that this field may be repeated.
AltDomain 100 bytes Domain Name for subject alternative name extension. Optional. There is no default. Note that this field may be repeated.
AltOther 255 bytes Other Name for subject alternative name extension. Optional. There is no default. Note this field may be repeated.
HostIdMap 100 bytes HostIdMapping extension entry. Note this field may be repeated. Optional.
CertPolicies 32 bytes Blank separated array of non-repeating policy numbers, range 1 - 99, for the CertificatePolicies extension. These correspond to the policy numbers defined during PKI Services configuration. Each value must be one or two digits with no leading zeros. Optional, no default.
AuthInfoAcc 255 bytes A comma separated two part string specifying information used to create the AuthorityInfoAccess extension. The two part string identifies the accessMethod and accessLocation. The accessMethod is one of 'OCSP' | 'IdentrusOCSP' (not case sensitive, no quotes). The accessLocation is a URI in the form URI=access-url or URL=access-url. Optional, no default. Note this field may be repeated.
Critical 32 bytes Name of a certificate extension to be marked critical. One of 'BasicConstraints' | 'KeyUsage' | 'ExtKeyUsage' | 'SubjectAltName' | 'AltEmail' | 'AltIPAddr' | 'AltDomain' | 'AltURI' | 'HostIdMappings' | 'HostIdMap' | 'CertificatePolicies' | 'CertPolicies' (not case sensitive, no quotes). Optional. The BasicConstraints and KeyUsage extensions are always marked critical even if not specified. Note this field may be repeated.
AutoRenew 1 byte Indicates whether the automatic renewal of certificates is enabled. Either ‘Y’ or ‘N’ (not case sensitive, no quotes). Optional. There is no default.
CustomExt 1024 bytes Customized extension in the form of a comma-separated four-part string. The first part is the OID of the extension, the second part is the critical flag – ‘C’(critical) or ‘N’(non-critical) , the third part is the encode type – ‘INT’(integer), ‘IA5’(IA5 string), ‘PRT’(printable string), ‘BMP’(BMP string) , ‘OCT’(Octet string) or ‘UTF’(UTF8 string), the last part is the value. Note 1: The value specified for the INT type is a string of printable hexadecimal characters. If the number of characters is odd, the high order bit of the first character is propagated in the encoded value. Note 2: The critical flag and the encode type are not case sensitive. ‘C’(critical) is allowed only if KeySize is not specified. Optional. No default. Only valid with PKI Services requests. Note that this field may be repeated.
Table 11. Function_parmlist for QUERYCERTS
Field Attributes Usage Description
Eyecatcher 8 characters In Eyecatcher, 8 characters left-aligned blank filled. Actual value set by invoker, for example, ' QUERYCTS '
ResultsListLen 4-byte length In/Out 4-byte area that is the length of the pre-allocated storage of the Results List area on input to QUERYCERTS. RACF will update this value with the actual length of the data returned. If the storage area, as specified by the Results List address is too small, RACF sets a failing return/reason code and update the length field to the size required. The caller must allocate a larger area.
ResultsList Address of In/Out The address of the storage area in which the R_PKIServ service stores the results of the query if the service was able to successfully retrieve the data. If the caller has supplied an area which is too small, (based in the ResultsListLen), this service fails the request, and updates the ResultsListLen field to indicate the actual storage required to store the data. Also, see Table 12.
SerialNum Address of In Points to a 17-byte area, in which the first byte will contain the actual length of the input certificate serial number that will be used as a starting point for this query. Only certificates located after this certificate will be returned. If the first byte is zero (x'00'), the query will start with the first request. The serial number is in printable EBCDIC (HEX) form for example, "01A6",
NumEntries 4-byte numeric In/Out Input value indicating the maximum number of entries that should be returned in the ResultsList area. Zero indicates no limit. Updated to indicate the number of entries actually returned.
CriteriaStatus 4-byte numeric In Value indicating the certificate status to be used as search criteria.
  • X'00000000' - return all issued certificates,
  • X'00000001' - return revoked certificates only,
  • X'00000002' -return expired certificates only,
  • X'00000003' - return non-expired, non-revoked certificates only, that is, active certificates,
  • X'00000004' - return non-expired revoked or suspended certificates only, that is, CRL certificates,
  • X'00000005' - return suspended certificates only,
  • X'00000006' - return active certificates enabled for auto renewal,
  • X'00000007' - return active certificates capable for auto renewal but disabled.
  • X'00000008' - return active certificates that cannot be renewed due to a change of email address.
CriteriaDays 4-byte numeric In Value indicating the recent activity time period or the certificate expiry period to be used as additional search criteria. A positive value indicates the number of days in the past that should be scanned for certificates that have been created or modified. A negative value indicates the numbers of days in the future that should be scanned for certificates that will expire within that period. A negative value is valid only if the CriteriaStatus is X’00000003’, X’00000006’, X’00000007’, or X’00000008’. If it is zero (x’00000000’), recent activity and certificate expiry period will not be used as additional search criteria.
CriteriaName Address of In Points to a 33-byte area, in which the first byte will contain the actual length of the input requestor's name to be used as additional search criteria. If the first byte is zero (x'00'), the requestor's name will not be used as additional search
Start of changeSerialNumOrFingerPrtEnd of change Start of changeAddress ofEnd of change Start of changeInEnd of change Start of changeThere are three acceptable formats:
  1. Points to a 17-byte area, in which the first byte will contain the actual length of the input certificate serial number from which details are to be extracted. The serial number is in printable EBCDIC (HEX) form for example, "01A6".
  2. Points to a 65-byte area, in which the first byte will contain the actual length of the input certificate SHA256 fingerprint with no separators. The fingerprint is in printable EBCDIC (HEX) form. For example: “9C3E4AFCC491DFD332F3089B8542E9417D893D7FE944E10A7937EE29D9693DAE”.
  3. Points to a 96-byte area, in which the first byte will contain the actual length of the input certificate SHA256 fingerprint with colon or blank separators. For example: “9C:3E:4A:FC:C4:91:DF:D3:32:F3:08:9B:85:42:E9:41:7D:89:3D:7F:E9:44:E1:0A:79:37:EE:29:D9:69:3D:AE”, or “9C 3E 4A FC C4 91 DF D3 32 F3 08 9B 85 42 E9 41 7D 89 3D 7F E9 44 E1 0A 79 37 EE 29 D9 69 3D AE”
End of change
The QUERYCERTS function returns results in the ResultsList area provided by the caller. The ResultsList has the following format:
Table 12. ResultsList for QUERYCERTS
Length Value
1-byte length Entry 1's serial number in printable EBCDIC (HEX) form for example, "01A6", max 16 bytes
1-byte length Entry 1's requestor's name, max 32 bytes
1-byte length Entry 1's subject's distinguished name, max 255 bytes
1-byte length Entry 1's issuer's distinguished name, max 255 bytes
1-byte length Entry 1's validity period in local time. Format YYYY/MM/DD HH:MM:SS - YYYY/MM/DD HH:MM:SS. Exactly 41 bytes
1-byte length Entry 1's keyUsage value, max 64 bytes (one or more of 'handshake' |'dataencrypt' |'certsign' |'docsign' | 'digitalsig' | 'keyencrypt' | 'keyagree' | 'keycertsign' | 'crlsign' or "not specified" )
1-byte length Entry 1's status, max 32 bytes, one of "Active", "Active, AutoRenew", "Active, AutoRenewDisabled", "Expired", "Revoked", "Suspended", "Revoked, Expired", or "Active, NotRenewable"
1-byte length Entry 1's creation date in YYYY/MM/DD form, exactly 10 bytes
1-byte length Entry 1's last modified date in YYYY/MM/DD form, exactly 10 bytes
1-byte length Entry 1's ApplData value from the GENCERT or REQCERT invocation, max 8 bytes
1-byte length Entry 1's ExtKeyUsage value, max 255 bytes (one or more of 'serverauth' | 'clientauth' | 'codesigning' | 'emailprotection' | 'timestamping' | 'ocspsigning' | 'mssmartcardlogon' | 'cmcca' | 'cmcra' | 'cmcas' | 'pkinitkdc' | 'pkinitclientauth' or "not specified")
1-byte length Entry 1's KeyId, exactly 40 bytes (printable EBCDIC)
Start of change1-byte lengthEnd of change Start of changeEntry 1's SHA256 fingerprint, exactly 95 bytes (printable EBCDIC, colon separated)End of change
1-byte length Entry 2's serial number in printable EBCDIC (HEX) form for example, "01A6", max 16 bytes
1-byte length Entry 2's requestor's name, max 32 bytes
1-byte length Entry 2's subject's distinguished name, max 255 bytes
1-byte length Entry 2's issuer's distinguished name, max 255 bytes
1-byte length Entry 2's validity period in local time. Format YYYY/MM/DD HH:MM:SS - YYYY/MM/DD HH:MM:SS. Exactly 41 bytes
1-byte length Entry 2's keyUsage value, max 64 bytes (one or more of 'handshake' |'dataencrypt' | 'certsign' |'docsign' |'digitalsig' | 'keyencrypt' | 'keyagree' | 'keycertsign' | 'crlsign' or "not specified")
1-byte length Entry 2's status, max 32 bytes, one of "Active", "Active, AutoRenew", "Active, AutoRenewDisabled", "Expired", "Revoked", "Suspended", "Revoked, Expired", or "Active, NotRenewable".
1-byte length Entry 2's creation date in YYYY/MM/DD form, exactly 10 bytes
1-byte length Entry 2's last modified date in YYYY/MM/DD form, exactly 10 bytes
1-byte length Entry 2's ApplData value from the GENCERT or REQCERT invocation, max 8 bytes
1-byte length Entry 2's ExtKeyUsage value, max 255 bytes (one or more of 'serverauth' | 'clientauth' | 'codesigning' | 'emailprotection' | 'timestamping' | 'ocspsigning' | 'mssmartcardlogon' | 'cmcca' | 'cmcra' | 'cmcas' | 'pkinitkdc' | 'pkinitclientauth' or "not specified")
1–byte length Entry 2's KeyID, exactly 40 bytes (printable EBCDIC)
Table 13. ResultsList for QUERYCERTS (continued)
Length, continued Value, continued
1-byte length Entry n's serial number in printable EBCDIC(HEX) form for example, "01A6", max 16 bytes
1-byte length Entry n's requestor's name, max 32 bytes
1-byte length Entry n's subject's distinguished name, max 255 bytes
1-byte length Entry n's issuer's distinguished name, max 255 bytes
1-byte length Entry n's validity period in local time. Format YYYY/MM/DD HH:MM:SS - YYYY/MM/DD HH:MM:SS. Exactly 41 bytes
1-byte length Entry n's keyUsage value, max 64 bytes (one or more of 'handshake' |'dataencrypt' |'certsign' |'docsign' |'digitalsig' | 'keyencrypt' | 'keyagree' | 'keycertsign' | 'crlsign' or "not specified")
1-byte length Entry n's status, max 32 bytes, one of "Active", "Active, AutoRenew", "Active, AutoRenewDisabled", "Expired", "Revoked", "Suspended", "Revoked, Expired", or "Active, NotRenewable"
1-byte length Entry n's creation date in YYYY/MM/DD form, exactly 10 bytes
1-byte length Entry n's last modified date in YYYY/MM/DD form, exactly 10 bytes
1-byte length Entry n's ApplData value from the GENCERT or REQCERT invocation, max 8 bytes
1-byte length Entry n's ExtKeyUsage value, max 255 bytes (one or more of 'serverauth' | 'clientauth' | 'codesigning' | 'emailprotection' | 'timestamping' | 'ocspsigning' | 'mssmartcardlogon' | 'cmcca' | 'cmcra' | 'cmcas' | 'pkinitkdc' | 'pkinitclientauth' or "not specified")
1-byte length Entry n's KeyId, exactly 40 bytes (printable EBCDIC)
Table 14. Function_parmlist for CERTDETAILS
Field Attributes Usage Description
Eyecatcher 8 characters In Eyecatcher, 8 characters left-aligned blank filled. Actual value set by invoker, for example, ' CRTDTAIL'
SumListLen 4-byte length In/Out 4-byte area that is the length of the pre-allocated storage of the Summary List area on input to CERTDETAILS. RACF will update this value with the actual length of the data returned. If the storage area as specified by the Summary List address is too small, RACF will set a failing return/reason code and update the length field to the size required. The caller must allocate a larger area.
SumList Address of In/Out The address of the storage area in which the R_PKIServ service stores the results of the query if the service was able to successfully retrieve the data. If the caller has supplied an area which is too small, (based in the SummaryListLen), this service fails the request, and updates the SummaryListLen field to indicate the actual storage required to store the data. Also, see Table 15.
CertPlistLen 4-byte length In/Out 4-byte area that is the length of the pre-allocated storage of the certificate generation plist area on input to CERTDETAILS. RACF will update this value with the actual length of the data returned. If the storage area as specified by the Results List address is too small, RACF will set a failing return/reason code and update the length field to the size required. The caller must allocate a larger area.
Start of changeSerialNumOrFingerPrtEnd of change Start of changeAddress ofEnd of change Start of changeInEnd of change Start of changeThere are three acceptable formats:
  1. Points to a 17-byte area, in which the first byte will contain the actual length of the input certificate serial number from which details are to be extracted. The serial number is in printable EBCDIC (HEX) form for example, "01A6".
  2. Points to a 65-byte area, in which the first byte will contain the actual length of the input certificate SHA256 fingerprint with no separators. The fingerprint is in printable EBCDIC (HEX) form. For example: “9C3E4AFCC491DFD332F3089B8542E9417D893D7FE944E10A7937EE29D9693DAE”.
  3. Points to a 96-byte area, in which the first byte will contain the actual length of the input certificate SHA256 finger print with colon or blank separators. The fingerprint is in printable EBCDIC (HEX) form, separated by colons or blanks e.g., “9C:3E:4A:FC:C4:91:DF:D3:32:F3:08:9B:85:42:E9:41: 7D:89:3D:7F:E9:44:E1:0A:79:37:EE:29:D9:69:3D:AE”, or “9C 3E 4A FC C4 91 DF D3 32 F3 08 9B 85 42 E9 41 7D 89 3D 7F E9 44 E1 0A 79 37 EE 29 D9 69 3D AE”.
End of change
CertPlist Address of In/Out The address of the storage area in which the R_PKIServ service stores the results of the query if the service was able to successfully retrieve the data. If the caller has supplied an area which is too small, (based in the CertPlistLen), this service fails the request, and updates the CertPlistLen field to indicate the actual storage required to store the data. This area maps some of the specific name, length, address/data values which were used when generating the original certificate request on GENCERT. Also, see Table 16.
SerialNum Address of In Points to a 17-byte area, in which the first byte will contain the actual length of the input certificate serial number from which details are to be extracted. The serial number is in printable EBCDIC (HEX) form for example, "01A6",

The CERTDETAILS function returns QUERYCERTS style summary data in the SumList area provided by the caller. The SumList has the following format:

Table 15. SumList for CERTDETAILS
Length Value
1-byte length Entry's serial number in printable EBCDIC(HEX) form for example, "01A6", max 16 bytes
1-byte length Entry's requestor's name, max 32 bytes
1-byte length Entry's subject's distinguished name, max 255 bytes
1-byte length Entry's issuer's distinguished name, max 255 bytes
1-byte length Entry's validity period in local time. Format YYYY/MM/DD HH:MM:SS - YYYY/MM/DD HH:MM:SS. Exactly 41 bytes
1-byte length Entry's keyUsage value, max 64 bytes (one or more of 'handshake' |'dataencrypt' |'certsign' |'docsign' |'digitalsig' | 'keyencrypt' | 'keyagree' | 'keycertsign' | 'crlsign' or "not specified")
1-byte length Entry's status, max 32 bytes, one of "Active", "Active, AutoRenew", "Active, AutoRenewDisabled", "Expired", "Revoked", "Suspended", "Revoked, Expired", or "Active, NotRenewable"
1-byte length Entry's creation date in YYYY/MM/DD form, exactly 10 bytes
1-byte length Entry's last modified date in YYYY/MM/DD form, exactly 10 bytes
1-byte length Entry's ApplData value from the GENCERT or REQCERT invocation, max 8 bytes
1-byte length Entry's last action comment, max 64 bytes
1-byte length Entry's ExtKeyUsage value, max 255 bytes (one or more of 'serverauth' | 'clientauth' | 'codesigning' | 'emailprotection' | 'timestamping' | 'ocspsigning' | 'mssmartcardlogon' | 'cmcca' | 'cmcra' | 'cmcas' | 'pkinitkdc' | 'pkinitclientauth' or "not specified")
1-byte length Entry's pass phrase provided when the certificate request was made, max 32 bytes
1-byte length Entry's KeyId, exactly 40 bytes (printable EBCDIC)
Start of change1-byte lengthEnd of change Start of changeEntry's SHA256 fingerprint, exactly 95 bytes (printable EBCDIC, colon separated)End of change
1-byte length
Entry’s certificate signature algorithm, max 32 bytes, one of
'sha-1WithRSAEncryption', 'sha-224WithRSAEncryption',
'sha-256WithRSAEncryption', 'sha-384WithRSAEncryption',
'sha-512WithRSAEncryption', 'md-5WithRSAEncryption',
'sha-256With RSAPSS', 'sha-384WithRSAPSS',
'sha512WithRSAPSS'
'md-2WithRSAEncryption', 'id-dsa-with-sha1',
'id-dsa-with-sha224' , 'id-dsa-with-sha256' ,
'ecdsa-with-sha1', 'ecdsa-with-sha224', 'ecdsa-with-sha256',
'ecdsa-with-sha384' or 'ecdsa-with-sha512'
1-byte length Entry’s Key type, max 16 bytes, one of 'RSA', 'DSA', 'BPECC' or 'NISTECC'
1–byte length Entry's Public Key size in bits, expressed as a decimal character string (EBCDIC, for example, "1024"). Zero bytes if unavailable

Additionally, the CERTDETAILS function returns GENCERT style certificate field name/value pairs in the CertPlist area. This is the list of fields that may be returned. The fields and their values are conditionally present, depending on the values of the original GENCERT request. Multiple HostIdMaps are returned in the order they were originally specified. Fields other than HostIdMap are not returned in any specific order. Like GENCERT, the CertPlist returned is a list of ordered triplets which consists of name, length and data value. The field name is a fixed 12-character field, case sensitive, left-aligned, and padded with blanks, the length field is a binary four byte value, which qualifies the length of the data item. Note that all data values are EBCDIC character data unless otherwise indicated.

Table 16. CertPlist for CERTDETAILS
Field Max length Description
AltIPAddr 45 bytes IP address in IPv4 or IPv6 format for subject alternative name extension. Note that this field may be repeated.
AltURI 255 bytes Uniform Resource Identifier for subject alternative name extension. Note that this field may be repeated.
AltEmail 100 bytes Email address for subject alternative name extension. Note that this field may be repeated.
AltDomain 100 bytes Domain Name for subject alternative name extension. Note that this field may be repeated.
AltOther 255 bytes Other Name for subject alternative name extension. Note this field may be repeated.
HostIdMap 100 bytes HostIdMapping extension entry. Note this field may be repeated.
CustomExt 1024 bytes Customized extension in the form of a comma-separated four-part string. The first part is the OID of the extension. The second part is the critical flag – ‘C’(critical) or ‘N’(non-critical), the third part is the encode type – ‘INT’(integer in printable hexadecimal format), ‘IA5’(IA5 string), ‘PRT’(printable string), ‘BMP’(BMP string) , ‘OCT’(Octet string) or ‘UTF’(UTF8 string), the last part is the value. Note that this field may be repeated.
Table 17. Function_parmlist for MODIFYCERTS
Field Attributes Usage Description
Eyecatcher 8 characters In Eyecatcher, 8 characters left-aligned blank filled. Actual value set by invoker, for example, 'MODCERTS'.
Action 4-byte value In 4-byte binary value indicating the action to take with the certificates.
  • X'00000002' - Revoke
  • X'00000003' - Delete from issued certificate database
  • X'00000004' - Resume suspended certificate
  • X'00000005' - Disable auto renew
  • X'00000006' - Enable auto renew
  • X'00000007' - Change requestor email
  • X'00000008' - Create CRLs
  • X'00000009' - Post Certs
Comment Address of In Points to a 65-byte area, in which the first byte will contain the actual length of the comment associated with this action. If the first byte is zero (x'00'), no comment will be recorded.

If the action is X'00000008' (Create CRLs), this field is ignored.
SerialNumsLen 4-byte length In/Out Describes the length in bytes of the input certificate serial number list. May be modified by RACF on output if a smaller list is being returned.

If the action is X'00000008' (Create CRLs), this field is ignored.
SerialNums Address of In/Out Points to an area containing 1 or more certificate serial numbers that are to be modified by this request. Each occupies a maximum of 17 bytes, in which the first byte will contain the actual length of the certificate serial number. The serial number itself is in printable EBCDIC (HEX) form for example, "01A6", If any certificates cannot be modified, RACF will return a shortened list containing those serial numbers that couldn't be modified. The ErrList field will contain the corresponding error description. If the action is X'00000007' - Change requestor email, this field must contain only 1 serial number.

If the action is X'00000008' (Create CRLs), this field is ignored.
Reason 4-byte value In 4-byte binary value indicating the reason for the certificate revocation.
  • X'00000000' - No Reason
  • X'00000001' - User key was compromised
  • X'00000002' - CA key was compromised
  • X'00000003' - User changed affiliation
  • X'00000004' - Certificate was superseded
  • X'00000005' - Original use no longer valid
  • X'00000006' - Temporarily suspend
Ignored for actions other than "Revoke".
RequestorEmail Address of In Points to a 33-byte area in which the first byte will contain the actual length of the email address to be changed. Only valid with action X'00000007' - Change requestor email. The minimum Parmlist_Version for the use of this parameter is 1.
ErrListLen 4-byte length In/Out 4-byte area that is the length of the pre-allocated storage for the Error List output area. May be modified by RACF on output to reflect the actual length of ErrList for certain reason and return codes. See Table 6. If the action is X'00000008' (Create CRLs) or X'00000009' (Post Certs), this field is ignored. The minimum Parmlist_Version for the use of this parameter is 2.
ErrList Address of In/Out Points to an area containing 1 or more error results when any of the input certificates cannot be modified for certain reason and return codes. See Table 6. Each error result occupies a maximum of 100 bytes, in which the first byte is the actual length of the error description for the corresponding serial number returned in the SerialNums field. If the action is X'00000008' (Create CRLs) or X'00000009' (Post Certs), this field is ignored. The minimum Parmlist_Version for the use of this parameter is 2.
Table 18. Function_parmlist for VERIFY
Field Attributes Usage Description
Eyecatcher 8 characters In Eyecatcher, 8 characters left-aligned blank filled. Actual value set by invoker, for example, ' VERIFY '.
SumListLen 4-byte length In/Out 4-byte area that is the length of the pre-allocated storage of the Summary List area on input to VERIFY. RACF will update this value with the actual length of the data returned. If the storage area as specified by the Summary List address is too small, RACF will set a failing return/reason code and update the length field to the size required. The caller must allocate a larger area.
SumList Address of In/Out The address of the storage area in which the R_PKIServ service stores the results of the verify if the service was able to successfully retrieve the data. If the caller has supplied an area which is too small, (based in the SummaryListLen) this service fails the request, and updates the SummaryListLen field to indicate the actual storage required to store the data. Also, see Table 19.
CertPlistLen 4-byte length In/Out 4-byte area which is the length of the pre-allocated storage of the certificate generation plist area on input to VERIFY. RACF will update this value with the actual length of the data returned. If the storage area as specified by the Results List address is too small, RACF will set a failing return/reason code and update the length field to the size required. The caller must allocate a larger area.
CertPlist Address of In/Out The address of the storage area in which the R_PKIServ service stores the results of the verify if the service was able to successfully retrieve the data. If the caller has supplied an area which is too small, (based in the CertPlistLen) this service fails the request, and updates the CertPlistLen field to indicate the actual storage required to store the data. This area maps some of the specific name, length, address/data values which were used when generating the original certificate request on GENCERT. Also, see Table 20.
CertLen 4-byte length In 4-byte area that is the length of the certificate contained in the Cert area on input to VERIFY.
Cert Address of In The address of the storage area containing the X509 certificate or the PKCS #7 certificate chain to verify. This is base64 encoded DER.
The VERIFY function returns CERTDETAILS style summary data in the SumList area provided by the caller. The SumList has the following format:
Table 19. SumList for VERIFY
Length Value
1-byte length Entry's serial number in printable EBCDIC(HEX) form for example, "01A6", max 16 bytes
1-byte length Entry's requestor's name, max 32 bytes
1-byte length Entry's subject's distinguished name, max 255 bytes
1-byte length Entry's issuer's distinguished name, max 255 bytes
1-byte length Entry's validity period in local time. Format YYYY/MM/DD HH:MM:SS - YYYY/MM/DD HH:MM:SS. Exactly 41 bytes
1-byte length Entry's keyUsage value, max 64 bytes (one or more of 'handshake' | 'dataencrypt' | 'certsign' | 'docsign' | 'digitalsig' | 'keyencrypt' | 'keyagree' | 'keycertsign' | 'crlsign' or "not specified")
1-byte length Entry's status, max 32 bytes, one of "Active", "Active, AutoRenew", "Active, AutoRenewDisabled", "Expired", "Suspended", "Revoked", "Revoked, Expired", or "Active, NotRenewable"
1-byte length Entry's creation date in YYYY/MM/DD form, exactly 10 bytes
1-byte length Entry's last modified date in YYYY/MM/DD form, exactly 10 bytes
1-byte length Entry's ApplData value from the GENCERT or REQCERT invocation, max 8 bytes
1-byte length Entry's ExtKeyUsage value, max 255 bytes (one or more of 'serverauth' | 'clientauth' | 'codesigning' | 'emailprotection' | 'timestamping' | 'ocspsigning' | 'mssmartcardlogon' | 'cmcca' | 'cmcra' | 'cmcas' | 'pkinitkdc' | 'pkinitclientauth' or "not specified")
Additionally, the VERIFY function returns GENCERT style certificate field name/value pairs in the CertPlist area. The fields and their values are conditionally present, depending on the values actually contained in the certificate. Fields are not returned in any specific order. Like GENCERT, the CertPlist is a list of ordered triplets which consists of name, length and data value. The field name is a fixed 12-character field, case sensitive, left-aligned, and padded with blanks, the length field is a binary four byte value, which qualifies the length of the data item. Note that all data values are EBCDIC character data unless otherwise indicated.
Table 20. CertPlist for VERIFY
Field Max length Description
AltIPAddr 45 bytes IP address in IPv4 or IPv6 format for subject alternative name extension. Note that this field may be repeated.
AltURI 255 bytes Uniform Resource Identifier for subject alternative name extension. Note that this field may be repeated.
AltEmail 100 bytes Email address for subject alternative name extension. Note that this field may be repeated.
AltDomain 100 bytes Domain Name for subject alternative name extension. Note that this field may be repeated.
AltOther 255 bytes Other Name for subject alternative name extension. Note this field may be repeated.
HostIdMap 100 bytes HostIdMapping extension entry. Note this field may be repeated.
CustomExt 1024 bytes Customized extension in the form of a comma-separated four-part string. The first part is the OID of the extension. The second part is the critical flag – ‘C’(critical) or ‘N’(non-critical), the third part is the encode type – ‘INT’(integer in printable hexadecimal format), ‘IA5’(IA5 string), ‘PRT’(printable string), ‘BMP’(BMP string) , ‘OCT’(Octet string) or ‘UTF’(UTF8 string), the last part is the value. Note that this field may be repeated.
Table 21. Function_parmlist for REVOKE
Field Attributes Usage Description
Eyecatcher 8 characters In Eyecatcher, 8 characters left-aligned blank filled. Actual value set by invoker, for example, ' REVOKE '
Reason 4-byte value In 4-byte binary value indicating the reason for the certificate revocation,
  • X'00000000' - No Reason
  • X'00000001' - User key was compromised
  • X'00000002' - CA key was compromised
  • X'00000003' - User changed affiliation
  • X'00000004' - Certificate was superseded
  • X'00000005' -Original use no longer valid
  • X'00000006' - Temporarily suspended
SerialNum Address of In Points to a 17-byte area, in which the first byte will contain the actual length of the input certificate serial number for the certificate that is to be revoked. The serial number is in printable EBCDIC (HEX) form for example, "01A6",
Table 22. Function_parmlist for GENRENEW and REQRENEW
Field Attributes Usage Description
Eyecatcher 8 characters In Eyecatcher, 8 characters left-aligned blank filled. Actual value set by invoker, for example, ' RENEW '
CertPlistLen 4-byte length In Describes the length in bytes of the certificate generation plist. A zero indicates no modification plist
CertPlist Address of In The name of the area which is the renew request parameter list. This area maps the specific name, length, address/data values which are used in satisfying the certificate request for the specified user. Also, see Table 23.
CertId Address of In/Out Points to a 57-byte area, in which the first byte will contain the actual length on return of the certificate request ID. The storage address specified must be obtained by the caller, and freed by the caller. The returned certificate request ID is used to extract the completed certificate, if the request has been accepted.
SerialNum Address of In Points to a 17-byte area, in which the first byte will contain the actual length of the input certificate serial number for the certificate that is to be renewed. The serial number is in printable EBCDIC (HEX) form for example, "01A6",

Here is the layout and supported fields for the RENEW CertPlist. Because most of the certificate information from the old certificate is reused for the new certificates, very little new information can be specified in the RENEW CertPlist. Like GENCERT, the CertPlist is a list of ordered triplets that consists of name, length and data value. The field name is a fixed 12-character field, case sensitive, left-aligned, and padded with blanks. The length field is a binary four byte value, which qualifies the length of the data item. Note that all data values are EBCDIC character data unless otherwise indicated. See GENCERT for more information about the other individual fields

Table 23. CertPlist for GENRENEW and REQRENEW
Field name Max length Description
DiagInfo 80 bytes (exactly) Diagnostic information area. Must be first field in the CertPlist. For certificate generation warnings and errors, RACF will update this field with diagnostic information. The length will be updated as well. Required field.
PassPhrase 32 bytes Value to be used for challenge/response when retrieving the certificate through function EXPORT. When renewing a certificate whose key pair was generated by PKI Services, the PassPhrase from the original certificate will be used if this field is not specified. Optional.
NotAfter 4 bytes Number of days from today's date that the certificate expires. Range 1-9999. Validity checked by RACF. Optional. Default is 365. The start date of the validity period is set from the original certificate's start of validity.
NotifyEmail 64 bytes Email address for notification purposes. When renewing a certificate whose key pair was generated by PKI Services, the specified value must not exceed 32 characters. If this field is not specified, the notification email address of the original certificate will be used. Optional.
CertPolicies 32 bytes Blank separated array of non-repeating policy numbers. Range 1 - 99, for the CertificatePolicies extension. These correspond to the policy numbers defined during PKI Services configuration. Each value must be one or two digits with no leading zeros. Optional, no default.
AuthInfoAcc 255 bytes A comma separated two part string specifying information used to create the AuthorityInfoAccess extension. The two part string identifies the accessMethod and accessLocation. The accessMethod is one of 'OCSP' | 'IdentrusOCSP' (not case sensitive, no quotes). The accessLocation is a URI in the form URI=access-url or URL=access-url. Optional, no default. Note this field may be repeated.
Critical 32 bytes Name of a certificate extension to be marked critical. One of 'CertificatePolicies' | 'CertPolicies' (not case sensitive, no quotes). Optional.
Table 24. Function_parmlist for RESPOND
Field Attributes Usage Description
Eyecatcher 8 characters In Eyecatcher, 8 characters left-aligned blank filled. Actual value set by invoker, for example 'RESPOND'
RestLen 4-byte length In/Out 4-byte area that is the length of the pre-allocated storage of the OCSP response area on input to RESPOND. RACF will update this value with the actual length of the data returned. If the storage area as specified by the Response address is too small, RACF will set a failing return/reason code and update the length field to the size required. The caller must allocate a larger area.
Response Address of In/Out The address of the storage area in which the R_PKIServ service stores the results of the RESPOND function if the service was able to successfully retrieve the data. If the caller has supplied an area which is too small, (based in the ResLen), this service fails the request, and updates the ResLen field to indicate the actual storage required to store the data.
ReqLen 4-byte length In 4-byte area that is the length of the request contained in the Request area on input to RESPOND.
Request Address of In The address of the storage area containing the request to verify.
Table 25. Function_parmlist for SCEPREQ
Field Attributes Usage Description
Eyecatcher 8 characters In Eyecatcher, 8 characters left-aligned blank filled. Actual value set by invoker, for example, ' SCEPREQ '
RestLen 4-byte length In/Out 4-byte area that is the length of the pre-allocated storage of the SCEP response area on input to SCEPREQ. RACF will update this value with the actual length of the data returned. If the storage area, as specified by the Response address is too small, RACF sets a failing return/reason code and update the length field to the size required. The caller must allocate a larger area.
Response Address of In/Out The address of the storage area in which the R_PKIServ service stores the results of the SCEPREQ function if the service was able to successfully retrieve the data. If the caller has supplied an area which is too small, (based in the ResLen), this service fails the request, and updates the ResLen field to indicate the actual storage required to store the data.
ReqLen 4-byte length In 4-byte area that is the length of the SCEP request contained in the Request area on input to SCEPREQ.
Request Address of In The address of the storage area containing the SCEP request to verify.
Table 26. Function_parmlist for PREREGISTER
Field Attributes Usage Description
Eyecatcher 8 characters In Eyecatcher, 8 characters left-aligned blank filled. Actual value set by invoker, for example, ' PREREG '
PreregPlistLen 4-byte length In Describes the length in bytes of the preregistration plist
PreregPlist Address of In The name of the area which is the preregistration parameter list. This area maps the specific name, length, address or data values which must match the values specified when the certificate request is received.
CertId Address of In/Out Points to a 57-byte area, in which the first byte will contain the actual length on return of the certificate request ID. The storage address specified must be obtained by the caller, and freed by the caller. The returned certificate request ID is used to query the preregistration record, if the request has been accepted by RACF.
Like GENCERT, the Preregistration CertPlist is a list of ordered triplets which consists of name, length and data value. The data values provided on PREREGISTER must match the values specified when the certificate request is received, otherwise the requestor is considered unauthenticated. The field name is a fixed 12-character field, case sensitive, left-aligned, and padded with blanks, the length field is a binary 4-byte value, which qualifies the length of the data item.
Note: All data values are EBCDIC character data unless otherwise indicated. See GENCERT for more information about the other individual fields.
Table 27. CertPlist for PREREGISTER
Field name Max length Description
DiagInfo 80 bytes (exactly) EyeCatcher to identify this request in virtual storage for diagnostic reasons. For certificate generation warnings and errors RACF will update this field with diagnostic information. The length will be updated as well. Required field. Must be first field in the CertPlist.
ClientName 64 bytes Name of the person or device that is being preregistered. Must match either the CommonName or the UnstructName when the certificate request is received. Required field.
PassPhrase 32 bytes Challenge/response value to be used for authenticating when the certificate request is received. Optional. No default.
SerialNumber 64 bytes Serial number of the subject device. Optional. No default.
UnstructAddr 64 bytes Unstructured address of the subject device. Optional. No default.
EmailAddr 64 bytes Subject’s email address for distinguished name EMAIL= attribute. Optional. No default.
Mail 64 bytes Subject’s email address for distinguished name MAIL= attribute. Optional. No default.
DNQualifier 64 bytes Subject’s Distinguished Name Qualifier. Optional. No default.
Uid 64 bytes Subject’s login ID. Optional. No default.
Title 64 bytes Subject’s Title. Optional. No default.
DomainName 64 bytes Subject’s Domain Name containing all the domain components in the form of domain-component-1.domain-component-2.domain-component-3…domain-component-n. Optional. No default.
OrgUnit 64 bytes Subject’s Organizational Unit. Note this field may be repeated, RACF concatenates in the order of appearance to construct the hierarchy of organizational units. Optional. No default.
Org 64 bytes Subject’s Organization. Optional. Optional. No default.
Street 64 bytes Subject’s Street Address. Optional. No default.
Locality 64 bytes Subject’s City or Locality. Optional. No default.
StateProv 64 bytes Subject’s State/Province. Optional. No default.
PostalCode 64 bytes Subject’s Zip code or Postal Code. Optional. No default.
Country 2 bytes Subject’s Country. Optional. No default.
AltIPAddr 45 bytes IP address in IPv4 or IPv6 format for subject alternate name extension. Optional. No default. Note that this field may be repeated.
AltURI 255 bytes Uniform Resource Identifier for subject alternate name extension. Optional. No default. Note that this field may be repeated.
AltEmail 100 bytes Email address for subject alternate name extension. Optional. No default. Note that this field may be repeated.
AltDomain 100 bytes Domain Name for subject alternate name extension.Optional. No default. Note that this field may be repeated.
AltOther 255 bytes Other Name for subject alternate name extension. Optional. No default. Note this field may be repeated.
BusinessCat 64 bytes Subject's business category. Optional. No default. Only valid with PKI Services requests.
Note: It is recommended that this field be used only in requests for Extended Verification certificates.
JurCountry 2 bytes Subject's Jurisdiction Country. Optional. No default. Only valid with PKI Services requests.
Note: It is recommended that this field be used only in requests for Extended Verification certificates.
JurStateProv 64 bytes Subject's Jurisdiction State/Province. Optional. No default. Only valid with PKI Services requests.
Note: It is recommended that this field be used only in requests for Extended Verification certificates.
JurLocality 64 bytes Subject's Jurisdiction Locality. Optional. No default. Only valid with PKI Services requests.
Note: It is recommended that this field be used only in requests for Extended Verification certificates.
Table 28. Function_parmlist for QRECOVER
Field Attributes Usage Description
Eyecatcher 8 characters In Eyecatcher, 8 characters left-aligned blank filled. Actual value set by invoker, for example 'QRECOVER'.
ResultsListLen 4-byte length In/Out 4-byte area which is the length of the pre-allocated storage of the Results List area on input to QRECOVER. RACF will update this value with the actual length of the data returned. If the storage area as specified by the Results List address is too small, RACF will set a failing return/reason code and update the length field to the size required. The caller must allocate a larger area.
ResultsList Address of In/Out The address of the storage area in which the R_PKIServ service stores the results of the query if the service was able to successfully retrieve the data. If the caller has supplied an area which is too small, (based in the ResultsListLen), this service fails the request, and updates the ResultsListLen field to indicate the actual storage required to store the data.
NumEntries 4-byte numeric In/Out Input value indicating the maximum number of entries that should be returned in the ResultsList area. Zero indicates no limit. Updated to indicate the number of entries actually returned.
CriteriaName Address of In Points to a 33-byte area, in which the first byte will contain the actual length of the input requestor’s email address to be used as a search criterion.
CriteriaPass Address of In Points to a 33-byte area, in which the first byte will contain the actual length of the input pass phrase to be used as a search criterion.
The QRECOVER function returns results in the ResultsList area provided by the caller. The results list has the following format:
Table 29. ResultsList for QRECOVER
Length Value
1-byte length Entry 1's serial number in printable EBCDIC (HEX) form for example, "01A6", max 16 bytes
1-byte length Entry 1’s subject’s distinguished name, max 255 bytes
1-byte length Entry 1’s issuer’s distinguished name, max 255 bytes
1-byte length Entry 1’s validity period in local time. Format YYYY/MM/DD HH:MM:SS - YYYY/MM/DD HH:MM:SS. Exactly 41 bytes
1-byte length Entry 1’s Pass phrase provided when the certificate request was made, max 32 bytes
1-byte length Entry 1’s KeyId, exactly 40 bytes (printable EBCDIC)
1-byte length Entry 2’s serial number in printable EBCDIC (HEX) form for example, “01A6”, max 16 bytes
1-byte length Entry 2’s subject’s distinguished name, max 255 bytes
1-byte length Entry 2’s issuer’s distinguished name, max 255 bytes
1-byte length Entry 2’s validity period in local time. Format YYYY/MM/DD HH:MM:SS - YYYY/MM/DD HH:MM:SS. Exactly 41 bytes
1-byte length Entry 2's Pass phrase provided when the certificate request was made, max 32 bytes
1-byte length Entry 2’s KeyId, exactly 40 bytes (printable EBCDIC)
⋮
Length, continued Value, continued
1-byte length Entry n’s serial number in printable EBCDIC (HEX) form for example, “01A6”, max 16 bytes
1-byte length Entry n’s subject’s distinguished name, max 255 bytes
1-byte length Entry n’s issuer’s distinguished name, max 255 bytes
1-byte length Entry n’s validity period in local time. Format YYYY/MM/DD HH:MM:SS - YYYY/MM/DD HH:MM:SS. Exactly 41 bytes
1-byte length Entry n’'s Pass phrase provided when the certificate request was made, max 32 bytes
1-byte length Entry 1’s KeyId, exactly 40 bytes (printable EBCDIC)
CA_domain
The name of an optional 9-byte input area that consists of a 1-byte length field followed by up to 8 characters from the following character set: the alphanumerics (a-z, A-Z, 0-9) and the hyphen ('-'). In addition, the leftmost character must not be a digit or the hyphen. The value is the not case-sensitive domain name of the PKI Services certificate authority instance to be invoked. If Number_parameters is less than 6, CA_domain is null, or the length byte is 0, then the default instance of PKI Services will be invoked. This field is ignored for SAF requests.