File: README

package info (click to toggle)
libcgi-application-plugin-captcha-perl 0.04-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid, stretch
  • size: 176 kB
  • ctags: 18
  • sloc: perl: 263; makefile: 2
file content (184 lines) | stat: -rw-r--r-- 7,186 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
NAME
    CGI::Application::Plugin::CAPTCHA - Easily create, use, and verify
    CAPTCHAs in CGI::Application-based web applications.

VERSION
    Version 0.04

SYNOPSIS
        # 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"));
        }

DESCRIPTION
    "CGI::Application::Plugin::CAPTCHA" allows programmers to easily add and
    verify CAPTCHAs in their CGI::Application-derived web applications.

    A CAPTCHA (or Completely Automated Public Turing Test to Tell Computers
    and Humans Apart) is an image with a random string of characters. A user
    must successfully enter the random string in order to submit a form.
    This is a simple (yet annoying) procedure for humans to complete, but
    one that is significantly more difficult for a form-stuffing script to
    complete without having to integrate some sort of OCR.

    CAPTCHAs are not a perfect solution. Any skilled, diligent cracker will
    eventually be able to bypass a CAPTCHA, but it should be able to shut
    down your average script-kiddie.

    "CGI::Application::Plugin::CAPTCHA" is a wrapper for GD::SecurityImage.
    It makes it more convenient to access GD::SecurityImage functionality,
    and gives a more CGI::Application-like way of doing it.

    When a CAPTCHA is created with this module, raw image data is
    transmitted from your web application to the client browser. A cookie
    containing a checksum is also transmitted with the image. 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 allow the user to continue processing
    their form.

    The checksum is generated by taking the string in question, and joining
    it with a SECRET. We then 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 do not know the value of our
    SECRET. This means it is important to choose a good value for your
    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.

FUNCTIONS
  captcha_config()
    This method is used to customize how new CAPTCHA images will be created.
    Values specified here are passed along to the appropriate functions in
    GD::SecurityImage when a new CAPTCHA is created.

    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.

    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.

  captcha_create()
    Creates the CAPTCHA image, and return a cookie with the encrypted hash
    of the random string. Takes no arguments.

    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.

  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.

AUTHOR
    Jason A. Crome, "<cromedome@cpan.org>"

TODO
    *   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.

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-C
    APTCHA>. I will be notified, and then you'll automatically be notified
    of progress on your bug as I make changes.

CONTRIBUTING
    Patches, questions, and feedback are welcome.

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.

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.