How to add SSL certificate module

The SSL certificate sales module is responsible for a set of connection settings and types of certificates sold. The module also implements mechanisms for ordering, renewing, and reissuing SSL certificates.

General information

Module commands

SSL certificate modules are a special case of service processing modules with itemtype name="certificate". Specific commands:

• approver;
• usercreate;
• reopen.

The module processes other commands (open, suspend, close, setparam, prolong, sync_item) according to the standard algorithm for all service processing modules.

Main commands:

• open — service creation;
• suspend — service suspension;
• resume — service resumption;
• close — service deletion;
• setparam — changing service parameters or tariff;
• prolong — service renewal;
• sync_item — synchronizing service status with an external system. Used with the parameter --item;
• check_connection — checking connection parameters to an external system;
• tune_connection — modifying the form for adding a processing module.

Additional commands:

Specific commands for SSL certificates:

• approver — obtaining email addresses for domain ownership confirmation;
• usercreate — creating an account in the certification authority;
• reopen — reissuing a certificate.

Explanations for the SSL certificate module XML file

features — additional section <templates>

< doc >
< itemtypes >< itemtype name = "certificate" /></ itemtypes >
< params >...</ params >
< features >...</ features >
< templates >
< template name = "securesite" multidomain = "yes" orginfo = "yes" />
< template name = "wildcard" wildcard = "yes" www = "yes" />
</ templates >
</ doc >

Attributes:

• multidomain;
• wildcard;
• www;
• orginfo;
• csraltname.

approver — output

< doc >
< email >admin@example.com</ email >
< email >hostmaster@example.com</ email >
</ doc >

usercreate — input and output

Input — accepts the current form XML file (standard BILLmanager form description).
Output — returns the modified XML file. You can add fields, attributes, hints.

check_param — input and output

Input — accepts the current form XML file.

<doc>
<item> <!-- List of old service parameter values. -->
<param1>...</param1>
...
<paramN>...</paramN>
</item>
<newitem> <!-- List of new service parameter values. -->
<param1>...</param1>
...
<paramN>...</paramN>
</newitem>
</doc>

Output — returns <doc/> or an error.

< doc >
< error type = "field" field = "altname" value = "Invalid domain" />
</ doc >

Module operation mechanism

Stages of working with the SSL certificate module in BILLmanager:

1. Initial configuration:
   1. Module installation.
   2. Adding a connection to the certification authority.
   3. Tariff plan configuration.
2. Service workflow:
   1. Ordering and paying for the service.
   2. Processing service opening.
   3. Enabling, disabling, deleting the service, and performing additional operations.

Install the module:

• manually, if it is provided as a set of files;
• from the standard repository using a package manager.

After installation, the module becomes available for selection when creating a payment method in BILLmanager.

The platform polls each module at startup to learn about supported features and required parameters. This speeds up operation: unsupported calls are excluded.

Module structure

The standard set of module files looks as follows:

Where XXX is the name of your module in Latin characters. If the name of the main module script contains a file extension, it is also included in the module name. For example, if your script is named pmresellerclub.php, then the module name will be pmresellerclub.php, not resellerclub or pmresellerclub.

XML description

The file name must be in the format billmgr_mod_XXX.xml, where XXX is the module name. The file is copied to the directory /usr/local/mgr5/etc/xml/. The file contains a description of the module itself (described as a plugin), as well as descriptions of additional forms and messages.

<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 is responsible for describing the module itself. The name property matches the name of the SSL certificate ordering module. Inside the section there can be one:
  • element group with the value processing_module, which indicates that this module is used for service handlers;
  • section params with a child element <type name="certificate"/>, which indicates that the handler belongs to SSL certificate ordering modules, i.e. it can process services with the internal name certificate;
  • several msg elements. The lang property in the msg element indicates which language the message belongs to; the name attribute can have the following values:
    • desc_short — brief module description. Displayed when selecting a module in BILLmanager;
    • desc_full — full module description. Displayed when building a list on the service handler addition form in BILLmanager.
• The metadata section with the name processing.edit.XXX is responsible for additional module fields when adding and configuring a handler. Formed according to the standard XML form description. When forming, it takes into account the need to place fields in the section <page name="connect"></page> for correct placement of fields on forms in BILLmanager.
• The lang section contains translations of field names on the form according to the standard translation description scheme. The section <messages name="label_processing_modules"> is responsible for the module name label in the handler list.

Main module script

The main processing module script is responsible for:

• passing information about the functions that the module supports to BILLmanager,
• processing supported functions.

When working with the module, 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 — control command. Indicates the action that the module needs to perform;
• item — service code for which the action is performed;
• module — handler code for which the action is performed;
• itemtype — internal name of the product type for which the action is performed;
• param — parameter name;
• value — parameter value;
• runningoperation — code of the current operation for the performed action. Required for changing parameters of the current operation, as well as for creating tasks;
• domain — domain name for which the certificate is issued.

The runningoperation parameter is passed if the module is launched by BILLmanager after creating the current operation. After the module works in this case, you need to either execute one of the BILLmanager functions described in the section Functions. This function will remove the current operation from the queue, or perform one or more of the following actions:

• save the error text in the properties of the current operation using the function runningoperation.edit;
• set the current operation to manual launch to prevent automatic restart of this operation using the function runningoperation.setmanual;
• create a task for the responsible department using the function task.edit.

The command parameter can take one of the following values:

• features — request for a list of supported features. In response to calling this command, the module must return an XML document of the following type:

<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"/>                                 <!-- Module support for connection parameter verification function when adding a service handler. -->
    <feature name="approver"/>                                         <!-- Module support for obtaining a list of administrator email addresses. -->
    <feature name="prolong"/>                                          <!-- Support for service renewal on the certification authority side. -->
    <feature name="usercreate"/>                                       <!-- Module support for a function that allows creating an account in the certification authority. -->
    <feature name="sync_item"/>                                        <!-- Support for obtaining certificate information from the certification authority. -->
 </features>
 <templates>
    <!-- List of 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 with support for alternative domain names
    orginfo - certificate requires organization information
    wildcard - certificate is issued for all subdomains *.mydomain.com
    www - certificate is issued for domain.com and www.domain.com
    
    Domain ownership verification methods:
    authemail - by email;
    authcname - via DNS CNAME;
    authfile - via HTTP(S).
    -->
  </templates>
</doc>

If the module does not support the described functions, do not specify them in the response to the features command. Otherwise, service processing errors may occur.

• approver — request for a list of allowed administrator email addresses;
• usercreate — register an account on the certification authority side through the BILLmanager interface;
• check_connection — an XML document with connection parameters to the certification authority is supplied to the module input. The format of the input document looks as follows:

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

Regardless of module requirements, parameters are presented in unencrypted form.

Using these parameters, the module must verify the possibility of using them to connect to the certification authority and in case of an error return its XML description. In case of success, it is necessary to return an XML document of the form:

<doc/>

• tune_connection — an XML document of the current description of the connection form to the certification authority is passed to the handler input; an XML document with the necessary changes must be passed to the output;
• open — service opening command. The module is also passed the parameters item and runningoperation (when launching a BILLmanager task). After processing service opening, it is necessary to call the function certificate.open to complete service processing and remove the task from current operations;
• reopen — SSL certificate reissue command. The module is also passed the parameters item and runningoperation (when launching a BILLmanager task). After processing service opening, it is necessary to call the function service.postreopen to complete service processing and remove the task from current operations;
• suspend — service disabling command. The module is also passed the parameters item and runningoperation (when launching a BILLmanager task). After disabling the service, it is necessary to call the function service.postsuspend to change the service status to Suspended and remove the task from current operations;
• resume — service enabling command. The module is also passed the parameters item and runningoperation (when launching a BILLmanager task). After enabling the service, it is necessary to call the function service.postresume to change the service status to Active and remove the task from current operations;
• close — service deletion command. The module is also passed the parameters item and runningoperation (when launching a BILLmanager task). After deleting the service, it is necessary to call the function service.postclose to change the service status to Deleted and remove the task from current operations;
• setparam — command to change service parameters or tariff. The module is also passed the parameters item and runningoperation (when launching a BILLmanager task). After changing service parameters, it is necessary to call the function service.postsetparam to save the new tariff plan, update the service cost for display in the list, and remove the task from current operations;
• prolong — command to extend the service validity period. The module is also passed the parameters item and runningoperation (when launching a BILLmanager task). After renewing the service, it is necessary to call the function service.postprolong to remove the task from current operations;
• sync_item — command to obtain service information from the certification authority. The module is also passed the parameter item. Saving parameters is performed using the functions certificate.save, described below. In case of a certificate issuance error, you can notify the client about it using the function certificate.failed;
• check_param — command to check service parameters when they are changed. The module is passed the parameters:
  • item — service code;
  • param — parameter name (passed only for some built-in parameters);
  • value — parameter value (passed only for some built-in parameters);
  • level — access level of the user who changed the parameters;

An XML document containing the old and new values of service parameters is also supplied to the module input.

Structure of related tables

Tables:

• item — contains basic information about services. Fields:
  • id — service code;
  • processingmodule — handler code;
• certificate — contains certificate data. Fields:
  • item — service code;
  • csr — text of the certificate issuance request;
• processingmodule — contains basic information about the service handler. Fields:
  • id — handler code;
• processingparam — contains parameters of the handler module. Fields:
  • processingmodule — handler code;
  • intname — parameter name;
  • value — value;
• processingcryptedparam — contains encrypted parameters of the handler module. Fields:
  • processingmodule — handler code;
  • intname — parameter name;
  • value — encrypted value.

Working with current operations

Before passing most module requests, BILLmanager creates an operation. If the previous attempt to execute the operation ended unsuccessfully and automatic restart is enabled, BILLmanager will restart the operations. The operation code is passed to the module as the runningoperation parameter and may be absent.

If the module receives the current operation code, in case of an error processing the command, you can save information about it in the parameters of the current operation.

To display an error in BILLmanager, use the function runningoperation.edit.

To switch the operation launch to manual mode, use the function runningoperation.setmanual.

To create a task based on the current operation for its resolution by a BILLmanager administrator:

1. Obtain the task type using the function task.gettype. Pass the command received by the module to the function using the parameter operation.
2. Register the task using the function task.edit

After that, the task will appear in the list for employees belonging to the responsible department specified in the handler settings.

BILLmanager functions

• paramlist — returns a list of platform configuration parameters. Does not require parameters;
• runningoperation.delete — deleting the current operation. Parameters:
  • elid — current operation code;
• runningoperation.edit — changing parameters of the current operation. Parameters:
  • elid — current operation code;
  • sok=ok — flag for saving parameters;
  • errorxml — XML of the occurred error;
• runningoperation.setmanual — switch the current operation to manual launch mode. Parameters:
  • elid — current operation code;
• certificate.open — operation to complete service opening. Changes the service status to "active", sends a letter to the client about completion of service processing, and removes the opening operation. Parameters:
  • elid — service code;
  • sok=ok — flag for saving parameters;
• service.postclose — operation to complete service deletion. Changes the service status and removes the deletion operation. Parameters:
  • elid — service code;
  • sok=ok — flag for saving parameters;
• service.postopen — operation to complete service opening. Removes the service opening operation. Parameters:
  • elid — service code;
  • sok=ok — flag for saving parameters;
• service.postreopen — operation to complete SSL certificate reissue. Removes the certificate reissue operation. Parameters:
  • elid — service code;
  • sok=ok — flag for saving parameters;
• service.postprolong — operation to complete service renewal. Removes the service renewal operation. Parameters:
  • elid — service code;
  • sok=ok — flag for saving parameters;
• service.postresume — operation to complete service enabling. Changes the service status and removes the enabling operation. Parameters:
  • elid — service code;
  • sok=ok — flag for saving parameters;
• service.postsetparam — operation to complete changing service parameters. Resets the reference to the previous tariff plan, removes the current operation, and updates the service cost for display in the list. Parameters:
  • elid — service code;
  • sok=ok — flag for saving parameters;
• service.postsuspend — operation to complete service disabling. Changes the service status and removes the disabling operation. Parameters:
  • elid — service code;
  • sok=ok — flag for saving parameters;
• service.saveparam — saves an arbitrary service parameter. Parameters:
  • elid — service code;
  • name — internal parameter name;
  • value — parameter value;
• service.setexpiredate — changes the service validity period. Parameters:
  • elid — service code;
  • expiredate — new service validity period;
• service.setstatus — changes the additional service status. Parameters:
  • elid — service code;
  • service_status — new service status;
• certificate.save — saves data of the issued certificate in BILLmanager. Parameters:
  • elid — service code;
  • crt — certificate data;
  • crt_type — type of certificate data. Empty value for text representation of the certificate. When saving, the type (file extension) of the archive is passed, and the file contents are passed in base64 encoding;
• certificate.failed — saves data about a certificate issuance error in BILLmanager. Parameters:
  • elid — service code.

Service statuses

The additional service status can take the following values:

• 0 — unknown;
• 1 — ordered, not paid;
• 2 — paid, not processed;
• 3 — certificate request sent;
• 4 — certificate awaiting issuance;
• 5 — certificate issued;
• 6 — error during certificate issuance.

Additional service parameters

• altname — alternative domains for SAN certificates;
• old_altname — previous list of alternative names. Saved in the database in case of SSL certificate reissue with a change in the list of alternative domains for SAN certificates;
• approver_email — email addresses for confirming ownership of the domain specified in the certificate;
• custom_order_id — certificate code on the certification authority side;
• service_status — current additional service status;
• approver_method — domain ownership verification method. Can take values:
  • auth_email — by email;
  • auth_cname — by DNS CNAME record;
  • auth_file — by HTTP(S).

Features of SAN certificate processing

Processing SAN certificates has the following differences from processing other types of certificates:

• the list of email addresses for confirming domain ownership is stored in one parameter approver_email. Addresses are listed via comma in the same order as the additional domains are specified. At the same time, the confirmation email address for the main domain is always specified first;
• when processing SSL certificate reissues, you need to pay attention to the service parameter old_altname. If it is not empty, certificate reissue with a change in the list of additional domains is used. The new list of domains is stored in the parameter altname. The list of domains specified before reissue — in the parameter old_altname.

Module examples

Examples of processing modules in C++ and Python are available in the repository https://github.com/ISPsystemLLC/billmanager/

C++

C++ (using BILLmanager libraries)

In addition to the provided example, you can study examples from the BILLmanager developer package. BILLmanager contains libraries necessary for working with modules in C++. To develop your own processing modules:

1. Connect to the server with the platform via SSH. For more details on connecting via SSH, see the article Workstation setup.
2. Install the software package:

apt-get install billmanager-corporate-dev

dnf install billmanager-corporate-devel

After installation, the package contents will be available in the following directories:

Example of The SSL Store integration module in C++

The example contains a module for integration with The SSL Store.

To build and install the module:

1. Connect to the server with the platform via SSH. For more details on connecting via SSH, see the article Workstation setup.

2. Install the software package:

   Ubuntu, AstraLinux:

   apt-get install coremanager-dev

   AlmaLinux:

   dnf install coremanager-devel

3. Navigate to the directory:

   cd /usr/local/mgr5/src

4. Obtain the module example source code. This can be done in two ways:
   • Download the archive:
     1. Navigate to the page 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 received files to the directory /usr/local/mgr5/src/.
   • Create a local copy of the repository:

     1. Install GIT:

        Ubuntu, AstraLinux:

        apt-get install git

        AlmaLinux:

        dnf install git

     2. Clone the BILLmanager repository:

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

5. Navigate to the directory:

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

6. Execute the command:

   Command to build the module example

   make

   Command to build and install the module

   make install

7. Restart the platform:

   /usr/local/mgr5/sbin/mgrctl -m billmgr -R

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

Python

The integration module in Python is available starting from BILLmanager version 6.75.0 and higher.

To work with processing modules in Python and develop your own:

1. Connect to the server with the platform via SSH. For more details on connecting via SSH, see the article Workstation setup.
2. Install the package:

apt-get install billmanager-plugin-python-libs

dnf install billmanager-plugin-python-libs

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

Example of GlobalSign integration module in Python

To build and install the module, you can use one of the proposed methods:

1. Connect to the server with the platform via SSH. For more details on connecting via SSH, see the article Workstation setup.

2. Navigate to the directory:

   cd /usr/local/mgr5/src/

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

     • Install GIT:

       Ubuntu, AstraLinux:

       apt-get install git

       AlmaLinux:

       dnf install git

     • Clone the BILLmanager repository:

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

4. Execute the command:

   make globalsign

5. Restart the platform:

   /usr/local/mgr5/sbin/mgrctl -m billmgr -R

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