From a2d55a0ecb52cf1e1334b61496a7a4ec3025802c Mon Sep 17 00:00:00 2001 From: Travis Smith Date: Wed, 5 Feb 2025 22:34:40 -0600 Subject: [PATCH 1/4] Update captchas.md General improvements to the captcha docs. --- docs/security/captchas.md | 46 +++++++++++++++++++++++++-------------- 1 file changed, 30 insertions(+), 16 deletions(-) diff --git a/docs/security/captchas.md b/docs/security/captchas.md index 6df4d0636..5f1f808d3 100755 --- a/docs/security/captchas.md +++ b/docs/security/captchas.md @@ -11,25 +11,28 @@ [TOC] -ExpressionEngine supports what are known as "CAPTCHAs", or Completely Automated Public Turing tests to tell Computers and Humans Apart. A CAPTCHA is a computer-generated test that humans can easily pass, but that is computationally difficult for a computer to do. +A CAPTCHA, as a general concept, is a computer-generated test that humans can easily pass, but that is computationally difficult for a computer to do. They are used when you want to ensure that a human is performing an action, not an automated script -- often to block spam. -So how does this work? An image is generated in real time for a user loading a web page. This image contains a word that the user must enter in a form. The concept is effective because computers are generally not very good at reading images, but it is something humans can do with little effort. +ExpressionEngine has built-in support for CAPTCHAs (Completely Automated Public Turing tests to tell Computers and Humans Apart), and can also use (Google's reCAPTCHA v3)[https://cloud.google.com/security/products/recaptcha]. + +So how does the built-in CAPTCHA functionality work? + +When a user loads a web page with a form protected by a CAPTCHA, EE generates a unique image in real time. This image contains a word that the user must enter when they submit a form. The CAPTCHA is effective because computers are generally not very good at reading images, but it is something humans can do with little effort. In ExpressionEngine, CAPTCHAs can be used in several places: -- [CAPTCHAs](#captchas) -- [Comment Forms](#comment-forms) -- [Member Registration Form](#member-registration-form) -- [Contact and Tell-a-Friend Email Forms](#contact-and-tell-a-friend-email-forms) -- [CAPTCHA Code](#captcha-code) -- [Notes](#notes) -- [CAPTCHA Words](#captcha-words) +- [To submit a comment](#comment-forms) +- [To register a new member](#member-registration-form) +- [In the Contact and Tell-a-Friend email forms](#contact-and-tell-a-friend-email-forms) +- [In Channel Forms](#channel-forms) -The settings to require CAPTCHAs for these forms are located at `Settings --> CAPTCHA` in the control panel. +The settings to require CAPTCHAs for these forms are located at [`Settings --> CAPTCHA`](control-panel/settings/captcha.md) in the control panel. + +The CAPTCHA settings are applied site-wide. If other add-ons allow the use of captchas, they will also be controlled by the same settings. ## Comment Forms -Once you have the preference turned on, you'll need to add the CAPTCHA code to your [Comment Submission Form](comment/form.md). See below for the [CAPTCHA Code](#captcha-code). +If you have the setting turned on, you'll need to add the CAPTCHA code to your [Comment Submission Form](comment/form.md). See below for the [CAPTCHA Code](#captcha-code). ## Member Registration Form @@ -37,16 +40,27 @@ The necessary CAPTCHA code already exists in the Member Templates by default, so ## Contact and Tell-a-Friend Email Forms -Once you have the preference turned on, you'll need to add the CAPTCHA code. See below for the [CAPTCHA Code](#captcha-code). +If you have the setting turned on, you'll need to add the CAPTCHA code to the form. See below for the [CAPTCHA Code](#captcha-code). + +## Channel Forms + +If you have the setting turned on, you'll need to add the CAPTCHA code to your [Channel Entry Form](channels/channel-form/overview.md#captcha). See below for the [CAPTCHA Code](#captcha-code). ## CAPTCHA Code +This is the code for Comment forms, Contact forms, and Channel Entry forms. + {if captcha}

Please enter the word you see in the image below:

-

{captcha}

+

{captcha}
+

{/if} -The contents of the conditional {if captcha} tag will only appear if you have the CAPTCHA preference turned on for either the comment or member registration forms. +The contents of the conditional `{if captcha}` tag will appear if you: + +- have the CAPTCHA setting turned on +- are not logged in as a superadmin (Superadmins never have to pass a CAPTCHA test) +- are using the built-in CAPTCHA (Google's reCAPTCHA v3 does not display anything) The code used inside the Member Registration Form is very similar, with only the omission of the {captcha_word} variable: @@ -56,7 +70,7 @@ The code used inside the Member Registration Form is very similar, with only the

{/if} -If using using [reCAPTCHA v3](security/captchas.md), use a simplified tag that will output the required javascript, with the CAPTCHA otherwise invisible. +If using using [reCAPTCHA v3](security/captchas.md), use this simplified code. It will output the required javascript with the CAPTCHA being otherwise invisible. {if captcha} {captcha} @@ -72,7 +86,7 @@ For ExpressionEngine installations that power multiple domains or subdomains, yo ## CAPTCHA Words -The CAPTCHA system uses a default dictionary. You can override these by adding a special user config file and returning an array of words you want to use instead. Create a PHP file at `system/user/config/captcha.php` with the format: +The CAPTCHA system uses a default dictionary. You can override these by adding a special user config file that returns an array of words you want to use instead. Create a PHP file at `system/user/config/captcha.php` with the format: Date: Thu, 10 Apr 2025 18:06:42 -0400 Subject: [PATCH 2/4] Further tweaks --- docs/security/captchas.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/security/captchas.md b/docs/security/captchas.md index 5f1f808d3..5ebf99465 100755 --- a/docs/security/captchas.md +++ b/docs/security/captchas.md @@ -28,11 +28,11 @@ In ExpressionEngine, CAPTCHAs can be used in several places: The settings to require CAPTCHAs for these forms are located at [`Settings --> CAPTCHA`](control-panel/settings/captcha.md) in the control panel. -The CAPTCHA settings are applied site-wide. If other add-ons allow the use of captchas, they will also be controlled by the same settings. +The CAPTCHA settings are applied site-wide. If you have CAPTCHAS required, they will be required for all of the following uses with the same settings. If other add-ons integrate the use of EE's captcha system, they will also be controlled by the same settings. ## Comment Forms -If you have the setting turned on, you'll need to add the CAPTCHA code to your [Comment Submission Form](comment/form.md). See below for the [CAPTCHA Code](#captcha-code). +If you have CAPTCHAS required, you'll need to add the CAPTCHA code to your [Comment Submission Form](comment/form.md). See below for the [CAPTCHA Code](#captcha-code). ## Member Registration Form @@ -40,11 +40,11 @@ The necessary CAPTCHA code already exists in the Member Templates by default, so ## Contact and Tell-a-Friend Email Forms -If you have the setting turned on, you'll need to add the CAPTCHA code to the form. See below for the [CAPTCHA Code](#captcha-code). +If you have CAPTCHAS required, you'll need to add the CAPTCHA code to these forms in order to submit properly. See below for the [CAPTCHA Code](#captcha-code). ## Channel Forms -If you have the setting turned on, you'll need to add the CAPTCHA code to your [Channel Entry Form](channels/channel-form/overview.md#captcha). See below for the [CAPTCHA Code](#captcha-code). +If you have CAPTCHAS required, you'll need to add the CAPTCHA code to your [Channel Entry Form](channels/channel-form/overview.md#captcha). See below for the [CAPTCHA Code](#captcha-code). ## CAPTCHA Code @@ -56,13 +56,15 @@ This is the code for Comment forms, Contact forms, and Channel Entry forms.

{/if} -The contents of the conditional `{if captcha}` tag will appear if you: +The contents of the conditional `{if captcha}` tag will be displayed if you: - have the CAPTCHA setting turned on - are not logged in as a superadmin (Superadmins never have to pass a CAPTCHA test) -- are using the built-in CAPTCHA (Google's reCAPTCHA v3 does not display anything) +- are not logged in (only if you have "Require CAPTCHA while logged in?" enabled) -The code used inside the Member Registration Form is very similar, with only the omission of the {captcha_word} variable: +The `{captcha}` tag itself will be an image tag if you are using the built-in CAPTCHA. + +The code used in the Member Registration Form is very similar, with only the omission of the {captcha_word} variable: {if captcha}

Please enter the word you see in the image below:

@@ -70,7 +72,7 @@ The code used inside the Member Registration Form is very similar, with only the

{/if} -If using using [reCAPTCHA v3](security/captchas.md), use this simplified code. It will output the required javascript with the CAPTCHA being otherwise invisible. +If you are using [Google's reCAPTCHA v3](security/captchas.md), use this simplified code in all cases. The `{captcha}` tag will output the required JavaScript, the CAPTCHA is invisible, and there is no need for an input field. {if captcha} {captcha} From 1363feaccea79019ecd1d5a1173e2ae91df8ae83 Mon Sep 17 00:00:00 2001 From: Travis Smith Date: Thu, 10 Apr 2025 18:31:10 -0400 Subject: [PATCH 3/4] crosslinking with the Captcha Settings page --- docs/control-panel/settings/captcha.md | 8 ++++++-- docs/security/captchas.md | 4 ++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/control-panel/settings/captcha.md b/docs/control-panel/settings/captcha.md index c609e5446..3f835f618 100755 --- a/docs/control-panel/settings/captcha.md +++ b/docs/control-panel/settings/captcha.md @@ -17,7 +17,11 @@ This section of the Control Panel allows you to set [CAPTCHA](security/captchas. ### Require CAPTCHA? -If you enable this preference, then site visitors will be required to pass a CAPTCHA to submit any front-end form, including Channel Form, comment forms, and member registrations. If members are logged in, they will not have to enter a CAPTCHA unless the [Require CAPTCHA while logged in?](#require-captcha-while-logged-in) preference is enabled below. +If you enable this preference, then site visitors will be required to pass a CAPTCHA to submit any front-end form, including [channel forms](security/captchas.md#channel-forms), [comment forms](security/captchas.md#comment-forms), contact and tell-a-friend email forms](#contact-and-tell-a-friend-email-forms), and [member registrations](security/captchas.md#member-registration-forms). + +If members are logged in, they will not have to enter a CAPTCHA unless the [Require CAPTCHA while logged in?](#require-captcha-while-logged-in) preference is enabled. + +Superadmins are not required to submit a captcha and are never shown one. ### Use TrueType font? @@ -55,7 +59,7 @@ If you wish to use Google reCAPTCH v3 as a replacement you will need to ensure t ### Use reCAPTCHA v3? -If you enable this preference then the system will use reCAPTCHA v3 in place of the older image based solution. +If you enable this preference then the system will use reCAPTCHA v3 in place of the older image-based CAPTCHA method built into ExpressionEngine. ### reCAPTCHA site key diff --git a/docs/security/captchas.md b/docs/security/captchas.md index 5ebf99465..15f7d7276 100755 --- a/docs/security/captchas.md +++ b/docs/security/captchas.md @@ -22,7 +22,7 @@ When a user loads a web page with a form protected by a CAPTCHA, EE generates a In ExpressionEngine, CAPTCHAs can be used in several places: - [To submit a comment](#comment-forms) -- [To register a new member](#member-registration-form) +- [To register a new member](#member-registration-forms) - [In the Contact and Tell-a-Friend email forms](#contact-and-tell-a-friend-email-forms) - [In Channel Forms](#channel-forms) @@ -34,7 +34,7 @@ The CAPTCHA settings are applied site-wide. If you have CAPTCHAS required, they If you have CAPTCHAS required, you'll need to add the CAPTCHA code to your [Comment Submission Form](comment/form.md). See below for the [CAPTCHA Code](#captcha-code). -## Member Registration Form +## Member Registration Forms The necessary CAPTCHA code already exists in the Member Templates by default, so you should not need to add it. If you have a version of ExpressionEngine from before the CAPTCHA feature was added or if you otherwise need the code, see below for the [CAPTCHA Code](#captcha-code). From 3ea1fd9badc5bc48d2743212cfaa1930c4feeb18 Mon Sep 17 00:00:00 2001 From: Travis Smith Date: Thu, 10 Apr 2025 18:49:26 -0400 Subject: [PATCH 4/4] A few more changes --- docs/control-panel/settings/captcha.md | 22 +++++++++++++--------- docs/troubleshooting/templates.md | 5 +++-- 2 files changed, 16 insertions(+), 11 deletions(-) diff --git a/docs/control-panel/settings/captcha.md b/docs/control-panel/settings/captcha.md index 3f835f618..5911df681 100755 --- a/docs/control-panel/settings/captcha.md +++ b/docs/control-panel/settings/captcha.md @@ -11,7 +11,7 @@ **Control Panel Location: `Settings > CAPTCHA`** -This section of the Control Panel allows you to set [CAPTCHA](security/captchas.md) preferences for your website. +This section of the Control Panel allows you to set the [CAPTCHA](security/captchas.md) preferences for your website. ## Settings @@ -23,6 +23,16 @@ If members are logged in, they will not have to enter a CAPTCHA unless the [Requ Superadmins are not required to submit a captcha and are never shown one. +### Require CAPTCHA while logged in? + +If you enable this preference, then even members who are logged in will need to fill out CAPTCHA information in order to post, for example, comments (assuming you've enabled CAPTCHA support for comment posting). If you disable this setting, then members who are logged in will bypass the CAPTCHA check. + +### Use reCAPTCHA v3? + +If you enable this preference then the system will use reCAPTCHA v3 in place of the built-in image based solution. You will also want to ensure that you [update any code](security/captchas.md#captcha-code) used to output CAPTCHAs on your site. + +## Built-in CAPTCHA Settings + ### Use TrueType font? If your server supports TrueType Fonts, then you can enable this setting. If you receive errors such as Call to undefined function: imagettftext() on your site then your server does not support TrueType Fonts and you should set this to "No". @@ -31,10 +41,6 @@ If your server supports TrueType Fonts, then you can enable this setting. If you Specify whether to add a random three-digit number to the end of each generated CAPTCHA word. This makes it more difficult for scripts to guess or brute-force the form submission. -### Require CAPTCHA while logged in? - -If you enable this preference, then members who are logged in will need to fill out CAPTCHA information in order to post comments (assuming you've enabled CAPTCHA support for comment posting). If you disable this setting, then members who are logged in can bypass the CAPTCHA check. - ### CAPTCHA directory The URL to your [CAPTCHA](security/captchas.md) images. In most cases, this will be similar to: @@ -55,11 +61,9 @@ If you do not know what to use for your full server path, contact your Host or s ## reCAPTCHA v3 Settings -If you wish to use Google reCAPTCH v3 as a replacement you will need to ensure that the site is set up with Google to gain the required site key and secret. See https://www.google.com/recaptcha/admin/create - -### Use reCAPTCHA v3? +If you wish to use (Google reCAPTCHA v3)[https://cloud.google.com/security/products/recaptcha#how-it-works] as a replacement for the built-in functionality, you will need to ensure that the site is set up with Google with the required site key and secret. -If you enable this preference then the system will use reCAPTCHA v3 in place of the older image-based CAPTCHA method built into ExpressionEngine. +Note that there is currently a monthly limit on the number of free CAPTCHAs that Google provides. See https://www.google.com/recaptcha/admin/create ### reCAPTCHA site key diff --git a/docs/troubleshooting/templates.md b/docs/troubleshooting/templates.md index 53da4b534..368dfe4b5 100755 --- a/docs/troubleshooting/templates.md +++ b/docs/troubleshooting/templates.md @@ -64,16 +64,17 @@ Ensure that the channel field is being called within the template. For example, ## CAPTCHA images not appearing -CAPTCHAs are enabling but there is a blank space where they should appear. +CAPTCHAs are enabled but there is a blank space where they should appear. ### Troubleshooting missing CAPTCHA Images There are several possible reasons for CAPTCHA images to not appear: -- The path and/or URL to the CAPTCHA directory is not specified correctly under `Settings --> CAPTCHA`. +- The path and/or URL to the CAPTCHA directory is not specified correctly under [`Settings --> CAPTCHA`](control-panel/settings/captcha.md). - The `images/captchas/` directory is not writable. See [File Permissions](troubleshooting/general.md#file-permissions) for details. - The server does not support True Type Fonts. TrueType Fonts can be disabled in `Settings --> CAPTCHA`. - GD library isn't installed and/or working correctly +- You are logged in as a superadmin, and superadmins are not required to solve CAPTCHAs ## Can not save a template with the {exp:query} tag