Merge remote-tracking branch 'upstream/master'

spinupwp · Dec 6, 2024 · f98bda1 · f98bda1
2 parents f024115 + 6c1fa94
commit f98bda1
Show file tree

Hide file tree

Showing 18 changed files with 1,274 additions and 678 deletions.
diff --git a/README.md b/README.md
@@ -1,23 +1,28 @@
 # LEClient
-PHP LetsEncrypt client library for ACME v2. The aim of this client is to make an easy-to-use and integrated solution to create a LetsEncrypt-issued SSL/TLS certificate with PHP. The user has to have access to the web server or DNS management to be able to verify the domain is accessible/owned by the user.
 
-## Current version
+[![Latest Stable Version](https://poser.pugx.org/yourivw/leclient/v/stable)](https://packagist.org/packages/yourivw/leclient)
+[![Total Downloads](https://poser.pugx.org/yourivw/leclient/downloads)](https://packagist.org/packages/yourivw/leclient)
+[![License](https://poser.pugx.org/yourivw/leclient/license)](https://packagist.org/packages/yourivw/leclient)
+
+&nbsp;
 
-The current version is 1.1.7
+PHP LetsEncrypt client library for ACME v2. The aim of this client is to make an easy-to-use and integrated solution to create a LetsEncrypt-issued SSL/TLS certificate with PHP. The user has to have access to the web server or DNS management to be able to verify the domain is accessible/owned by the user.
 
-The example codes below are to be updated.
+## Current version
 
-This client was developed with the use of the LetsEncrypt staging server for version 2. While version 2 is still being developed and implemented by LetsEncrypt at this moment, the project might be subject to change.
+The current version is 1.2.2
 
 ## Getting Started
 
-These instructions will get you started with this client library. Is you have any questions or find any problems, feel free to open an issue and I'll try to have a look at it.
+These instructions will get you started with this client library. If you have any questions or find any problems, feel free to open an issue and I'll try to have a look at it.
 
 Also have a look at the [LetsEncrypt documentation](https://letsencrypt.org/docs/) for more information and documentation on LetsEncrypt and ACME.
 
 ### Prerequisites
 
-The minimum required PHP version is 5.2.0. Version 7.1.0 is required for EC keys. The function generating EC keys will throw an exception when trying to generate EC keys with a PHP version below 7.1.0. Version 1.0.0 will be kept available, but will not be maintained.
+The minimum required PHP version is 5.2.0. Version 7.1.0 is required for EC keys. The function generating EC keys will throw an exception when trying to generate EC keys with a PHP version below 7.1.0.
+
+Version 1.0.0 will be kept available, but will not be maintained.
 
 This client also depends on cURL and OpenSSL.
 
@@ -28,9 +33,7 @@ Using composer:
 composer require yourivw/leclient
 ```
 
-Although it is possible to add this to your own autoloader, it's not recommended as you'll have no control of the dependencies. If you haven't used composer before, I strongly recommend you check it out at [https://getcomposer.org](https://getcomposer.org).
-
-It is advisable to cut the script some slack regarding execution time by setting a higher maximum time. There are several ways to do so. One it to add the following to the top of the page:
+It is advisable to cut the script some slack regarding execution time by setting a higher maximum time. There are several ways to do so. One is to add the following to the top of the page:
 ```php
 ini_set('max_execution_time', 120); // Maximum execution time in seconds.
 ```
@@ -47,11 +50,13 @@ Initiating the client:
 ```php
 use LEClient\LEClient;
 
-$client = new LEClient($email);                               				// Initiating a basic LEClient with an array of string e-mail address(es).
-$client = new LEClient($email, true);                         				// Initiating a LECLient and use the LetsEncrypt staging URL.
-$client = new LEClient($email, true, $logger);   					// Initiating a LEClient and use a PSR-3 logger (\Psr\Log\LoggerInterface).
-$client = new LEClient($email, true, LEClient::LOG_STATUS);   				// Initiating a LEClient and log status messages (LOG_DEBUG for full debugging).
-$client = new LEClient($email, true, LEClient::LOG_STATUS, 'keys/');   			// Initiating a LEClient and select custom certificate keys directory (string or array)
+$client = new LEClient($email);								// Initiating a basic LEClient with an array of string e-mail address(es).
+$client = new LEClient($email, LEClient::LE_STAGING);					// Initiating a LECLient and use the LetsEncrypt staging URL.
+$client = new LEClient($email, LEClient::LE_PRODUCTION);				// Initiating a LECLient and use the LetsEncrypt production URL.
+$client = new LEClient($email, true);							// Initiating a LECLient and use the LetsEncrypt staging URL.
+$client = new LEClient($email, true, $logger);						// Initiating a LEClient and use a PSR-3 logger (\Psr\Log\LoggerInterface).
+$client = new LEClient($email, true, LEClient::LOG_STATUS);				// Initiating a LEClient and log status messages (LOG_DEBUG for full debugging).
+$client = new LEClient($email, true, LEClient::LOG_STATUS, 'keys/');			// Initiating a LEClient and select custom certificate keys directory (string or array)
 $client = new LEClient($email, true, LEClient::LOG_STATUS, 'keys/', '__account/');	// Initiating a LEClient and select custom account keys directory (string or array)
 ```
 The client will automatically create a new account if there isn't one found. It will forward the e-mail address(es) supplied during initiation, as shown above.
@@ -78,14 +83,16 @@ $order = $client->getOrCreateOrder($basename, $domains, $keyType, $notBefore, $n
 
 Using the order functions:
 ```php
+use LEClient\LEOrder;
+
 $valid      = $order->allAuthorizationsValid();                             // Check whether all authorizations in this order instance are valid.
 $pending    = $order->getPendingAuthorizations($type);                      // Get an array of pending authorizations. Performing authorizations is described further on. Type is LEOrder::CHALLENGE_TYPE_HTTP or LEOrder::CHALLENGE_TYPE_DNS.
 $verify     = $order->verifyPendingOrderAuthorization($identifier, $type);  // Verify a pending order. The identifier is a string domain name. Type is LEOrder::CHALLENGE_TYPE_HTTP or LEOrder::CHALLENGE_TYPE_DNS.
 $deactivate = $order->deactivateOrderAuthorization($identifier);            // Deactivate an authorization. The identifier is a string domain name.
 $finalize   = $order->finalizeOrder();                                      // Finalize the order and generate a Certificate Signing Request automatically.
 $finalize   = $order->finalizeOrder($csr);                                  // Finalize the order with a custom Certificate Signing Request string.
 $finalized  = $order->isFinalized();                                        // Check whether the order is finalized.
-$cert       = $order->getCertificate();                                     // Retrieves the certificate and stores it in the keys directory, under the specific order (basename).
+$cert       = $order->getCertificate();                                     // Retrieves the certificate and stores it in the keys directory.
 $revoke     = $order->revokeCertificate();                                  // Revoke the certificate without a reason.
 $revoke     = $order->revokeCertificate($reason);                           // Revoke the certificate with a reason integer as found in section 5.3.1 of RFC5280.
 ```
@@ -95,14 +102,61 @@ Supportive functions:
 ```php
 use LEClient\LEFunctions;
 
-LEFunctions::RSAGenerateKeys($directory, $privateKeyFile, $publicKeyFile);  // Generate a RSA keypair in the given directory. Variables privateKeyFile and publicKeyFile are optional and have default values private.pem and public.pem.
-LEFunctions::ECGenerateKeys($directory, $privateKeyFile, $publicKeyFile);   // Generate a EC keypair in the given directory (PHP 7.1+ required). Variables privateKeyFile and publicKeyFile are optional and have default values private.pem and public.pem.
-LEFunctions::Base64UrlSafeEncode($input);                                   // Encode the input string as a base64 URL safe string.
-LEFunctions::Base64UrlSafeDecode($input);                                   // Decode a base64 URL safe encoded string.
-LEFunctions::log($data, $function);                                         // Print the data. The function variable is optional and defaults to the calling function's name.
-LEFunctions::checkHTTPChallenge($domain, $token, $keyAuthorization);        // Checks whether the HTTP challenge is valid. Performing authorizations is described further on.
-LEFunctions::checkDNSChallenge($domain, $DNSDigest);                        // Checks whether the DNS challenge is valid. Performing authorizations is described further on.
-LEFunctions::createhtaccess($directory);									// Created a simple .htaccess file in the directory supplied, denying all visitors.
+LEFunctions::RSAGenerateKeys($directory, $privateKeyFile, $publicKeyFile);	// Generate a RSA keypair in the given directory. Variables privateKeyFile and publicKeyFile are optional and have default values private.pem and public.pem.
+LEFunctions::ECGenerateKeys($directory, $privateKeyFile, $publicKeyFile);	// Generate a EC keypair in the given directory (PHP 7.1+ required). Variables privateKeyFile and publicKeyFile are optional and have default values private.pem and public.pem.
+LEFunctions::Base64UrlSafeEncode($input);					// Encode the input string as a base64 URL safe string.
+LEFunctions::Base64UrlSafeDecode($input);					// Decode a base64 URL safe encoded string.
+LEFunctions::log($data, $function);						// Print the data. The function variable is optional and defaults to the calling function's name.
+LEFunctions::checkHTTPChallenge($domain, $token, $keyAuthorization);		// Checks whether the HTTP challenge is valid. Performing authorizations is described further on.
+LEFunctions::checkDNSChallenge($domain, $DNSDigest);				// Checks whether the DNS challenge is valid. Performing authorizations is described further on.
+LEFunctions::createhtaccess($directory);					// Created a simple .htaccess file in the directory supplied, denying all visitors.
+```
+
+## Filesystem Structure
+
+LEClient stores account keys, certificate keys, certificates and order data in the filesystem. By default, the folder structure used will look like this, relative to your working directory:
+
+    keys/                   Top-level LEClient folder
+      public.pem            Your certificate’s public key
+      private.pem           Your certificate’s private key
+      order                 A file used to store the order URL
+      fullchain.crt         The full-chain certificate
+      certificate.crt       The certificate
+      __account/            An internal folder for LEClient to store your account keys
+        public.pem          Your ACME account’s public key
+        private.pem         Your ACME account’s private key
+        .htaccess           An automatically-generated .htaccess to prevent accidental exposure
+
+You can customise these locations by passing values to the `$certificateKeys` and `$accountKeys` construction parameters when creating an `LEClient`.
+
+Passing strings will change the location and name of the top-level LEClient folder, and the name of the Account Key folder. Note that when passing strings, the account key folder will always be a subfolder of the top-level folder, meaning that:
+
+```php
+$client = new LEClient('[email protected]', LEClient::PRODUCTION, LEClient::LOG_OFF, 'path/to/my/key/folder/', 'my_account_folder');
+```
+
+will result in the following structure:
+
+    path/to/my/key/folder/
+      public.pem
+      …
+      my_account_folder/
+        public.pem
+        …
+
+If you want to have more control over the exact locations the various files are stored in, you can instead pass arrays to the `$certificateKeys` and `$accountKeys` parameters. If you pass an array to one, you must pass arrays to both.
+
+```php
+$client = new LEClient('[email protected]', LEClient::PRODUCTION, LEClient::LOG_OFF, [
+  'public_key' => 'path/to/public/key.pem',          // Required
+  'private_key' => 'path/to/private/key.pem',        // Required
+  'order' => 'path/to/order.txt',                    // Required
+  'certificate' => 'path/to/certificate.crt',        // One or both of certificate and fullchain_certificate
+  'fullchain_certificate' => 'path/to/fullchain.crt' // must be provided.
+], [
+  'public_key' => 'path/to/account/public/key.pem',  // Required
+  'private_key' => 'path/to/account/private/key.pem' // Required
+]);
 ```
 
 ## Authorization challenges
@@ -176,7 +230,7 @@ The DNS record name also depends on your provider, therefore getPendingAuthoriza
 
 For both HTTP and DNS authorizations, a full example is available in the project's main code directory. The HTTP authorization example is contained in one file. As described above, the DNS authorization example is split into two parts, to allow for the DNS record to update in the meantime. While the TTL of the record might be low, it can sometimes take some time for your provider to update your DNS records after an amendment.
 
-If you can't get these examples, or the client library to work, try and have a look at the LetsEncrypt documentation mentioned above as well.
+If you can't get these examples, or the client library to work, try and have a look at the LetsEncrypt documentation mentioned above as well. In order for the example code to work, make sure to replace all 'example.org' information with your own information. The examples will fail when you run them using the preset example data.
 
 ## Security
 

diff --git a/composer.json b/composer.json
@@ -4,11 +4,15 @@
     "description": "PHP LetsEncrypt client library for ACME v2",
     "license": "MIT",
     "require": {
-        "php": ">=5.2"
+        "php": ">=5.2",
+        "ext-openssl": "*"
     },
     "autoload": {
         "psr-4": {
             "LEClient\\": "src/"
         }
+    },
+    "require-dev": {
+        "psr/log": "^1.1"
     }
 }
diff --git a/examples/dns_finish.php b/examples/dns_finish.php
@@ -16,7 +16,7 @@
 $domains = array('example.org', 'test.example.org');
 
 // Initiating the client instance. In this case using the staging server (argument 2) and outputting all status and debug information (argument 3).
-$client = new LEClient($email, true, LECLient::LOG_STATUS);
+$client = new LEClient($email, LEClient::LE_STAGING, LECLient::LOG_STATUS);
 // Initiating the order instance. The keys and certificate will be stored in /example.org/ (argument 1) and the domains in the array (argument 2) will be on the certificate.
 $order = $client->getOrCreateOrder($basename, $domains);
 // Check whether there are any authorizations pending. If that is the case, try to verify the pending authorizations.

diff --git a/examples/dns_init.php b/examples/dns_init.php
@@ -16,7 +16,7 @@
 $domains = array('example.org', 'test.example.org');
 
 // Initiating the client instance. In this case using the staging server (argument 2) and outputting all status and debug information (argument 3).
-$client = new LEClient($email, true, LECLient::LOG_STATUS);
+$client = new LEClient($email, LEClient::LE_STAGING, LECLient::LOG_STATUS);
 // Initiating the order instance. The keys and certificate will be stored in /example.org/ (argument 1) and the domains in the array (argument 2) will be on the certificate.
 $order = $client->getOrCreateOrder($basename, $domains);
 // Check whether there are any authorizations pending. If that is the case, try to verify the pending authorizations.

diff --git a/examples/http.php b/examples/http.php
@@ -16,7 +16,7 @@
 $domains = array('example.org', 'test.example.org');
 
 // Initiating the client instance. In this case using the staging server (argument 2) and outputting all status and debug information (argument 3).
-$client = new LEClient($email, true, LECLient::LOG_STATUS);
+$client = new LEClient($email, LEClient::LE_STAGING, LECLient::LOG_STATUS);
 // Initiating the order instance. The keys and certificate will be stored in /example.org/ (argument 1) and the domains in the array (argument 2) will be on the certificate.
 $order = $client->getOrCreateOrder($basename, $domains);
 // Check whether there are any authorizations pending. If that is the case, try to verify the pending authorizations.

diff --git a/src/Exceptions/LEAccountException.php b/src/Exceptions/LEAccountException.php
@@ -0,0 +1,46 @@
+<?php
+
+namespace LEClient\Exceptions;
+
+/**
+ * LetsEncrypt Client Account exception, extends LEException
+ *
+ * PHP version 5.2.0
+ *
+ * MIT License
+ *
+ * Copyright (c) 2020 Youri van Weegberg
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * @author     Youri van Weegberg <[email protected]>
+ * @copyright  2020 Youri van Weegberg
+ * @license    https://opensource.org/licenses/mit-license.php  MIT License
+ * @link       https://github.com/yourivw/LEClient
+ * @since      Class available since Release 1.2.0
+ */
+class LEAccountException extends LEException
+{
+	public const ACCOUNTNOTFOUNDEEXCEPTION 	= 0x21;
+
+	public static function AccountNotFoundException()
+	{
+		return new static('Account not found or deactivated.', self::ACCOUNTNOTFOUNDEEXCEPTION);
+	}
+}
diff --git a/src/Exceptions/LEAuthorizationException.php b/src/Exceptions/LEAuthorizationException.php
@@ -0,0 +1,46 @@
+<?php
+
+namespace LEClient\Exceptions;
+
+/**
+ * LetsEncrypt Client Authorization exception, extends LEException
+ *
+ * PHP version 5.2.0
+ *
+ * MIT License
+ *
+ * Copyright (c) 2020 Youri van Weegberg
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * @author     Youri van Weegberg <[email protected]>
+ * @copyright  2020 Youri van Weegberg
+ * @license    https://opensource.org/licenses/mit-license.php  MIT License
+ * @link       https://github.com/yourivw/LEClient
+ * @since      Class available since Release 1.2.0
+ */
+class LEAuthorizationException extends LEException
+{
+	public const NOCHALLENGEFOUNDEEXCEPTION	= 0x41;
+
+	public static function NoChallengeFoundException($type, $identifier)
+	{
+		return new static(sprintf('No challenge found for type \'%s\' and identifier \'%s\'.', $type, $identifier), self::NOCHALLENGEFOUNDEEXCEPTION);
+	}
+}