How to add an SSL certificate module

An SSL certificate module allows you to configure SSL certificates of different types that you can offer to your clients. This module also implements the order, renewal, and reissue procedures. 

Module at work

An SSL certificate module in BILLmanager involves the following steps:

1. Module setup
2. Connection to a Certification Authority 
3. Tariff configuration 
4. Service order and payment 
5. Service activation
6. Service activation/suspension/deletion/other operations

You can install the module manually (if it is a list of files) or from the repository using the package manager. The module will be available when adding a Certification Authority in BILLmanager.

BILLmanager requests supported features and required parameters from every module. This operation is performed each time BILLmanager starts and allows to improve BILLmanager performance and exclude unsupported calls.

Module structure

The module contains two files:

• etc/xml/billmgr_mod_XXX.xml — XML description
• processing/XXX — main script

Where XXX is the name of your module in the Latin alphabet letters. If the name of the main module contains a file extension, it will be also included in the name. For example, if your script name is pmresellerclub.php, the module name will be pmreselleclub.php, rather than resellerclub or pmresellerclub.

XML description

A file name can look like the following - billmgr_mod_XXX.xml, where XXX  is a module name. The file is copied into the etc/xml directory relative to the BILLmanager installation path. The file contains the description of the module (it is described as a plugin) and additional forms and messages.

Example of the module XML file:

<mgrdata>
  <plugin name="XXX">
    <group>processing_module</group>
    <params>
      <type name="certificate"/>
    </params>
    <msg name="desc_short" lang="ru">XXX module</msg>
    <msg name="desc_short" lang="en">XXX module</msg>
    <msg name="desc_full" lang="ru">XXX module</msg>
    <msg name="desc_full" lang="en">XXX module</msg>
  </plugin>

  <metadata name="processing.edit.XXX" type="form">
    <form>
      <page name="connect">
        <field name="prop1">
          <input name="prop1" required="yes" type="text" />
        </field>
        <field name="prop2">
          <input name="prop2" required="yes" type="text" />
        </field>
      </page>
    </form>
  </metadata>

  <lang name="en">
    <messages name="label_processing_modules">
      <msg name="XXX">XXX module</msg>
      <msg name="module_XXX">XXX module</msg>
    </messages>

    <messages name="processing.edit.XXX">
      <msg name="prop1">Prop 1</msg>
      <msg name="hint_prop1">Hint for prop 1</msg>
      <msg name="prop2">Prop 2</msg>
      <msg name="hint_prop2">Hint for prop 2</msg>
    </messages>
  </lang>

  <lang name="ru">
     <messages name="label_processing_modules">
      <msg name="XXX">XXX module</msg>
      <msg name="module_XXX">XXX module</msg>
    </messages>

    <messages name="processing.edit.XXX">
      <msg name="prop1">Property 1</msg>
      <msg name="hint_prop1">Hint for property 1</msg>
      <msg name="prop2">Property 2</msg>
      <msg name="hint_prop2"Hint for property 2</msg>
    </messages>
  </lang>
</mgrdata>

The <plugin> section describes the module. The name property must match the name of your SSL module. The section may contain the group element with the processing_module value indicating that this module is used to handle services, several msg elements, and the params section with the <type name="certificate"/> sub-node indicating that this handler is an SSL order module, i.e. can process services with the certificate internal name. The lang property defines a language associated with the message, the name attribute may have the following values

• desc_short — a brief description of the module. It is displayed in the BILLmanager payment form.
• desc_full — a full description of the module which is displayed in the list of installed modules in COREmanager.

The metadata section processing.edit.XXX handles additional fields of the module that are displayed when you add or configure the module. It is formed according to the standard description of XML forms. Take the note of the location of fields in the <page name="connect"></page> section for correct location of fields on BILLmanager forms.

The lang section contains translations of form fields according to the standard scheme of translation description. The <messages name="label_processing_modules"> section specifies the module name in a list of processing modules.

Main script

The main script sends BILLmanager information about the functions that the module supports and handles those functions. BILLmanager executes the script file with the following parameters:  

processing/pmxxx --command command [--item item] [--module module] [--itemtype itemtype] [--param param --value value] [--runningoperation runningoperation] [--domain domain]

Where

• command — a command which defines an action that the module should perform. 
• item — service id for which the operation is performed 
• module — processing module id for which the operation is performed 
• itemtype — product type internal name
• param — parameter name
• value — parameter value
• runningoperation — id of the current operation. This id is required for changing parameters of the current operation and creating tasks.
• domain — name of the domain this certificate is issued for.

The runningoperation parameter is passed if BILLmanager starts the module after creating the current operation. Once completed, perform one of BILLmanager functions (they are described below) to delete the current operation from the queue, or to perform one of the following operations:

• execute the runningoperation.edit function to save a text of the error into properties of the operation 
• execute the  runningoperation.setmanual function for manual set up of the current operation to avoid an automatic restart of the operation 
• execute the task.edit function  to assign the task to a Support center department

The command parameter can have one of the following values: 

• features — request a list of features that the module supports. The following XML will be sent to stdout:  

<doc>
 <itemtypes>
    <itemtype name="certificate"/>
 </itemtypes>
 <params>
    <param name="url"/>
    <param name="auth_token" crypted="yes"/>
    <param name="partner_code"/>
 </params>
 <features>
    <feature name="check_connection"/>                                 <!-- the module can verify parameters that were entered when adding the processing module -->
    <feature name="approver"/>                                         <!-- the module can get a list of administrator's email addresses -->
    <feature name="prolong"/>                                          <!-- the module can renew services with a certification authority -->
    <feature name="usercreate"/>                                       <!-- the module can create an account on a certification authority web-site -->
    <feature name="sync_item"/>                                        <!-- the module can get information about an SSL certificate from a certification authority -->
 </features>
 <templates>
    <!-- Supported certificates: -->
    <template name="securesiteproev" multidomain="yes" orginfo="yes"/>
    <template name="securesitewildcard" wildcard="yes" orginfo="yes"/>
    <template name="quicksslpremium" www="yes"/>
    <template name="truebizid" orginfo="yes" csraltname="yes"/>
    ...
    <!--
    Certificate properties: 
    multidomain - certificate secures multiple (alternative) domain names certificate
    orginfo - organization information is required 
    wildcard - certificate secures all subdomains of *.mydomain.com
    www - certificate secures both for domain.com and  www.domain.com 
    
    Domain verification methods:
    authemail - via email;
    authcname - via DNS CNAME;
    authfile - via HTTP(S).
    -->
  </templates>
</doc>

Your module may not support some of the above functions. If a feature is not supported, it shouldn't be passed to the command stdout.

• approver — request a list of allowed email addresses. 
• usercreate — register a new account on the certification authority (CA) website through BILLmanager.
• check_connection — send the XML with CA connection parameters. The output document looks like the following: 

<doc>
  <param>value</param>
  ...
  <param>value</param>
</doc>

Regardless of module requirements, the parameters are not encrypted. 

Using these parameters your module will check if it is possible to use them to connect to a CA, and will return the error XML description if any. If a success, it should return the following XML: 

<doc/>

• tune_connection — the XML containing parameters of the CA connection form is sent to the module standard input. The XM document with the required parameters is sent to its standard output. 
• open — service activation command. The system sends the item and runningoperation parameters to the module  (when starting the task in BILLmanager). Once the service is activated, call the certificate.open  function to complete the operation and delete the task from the list of current operations. 
• reopen — SSL reissue. The system sends the item and runningoperation parameters to the module  (when starting the task in BILLmanager). Once the service is activated, call the service.postreopen function to complete the operation and delete the task from the list of current operations. 
• suspend — service suspension command. The system sends the item and runningoperation parameters to the module  (when starting the task in BILLmanager). Once the service is suspended, call the service.postsuspend function to mark the service as Suspended and delete the task from the list of current operations. 
• resume — service activation command. The system sends the item and runningoperation parameters to the module (when starting the task in BILLmanager). Once the service is activated, call the service.postresume function to change the service status to Active and delete the task from the list of current operations.
• close — service deletion command. The system sends the item and runningoperation parameters to the module (when starting the task in BILLmanager). Once the service is deleted, modify the  service.postclose function to change the service status to Deleted and delete the task from the list of current operations. 
• setparam — modify service parameters or tariff plans. The system sends the item and runningoperation parameters to the module (when starting the task in BILLmanager). Once parameters are modified, call the service.postsetparam function to save the new tariff plan, update service price and delete the task from the list of current operations. 
• prolong — service renewal command. The system sends the item and runningoperation parameters to the module (when starting the task in BILLmanager).  Once the service is renewed, call the service.postprolong  function to delete the task from the list of current operations. 
• sync_item — get information about the service from the registrar. The system also sends the item parameter The below functions are used to save parameters. In case of an error, you can use the certificate.failed function to inform a client. 
• check_param — check modified parameters. The system sends the item (service id) and param (parameter name) parameters (they are passed only for a number of built-in parameters), value — parameter value (it is passed only for a number of built-in parameters), level - access permissions of the user who has modified the parameters. To stdout, the system also sends the XML containing new and old values of service parameters. 

You can find the script example at the end of this article. 

Linked table structure 

• the item table — contains the main information about services,  id - service id, processingmodule -  processing module id. 
• the certificate table — contains certificate data, item - service id, csr - certificate signing request 
• the processingmodule table — contains the main information about the processing module, id - processing module id
• the processingparam  table — contains parameters of the processing module, processingmodule — processing module id, intname — parameters name, value — value
• the processingcryptedparam table — contains encrypted  parameters of the processing module, processingmodule — processing module id, intname — parameter name, value — encrypted value

Managing current operations 

Before sending most of the requests, BILLmanager creates an operation that will be restarted if the previous operation fails and automatic restart is enabled. The operation id is passed to the module with the runningoperation parameter (you may not pass it). 

When the module gets the id of the current operation, if the command fails, the information about the operation can be kept in parameters of the current operation to be displayed in BILLmanager with the runningoperation.edit function, and activate manual setup with the runningoperation.setmanual function. 

To create a task based on the current operation, complete the following steps: 

1. Define a task type using the  task.gettype function. Use the operation parameter to pass the command that the module has received
2. Execute the task.edit function to register the task 

Once completed, the task will be assigned to a  department that can handle it (it is already selected in the processing module configuration form).

BILLmanager functions

• paramlist — does not require parameters. The function passes a list of panel configuration parameters.
• runningoperation.delete — delete the current operation
  • elid — current operation id
• runningoperation.edit — edit parameters of the current operation
  • elid — current operation id
  • sok=ok — indicates that parameters are saved 
  • errorxml — error XML description 
• runningoperation.setmanual — process the operation manually 
  • elid — current operation id
• certificate.open — service activation completion. It will change the status into "Active", send the service activation email to a client, and delete the activation operation 
  • elid — service id
  • sok=ok — indicates that parameters are saved 
• service.postclose — complete service deletion. This operation will change the service status and delete the deletion operation
  • elid — service id
  • sok=ok — indicates that parameters are saved 
• service.postopen — complete service setup . This operation will delete the setup operation
  • elid — service id
  • sok=ok — indicates that parameters are saved 
• service.postreopen — complete service renewal. This operation will delete the renewal operation
  • elid — service id
  • sok=ok — indicates that parameters are saved 
• service.postprolong — complete service renewal. This operation will delete the renewal operation
  • elid — service id
  • sok=ok — indicates that parameters are saved
• service.postresume — complete service activation. This operation will change the service status, and delete the activation operation
  • elid — service id
  • sok=ok — indicates that parameters are saved
• service.postsetparam — complete service modification. This operation will change the service status, delete the link to the previous tariff plan, and update the service price
  • elid — service id
  • sok=ok — indicates that parameters are saved
• service.postsuspend —  complete service suspension. This operation will change the service status, and delete the suspension operation
  • elid — service id
  • sok=ok — indicates that parameters are saved
• service.saveparam - save a service parameter 
  • elid — service id
  • name — parameter internal name
  • value — parameter value
• service.setexpiredate — change the validity period
  • elid — service id
  • expiredate — new validity period 
• service.setstatus — change the additional status of the service 
  • elid — service id
  • service_status — new status
• certificate.save — save certificate data in BILLmanager
  • elid — service id
  • crt — certificate data
  • crt_type — certificate data type. An empty value for text. When saving the archive in the control panel, the system will pass the archive type (file extension) and file contents in base64
• certificate.failed — save certificate data in BILLmanager
  • elid — service id

Service statuses

The service may have one of the following statuses:

•  — unknown (this status is not used in BILLmanager 5)
• 1 — order not paid (this status is not used in BILLmanager 5)
• 2 — paid, not processed (this status is not used in BILLmanager 5)
• 3 — CRS sent 
• 4 — awaiting the certificate issue 
• 5 — issued
• 6 — issues failed 

Additional parameters

• altname — alternative domains for SAN certificates 
• old_altname — old list of alternative names. The system saves it into the database if alternative names for SAN certificates are changed when reissuing an SSL-certificate.   
• approver_email — email for domain verification 
• custom_order_id — certificate id  on the Certification authority side
• service_status — current additional status
• approver_method — domain verification methods. Possible values:

1. auth_email — email;
2. auth_cname — via DNS CNAME;
3. auth_file — via HTTP(S).

SAN certificates

The system handles SAN certificated the same way as other types of certificates. However, note

• The list of email addresses for domain verification is kept in one approver_email parameter. Emails are enumerated space separated in the same order as additional domains are added. The verification email of the main domain must stand first. 
• In the case of SSL reissue pay attention to the old_altname parameter. If it's not empty, the system will change the list of additional domains when reissuing a certificate. a new list of domain names will be saved in the altname parameter, and the domains specified before the reissue will be kept in the  old_altname parameter.

Example of module

Examples of processing modules in C++ and Python are available on Github at https://github.com/ISPsystemLLC/billmanager/

С++

C++ (using BILLmanager libraries)

In addition to this example, you can study examples from the BILLmanager package for the developer. BILLmanager contains the libraries required for C++ modules. To develop your own processing modules, install the package:

yum install billmanager-corporate-devel

After installation:

An example of a C++ integration module for The SSL Store

The example shows a working integration module for The SSL Store.

To assemble and install the module:

1. Install the software package:

   Ubuntu 20.04, AstraLinux 1.7.4

   apt-get install coremanager-dev

   CentOS 7, AlmaLinux 9

   yum install coremanager-devel

2. Enter the directory

   cd /usr/local/mgr5/src

3. Get the source code of the example module. This can be done in two ways:
   • Download the archive:
     1. Go to https://github.com/ISPsystemLLC/billmanager
     2. Click Code → Download ZIP. The archive with the example will be downloaded to your PC.
     3. Unzip and copy the files into the directory /usr/local/mgr5/src/.
   • Create a local copy of the repository:

     1. Install GIT:
        

        Ubuntu 20.04, AstraLinux 1.7.4

        apt-get install git

        CentOS 7, AlmaLinux 9

        yum install git

        
        

     2. Clone the BILLmanager repository:

        git clone https://github.com/ISPsystemLLC/billmanager

4. Enter the director:

   cd /usr/local/mgr5/src/billmanager/processing/certificate/sslstore/

5. Run the command:

   command to assemble an example module

   make

   command to assemble and install the module

   make install

6. Restart the platform:

   killall core

After installation, the files with the example module will be located in the directory /usr/local/mgr5/src/billmanager/.

Python

The Python integration module is available since BILLmanager version 6.75.0.

To run Python processing modules and develop your own, install the package:

apt-get install billmanager-plugin-python-libs

yum install billmanager-plugin-python-libs

The following will be installed into the lib/python/billmgr/ directory:

Example of the GlobalSign integration module in Python

You can use one of the suggested ways to assemble and install the module:

1. Enter the directory:

   cd /usr/local/mgr5/src/

2. Get the source code of the example module. This can be done in two ways:
   • Download the archive
     1. Open https://github.com/ISPsystemLLC/billmanager.
     2. Click Code → Download ZIP. The archive with the example will be downloaded to your PC.
     3. Unzip and copy the files into the directory /usr/local/mgr5/src/.
   • Create a local copy of the repository:

     1. Install GIT
        

        Ubuntu 20.04, AstraLinux 1.7.4

        apt-get install git

        CentOS 7, AlmaLinux 9

        yum install git

        
        

     2. Clone the BILLmanager repository:
        

        git clone https://github.com/ISPsystemLLC/billmanager

        
        

3. Run the command: 

   make globalsign

4. Restart the platform:

   killall core

After installation, the files with the example module will be located in the directory /usr/local/mgr5/.