NAME

SYNOPSIS

    package SomeCA::ACME;

    use parent qw( Net::ACME2 );

    use constant {
        DIRECTORY_PATH => '/acme-directory',
    };

    # %opts are the parameters given to new().
    sub HOST {
        my ($class, %opts) = @_;

        # You can make this depend on the %opts if you want.
        return 'acme.someca.net';
    }

    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_account(
            termsOfServiceAgreed => 1,
        );
    }

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

    my $order = $acme->create_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 'valid' ne $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);
    }

    # ... and now fetch the certificate chain:

    my $pem_chain = $acme->get_certificate_chain($order);

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

To use Let’s Encrypt <http://letsencrypt.org>, see Net::ACME2::LetsEncrypt.

DESCRIPTION

STATUS

FEATURES

• Support for both ECDSA and RSA encrytion.
• Support for http-01, dns-01, and tls-alpn-01 <https://datatracker.ietf.org/doc/draft-ietf-acme-tls-alpn/> challenges.
• Comprehensive error handling with typed, X::Tiny-based exceptions.
• Retry POST on "badNonce" errors. <https://tools.ietf.org/html/rfc8555#section-6.5>
• This is a pure-Perl solution. Most of its dependencies are either core modules or pure Perl themselves. XS is necessary to communicate with the ACME server via TLS; however, most Perl installations already include the necessary logic (i.e., Net::SSLeay) for TLS.

  In short, Net::ACME2 will run anywhere that Perl can speak TLS, which is almost everywhere that Perl runs.

ERROR HANDLING

CRYPTOGRAPHY & SPEED

To address these problems, Net::ACME2 will, after parsing a key, look for and prefer the following XS-based libraries for cryptography instead:

• Crypt::OpenSSL::RSA (based on OpenSSL <http://openssl.org>)
• CryptX (based on LibTomCrypt <http://www.libtom.net/LibTomCrypt/>)

If the above are unavailable to you, then you may be able to speed up your Math::BigInt installation; see that module’s documentation for more details.

METHODS

TODO

• Add pre-authorization support if there is ever a production use for it.
• Expose the Retry-After header via the module API.
• There is currently no way to fetch an order or challenge’s properties via URL. Prior to ACME’s adoption of “POST-as-GET” this was doable via a plain GET to the URL, but that’s no longer possible. If there’s a need, I’ll consider adding such logic to Net::ACME2. (It’s trivial to add; I’d just like to keep things as simple as possible.)
• Add (more) tests.

SEE ALSO

Crypt::Perl provides this library’s default cryptography backend. See this distribution’s /examples directory for sample usage to generate keys and CSRs.

Net::ACME implements client logic for the variant of this protocol that Let’s Encrypt first deployed.