5.7 Using Guile Actions

The name Guile stands for GNU's Ubiquitous Intelligent Language for Extensions. It provides a Scheme interpreter conforming to the R4RS language specification. GNU Anubis uses Guile as its extension language.

This section describes how to write GNU Anubis actions in Scheme. It assumes that the reader is sufficiently familiar with the Scheme language. For information about the language, refer to (r4rs)Top section `Top' in Revised(4) Report on the Algorithmic Language Scheme. For more information about Guile, See (guile)Top section `Overview' in The Guile Reference Manual.

Predefined Guile Actions

5.7.1 Defining Guile Actions

A Guile action is defined as follows:

(define (function-name header body . rest)
 ...)

Its arguments are:

header

List of message headers. Each list element is a cons

(name . value)

where name is the name of the header field, and value is its value with final CRLF stripped off. Both name and value are strings.

body

A string containing the message body.

rest

Any additional arguments passed to the function from the configuration file (see section Invoking Guile Actions). This argument may be absent if the function is not expected to take optional arguments.

The function must return a cons whose car contains the new message headers, and cdr contains the new message body. If the car is #t, it means that no headers are changed. If the cdr is #t, it means that the body has not changed. If the cdr is #f, Anubis will delete the entire message body.

As the first example, let's consider a no-operation action, i.e. an action that does not alter the message in any way. It can be written in two ways:

(define (noop-1 header body)
  (cons header body))
  
(define (noop-2 header body)
  (cons #t #t))

The following example is a function that deletes the message body and adds an additional header:

(define (proc header body)
  (cons (append header
                (cons "X-Body-Deleted" "yes"))
        #f))

Let's consider a more constructive example. The following function checks if the Subject header starts with string ‘ODP:’ (a Polish equivalent to ‘Re:’), and if it does, the function replaces it with ‘Re:’. It always adds to the message the header

X-Processed-By: GNU Anubis

Additionally, if the optional argument is given, it is appended to the body of the message.

(define (fix-subject hdr body . rest)
  "If the Subject: field starts with characters \"ODP:\", replace
them with \"Re:\".
If REST is not empty, append its car to BODY"
  (cons (append
	 (map (lambda (x)
		(if (and (string-ci=? (car x) "subject")
			 (string-ci=? (substring (cdr x) 0 4) "ODP:"))
		    (cons (car x)
			  (string-append "Re:"
					 (substring (cdr x) 4)))
		    x))
	      hdr)
	 (list (cons "X-Processed-By" "GNU Anubis")))
	(if (null? rest)
	    #t
	    (string-append body "\n" (car rest)))))

5.7.2 Invoking Guile Actions

The Guile actions are invoked from the RULE section using the guile-process command. Its syntax is:

Scheme Function: function args

Arguments:

function

The name of the Guile function to be invoked.

args

Additional arguments. These are passed to the function as its third argument (rest).

To pass keyword arguments to the function, use the usual Scheme notation: ‘#:key’.

As an example, let's consider the invocation of the fix-subject function, defined in the previous subsection:

guile-process fix-subject <<-EOT
                                ----------
                                Kind regards,
                                Antonius Block
                          EOT

In this example, the additional argument (a string of three lines) is passed to the function, which will add it to the message of the body.

5.7.3 Support for ROT-13

The ROT-13 transformation is a simple form of encryption where the letters A-M are transposed with the letters L-Z. It is often used in Usenet postings/mailing lists to prevent people from accidentally reading a disturbing message.

GNU Anubis supports ROT-13 via a loadable Guile function. To enable this support, you will have to add the following to your GUILE section:

guile-load-program rot-13.scm

Then, in your RULE section use:

Scheme Function: rot-13 keyword-arguments

The command accepts the following keyword-arguments:

#:body

Encrypt the entire body of the message

#:subject

Encrypt the ‘Subject’ header.

For example:

trigger "rot-13.*body" guile-process rot-13 #:body done trigger "rot-13.*subj" guile-process rot-13 #:subject done

5.7.4 Remailers Type-I

GNU Anubis supports remailers of type I. The support is written entirely in Scheme. To enable it you need to specify the following in the GUILE section of your configuration file:

guile-load-program remailer.scm

To send the message via a remailer, use the following command in the RULE section:

Scheme Function: remailer-I keyword-arguments

The keyword-arguments specify the various parameters for the remailer. These are:

#:rrt string

This is the only required keyword argument. It sets the value for the Request Remailing To line. string should be your actual recipient's email address.

#:post news-group

Adds the ‘Anon-Post-To: news-group’ line, and prepares the message for sending it to the Usenet via a remailer. Note, that this is only possible with remailers that support ‘Anon-Post-To:’ header.

#:latent time

Adds the ‘Latent-Time:’ line, that causes a remailer to keep your message for specified time before forwarding it.

#:random

Adds random suffix to the latent time.

#:header string

Adds an extra header line to the remailed message.

Example:

trigger "remail:(.*)/(.*)" guile-process remailer-I \ #:rrt antonius_block@helsingor.net \ #:post \1 \ #:latent \2 \ #:header "X-Processed-By: GNU Anubis & Remailer-I" done

Some remailers require the message to be GPG encrypted or signed. You can achieve this by placing gpg-encrypt or gpg-sign statement right after the invocation of remailer-I, for example:

trigger "remail:(.*)/(.*)"
 guile-process remailer-I \
             #:rrt antonius_block@helsingor.net \
             #:post \1 \
             #:latent \2 \
             #:header "X-Processed-By: GNU Anubis & Remailer-I"
 gpg-sign mykey
done

See section Mail Encryption, for more information on mail encryption in GNU Anubis.

5.7.5 Entire Message Filters

There may be some cases when you need to use an external filter that processes the entire message (including headers). You cannot use external-body-processor, since it feeds only the message body to the program. To overcome this difficulty, GNU Anubis is shipped with ‘entire-msg.scm’ module. This module provides Scheme function entire-msg-filter, which is to be used in such cases.

Scheme Function: entire-msg-filter program [args]

Feeds entire message to the given program. The output from the program replaces message headers and body.

progname

Full pathname of the program to be executed.

args

Any additional arguments it may require.

Suppose you have a program /usr/libexec/myfilter, that accepts entire message as its output and produces on standard output a modified version of this message. The program takes as its argument he name of a directory for temporary files. The following example illustrates how to invoke this program:

BEGIN GUILE
guile-load-program entire-msg.scm
END

BEGIN RULE
guile-process entire-msg-filter /usr/libexec/myfilter /tmp
END

Another function defined in this module is openssl-filter:

Scheme Function: openssl-filter program [args]

This function is provided for use with openssl program. Openssl binary attempts to rewind its input and fails if the latter is a pipe, so openssl cannot be used with entire-msg-filter. Instead, you should use openssl-filter. Its arguments are:

program

Path to openssl binary.

args

Its arguments

See section Using S/MIME Signatures, for an example of use of this function.

This document was generated by Sergey Poznyakoff on December, 20 2008 using texi2html 1.78.