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 System. 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
The following table lists the agent interfaces and their functions:
Approve Revocation Interface
Description
URI: /ca/doRevoke or /ra/doRevoke
Available on: Certificate Manager or Registration Manager
Function: Actually revokes a certificate or group of certificates for a given reason.
The Select for Revocation Interface is used to select a certificate or group of certificates for revocation based on some criteria. That interface returns a list of certificates using the reasonToRevoke.template file. The reasonToRevoke.template response contains a form that posts data to the Approve Revocation interface with the serial numbers and reasons to finally revoke the certificates.
Default Forms
The Approve Revocation interface is accessed through the reasonToRevoke.template file by default. No forms directly post data to this interface. Other forms, such as revokeCert.html, are used to select certificates based on query criteria; the selected certificates can then be marked for revocation by creating buttons or links that post data to the Approve Revocation interface.
Request Parameters
The following table lists the parameters that are used to revoke certificates through the Approve Revocation interface. This is an agent interface, so the HTTP POST or GET request must use SSL client authentication with a valid agent certificate.
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.
|