Agilicus Connector

Overview

Applications generate a valid certificate. You can export this certificate for integration with other systems whenever it is issued or rotated. For example, VTScada requires a valid certificate for the server to be enabled with SSL.

Requirements

The connector associated with the application invokes a script when it learns about a new certificate.
  – The script must be accessible by the connector (e.g. on the same machine)
  – The script must be executable by the connector
  – You are responsible for ensuring the execution environment for the script

 For example, for the connector to execute a Python script, Python must be installed on the machine, and the machine must be configured to associate .py files with the Python interpreter. You are also responsible for installing any supporting packages used by your script.

Windows Python Installation

The Agilicus connector runs as a service. In order for the connector to invoke the Python script, Python must be installed on the local machine for all users. See https://docs.python.org/3/using/windows.html

Once Python is installed, the connector will look for a script in the directory: C:\Program Files\agilicus\agent\plugins\certificate-exporter.py

If there is no script found, no export will occur.

Windows Example Script

An example script is shown below, which will import the script as a .p12 file and store it into the Local Machine certificates storage.

import sys
import json
import base64
import tempfile
import subprocess
import os

# load the certificate export json from stdin
# see https://agilicus.com/www/api/certificate-export.schema.json
cert_obj = json.loads(sys.stdin.readline())

def import_certificate(obj):
    # create a temporary file. It must be closed
    # after write before calling certutil.
    tmp = tempfile.NamedTemporaryFile(delete=False)
    try:
        # retrieve the pkcs12 and base64 decode it
        pkcs12 = base64.b64decode(obj.get("pkcs12_b64"))

        # write the pkcs12 to the temporary file
        tmp.write(pkcs12)
        
        # close the file
        tmp.close()

        # now import the pkcs12 file into the local machine account
        subprocess.run(
            ["certutil",
             "-f",
             "-p",
             obj.get("pkcs12_password"),
             "-importpfx",
             tmp.name,
             ]
        )
    except Exception as exc:
        print(exc)
        raise exc
    finally:
        # after completion, delete the pkcs12 file
        os.unlink(tmp.name)

import_certificate(cert_obj)

Programming Interface Details

The json document includes the PKCS #12-encoded certificate bundle and private key, as well as the pem-encoded certificate and private key, and various pieces of supporting data. To view the full details, consult the json definition for the json schema.