Chapter 3
End-Entity Interface Reference
This chapter provides a detailed reference of all the service interfaces available on an end-entity port of iPlanet Certificate Management System. For each interface, there is a description including the URI used and the purpose, 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 End-Entity Interfaces
The following table lists the end-entity interfaces and their functions. The sections that follow cover each interface in detail.
Certificate Enrollment Protocol Interface
Description
URI: /cgi-bin/pkiclient.exe
Available on: Certificate Manager and Registration Manager
Function: Handles Certificate Enrollment Protocol (CEP) requests from devices such as Virtual Private Network (VPN) routers.
VPN routers use CEP to enroll in and get information about their PKI. The Certificate Enrollment Protocol interface uses CEP to issue new certificates, distribute Certificate Revocation List (CRL) data, and distribute the CA certificate.
Default Forms
There are no forms that use the Certificate Enrollment Protocol. The interface is provided so that VPN clients, such as routers, can use CEP to interact with the PKI.
Request Parameters
You will not generally develop your own request forms or response templates for use with CEP. The Certificate Enrollment Protocol interface complies with the CEP protocol developed by Cisco, so if your application or device uses this protocol it will be able to use the Certificate Enrollment Protocol Interface.
To use the interface with a Cisco router, for example, you configure the router to point to the end-entity gateway port using the router's enrollment url command. You can then use crypto ca enroll to request a certificate:
> crypto ca identity Example
> enrollment url https://example:443/
> crypto ca enroll Example
The router uses the CEP protocol and expects to find the /cgi-bin/pkiclient.exe interface at the URL named by the enrollment url command. The details of interacting with the interface are handled by the protocol itself.
Challenge Revocation Interface
Description
URI: /challenge_revocation1
Available on: Certificate Manager and Registration Manager
Function: Allows an entity to revoke a certificate using a challenge password set during enrollment.
The Challenge Revocation interface is useful if an entity must revoke a certificate that is not available or not valid for SSL client authentication. (The Revocation Interface can be used to present a certificate using SSL client authentication for revocation.) To use this interface, the challenge password for revocation must be set during enrollment (see the challengePassword request parameter in Enrollment Interface).
Default Forms
The ChallengeRevoke1.html form is the only default form that uses the Challenge Revocation interface. It allows an end user to enter either the certificate's serial number or subject name and the challenge password to revoke the certificate.
Request Parameters
The following table lists the parameters accepted by the Challenge Revocation interface.
Table 3-2 Parameters Accepted by the Challenge Revocation Interface
|
Parameter
|
Format and Description
|
|
certSerialToRevoke
|
number (decimal or hexadecimal)
The serial number of the certificate to revoke. Either this parameter or subjectName are required.
|
|
challengePhrase
|
string
The challenge phrase, set during certificate enrollment, that allows the certificate to be revoked.
|
|
reasonCode
|
0-8
The code for the reason why the certificate is being revoked. This code is added to the Certificate Revocation List (CRL) entry for the revoked certificate. Valid reasonCode values 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
|
|
subjectName
|
Distinguished Name (DN) string. See RFC 2253.
The DN appearing in the certificate subject field. Either subjectName or certSerialToRevoke must be specified. The subject name should only be used when the subject DN is guaranteed to uniquely identify the certificate.
Example DN: 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.
|
|
templateType
|
RevocationConfirmation
This parameter specifies which response template to use. At this time, the only valid value is "Revocation Confirmation." This value causes the revocationResult.template file to be used.
|
Response
The response from the Challenge Revocation interface will be identical to a response from the Revocation interface. See the Response section in Revocation Interface for details on what JavaScript variables are returned in the response template.
Display Certificate By Serial Number Interface
Description
URI: /displayBySerial
Available on: Certificate Manager
Function: Displays a single certificate in human-readable form.
The Display Certificate By Serial Number interface is typically used within a form that lists certificates to display detailed information about a selected certificate. The response is an HTML page built from a template (not just raw certificate data), so this interface should not be used to retrieve certificates for processing (such as importing into a browser); use the Get Certificate By Serial Number Interface (/getBySerial) instead.
Default Forms
The Display Certificate By Serial Number interface is used in the queryCert.template file. Each certificate in the list of certificates satisfying the query has a button the user can press to see the certificate in detail. This button submits data to the Display Certificate By Serial Number interface.
Request Parameters
The following table lists the parameters accepted by the Display Certificate By Serial Number interface.
Table 3-3 Parameters Accepted by the Display Certificate 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 certificate to display.
|
|
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. The base JavaScript for responses is inserted in place of the <CMS_TEMPLATE> tag. In addition, the Display Certificate By Serial Number interface adds the JavaScript variables listed in the following table:
Table 3-4 Variables Returned by the Display Certificate By Serial Number Interface
|
Variable
|
Description
|
|
result.header variables
|
Variables added to the header object.
|
|
authorityid
|
ca
Indicates the source of the certificate information. Only Certificate Managers can return certificates by serial number directly.
|
|
certChainBase64
|
base-64 encoded data
Contains the certificate in PKCS #7 format.
|
|
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
Contains details about the certificate in a human-readable form. This is the field used to show the certificate to a user in a page.
|
|
serialNumber
|
number
The serial number of the certificate in decimal.
|
Display Certificate From Request Interface
Description
URI: /displayCertFromRequest
Available on: Certificate Manager or Registration Manager
Function: Retrieves the certificate associated with an enrollment or renewal request to be displayed in a response template.
The Display Certificate From Request interface is typically used in JavaScript embedded in the response template of an enrollment or renewal request. This interface uses the requestID returned in the JavaScript of a response to fetch the associated certificate.
In the requestStatus.template file, there is JavaScript code to build a URL that fetches the certificate from the Display Certificate From Request Interface if the CMS server is a Registration Authority.
The requestID parameter from the response template is required: it identifies the request from which to extract the certificate.
Default Forms
By default, the Display Certificate From Request interface is used by the requestStatus.template file only.
Request Parameters
The following table lists the parameters accepted by the Display Certificate From Request interface.
Table 3-5 Parameters Accepted by the Display Certificate From Request Interface
|
Parameter
|
Format and Description
|
|
requestId
|
number
The requestID returned in the JavaScript by the Enrollment or Renewal interface (fixed.requestID).
|
|
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
By default, the displayCertFromRequest.template file is used to create the response. The <CMS_TEMPLATE> tag is replaced with the the base JavaScript for responses. In addition, the Get Certificate From Request interface adds the JavaScript variables listed in the following table:
Table 3-6 Variables Returned by the Display Certificate From Request 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.
|
|
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
The request identification number that was requested.
|
|
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.
|
|
result.header variables
|
Variables added to the header object.
|
|
emailCert
|
true | false
If true, the certificate contained in the recordSet array or cmmfResponse is a valid S/MIME certificate.
|
|
noCertImport
|
true | false
Indicates whether the certificate should not be imported.
|
|
requestId
|
number
The request identification number that was requested.
|
|
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.
|
|
serialNo
|
number
The serial number (in decimal) of the certificate.
|
Enrollment Interface
Description
URI: /enrollment
Available on: Certificate Manager and Registration Manager.
Function: Enrolls an entity into the Public-Key Infrastructure (PKI).
This servlet uses data from an HTTP POST or HTTP GET to formulate a certificate request, hands the request off to a Certificate Manager, and returns a response (which may include the newly issued certificate) to the entity.
The certificate request may be based only on the data in the request, or it may get additional data from an authentication plug-in named in the authenticator parameter. If an authentication plug-in is used, the Certificate Manager may be able to automatically issue a certificate which is passed to the entity in the enrollment servlet's response. If no authentication plug-in is used, the request is placed in an agent queue for manual approval and the enrollment servlet returns a "request pending" page to the entity.
|
Note
|
The forms rely on a shared library called xenroll.dll (downloaded from the CMS server) to generate keys for Microsoft Internet Explorer browsers. By default, the keys generated by xenroll.dll have a "medium" security setting which means they will be stored unencrypted and that they can be used by the browser for signing without prompting the user for a password. A "high" security setting will store the keys in a separate, encrypted file and force the user to enter a password to use the keys for signing. There is no way to force a "high" setting for keys, but you can force a dialog to appear to allow the user to choose a security setting when the key is first generated. Edit the the VisualBasic script for xenroll.dll used in the enrollment forms (listed in the next section). Set the value of the GenKeyFlags parameter to 3 to prompt the user for a security setting when a key is generated using Microsoft Internet Explorer.
|
Default Forms
There are two types of default HTML forms that use the enrollment interface: manual or automated enrollment. Forms that use automated enrollment send an authentication plug-in name as a parameter in the request which the servlet can use to authenticate and process the request without manual intervention.
The default manual enrollment forms are:
ManUserEnroll.html for requesting client certificates.
ManServerEnroll.html for requesting server certificates.
ManObjSign.html for requesting object signing certificates.
ManCAEnroll.html for requesting subordinate Certificate Manager signing certificates.
ManRAEnroll.html for requesting Registration Manager certificates.
The default automated enrollment forms are:
DirUserEnroll.html uses a UserDirEnrollment instance of the UidPwdDirAuth plug-in class by default.
DirPinUserEnroll.html uses a PinDirEnrollment instance of the UidPwdPinDirAuth plug-in class by default.
Request Parameters
The following table lists the parameters accepted by the enrollment interface.
Table 3-7 Parameters Accepted by the 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 provided 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 parameter 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 parameter 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 parameter 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 parameter 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 parameter 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
The Registration Authority or Certificate Authority that process an enrollment request will perform some processing, determine the status of the request, then return a result using the appropriate template for the status.
The response templates are ASCII files that you can edit to create responses suited to your needs. The templates may include JavaScript that depends on the JavaScript inserted in place of the <CMS_TEMPLATE> tag when the response is sent. The status of the request determines which template will be used for the response. The following table describes the templates used by the enrollment interface (more details on the request status codes can be found in Table 3-9):
Table 3-8 Enrollment Interface Response Templates
|
Template File Name
|
Request Status
|
Description
|
|
EnrollSuccess.template
|
2 (Success)
|
Used only for requests that specify an authenticator. If authentication and subsequent policy processing are successful and importCert was "true" in the request, a certificate is generated (otherwise, see GenRejected.template). The issued certificate is included in base-64 in the response. The template includes JavaScript and VisualBasic code that attempts to import the certificate into a browser's certificate database.
|
|
GenError.template
|
6 (Error)
|
Used to display an error message.
|
|
GenPending.template
|
3 (Pending)
|
Used to inform the user that the certificate request he or she submitted has been queued for agent approval.
|
|
GenRejected.template
|
5 (Rejected)
|
Used to inform the user that the certificate request he or she submitted has been rejected by the CMS server.
|
|
GenSuccess.template
|
2 (Success)
|
Used to inform the user that the certificate request he or she submitted has been approved by the CMS server.
|
|
GenSvcPending.template
|
3 (Pending)
|
Used to inform the user that the certificate request he or she submitted has been queued for agent approval.
|
|
GenUnauthorized.template
|
1 (Unauthorized)
|
Used to inform the user that he or she performed an unauthorized operation.
|
The <CMS_TEMPLATE> tag in the selected template is replaced with the base JavaScript code. In addition, the Enrollment interface may add the JavaScript variables listed in the following table. Not all templates use all of the variables listed in the table; a variable is only included when it is used (for example, the EnrollmentSuccess.template does not include result.fixed.unexpectedError).
Table 3-9 Variables Returned by the 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.
|
Get CA Chain Interface
Description
URI: /getCAChain
Available on: Certificate Manager only.
Function: Retrieves the CA certificate or certificate chain for the Certificate Manager either in binary form for use by an application or in a format for display.
The Get CA Chain interface accepts an operation (for example, download) and a MIME type to be used for the response. The response is always the CA certificate or certificate chain (if the CA certificate is not self-signed) for the Certificate Manager handling the request. No templates are used; the response is either ASCII data that can be displayed or a binary blob (using the indicated MIME type) that can be used by the requesting application.
Using the Get CA Chain interface to display certificates is useful for creating data that can be imported into another application such as an HTTP or LDAP server.
Default Forms
The Get CA Chain interface uses one default form: GetCAChain.html. This form allows an entity to choose one of four operations:
Import the CA certificate chain into a browser (download).
Download the CA certificate chain in binary form (downloadBIN).
Display the CA certificate chain in PKCS #7 for importing into a server (display).
Display certificates in the CA certificate chain for importing individually into a server (displayIND).
Request Parameters
The following table lists the parameters accepted by the Get CA Chain interface.
Table 3-10 Parameters Accepted by the Get CA Chain Interface
|
Parameter
|
Format and Description
|
|
mimeType
|
<type>/<subtype>
Indicates the MIME the CMS server should use for the response. The default form uses application/x-x509-ca-cert for downloads. For op = downloadBIN, mimeType is ignored and application/octet-stream is always used.
|
|
op
|
display | displayIND | download | downloadBIN
This required parameter specifies how the CA certificate chain should be returned:
display returns a base-64 encoded PKCS #7 certificate chain.
displayIND returns each certificate in the CA chain in a base-64 encoded DER blob and a human-readable format.
download returns the entire certificate chain in binary form using the MIME type specified. If the browser is not Internet Explorer, the chain is returned as a PKCS #7 blob. If the browser is Internet Explorer, only the CA signing certificate will be returned in a DER-encoded format.
downloadBIN is the same as download, except that the MIME type is always set to application/octet-stream. Use of downloadBIN is deprecated; use download and set mimeType = application/octet-stream in the request instead.
|
|
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 Get CA Chain interface does not use any templates. The response is just the requested certificate or certificates in the format indicated by the request parameters.
Get Certificate By Serial Number Interface
Description
URI: /getBySerial
Available on: Certificate Manager only
Function: Retrieves the certificate with the given serial number in a specified format. The certificate can be imported into a browser.
This interface is used in the EnrollSuccess.template and RenewalSuccess.template to download and import the newly issued certificate. The displayBySerial.template also uses this interface to create "Import Certificate" and "Import S/MIME Certificate" buttons on a page that displays a certificate; this allows a user to retrieve and import a certificate that was issued manually.
Default Forms
There are no default forms that use the Get Certificate By Serial Number interface. This interface is usually used embedded in a response template to either embed a certificate in the response or provide a button on a form that downloads and imports the certificate.
Request Parameters
The following table lists the parameters accepted by the Get Certificate By Serial Number interface.
Table 3-11 Parameters Accepted by the Get Certificate By Serial Number Interface
|
Parameter
|
Format and Description
|
|
cmmfResponse
|
true | false
Indicates whether the certificate should be returned using CMMF. The CMMF format can be used with browsers that understand it to allow the browser to import the certificate into its database. The CMMF data will be returned as a JavaScript variable in the response.
|
|
emailCert
|
true | false
Indicates whether the certificate returned is expected to be valid for signing e-mail.
|
|
importCert
|
true | false
Indicates how to format the certificate in the response if cmmfResponse is false or not set. By default, the response will be a page created from the ImportCert.template file. If importCert = true, the MIME type will be set to application/x-x509-user-cert and the data will be a binary blob in PKCS #7 format.
|
|
serialNumber
|
number
The serial number of the certificate to retrieve.
|
|
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 importCert = true in the request, the response is a binary blob containing the certificate and no templates are used to construct the response. See the Request Parameters for details on how the response is formatted.
By default, the ImportCert.template file is used to create the response. The <CMS_TEMPLATE> tag is replaced with the base JavaScript for responses. In addition, the Get Certificate By Serial Number interface adds the JavaScript variables listed in the following table:
Table 3-12 Variables Returned by the Get Certificate By Serial Number 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.
|
|
certNickname
|
string
The nickname for the certificate. By default, this is just the certificate subject DN.
|
|
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.
|
|
cmmfResponse
|
base-64 encoded data
The CMMF response data containing the certificate (if cmmfResponse was true in the request). If the browser supports the Personal Security Manager crypto API, you can use this response with a call to importUserCertificates to import the certificate into a local database:
importUserCertificates(result.fixed.nickname,
result.fixed.cmmfResponse, true);
(The last parameter indicates whether the user should be prompted to back up the key.)
|
|
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.
|
|
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.
|
|
|
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.
|
|
serialNo
|
number
The serial number (in decimal) of the certificate.
|
Get Certificate From Request Interface
Description
URI: /getCertFromRequest
Available on: Certificate Manager or Registration Manager
Function: Retrieves the certificate associated with an enrollment or renewal request to be displayed in a response template or imported into a browser.
The Get Certificate From Request interface is typically used in JavaScript embedded in the response template of an enrollment or renewal request. This interface uses the requestID returned in the JavaScript of a response to fetch the associated certificate.
In the EnrollSuccess.template and RenewalSuccess.template files, there is JavaScript code to build a URL that fetches the certificate from the Get Certificate From Request interface. The URL is assigned to the window.location object, which causes the contents of the URL to be displayed in-line in the response.
The requestID parameter from the response template is required: it identifies the request from which to extract the certificate. A parameter can also be used to instruct the requesting browser to import the certificate into its database: importCert or cmmfResponse (for browsers that support CMMF).
Default Forms
The Get Certificate From Request interface is used by response templates, not forms that an entity submits. The interface is used in these templates to incorporate the certificate in the page itself, so that it can be displayed and possibly imported into the browser. The templates that use the interface by default are:
displayCertFromRequest.template is a generic template that shows how to display a certificate from a request.
EnrollSuccess.template is the template returned by a successful enrollment request (when a certificate has been issued, not when the request is successful but still pending).
RenewalSuccess.template is the template returned by a successful automated renewal request (such as a renewal using SSL client authentication).
Request Parameters
The following table lists the parameters accepted by the Get Certificate From Request interface.
Table 3-13 Parameters Accepted by the Get Certificate From Request Interface
|
Parameter
|
Format and Description
|
|
cmmfResponse
|
true | false
Indicates whether the returned certificate should be formatted using Certificate Management Message Format (CMMF). Entities that support CMMF can use the result to import the certificate into a local database. The CMMF data will be returned as a JavaScript variable in the response.
|
|
importCert
|
true | false
Indicates whether the returned certificate should be imported into the local database. This causes the MIME type of the returned HTTP to be application/x-x509-user-cert and the certificate to be a PKCS #7 formatted binary blob.
|
|
requestId
|
number
The requestID returned in the JavaScript by the Enrollment or Renewal interface (fixed.requestID).
|
|
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 importCert = true in the request, the response is a binary blob containing the certificate and no templates are used to construct the response. See the Request Parameters for details on how the response is formatted.
By default, the ImportCert.template file is used to create the response. The <CMS_TEMPLATE> tag is replaced with the base JavaScript for responses. In addition, the Get Certificate From Request interface adds the JavaScript variables listed in the following table:
Table 3-14 Variables Returned by the Get Certificate From Request 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.
|
|
certNickname
|
string
The nickname for the certificate. By default, this is just the certificate subject DN.
|
|
cmmfResponse
|
base-64 encoded data
The CMMF response data containing the certificate (if cmmfResponse was true in the request). If the browser supports the Personal Security Manager crypto API, you can use this response with a call to importUserCertificates to import the certificate into a local database:
importUserCertificates(result.fixed.nickname, result.fixed.cmmfResponse, true);
(The last parameter indicates whether the user should be prompted to back up the key.)
|
|
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
The request identification number that was requested.
|
|
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.
|
|
result.header variables
|
Variables added to the header object.
|
|
emailCert
|
true | false
If true, the certificate contained in the recordSet array or cmmfResponse is a valid S/MIME certificate.
|
|
noCertImport
|
true | false
Indicates whether the certificate should not be imported.
|
|
requestId
|
number
The request identification number that was requested.
|
|
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.
|
|
serialNo
|
number
The serial number (in decimal) of the certificate.
|
Get CRL Interface
Description
URI: /getCRL
Available on: Certificate Manager only
Function: Retrieves the current Certificate Revocation List (CRL) for this certificate authority.
This interface can be used to retrieve a CRL for display or importing into an application and it can be used simply to check whether a certificate appears on the current CRL.
Default Forms
The only default form that uses the Get CRL interface is DisplayCRL.html. This form allows the user to choose any of the possible options for the getCRL interface:
Check whether a particular certificate is on the CRL.
Import the CRL into a browser.
Display the CRL in binary form.
Display the CRL in human-readable form (pretty print).
Request Parameters
The following table lists the parameters accepted by the Get CRL interface.
Table 3-15 Parameters Accepted by the Get CRL Interface
|
Parameter
|
Format and Description
|
|
certSerialNumber
|
Number string in decimal (e.g., 330) or hexadecimal (0x14A).
If op = checkCRL, use this parameter to specify the serial number of the certificate to check.
|
|
issuepoint
|
MasterCRL
The default value, MasterCRL, indicates that the complete master CRL should be checked. Other issue points may be configured for a Certificate Manager; in that case use the token that defines the issue point in the configuration file (CMS.cfg).
|
|
op
|
checkCRL | displayCRL | getCRL | importCRL
This required parameter specifies the CRL operation to perform:
checkCRL instructs the Certificate Manager to look for the serial number specified in certSerialNumber on the CRL. The result is returned in the result.header.isOnCRL field.
displayCRL returns the entire CRL formatted in HTML for display in a browser.
getCRL returns the entire CRL as a PKCS #7 formatted blob; the MIME type of the response will be application/octet-stream for Communicator clients or application/x-pkcs7-crl. for Internet Explorer.
importCRL is the same as getCRL except the MIME type is always application/x-pkcs7-crl.
|
|
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
Responses to requests for checkCRL or displayCRL use the displayCRL.template template. The <CMS_TEMPLATE> tag is replaced with the base JavaScript for responses. In addition, the Get CRL interface adds the JavaScript variables listed in the following table:
Table 3-16 Variables Returned by the Get CRL Interface
|
Variable
|
Description
|
|
result.header variables
|
Variables added to the header object.
|
|
certSerialNumber
|
number
If toDo = checkCRL, this field contains the serial number of the certificate that was checked (from certSerialNumber in the request).
|
|
crlBase64
|
base-64 encoded data
The base-64 encoded CRL data in PKCS #7 format.
|
|
crlPrettyPrint
|
string
Contains the CRL formatted for human-readable display if op=displayCRL in the request.
|
|
isOnCRL
|
true | false
If toDo = checkCRL, this field indicates whether the named certificate serial number appears on the CRL.
|
|
toDo
|
displayCRL | checkCRL
Indicates the type of result being returned.
|
List Certificates Interface
Description
URI: /listCerts
Available on: Certificate Manager
Function: Retrieves a list of certificates that match a query filter.
The query criteria are search filters that the interface uses to select certificates in the Certificate Manager's repository. The queryCert.html default form contains JavaScript code that can construct all possible filters. You should study this file for examples before you write code to construct your own forms. Valid query filter constructions are explained in the Request Parameters section.
The response is constructed using the queryCert.template. The listing that this template provides by default has code for displaying a listed certificate in more detail, revoking a listed certificate, or revoking all certificates listed.
Default Forms
The List Certificates interface uses two default forms:
queryBySerial.html is a simple form that accepts a lower and upper bound for the range of serial numbers and the option to skip revoked or invalid certificates. This form constructs a simple query filter to select certificates that meet the user's preferences for certificate status (valid, invalid, and revoked).
queryCert.html is a complex form that allows the user to specify all possible query criteria. This form makes extensive use of JavaScript to formulate a query filter for any criteria the user chooses.
Request Parameters
The following table lists the parameters accepted by the List Certificates interface.
The queryCertFilter 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 3-17 Parameters Accepted by the List Certificates Interface
|
Parameter
|
Format and Description
|
|
maxCount
|
number
Specifies the maximum number of certificates to display on each page returned. If more than maxCount certificates match the search criteria, each page will have controls to see the next or previous page of results.
|
|
op
|
listCerts
The only operation supported by the List Certificates interface is listCerts.
|
|
queryCertFilter
|
([<OP>]<FILTER>[<FILTER>...])
Details about building query filters are provided in the next table.
The queryCertFilter 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 certificate.
| (pipe) means that the filters should be linked by a logical OR: if at least one filter evaluates to true, the expression matches a certificate.
Any number of filters can be concatenated within any set of parentheses.
An example filter is
(&(certStatus=VALID)(|(x509cert.nsExtension.SSLClient=on)(x509cert.nsExtension.SecureEmail=on)))
This filter matches any certificate that is valid and has either the SSL Client or S/MIME bit set in the netscape-cert-type extension.
|
|
querySentinel
|
number
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.
|
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 x509cert.subject) accept the asterisk (*) as a wildcard to match 0 or more characters; for example. "E=jdoe*" matches "E=jdoe@netscape.com" and "E=jdoe@example.com."
Table 3-18 List Certificates queryCertFilter Parameters
|
Parameter
|
Expression Values
|
|
certCreateTime
|
Value: date (number of seconds since Jan 1, 1970)
A date object can be created using the JavaScript Date() constructor.
This parameter matches the date a certificate was issued. For example, to find certificates created during 1999:
Object lowDate = new Date(1999,00,01);
Object highDate = new Date(1999,11,31);
form.queryCertFilter.value =
"(&(certCreateTime>=" + lowDate + ")" +
"(certCreateTime<=" + highDate + ")";
|
|
certIssuedBy
|
Value: user ID of an agent issuing a certificate
Use the asterisk (*) wildcard to match partial names. For example, (certIssuedBy=localAgent*).
|
|
certRecordId
|
Value: number in decimal or hexadecimal.
This parameter matches the serial number on a certificate. Connect a lower and upper bound with a logical AND (&) to specify a bounded range of serial numbers. For example:
(&(certRecordId>=100)(certRecordId<=199))
|
|
certRevokedBy
|
Value: user ID of an agent that revoked a certificate
Use the asterisk (*) wildcard to match partial names. For example, (certRevokedBy=localAgent*).
|
|
certRevokedOn
|
Value: date (number of seconds since Jan 1, 1970)
A date object can be created using the JavaScript Date() constructor.
This parameter matches the date when a certificate was revoked. See certCreateTime for an example of creating a date value in JavaScript
|
|
certStatus
|
Value: * | EXPIRED | INVALID | REVOKED | VALID | REVOKED_EXPIRED
This parameter matches the current status of a certificate. The asterisk (*) matches any status.
|
|
x509cert.certRevoInfo
|
Value: * | number between 0 and 6
This parameter matches the reason for revocation code on a certificate. 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
To search for multiple values, construct a filter with multiple x509cert.certRevoInfo parameters connected with a logical OR. Do not connect these parameters with an AND, since a certificate cannot have more than one revocation reason. For example, to match certificates revoked due to key compromise or an unspecified reason:
(|(x509cert.certRevoInfo=0)(x509cert.certRevoInfo=1))
|
|
x509cert.duration
|
Value: number of milliseconds
This parameter matches the total number of milliseconds of a certificates validity period. Typically a range is specified using filters with >= and <= operators, rather than an exact match. The following list shows the number of milliseconds in some typical time intervals:
Day: 86,400,000
Week: 604,800,000
Month (30 Days): 2,592,000,000
Year: 31,536,000,000
|
|
x509cert.notAfter
|
Value: date (number of seconds since Jan 1, 1970)
A date object can be created using the JavaScript Date() constructor.
This parameter matches the date when a certificate expires. See certCreateTime for an example of creating a date value in JavaScript
|
|
x509cert.notBefore
|
Value: date (number of seconds since Jan 1, 1970)
A date object can be created using the JavaScript Date() constructor.
This parameter matches the date when a certificate became valid. See certCreateTime for an example of creating a date value in JavaScript
|
|
x509cert.nsExtension.<X>
|
Value: on | off
This parameter matches the bit in the ns-cert-type extension specified by the extension <X>.
Substitute an extension identifier for <X>:
SecureEmail - for S/MIME certificates
SSLClient - for SSL client certificates
SSLServer - for SSL server certificates
SubordinateEmailCA - for certificates with the S/MIME CA bit set
SubordinateSSLCA - for certificates with the SSL CA bit set
For example, to match only certificates with the SSL client bit (bit 0) set in the ns-cert-type extension:
(x509cert.nsExtension.SSLClient=on)
|
|
x509cert.subject
|
Value: a pattern that may include the wildcard (*)
This parameter matches the certificate subject DN. You can use a single filter or connect multiple filters to build more complex DN patterns.
The value is typically a string in the form *<TAG>=<VALUE>*. The asterisks allow the name-value pair to be matched at any location in the DN. The tag is one of the subject DN attributes: CN, E, UID, OU, O, L, ST, C.
To allow partial matches, use the wildcard in the attribute value. For example, to match email addresses containing "jdoe,"
(x509cert.subject=*E=*jdoe*)
To force an exact match of "jdoe@example.com," you should still use the wildcard to allow the E attribute to occur anywhere in the DN:
(|(x509cert.subject=*E=jdoe@example.com,*)
(x509cert.subject=*E=jdoe@example.com))
|
Response
The default response template is queryCert.template. The base JavaScript for responses is inserted in place of the <CMS_TEMPLATE> tag. In addition, the Revocation interface adds the JavaScript variables listed in the following table:
Table 3-19 Variables Returned by the List Certificates Interface
|
Variable
|
Description
|
|
result.header Variables
|
Variables added to the header object.
|
|
currentRecordCount
|
The total number of certificates displayed on this page of output. This number may be less than totalRecordCount.
|
|
issuerName
|
The distinguished name (DN) of the certificate authority that processed the query. This DN appears in the issuer field of all of the certificates listed.
Example: CN=Certificate Manager, O=Organization, C=US
|
|
maxCount
|
The maximum number of certificate records to display on any single page of output.
|
|
op
|
The operation parameter to send (to the serviceURL) when the user requests more certificates. This value will always be listCerts for the List Certificates interface.
|
|
queryCertFilter
|
The queryCertFilter parameter that was used to generate the current list of certificates, and will be used for subsequent pages if the user requests to see more certificates. For information on how the filter is constructed, see the Request Parameters section.
An example queryCertFilter is
(&(certStatus=VALID)(certRecordId>=100))
|
|
querySentinel
|
This field holds the number of the lowest certificate serial number to display on the current page of output.
|
|
serviceURL
|
The URI to use to post requests for more certificates matching the query criteria. This variable will always be /listCerts for the List Certificates interface.
|
|
templateName
|
The name of the response template the CMS server should use to construct a response from the serviceURL. By default, this field will always be queryCert.template for the List Certificates interface.
|
|
totalRecordCount
|
The total number of records that match the query criteria. This number may be larger than the currentRecordCount if not all of the matching certificates can be displayed on one page of output.
|
|
recordSet Variables
|
These fields are added to each record object in the recordSet array. They are accessed as fields of a recordSet element in the JavaScript; for example, result.recordSet[1].error.
|
|
issuedBy
|
The user ID of the agent that issued the certificate.
|
|
issuedOn
|
The date when the certificate was issued. Dates are represented as number of seconds since January 1, 1970. The default template provides a function, renderDateFromSecs, that converts these dates to a human-readable string.
|
|
revocationReason
|
If the certificate has been revoked, this field contains the code for the reason. 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
|
|
revokedBy
|
The user ID of the agent who revoked the certificate.
|
|
revokedOn
|
The date when the certificate was revoked. See the description for issuedOn for details on date values.
|
|
serialNumber
|
The serial number of the certificate (in decimal).
|
|
signatureAlgorithm
|
The Object Identifier (OID) of the algorithm used to sign the certificate. For example, "1.2.840.113549.1.1.4" is the OID for an MD5 with RSA signature.
|
|
subject
|
The subject distinguished name of the certificate. For example, "CN=Jane Doe, UID=jdoe, OU=Users, O=Organization, ST=California, C=US."
|
|
subjectPublicKeyAlg
orithm
|
The OID of the key algorithm used by the public key contained in the certificate. For example, "1.2.840.113549.1.1.1" represents an RSA key.
|
|
subjectPublicKeyLen
gth
|
The number of bits of the public key contained in the certificate.
|
|
validNotAfter
|
The date when the certificate expires. See the description for issuedOn for details on date values.
|
|
validNotBefore
|
The date when the certificate became valid. See the description for issuedOn for details on date values.
|
Renewal Interface
Description
URI: /renewal
Available on: Certificate Manager or Registration Manager
Function: Processes requests for certificate renewal.
The Renewal interface allows an end entity to present a certificate and have it renewed. Only certificates that can be used for SSL client authentication can be renewed using the Renewal interface.
Default Forms
The only default form used by the Renewal interface is UserRenewal.html. This form allows a user to renew a certificate using SSL client authentication.
Request Parameters
The following table lists the parameters accepted by the Renewal interface.
Table 3-20 Parameters Accepted by the Renewal Interface
|
Parameter
|
Format and Description
|
|
certType
|
client
Only client certificate renewals are supported through the Renewal interface.
|
|
doSslAuth
|
on | off
Set to on to force the CMS server to request an SSL client authentication certificate. Since this is the only renewal method supported, doSslAuth should always be set to on.
|
|
requestFormat
|
clientAuth
Only client certificate renewals are supported through the Renewal interface.
|
|
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
Responses from the Renewal interface are functionally equivalent to the Enrollment interface. Once the request has been submitted, the role of the Certificate Manager or Registration Manager is the same as if the request were for enrollment: the CMS server either rejects the request, queues it for manual processing, or issues a certificate.
The only difference in the response is for a successful request. The Renewal interface uses the RenwalSuccess.template file by default instead of EnrollSuccess.template. The difference between these two files (by default) is superficial: the word "Enrollment" is replaced with the word "Renewal." If you want to customize the renewal success message, customize the RenewalSuccess.template file.
Except for template for a successful request, the Renewal interface response is identical to the Enrollment interface response.
Refer to the Response section of the Enrollment Interface section for complete details on the data returned and templates used.
Revocation Interface
Description
URI: /revocation
Available on: Certificate Manager or Registration Manager
Function: Allows automatic revocation of certificates by client authentication (an entity can revoke a certificate it presents).
The response is always a form that indicates the status of the revocation request (revoked, pending, or error), the result of updating the Certificate Revocation List, and the result of updating the certificate directory (if publishing is enabled).
Default Forms
The Revocation interface uses the UserRevocation.html form by default. This form posts requests that use SSL client authentication to present the certificate to be revoked. The certificate is automatically revoked.
Request Parameters
The following table lists the parameters accepted by the Revocation interface.
Table 3-21 Parameters Accepted by the Revocation Interface
|
Parameter
|
Format and Description
|
|
certType
|
client
Specifies the type of certificate to revoke. For automatic revocation, the certType must be client and doSslAuth must be on.
|
|
csrRequestorComments
|
string
Additional comments to assist the agent who will process the revocation request.
|
|
csrRequestorEmail
|
string
Contact email address of someone responsible for the CMS server certificate. May be used to send out notification when a certificate has been revoked.
Example: alice@example.com
|
|
csrRequestorName
|
string
Name of someone responsible for the CMS server certificate; helps identify the requestor during manual revocation.
Example: Alice Apple
|
|
csrRequestorPhone
|
string
Phone number of someone responsible for the CMS server certificate.
Example: 650.555.1212
|
|
doSslAuth
|
on | off
Instructs the CMS server to request SSL client authentication. The certificate that the entity then presents will be the one that is automatically revoked. Only valid if certType = client.
|
|
op
|
RevocationRequest
RevocationRequest is the only value currently supported for the op parameter. This parameter is required.
|
|
reasonCode
|
0-8
The reasonCode identifies the reason the certificate is being revoked. This information will be recorded on the Certificate Revocation List. The reasonCode is only valid for automatic revocation requests. Manual revocation requests can use the csrRequestorComments parameter to tell the processing agent why the certificate is being revoked.
The meaning of the reasonCode values are:
0 - Unspecified
1 - Key Compromised
2 - CA Compromise*
3 - Affiliation Changed
4 - Certificate Superseded
5 - Cessation of Operation
6 - Certificate Hold*
7 - (Reserved for future use)*
8 - Remove from CRL*
Values marked with an asterisk (*) are valid reasonCode parameters that are not used in the default UserRevocation.html form. These values should generally not be used for client self-revocation.
|
|
serialNumber
|
string
The serial number of the certificate to be revoked. This parameter is used for manual revocation: either a serial number or a subject name is used to identify the certificate to be revoked.
|
|
subject
|
string
The subject distinguished name (DN) of the certificate to be revoked.
|
|
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
|
RevocationConfirmation
RevocationConfirmation is the only value currently supported. This parameter is required.
|
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 Revocation interface adds the JavaScript variables listed in the following table:
Table 3-22 Variables Returned by the Revocation Interface
|
Variable
|
Description
|
|
Generic Variable
|
|
|
revokedCerts
|
The number of certificates that were revoked as a result of the request.
|
|
result.header Variables
|
Variables added to the header object.
|
|
certsToUpdate
|
The number of certificates that need to be updated in the publishing directory as a result of the request. Used only when directory publishing is on, indicated by the dirEnabled field in the header object.
|
|
certsUpdated
|
A number, less than or equal to certsToUpdate, indicating how many certificates have already been successfully updated in the publishing directory. Used only when directory publishing is on, indicated by the dirEnabled field in the header object.
|
|
dirEnabled
|
yes | no
Indicates whether directory publishing is enabled on the Certificate Manager where the revocation request was handled. May be null if directory publishing is not defined.
|
|
error
|
A text message indicating why the revocation request itself could not be processed. The result.header.error message will exist only when result.header.revoked = no.
|
|
revoked
|
yes | pending | no
This field indicates the overall status of the revocation request. If the certificate could be revoked automatically, revoked will be yes. If the request was processed successfully, but requires manual processing by an agent, revoked = pending. If revoked = no, the request could not be processed. See result.header.error for the error message.
|
|
totalRecordCount
|
The total record count indicates the number of requests that were successfully processed. This number may be different from the number of certificates actually revoked. The recordSet array contains information for each processed revocation request (including requests that failed due to an error). The recordSet.length may be less than totalRecordCount if any certificates were already revoked.
|
|
updateCRL
|
yes | no
If present and equal to yes, this field indicates that the Certificate Manager has attempted to update the Certificate Revocation List (CRL). Check updateCRLSuccess to see if the update was successful. If this field is null or equal to no, the Certificate Manger will attempt to update the CRL at the next scheduled update interval.
|
|
updateCRLError
|
This text message indicates the reason why an attempt to update the CRL has failed. This will be present if updateCRL = yes and updateCRLSuccess = no (or is null).
|
|
updateCRLSuccess
|
yes | no
If updateCRL = yes, this field indicates whether the attempt to update the CRL has succeeded and the certificate now appears as revoked on the CRL. If this field is null or equal to no, see updateCRLError.
|
|
recordSet Variables
|
These fields are added to each record object in the recordSet array. They are accessed as fields of a recordSet element in the JavaScript; for example, result.recordSet[1].error.
|
|
error
|
This text message indicates the reason that the certificate associated with this recordSet was processed, but could not be revoked.
|
|
serialNumber
|
Contains the serial number of the certificate represented by this recordSet object.
|