1. Manuals
  2. Brands
  3. Netscape Manuals
  4. Software
  5. NETSCAPE MANAGEMENT SYSTEM 6.01 -...
  6. Manual

Netscape MANAGEMENT SYSTEM 6.01 - CUSTOMIZATION Manual

Hide thumbs
Table of Contents

Advertisement

Quick Links

Download this manual
Customization Guide
Netscape Certificate Management System
Version 6.01
May 2002

Advertisement

Table of Contents
loading
Need help?

Need help?

Do you have a question about the NETSCAPE MANAGEMENT SYSTEM 6.01 - CUSTOMIZATION and is the answer not in the manual?

Questions and answers

Subscribe to Our Youtube Channel

Related Manuals for Netscape NETSCAPE MANAGEMENT SYSTEM 6.01 - CUSTOMIZATION

Summary of Contents for Netscape NETSCAPE MANAGEMENT SYSTEM 6.01 - CUSTOMIZATION

  • Page 1 Customization Guide Netscape Certificate Management System Version 6.01 May 2002...
  • Page 2 Netscape Communications Corporation ("Netscape") and its licensors retain all ownership rights to the software programs offered by Netscape (referred to herein as "Software") and related documentation. Use of the Software and related documentation is governed by the license agreement for the Software and applicable copyright law. Your right to copy this documentation is limited by copyright law.

  • Page 3: Table Of Contents

    Contents About This Guide ............. . 11 What’s in This Guide .
  • Page 4 Locating End-Entity Forms and Templates ..........34 Forms for Certificate Enrollment .
  • Page 5 Request Parameters ..............66 Response .
  • Page 6 Part 2 Customizing Agent Services Interface ........99 Chapter 5 Introduction to Agent Services Interface .
  • Page 7 Description ............... . 131 Default Forms .
  • Page 8 Response ................154 Process Certificate Request Interface .
  • Page 9 Default Forms ..............185 Request Parameters .
  • Page 10 Netscape Certificate Management System Customization Guide • May 2002...

  • Page 11: About This Guide

    About This Guide The Customization Guide provides reference information about the HTTP interface of Netscape Certificate Management System (CMS). The information helps you customize Certificate Management System, and use it for issuing and managing certificates to various end entities, such as web browsers (users), servers, Virtual Private Network (VPN) clients, and Cisco™...

  • Page 12: Conventions Used In This Guide

    Conventions Used in This Guide This guide assumes that you • Are familiar with the basic concepts of public-key cryptography and the Secure Sockets Layer (SSL) protocol. SSL cipher suites The purpose of and major steps in the SSL handshake •...
  • Page 13 Conventions Used in This Guide Example: This control depends on the access permissions the superadministrator has set up for you. • Text within “quotation marks”—Cross-references to other topics within this guide. Example: For more information, see “Issuing a Certificate to a New User” on page 154.

  • Page 14: Where To Go For Related Information

    Where to Go for Related Information NOTE You can use Netscape Console only when Netscape Administration Server is up and running. CAUTION A caution note documents a potential risk of losing data, damaging software or hardware, or otherwise disrupting system performance. Where to Go for Related Information This section summarizes the documentation that ships with Certificate Management System, using these conventions:...
  • Page 15 Where to Go for Related Information • CMS Command-Line Tools Guide Provides detailed reference information on CMS tools. To view the HTML version of this guide, open this file: <server_root>/manual/en/cert/tools_guide/contents.htm • CMS Customization Guide (this guide) Provides detailed reference information on customizing the end-entity and agent interfaces.
  • Page 16 Where to Go for Related Information Netscape Certificate Management System Customization Guide • May 2002...

  • Page 17: Chapter 1 Before You Begin

    Chapter 1 Before You Begin The services interfaces that come with Netscape Certificate Management System (CMS) make it possible for end-entities and agents to interact with the server. Your end-entities and agents can use the interface’s HTML-based forms to carry out various certificate and key-related operations, such as enrolling for, renewing, and revoking certificates.

  • Page 18: Http, Query Urls, And Html Forms

    How the Forms Work HTTP, Query URLs, and HTML Forms Requests from the end-entity services interface to Certificate Management System are submitted using the HTTP methods. Requests take the form of POST query URLs (in the case of the method) or data sent through standard output (in the case of the method).

  • Page 19: Requests Sent To The Cms Server

    How the Forms Work where designates the certificate (management) service portion, such as operation enrollment, retrieval, renewal, or revocation of the CMS server. Any HTTP operations with URIs that do not begin with the prefix are treated as /<operation> requests for other kinds of web service by the CMS server. See chapters Chapter 3, “End-Entity Interface Reference”...
  • Page 20 How the Forms Work The fragment of JavaScript code consists of a object that contains data result properties only (no methods). The properties of the object correspond to parts of the response. The template generally contains a combination of HTML and JavaScript code that processes and displays data.

  • Page 21: Errors And The Error Template

    How the Forms Work result.header = header; result.fixed = fixed; result.recordSet = recordSet; </SCRIPT> Notice how this code fragment defines an object named and puts the result resulting data from the operation in the properties of that object. Each certificate service operation returns an object named .

  • Page 22: Javascript Used By All Interfaces

    JavaScript Used By All Interfaces <SCRIPT LANGUAGE="JavaScript"> var header = new Object(); var result = new Object(); header.errorDetails = [a string describing the context of the error] header.errorDescription = [a string describing the error] result.header = header; </SCRIPT> The default CMS error template prints the information in the object error result along with some explanatory text.
  • Page 23 JavaScript Used By All Interfaces fixed.preserved = "foo"; var recordCount = 0; var record; record = new Object; record.HTTP_PARAMS = new Array; record.HTTP_HEADERS = new Array; record.AUTH_TOKEN = new Array; record.SERVER_ATTRS = new Array; recordSet[recordCount++] = record; result.header = header; result.fixed = fixed;...
  • Page 24 JavaScript Used By All Interfaces Table 1-1 Variables Returned by the Base JavaScript Variable Format/Type and Description array AUTH_TOKEN Each element in this array is a name-value pair. These pairs represent variables that were returned from an authentication plug-in used (internally) by the interface.
  • Page 25 JavaScript Used By All Interfaces Variables Returned by the Base JavaScript (Continued) Table 1-1 Variable Format/Type and Description number httpHeadersCount The number of HTTP_HEADERS objects returned in this response. Array HTTP_PARAMS Each element in this array is a name-value pair. These pairs represent variables and their values that were used in the HTTP request made to the interface.

  • Page 26: How To Register Servlets

    How to Register Servlets Variables Returned by the Base JavaScript (Continued) Table 1-1 Variable Format/Type and Description number recordCount The number of record objects returned in this response. Usually this is incremented for each record added to the recordSet array. For example, recordCount = 0;...

  • Page 27: Part 1 Customizing End-Entity Services Interface

    Part 1 Customizing End-Entity Services Interface Chapter 2, “Introduction to End-Entity Services Interface” Chapter 3, “End-Entity Interface Reference” Chapter 4, “Internationalization of End-Entity Interface...
  • Page 28 Netscape Certificate Management System Customization Guide • May 2002...

  • Page 29: Chapter 2 Introduction To End-Entity Services Interface

    Chapter 2 Introduction to End-Entity Services Interface The services interfaces that come with Netscape Certificate Management System (CMS) make it possible for end-entities to interact with the server. Your end-entities can use the interface’s HTML-based forms to carry out various certificate and key-related operations, such as enrolling for, renewing, and revoking certificates.
  • Page 30 End-Entity Services Interface Communicator versions earlier than 4.5 present an enrollment form based on the use of the HTML tag to generate keys; end entities running Internet KEYGEN Explorer present a form based on PKCS #10, the RSA standard for certificate request syntax.

  • Page 31: How Client Type Determines The End-Entity Interface

    End-Entity Services Interface For a complete list of the end-entity forms—for enrollment, renewal, retrieval, revocation, and key recovery—that come with Certificate Management System, see “End-Entity Forms and Templates” on page 33. How Client Type Determines the End-Entity Interface Each type of end-entity form provided by Certificate Management System is served by a servlet.

  • Page 32: Certificate Request Formats Specific To End Entities

    End-Entity Services Interface Certificate Request Formats Specific to End Entities Table 2-1 lists the forms provided by the Certificate Manager and Registration Manager for certificate issuance and life-cycle management operations, and indicates supported authentication mechanisms and request formats. You can customize any of the default forms and their corresponding servlets and output templates.

  • Page 33: Accessing The End-Entity Services Interface

    Accessing the End-Entity Services Interface Summary of end-entity forms, authentication methods and certificate request formats Table 2-1 Form for end-entity operation Authentication method Supported certificate request formats Client (end user) certificates Not applicable • Not supported for clients that can’t generate dual key pairs •...

  • Page 34: Locating End-Entity Forms And Templates

    End-Entity Forms and Templates Locating End-Entity Forms and Templates You can find the HTML forms and the corresponding output templates for the end-entity interface at this location: <server_root>/cert-<instance_id>/web-apps/ee Forms for Certificate Enrollment Table 2-2 lists the file names of forms that appear as menu options in the Enrollment tab of the end-entity interface.

  • Page 35: Forms For Certificate Renewal

    End-Entity Forms and Templates Forms for end-entity enrollment (Continued) Table 2-2 Form Type: Menu Link and Filename What form is used for... Server Enrollment (lists menu options for server enrollment) SSL Server Server administrators can use this form to request SSL (ManServerEnroll.html) server certificates for servers.

  • Page 36: Forms For Certificate Revocation

    End-Entity Forms and Templates Forms for Certificate Revocation Table 2-4 lists the forms that correspond to the menu options in the Revocation tab of the end-entity services interface. Table 2-4 Forms for certificate revocation Menu Link and Filename What form is used for... Certificate (challenge phrase-based) End users can use this form to revoke their SSL client certificates (ChallengeRevoke1.html)

  • Page 37: Forms For Key Recovery

    End-Entity Forms and Templates Forms provided for certificate retrieval (Continued) Table 2-5 Menu Link and Filename What form is used for... Import CA Certificate Chain End users and administrators can use this form to import the (GetCAChain.html) certificate chain of a Certificate Manager (CA) into their browsers or servers.

  • Page 38: Output Templates For End-Entity Interfaces

    End-Entity Forms and Templates Table 2-7 Files and forms used by other forms Form filename What form is used for... This file loads and highlights the Enrollment tab. enrollMenu.html This file loads and highlights the Renewal tab. renewalMenu.html This file loads and highlights the Recovery tab. recoveryMenu.html This file loads and highlights the Retrieval tab.
  • Page 39 End-Entity Forms and Templates Response templates used by the end-entity interface (Continued) Table 2-8 Template filename Description Used to inform a user requesting a certificate that the request GenSvcPending.template has been queued for agent approval. Used to inform users when they perform unauthorized GenUnauthorized.template operations.
  • Page 40 End-Entity Forms and Templates Netscape Certificate Management System Customization Guide • May 2002...

  • Page 41: Chapter 3 End-Entity Interface Reference

    Chapter 3 End-Entity Interface Reference This chapter provides a detailed reference of all the service interfaces available on an end-entity port of Netscape 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.

  • Page 42: Overview Of End-Entity Interfaces

    Overview of End-Entity Interfaces 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. Overview of End-Entity Interfaces Table 3-1 Interface Purpose Approve Revocation Revokes a certificate of group of certificates /doRevoke Interface for a given reason.

  • Page 43: Approve Revocation Interface

    Approve Revocation Interface Overview of End-Entity Interfaces (Continued) Table 3-1 Interface Purpose Renewal Interface Process requests for renewing a certificate /renewal presented to the interface using SSL client authentication. Revocation Interface Process requests for manual revocation or /revocation for revocation of a certificate presented to the interface using SSL client authentication.
  • Page 44 Approve Revocation Interface Table 3-2 Parameters Accepted by the Approve Revocation Interface Parameter Format and Description base-64 encoded certificate data b64eCertificate Allows you to specify the certificate to revoke by posting its base-64 encoding to the interface. string csrRequestorComments A comment field to provide more details about why the certificates are being revoked.

  • Page 45: Response

    Approve Revocation Interface Parameters Accepted by the Approve Revocation Interface (Continued) Table 3-2 Parameter Format and Description QUERY_FILTER revokeAll For information on constructing a query filter, see Table 3-19 in the section for “List Certificates Interface” on page 78. To ensure accuracy when revoking certificates, you should use a query filter that selects each certificate by its serial number.
  • Page 46 Approve Revocation Interface Table 3-3 Variables Returned by the Approve Revocation Interface Variable Description Variables added to the header object. result.header variables number certsUpdated Contains the number of certificates that were revoked from the publishing directory, if publishing is enabled (dirEnabled = yes). yes | no dirEnabled Indicates whether LDAP publishing is enabled on the Certificate Manager that...

  • Page 47: Certificate Enrollment Protocol Interface

    Certificate Enrollment Protocol Interface Variables Returned by the Approve Revocation Interface (Continued) Table 3-3 Variable Description number serialNumber The decimal serial number of the certificate. 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.

  • Page 48: Challenge Revocation Interface

    Challenge Revocation Interface > enrollment url https://example:443/ > crypto ca enroll Example The router uses the CEP protocol and expects to find the interface at the URL named by the /cgi-bin/pkiclient.exe enrollment url command. The details of interacting with the interface are handled by the protocol itself.
  • Page 49 Challenge Revocation Interface Table 3-4 Parameters Accepted by the Challenge Revocation Interface Parameter Format and Description number (decimal or hexadecimal) certSerialToRevoke The serial number of the certificate to revoke. Either this parameter or subjectName are required. string challengePhrase The challenge phrase, set during certificate enrollment, that allows the certificate to be revoked.

  • Page 50: Response

    Display Certificate By Serial Number Interface 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” on page 89 for details on what JavaScript variables are returned in the response template.

  • Page 51: Response

    Display Certificate By Serial Number Interface Table 3-5 Parameters Accepted by the Display Certificate By Serial Number Interface Parameter Format and Description displayBySerial Specifies the operation to perform. The only valid value is displayBySerial. number serialNumber The serial number of the certificate to display. string templateName Filename relative to the template directory (web-apps/ee/ca,...

  • Page 52: Display Certificate From Request Interface

    Display Certificate From Request Interface Variables Returned by the Display Certificate By Serial Number Interface (Continued) Table 3-6 Variable Description string certPrettyPrint 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. number serialNumber The serial number of the certificate in decimal.

  • Page 53: Request Parameters

    Display Certificate From Request Interface Request Parameters The following table lists the parameters accepted by the Display Certificate From Request interface. Table 3-7 Parameters Accepted by the Display Certificate From Request Interface Parameter Format and Description number requestId The requestID returned in the JavaScript by the Enrollment or Renewal interface (fixed.requestID).
  • Page 54 Display Certificate From Request Interface Variables Returned by the Display Certificate From Request Interface (Continued) Table 3-8 Variable Description string errorDetails 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.

  • Page 55: Enrollment Interface

    Enrollment Interface Variables Returned by the Display Certificate From Request Interface (Continued) Table 3-8 Variable Description string certFingerprint 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.

  • Page 56: Default Forms

    Enrollment Interface NOTE The forms rely on a shared library called (downloaded xenroll.dll 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.

  • Page 57: Request Parameters

    Enrollment Interface Request Parameters The following table lists the parameters accepted by the enrollment interface. Table 3-9 Parameters Accepted by the Enrollment Interface Parameter Format and Description Subject Name Distinguished Name (DN) string. See RFC 2253. subject DN to be used for the certificate subject. Example: CN=Alice Apple, UID=alice, OU=People, O=Example Corporation, C=US Contact Information...
  • Page 58 Enrollment Interface Parameters Accepted by the Enrollment Interface (Continued) Table 3-9 Parameter Format and Description true | false object_signing Sets the object signing certificate bit (bit 3). true | false object_signing_ca Sets the object signing certificate issuer bit (bit 7). true | false ssl_ca Sets the SSL certificate issuer bit (bit 5).
  • Page 59 Enrollment Interface Parameters Accepted by the Enrollment Interface (Continued) Table 3-9 Parameter Format and Description true | false key_agreement Sets the keyUsage extension bit (4) indicating that the key may be used to encipher and decipher keys during key agreement. true | false key_certsign Sets the keyUsage extension bit (5) indicating that the key may be used to sign...
  • Page 60 Enrollment Interface Parameters Accepted by the Enrollment Interface (Continued) Table 3-9 Parameter Format and Description ca | CEP-Request | client | objSignClient | ra | server | other certType Specifies the type of certificate requested by the entity. The default is client. The certType is not associated with any certificate extensions.

  • Page 61: Response

    Enrollment Interface Parameters Accepted by the Enrollment Interface (Continued) Table 3-9 Parameter Format and Description clientAuth | crmf | keygen | pkcs10 requestFormat 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.
  • Page 62 Enrollment Interface Table 3-10 Enrollment Interface Response Templates Template File Name Request Status Description 2 (Success) Used only for requests that specify an authenticator. EnrollSuccess.template If authentication and subsequent policy processing are successful and importCert was "true" in the request, a certificate is generated (otherwise, see GenRejected.template).
  • Page 63 Enrollment Interface Table 3-11 Variables Returned by the Enrollment Interface (Continued) Variable Description Certificate Manager | Registration Manager authorityName The name of the system that handled the request. ca | CEP-Request | client | objSignClient | ra | server | other certType The type of certificate returned.
  • Page 64 Enrollment Interface Table 3-11 Variables Returned by the Enrollment Interface (Continued) Variable Description number requestStatus 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.

  • Page 65: Get Ca Chain Interface

    Get CA Chain Interface Table 3-11 Variables Returned by the Enrollment Interface (Continued) Variable Description string base64Cert The newly issued certificate in base-64 encoded format. This string includes the "-----BEGIN CERTIFICATE-----" header and "-----END CERTIFICATE-----" footer. string certFingerprint A string of hexadecimal numbers separated by colons that represent the certificate fingerprints.

  • Page 66: Default Forms

    Get CA Chain Interface 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: .

  • Page 67: Response

    Get Certificate By Serial Number Interface Table 3-12 Parameters Accepted by the Get CA Chain Interface (Continued) Parameter Format and Description display | displayIND | download | downloadBIN This required parameter specifies how the CA certificate chain should be returned: •...

  • Page 68: Default Forms

    Get Certificate By Serial Number Interface 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 to download and import the newly issued certificate. RenewalSuccess.template also uses this interface to create “Import displayBySerial.template...

  • Page 69: Response

    Get Certificate By Serial Number Interface Table 3-13 Parameters Accepted by the Get Certificate By Serial Number Interface (Continued) Parameter Format and Description number serialNumber The serial number of the certificate to retrieve. string templateName Filename relative to the template directory (web-apps/ee/ca, web-apps/agent/ca, web-apps/agent/kra, or web-apps/agent/ra) of a file to use as the response template.
  • Page 70 Get Certificate By Serial Number Interface Table 3-14 Variables Returned by the Get Certificate By Serial Number Interface (Continued) Variable Description base-64 encoded data cmmfResponse The CMMF response data containing the certificate (if cmmfResponse was true in the request). If the browser supports the Netscape 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,...

  • Page 71: Get Certificate From Request Interface

    Get Certificate From Request Interface Table 3-14 Variables Returned by the Get Certificate By Serial Number Interface (Continued) Variable Description string base64Cert The newly issued certificate in base-64 encoded format. This string includes the "-----BEGIN CERTIFICATE-----" header and "-----END CERTIFICATE-----" footer. string certFingerprint A string of hexadecimal numbers separated by colons that represent the...

  • Page 72: Default Forms

    Get Certificate From Request Interface parameter from the response template is required: it identifies the requestID 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: (for browsers that support CMMF).

  • Page 73: Response

    Get Certificate From Request Interface Table 3-15 Parameters Accepted by the Get Certificate From Request Interface (Continued) Parameter Format and Description number requestId The requestID returned in the JavaScript by the Enrollment or Renewal interface (fixed.requestID). string templateName Filename relative to the template directory (web-apps/ee/ca, web-apps/ee/ra, web-apps/agent/ca, web-apps/agent/kra, or web-apps/agent/ra) of a file to use as the response template.
  • Page 74 Get Certificate From Request Interface Table 3-16 Variables Returned by the Get Certificate From Request Interface (Continued) Variable Description base-64 encoded data cmmfResponse The CMMF response data containing the certificate (if cmmfResponse was true in the request). If the browser supports the Netscape 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,...

  • Page 75: Get Crl Interface

    Get CRL Interface Table 3-16 Variables Returned by the Get Certificate From Request Interface (Continued) Variable Description true | false noCertImport Indicates whether the certificate should not be imported. number requestId The request identification number that was requested. result.recordSet[i] Variables added to each record object. Each record object is added as an element of the recordSet array.

  • Page 76: Default Forms

    Get CRL Interface 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.

  • Page 77: Response

    Get CRL Interface Table 3-17 Parameters Accepted by the Get CRL Interface (Continued) Parameter Format and Description 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.

  • Page 78: List Certificates Interface

    List Certificates Interface Table 3-18 Variables Returned by the Get CRL Interface (Continued) Variable Description base-64 encoded data crlBase64 The base-64 encoded CRL data in PKCS #7 format. string crlPrettyPrint Contains the CRL formatted for human-readable display if op=displayCRL in the request.

  • Page 79: Default Forms

    List Certificates Interface Default Forms The List Certificates interface uses two default forms: • is a simple form that accepts a lower and upper bound queryBySerial.html for the range of serial numbers and the option to skip revoked or invalid certificates.
  • Page 80 List Certificates Interface Table 3-19 Parameters Accepted by the List Certificates Interface (Continued) Parameter Format and Description 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: •...
  • Page 81 List Certificates Interface 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 >= ) accept the asterisk ( ) as a wildcard to match 0 or more...
  • Page 82 List Certificates Interface Table 3-20 List Certificates queryCertFilter Parameters (Continued) Parameter Expression Values Value: * | EXPIRED | INVALID | REVOKED | VALID | certStatus REVOKED_EXPIRED This parameter matches the current status of a certificate. The asterisk (*) matches any status. Value: * | number between 0 and 6 x509cert.certRevoInfo This parameter matches the reason for revocation code on a certificate.
  • Page 83 List Certificates Interface Table 3-20 List Certificates queryCertFilter Parameters (Continued) Parameter Expression Values Value: date (number of seconds since Jan 1, 1970) x509cert.notAfter 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 Value: date (number of seconds since Jan 1, 1970) x509cert.notBefore...

  • Page 84: Response

    List Certificates Interface Table 3-20 List Certificates queryCertFilter Parameters (Continued) Parameter Expression Values Value: a pattern that may include the wildcard (*) x509cert.subject 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>*.
  • Page 85 List Certificates Interface Table 3-21 Variables Returned by the List Certificates Interface (Continued) Variable Description 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. The queryCertFilter parameter that was used to generate the current list of queryCertFilter certificates, and will be used for subsequent pages if the user requests to see...
  • Page 86 List Certificates Interface Table 3-21 Variables Returned by the List Certificates Interface (Continued) Variable Description If the certificate has been revoked, this field contains the code for the reason. revocationReason The revocation codes are: • 0 - Reason not specified •...

  • Page 87: Online Certificate Status Protocol Interface

    Online Certificate Status Protocol Interface Online Certificate Status Protocol Interface Description URI: /ocsp Available on: Online Certificate Status Manager Function: Serves the OCSP requests to the Online Certificate Status Manager The Online Certificate Status Protocol interface provides a means to query the Online Certificate Status Manager about the status of a certificate.

  • Page 88: Renewal Interface

    Renewal Interface • Unknown—indicates the OCSP responder cannot determine the certificate status. 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.

  • Page 89: Response

    Revocation Interface Table 3-22 Parameters Accepted by the Renewal Interface (Continued) Parameter Format and Description requestFormat clientAuth Only client certificate renewals are supported through the Renewal interface. string templateName Filename relative to the template directory (web-apps/ee/ca, web-apps/ee/ra, web-apps/agent/ca, web-apps/agent/kra, or web-apps/agent/ra) of a file to use as the response template.

  • Page 90: Default Forms

    Revocation Interface 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).
  • Page 91 Revocation Interface Table 3-23 Parameters Accepted by the Revocation Interface (Continued) Parameter Format and Description on | off doSslAuth 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.

  • Page 92: Response

    Revocation Interface Table 3-23 Parameters Accepted by the Revocation Interface (Continued) Parameter Format and Description string templateName Filename relative to the template directory (web-apps/ee/ca, web-apps/ee/ra, web-apps/agent/ca, web-apps/agent/kra, or web-apps/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.
  • Page 93 Revocation Interface Table 3-24 Variables Returned by the Revocation Interface (Continued) Variable Description A text message indicating why the revocation request itself could not be error processed. The result.header.error message will exist only when result.header.revoked = no. yes | pending | no revoked This field indicates the overall status of the revocation request.
  • Page 94 Revocation Interface Netscape Certificate Management System Customization Guide • May 2002...

  • Page 95: Chapter 4 Internationalization Of End-Entity Interface

    Chapter 4 Internationalization of End-Entity Interface The services interfaces that come with Netscape Certificate Management System (CMS) make it possible for end-entities and agents to interact with the server. Your end-entities and agents can use the interface’s HTML-based forms to carry out various certificate and key-related operations, such as enrolling for, renewing, and revoking certificates.
  • Page 96 Displaying Forms in Non-English Languages directory where the default form would be stored to see if there is a directory matching the first value in the header. If there is such a Accept-language directory, Certificate Management System looks for the correct form or template in the language-specific directory;...
  • Page 97 Displaying Forms in Non-English Languages Table 4-1 Languages and Default Character Sets Language Code Character set Language Code Character set Albanian ISO-8859-2 Arabic ISO-8859-6 Bulgarian ISO-8859-5 Byelorussian ISO-8859-5 Catalan (Spanish) ISO-8859-1 Chinese GB2312 (Simplified/Mainland) Chinese Big5 Croatian ISO-8859-2 (Traditional/Taiwan) Czech ISO-8859-2 Danish ISO-8859-1...
  • Page 98 Displaying Forms in Non-English Languages Netscape Certificate Management System Customization Guide • May 2002...

  • Page 99: Part 2 Customizing Agent Services Interface

    Part 2 Customizing Agent Services Interface Chapter 5, “Introduction to Agent Services Interface” Chapter 6, “Agent Interface Reference”...
  • Page 100 Netscape Certificate Management System Customization Guide • May 2002...

  • Page 101: Chapter 5 Introduction To Agent Services Interface

    Chapter 5 Introduction to Agent Services Interface Netscape Certificate Management System (CMS) provides HTML forms-based interfaces for agents to use in performing certificate- and key-related operations. This chapter introduces these forms and explains how they work. You can use the forms as they are provided out of the box or customize them to meet your organization’s requirements.

  • Page 102: Certificate Manager Agent Services

    Agent Services Interface • Online Certificate Status Manager Agent Services This section gives an overview of these forms and explains how to access them. For a complete list of the agent forms and output templates that come with Certificate Management System, see “Agent Forms and Templates” on page 106. For step-by-step instructions on using the agent forms, see CMS Agent’s Guide.

  • Page 103: Registration Manager Agent Services

    Agent Services Interface • Listing deferred certificate requests from end entities and process them • Listing certificates issued by the server • Searching for certificates issued by the server • Revoking certificates issued by the server • Updating certificates and certificate revocation lists (CRLs) maintained in the publishing directory Registration Manager Agent Services The Registration Manager Agent Services interface enables a Registration Manager...

  • Page 104: Data Recovery Manager Agent Services

    Agent Services Interface Data Recovery Manager Agent Services The Data Recovery Manager Agent Services interface enables a Data Recovery Manager agent to interact with the Data Recovery Manager (the server). Figure 5-3 shows the Data Recovery Manager Agent Services interface. Figure 5-3 Data Recovery Manager Agent Services interface Using the default forms, a Data Recovery Manager agent can search for and...

  • Page 105: Accessing The Agent Services Interface

    Accessing the Agent Services Interface Online Certificate Status Manager Agent Services interface Figure 5-4 Using the default forms, an OCSM agent can accomplish these tasks: • List Certificate Authorities (CAs) that have been added by an agent. • Add a new CA requested by an agent •...

  • Page 106: Agent Forms And Templates

    Agent Forms and Templates is in the form: <hostname> <machine_name>.<your_domain>.<domain> If you have customized Certificate Management System, go to the page containing the agent forms that you would use to submit a request. In the Agent Services menu, choose the agent services you require: To access the agent services for the Certificate Manager, click the Certificate Manager Agent Services link.

  • Page 107: Locating Agent Forms And Templates

    Agent Forms and Templates Various parts of the Agent Services interface Figure 5-5 Locating Agent Forms and Templates You can find the HTML forms specific to agent operations and the corresponding output templates at this location: <server_root>/cert-<instance_id>/web-apps/agent/<subsystem> is the directory where the CMS binaries are kept, as specified <server_root>...
  • Page 108 Agent Forms and Templates Netscape Certificate Management System Customization Guide • May 2002...

  • Page 109: Chapter 6 Agent Interface Reference

    Chapter 6 Agent Interface Reference This chapter provides a detailed reference of all the service interfaces available on an agent port of Netscape 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.

  • Page 110: Overview Of Agent Interfaces

    Overview of Agent Interfaces • Process Certificate Request Interface (page 155) • Process DRM Request Interface (page 163) • Process Request Interface (page 167) • Recover Key By Serial Number Interface (page 169) • Remove Certificate Hold Interface (page 172) •...
  • Page 111 Overview of Agent Interfaces Agent Interfaces (Continued) Table 6-1 Interface Purpose Check Certificate Checks the revocation status of a /ocsp/checkCert Interface certificate. Display Key By Serial Display information about an /kra/displayBySerial Number Interface archived key. Display Key For Recovery Display a form for recovering a /kra/displayBySerialForRecovery Interface key.

  • Page 112: Add Ca Interface

    Add CA Interface Agent Interfaces (Continued) Table 6-1 Interface Purpose Requests Query Interface View requests that match certain /ca/queryReq criteria (such as request type or /ra/queryReq status). /kra/queryReq Select for Revocation Revoke a set of certificates for a /ca/reasonToRevoke Interface given reason.

  • Page 113: Request Parameters

    Add CRL Interface Request Parameters The following table lists the parameter accepted by the Add Certificate Authority interface. This is an agent interface, so the HTTP POST or GET request must use SSL client authentication with a valid agent certificate. Add CA Table 6-2 Parameters Accepted by the...

  • Page 114: Default Forms

    Add CRL Interface Default Forms The form , available in the OCSP agent directory, uses the Add CRL addCRL.html Interface. The form allows the agent to add a CRL. Request Parameters The following table lists the parameters accepted by the Add CRL interface. This is an agent interface, so the HTTP POST or GET request must use SSL client authentication with a valid agent CRL.

  • Page 115: Approve Revocation Interface

    Approve Revocation Interface Approve Revocation Interface Description URI: /ca/doRevoke /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.
  • Page 116 Approve Revocation Interface Parameters Accepted by the Approve Revocation Interface (Continued) Table 6-4 Parameter Format and Description string csrRequestorComments A comment field to provide more details about why the certificates are being revoked. number of seconds since 1 January 1970 invalidityDate The time when the certificates became invalid.

  • Page 117: Response

    Approve Revocation Interface Parameters Accepted by the Approve Revocation Interface (Continued) Table 6-4 Parameter Format and Description string templateName Filename relative to the template directory (web-apps/ee/ca, web-apps/ee/ra, web-apps/agent/ca, web-apps/agent/kra, or web-apps/agent/ra) of a file to use as the response template. This template will be used for any response, overriding default template settings.
  • Page 118 Approve Revocation Interface Variables Returned by the Approve Revocation Interface (Continued) Table 6-5 Variable Description message error If there was an error while processing the revocation request, the error message is stored in this variable. Otherwise, the value is null. yes | pending revoked Indicates whether or not all certificates were successfully revoked.

  • Page 119: Bulk Enrollment Interface

    Bulk Enrollment Interface 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.
  • Page 120 Bulk Enrollment Interface Table 6-6 Bulk Enrollment Interface Configuration File Parameters Parameter Format and Description true | false enableBulkInterface Enables or disables the servlet handling bulk enrollment at /ca/bulkissuance. filename errorTemplate The template file to use when the response requestStatus = 6, meaning an error occurred while processing the request.

  • Page 121: Default Forms

    Bulk Enrollment Interface 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.
  • Page 122 Bulk Enrollment Interface Parameters Accepted by the Bulk Enrollment Interface (Continued) Table 6-7 Parameter Format and Description Netscape Certificate Parameters for setting bits in the netscape-cert-type certificate extension. See http://home.netscape.com/eng/security/comm4-cert-exts.html for details. Type Extensions A true value sets the bit to 1; false sets the bit to 0. true | false email Sets the S/MIME client certificate bit (bit 2).
  • Page 123 Bulk Enrollment Interface Parameters Accepted by the Bulk Enrollment Interface (Continued) Table 6-7 Parameter Format and Description true | false digital_signature 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.
  • Page 124 Bulk Enrollment Interface Parameters Accepted by the Bulk Enrollment Interface (Continued) Table 6-7 Parameter Format and Description string Specifies the password passed to the authentication plug-in. Other string certNickname Specifies the nickname that should be associated with the certificate in the reply;...
  • Page 125 Bulk Enrollment Interface Parameters Accepted by the Bulk Enrollment Interface (Continued) Table 6-7 Parameter Format and Description MIME Type string importCertMimeType 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>.

  • Page 126: Response

    Bulk Enrollment Interface Response If the request parameter is set to and the certificate request is importCert true successful, the Certificate Manager will return the binary PKCS #7 certificate chain using the MIME type . This is the most useful application/x-x509-user-cert application of the Bulk Enrollment interface.
  • Page 127 Bulk Enrollment Interface Table 6-8 Variables Returned by the Bulk Enrollment Interface Variable Description result.fixed variables Variables added to the fixed object. Certificate Manager | Registration Manager authorityName The name of the system that handled the request. ca | CEP-Request | client | objSignClient | ra | server | other certType The type of certificate returned.
  • Page 128 Bulk Enrollment Interface Variables Returned by the Bulk Enrollment Interface (Continued) Table 6-8 Variable Description number requestStatus 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.

  • Page 129: Check Certificate Interface

    Check Certificate Interface Variables Returned by the Bulk Enrollment Interface (Continued) Table 6-8 Variable Description string base64Cert The newly issued certificate in base-64 encoded format. This string includes the "-----BEGIN CERTIFICATE-----" header and "-----END CERTIFICATE-----" footer. string certFingerprint A string of hexadecimal numbers separated by colons that represent the certificate fingerprints.

  • Page 130: Default Forms

    Check Certificate Interface Default Forms The form , available in the OCSP agent directory, uses the Check checkCert.html Certificate interface. The form allows the agent to confirm the status of a certificate. Request Parameters The following table lists the parameters accepted by the Check Certificate interface. This is an agent interface, so the HTTP POST or GET request must use SSL client authentication with a valid agent certificate.

  • Page 131: Display Key By Serial Number Interface

    Display Key By Serial Number Interface 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.

  • Page 132: Response

    Display Key By Serial Number Interface Table 6-11 Parameters Accepted by the Display Key By Serial Number Interface (Continued) Parameter Format and Description string templateName Filename relative to the template directory (web-apps/ee/ca, web-apps/ee/ra, web-apps/agent/ca, web-apps/agent/kra, or web-apps/agent/ra) of a file to use as the response template. This template will be used for any response, overriding default template settings.

  • Page 133: Display Key For Recovery Interface

    Display Key For Recovery Interface Table 6-12 Variables Returned by the Display Key By Serial Number Interface (Continued) Variable Description Distinguished Name (DN) string. See RFC 2253. ownerName 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 Corporation, C=US string...

  • Page 134: Default Forms

    Display Key For Recovery Interface Default Forms The Display Key For Recovery interface is used in the file. Each key in the list of keys satisfying the queryKeyForRecovery.template query has a button the user can press to start the recovery process. This button submits data to the Display Key For Recovery interface.
  • Page 135 Display Key For Recovery Interface Table 6-14 Variables Returned by the Display Key For Recovery Interface Variable Description result.header variables Variables added to the header object. user ID archivedBy The user ID of the agent that processed the key archival request. number of seconds since 1 January 1970 archivedOn The time when the key was stored in the archive (for completed Data Recovery...

  • Page 136: Examine Recovery Interface

    Examine Recovery Interface Table 6-14 Variables Returned by the Display Key For Recovery Interface (Continued) Variable Description VALID | INVALID state 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.

  • Page 137: Response

    Examine Recovery Interface Table 6-15 Parameters Accepted by the Examine Recovery Interface Parameter Format and Description examineRecovery The only operation supported by the Examine Recovery interface is examineRecovery. number recoveryID The unique identification number assigned to the recovery request. string templateName Filename relative to the template directory (web-apps/ee/ca, web-apps/ee/ra, web-apps/agent/ca, web-apps/agent/kra, or...

  • Page 138: Get Approval Status Interface

    Get Approval Status Interface Table 6-16 Variables Returned by the Examine Recovery Interface (Continued) Variable Description number serialNumber 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:...

  • Page 139: Request Parameters

    Get Approval Status Interface Request Parameters The following table lists the parameters accepted by the Get Approval Status interface. Table 6-17 Parameters Accepted by the Get Approval Status Interface Parameter Format and Description number recoveryID The unique identification number assigned to the recovery request. string templateName Filename relative to the template directory (web-apps/ee/ca,...

  • Page 140: Get Pkcs #12 Data Interface

    Get PKCS #12 Data Interface Table 6-18 Variables Returned by the Get Approval Status Interface (Continued) Variable Description number noOfRequiredAgents 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.

  • Page 141: Default Forms

    Get PKCS #12 Data Interface Default Forms No default forms use the Get PKCS #12 Data interface. The , and finishRecovery.template getApprovalStatus.template files all embed links to the Get PKCS #12 Data recoverBySerial.template interface that are displayed if the recovery has been granted (if result.header.status = "complete"...

  • Page 142: Grant Recovery Interface

    Grant Recovery Interface 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.

  • Page 143: Response

    Grant Recovery Interface Table 6-20 Parameters Accepted by the Grant Recovery Interface (Continued) Parameter Format and Description grantRecovery The only operation supported by the Grant Recovery interface is grantRecovery. number recoveryID The unique identification number assigned to the recovery request. string templateName Filename relative to the template directory (web-apps/ee/ca,...

  • Page 144: Key Query Interface

    Key Query 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.
  • Page 145 Key Query Interface Table 6-22 Parameters Accepted by the Key Query Interface Parameter Format and Description number maxCount 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.
  • Page 146 Key Query Interface Table 6-22 Parameters Accepted by the Key Query Interface (Continued) Parameter Format and Description number totalRecordCount 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.

  • Page 147: Response

    Key Query Interface Table 6-23 Key Query queryFilter Parameters (Continued) Parameter Expression Values Value: distinguished name appearing as the subject of the certificate keyOwnerName corresponding to the key. This parameter matches the DN (taken from the certificate) stored with the key during archival.
  • Page 148 Key Query Interface Table 6-24 Variables Returned by the Key Query Interface (Continued) Variable Description query string queryFilter Contains the query string that was used to select keys from the archive. See the previous section, “Request Parameters” on page 144, for details on how queryFilter is constructed.

  • Page 149: Key Recovery Query Interface

    Key Recovery Query Interface Table 6-24 Variables Returned by the Key Query Interface (Continued) Variable Description number keyLength The number of bits in the archived key (Data Recovery Manager requests). Distinguished Name (DN) string. See RFC 2253. ownerName The subject entry on the certificate corresponding to an archived encryption key (Data Recovery Manager requests only).

  • Page 150: Default Forms

    Key Recovery Query Interface 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 uses the Key Recovery Query...
  • Page 151 Key Recovery Query Interface Table 6-25 Parameters Accepted by the Key Recovery Query Interface (Continued) Parameter Format and Description 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: •...

  • Page 152: Response

    Key Recovery Query Interface Response The default response template is . The base queryKeyForRecovery.template JavaScript for responses is inserted in place of the tag. In <CMS_TEMPLATE> addition, the Key Recovery Query interface adds the JavaScript variables listed in the following table. Table 6-26 Variables Returned by the Key Recovery Query Interface Variable Description...
  • Page 153 Key Recovery Query Interface Table 6-26 Variables Returned by the Key Recovery Query Interface (Continued) Variable Description result.recordSet[i] Variables added to record objects in the response. variables user ID archivedBy The user ID of the agent that processed the key archival request. number of seconds since 1 January 1970 archivedOn The time when the key was stored in the archive (for completed Data Recovery...

  • Page 154: List Ca Interface

    List CA Interface List CA Interface Description URI: /ocsp/listCA Available on: Online Certificate Status Manager. Function: The List CA interface displays a list of the CAs for which the OCSP responder accepts requests. Default Forms The List CA interface does not use any forms. Request Parameters The List CA interface does not use any request parameters.

  • Page 155: Process Certificate Request Interface

    Process Certificate Request Interface Table 6-27 Variables Returned by the List CA Interface (Continued) Variable Description The number of OCSP requests received for this CA. ReqCount Process Certificate Request Interface Description URI: /ca/processCertReq /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.

  • Page 156: Request Parameters

    Process Certificate Request Interface 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.
  • Page 157 Process Certificate Request Interface Table 6-28 Parameters Accepted by the Process Certificate Request Interface (Continued) Parameter Format and Description yes | no checkPubKeyUniqueness Specifies whether the CMS server should ensure that the new certificate’s public key is unique. yes | no checkValidityNesting Specifies whether the CMS server should check to make sure that the certificate does not expire later than the CA’s signing certificate.
  • Page 158 Process Certificate Request Interface Table 6-28 Parameters Accepted by the Process Certificate Request Interface (Continued) Parameter Format and Description MD5withRSA | SHA1withDSA | SHA1withRSA signatureAlgorithm 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.

  • Page 159: Response

    Process Certificate Request Interface Response The default response template is . The base JavaScript processCertReq.template for responses is inserted in place of the tag. In addition, the <CMS_TEMPLATE> Process Certificate Request interface adds the JavaScript variables listed in the following table. Table 6-29 Variables Returned by the Process Certificate Request Interface Variable Description...
  • Page 160 Process Certificate Request Interface Table 6-29 Variables Returned by the Process Certificate Request Interface (Continued) Variable Description message errorDetails A more detailed description of any processing errors. message errors A message explaining any errors that may have occurred. true | false ext_email Indicates whether or not the Netscape certificate extension S/MIME bit (bit 2) is set in the certificate or request that was processed.
  • Page 161 Process Certificate Request Interface Table 6-29 Variables Returned by the Process Certificate Request Interface (Continued) Variable Description string grantPrivilege 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 "...
  • Page 162 Process Certificate Request Interface Table 6-29 Variables Returned by the Process Certificate Request Interface (Continued) Variable Description MD5withRSA | SHA1withDSA | SHA1withRSA signatureAlgorithmNam The name token associated with the signature algorithm whose OID is stored in signatureAlgorithm. pending | complete status Indicates whether the request is complete or if further action is required.

  • Page 163: Process Drm Request Interface

    Process DRM Request Interface Table 6-29 Variables Returned by the Process Certificate Request Interface (Continued) Variable Description number of seconds validityLength 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: •...

  • Page 164: Default Forms

    Process DRM Request Interface 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.

  • Page 165: Response

    Process DRM Request Interface Table 6-30 Parameters Accepted by the Process DRM Request Interface (Continued) Parameter Format and Description email address requestorEmail The email address of the entity requesting archival or recovery, if the information is available. string requestorName The name of the entity requesting archival or recovery, if the information is available.
  • Page 166 Process DRM Request Interface Table 6-31 Variables Returned by the Process DRM Request Interface (Continued) Variable Description user ID 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. seconds since 1 January 1970 createdOn The time when the request was created.

  • Page 167: Process Request Interface

    Process Request Interface Table 6-31 Variables Returned by the Process DRM Request Interface (Continued) Variable Description VALID | INVALID state The current status of the key corresponding to the request. pending | complete status Only requests that have status == pending need to use the Process DRM Request interface to assign the request to an agent.

  • Page 168: Request Parameters

    Process Request Interface 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.

  • Page 169: Recover Key By Serial Number Interface

    Recover Key By Serial Number Interface Table 6-33 Variables Returned by the Process Request Interface Variable Description result.header variables Variables added to the header object. The user ID of the agent to whom the request is currently assigned. Compare to assignedTo callerName to see if the agent viewing the request is the current owner.

  • Page 170: Default Forms

    Recover Key By Serial Number Interface 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.

  • Page 171: Response

    Recover Key By Serial Number Interface Table 6-34 Parameters Accepted by the Recover Key By Serial Number Interface (Continued) Parameter Format and Description recoverBySerial Specifies the operation to perform. The only valid value is recoverBySerial. string p12password 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.

  • Page 172: Remove Certificate Hold Interface

    Remove Certificate Hold Interface If the request was not local or if there was an error, the default response template is . The base JavaScript for responses is inserted in place recoverBySerial.template of the tag. If there are no errors, the default template includes <CMS_TEMPLATE>...

  • Page 173: Default Forms

    Remove Certificate Hold Interface 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.

  • Page 174: Response

    Remove Certificate Hold Interface Response The default response template is . The base unrevocationResult.template JavaScript for responses is inserted in place of the tag. In <CMS_TEMPLATE> addition, the Remove Certificate Hold Interface adds the JavaScript variables listed in the following table: Table 6-37 Variables Returned by the Remove Certificate Hold Interface Variable Description...

  • Page 175: Requests Query Interface

    Requests Query Interface Table 6-37 Variables Returned by the Remove Certificate Hold Interface (Continued) Variable Description message updateCRLError If the CMS server attempted to update the CRL and encountered an error, this variable contains the text of the error message. yes | no updateCRLSuccess If the CMS server attempted to update the CRL, this variable will indicate...

  • Page 176: Request Parameters

    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-38 Parameters Accepted by the Requests Query Interface Parameter Format and Description...

  • Page 177: Response

    Requests Query Interface Table 6-38 Parameters Accepted by the Requests Query Interface (Continued) Parameter Format and Description number totalRecordCount 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).
  • Page 178 Requests Query Interface Table 6-39 Variables Returned by the Requests Query Interface (Continued) Variable Description number querySentinel 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.
  • Page 179 Requests Query Interface Table 6-39 Variables Returned by the Requests Query Interface (Continued) Variable Description user ID callerName The user ID of the agent that requested this list of requests. ca | CEP-Request | client | objSignClient | ra | server | other certType Indicates the type of certificate.

  • Page 180: Select For Revocation Interface

    Select for Revocation Interface Table 6-39 Variables Returned by the Requests Query Interface (Continued) Variable Description Distinguished Name (DN) string. See RFC 2253. subject The subject entry on the certificate corresponding to this request (if there is one). user ID updatedBy The user ID of the agent who last updated this request.

  • Page 181: Request Parameters

    Select for Revocation Interface 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-40 Parameters Accepted by the Select For Revocation Interface Parameter Format and Description...
  • Page 182 Select for Revocation Interface Table 6-41 Variables Returned by the Select For Revocation Interface (Continued) Variable Description number caSerialNumber The decimal serial number of the Certificate Authority’s signing certificate. QUERY_FILTER revokeAll The query filter that was used in the request to select the certificates that appear in this response.

  • Page 183: Update Crl Interface

    Update CRL Interface Update CRL Interface Description URI: /ca/updateCRL /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 , available in the CA agent and RA agent directories,...

  • Page 184: Response

    Update Directory Interface Table 6-42 Parameters Accepted by the Update CRL Interface (Continued) Parameter Format and Description string templateName Filename relative to the template directory (web-apps/ee/ca, web-apps/ee/ra, web-apps/agent/ca, web-apps/agent/kra, or web-apps/agent/ra) of a file to use as the response template. This template will be used for any response, overriding default template settings.

  • Page 185: Default Forms

    Update Directory Interface 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.
  • Page 186 Update Directory Interface Table 6-44 Parameters Accepted by the Update Directory Interface (Continued) Parameter Format and Description string templateName Filename relative to the template directory (web-apps/ee/ca, web-apps/ee/ra, web-apps/agent/ca, web-apps/agent/kra, or web-apps/agent/ra) of a file to use as the response template. This template will be used for any response, overriding default template settings.

  • Page 187: Response

    Update Directory Interface Response The default response template is . The base JavaScript for updateDir.template responses is inserted in place of the tag. In addition, the Update <CMS_TEMPLATE> Directory interface adds the JavaScript variables listed in the following table. A variable will not be added (it will have a value) if it does not apply;...
  • Page 188 Update Directory Interface Table 6-45 Variables Returned by the Update Directory Interface (Continued) Variable Description Success | Failure revokedCertsUnpublished 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. A message explaining why new certificates could not be published to the validCertsError directory, if there was an error.

  • Page 189: Index

    Index Remove Certificate Hold 172 Requests Query 175 Add CA (OCSM interface) 112, 113 Select for Revocation 180 Add CRL (OCSM interface) 113 Update CRL 183 Update Directory 184 addCA 112 who can access 102 addCRL 113 agents Agent Services interface 101 forms for 106 Add CA 112 locating forms and templates for 107...
  • Page 190 adding 112 key for recovery 131 getting 37 displayBySerialForRecovery 133 certificate enrollment displayCertFromRequest 52 supported authentication mechanisms 32 documentation supported request formats 32 conventions followed 12 Certificate Enrollment Protocol Interface 47, 87 where to find 14 Certificate Manager doRevoke 43, 115 enrollment forms for 35 doUnrevoke 172 interface for agents 102...
  • Page 191 for end users 34 for object signing certificates 35 key archival for Registration Managers 35 required format for requests 32 for servers 35 Key Query (DRM Interface) 144 Examine Recovery 136 key recovery examineRecovery 136 archive request approval 163 by serial number 131, 133 check request 136 find by serial number 169 grant approval 142...
  • Page 192 interface for agents 104 interface for agents 103 Online Certificate Status Protocol Remove Certificate Hold 172 interface for end-entity 87 renew certificates 88 OCSP responder 87 Renewal (interface) 88 output templates request formats for certificates 32 for end-entity operations 38 Requests Query 175 retrieve certificate by list 78...
  • Page 193 unrevocation 172 Update CRL 183 Update Directory (interface) 184 updateCRL 183 updateDir 184 user enrollment forms 34 Index...

This manual is also suitable for:

Certificate management system 6.01

Table of Contents