NAME

Net::ACME2 - IETF-standard ACME (Let’s Encrypt) client

SYNOPSIS

    package SomeCA::ACME;

    use parent qw( Net::ACME2 );

    use constant {
        HOST => 'acme.someca.net',
        DIRECTORY_PATH => '/acme-directory',
    };

    package main;

    my $acme = SomeCA::ACME->new(
        key => $account_key_pem_or_der,
        key_id => undef,
    );

    #for a new account
    {
        my $terms_url = $acme->get_terms_of_service();

        $acme->create_new_account(
            termsOfServiceAgreed => 1,
        );
    }

    #Save $acme->key_id() somewhere so you can use it again.

    my $order = $acme->create_new_order(
        identifiers => [
            { type => 'dns', value => '*.example.com' },
        ],
    );

    my $authz = $acme->get_authorization( ($order->authorizations())[0] );

    my @challenges = $authz->challenges();

    # ... Pick a challenge, and satisfy it.

    $acme->accept_challenge($challenge);

    sleep 1 while !$acme->poll_authorization($authz);

    # ... Make a key and CSR for *.example.com

    $acme->finalize_order($order, $csr_pem_or_der);

    while ($order->status() ne 'valid') {
        sleep 1;
        $acme->poll_order($order);
    }

    my $certificate_url = $order->certificate();

    # ... Download your certificate! :)

See /examples in the distribution for a more fleshed-out example.

To use Let’s Encrypt, see Net::ACME2::LetsEncrypt.

DESCRIPTION

This library implements client logic for the IETF-standard ACME (Automated Certificate Management Environment) protocol. As of this writing, that protocol remains in development; the latest draft will be available from https://datatracker.ietf.org/doc/draft-ietf-acme-acme/.

Net::ACME2 derives from Net::ACME, which implements the (significantly different) earlier draft of that protocol as initially deployed by Let’s Encrypt.

Net::ACME2 is pure Perl, and all of its dependencies are either pure Perl or core modules.

STATUS

This is a “first-stab”, alpha-grade implementation. This distribution, like the underlying protocol, is very much still subject to change.

FEATURES

• This is a pure-Perl solution, all of whose dependencies are either core modules or pure-Perl themselves. Net::ACME2 will run anywhere that Perl runs. :)

• Support for both ECDSA and RSA encrytion.

• Comprehensive error handling with typed, X::Tiny-based exceptions.

ERROR HANDLING

All thrown exceptions are instances of Net::ACME2::X::Base. Specific error classes aren’t yet defined.

METHODS

CLASS->new( %OPTS )

Instantiates an ACME2 object, which you’ll use for all interactions with the ACME server. %OPTS is:

• key - Required. The private key to associate with the ACME2 user. PEM or DER format.

• key_id - Optional. As returned by key_id(). Saves a round-trip to the ACME2 server, so you should give this if you have it.

• directory - Optional. A hash reference to use as the directory contents. Saves a round-trip to the ACME2 server, but there’s no built-in logic to determine when the cache goes invalid. Caveat emptor.

OBJ->key_id()

Returns the object’s cached key ID, either as given at instantiation or as fetched in create_new_account().

CLASS_OR_OBJ->get_terms_of_service()

Callable as either an instance method or a class method. Returns the URL for the terms of service.

NOTE: For Let’s Encrypt you can unofficially resolve against https://acme-v01.api.letsencrypt.org/terms to see the terms of service.

OBJ->create_new_account( %OPTS )

Creates a new account using the ACME2 object’s key and the passed %OPTS, which are as described in the ACME2 spec (cf. newAccount). Boolean values may be given as simple Perl booleans.

Returns 1 if the account is newly created or 0 if the account already existed.

OBJ->create_new_order( %OPTS )

Returns a Net::ACME2::Order object. %OPTS is as described in the ACME spec (cf. newOrder). Boolean values may be given as simple Perl booleans.

OBJ->get_authorization( URL )

Fetches the authorization’s information based on the given URL and returns a Net::ACME2::Authorization object.

The URL is as given by Net::ACME2::Order.

OBJ->make_key_authorization( CHALLENGE )

Accepts an instance of Net::ACME2::Challenge and returns a key authorization string suitable for handling the given CHALLENGE. See /examples in the distribution for example usage.

If you’re using HTTP authorization and are on the same server as the domains’ document roots, then look at the handler logic in Net::ACME2::Challenge::http_01 for a potentially simpler way to handle HTTP challenges.

OBJ->accept_challenge( CHALLENGE )

Signal to the ACME server that the CHALLENGE is ready.

OBJ->poll_authorization( AUTHORIZATION )

Accepts a Net::ACME2::Authorization instance and polls the ACME server for that authorization’s status. The AUTHORIZATION object is then updated with the results of the poll.

OBJ->finalize_order( ORDER, CSR )

Finalizes an order and updates the ORDER object with the returned status. The CSR may be in either DER or PEM format.

ORDER may have status() of valid after this operation, or you may need to poll_order().

OBJ->poll_order( ORDER )

Like poll_authorization() but handles a Net::ACME2::Order object instead.

TODO

• Re-evaluate once there is a production server in place.

• Add pre-authorization support if there is ever a production use for it.

• Tighten up challenge failure response.

• Add (more) tests.

SEE ALSO

Crypt::Perl provides pure-Perl cryptography for this library. See the present library distribution’s /examples directory for sample usage to generate CSRs.

cpanm Net::ACME2

perl -MCPAN -e shell
install Net::ACME2