Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/do-know/crypt-le

Crypt::LE - Let's Encrypt / Buypass / ZeroSSL and other ACME-servers client and library in Perl for obtaining free SSL certificates (inc. generating RSA/ECC keys and CSRs). HTTP/DNS verification is supported out of the box, EAB (External Account Binding) supported, easily extended with plugins, easily dockerized.
https://github.com/do-know/crypt-le

acme acme-client acme-v2 certificate crypt crypt-le dns docker docker-ssl ecc ecdsa free-ssl-certificates https perl pfx rsa security ssl windows-ssl zerossl

Last synced: 10 days ago
JSON representation

Crypt::LE - Let's Encrypt / Buypass / ZeroSSL and other ACME-servers client and library in Perl for obtaining free SSL certificates (inc. generating RSA/ECC keys and CSRs). HTTP/DNS verification is supported out of the box, EAB (External Account Binding) supported, easily extended with plugins, easily dockerized.

Awesome Lists containing this project

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 "[email protected], [email protected]" --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 "[email protected]" --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



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.