SSL module

From ISPWiki
Jump to: navigation, search

General information

An SSL certificates module allows you to configure SSL certificates that you can offer to your clients. This module implements SSL order, renewal, reissue.

Module at work

  1. An SSL module is set up
  2. The module is integrated with a certification authority
  3. A new tariff plan is created
  4. A client orders and pays for a service
  5. The service is set up
  6. The service is activated/suspended/deleted, etc.

The module can be installed either manually (if it is a list of files), or from repository using the package manager. Once installed, you can choose this module when adding a certification authority in BILLmanager.

Each module sends requests to BILLmanager for supported features and required parameters. This operation is performed each time BILLmanager starts, and the call is sent to the payment module allowing to improve BILLmanager performance, and exclude unsupported calls.

Module structure

The SSL module contains two files:

  • etc/xml/billmgr_mod_XXX.xml - XML description of the module. Be sure to provide a standard filename format.
  • processing/XXX - the main script of the module. Be sure to provide a standard filename format

Where XXX is the name of your module in Latin characters. If the name of the main module contains file extension, it will be included into 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_pmXXX.xml, where XXX - is a module name. The file is placed into the etc/xml directory relative to the BILLmanager installation directory. The file contains description of the module (it is described as a plugin) and additional forms and messages.

Example of the XML file:

<?xml version="1.0" encoding="UTF-8"?>
<mgrdata>
  <plugin name="XXX">
    <group>processing_module</group>
    <params>
      <type name="certificate"/>
    </params>     
    <msg name="desc_short" lang="en">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>
</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 sections with the <type name="certificate"/>sub-node indicating that this handler is an SSL order module, and 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 - brief description of the module, which is displayed in BILLmanager payment form.
  • desc_full - full description of the module, which is displayed in the list of installed modules in COREmanager.

The metadata section named processing.edit.XXX handles additional fields of the module that are displayed when you add or configure the module. It is formed according to standard description of XML forms. Take the note of the location of fields in the <page name="connect"></page> section to ensure 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_paymethod"> section is used to specify the module name.

Main script

The main script passes information about functions supported by the module to BILLmanager, and handles these 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 - control command. Defines an action to be performed by the module.
  • item - service id.
  • module - module id.
  • itemtype - internal name of the product type.
  • 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 operations (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 automatic restart of the operation
  • Add and assign a task to an appropriate Support department by executing the task.edit function

The command parameter may have one of the following values:

  • features - request features supported by the module. The following XML will be sent to stdout:
<?xml version="1.0" encoding="UTF-8"?>
<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"/>                                 <!-- verify parameters that were entered when adding the processing module -->
    <feature name="approver"/>                                         <!-- get a list of administrator's email addresses -->
    <feature name="prolong"/>                                          <!-- renew services with a certification authority -->
    <feature name="usercreate"/>                                       <!-- create an account on a certification authority web-site -->
    <feature name="sync_item"/>                                        <!-- 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 сертификат
    orginfo - organization information is required 
    wildcard - certificate is issued for all subdomains of *.mydomain.com
    www - certificate is issued both for domain.com and  www.domain.com 
    -->
  </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's standard output.

  • approver - request for allowed email addresses.
  • usercreate - register a new account on the certification authority (CA) web-site through BILLmamager.
  • check_connection - send the XML with CA connection parameters. The output document looks like the following:
<?xml version="1.0" encoding="UTF-8"?>
<doc>
  <param>value</param>
  ...
  <param>value</param>
</doc>

Note: 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 XML description of an error, if any. If a success, it should return the following XML:


<?xml version="1.0" encoding="UTF-8"?>
<doc/>
  • tune_connection - the XML containing parameters of the CA connection form is sent to the module's standard input. The XM document with required parameters is sent to its standard output.
  • open - service setup command. The item and runningoperation parameters are also sent to the module (when starting the task in BILLmanager). Once the service is activated, call the domain.open function to complete the operation and delete the task from the list of current operations.
  • suspend - service suspension command. The item and runningoperation parameters are also sent to the module (when starting the task in BILLmanager). Once the service is suspended, call the service.postsuspend function to mark the service Suspended and and delete the task from the list of current operations.
  • resume - service activation command. The item and runningoperation parameters are also sent 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. Theitem and runningoperation parameters are also sent 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 item and runningoperation parameters are also sent 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 item and runningoperation parameters are also sent 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 registrar. The item parameter is also sent. The below functions are used to save parameters.

A script example can be found below.

Structure of linked tables

  • the item table - contains information about services, id - service id, processingmodule - processing module id.
  • the processingmodule table - contains 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

Operations

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

When the module gets the id of current operation, if the command fails, the information about this 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 that will be assigned to BILLmanager staff, complete the following steps:

  1. With the operation parameter, pass the command received from the module to the task.gettype function, and run that function to get a task type.
  2. Run the task.edit function to register the task with

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

BILLmanager functions

  • otparamlist - does not require parameters. The function passes a list of panel configuration parameters.
  • runningoperation.delete -
    • elid - id of the current operation
  • runningoperation.edit - edit parameters of current operation
    • elid - id of the current operation
    • sok=ok - indicates that parameters are saved
    • errorxml - error XML
  • runningoperation.setmanual - set up current operation manually
    • elid - id of the current operation
  • 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.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 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 validity period
    • elid - service id
    • expiredate - new validity period
  • service.setstatus - change additional status of the service
    • elid - service id
    • service_status - new service status
    • sok=ok - indicates that parameters are saved
    • processingmodule - module id
    • type - contact type
    • externalid - contact id on the registrar side
    • externalpassword - contact password on the registrar side (optional)


Service statuses

The service may also get one of the following statuses:

  • 0 - unknown (this status is not used in BILLmanager 5)
  • 1 - the order is not paid (this status is not used in BILLmanager 5)
  • 2 - the order is paid, but not handled (this status is not used in BILLmanager 5)
  • 3 - CRS is sent
  • 4 - the certificate is awaiting issue
  • 5 - the certificate has been issued
  • 6 - error issuing the certificate

Example

This is a fully functional integration module with The SSL Store.

C++ (with the use of BILLmanager libraries)

Starting from version 5.58.0 you can use BILLmanager header files to develop custom processing modules. Beside a simplified example, you can look into examples in the BILLmanager developer package - billmanager-[BILLmanager version]-devel, example:

 yum install billmanager-standard-devel

Then you can find examples in the directory:

/usr/local/mgr5/src/examples

C++

Files:

  • dist/etc/xml/billmgr_mod_pmregistrar.php.xml -
  • processing/certificate/pmthesslstore.cpp - main script
  • processing/certificate/common.h - description of enumerations for BILLmanager 5
  • processing/certificate/defines.h - define macros
  • processing/certificate/module.h - description of classes for creating processing modules BILLmanager 5
  • processing/certificate/module.cpp - implementation of classes for creating processing modules BILLmanager 5
  • processing/certificate/sslutil.h - description of classes for creating SSL certificate templates
  • processing/certificate/sslutil.cpp - implementation of classes for creating SSL certificate templates
  • processing/certificate/util.h - additional functions for working with BILLmanager 5

The example can be found at https://github.com/ISPsystemLLC/billmanager/

Module deployment

Complete the following steps to deploy the module successfully:

  1. Install the package:
    • Debian: apt-get install coremanager-dev
    • CentOS: yum install coremanager-devel
  2. Go to the cd /usr/local/mgr5/src directory
  3. Get the source code of the plug-in:
    • Click Download ZIP at https://github.com/ISPsystemLLC/billmanager to download then and copy the files into the /usr/local/mgr5/src directories
    • Install GIT. Debian: apt-get install. CentOS: yum install git. Clone the repository billmanager git clone https://github.com/ISPsystemLLC/billmanager
  4. Go to the cd /usr/local/mgr5/src/billmanager/processing/certificate directory
  5. Get the make plug-in, or setup make install