CGI::A...CAPTCHA(3pm)

💖 CGI::Application::Plugin::CAPTCHA 💖

okay bestie, so this is the manual page for CGI::Application::Plugin::CAPTCHA — say that five times fast, I dare you — and it's literally the easiest way to make, use, and verify CAPTCHAs in your CGI::Application-based web apps. no cap. 🎀

✨ VERSION ✨

Version 0.04 🦋

---

🌸 SYNOPSIS 🌸

okay so here's the whole vibe, look:

# In your CGI::Application-based web application module. . .
use CGI::Application::Plugin::CAPTCHA;

sub setup
{
    my $self = shift;

    $self->run_modes([ qw/
        create
        # Your other run modes go here
    /]);

    $self->captcha_config(
        IMAGE_OPTIONS    => {
            width    => 150,
            height   => 40,
            lines    => 10,
            font     => "/Library/Fonts/Arial",
            ptsize   => 18,
            bgcolor  => "#FFFF00",
        },
        CREATE_OPTIONS   => [ 'ttf', 'rect' ],
        PARTICLE_OPTIONS => [ 300 ],
    );
}

# Create a run mode that calls the CAPTCHA creation method...
sub create
{
    my $self = shift;
    return $self->captcha_create;
}

# In a template far, far away. . .
<img src="/delight/Ident/create"> (to generate a CAPTCHA image)

# Back in your application, to verify the CAPTCHA...
sub some_other_runmode
{
    my $self    = shift;
    my $request = $self->query;

    return unless $self->captcha_verify($request->cookie("hash"), $request->param("verify"));
}

no fr, that's the entire workflow. copy it, paste it, slay. 💅

---

👑 DESCRIPTION 👑

CGI::Application::Plugin::CAPTCHA lets programmers easily add and verify CAPTCHAs in their CGI::Application-derived web applications. it's giving convenience.

so a CAPTCHA (or, if you wanna be extra, a Completely Automated Public Turing Test to Tell Computers and Humans Apart) is just an image with a random string of characters in it. the user has to type that random string correctly before they can submit a form. it's a simple (yet, honestly, kinda annoying 😭) procedure for humans to get through — but it is significantly more difficult for a form-stuffing script to get through without having to integrate some sort of OCR. so like, vibe check: humans pass, bots cry. 💀

CAPTCHAs are not a perfect solution, bestie, let's be real. any skilled, diligent cracker will eventually be able to bypass a CAPTCHA. but it should absolutely be able to shut down your average script-kiddie. periodt. 🔥

CGI::Application::Plugin::CAPTCHA is a wrapper for GD::SecurityImage. it makes accessing GD::SecurityImage functionality way more convenient, and gives you a much more CGI::Application-flavored way of doing it.

when a CAPTCHA is created with this module, raw image data gets transmitted from your web application over to the client browser. a cookie containing a checksum also gets transmitted along with the image. then when the client submits their form for processing (along with their verification of the random string), captcha_verify() generates a checksum of the verification string the user entered. if the newly generated checksum matches the checksum found in the cookie, we trust that the CAPTCHA has been successfully entered, and we let the user continue processing their form. it's a whole handshake moment. 🫶

the checksum is generated by taking the string in question and joining it with a SECRET. then we generate an SHA1 hex digest of the resulting string. the end user will not be able to generate their own checksums to bypass the CAPTCHA check, because they don't know the value of our SECRET. which means — and hear me on this one — it is important to choose a good value for your SECRET. don't be out here using SECRET => "secret". 🙈

an easy way to generate a relatively good secret is to run the following perl snippet:

perl -MDigest::SHA=sha1_base64 -le 'print sha1_base64($$,time(),rand(9999))'

the author recognizes that the transmission of a cookie with the CAPTCHA image may not be a popular decision, and welcomes any patches from those who can provide an equally easy-to-implement solution. so if you've got a better idea, speak up bestie, the door is open. 🚪✨

---

🧚 FUNCTIONS 🧚

🌈 captcha_config()

this method is used to customize how new CAPTCHA images will be created. whatever values you specify here get passed along to the appropriate functions in GD::SecurityImage when a new CAPTCHA is created. iykyk.

it is recommended that you call captcha_config() in the cgiapp_init() method of your CGI::Application base class, and in the setup() method of any derived applications. do it in both, fr fr.

the following parameters are currently accepted:

⭐ IMAGE_OPTIONS

this specifies what options will be passed to the constructor of GD::SecurityImage. please see the documentation for GD::SecurityImage for more information.

⭐ CREATE_OPTIONS

this specifies what options will be passed to the create() method of GD::SecurityImage. please see the documentation for GD::SecurityImage for more information.

⭐ PARTICLE_OPTIONS

this specifies what options will be passed to the particle() method of GD::SecurityImage. please see the documentation for GD::SecurityImage for more information.

⭐ SECRET

this specifies the secret that will be used when generating the checksum hash. guard it with your life. 💜

---

🎀 captcha_create()

creates the CAPTCHA image, and returns a cookie with the encrypted hash of the random string. takes no arguments. not even one. zero. nada.

the cookie created in this method is named hash, and contains only the encrypted hash. future versions of this module will allow you to specify cookie options in greater detail. (it's a coming-soon moment, not a here-right-now moment.)

---

🦋 captcha_verify()

verifies that the value entered by the user matches what was in the CAPTCHA image. argument 1 is the encrypted hash from the cookie sent by captcha_create(), and argument 2 is the value the user entered to verify the CAPTCHA image. returns true if the CAPTCHA was successfully verified, else returns false. simple as that, bestie. ✅

---

🌸 AUTHOR 🌸

Jason A. Crome, <cromedome@cpan.org> — icon, legend, the moment. 👑

---

💅 TODO 💅

the to-do list, bestie, she's short and she's honest:

• Allow captcha_config() to take cookie configuration arguments.
• Allow the plugin to actually create a run mode in your CGI::Application-based webapp without the developer having to manually create one. (we love an automation era.)

---

😭 BUGS 😭

please report any bugs or feature requests to bug-cgi-application-plugin-captcha@rt.cpan.org, or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Application-Plugin-CAPTCHA>.

I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. it's a whole mutual-notification situation. 🫶

---

🌈 CONTRIBUTING 🌈

Patches, questions, and feedback are welcome. come through. 🎀

---

🥹 ACKNOWLEDGEMENTS 🥹

a big thanks to Cees Hek for providing a great module for me to borrow code from (CGI::Application::Plugin::Session), to Michael Peters and Tony Fraser for all of their valuable input, and to the rest who contributed ideas and criticisms on the CGI::Application mailing list.

additional thanks to chorny and Cees for the various bug fixes and patches they have submitted. absolute legends, every single one. 💖

---

🔥 SEE ALSO 🔥

CGI::Application GD::SecurityImage Wikipedia entry for CAPTCHA - <http://en.wikipedia.org/wiki/Captcha>

---

👑 COPYRIGHT & LICENSE 👑

Copyright 2005-2011 Jason A. Crome, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

okay and that's the whole page, bestie!! 🎉 this was CGI::A...CAPTCHA(3pm) — the truncated title is giving ✨mystery✨ — perl v5.36.0, dated 2022-12-20. thanks for reading, go forth and CAPTCHA responsibly, mwah 💋🌈