Crypt-LE The Crypt::LE module provides the functionality necessary to use Let's Encrypt API and generate free SSL certificates for your domains. It can also be used to generate private RSA (and from version 0.20 also 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. 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-2020 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.