Guide to Third-Party AutoSSL Provider Modules

#Name your module properly as a submodule of the Provider parent module::
package Cpanel::SSL::Auto::Provider::ExampleSSLProvider;

use strict;
use warnings;

use parent qw( Cpanel::SSL::Auto::Provider );

# This example uses CPAN modules here as much as possible for clarity.
# You can write your own custom parsers or requesters if necessary.

use HTTP::Tiny             ();
use JSON::MaybeXS          ();
use Crypt::X509            ();
use Crypt::OpenSSL::RSA    ();
use Crypt::OpenSSL::PKCS10 ();

# Set the DAYS_TO_REPLACE value to a reasonable window for the domain to begin requesting a new free certificate (as you may queue the DCV check).
# This ensures a seamless SSL coverage experience for users of your free certificates (instead of them having coverage gaps waiting on DCV).

sub DAYS_TO_REPLACE { return 15; }

# Set the MAX_DOMAINS_PER_CERTIFICATE value to whatever maximum you allow within your signing infrastructure for DV certificates.
# For example, Let's Encrypt has a limit of 100 domains that can be on any given CSR they'll sign.

sub MAX_DOMAINS_PER_CERTIFICATE { return 100; }

# The DISPLAY_NAME value defines what your SSL Provider name will look like in the cPanel & WHM UIs and AutoSSL logs.

sub DISPLAY_NAME { return 'Example SSL Provider for Testing Purposes'; }

# The logic in the CERTIFICATE_IS_FROM_HERE subroutine accepts an SSL certificate string (in PEM format) and should determine if your provider generated the certificate.
# Retuns 1 if yes, 0 if no.

sub CERTIFICATE_IS_FROM_HERE {

    my ( $self, $cert_pem ) = @_;

    # To parse a PEM-encoded certificate file, you may want to use a module such as Crypt::X509 from CPAN. See http://search.cpan.org/~ajung/Crypt-X509-0.51/lib/Crypt/X509.pm

    my $parsed_certificate = Convert::X509->new($cert_pem);

    # This subroutine looks at the organization that signed the cert, but you can use other criteria as necessary.
    # For example, you can confirm if the validity period for your certificate matches the product type of your free certificate offering.
    # The Convert::X509 module contains 'to' and 'from' subroutines for such checks.

    my $provider_name = "Example Signing Organizaton, pty";
    return ( $parsed_certificate->issuer =~ m/$provider_name/ ) ? 1 : 0;
}

# The optional get_vhost_dcv_errors method allows a provider to perform Domain Control Validation (DCV) as part of the AutoSSL vhost processing. When this method runs correctly, AutoSSL not pass domains to {{renew_ssl_for_vhosts()}} which fail the provider’s DCV. This can mitigate situations where cPanel & WHM’s local DCV succeeds but the provider or CA’s DCV fails.

sub get_vhost_dcv_errors {
    my ( $self, %opts ) = @_;
    my @dcv_errors;
    for my $domain ( @{ $opts{'domains'} } ) {
        my @these_dcv_errors = _check_domain_for_dcv($domain);
        push @dcv_errors, \@these_dcv_errors;
    }
    return \@dcv_errors;
}

# Replace the following _check_domain_for_dcv placeholder with the external DCV logic as needed.

sub _check_domain_for_dcv {
    return;    # returns list of errors, no errors = success
}

# The renew_ssl_for_vhosts function is where the system makes a request to your servers, and then performs the necessary actions.
# This example assumes that the DCV happens *instantaneously* and the provider returns a certificate (as with the Let's Encrypt provider).
# If your provider cannot do this, we recommend that you create a companion script that references a queue for installing SSL certificates.

# The autossl binary passes to this function the account and a hash containing information on all vhosts and domains that they contain.
# The function can return anything, but it should probably return undef, because nothing checks the return value. If an error occurs, it should throw an exception/die.

sub renew_ssl_for_vhosts {
    my ( $self, $account_name, %vh_domains ) = @_;

    # Generate the key for the cPanel account. See https://metacpan.org/pod/Crypt::OpenSSL::RSA for more information.
    # The /dev/random file exists on all supported platforms, so you should not need to use Crypt::OpenSSL::Random's random_seed function or importing that seed.

    my $key = Crypt::OpenSSL::RSA->generate_key(2048);
    my ( $csr, $cert, $payload, $res );

    # Each vhost on the account requires a separate CSR, because cPanel & WHM's Apache stack only allows one certificate per vhost.

    foreach my $vhost ( keys(%vh_domains) ) {

        # The following line creates the CSR for the vhost

        $csr = _create_csr_for_vhost( $key, @{ ( $vh_domains{$vhost} ) } );

        # The following line generates any additional data that you want to send to your HTTP certificate-requesting endpoint.
        # This example assumes that you will POST data along with your CSR, but you can do whatever is necessary.

        _generate_dcv_files( $csr, @{ ( $vh_domains{$vhost} ) } );

        # The following section requests the signed certificate.

        $payload = { 'validation_type' => 'dcv', 'csr' => $csr };
        $res     = HTTP::Tiny->new()->post_form( 'https://some.url.endpoint/my_ssl_api', $payload );
        $res     = $res->{content} if length $res->{content};
        $res     = JSON::MaybeXS::decode_json($res);

        # If the module has not already thrown an exception by now, the server should receive a certificate.
        # The following lines will install that certificate.

        $res = eval { $self->install_certificate( 'web_vhost_name' => $vhost, 'certificate_pem' => $res->{'cert'}, 'key_pem' => $key->get_private_key_string() ); };
        warn $@ if $@;
    }

    # At this point, the AutoSSL logger will report a success message to the user regarding the AutoSSL check *for this account*.
    # The module will write to autossl log any exceptions or warnings that the module threw earlier.

    return;

}

# The following skeleton function creates a CSR for a vhost.
# See https://metacpan.org/pod/Crypt::OpenSSL::PKCS10 for a CPAN module that can help here.

sub _create_csr_for_vhost {
    my ( $key, @domains ) = @_;
    my $req = Crypt::OpenSSL::PKCS10->new_from_rsa($key);

    # Add whatever extensions or other items that you need for your request.

    foreach my $domain (@domains) {

        # Add whatever actions you might need to add per domain for your request.

    }

    # Get the CSR in PEM format for us to return.

    my $csr = $req->get_pem_req();
    return $csr;

}

# Add the appropriate code to generate the DCV files in the places you would normally look for DCV files on a domain on your end.
# This example iterates over the array of domains in a vhost passed to the function. It also includes the CSR text.
# Pass in whatever necessary. If the function needs to parse the CSR, use https://metacpan.org/pod/Crypt::PKCS10

# If you want a CPAN module that can help for writing your files, use File::Slurp::write_file -- see https://metacpan.org/pod/File::Slurp

sub _generate_dcv_files {
    my ( $csr, @domains ) = @_;
    my $something;
    foreach my $domain (@domains) {

        #Add whatever actions you might need to generate the DCV files.

    }

    # The foreach loop should populate data for the function to return.

    return $something;

}

1;