README

Crypt-LE

The Crypt::LE module provides the functionality necessary to use the API of Let's Encrypt API and other ACME-compatible
CAs, and to generate free SSL certificates for your domains. It can also be used to generate private RSA and ECC keys or
Certificate Signing Requests without resorting to openssl command line.


COMPATIBILITY

The code has been successfully tested on more than 500 combinations of OS and Perl versions. It should install
and run fine on Linux, FreeBSD, NetBSD, etc. It also works on Mac OS X and Windows (tested with ActiveState and
Strawberry Perl).

In addition, if you are able to run docker containers, you can pull the latest client image from
https://hub.docker.com/r/zerossl/client/. Docker image is lightweight and the client is run as a non-privileged
user in a container.


REQUIREMENTS

LINUX: There are just 3 essential things which should be in place for the package to be successfully installed:
"gcc", "make" and the SSL development package. The SSL development package name differs depending on 
Linux distribution and it can be either "libssl-dev" or "openssl-devel". 

WINDOWS: There are no requirements if Raspberry Perl is used. For ActiveState Perl you may need to install CPANminus
first (business license users of ActiveState have direct access to Crypt::LE ppm).

WINDOWS BINARIES: You can also use Windows binaries available at https://github.com/do-know/Crypt-LE/releases - those
require no installation and available for both 32bit and 64bit environments.


INSTALLATION

The installation is quite easy and straightforward. The provided client does not need any specific privileges (certainly
does not need to be run as a root or any privileged user). Keep in mind that the client functionality can be extended
with plugins, so make sure you have read the "Plugins" section and especially "Plugins in multiuser environment" notes.

- With CPANminus

  cpanm Crypt::LE

- With CPAN

  cpan -i Crypt::LE

- Manual installation:

  perl Makefile.PL
  make
  make test
  make install

- Windows installation (with Strawberry Perl)

  cpanm -f Log::Log4perl
  cpanm Crypt::LE

Note: On Windows current version of the logging module needs to be installed with -f flag first if Strawberry Perl is used.


CLIENT

Crypt::LE is shipped with a self-sufficient client for obtaining SSL certificates - le.pl. Run it without parameters to see how it is used.
The client supports 'http' and 'dns' challenges out of the box.

Usage example: le.pl --key account.key --csr domain.csr --csr-key domain.key --crt domain.crt --domains "www.domain.ext,domain.ext" --generate-missing

That will generate an account key and a CSR if they are missing. If any of those files exists, they will just be loaded, so it is safe to re-run
the client.

Note: If you would like to receive expiration notifications for your domain, you can specify --email parameter and an appropriate email address
during the initial registration of the account. Later, shall you want to change your email or specify more than one, you can use --update-contacts
parameter to update your contact information.

For example: le.pl --key account.key --update-contacts "one@email.address, another@email.address" --live

To reset your contact details, please specify "none" as a value, as follows: le.pl --key account.key --update-contacts "none" --live


WILDCARD CERTIFICATES SUPPORT

To issue a wildcard certificate, use DNS verification and specify the domain in the following format: *.some.domain

For example: le.pl ... --domains "*.some.domain" --handle-as dns

Please note that at the moment wildcards are only supported by the v2.0 of the API and they can only be issued if DNS verification is used.


PFX/P12 SUPPORT

Windows binaries include export functions into PFX/P12 format, which is normally required by IIS. The export (in addition to saving certificates in
PEM format) can be activated by specifying a PFX password with '--export-pfx' option.


IDN (INTERNATIONALIZED DOMAIN NAMES) SUPPORT

If you are using IDN (Internationalized Domain Names) and generating a certificate for those, you can either encode those into "punycode" form by yourself,
or let the client do that for you. Please note that for the conversion to work properly you need to have correct locale settings on your system. For
Linux-based systems you can check that with the "locale" command, for Windows make sure that "System locale" in the Control Panel is set correctly.

EAB (EXTERNAL ACCOUNT BINDING) SUPPORT

Some ACME-compatible Certificate Authorities manage their accounts differently from how ACME accounts are normally created, but link those to an ACME
account through so-called External Account Binding. In essence, you would need to get 2 additional parameters from those CAs and use those on the command
line. Those parameters are the "Key ID" ('eab-kid') and "HMAC Key" ('eab-hmac-key').

Please note that the same EAB credentials, depending on the CA, might be allowed to be used for multiple ACME accounts or just one.

PLUGINS

Both the library and the client can be easily extended with custom plugins to handle Let's Encrypt challenges (both pre- and post-verification). See
Crypt::LE::Challenge::Simple module as an example of such plugin. The client application can also be easily extended with modules handling process
completion. See Crypt::LE::Complete::Simple module as an example of such plugin.

Client options related to plugins are:

 --handle-with
 --handle-params
 --handle-as
 --complete-with
 --complete-params

Please note that parameters for --handle-params and --complete-params are expected to be valid JSON documents or to point to files containing valid
JSON documents (the latter is a preferable method).

Example of running the client with plugins (you can modify the source code of the provided Crypt::LE::Challenge::Simple and Crypt::LE::Complete::Simple):

    le.pl --key account.key --email "my@email.address" --csr domain.csr --csr-key domain.key --crt domain.crt --domains "www.domain.ext,domain.ext" \
--generate-missing --handle-with Crypt::LE::Challenge::Simple --complete-with Crypt::LE::Complete::Simple

Note: you can use the same plugin to cover both the challenge/verification and the completion process, as long as it has appropriately named methods defined.
You can also point directly to a Perl module file rather than specify a name of the module.

This will work even on Windows, without any need to install anything - having just the binary file of the client and the plugin file is sufficient.

For example, if you have your le64.exe client and then created or downloaded the plugin code into the same directory, you can use it like this:

    le64.exe -key account.key -domains test.com -csr test.csr -csr-key test.key -crt test.crt -generate-missing -handle-with DNS.pm -handle-as dns

See https://github.com/do-know/Crypt-LE/blob/master/Plugins/DNS.pm as an example of such "combined" plugin.

All comand line parameters are passed to the methods of the plugin, along with the information about the challenge requirements and the verification results.
For example, if you have defined handle_challenge_dns method, it will receive the challenge data and the parameters data. The challenge data will contain
all the necessary details, including "domain", "host" and "record" values. In this case the "host" would be the same as the "domain", except the wildcard
part removed (if it was present). To illustrate:

- If the "domain" is test.com, then the "host" is test.com;
- If the "domain is "*.test.com", then the "host" is test.com;

So you would need to set _acme-challenge record in your "host" zone with the value of the "record".

In a similar way, for the HTTP verification, the method handle_challenge_http would have access to "file", which contains the name of the file to be created,
and the "text", which contains the content of that file.

#### Plugins in multiuser environment ####

It is important to remember that the client code allows plugins to be used. While this makes the client rather flexible in terms of possible automation,
it should be kept in mind that you should not be running it from a privileged user (and you do not need to), especially in the multiuser environment.
As with any other application that can extend the functionality either by plugins or by executing some commands/hooks, it is never a good idea to make it
writable by anyone else or make it run with the privileges it does not actually need. You can almost always achieve the resuts you need without resorting
to making your application (or the script that runs it) running as a root or a privileged user - for example to allow reloading the web server on completion
you can just configure sudo to allow that reload to a specific user, etc.


SUPPORT AND DOCUMENTATION

After installing, you can find documentation for this module with the
perldoc command.

    perldoc Crypt::LE

You can also look for information at:

    RT, CPAN's request tracker (report bugs here)
        http://rt.cpan.org/NoAuth/Bugs.html?Dist=Crypt-LE

    AnnoCPAN, Annotated CPAN documentation
        http://annocpan.org/dist/Crypt-LE

    CPAN Ratings
        http://cpanratings.perl.org/d/Crypt-LE

    Search CPAN
        http://search.cpan.org/dist/Crypt-LE/

For feedback or custom development requests see:

    Project homepage
        https://Do-Know.com


LICENSE AND COPYRIGHT

Copyright (C) 2016-2023 Alexander Yezhov

This program is free software; you can redistribute it and/or modify it
under the terms of the the Artistic License (2.0). You may obtain a
copy of the full license at:

L<http://www.perlfoundation.org/artistic_license_2_0>

Any use, modification, and distribution of the Standard or Modified
Versions is governed by this Artistic License. By using, modifying or
distributing the Package, you accept this license. Do not use, modify,
or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made
by someone other than you, you are nevertheless required to ensure that
your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service
mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge
patent license to make, have made, use, offer to sell, sell, import and
otherwise transfer the Package with respect to any patent claims
licensable by the Copyright Holder that are necessarily infringed by the
Package. If you institute patent litigation (including a cross-claim or
counterclaim) against any party alleging that the Package constitutes
direct or contributory patent infringement, then this Artistic License
to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER
AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES.
THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY
YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR
CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR
CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.