This section provides a detailed reference of all the service interfaces available on an agent port. For each interface, there is
The following table lists the end-entity interfaces and their functions:
Approve Revocation Interface
Description
URI: /ca/doRevoke or /ra/doRevoke
Available on: Certificate Manager or Registration Manager
Function: Actually revokes a certificate or group of certificates for a given reason.
The Select for Revocation Interface is used to select a certificate or group of certificates for revocation based on some criteria. That interface returns a list of certificates using the reasonToRevoke.template file. The reasonToRevoke.template response contains a form that posts data to the Approve Revocation interface with the serial numbers and reasons to finally revoke the certificates.
Default Forms
The Approve Revocation interface is accessed through the reasonToRevoke.template file by default. No forms directly post data to this interface. Other forms, such as revokeCert.html, are used to select certificates based on query criteria; the selected certificates can then be marked for revocation by creating buttons or links that post data to the Approve Revocation interface.
Request Parameters
The following table lists the parameters that are used to revoke certificates through the Approve Revocation interface. This is an agent interface, so the HTTP POST or GET request must use SSL client authentication with a valid agent certificate.
Response
The default response template is revocationResult.template. The base JavaScript for responses is inserted in place of the <CMS_TEMPLATE> tag. In addition, the Approve Revocation interface adds the JavaScript variables listed in the following table.
Bulk Enrollment Interface
Description
URI: /ca/bulkissuance
Available on: Certificate Manager only
Function: The Bulk Enrollment interface allows a connection using SSL client authentication with a valid agent certificate to have a certificate issued on behalf of another entity. The entire process is automated so that a device or application with an agent certificate, the ability to do SSL client authentication, and the ability to parse and store the certificate in the response can programmatically request and receive certificates.
An application or hardware device that can also generate keys could use the Bulk Enrollment interface to generate keys, request a certificate for the public key, receive the certificate and store it (for example on a smart card to be distributed to a user).
The reply from the Bulk Enrollment interface can be just the certificate chain (in PKCS #7format), or it can be an HTML page.
Configuration Parameters
The Bulk Enrollment interface can be configured with parameters in the CMS.cfg configuration file.
The interface can be enabled or disabled using the agentGateway.enableBulkInterface parameter. The rest of the parameters configure which template file to use when a response has a given requestStatus code. The template configuration parameter names should be prefixed with agentGateway.bulkissuance. For example, agentGateway.bulkissusance.successTemplate=/ca/bulkissuance.template.
The following table lists the valid configuration file parameters and what they control. The file names for the template parameters are relative to the <server_root>/<instance_id>-cert/web/agent directory.
Default Forms
No default forms use the Bulk Enrollment interface. The intent of the interface is to provide a programmatic, rather than interactive, method for enrolling entities into the PKI.
Request Parameters
The following table lists the parameters accepted by the Bulk Enrollment interface.
Note that the Bulk Enrollment interface requires SSL Client authentication with an agent certificate authorized to approve certificate requests. Table 24.36 Parameters Accepted by the Bulk Enrollment Interface
Parameter
| Format and Description
|
Subject Name
|
|
subject
| Distinguished Name (DN) string. See RFC 2253. DN to be used for the certificate subject. Example: CN=Alice Apple, UID=alice, OU=People, O=Example, C=US
|
Contact Information
|
|
csrRequestorName
| string Name of the entity making a request; helps identify the requestor during manual enrollment. Example: Alice Apple
|
csrRequestorEmail
| string Email address of the entity making a request. May be used to send out notification when a certificate has been issued. Example: alice@example.com
|
csrRequestorPhone
| string Phone number of the entity making a request. Example: 650.555.1212
|
csrRequestorComments
| string Additional comments provide by the requestor on the HTML form. This field can be used if there is additional information you want to collect to help the manual enrollment.
|
Netscape Certificate Type Extensions
| Parameters for setting bits in the netscape-cert-type certificate extension. See http://home.netscape.com/eng/security/comm4-cert-exts.html for details. A true value sets the bit to 1; false sets the bit to 0.
|
email
| true | false Sets the S/MIME client certificate bit (bit 2).
|
email_ca
| true | false Sets the S/MIME certificate issuer bit (bit 6).
|
object_signing
| true | false Sets the object signing certificate bit (bit 3).
|
object_signing_ca
| true | false Sets the object signing certificate issuer bit (bit 7).
|
ssl_ca
| true | false Sets the SSL certificate issuer bit (bit 5).
|
ssl_client
| true | false Sets the SSL client authentication certificate bit (bit 0).
|
ssl_server
| true | false Sets the SSL server authentication certificate bit (bit 1).
|
Key Usage
| Parameters for setting bits in the keyUsage certificate extension. A true value sets the bit to 1; false sets the bit to 0.
|
crl_sign
| true | false Sets the keyUsage extension bit (6) indicating that the key may be used to sign Certificate Revocation Lists (CRLs).
|
data_encipherment
| true | false Sets the keyUsage extension bit (3) indicating that the key may be used to encipher application data (as opposed to key material).
|
decipher_only
| true | false Sets the keyUsage extension bit (8) indicating that the key may only be used to decipher data and keys. If this is true, keyAgreement should also be true.
|
digital_signature
| true | false Sets the keyUsage extension bit (0) indicating that the key may be used to sign any data. This should be true for SSL client certificates, S/MIME signing certificates, and object signing certificates.
|
encipher_only
| true | false Sets the keyUsage extension bit (7) indicating that the key may only be used to encipher data and keys. If this is true, keyAgreement should also be true.
|
key_agreement
| true | false Sets the keyUsage extension bit (4) indicating that the key may be used to encipher and decipher keys during key agreement.
|
key_certsign
| true | false Sets the keyUsage extension bit (5) indicating that the key may be used to sign other certificates. All CA signing certificates should set this to true.
|
key_encipherment
| true | false Sets the keyUsage extension bit (2) indicating that the key may be used to encipher symmetric session keys. This should be true for SSL server and S/MIME encryption certificates.
|
non_repudiation
| true | false Sets the keyUsage extension bit (1) indicating that the key may be used to create non-repudiable (by the signer) digital signatures. Non-repudiation service requires more infrastructure, planning, and policy than just setting this bit. Consider the ramifications before using this bit
|
Automated Enrollment
| Parameters to configure automatic authentication for entity requests.
|
authenticator
| string Specifies the name of the authentication plug-in instance to use to authenticate the entity.
|
uid
| string Specifies a unique identifier passed to the authentication plug-in.
|
pin
| string An optional identifying string that helps to authenticate an entity. Usually used when the Pin Generator tool has been used to populate a directory with unique identifiers for each user.
|
pwd
| string Specifies the password passed to the authentication plug-in.
|
Other
|
|
certNickname
| string Specifies the nickname that should be associated with the certificate in the reply; used with Certificate Request Management Format (CRMF) requests.
|
certType
| ca | CEP-Request | client | objSignClient | ra | server | other Specifies the type of certificate requested by the entity. The default is client. The certType is not associated with any certificate extensions. It may be used by policy modules to make decisions, and it may be used by a CMS server to determine how to decode the request or format the response.
|
challengePassword
| string An optional challenge phrase or password that can be used later by the entity to revoke the certificate. This parameter is optional. If you use this, entities can use the Challenge Revocation Interface (/challenge_revocation1) with this challenge password to revoke a certificate without manual intervention and without SSL client authentication.
|
CRMFRequest
| base-64 encoded data If requestFormat = crmf, this parameter should be used to send the base-64 encoded CRMF request.
|
importCAChain
| true | false Used only when importCert = true. The default, if this parameter is not explicitly passed, is true. If set to true, a successful certificate request will return a PKCS #7 formatted certificate chain; if set to false, a single, DER-encoded certificate will be returned. The certificate chain includes the issued certificate and the CA (issuer) certificate.
|
importCert
| true | false If true, and the certificate request is not deferred or rejected, the CMS server's response will be binary data with the MIME type determined by the importCertMimeType parameter. The data returned will be either a certificate or a certificate chain, based on the value of importCAChain.
|
importCertMimeType
| MIME Type string Sets the MIME type the CMS server uses when a certificate is returned to the requestor. The default is application/x-x509-user-cert. The MIME type should be in the standard MIME type format of <type>/<subtype>.
|
pkcs10Request
| base-64 encoded data If requestFormat = pkcs10, this parameter should be used to send the base-64 encoded certificate request.
|
requestFormat
| clientAuth | crmf | keygen | pkcs10 The value indicates the format used to submit the certificate request:
|
subjectKeyGenInfo
| base-64 encoded data If requestFormat=keygen, this parameter should be used to send the base-64 encoded keygen request. To use the keygen HTML tag to cause the browser to generate the request using this parameter, the format is <KEYGEN name="subjectKeyGenInfo">
|
templateName
| string Filename relative to the template directory (web/ee, web/agent/ca, web/agent/kra, or web/agent/ra) of a file to use as the response template. This template will be used for any response, overriding default template settings.
|
Response
If the request parameter importCert is set to true and the certificate request is successful, the Certificate Manager will return the binary PKCS #7 certificate chain using the MIME type application/x-x509-user-cert. This is the most useful application of the Bulk Enrollment interface.
If importCert is not set to true, or if there is an error, the default response template is bulkissuance.template. Applications using the Bulk Enrollment interface should be prepared to handle the HTML output created using the template when errors occur.
The base JavaScript for responses is inserted in place of the <CMS_TEMPLATE> tag. In addition, the Bulk Enrollment interface adds the JavaScript variables listed in the following table:.
Display Key By Serial Number Interface
Description
URI: /kra/displayBySerial
Available on: Data Recovery Manager
Function: Displays information in human-readable form about a single archived key.
The Display Key By Serial Number interface is typically used within a form that lists keys to display detailed information about a selected key.
Default Forms
The Display Key By Serial Number interface is used in the queryKey.template file. Each key in the list of keys satisfying the query has a button the user can press to see the key in detail. This button submits data to the Display Key By Serial Number interface.
Request Parameters
The following table lists the parameters accepted by the Display Key By Serial Number interface.
Response
The default response template is displayBySerial.template (note that the template in the web/agents/kra directory differs significantly from the template for Certificate Managers, Registration Managers, or end entities; those forms are used to display certificates, not keys).
The base JavaScript for responses is inserted in place of the <CMS_TEMPLATE> tag. In addition, the Display Key By Serial Number interface adds the JavaScript variables listed in the following table:
Display Key For Recovery Interface
Description
URI: /kra/displayBySerialForRecovery
Available on: Data Recovery Manager
Function: Displays a form for recovering a key.
The Display Key For Recovery interface is typically used in the list returned by the Key Recovery Query Interface. The purpose of the interface is to retrieve information about a specific key (based on its DRM serial number) and present a form to collect the rest of the information required to start the recovery process. The response template, displayBySerialForRecovery.template, will render a form that uses the Recover Key By Serial Number Interface.
Default Forms
The Display Key For Recovery interface is used in the queryKeyForRecovery.template file. Each key in the list of keys satisfying the query has a button the user can press to start the recovery process. This button submits data to the Display Key For Recovery interface.
Request Parameters
The following table lists the parameters accepted by the Display Key For Recovery interface.
Response
The default response template is displayBySerialForRecovery.template. The base JavaScript for responses is inserted in place of the <CMS_TEMPLATE> tag. In addition, the Display Key For Recovery interface adds the JavaScript variables listed in the following table:
Examine Recovery Interface
Description
URI: /kra/examineRecovery
Available on: Data Recovery Manager
Function: Checks to see if a recovery request identification number is valid.
The Examine Recovery interface is an intermediate interface that validates a request identification number. The interface takes a request identification number and makes sure that it is associated with a valid recovery request on the CMS server. If the request number is not valid, an error is returned (using the GenError.template file). If the request number is valid, the interface returns a template that by default creates a form for posting a user ID and password to the Grant Recovery Interface.
Default Forms
The Examine Recovery interface is used by the grantRecovery.html form in the Data Recovery Manager web directory (web/agents/kra). The form accepts a recovery id and posts it to the Examine Recovery interface, which returns either a form for granting the recovery or an error message (if the request id is invalid).
Request Parameters
The following table lists the parameters accepted by the Examine Recovery interface.
Response
The GenError.template file is used to return any error messages. Successful requests use the examineRecovery.template file. Since the interface is used to validate a request id, the examineRecovery.template is used by default to create a form to submit a user ID and password to the Grant Recovery Interface to approve that request.
The base JavaScript for responses is inserted in place of the <CMS_TEMPLATE> tag. In addition, the Examine Recovery interface adds the JavaScript variables listed in the following table:
Get Approval Status Interface
Description
URI: /kra/getApprovalStatus
Available on: Data Recovery Manager
Function: Displays the status of a recovery operation.
The Get Approval Status interface accepts a recovery request number and returns the status of the request. The response includes the number of agents required to approve the recovery and the number that have already granted approval. While a request is pending, agents can use the Grant Recovery Interface to submit user IDs and passwords. The Examine Recovery Interface can be used as an intermediate step to make sure that there is a valid request corresponding to a request identification number (this is the default behavior of the Authorize Recovery link from the Data Recovery Manager gateway).
Default Forms
The Get Approval Status interface requires a valid request id number, so it is used by default only in the response template for the Recover Key By Serial Number Interface. The Recover Key By Serial Number Interface returns a request id number for pending (non-local) requests. In the default response, this request id number is used in a form that polls the Get Approval Status interface using a <META HTTP-EQUIV="Refresh"> tag to make continuous requests until the recovery is completed. The page looks at the result.recordSet array to see how many agents have approved the request so far.
Request Parameters
The following table lists the parameters accepted by the Get Approval Status interface.
Response
The default response template depends on the status of the request. While the request is pending, the getApprovalStatus.template file is used. Once the request is completed the finishRecovery.template file is used. By default, these templates are identical except for the <META HTTP-EQUIV="Refresh" CONTENT="5"> tag in getApprovalStatus.template, which causes the page to refresh itself every 5 seconds.
The base JavaScript for responses is inserted in place of the <CMS_TEMPLATE> tag. In addition, the Get Approval Status interface adds the JavaScript variables listed in the following table:
Get PKCS #12 Data Interface
Description
URI: /kra/getPk12
Available on: Data Recovery Manager
Function: Retrieves the PKCS #12 data containing a recovered key and certificate.
The Get PKCS #12 Data interface is used to retrieve the PKCS #12 blob containing a recovered key and its associated certificate. The PKCS #12 data is encrypted using the password supplied to the Recover Key By Serial Number Interface.
Default Forms
No default forms use the Get PKCS #12 Data interface. The finishRecovery.template, getApprovalStatus.template, and recoverBySerial.template files all embed links to the Get PKCS #12 Data interface that are displayed if the recovery has been granted (if result.header.status = "complete").
Request Parameters
The Get PKCS #12 Data interface requires only a recovery request ID. This parameter is set in the HTML form and passed to the interface using HTTP.
Response
If the recovery has been granted, the response is to return a PKCS #12 blob with the MIME type application/x-pkcs12. This blob is encrypted with a password (supplied when the recovery request was initiated) and contains the key and corresponding certificate.
If the recovery has not yet been granted, the default response template is finishRecovery.template. See the Response section for the Get Approval Status Interface for details on the JavaScript returned.
Grant Recovery Interface
Description
URI: /kra/grantRecovery
Available on: Data Recovery Manager
Function: Submits a password to approve a key recovery.
The Grant Recovery interface is used by agents to submit their passwords to authorize a key recovery. Key recovery requires a certain number of authorized agents submit passwords before the key can be recovered. Each agent uses the Grant Recovery interface to submit a password until the minimum number of passwords has been collected.
Default Forms
The Grant Recovery interface is used by the examineRecovery.template result template by default. This form is returned when a request ID has been verified as valid, so it ensures that the Grant Recovery interface will be called with a valid request id.
Request Parameters
The following table lists the parameters accepted by the Grant Recovery interface.
Response
The default response template is grantRecovery.template. The base JavaScript for responses is inserted in place of the <CMS_TEMPLATE> tag. In addition, the Grant Recovery interface adds the JavaScript variables listed in the following table:
Key Query Interface
Description
URI: /kra/queryKey
Available On: Data Recovery Manager only.
Function: Retrieves a set of archived keys based on a flexible query specification.
The Key Query interface allows you to build query criteria much like an LDAP query. Criteria can be combined using logical AND or OR for flexibility. You can match keys in the archive based on the DRM serial number, the DN of the key owner, the certificate containing the corresponding public key, or the agent that archived the key.
The interface returns the public keys corresponding to the archived keys that match the query criteria.
Default Forms
The Data Recovery Manager form searchKey.html uses the Key Query interface. The form allows the agent to specify any of the valid query parameters: serial number range, key owner DN, public key certificate, or user ID of the archiving agent.
Request Parameters
The following table lists the parameters accepted by the Key Query interface.
The queryFilter parameter must be a valid query filter. The syntax and valid query parameters are too complex to describe in the parameter table. Details about valid parameters and values for query filters are in a separate table following the parameters.Table 24.49 Parameters Accepted by the Key Query Interface
Parameter
| Format and Description
|
maxCount
| number Specifies the maximum number of keys to display on each page returned. If more than maxCount keys match the search criteria, each page will have controls to see the next or previous page of results.
|
op
| queryKey The only operation supported by the List Certificates interface is queryKey.
|
queryFilter
| ([<OP>]<FILTER>[<FILTER>...]) Details about building query filters are provided in the next table. The queryFilter must be enclosed in parentheses. The <OP> argument, required if there is more than one <FILTER>, specifies how the filters that follow should be logically evaluated: Any number of filters can be concatenated within any set of parentheses. An example filter is
(|(keyArchivedBy=drmagent1)(&(keySerialNumber>=5)(keySerialNumber
<=35)))
This filter matches any key that was archived by drmagent1 or keys with serial numbers between 5 and 35 in the archive.
|
querySentinel
| number The querySentinel indicates which record out of the total matching set should be the first displayed on the resulting output page. For example, if totalRecordCount = 15 and maxCount = 5, set querySentinel to 6 to show the 6th through 10th element of the matching set.
|
templateName
| string Filename relative to the template directory (web/ee, web/agent/ca, web/agent/kra, or web/agent/ra) of a file to use as the response template. This template will be used for any response, overriding default template settings.
|
totalRecordCount
| number The total number of keys in the archive that match the queryFilter. This number is returned by the interface in the initial response. This can be posted in subsequent calls to prevent the CMS server from calculating a number. In this way every page can tell the user the absolute size of the matching set, rather than have the size of the set appear to decrease on each next page of data.
|
The following table describes the parameter names that are valid for constructing query filters, and the range of valid values that can be used with the parameter. The parameters can be combined using parentheses and logical operators (as described in the previous table) to construct query filters of arbitrary complexity.
In a filter, the parameter name is compared to the expression value using one of the relational operators = (matches), < (less than), <= (less than or equal to), > (greater than), or >= (greater than or equal to). Some expressions (such as keySerialNumber) accept the asterisk (*) as a wildcard to match 0 or more characters; for example, "keyOwnerName=CN=*,*OU=Engineering*" matches "CN=jsmith, OU=Engineering, O=Organization1, C=US" and "CN=jdoe, OU=Engineering, O=Organization2, C=CA."
Response
The default response template is queryKey.template. The base JavaScript for responses is inserted in place of the <CMS_TEMPLATE> tag. In addition, the Key Query interface adds the JavaScript variables listed in the following table. Table 24.51 Variables Returned by the Key Query Interface
Variable
| Description
|
result.header variables
| Variables added to the header object.
|
archiverName
| Distinguished Name (DN) string. See RFC 2253. The subject name on the Data Recovery Manager's signing certificate.
|
op
| queryKey Indicates the operation that was requested.
|
queryFilter
| query string Contains the query string that was used to select keys from the archive. See the previous section, Request Parameters, for details on how queryFilter is constructed. The queryFilter should be reused to query for more keys when there are more records than displayed on the current page.
|
querySentinel
| number The number of the first record shown on this page of output. This is an index relative to the totalRecordCount. For example, if querySentinel = 6, totalRecordCount = 8, and maxCount = 5, then the 6th through 8th records that matched the query will be displayed.
|
templateName
| string Indicates the name of the template that was used to display the response. By default it is queryKey.template, but it can be changed with the templateName request parameter.
|
totalRecordCount
| number The total number of records that match the query criteria (queryFilter). This may be more than the number of records currently displayed, which is limited by fixed.maxCount.
|
result.fixed variable
| Variable added to the fixed object.
|
maxCount
| number The maximum number of records that can be displayed on a single page of output (taken from the request parameter maxCount).
|
result.recordSet[i] variables
| Variables added to record objects in the response.
|
archivedBy
| user ID The user ID of the agent that processed the key archival request.
|
archivedOn
| number of seconds since 1 January 1970 The time when the key was stored in the archive (for completed Data Recovery Manager requests).
|
keyAlgorithm
| OID string The object identifier (OID) used by the archived key corresponding to this request (Data Recovery Manager requests). For example, the OID for an RSA encryption key is "1.2.840.113549.1.1.1."
|
keyLength
| number The number of bits in the archived key (Data Recovery Manager requests).
|
ownerName
| Distinguished Name (DN) string. See RFC 2253. The subject entry on the certificate corresponding to an archived encryption key (Data Recovery Manager requests only). Example: CN=Alice Apple, UID=alice, OU=People, O=Example, C=US
|
publicKey
| string A string of two-digit hexadecimal numbers separated by colon. Each number represents a byte in the public key corresponding to the private key to be archived.
|
serialNumber
| number A unique identification number that identifies a key in the archive. This differs from the certificate serial number.
|
state
| VALID | INVALID The current status of the key corresponding to the request.
|
Key Recovery Query Interface
Description
URI: /kra/queryKeyForRecovery
Available On: Data Recovery Manager only.
Function: Retrieves a set of archived keys, for the purpose of recovering them, based on a flexible query specification.
The Key Recovery Query interface allows you to build query criteria much like an LDAP query. Criteria can be combined using logical AND or OR for flexibility. You can match keys in the archive based on the DRM serial number, the DN of the key owner, the certificate containing the corresponding public key, or the agent that archived the key.
The interface returns the public keys corresponding to the archived keys that match the query criteria. The list of keys in the response will each have a "Recover" button that allows the key to be recovered.
Default Forms
The Data Recovery Manager form recoverKey.html uses the Key Recovery Query interface. The form allows the agent to specify any of the valid query parameters: serial number range, key owner DN, public key certificate, or user ID of the archiving agent.
Request Parameters
The following table lists the parameters accepted by the Key Recovery Query interface.
The queryFilter parameter must be a valid query filter. The syntax and valid query parameters are too complex to describe in the parameter table. The parameter is identical to the queryFilter request parameter for the Key Query Interface; refer to that section for complete details on building queries.Table 24.52 Parameters Accepted by the Key Recovery Query Interface
Parameter
| Format and Description
|
maxCount
| number Specifies the maximum number of keys to display on each page returned. If more than maxCount keys match the search criteria, each page will have controls to see the next or previous page of results.
|
op
| queryKey The only operation supported by the List Certificates interface is queryKey.
|
publicKeyData
| base-64 encoded certificate The certificate containing the public key associated with a key to be matched in the archive. The publicKeyData should include the "-----BEGIN CERTIFICATE-----" header and "-----END CERTIFICATE-----" footer.
|
queryFilter
| ([<OP>]<FILTER>[<FILTER>...]) Details about building query filters are provided in the next table. The queryFilter must be enclosed in parentheses. The <OP> argument, required if there is more than one <FILTER>, specifies how the filters that follow should be logically evaluated: Any number of filters can be concatenated within any set of parentheses. An example filter is
(|(keyArchivedBy=drmagent1)(&(keySerialNumber>=5)(keySerialNumber
<=35)))
This filter matches any key that was archived by drmagent1 or keys with serial numbers between 5 and 35 in the archive.
|
querySentinel
| number The querySentinel indicates which record out of the total matching set should be the first displayed on the resulting output page. For example, if totalRecordCount = 15 and maxCount = 5, set querySentinel to 6 to show the 6th through 10th element of the matching set.
|
templateName
| string Filename relative to the template directory (web/ee, web/agent/ca, web/agent/kra, or web/agent/ra) of a file to use as the response template. This template will be used for any response, overriding default template settings.
|
totalRecordCount
| number The total number of keys in the archive that match the queryFilter. This number is returned by the interface in the initial response. This can be posted in subsequent calls to prevent the CMS server from calculating a number. In this way every page can tell the user the absolute size of the matching set, rather than have the size of the set appear to decrease on each next page of data.
|
Response
The default response template is queryKeyForRecovery.template. The base JavaScript for responses is inserted in place of the <CMS_TEMPLATE> tag. In addition, the Key Recovery Query interface adds the JavaScript variables listed in the following table. Table 24.53 Variables Returned by the Key Recovery Query Interface
Variable
| Description
|
result.header variables
| Variables added to the header object.
|
archiverName
| Distinguished Name (DN) string. See RFC 2253. The subject name on the Data Recovery Manager's signing certificate.
|
op
| queryKey Indicates the operation that was requested.
|
queryFilter
| query string Contains the query string that was used to select keys from the archive. See the previous section, Request Parameters, for details on how queryFilter is constructed. The queryFilter should be reused to query for more keys when there are more records than displayed on the current page.
|
querySentinel
| number The number of the first record shown on this page of output. This is an index relative to the totalRecordCount. For example, if querySentinel = 6, totalRecordCount = 8, and maxCount = 5, then the 6th through 8th records that matched the query will be displayed.
|
templateName
| string Indicates the name of the template that was used to display the response. By default it is queryKey.template, but it can be changed with the templateName request parameter.
|
totalRecordCount
| number The total number of records that match the query criteria (queryFilter). This may be more than the number of records currently displayed, which is limited by fixed.maxCount.
|
result.fixed variable
| Variable added to the fixed object.
|
maxCount
| number The maximum number of records that can be displayed on a single page of output (taken from the request parameter maxCount).
|
result.recordSet[i] variables
| Variables added to record objects in the response.
|
archivedBy
| user ID The user ID of the agent that processed the key archival request.
|
archivedOn
| number of seconds since 1 January 1970 The time when the key was stored in the archive (for completed Data Recovery Manager requests).
|
keyAlgorithm
| OID string The object identifier (OID) used by the archived key corresponding to this request (Data Recovery Manager requests). For example, the OID for an RSA encryption key is "1.2.840.113549.1.1.1."
|
keyLength
| number The number of bits in the archived key (Data Recovery Manager requests).
|
ownerName
| Distinguished Name (DN) string. See RFC 2253. The subject entry on the certificate corresponding to an archived encryption key (Data Recovery Manager requests only). Example: CN=Alice Apple, UID=alice, OU=People, O=Example, C=US
|
publicKey
| string A string of two-digit hexadecimal numbers separated by colon. Each number represents a byte in the public key corresponding to the private key to be archived.
|
serialNumber
| number A unique identification number that identifies a key in the archive. This differs from the certificate serial number.
|
state
| VALID | INVALID The current status of the key corresponding to the request.
|
Process Certificate Request Interface
Description
URI: /ca/processCertReq or /ra/processCertReq
Available on: Certificate Manager or Registration Manager
Function: Agents can use the Process Certificate Request interface to accept, reject, or cancel requests to sign, renew, or revoke requests.
The Process Request Interface is used to assign pending requests to agents. The Process Certificate Request interface is used by an agent to act on requests owned by the agent (or not yet owned).
The interface is called once the sequence number of a pending request is known, so forms that use the interface are usually embedded in a response template from an interface that can list pending requests (for example, the Requests Query Interface). The list of pending requests will also include the requestType variable to distinguish between signing, revocation, and renewal requests.
Default Forms
No default forms use the Process Certificate Request Interface directly. The listRequests.html form calls the Requests Query Interface which returns data using the processReq.template when pending requests are selected.
The processReq.template will create a link to the Process Certificate Request Interface for all requests with status == pending. Additional JavaScript in that template is used to add parameters to the request to the Process Certificate Request interface (such as the validity period for enrollments and renewals).
Request Parameters
The following table lists the parameters accepted by the Process Request Interface.
The agent interface requires SSL client authentication, so information about the agent can be gleaned from the certificate used to authenticate and does not need to be passed in parameters.Table 24.54 Parameters Accepted by the Process Certificate Request Interface
Parameter
| Format and Description
|
addExts
| base-64 encoded certificate extensions Specifies any additional certificate extensions that should be added. There is sample code in the cms_sdk/samples/exttools directory that can be used to generate the base-64 encoding of some extensions; the code can be modified to generate other extensions.
|
certTypeEmail
| yes | no Specifies whether to set the netscape certificate extension S/MIME client certificate bit (bit 2).
|
certTypeEmailCA
| yes | no Specifies whether to set the netscape certificate extension S/MIME certificate issuer bit (bit 6).
|
certTypeObjSigning
| yes | no Specifies whether to set the netscape certificate extension object signing certificate bit (bit 3).
|
certTypeObjSigningCA
| yes | no Specifies whether to set the netscape certificate extension object signing certificate issuer bit (bit 7).
|
certTypeSSLCA
| yes | no Specifies whether to set the netscape certificate extension SSL certificate issuer bit (bit 5).
|
certTypeSSLClient
| yes | no Specifies whether to set the netscape certificate extension SSL client authentication certificate bit (bit 0).
|
certTypeSSLServer
| yes | no Specifies whether to set the netscape certificate extension SSL server authentication certificate bit (bit 1).
|
checkPubKeyUniqueness
| yes | no Specifies whether the CMS server should ensure that the new certificate's public key is unique.
|
checkValidityNesting
| yes | no Specifies whether the CMS server should check to make sure that the certificate does not expire later than the CA's signing certificate.
|
csrRequestorEmail
| string The email address of the party making the original signing request.
|
csrRequestorName
| string The real name of the party making the original signing request.
|
csrRequestorPhone
| string The phone number of the party making the original signing request.
|
grantCMAgentPrivilege
| yes | no Specifies whether the new certificate will be trusted as a Certificate Manager agent.
|
grantDRMAgentPrivilege
| yes | no Specifies whether the new certificate will be trusted as a Data Recovery Manager agent.
|
grantRMAgentPrivilege
| yes | no Specifies whether the new certificate will be trusted as a Registration Manager agent.
|
grantTrustedManagerPrivilege
| yes | no Specifies whether the new certificate will be an SSL certificate used by a server that is trusted. For example, set this to yes when you issue the SSL server certificate for a new Registration Manager.
|
grantUID
| user ID The user ID that will be associated with the agent certificate.
|
seqNum
| number The sequence number of the request that is being acted upon. When requests are listed from the Requests Query Interface, their sequence numbers are returned from the CMS server in the result.header.seqNum field.
|
signatureAlgorithm
| MD5withRSA | SHA1withDSA | SHA1withRSA Specifies the signing algorithm that should be used to sign a newly issued certificate. The CA signing key must match the key type (RSA or DSA) of the selected algorithm.
|
subject
| Distinguished Name (DN) string. See RFC 2253. DN to be used for the certificate subject. Example: CN=Alice Apple, UID=alice, OU=People, O=Example, C=US
|
templateName
| string Filename relative to the template directory (web/ee, web/agent/ca, web/agent/kra, or web/agent/ra) of a file to use as the response template. This template will be used for any response, overriding default template settings.
|
toDo
| accept | cancel | clone | reject Specifies the action to take on the request.
|
validityLength
| number of seconds The length of time, in seconds, for which the newly issued certificate will be valid. The following list shows the approximate number of seconds in some common time intervals:
- 1 day: 86,400
- 7 days: 604,800
- 14 days: 1,209,600
- 30 days: 2,592,000
- 180 days: 15,552,000
- 365 days: 31,536,000
- 540 days: 46,665,000
- 730 days: 63,072,000
|
Response
The default response template is processCertReq.template. The base JavaScript for responses is inserted in place of the <CMS_TEMPLATE> tag. In addition, the Process Certificate Request interface adds the JavaScript variables listed in the following table. Table 24.55 Variables Returned by the Process Certificate Request Interface
Variable
| Description
|
result.header variables
| Variables added to the header object.
|
assignedTo
| The user ID of the agent to whom the request is currently assigned. Compare to callerName to see if the agent viewing the request is the current owner.
|
authorityid
| ca | ra The type of authority that handled the request: ca for Certificate Manager or ra for Registration Manager.
|
callerName
| The user ID of the agent who is viewing the request. This data is determined from the SSL client certificate presented to the agent interface.
|
certsUpdated
| number The number of certificates that were updated in the publishing directory if publishing is enabled (if result.header.dirEnabled = yes).
|
certType
| ca | CEP-Request | client | objSignClient | ra | server | other Specifies the type of certificate request that was acted upon. The certType is not associated with any certificate extensions. It may be used by policy modules to make decisions, and it may be used by a CMS server to determine how to decode the request or format the response.
|
clonedRequestId
| number The sequence number (or request ID) of the newly cloned request, if the action toDo = clone.
|
createdOn
| number of seconds since 1 January 1970 The time when the certificate request was created on the CMS server.
|
dirEnabled
| yes | no Indicates whether or not LDAP publishing is enabled on the CMS server. If yes, then certsUpdated will indicate how many certificates were updated in the directory as a result of the certificate processing action.
|
errorDetails
| message A more detailed description of any processing errors.
|
errors
| message A message explaining any errors that may have occurred.
|
ext_email
| true | false Indicates whether or not the Netscape certificate extension S/MIME bit (bit 2) is set in the certificate or request that was processed.
|
ext_email_ca
| true | false Indicates whether or not the Netscape certificate extension S/MIME CA bit (bit 6) is set in the certificate or request that was processed.
|
ext_object_signing
| true | false Indicates whether or not the Netscape certificate extension object signing bit (bit 3) is set in the certificate or request that was processed.
|
ext_object_signing_ca
| true | false Indicates whether or not the Netscape certificate extension object signing CA bit (bit 7) is set in the certificate or request that was processed.
|
ext_ssl_ca
| true | false Indicates whether or not the Netscape certificate extension SSL CA bit (bit 5) is set in the certificate or request that was processed.
|
ext_ssl_client
| true | false Indicates whether or not the Netscape certificate extension SSL client bit (bit 0) is set in the certificate or request that was processed.
|
ext_ssl_server
| true | false Indicates whether or not the Netscape certificate extension SSL server bit (bit 1) is set in the certificate or request that was processed.
|
grantError
| SUCCESS | error message If there were any errors processing a request for an agent certificate, this field will have an error message. If grantError = SUCCESS, the agent was created successfully.
|
grantPrivilege
| string Indicates the groups to which the new agent or certificate has been added. If there is more than one group, the group names will be separated by the text " and " in the string. Valid group names are:
|
grantUID
| user ID The user name assigned to the agent certificate that was processed.
|
localca
| yes | no Indicates whether the CMS server that processed the request is a Certificate Manager (the CMS server is not a Registration Manager).
|
localkra
| yes | no Indicates whether the CMS server that processed the request also hosts a Data Recovery Manager.
|
requestType
| enrollment | getCAChain | getCertificates | getRevocationInfo | renewal | revocation | unrevocation The requestType returns the type of request that was made to the interface returning this template.
|
serialNumber
| number The serial number of the certificate that was processed. This might be a newly issued certificate or a newly revoked certificate.
|
seqNum
| number The unique sequence number assigned to the request by the Certificate Manager or Registration Manager.
|
signatureAlgorithm
| OID The object identifier (OID) string corresponding to the algorithm used to sign a newly issued certificate. For example, "1.2.840.113549.1.1.4" is the OID for MD5 with RSA signing.
|
signatureAlgorithmName
| MD5withRSA | SHA1withDSA | SHA1withRSA The name token associated with the signature algorithm whose OID is stored in signatureAlgorithm.
|
status
| pending | complete Indicates whether the request is complete or if further action is required. Responses from the Process Certificate Request interface will return a status of complete unless an error occurred.
|
subject
| Distinguished Name (DN) string. See RFC 2RFC 2253. The DN appearing in the certificate subject field. Example DN: CN=Alice Apple, UID=alice, OU=People, O=Example, C=US
|
subjectPublicKey
| string of hexadecimal numbers The actual public key in the certificate that was processed. The string is a sequence of two-digit hexadecimal numbers separated by colons: "A1:3F:23:90:D7\n" Each pair of digits represents a byte or octet in the public key.
|
subjectPublicKeyInfo
| string A string indicating the public key algorithm and certificate signing algorithm. For example, "RSA - 1.2.840.113549.1.1.1" for a certificate with an RSA key signed using MD5 with RSA.
|
toDo
| accept | cancel | clone | reject Indicates the action that was taken to produce this response (that is, this is the same as the value of the toDo request parameter).
|
updatedBy
| user ID The user ID of the agent that updated the request. In the case of a response from the Process Certificate Request interface, this is the user ID of the agent that made the request.
|
updatedOn
| number of seconds since 1 January 1970 The time that the request was made to the Process Certificate Request interface.
|
validityLength
| number of seconds The length of time, in seconds, for which the newly issued certificate will be valid. The following list shows the approximate number of seconds in some common time intervals:
- 1 day: 86,400
- 7 days: 604,800
- 14 days: 1,209,600
- 30 days: 2,592,000
- 180 days: 15,552,000
- 365 days: 31,536,000
- 540 days: 46,665,000
- 730 days: 63,072,000
|
result.recordSet[i] variables
| Variables added to record objects in the response.
|
ext_prettyprint
| string A representation of any extensions present in the certificate in human-readable form.
|
serialNumber
| number The decimal serial number of the certificate.
|
Process DRM Request Interface
Description
URI: /kra/processReq
Available on: Data Recovery Manager
Function: This interface allows an agent to view a request or assign the request to himself.
The Process DRM Request interface is slightly different from the Process Request Interface used by Certificate Managers and Registration Managers.
Default Forms
The Process DRM Request interface is not used in any default forms. The interface requires the sequence number of an archival request, so it is used in templates that list requests (with their sequence numbers) to render buttons that allow an agent to view or change the assignment of a request.
Request Parameters
The following table lists the parameters accepted by the Process DRM Request interface.
The agent interface requires SSL client authentication, so information about the agent can be gleaned from the certificate used to authenticate and does not need to be passed in parameters.Table 24.56 Parameters Accepted by the Process DRM Request Interface
Parameter
| Format and Description
|
doAssign
| yes | no Specifies whether to assign the request to the agent using the interface. If this parameter is no, null, or not supplied, the request will be displayed, but not assigned to the agent.
|
moreComments
| string Specifies additional comments to be stored with the request. Comments may be useful for future reference or to provide data to another agent that needs to process the request.
|
op
| processReq The only operation supported is processReq.
|
overrideAssignment
| yes | no Specifies whether or not to override an existing assignment. If a request is already assigned to another agent, an agent must use doAssign = yes and overrideAssignment = yes to assume assignment of the request. If the request is not assigned, overrideAssignment is not required.
|
requestorEmail
| email address The email address of the entity requesting archival or recovery, if the information is available.
|
requestorName
| string The name of the entity requesting archival or recovery, if the information is available.
|
requestorPhone
| string The phone number of the entity requesting archival or recovery, if the information is available.
|
seqNum
| number The sequence number of a pending request to assign or redisplay.
|
templateName
| string Filename relative to the template directory (web/ee, web/agent/ca, web/agent/kra, or web/agent/ra) of a file to use as the response template. This template will be used for any response, overriding default template settings.
|
Response
The default response template is processReq.template. The base JavaScript for responses is inserted in place of the <CMS_TEMPLATE> tag. In addition, the Process DRM Request interface adds the JavaScript variables listed in the following table.
Process Request Interface
Description
URI: /ca/processReq or /ra/processReq
Available on: Certificate Manager or Registration Manager
Function: Changes the assignment of a pending certificate request to an agent.
This is an agent interface and requires SSL client authentication with a valid agent certificate. The Process Request Interface can be used to assign a certificate request (identified by a sequence number) to the agent user ID associated with the certificate presented for authentication or to assign the request to nobody (remove any existing assignment).
Default Forms
The Process Request Interface is not used in any default forms. The interface requires the sequence number of a certificate request, so it is used in templates that list pending requests (with their sequence numbers) to render buttons that allow an agent to change the assignment of a request.
Request Parameters
The following table lists the parameters accepted by the Process Request interface.
The agent interface requires SSL client authentication, so information about the agent can be gleaned from the certificate used for authentication and does not need to be passed in parameters.
Response
The default response template is processReq.template. The base JavaScript for responses is inserted in place of the <CMS_TEMPLATE> tag.
In addition, the Process Request interface adds the JavaScript variables listed in the following table. The table lists only the variables in the template related to the Process Request interface. The template includes more variables related to the status and origin of the request; these are documented in other interfaces that use the template.
Recover Key By Serial Number Interface
Description
URI: /kra/recoverBySerial
Available on: Data Recovery Manager
Function: Displays a form for recovering a key.
Once a key has been selected from the archive, the Recover Key By Serial Number Interface can be used to start the recovery operation. This interface accepts the serial number of an archived key and optionally the user ID and passwords of recovery agents.
The recovery operation can be completed by one call to the Recover Key By Serial Number Interface if the proper number of recovery agent user IDs and passwords are provided. In this case, a PKCS #12 blob is returned with the recovered key and an associated public key certificate.
The recovery operation can also be deferred if the agent passwords cannot be immediately provided. In this case, the response from the interface is a new form that polls the Get Approval Status Interface until the passwords are entered by agents (from other locations) and the PKCS #12 blob can be delivered.
Default Forms
The Recover Key By Serial Number Interface typically follows a request to the Display Key For Recovery Interface. The result of the Display Key For Recovery Interface request is to display a key from the archive using the displayBySerialForRecovery.template file. This template provides a form for making a request to the Recover Key By Serial Number Interface to initiate the recovery operation for the selected key.
Request Parameters
The following table lists the parameters accepted by the Recover Key By Serial Number interface. Table 24.60 Parameters Accepted by the Recover Key By Serial Number Interface
Parameter
| Format and Description
|
cert
| base-64 encoded PKCS #7 certificate You must supply the certificate containing the public key corresponding to the key in the archive. Be sure to include the "-----BEGIN CERTIFICATE-----" header and "-----END CERTIFICATE-----" footer.
|
localAgents
| yes | no Specifies whether agent user IDs and passwords have been entered locally (that is, submitted with this request), or will be entered remotely. If localAgents = no, agents will have to access the Examine Recovery interface with the request id and enter their passwords.
|
nickname
| string Specifies an optional nickname for the certificate that will be returned in the PKCS #12 blob when the key is recovered.
|
op
| recoverBySerial Specifies the operation to perform. The only valid value is recoverBySerial.
|
p12password
| string Specifies a password used to protect the recovered key. When the PKCS #12 blob containing the key is returned, this password will be required to decrypt the data.
|
p12passwordAgain
| string This parameter serves as a quality check; the string must match the value of p12password.
|
pwd<n>
| string Specifies the password for agent <n>, where <n> is replaced by a sequence number (beginning with 0). If this is a local recovery operation, user IDs (uid<n>) and passwords must be supplied for the number of agents required to authorize a recovery. For example, if two agents are required, a local recovery operation requires uid0, pwd0, uid1, and pwd1 parameters.
|
serialNumber
| number The serial number of the key to recover. Note that this is the DRM serial number, not the serial number from a certificate.
|
templateName
| string Filename relative to the template directory (web/ee, web/agent/ca, web/agent/kra, or web/agent/ra) of a file to use as the response template. This template will be used for any response, overriding default template settings.
|
uid<n>
| string Specifies the user ID for agent number <n>, if this is a local operation. See the description for pwd<n>.
|
Response
If the request was for a local recovery (localAgents = yes in the request), and the recovery is successful, the response will be the binary PKCS #12 blob containing the key and certificate. The MIME type of the response will be application/x-pkcs12.
If the request was not local or if there was an error, the default response template is recoverBySerial.template. The base JavaScript for responses is inserted in place of the <CMS_TEMPLATE> tag. If there are no errors, the default template includes JavaScript code that uses window.location to immediately replace the returned page with a call to the Get Approval Status Interface.
In addition, the Recover Key By Serial Number interface adds the JavaScript variables listed in the following table:
Remove Certificate Hold Interface
Description
URI: /ca/doUnrevoke or /ra/doUnrevoke
Available on: Certificate Manager or Registration Manager agent ports.
Function: Changes the status of a certificate that has been put on hold so that it is no longer considered revoked.
A certificate can be temporarily rendered invalid --or "put on hold"-- by revoking it with a revocation reason code of 6. If subsequent analysis reveals that the certificate does not need to be permanently revoked, it can be made valid again using the Remove Certificate Hold Interface.
Only agents with valid SSL client certificates can use the Remove Certificate Hold interface.
Default Forms
There are no default forms that use this interface. The Remove Certificate Hold Interface is usually accessed after a list of certificates currently on hold has been generated. In the response template that displays the list, certificates on hold can be rendered with a "Remove Certificate Hold" button next to their listing. The displayByCert.template and queryCert.template create buttons that use the Remove Certificate Hold Interface.
Request Parameters
The following table lists the parameters accepted by the Remove Certificate Hold interface.
Response
The default response template is unrevocationResult.template. The base JavaScript for responses is inserted in place of the <CMS_TEMPLATE> tag. In addition, the Remove Certificate Hold Interface adds the JavaScript variables listed in the following table:
Requests Query Interface
Description
URI: /ca/queryReq or /ra/queryReq or /kra/queryReq
Available on: Certificate Manager, Registration Manager, or Data Recovery Manager
Function: Lists requests that have been made to a given server.
The interface can return all requests, or subsets based on request status (pending, complete, etc.) and request type (enrollment, renewal, etc.).
Default Forms
The listRequests.html form uses the Requests Query Interface. This form can be found in the Certificate Manager, Registration Manager, and Data Recovery Manager web directories. The listRequests.html form presents menus for choosing the request type and status as well as a field for setting the lowest request id to return.
Since the number or records returned by the interface may be more than the user wants to see on one page, the response template (queryReq.template) may have a button to retrieve more records that also uses the Requests Query Interface.
Request Parameters
The following table lists the parameters that are used to view requests through the Requests Query Interface. This is an agent interface, so the HTTP POST or GET request must use SSL client authentication with a valid agent certificate. Table 24.64 Parameters Accepted by the Requests Query Interface
Parameter
| Format and Description
|
maxCount
| number Specifies the maximum number of requests to display on a page. If more than maxCount requests match the criteria, the response template can include code to request more records from the Requests Query interface.
|
op
| queryReq Specifies the operation to perform. For the Requests Query interface, this should be queryReq.
|
reqState
| showAll | showCancelled | showCompleted | showInService | showRejected | showWaiting Specifies the status of requests to show.
|
reqType
| archival | enrollment | getCAChain | getCertificates | getCRL | getRevocationInfo | recovery | renewal | revocation | showAll | unrevocation Specifies the type of request to show.
|
seqNumFrom
| number Specifies the lowest request identification number to retrieve. This parameter is useful when the number of requests is more than maxCount and another page of data can be requested: set seqNumFrom to one more than the last request displayed on the current page and repost the request.
|
templateName
| string Filename relative to the template directory (web/ee, web/agent/ca, web/agent/kra, or web/agent/ra) of a file to use as the response template. This template will be used for any response, overriding default template settings.
|
totalRecordCount
| number The total number of requests that match the criteria. This is, of course, not known until at least one page of requests have been retrieved. Requests to see more data can pass this number along so that the total number of matching requests can be displayed on every page (otherwise the total would decrease as subsequent requests used higher values for seqNumFrom). If this parameter is not passed, the total will be calculated on the CMS server, and the response table will include the total in the result.header.totalRecordCount variable.
|
Response
The default response template is queryReq.template. The base JavaScript for responses is inserted in place of the <CMS_TEMPLATE> tag.
For each request returned, a record object is created. Some of the record object fields listed below may not apply to some requests; for example, a pending or rejected enrollment request will have no certificate subject.
The Requests Query interface adds the JavaScript variables listed in the following table.Table 24.65 Variables Returned by the Requests Query Interface
Variable
| Description
|
result.header variables
| Variables added to the header object.
|
authorityId
| ca | kra | ra The type of server that generated the list of requests: ca for Certificate Manager, kra for Data Recovery Manager, or ra for Registration Manager.
|
currentRecordCount
| number The number of request records displayed on the current page of output.
|
error
| message If there was an error while processing the revocation request, the error message is stored in this variable. Otherwise, the value is null.
|
querySentinel
| number A tracking number that indicates the default number of records to retrieve on the next page of output. This number is the lesser of the maxCount requested and the total number of records left in the result set.
|
requestingUser
| user ID The user ID of the agent that requested the list of requests.
|
totalRecordCount
| number The total number of request records that matched the criteria.
|
result.fixed variables
| Variables added to the fixed object.
|
maxCount
| number The maximum number of records to display on a page. This is taken from the maxCount request parameter.
|
reqState
| showAll | showCancelled | showCompleted | showInService | showRejected | showWaiting Indicates the request state parameter that was used to generate the list.
|
reqType
| archival | enrollment | getCAChain | getCertificates | getCRL | getRevocationInfo | recovery | renewal | revocation | showAll | unrevocation Indicates the request type parameter that was used to generate the response.
|
seqNumFrom
| number The lowest request id number displayed in the current list of requests. This value is taken from the seqNumFrom request parameter.
|
result.recordSet[i] variables
| Variables added to record objects in the response.
|
archivedBy
| user ID The user ID of the agent that processed the key archival request.
|
archivedOn
| number of seconds since 1 January 1970 The time when the key was stored in the archive (for completed Data Recovery Manager requests).
|
assignedTo
| user ID The user ID of the agent currently assigned to the request. If no agent is assigned, assignedTo will be null.
|
callerName
| user ID The user ID of the agent that requested this list of requests.
|
certType
| ca | CEP-Request | client | objSignClient | ra | server | other Indicates the type of certificate.
|
createdOn
| seconds since 1 January 1970 Indicates the time when the request was created.
|
keyAlgorithm
| OID string The object identifier (OID) used by the archived key corresponding to this request (Data Recovery Manager requests). For example, the OID for an RSA encryption key is "1.2.840.113549.1.1.1."
|
keyLength
| number The number of bits in the archived key (Data Recovery Manager requests).
|
ownerName
| Distinguished Name (DN) string. See RFC 2253. The subject entry on the certificate corresponding to an archived encryption key (Data Recovery Manager requests only). Example: CN=Alice Apple, UID=alice, OU=People, O=Example, C=US
|
requestType
| enrollment | getCAChain | getCertificates | getRevocationInfo | renewal | revocation | unrevocation Indicates the type of request for this record.
|
serialNumber
| number The unique identification number for the request on a Data Recovery Manager. Registration Managers and Certificate Managers use seqNum.
|
seqNum
| number The request identification number for this request. The request ID is unique on any instance of a server. The seqNum is used for Registration Manager and Certificate Manager Requests. Data Recovery Manager requests are indexed by the serialNumber field.
|
state
| VALID | INVALID For Data Recovery Manager requests, the current state of the archived key.
|
status
| cancelled | complete | rejected | waiting The current status of the request.
|
subject
| Distinguished Name (DN) string. See RFC 2253. The subject entry on the certificate corresponding to this request (if there is one).
|
updatedBy
| user ID The user ID of the agent who last updated this request.
|
updatedOn
| seconds since 1 January 1970 The time when this request was last updated.
|
Select for Revocation Interface
Description
URI: /ca/reasonToRevoke or /ra/reasonToRevoke
Available on: Certificate Manager or Registration Manager
Function: Displays a set of certificates matching a query filter to be revoked.
The Select for Revocation Interface uses a query filter to select certificates. The response template lists these certificates in a form that allows them to be revoked using the Approve Revocation Interface.
Default Forms
By default forms that use the Select for Revocation Interface are embedded as buttons on certificate lists returned from the List Certificates Interface accessed through an agent port (/ca/listCerts or /ra/listCerts). These response are rendered using the queryCert.template discussed in the List Certificates Interface section.
Request Parameters
The following table lists the parameters that are used to select certificates through the Select for Revocation Interface. This is an agent interface, so the HTTP POST or GET request must use SSL client authentication with a valid agent certificate.
Response
The default response template is reasonToRevoke.template. The base JavaScript for responses is inserted in place of the <CMS_TEMPLATE> tag. In addition, the Select for Revocation interface adds the JavaScript variables listed in the following table. Table 24.67 Variables Returned by the Select For Revocation Interface
Variable
| Description
|
result.header variables
| Variables added to the header object.
|
caSerialNumber
| number The decimal serial number of the Certificate Authority's signing certificate.
|
revokeAll
| QUERY_FILTER The query filter that was used in the request to select the certificates that appear in this response. An example value for revokeAll to revoke certificates with serial numbers 10 and 14 is:
(|(certRecordId=10)(certRecordId=14))
|
totalRecordCount
| number The value of totalRecordCount specified in the request.
|
verifiedRecordCount
| number The number of revocable certificate that were actually selected based on the query criteria.
|
result.recordSet[i] variables
| Variables added to record objects in the response.
|
error
| message If a particular certificate could not be revoked, the error field in its record object will contain an error message. If this field is null, the certificate was revoked successfully.
|
serialNumber
| number The decimal serial number of the certificate.
|
subject
| string The subject distinguished name of the certificate. For example, "CN=Jane Doe, UID=jdoe, OU=Users, O=Organization, ST=California, C=US."
|
validNotAfter
| number of seconds since 1 January, 1970 The date when the certificate expires. See the description for issuedOn for details on date values.
|
validNotBefore
| number of seconds since 1 January, 1970 The date when the certificate became valid. See the description for issuedOn for details on date values.
|
Update CRL Interface
Description
URI: /ca/updateCRL or /ra/updateCRL
Available on: Certificate Manager and Registration Manager agent ports.
Function: Certificate Revocation Lists (CRLs) are automatically updated on a regular basis. If necessary, this interface can be used to force an update to the CRL.
Default Forms
The form updateCRL.html, available in the CA agent and RA agent directories, uses the Update CRL Interface. The form allows the user to select a signing algorithm for the CRL.
Request Parameters
The following table lists the parameters accepted by the Update CRL interface.
Response
The default response template is updateCRL.template. The base JavaScript for responses is inserted in place of the <CMS_TEMPLATE> tag. This simple template uses the crlPublished variable to display either a success or failure message.
In addition, the Update CRL interface adds the JavaScript variables listed in the following table:
Update Directory Interface
Description
URI: /ca/updateDir or /ra/updateDir
Available on: Certificate Manager and Registration Manager.
Function: If enabled, the publishing directory is automatically updated on a regular basis. If necessary, this interface can be used to force new information to be published to the directory.
The interface allows all new information or just selected subsets (for example, only updated expired certificate information) to be published.
Default Forms
The form updateDir.html, available in the CA agent and RA agent directories, uses the Update Directory Interface.
Request Parameters
The following table lists the parameters accepted by the Update Directory interface. Table 24.70 Parameters Accepted by the Update Directory Interface
Parameter
| Format and Description
|
expiredFrom
| number The low end of the range of serial numbers of expired certificates to be updated in the directory. For no lower bound, set this to null or omit the parameter.
|
expiredTo
| number The high end of the range of serial numbers of expired certificates to be updated in the directory. For no upper bound, set this to null or omit the parameter.
|
revokedFrom
| number The low end of the range of serial numbers of revoked certificates to be updated in the directory. For no lower bound, set this to null or omit the parameter.
|
revokedTo
| number The high end of the range of serial numbers of revoked certificates to be updated in the directory. For no upper bound, set this to null or omit the parameter.
|
templateName
| string Filename relative to the template directory (web/ee, web/agent/ca, web/agent/kra, or web/agent/ra) of a file to use as the response template. This template will be used for any response, overriding default template settings.
|
updateAll
| yes | no Whether to update all information in the directory ("yes") or only to update selected categories ("no"). If "no," be sure to set one of updateCA, updateCRL, updateExpired, updateRevoked, or updateValid to "yes."
|
updateCA
| yes | no Whether or not to update the Certificate Manager's signing certificate in the directory.
|
updateCRL
| yes | no Whether or not to update the certificate revocation list (CRL) in the directory. Any new updates since the last automatic or manual update will be published.
|
updateExpired
| yes | no Whether or not to remove certificates from the directory that have expired since the last update. If you want to restrict the range of certificates (by serial number), specify values for expiredFrom, expiredTo, or both.
|
updateRevoked
| yes | no Whether or not to remove certificates from the directory that have been revoked since the last update. If you want to restrict the range of certificates (by serial number), specify values for revokedFrom, revokedTo, or both.
|
updateValid
| yes | no Whether or not to publish certificates that have been issued (or otherwise become valid) since the last update to the directory. If you want to restrict the range of certificates (by serial number), specify values for validFrom, validTo, or both.
|
validFrom
| number The low end of the range of serial numbers of valid certificates to be updated in the directory. For no lower bound, set this to null or omit the parameter.
|
validTo
| number The high end of the range of serial numbers of valid certificates to be updated in the directory. For no upper bound, set this to null or omit the parameter.
|
Response
The default response template is updateDir.template. The base JavaScript for responses is inserted in place of the <CMS_TEMPLATE> tag. In addition, the Update Directory interface adds the JavaScript variables listed in the following table.
A variable will not be added (it will have a null value) if it does not apply; for example, if updating the CRL was not requested, the crlPublished variable will not be present (crlPublished == null will evaluate to true).Table 24.71 Variables Returned by the Update Directory Interface
Variable
| Description
|
result.header variables
| Variables added to the header object.
|
caCertError
| string A message explaining why the CA certificate could not be published to the directory, if there was an error.
|
caCertPublished
| Success | Failure If updating the CA certificate was requested, this variable will indicate whether the update was successful or not. See caCertError for an error message in case of Failure.
|
crlError
| string A message explaining why the CRL could not be published to the directory, if there was an error.
|
crlPublished
| Success | Failure If updating the CRL was requested, this variable will indicate whether the update was successful or not. See crlError for an error message in case of Failure.
|
expiredCertsError
| string A message explaining why the expired certificates could not be removed from the directory, if there was an error.
|
expiredCertsUnpublished
| Success | Failure If removing expired certificates was requested, this variable will indicate whether the update was successful or not. See expiredCertsError for an error message in case of Failure.
|
revokedCertsError
| string A message explaining why the revoked certificates could not be removed from the directory, if there was an error.
|
revokedCertsUnpublished
| Success | Failure If removing revoked certificates was requested, this variable will indicate whether the update was successful or not. See revokedCertsError for an error message in case of Failure.
|
validCertsError
| A message explaining why new certificates could not be published to the directory, if there was an error.
|
validCertsPublished
| Success | Failure If publishing new certificates was requested, this variable will indicate whether the update was successful or not. See validCertsError for an error message in case of Failure.
|
|