Overview

The External Signing CA plugin's purpose is to generate certificate and private key pairs signed by a Certificate Authority. By using this type of plugin the certificate signing can be tailored to fit any custom requirement.

Details

The plugin is a .zip file containing a MANIFEST and a main.py file.

The MANIFEST file

The MANIFEST file is a YAML file, and should conform to version 1.2 of the YAML specification. It should contain the following information about the plugin:

api: 1.0
type: signingca
name: MySigningCaPlugin
version: 1.0
description: My custom Signing CA

The type of the plugin must be signingca.

The main.py file

A Plugin class containing the following methods must be defined in the main.py file:

  • generate_for_addresses: generates a key/certificate pair for the given addresses (IP/DNS)

  • generate_for_username: generates a key/certificate pair for the given username

  • generate_for_subject: generates a key/certificate pair for the given subject values

Method arguments

Each method must take the following arguments:

  • generate_for_addresses:

    • addresses: {list of str} - contains either IP or DNS addresses for which the certificate shall be issued

    • keytype: {str} - contains a fixed value of 'RSA' or 'DSS' indicating the requested key type for the certificate

  • generate_for_username:

    • username {str} - contains the username for which the certificate shall be issued

    • keytype: {str} - contains a fixed value of 'RSA' or 'DSS' indicating the requested key type for the certificate

  • generate_for_subject:

    • subject {list of (str, str)} - contains the certificate subject as type-value pairs (tuples). Valid types are the following:

      • 'C' country name

      • 'ST' state or province name

      • 'L' locality name

      • 'O' orangization name

      • 'OU' organizational unit

      • 'CN' common name

      • 'emailAddress' email address

    • keytype: {str} - contains a fixed value of 'RSA' or 'DSS' indicating the requested key type for the certificate

Method return values

Each method returns a {dict} that must have the following keys:

  • key: {str} the generated key

  • chain: {list of str} a PEM encoded certificate chain containing the generated certificate as the first element

Example

The code below demonstrates a simple plugin that can sign certificates with a built in CA. By default it uses a pre-generated CA certificate and key to complete signing requests. To use a custom certificate, provide a certificate and a key in a python dict format in the configuration field.

NOTE: If you wish to try this sample code, you will need to provide a MANIFEST file (see below) and the following package dependencies in the .zip file alongside the plugin:

  • asn1crypto

  • certbuilder

  • oscrypto

main.py: 

#!/usr/bin/env pluginwrapper3

#
# Copyright (c) One Identity
# All Rights Reserved.
#

from ast import literal_eval
from certbuilder import CertificateBuilder, pem_armor_certificate
from ipaddress import ip_address
from oscrypto import asymmetric

class Plugin(object):

    plugin_root_ca = """-----BEGIN CERTIFICATE-----
MIIDhjCCAm6gAwIBAgIIW+mOlk1Cu4swDQYJKoZIhvcNAQELBQAwYTELMAkGA1UE
BhMCSFUxETAPBgNVBAgMCEJ1ZGFwZXN0MREwDwYDVQQHDAhCdWRhcGVzdDEQMA4G
A1UECgwHQmFsYWJpdDEaMBgGA1UEAwwRQmFsYWJpdCBQbHVnaW4gQ0EwHhcNMTgx
MTEyMTQzMDQ2WhcNMTkxMTEyMTQzMDQ2WjBhMQswCQYDVQQGEwJIVTERMA8GA1UE
CAwIQnVkYXBlc3QxETAPBgNVBAcMCEJ1ZGFwZXN0MRAwDgYDVQQKDAdCYWxhYml0
MRowGAYDVQQDDBFCYWxhYml0IFBsdWdpbiBDQTCCASIwDQYJKoZIhvcNAQEBBQAD
ggEPADCCAQoCggEBAO73W0ONVwIaBJas+qUe0VBZ4rtk6PtzRNenZcBkTCkITuuF
DAQ3T1qLUsCyQ4uHMo+yKZUqR3HxbWGxS2l4IaHP6Hbna2kNEyYEsg16mGVUz6tc
D6bxFu3EpB7eU/OXh8RS8URIfZbLNrql1sKe7k1hpXUDS74Ra/avUIYKIpZ5sCjs
F6MBZWz5u3tNUa53xVmqgpnQ6pozN+OQ6k74DjK4xqWqJgTWcN6rxZ9k2voQYE3s
H66jl53q+Zl0D4w/AEW5W3OYNHJtx3tsc36sD2i0doqBCAAvflcSDEs7TXhfXSkC
qCBKyx8ics5EL9h49MDPGwDTehzwvXusz8LlxeMCAwEAAaNCMEAwDwYDVR0TAQH/
BAUwAwEB/zAdBgNVHQ4EFgQUyFWUMJli0q5CtJOp25IqK2M70oAwDgYDVR0PAQH/
BAQDAgEGMA0GCSqGSIb3DQEBCwUAA4IBAQCWoQCJPqfM4Sjg0R2O42yrE2GtQsXf
Qb3Dur+CefWLcvjI28t1xuj31khDgpNTwk4IVYrvarNX33C3tjYKgcimwWRMijbA
p8kZzFajOZSWC32CQtkWL79LLkJCTJB7b/4E41oNQPHtOoNCqFY+uQogP90qZ1w1
xlFX8ie/W3cuqhfzW6+/M3iCIwdjhBquvOo6mE3t2/lUcGXE20GayFsKnEmgpDJa
nxoG1+m+s5zCwDuukX8Lr1O7maTMwNVhm5P5QWeEPbGRN7yw+CfzcvPIbFYwnZ5x
XeC9Vtoj2Jbom8RV9uus8R5LfYBJ+HZh74wbGhIC2Kf9LrJTK7r92uVA
-----END CERTIFICATE-----"""

    plugin_root_ca_key = """-----BEGIN PRIVATE KEY-----
MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQDu91tDjVcCGgSW
rPqlHtFQWeK7ZOj7c0TXp2XAZEwpCE7rhQwEN09ai1LAskOLhzKPsimVKkdx8W1h
sUtpeCGhz+h252tpDRMmBLINephlVM+rXA+m8RbtxKQe3lPzl4fEUvFESH2Wyza6
pdbCnu5NYaV1A0u+EWv2r1CGCiKWebAo7BejAWVs+bt7TVGud8VZqoKZ0OqaMzfj
kOpO+A4yuMalqiYE1nDeq8WfZNr6EGBN7B+uo5ed6vmZdA+MPwBFuVtzmDRybcd7
bHN+rA9otHaKgQgAL35XEgxLO014X10pAqggSssfInLORC/YePTAzxsA03oc8L17
rM/C5cXjAgMBAAECggEBAIucxpw76naW3tFtNG7eB2pLaZUUSq4F1VWtPlxd/MUI
Tpt5OuEHs3vx5CIixCWzkk2zyGmWrvEaHU6zN5ziC7wu7ODzKaTRd7uBiMkpM/oX
x9CU06w0NLIrbbt/J0ss36xKzRyYwY8lIM+Bbmx8UDuzbehkSY89PHd+S6xUJYsF
YmOVM00wx1N6yZGKHUV9GLRnysHb+DBbjGIcjDqmlsdyuAzlB7/DAeToLFNkZvzx
Qzza6whMILXS9Qp39dzn7nJuJywfoOAX2q5LgOrPise2QY1FuAy0GTfqvBDR1eGd
NwFW5YtH89l347AIDPgklKvKaii2iIw1ZEMf1AlX7mECgYEA+0JM9sToMgLhHJDj
cUsznVn3xzjDT/4O95LdAq1fVrn10wh/SwGCBBPMHQkV1nS70d//1aGctZLWk5+F
K3aPGV9Eas70mOGNcXdU1ITpFNuVfbKK8uH5NF/oEuoD4zRabunrj/zEk0Qu/D9v
pN4qEwJoV1SD/9HpfpaUG/xuBLECgYEA83mtE34zYTY2TLBr4HvoiWrFYoEpPldN
64oD+w1/D0Wd9hxCyzO3y2SmrBmmbzoawTckxD/VKndeRdV5dLlEnAV4F35bPsQl
dRJJEAAQPqqc1z4x6c2my27WPSbm4mIcvfTc65UFu4ovm/koywc96fwvpTX6JIN1
X8zHZ/tQaNMCgYEAl3yk3I9hk22K/ecZSiBWEUPCETpW/66kpX3FhKy085wQ61iP
LtDM69pn0QW+RduBtgsAu3PCAPN0LfManlbP9jMrE96NOHOdDNEusycjRHET04JH
JiM6VeqRCH5RM7ZH4+FjJh/3APc2AN3aWSOdaHKmKCkLoLyVs73jtG/ggTECgYBp
reCf22E1yrAa7WCFmYK/UqbGMMXUF1Ts7YT4zUzfNhpwHqgnRxV5pQBrJt8E3DWM
tACzZfmCazlyGkyTi27qQb10hRXZ0o1nmT45Qa3LZYaaLpa/otHI7xzyghYpIOjU
0pmpb4+DbWFo0+cO6N/I1ftgPGOMwbqKkHnk+kJWnQKBgQDQwITXna8OVjn86AQP
m36JHXi0RNVO/x4+b8T7nurU6XCPIzE0PxfVVSXXsbKTWlq48GIw9ZNpPKPSTCQy
fnYC+Pcu+4A+bfUwFk21khnN/fP5vyFlFhTrGneZeKWhUxv5iOqASEaizfOePmtj
et/4B9LUf9KQFstlhuIR4AP2OA==
-----END PRIVATE KEY-----"""

    def __init__(self, configuration=""):
        self.cert_x509name = {
            'country_name': 'HU',
            'state_or_province_name': 'Budapest',
            'locality_name': 'Budapest',
            'organization_name': 'One Identity',
            'common_name': '',
        }
        self.cert_alt_domains = []
        self.cert_alt_ips = []

        if configuration is not "":
            try:
                configdict = literal_eval(configuration)
                self.plugin_root_ca = configdict['ca']
                self.plugin_root_ca_key = configdict['key']
            except Exception:
                pass

        self.root_ca_certificate = asymmetric.load_certificate(bytes(self.plugin_root_ca, 'utf-8'))
        self.root_ca_key = asymmetric.load_private_key(bytes(self.plugin_root_ca_key, 'utf-8'))

    def _sign_certificate(self):
        end_entity_public_key, end_entity_private_key = asymmetric.generate_pair(self.cert_keytype, bit_size=2048)
        end_entity_private_key = asymmetric.dump_private_key(end_entity_private_key, None)
        end_entity_subject = self.cert_x509name

        builder = CertificateBuilder(
            end_entity_subject,
            end_entity_public_key
        )

        builder.subject_alt_domains = self.cert_alt_domains
        builder.subject_alt_ips = self.cert_alt_ips
        builder.issuer = self.root_ca_certificate
        end_entity_certificate = builder.build(self.root_ca_key)
        end_entity_certificate = pem_armor_certificate(end_entity_certificate)
        return end_entity_certificate, end_entity_private_key

    _subject_type_mapping = {
        'C': 'country_name',
        'ST': 'state_or_province_name',
        'L': 'locality_name',
        'O': 'organization_name',
        'OU': 'organizational_unit_name',
        'CN': 'common_name',
        'emailAddress': 'email_address',
    }

    def _set_certificate_x509_name(self, x509name):
        for (t, v) in x509name:
            self.cert_x509name[self._subject_type_mapping[t]] = v

    def _set_certificate_keytype(self, keytype):
        # Certbuilder lists DSS key as DSA so we have to translate the string here
        if keytype == "dss": keytype = "dsa"
        if keytype not in ['dsa', 'rsa']:
            raise ValueError('Certificate type should be either \'rsa\' or \'dss\'')
        else:
            self.cert_keytype = keytype

    def _set_certificate_cn(self, cn):
        self.cert_x509name['common_name'] = cn

    def _set_certificate_addresses(self, addresses):
        for address in addresses:
            try:
                ip_address(address)
                self.cert_alt_ips.append(address)
            except ValueError:
                self.cert_alt_domains.append(address)

    def _build_response(self, cert, key):
        return {'key': key.decode('ascii'), 'chain': [cert.decode('ascii'), self.plugin_root_ca]}

    def generate_for_addresses(self, addresses: list, keytype: str):
        self._set_certificate_keytype(keytype)
        self._set_certificate_addresses(addresses)
        self._set_certificate_cn(addresses[0])
        return self._build_response(
            *self._sign_certificate()
        )

    def generate_for_username(self, username: str, keytype: str):
        self._set_certificate_keytype(keytype)
        self._set_certificate_cn(username)
        return self._build_response(
            *self._sign_certificate()
        )

    def generate_for_subject(self, x509name: list, keytype: str):
        self._set_certificate_keytype(keytype)
        self._set_certificate_x509_name(x509name)
        return self._build_response(
            *self._sign_certificate()
        )

Use the following snippet as the MANIFEST file:

# Name of the plugin, may contain [a-zA-Z0-9]
name: HelloSigningCaPlugin

# Version of the plugin, only for display purposes
version: 0.1

# Type of the plugin - this is a signingca plugin
type: signingca

# API version of the SCB the plugin was written for, in major.minor format
api: 1.0

# Free form description.
description: This is an example plugin used for testing.

# Entry point for the plugin (also for running with python3)
entry_point: main.py