Additional modules for certificate authorities

From ISPWiki

Jump to: navigation, search

To automatically sell SSL certificates via BILLmanager you can add a custom module.

The module consists of two sections:

  • The XML file that describes messages and interface of the certificate authority creation form in BILLmanager;
  • The executable file that processes all operations associated with certificate order.


XML file

The XML file should be named as billmgr_mod_xxx.xml and reside in the /usr/local/ispmgr/etc/ directory. Restart BILLmanager after you create or edit the file. If the changes made to the XML file do not display in the interface, execute the following command to check for errors:

/usr/local/ispmgr/sbin/xmlcache billmgr

The XML document must contain the following sections:

  • Description of form fields in the certificate authority creation form.
  • Text that will be used instead of a module name in the certificate authority edit form.
  • Text that will be used instead of a module name on the list of certificate authorities.
  • Text that will be used instead of a template name in the certificate template edit form.
  • Text that will be used instead of a template name on the list of certificate templates of a certification authority.
  • Text that will be used instead of a template name on the list of certificates.

Example of the XML file

<?xml version="1.0" encoding="UTF-8"?>
        <metadata name="certauth.edit" type="form">
                        <field name="name">
                                <select name="name" sorted="yes">
                                        <if value="template" show="'admingroup','usr','pwd','apiurl'" hide="'partnercode','resellerid','ipaddr','usedemo','handle','server'"/>
        <lang name="ru">
                <messages name="certauth.edit">
                        <msg name="template.php">Template</msg>

                <messages name="certauth">
                        <msg name="name_template.php">Template</msg>
                <messages name="certauth.templates">
                        <msg name="certtype_type_1">Type 1</msg>
                        <msg name="certtype_type_2">Type 2</msg>
                        <msg name="certtype_type_3">Type 3</msg>

                <messages name="certauth.templates.edit">
                        <msg name="type_1">Type 1</msg>
                        <msg name="type_2">Type 2</msg>
                        <msg name="type_3">Type 3</msg>

                <messages name="certificate">
                       <msg name="certauth_template.php">Template</msg>
                       <msg name="certtype_type_1">Type 1</msg>
                       <msg name="certtype_type_2">Type 2</msg>
                       <msg name="certtype_type_3">Type 3</msg>

Executable file

The executable file should be named as caxxx (where xxx is an arbitrary name) and reside in the /usr/local/ispmgr/sbin/ directory. If you are going to use one of script languages (php, perl, etc.), add an extension to the file's name. The LD_LIBRARY_PATH environment variable will be reseted before starting the module. Example (it is used in this article) - /usr/local/ispmgr/sbin/catemplate.php

BILLmanager must support the following commands:

  • checkaccess - check access through API with specified parameters. Parameters: username - a username or some other identifier for which API access is checked, url - a URL path to API. The password is sent to stdin. If API checks are successful, OK (without quotation marks)and the parameters should be sent to stdout.
  • buildtemplate - list all certificate types available. Its parameter is a certification authority's id. To execute the function, read the XML from stdin, add all certificate types and send to stdout. To add types of certificates, create a list and specify elements. The list looks something like this:
<slist name='certtype'>

Add it to the root element of the XML document.

  • gettemplprops - receive default parameters for a certificate type. Parameters: certificate_type_name, certificate_authority_name. Based on these parameters, the module will form an XML document containing the list of default parameters supported by this type. The XML document should look like this:
<?xml version="1.0" encoding="UTF-8"?>

If you choose to manually set up template parameters, you can return an empty XML document: "<?xml version="1.0" encoding="UTF-8"?><doc/>".

<prop>wildcard</prop> - is added to the XML document, if this type supports Wildcard certificates.

<prop>extvalid</prop> - is added to the XML document, if extended validation is performed.

<prop>orginfo</prop> - is added to the XML document, if organization information is required.

<prop>idn</prop> - is added to the XML document, if this type supports IDN domains.

<prop>www</prop> - is added to the XML document, if this certificate can be used for both www and non-www domains.

  • approverlist - list email addresses for certificate confirmation. Parameters: domain_name, certificate_template_id. You may not execute this command. A default list of email address will be used. After you execute the command, return to stdout a list of allowed email addresses, hyphen separated.
  • new - submit a certificate request. Parameters: service_id.
  • check - check the certificate current status. Parameters: service_id.
  • renew - submit a certificate renewal request. Parameters: service_id.
  • reissue - submit a certificate reissue request. Parameters: service_id.

After executing one of the above commands, the module will pass the result to BILLmanager. Call the certificate.process function in BILLmanager. The following parameters are supported:

  • itemid - obligatory parameter containing id.
  • result - obligatory parameter containing a result of the operation:
    • created - the certificate was create in the certification authority.
    • enrolled - the certification authority is processing a certificate request (the "Enrolled" status in BILLmanager).
    • renewed - the certification authority is processing a certificate renewal request.
    • issued - the certificate is issued by the certification authority (the "Issued" status in BILLmanager).
    • reissued - the certificate is reissued by the certification authority (the "Issued" status in BILLmanager)
    • error - an error occurred while issuing the certificate (the "Order error" status in BILLmanager). If this parameter is sent to result, the order will be cancelled in BILLmanager and the funds will be refunded.
  • message - the value depends on the result parameter:
    • result = created - contains the id of the certificate in a certification authority. It can be used to check current status of the certificate.
    • result = enrolled - not processed.
    • result = renewed - not processed.
    • result = issued - contains text representation of the issued certificate.
    • result = reissued - not processed.
    • result = error - contains the name of operation that was executed when the error occurred. In case of new' or renew, the order is cancelled in BILLmanager, the money charged are returned to a client's account and the client receives the error message.
  • errormsg - contains information about errors that occurred while ordering the service.
  • validto - certificate expiration date. It is processed as result when sending issued.

Data structure associated with processing ssl certificates

A service is associated with the certificate template through the table the certtmpl field of the pricelist table

Certificate data are stored in the certificate table

  • pid - link to item
  • csr - text of the certificate signing request
  • crt - text of a certificate
  • pkey - text of the private key
  • adm_fname - first name of the administrative contact
  • adm_lname - last name of the administrative contact
  • adm_jtitle - job title of the administrative contact
  • adm_phone - phone number of administrative contact
  • adm_email - email of administrative contact
  • tech_fname - first name of the technical contact
  • tech_lname - last name of the technical contact
  • tech_jtitle - job title of the technical contact
  • tech_phone - phone number of the technical contact
  • tech_email - email of the technical contact
  • org_name - organization name
  • org_country - country code (link to the reference)
  • org_state - region/state whre the organization is located
  • org_city - city where the organization is located
  • org_postcode - organization post code
  • org_address - organization address
  • org_phone - organization phone number
  • vemail - email for confirmation
  • status - certificate status:

0- unknown, 1-ordered, 2-paid, 3-ordere in CA, 4-enrolled, 5-issued, 6-error

  • caorderid - order id in the certification authority
  • fqdn - domain name

Certificate template's data are stored in the certtmpl table

  • id - id
  • name - name
  • certauth - url to a certification authority's web-site
  • wildcard - the certificate supports wildcard
  • orginfo - organization information is required
  • extvalid - extended validation
  • longkey - the certificate's key must be 2048 bite long
  • idn - the certificate supports IDN domains
  • www - the certificate can be ordered for a www domain
  • certtype - name of a certificate type

Data from a certifcate authority are stored in the certauth table

  • id - id
  • name - processing module
  • account - URL to a provider's account
  • username - username
  • password - password
  • admingroup - department in charge of this issue
  • apiurl - access URL
  • partnercode - partner id (is used in some modules)
  • ipaddr - IP-address (is used in some modules)
  • usedemo - test mode

Example of php script

       $LOG_FILE = fopen("/usr/local/ispmgr/var/catemplate.php.log", "a");

       function Debug($log_str) {
          fwrite($GLOBALS["LOG_FILE"], date("M d H:i:s")." [".posix_getpid()."] ".$log_str."\n");

       function defErrorHandler($errno, $errstr, $errfile, $errline) {
               if (!(error_reporting() & $errno)) {
               Debug($errfile.":".$errline." Error: ".$errno.", error message: ".$errstr);
               return true;

       function userga() {
               echo "Template CA File.";

       if ($argc<2) {
       } else {
               switch($argv[1]) {
                       case "checkaccess":
                               $user = $argv[2];
                               $pass = file_get_contents("php://stdin");
                               if ($user == "test" && $pass == "test")
                                       echo "OK";
                                       echo "Not test";
                       case "buildtemplate":
                               $xml_doc = file_get_contents("php://stdin");
                               $xmldata = new SimpleXMLElement($xml_doc);
                               $slist = $xmldata->addChild("slist");
                               $slist->addAttribute("name", "certtype");
                               $slist->addChild("msg", "type_1");
                               $slist->addChild("msg", "type_2");
                               $slist->addChild("msg", "type_3");
                               echo $xmldata->asXML();
                       case "gettemplprops":
                               $xmldata = simplexml_load_string("<?xml version='1.0'?><doc/>");
                               $type = $argv[2];
                               switch ($type) {
                                       case "type_1":
                                               $xmldata->addChild("prop", "wildcard");
                                               $xmldata->addChild("prop", "idn");
                                               $xmldata->addChild("prop", "www");
                                       case "type_2":
                                               $xmldata->addChild("prop", "idn");
                                               $xmldata->addChild("prop", "orginfo");
                                               $xmldata->addChild("prop", "extvalid");
                                       case "type_3":
                               echo $xmldata->asXML();
                       case "approverlist":
                               $domain = $argv[2];
                               $type = $argv[3];
                               echo "root@".$domain;
                       case "new":
                               $iid = $argv[2];
                               //Process order
                       case "check":
                               $iid = $argv[2];
                               //process check
                       case "renew":
                               $iid = $argv[2];
                               //process renew
                       case "reissue":
                               $iid = $argv[2];
                               //process reissue
Was this helpful? Yes | No
Personal tools