Chapter 6   Agent Interface Reference


This chapter provides a detailed reference of all the service interfaces available on an agent port of iPlanet Certificate Management Server. For each interface, there is a description including the URI used, the purpose, and which agents can use it, a list of forms that use the interface by default, a detailed description of valid input parameters and their values, and information about the response which lists the templates used and the additional JavaScript variables available.

The chapter has the following sections:

• Overview of Agent Interfaces

• Approve Revocation Interface

• Bulk Enrollment Interface

• Display Key By Serial Number Interface

• Display Key For Recovery Interface

• Examine Recovery Interface

• Get Approval Status Interface

• Get PKCS #12 Data Interface

• Grant Recovery Interface

• Key Query Interface

• Key Recovery Query Interface

• Process Certificate Request Interface

• Process DRM Request Interface

• Process Request Interface

• Recover Key By Serial Number Interface

• Remove Certificate Hold Interface

• Requests Query Interface

• Select for Revocation Interface

• Update CRL Interface

• Update Directory Interface

Overview of Agent Interfaces

---

The following table lists the agent interfaces and their functions:

Table 6-1    Agent Interfaces  

Interface	URI	Purpose
Approve Revocation Interface	/ca/doRevoke /ra/doRevoke	Use the id assigned to a pending request to retrieve the certificate once it has been issued.
Bulk Enrollment Interface	/ca/bulkissuance	Allows a process to programatically connect to the interface using SSL client authentication (with a CMS agent certificate) to submit a request and receive a certificate in response.
Display Key By Serial Number Interface	/kra/displayBySerial	Display information about an archived key.
Display Key For Recovery Interface	/kra/displayBySerialForRecovery	Display a form for recovering a key.
Examine Recovery Interface	/kra/examineRecovery	Check to see if a recovery request id is valid.
Get Approval Status Interface	/kra/getApprovalStatus	Display the status of a key recovery operation.
Get PKCS #12 Data Interface	/kra/getPk12	Retrieve the PKCS #12 data containing a recovered key.
Grant Recovery Interface	/kra/grantRecovery	Submit an agent password to approve a key recovery.
Key Query Interface	/kra/queryKey	View archived keys that meet query criteria.
Key Recovery Query Interface	/kra/queryKeyForRecovery	Display archived keys that meet query criteria and get links to initiate recovery of these keys.
Process Certificate Request Interface	/ca/processCertReq /ra/processCertReq	Allows agents to accept or reject requests for enrollment, renewal, or revocation.
Process DRM Request Interface	/kra/processReq	Allows key recovery agents to view requests and change request assignments.
Process Request Interface	/ca/processReq /ra/processReq	Allows agents to view pending requests and assign them to themselves.
Recover Key By Serial Number Interface	/kra/recoverBySerial	Given an archive serial number, display a form for recovering the archived key.
Remove Certificate Hold Interface	/ca/doUnrevoke /ra/doUnrevoke	Remove the "on hold" revocation status of a certificate.
Requests Query Interface	/ca/queryReq /ra/queryReq /kra/queryReq	View requests that match certain criteria (such as request type or status).
Select for Revocation Interface	/ca/reasonToRevoke /ra/reasonToRevoke	Revoke a set of certificates for a given reason.
Update CRL Interface	/ca/updateCRL /ra/updateCRL	Force the Certificate Revocation List (CRL) to be updated before the scheduled update.
Update Directory Interface	/ca/updateDir /ra/updateDir	Force the publishing directory to be updated before the next scheduled update.

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.

Table 6-2    Parameters Accepted by the Approve Revocation Interface  

Parameter	Format and Description
b64eCertificate	base-64 encoded certificate data Allows you to specify the certificate to revoke by posting its base-64 encoding to the interface.
csrRequestorComments	string A comment field to provide more details about why the certificates are being revoked.
invalidityDate	number of seconds since 1 January 1970 The time when the certificates became invalid.
op	doRevoke The only operation supported is doRevoke.
requestId	number Specifies the enrollment request id corresponding to the certificate to revoke. This allows you to post revocations to a Registration Authority.
revocationReason	0 - 6 The code for the reason the certificates are being revoked. The revocation codes are: 0 - Reason not specified 1 - Key compromised 2 - CA key compromised 3 - Affiliation changes 4 - Certificate superseded 5 - Cessation of operation 6 - Certificate is on hold
revokeAll	QUERY_FILTER For information on constructing a query filter, see Table 3-17 in the section for List Certificates Interface. To ensure accuracy when revoking certificates, you should use a query filter that selects each certificate by its serial number. An example value for revokeAll to revoke certificates with serial numbers 10 and 14 is: (|(certRecordId=10)(certRecordId=14))
serialNumber	number Specifies the serial number of a certificate to revoke.
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.
templateType	string The name of the template to use for the response. The reasonToRevoke.template file sets this to RevocationSuccess.
totalRecordCount	number The total number of certificates selected by the revokeAll filter. This number can be determined from the response variables in a template used to select certificates for revocation.
verifiedRecordCount	number Not presently used by the interface.

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.

Table 6-3    Variables Returned by the Approve Revocation Interface  

Variable	Description
result.header variables	Variables added to the header object.
certsUpdated	number Contains the number of certificates that were revoked from the publishing directory, if publishing is enabled (dirEnabled = yes).
dirEnabled	yes | no Indicates whether LDAP publishing is enabled on the Certificate Manager that handled the request.
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.
revoked	yes | pending Indicates whether or not all certificates were successfully revoked.
totalRecordCount	number Indicates the total number of revocation requests that were processed as a result of the request.
updateCRL	yes | no Indicates whether or not the CMS server attempted to update the Certificate Revocation List (CRL). If no or null, the CRL will be updated at the next scheduled update interval. If yes, check udpateCRLSuccess to determine if the update was successful.
updateCRLError	message If the CMS server attempted to update the CRL and encountered an error, this variable contains the text of the error message.
updateCRLSuccess	yes | no If the CMS server attempted to update the CRL, this variable will indicate whether the update was successful.
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.

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>/cert-<instance_id>/web/agent directory.

Table 6-4    Bulk Enrollment Interface Configuration File Parameters  

Parameter	Format and Description
agentGateway. enableBulkInterface	true | false Enables or disables the servlet handling bulk enrollment at /ca/bulkissuance.
errorTemplate	filename The template file to use when the response requestStatus = 6, meaning an error occurred while processing the request.
pendingTemplate	filename The template file to use when the response requestStatus = 3, meaning the request has been deferred for manual approval.
rejectedTemplate	filename The template file to use when the response requestStatus = 5, meaning the request was rejected by a policy on the CMS server.
successTemplate	filename The template file to use when the response requestStatus = 2, meaning the certificate has been issued.
svcpendingTemplate	filename The template file to use when the response requestStatus = 4, meaning the request is pending a response from a Data Recovery Manager.
unauthorizedTemplate	filename The template file to use when the response requestStatus = 1, meaning the SSL client authentication certificate presented to authenticate the request is not a valid agent certificate.
unexpectedErrorTemplate	filename The template file to use when the response requestStatus = 7, meaning an unexpected error prevented the CMS server from processing the response.

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 6-5    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: clientAuth - information for the new request is taken from the certificate presented by the client during SSL client authentication. crmf - the certificate request is a base-64 encoded blob contained in the CRMFRequest parameter. keygen - the certificate request is a base-64 encoded blob generated using the HTML <KEYGEN> tag. It is contained in the subjectKeyGenInfo parameter. pkcs10 - the certificate request is a base-64 encoded blob contained in the pkcs10Request parameter.
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.

Table 6-6    Variables Returned by the Bulk Enrollment Interface  

Variable	Description
result.fixed variables	Variables added to the fixed object.
authorityName	Certificate Manager | Registration Manager The name of the system that handled the request.
certType	ca | CEP-Request |client | objSignClient |ra | server | other The type of certificate returned. This value is the same as the certType value passed to the interface in the request.
errorDescription	string A message providing more details about the error described in errorDetails. This variable is only present if an error occurred while processing the request.
errorDetails	string A message explaining the error that occurred while processing the enrollment request. This variable is only present if an error occurred while processing the request.
host	string The fully qualified domain name of the CMS server that processed the request. This allows the resulting template to construct forms that post data to the same interface using the same port.
port	number The port number that was used to service the request.
requestId	number A unique number assigned by the CMS server to this request. This is especially useful for pending requests since there is no unique certificate serial number yet assigned.
requestStatus	number A code indicating the current status of the request: 1 (Unauthorized): The request specified a value for an authenticator to perform an automated enrollment, and the authenticator did not authorize the request. 2 (Success): Processing the request was successful and a certificate has been issued. If importCert was set to true, the response will include code (from the EnrollSuccess.template) to import the certificate into the browser making the request. Otherwise, the response is only a success message. 3 (Pending): The request has been successfully processed by the CMS server and added to a queue for approval by an agent. If the request has been submitted to another Certificate Manager or Data Recovery Manager and is currently pending in the queue for that service, the response template will be GenSvcPending.template instead of GenPending.template. 4 (Reserved): Not currently used. 5 (Rejected): The request was rejected during policy processing. 6 (Error): An error occurred when the CMS server processed the request. The error may be the result of missing or improperly formatted parameters. 7 (Exception): An unknown or unexpected error occurred when the CMS server processed the request.
scheme	http | https The protocol that was used to make the request. Use this along with host and port to make sure any new requests to the end-entity port use the correct scheme.
unexpectedError	string A message explaining the exception or unexpected error that occurred.
result.recordSet[i] variables	Variables added to each record object. Each record object is added as an element of the recordSet array. Multiple records may be returned if more than one certificate was generated as a result of the request. Dual-key requests (for example, if the request parameter requestFormat = crmf) may return two certificates if the request is successfully processed and approved.
base64Cert	string The newly issued certificate in base-64 encoded format. This string includes the "-----BEGIN CERTIFICATE-----" header and "-----END CERTIFICATE-----" footer.
certFingerprint	string A string of hexadecimal numbers separated by colons that represent the certificate fingerprints. There are three substrings: one each for the MD2, MD5, and SHA1 fingerprint. Each fingerprint begins with the hash algorithm name and a colon, and ends with a newline (\n).
certPrettyPrint	string A long text string that shows all of the certificate data in a human readable form.
policyMessage	string If the request was rejected by policy processing on the CMS server, this variable will contain a message explaining why.
serialNo	number The serial number (in decimal) of the newly issued certificate.

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.

Table 6-7    Parameters Accepted by the Display Key By Serial Number Interface  

Parameter	Format and Description
op	displayBySerial Specifies the operation to perform. The only valid value is displayBySerial.
serialNumber	number The serial number of the key to display. 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.

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:

Table 6-8    Variables Returned by the Display Key By Serial Number Interface  

Variable	Description
result.header variables	Variables added to the header object.
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).
op	displayBySerial Indicates the operation that was requested.
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 in the archive.
serviceURL	string Indicates the URI that was used to request this form. By default, this will always be "/kra/displayBySerial".
state	VALID | INVALID The current status of the key corresponding to the request.

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.

Table 6-9    Parameters Accepted by the Display Key For Recovery Interface  

Parameter	Format and Description
op	displayBySerial Specifies the operation to perform. The only valid value is displayBySerial.
publicKeyData	base-64 encoded certificate data This optional parameter allows you to pass the certificate corresponding to the key to revoke to the interface. The certificate will be required to recover the key, and passing it here allows the certificate to be automatically filled in on the resulting form.
serialNumber	number The serial number of the key to display. 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.

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:

Table 6-10    Variables Returned by the Display Key For Recovery Interface  

Variable	Description
result.header variables	Variables added to the header object.
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.
noOfRequiredAgents	number Indicates the number of authorized agents who must approve the request before the key can be recovered.
op	displayBySerial Indicates the operation that was requested.
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.
recoveryID	number A unique identification number assigned to each recovery request when it gets created.
serviceURL	string Indicates the URI that was used to request this form. By default, this will always be "/kra/displayBySerial".
state	VALID | INVALID The current status of the key corresponding to the request.

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.

Table 6-11    Parameters Accepted by the Examine Recovery Interface  

Parameter	Format and Description
op	examineRecovery The only operation supported by the Examine Recovery interface is examineRecovery.
recoveryID	number The unique identification number assigned to the recovery 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.

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:

Table 6-12    Variables Returned by the Examine Recovery Interface  

Variable	Description
result.header variables	Variables added to the header object.
op	examineRecovery Indicates the operation requested. Only examineRecovery is supported.
recoveryID	number The unique request identification number that was passed to the interface in the request. Since the examineRecovery.template has been returned, the recoveryID has been verified to correspond to a valid request.
serialNumber	number The serial number of the key in the archive.
serviceURL	/kra/examineRecovery The URL that was used to access the Examine Recovery interface.

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.

Table 6-13    Parameters Accepted by the Get Approval Status Interface  

Parameter	Format and Description
recoveryID	number The unique identification number assigned to the recovery 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.

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:

Table 6-14    Variables Returned by the Get Approval Status Interface  

Variable	Description
result.header variables	Variables added to the header object.
errorDetails	string If an error occurred while processing the request, this variable contains an error message.
noOfRequiredAgents	number The number of agents required to supply passwords before the key can be recovered. Compare to result.recordSet.length, which indicates how many agents have supplied valid passwords so far.
recoveryID	number The unique number assigned to this recovery request.
serialNumber	number The serial number of the key in the archive.
status	complete | null Once the required number of agents have supplied valid passwords, the status becomes complete and the finishRecovery.template is used for the response. Until the status is complete, result.header.status is not included in the response.
result.recordSet[i] variables	Variables added to record objects in the response.
agentName	string The user ID of an agent that has supplied a valid password to approve the recovery.

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.

Table 6-15    Parameters Accepted by the Get PKCS #12 Data Interface  

Parameter	Format and Description
recoveryID	number The unique identification number assigned to the recovery 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.

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.

Table 6-16    Parameters Accepted by the Grant Recovery Interface  

Parameter	Format and Description
agentID	string The key recovery agent id used by the agent making the request. Agent ids for key recovery are configured independently of agent user IDs, and so may be different.
agentPWD	string The password corresponding to the key recovery agent user ID submitted with agentID.
op	grantRecovery The only operation supported by the Grant Recovery interface is grantRecovery.
recoveryID	number The unique identification number assigned to the recovery 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.

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:

Table 6-17    Variables Returned by the Grant Recovery Interface  

Variable	Description
result.header variables	Variables added to the header object.
agentID	string The key recovery agent id whose password was submitted.
op	grantRecovery Indicates the operation requested. Only grantRecovery is supported.
recoveryID	number The unique request identification number that was passed to the interface in the request.
serialNumber	number The serial number of the key in the archive.
serviceURL	/kra/grantRecovery The URL that was used to access the Grant Recovery interface.

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 6-18    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: & (ampersand) means that the filters should be linked by a logical AND: all filters must evaluate to true for the expression to match a key. | (pipe) means that the filters should be linked by a logical OR: if at least one filter evaluates to true, the expression matches a key. 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."

Table 6-19    Key Query queryFilter Parameters  

Parameter	Expression Values
keyArchivedBy	Value: user ID of an agent This matches the user ID of the agent that approved archival. For example: (keyArchivedBy=drmagent1)
keySerialNumber	Value: serial number of a key This matches the serial number assigned by the Data Recovery Manager to a key when it is archived. Note that this differs from the serial number of the certificate corresponding to the key. Use the asterisk (*) wildcard to match any or partial serial numbers. For example: (&(keySerialNumber>=1)(keySerialNumber<=10))
keyOwnerName	Value: distinguished name appearing as the subject of the certificate corresponding to the key. This parameter matches the DN (taken from the certificate) stored with the key during archival. Use the wildcard (*) to match parts of a DN. If users are asked to enter a DN and it is likely that they will not remember all of the data, use the wildcard to allow partial matches. For example: <INPUT TYPE=TEXT NAME=partialDN> form.queryFilter.value = "(keyOwnerName=*" + partialDN + "*)";
publicKey	Value: x509cert#<base-64 encoded certificate> The query will find the archived key corresponding to the public key in the certificate. See searchKey.html for an example. The certificate in the proper format can be retrieved from a Certificate Manager using an interface such as the Display Certificate By Serial Number Interface. For example: (publicKey=x509cert#"-----BEGIN CERTIFICATE-----\nMII\"BFK364J978nmnJK89yjha\"asFDSJ973-----END CERTIFICATE-----")

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 6-20    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 6-21    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: & (ampersand) means that the filters should be linked by a logical AND: all filters must evaluate to true for the expression to match a key. | (pipe) means that the filters should be linked by a logical OR: if at least one filter evaluates to true, the expression matches a key. 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 6-22    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 6-23    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 6-24    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: Certificate Manager Agents Data Recovery Manager Agents Registration Manager Agents Trusted Managers (for SSL certificates used by trusted servers)
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 6-25    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.

Table 6-26    Variables Returned by the Process DRM Request Interface  

Variable	Description
result.header variables	Variables added to the header object.
archivedBy	user ID The user ID of the Data Recovery Agent that authorized the archival. This is sent only for completed archival requests.
archivedOn	seconds since 1 January 1970 The time when the key was stored in the archive. Sent only for completed archival requests.
callerName	user ID 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.
createdOn	seconds since 1 January 1970 The time when the request was created.
keyAlgorithm	OID The object identifier (OID) of the algorithm used by the key in the archive request.
keyLength	number The number of bits in the key in the archive request.
localca	yes | no Indicates whether the Certificate Manager associated with the Data Recovery Manager is located on the same host.
localkra	yes | no Indicates whether the Data Recovery Manager is located on the same host as the Process DRM Request interface. For this interface, the value is always yes.
ownerName	Distinguished Name (DN) string. See RFC 2253. The subject name on the certificate corresponding to the key to be archived. This appears only for archival requests.
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.
requestType	enrollment | recovery Indicates whether the request was made to archive (enrollment) or recover a key.
serialNumber	number A unique identification number that identifies a key in the archive. This differs from the certificate serial number and also from the request identifier (seqNum).
seqNum	number The sequence number assigned to the request by the Data Recovery Manager.
state	VALID | INVALID The current status of the key corresponding to the request.
status	pending | complete Only requests that have status == pending need to use the Process DRM Request interface to assign the request to an agent. Requests that are complete can only be displayed.
updatedBy	user ID Indicates the user ID of the agent that last changed the status of the request.
updatedOn	seconds since 1 January 1970 The time when the request status was last changed.

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.

Table 6-27    Parameters Accepted by the Process Request Interface  

Parameter	Format and Description
doAssign	reassignToMe | reassignToNobody | assignToMe | null Specifies how to change the agent assigned to a pending request. Use reassignToMe if the request has already been assigned to another agent or assignToMe if the request has not been assigned (or has just been assigned with reassignToNobody). If the interface is used with no doAssign parameter, the request in question is redisplayed using the processReq.template.
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 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.

Table 6-28    Variables Returned by the Process 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.
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.
requestType	enrollment | getCAChain | getCertificates | getRevocationInfo | renewal | revocation | unrevocation The requestType returns the type of request that was made to the interface returning this template. The Process Request Interface is used to assign pending requests, so only requests for enrollment, renewal, revocation, and unrevocation would need a link to the Process Request Interface.
seqNum	number The sequence number assigned to the request by the Certificate Manager or Registration Manager.
status	pending | complete Only requests that have status == pending need to use the Process Request interface to assign the request to an agent.

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 6-29    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:

Table 6-30    Variables Returned by the Recover Key By Serial Number Interface  

Variable	Description
result.fixed variables	Variables added to the fixed object
host	string The fully qualified domain name of the CMS server that processed the request. This allows the resulting template to construct forms that post data to the same interface using the same host and port.
port	number The port number that was used to service the request.
scheme	http | https The protocol that was used to make the request.
result.header variables	Variables added to the header object.
errorDetails	string If an error occurred while processing the request, this variable contains an error message.
recoveryID	number The unique number assigned to this recovery request. If agents need to approve the request, they will supply this number to the Examine Recovery Interface.

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.

Table 6-31    Parameters Accepted by the Remove Certificate Hold Interface  

Parameter	Format and Description
op	doUnrevoke Specifies the operation to perform. The valid value for the Remove Certificate Hold interface is "doUnrevoke."
serialNumber	number The serial number (in decimal or hexadecimal) of the certificate to revoke.
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 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:

Table 6-32    Variables Returned by the Remove Certificate Hold Interface  

Variable	Description
result.header variables	Variables added to the header object.
dirEnabled	yes | no Indicates whether LDAP publishing is enabled on the Certificate Manager that handled the request.
dirUpdated	yes | no If directory publishing is enabled, this indicates whether or not the directory was updated with the new certificate status.
error	message If there was an error while processing the unrevocation request, the error message is stored in this variable. Otherwise, the value is null.
publishCRLError	message If the CMS server attempted to publish the CRL and encountered an error, this variable contains the text of the error message.
publishCRLSuccess	yes | no If the CMS server attempted to publish the CRL to a directory, this variable will indicate whether the update was successful.
serialNumber	number The decimal serial number of the certificate.
unrevoked	yes | no | pending Indicates whether or not all certificates were successfully unrevoked.
updateCRL	yes | no Indicates whether or not the CMS server attempted to update the Certificate Revocation List (CRL). If no or null, the CRL will be updated at the next scheduled update interval. If yes, check udpateCRLSuccess to determine if the update was successful.
updateCRLError	message If the CMS server attempted to update the CRL and encountered an error, this variable contains the text of the error message.
updateCRLSuccess	yes | no If the CMS server attempted to update the CRL, this variable will indicate whether the update was successful.

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 6-33    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 6-34    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.

Table 6-35    Parameters Accepted by the Select For Revocation Interface  

Parameter	Format and Description
revokeAll	QUERY_FILTER For information on constructing a query filter, see Table 3-17 in the End-Entity Interfaces List Certificates Interface section. To ensure accuracy when revoking certificates, you should use a query filter that selects each certificate by its serial number. An example value for revokeAll to revoke certificates with serial numbers 10 and 14 is: (|(certRecordId=10)(certRecordId=14))
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 certificates to select for revocation. This value is simply passed through and shows up in the response template as result.header.totalRecordCount.

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 6-36    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.

Table 6-37    Parameters Accepted by the Update CRL Interface  

Parameter	Format and Description
crlIssuingPoint	MasterCRL Specifies the issuing point maintained by the CMS server handling the CRL update. In the default case, the only issuing point for all CRL information is the master CRL. If other issuing points have been configured in the Certificate Manager's configuration file, you can use the token used to define the issuing point for this parameter.
signatureAlgorithm	MD5withRSA | SHA1withDSA | SHA1withRSA Specifies the signing algorithm that should be used to sign the updated CRL. The CA signing key must match the key type (RSA or DSA) of the selected algorithm.
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 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:

Table 6-38    Variables Returned by the Update CRL Interface  

Variable	Description
result.header variables	Variables added to the header object.
crlPublished	Success | Failure Indicates whether or not the CRL was successfully updated and signed.
error	message A message explaining why the CRL update failed.

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 6-39    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 6-40    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.