The cl-recaptcha Reference Manual

Table of Contents

The cl-recaptcha Reference Manual

This is the cl-recaptcha Reference Manual, version 2.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 15:14:31 2021 GMT+0.

1 Introduction

cl-recaptcha

cl-recaptcha is a simple interconnection between recaptcha.com and common-lisp. It can be used for the trivial usage of the recaptcha service.

dependencies

cl-recaptcha requires cl-ppcre, flexi-streams, jsown and drakma. This library is available via quicklisp.

(ql:quickload :cl-recaptcha)

usage

The simplest way to use cl-recaptcha is to get a public and private key from "https://www.google.com/recaptcha/intro/index.html". Set the key in cl-recaptcha, insert the needed code in your site and ask cl-recaptcha for verification. All this should look somewhat like this:

(setf cl-recaptcha:*site-key* "your-site-key")
(setf cl-recaptcha:*secret-key* "your-secret-key")

In the source of the page, insert a call to challenge where you want to have your recaptcha inserted.

;; Javascript enabled version
(challenge-js)

or

;; Javascript with a noscript tag
(challenge-ns)

Assuming you get your post-vars by (get-post-var "varname") and the ip of the user by (get-ip-address), you can check the validity of the entry of the user by running:

(verify-captcha (get-post-var "g-recaptcha-response") (get-ip-address))

Please note that the ip address is an optional parameter, as it is not required by the recaptcha API call itself.

The verify-captcha function will return T on success and nil on failure. The second value it returns specifies the reason why the challenge was rejected. The result is returned as a list, however the error is usually a single string.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 cl-recaptcha

Maintainer

Aad Versteden <madnificent@gmail.com>

Author

Aad Versteden <madnificent@gmail.com>

License

MIT

Description

Trivial support for the recaptcha service

Version

2.0.0

Dependencies

• drakma
• cl-ppcre
• flexi-streams
• jsown

Source

cl-recaptcha.asd (file)

Component

code.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 cl-recaptcha.asd

Location

cl-recaptcha.asd

Systems

cl-recaptcha (system)

Packages

cl-recaptcha.sysdef

3.1.2 cl-recaptcha/code.lisp

Parent

cl-recaptcha (system)

Location

code.lisp

Packages

cl-recaptcha

Exported Definitions

• *recaptcha-header-script-tag* (special variable)
• *secret-key* (special variable)
• *site-key* (special variable)
• challenge-js (function)
• challenge-ns (function)
• verify-captcha (function)

Internal Definitions

*captcha-verify-url* (special variable)

4 Packages

Packages are listed by definition order.

4.1 cl-recaptcha.sysdef

Source

cl-recaptcha.asd

Use List

• asdf/interface
• common-lisp

4.2 cl-recaptcha

Source

code.lisp (file)

Use List

• flexi-streams
• drakma
• jsown
• common-lisp

Exported Definitions

• *recaptcha-header-script-tag* (special variable)
• *secret-key* (special variable)
• *site-key* (special variable)
• challenge-js (function)
• challenge-ns (function)
• verify-captcha (function)

Internal Definitions

*captcha-verify-url* (special variable)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *recaptcha-header-script-tag*

The source of the javascript file, the standard value comes from recaptcha itself and should be available in any case

Package

cl-recaptcha

Source

code.lisp (file)

Special Variable: *secret-key*

Secret key for the recaptcha service. This is mainly used server side to validate the challenge resopnse. Register at https://www.google.com/recaptcha/intro/index.html

Package

cl-recaptcha

Source

code.lisp (file)

Special Variable: *site-key*

Site key for the recaptcha service. This is public facing and will appear in the div element that holds the recaptcha form. Register at https://www.google.com/recaptcha/intro/index.html

Package

cl-recaptcha

Source

code.lisp (file)

5.1.2 Functions

Function: challenge-js &key SITE-KEY THEME CALLBACK EXPIRED-CALLBACK

This is the javascript-enabled version of the challenge, recaptcha advises you to use this.

Package

cl-recaptcha

Source

code.lisp (file)

Function: challenge-ns &key SITE-KEY THEME CALLBACK EXPIRED-CALLBACK

This is the javascript-disabled version of the challenge. Google does not recommend it’s use if Javascript is a requirement for your site

Package

cl-recaptcha

Source

code.lisp (file)

Function: verify-captcha G-RECAPTCHA-RESPONSE &optional REMOTE-IP &key SECRET-KEY

Verifies the result the user gave. There are two values returned. The first indicates the success or failure, the second indicates the error code the captcha-server gave. Errors are returned in a list (just as the original JSON response returns errors in an array).

Package

cl-recaptcha

Source

code.lisp (file)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *captcha-verify-url*

This is the URL that will be used to verify the result of the captcha. This is the one recaptcha provides

Package

cl-recaptcha

Source

code.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types