Certificate Management System 4.0 
Bulk Generation Interface Specification

$Id: bulkapi.html,v 1.1.2.2 1999/04/28 00:27:03 stevep Exp $

Introduction

In order to support smart card vendors that have bulk generation and smart card manufacturing solutions,  Certificate Management System (CMS) 4.0 provides for an agent interface (see CMS 4.0 documentation regarding details of the agent interface).  The agent interface is essentially an HTTP over SSL interface for authenticating as an issuing agent, and then posting, and getting automatically signed a public key certificate on behalf of a user being managed by the bulk generation solution.  Bulk key and certificate generators deal with enumeration of the clients, production of either PKCS#12 or hardware tokens, and personalization (integration of name and photo information into the token).   CMS 4.0 restricts its level of interest to the authentication of the agent, receipt of the request, automatic signing of the request, and delivery back to the agent of a PKCS#7 response.    This document will describe the specifics of this interface, that allows clients to achieve bulk signing from CMS 4.0.

Prerequisites

The client must be able to do the following:
  • Connect to the CA via TCP connection.
  • Create SSL 3.0 connections -- if they don't already have an SDK, they can license Netscape Security Services (NSS 2.0) -- contact Dmitri Krakovsky (dmitri@netscape.com) for more details.
  • Manage a client side X509v3 certificate, and use it in the context of an SSL 3.0 connection to the CA.
  • Create one of the following standards based (or non-standard) self signed enrollment requests
  • PKCS#10,
  • KEYGEN (see http://www.netscape.com/eng/security/comm4-keygen.html) for details of KEYGEN tag and resultant outputs,
  • or CRMF  (formats are described in PKIX drafts available online at http://www.ietf.org/html.charters/pkix-charter.html)
  • Parse and store the resultant digital certificates (including the chain) signed by the CA:
  • Base-64 encoded PKCS#7 certificate chain
  • CMMF response (see formats  at http://www.ietf.org/html.charters/pkix-charter.html)
  • Interface Details

    Hostname / Agent Port

    Once the CMS 4.0 product is installed, you will need to note the hostname and port that provides Agent services (see CMS 4.0 documentation for full details on how to install and configure CMS 4.0).  The TCP port is selected by the CMS 4.0 system administrator, when they setup the CA.  The hostname is the DNS name that would be selected when the agent access privileged CA services (e.g., https://mycaserver.netscape.com:2000).  Hostname is mycaserver, and port is 2000.

    POST

    The CA signing request will be delivered over HTTP protocol, via the POST method from the Ca's agent port.   The following are the fields and formats expected in the POST method.

    URL: https://hostname:port/ca/bulkissuance?...

    HTTP parameters:
     
    parameter name  required/optional value  what is it
    subjectKeyGenInfo required* Base-64 encoded SubjectPublicAndChallenge as defined in comm4-keygen.html on netscape's home page. The subject's public key info to be in the certificate.
    pkcs10Request required* Base-64 encoded PKCS#10 blob A PKCS#10 certificate request .
    CRMFRequest required* Base-64 encoded CRMF Request as defined in draft-ietf-pkix-crmf-01.txt A CRMF certificate request.
    subject required** subject name as a directory string, defined in RFC2253 The subject name to put in the certificate
    certType required one of:
    "client" "server" "ca" "ra" "vpn" "crs" "other"
    The certificate type, used by CA's policies to enforce certain constraints or add certificate extensions.
    csrCertType optional same as above Old style certificate type for backwards compatibility.
    importCert optional one of:
    "true" "false" "on" "off"
    Whether to return the certificate in binary form as mime type
    application/x-x509-user-certmime 
    SMIME optional one of: 
    "true" "false" "on" off" 
    Whether to set the SMIME bit in the Netscape Cert Type extension as defined in comm4-cert-exts.html on Netscape's home page. This is used only if the Netscape Cert Type extension is enabled on the CA. See the CMS Administrator's Guide for more information on extension policies on the CA.
    SSLClient optional one of: 
    "true" "false" "on" off" 
    Whether to set the SSL Client bit in the Netscape Cert Type extension. This is used only if the Netscape Cert Type extension is enabled on the CA.
    ObjectSigning optional one of: 
    "true" "false" "on" off" 
    Whether to set the Object Signing bit in the Netscape Cert Type Extension. This is used only if the Netscape Cert Type extension is enabled on the CA
    csrRequestorEmail optional any string Requester email - email address where certificate will be sent if the request was deferred and approved out of band. 
    If the certificate subject name has an email field, the email in the certificate overrides this field.
    csrRequestorPhone optional any string Requester's phone number for the agent processing the request to contact for verification if the request is deferred. 
    csrRequestorComments optional any string Any additional information for the agent processing to use for verification of the request if the request is deferred.
    cmmfResponse optional one of: 
    "true" "false" "on" off" 
    if true CA will return a base 64 encoded CMMF response as defined in draft-ietf-pkix-cmmf-02.txt containing one or more resulting certificates.

    * one of subjectKeyGenInfo, pkcs10Request or CRMFRequest is required.
    ** required only if subjectKeyGenInfo is used or if subject name is not set in a PKCS#10 or CRMF request.
     

    RESPONSE


    If the request is successful and http parameter importCert was set to true the CA will return the signed certificate in binary form using MIME type of application/x-x509-user-cert .  The response is compatible with the resulting formats provided by Communicator 4.X, and documented at http://www.netscape.com/eng/security/comm4-cert-download.html -- CMS 4.0 will return PKCS #7 certificate chain.

    If the request is successful and the csrCertType (old style parameter) was set to true, the CA will return the response in HTML as follows:
    Comments are in intalics enclosed in brackets.

    <HTML>
    <TITLE>
    Server Enrollment
    </TITLE>
    <H1>
    SUCCESS
    </H1>
    Your request is submitted and approved. Please cut and paste the certificate into your server.
    <P>
    Request Creation Time:
    Thu Feb 18 15:17:31 PST 1999
    <P>
    Request Status:
    2
    <P>
    Request ID:
    [request ID]
    <P>
    Certificate:
    <P>
    <PRE>
    -----BEGIN CERTIFICATE-----
    MIIBQTCB7AIDAY6gMA0GCSqGSIb3DQEBBAUAMCcxEzARBgNVBAoTCnRlc3RDTVMxMjcxEDAOBgNV
    BAMTB3Rlc3QgQ0EwHhcNOTkwMjE4MjMxMjMxWhcNMDEwMjA3MjMxMjMxWjAvMQ0wCwYDVQQKEwRi
    dWxrMQ8wDQYDVQQLEwZwa2NzMTAxDTALBgNVBAMTBGJ1bGswXDANBgkqhkiG9w0BAQEFAANLADBI
    AkEAzZwlHLRy9cOU8Lkn4JLeUsnK1LEfawCPIvwtgL9ZpGgFRrLWkSxk2aUFdEXg+GOW7nqQoIvg
    jF0jU+SIIafRsQIDAQABMA0GCSqGSIb3DQEBBAUAA0EAg0uzLdW/ECyniz88E0zxcXZ0/Ljp71hK
    Z3QrCdy8b02+C+8OiUxAItgcVBR1bS8l5SXjjVTPH0meHhnAhva1yQ==
    -----END CERTIFICATE-----

    </PRE>
    <P>
    <!HTTP_OUTPUT REQUEST_CREATION_TIME=Thu Feb 18 15:17:31 PST 1999>
    <!HTTP_OUTPUT REQUEST_STATUS=2>
    <!HTTP_OUTPUT REQUEST_ID=101652>
    <!HTTP_OUTPUT X509_CERTIFICATE=-----BEGIN CERTIFICATE-----
    MIIBQTCB7AIDAY6gMA0GCSqGSIb3DQEBBAUAMCcxEzARBgNVBAoTCnRlc3RDTVMxMjcxEDAOBgNV
    BAMTB3Rlc3QgQ0EwHhcNOTkwMjE4MjMxMjMxWhcNMDEwMjA3MjMxMjMxWjAvMQ0wCwYDVQQKEwRi
    dWxrMQ8wDQYDVQQLEwZwa2NzMTAxDTALBgNVBAMTBGJ1bGswXDANBgkqhkiG9w0BAQEFAANLADBI
    AkEAzZwlHLRy9cOU8Lkn4JLeUsnK1LEfawCPIvwtgL9ZpGgFRrLWkSxk2aUFdEXg+GOW7nqQoIvg
    jF0jU+SIIafRsQIDAQABMA0GCSqGSIb3DQEBBAUAA0EAg0uzLdW/ECyniz88E0zxcXZ0/Ljp71hK
    Z3QrCdy8b02+C+8OiUxAItgcVBR1bS8l5SXjjVTPH0meHhnAhva1yQ==
    -----END CERTIFICATE-----
    >
    </HTML>
     

    Otherwise if the request is successful the CA will return the following response in HTML and javascript:
    Comments are in italics enclosed in brackets.
    <HTML>
    <SCRIPT LANGUAGE="JavaScript">

    var header = new Object();
    var fixed = new Object();
    var recordSet = new Array;
    var result = new Object();
    fixed.requestStatus = [the request status as described below];
    fixed.certType = "[the certType that was passed in from the request]";
    fixed.authorityName = "Certificate Manager";
    fixed.host = "[the server's ip address in n.n.n.n form]";
    fixed.port = [the server port];
    fixed.scheme = ["https" or "http"];
    fixed.cmmfResponse = "[the Base-64 encoded CMMF response if CMMFResponse was set to true in the request]";
    var recordCount = 0;
    var record;
    record = new Object;
    record.certPrettyPrint = "[a pretty print of the certificate]";
    record.base64Cert = "[the certificate in base 64 encoded form]";
    record.serialNo = "[the certificate's serial number]";
    recordSet[recordCount++] = record;
    [more records can be set if more than one certificate was requested in a CRMF request, for example in the case of dual-key. If CMMFResponse was set to true in the request no certificate records will be set, instead CMMFResponse is returned.]
    record.recordSet = recordSet;
    result.header = header;
    result.fixed = fixed;
    result.recordSet = recordSet;

    </SCRIPT>

    If any error was encountered in the request the will return the following in HTML and javascript:
    Comments are in italics enclosed in brackets.
    <HTML>
    <SCRIPT LANGUAGE="JavaScript">

    var header = new Object();
    var fixed = new Object();
    var recordSet = new Array;
    var result = new Object();
    fixed.requestStatus = [the request status as described below];
    fixed.authorityName = "Certificate Manager";
    fixed.errorDetails = "[an error message if an error was encountered]";
    fixed.errorDescription = "[a more detailed error description if any]";
    fixed.unexpectedError = "[an unexpected error message if one was encountered]";
    var recordCount = 0;
    var record;
    record = new Object;
    record.policyMessage = "[policy rejection message if the request was rejected]";
    [records are only set if the request was rejected by the CA policies. One or more records could be set if there are more than one policy error message.]
    recordSet[recordCount++] = record;
    result.header = header;
    result.fixed = fixed;
    result.recordSet = recordSet;

    </SCRIPT>

    Request status is an integer. The possible values are:

        1 - unauthorized - a SSL client auth certificate was not present or does not have correct privileges.
        2 - success - the request was successful.
        3 - pending - policies on the CA decided to defer the request for an agent approval.
        4 - service pending - the request was sent to a data recovery manager to service and waiting for a response.
        5 - rejected - policies on the CA decided to reject the request.
        6 - error - an error was encountered while processing the request.
        7 - unexpected error - an unexpected error (such as error outputting the response) was encountered.

    SERVER CONFIGURATION

    The following are configuration parameters related to bulk issuance in the CMS configuration file, CMS.cfg, and their default values. See the CMS System Administration Guide for more information on templates.

    agentGateway.enableBulkInterface=true
    agentGateway.bulkissuance.successTemplate=/ca/bulkissuance.template
    agentGateway.bulkissuance.errorTemplate=/ca/bulkissuance.template
    agentGateway.bulkissuance.unexpectedErrorTemplate=/ca/bulkissuance.template
    agentGateway.bulkissuance.unauthorizedTemplate=/ca/bulkissuance.template
    agentGateway.bulkissuance.pendingTemplate=/ca/bulkissuance.template
    agentGateway.bulkissuance.svcpendingTemplate=/ca/bulkissuance.template
    agentGateway.bulkissuance.rejectedTemplate=/ca/bulkissuance.template