Postfix SPF readme

-------------------

SPF patch for libspf2 >= 1.2.0 by Nigel Kukard, partly based on work

by Dean Strik's and Jef Poskanzer's spfmilter

Official site:    http://www.linuxrulz.org/nkukard/postfix/

License:          Secure Mailer License (Postfix License)

----

This document describes how to configure Postfix to use SPF ("Sender

Policy Framework") validation. It does not describe the function or

design of SPF itself. Refer to one or more of the websites listed at

the end of this text for more information.

The actual SPF validation is offloaded to a special library called

libspf2. It is therefore necessary that you install libspf2 on your

system. You can find libspf2 either in your usual package repository or

at http://www.libspf2.org/.

To build Postfix, after installing libspf2, use something like:

    % make tidy

    % make makefiles CCARGS="-I/usr/local/include -DHAVE_NS_TYPE" \

        AUXLIBS="-L/usr/local/lib -lspf2"

    % make

-DHAVE_NS_TYPE is only needed if your system complains about ns_type

conflicting.

The pathnames here are the default pathnames used by libspf2's

installation procedure, which is not documented here.

SPF sender validation is implemented using a standard Postfix

restriction, called "reject_spf_invalid_sender". This means that you

can put this restriction in e.g. your smtpd_recipient_restrictions.

For more information on how to do this, consult your Postfix

documentation.

Postfix will by default add a mail header, Received-SPF:, to any mail

passing the SPF validation. This information can be useful for the

recipient of the message. You can disable this behaviour by setting

'spf_received_header = no'.

By default, Postfix will reject mail with invalid sender credentials.

You can however choose to prevent this from happening, and let the mail

pass, by setting 'spf_mark_only = yes'. The Received-SPF: header

(if enabled, see above) will show that the mail failed the test.

You can set the numerical SMTP response code when rejecting mails

due to SPF rule violations by changing the value of the

'spf_reject_code' variable (default: 550).

If a site does provide SPF DNS records yet no explanation, a generic

explanation will be used, with a URL to visit for more information.

You can override this generic explanation by setting the spf_explanation

setting, e.g.:

    spf_explanation = "%{h} [%{i}] is not allowed to send mail for %{s}"

See the SPF reference sites for information about the format used.

It is also possible to set a local policy using the spf_local_policy

setting. Currently the format is not documented here.

There exists a global SPF whitelist on trusted-forwarder.org. You can

enable use of this global whitelist by setting the variable

'spf_global_whitelist = yes'.

----

Bugs/problems/reports: the author of this patch, Nigel Kukard, can be

contacted at <nkukard@lbsd.net>. If reporting a problem, please send

the output of

    postconf -d spf_patch_version spf_libspf2_version

with your report.

Downloads and information with regard to this patch can be found at 

http://www.lbsd.net/~nkukard/postfix/

Links:

	http://www.ipnet6.org/postfix/spf/	- Original patch home

	http://spf.pobox.com/			- SPF background

	http://www.libspf2.org/			- LibSPF2 site

	http://www.trusted-forwarder.org/	- Global whitelist

	http://www.postfix.org/			- Postfix home page

$readme_directory/SPF_README:f:root:-:644

  * SPF support.

  */

#define REJECT_ILL_SPF_SENDER		"reject_spf_invalid_sender"

#define VAR_SPF_REJECT_CODE		"spf_reject_code"

#define DEF_SPF_REJECT_CODE		550

extern int var_spf_reject_code;

#define VAR_SPF_REJECT_DSN              "spf_reject_dsn"

#define DEF_SPF_REJECT_DSN              "5.7.1"

extern char *var_spf_reject_dsn;

#define VAR_SPF_MARK_ONLY		"spf_mark_only"

#define DEF_SPF_MARK_ONLY		0

extern bool var_spf_mark_only;

#define VAR_SPF_RCVD_HEADER		"spf_received_header"

#define DEF_SPF_RCVD_HEADER		1

extern bool var_spf_rcvd_header;

#define VAR_SPF_LOCAL_POLICY		"spf_local_policy"

#define DEF_SPF_LOCAL_POLICY		""

extern char *var_spf_local_policy;

#define VAR_SPF_EXPLANATION		"spf_explanation"

#define DEF_SPF_EXPLANATION		""

extern char *var_spf_explanation;

#define VAR_SPF_GLOBAL_WHITELIST	"spf_global_whitelist"

#define DEF_SPF_GLOBAL_WHITELIST	0

extern bool var_spf_global_whitelist;

 /*

/*

 * SPF patch version.

 */

#define VAR_SPF_PVERSION	"spf_patch_version"

#define DEF_SPF_PVERSION	"1.0.0"

extern char *var_spf_version;

#include <smtpd_spf.h>

bool    var_spf_mark_only;

int     var_spf_reject_code;

char   *var_spf_reject_dsn;

bool    var_spf_rcvd_header;

char   *var_spf_local_policy;

char   *var_spf_explanation;

bool    var_spf_global_whitelist;

    smtpd_spf_sess_reset(state);

     * Prepend Received-SPF header. The header (name,value) has been

     * constructed before in the SPF handler (if SPF is enabled).

     */

    if (var_spf_rcvd_header && state->spf_sess_data != NULL

	    && state->spf_header)

	out_fprintf(out_stream, REC_TYPE_NORM, "%s", state->spf_header);

    /*

        VAR_SPF_REJECT_CODE, DEF_SPF_REJECT_CODE, &var_spf_reject_code, 0, 0,

	VAR_SPF_MARK_ONLY, DEF_SPF_MARK_ONLY, &var_spf_mark_only,

	VAR_SPF_RCVD_HEADER, DEF_SPF_RCVD_HEADER, &var_spf_rcvd_header,

	VAR_SPF_GLOBAL_WHITELIST, DEF_SPF_GLOBAL_WHITELIST, &var_spf_global_whitelist,

	VAR_SPF_LOCAL_POLICY, DEF_SPF_LOCAL_POLICY, &var_spf_local_policy, 0, 0,

	VAR_SPF_EXPLANATION, DEF_SPF_EXPLANATION, &var_spf_explanation, 0, 0,

        VAR_SPF_REJECT_DSN, DEF_SPF_REJECT_DSN, &var_spf_reject_dsn, 0, 0,

#include <arpa/nameser.h>		/* for spf2/spf.h */

#include <sys/socket.h>			/* for spf2/spf.h */

#include <netinet/in.h>			/* for spf2/spf.h */

#include <spf2/spf.h>

     * SPF.

     */

    SPF_request_t *spf_sess_data;	/* session specific SPF data */

    char *spf_header;			/* SPF header to insert */

    /*

#include "smtpd_spf.h"

/* reject_spf_invalid_sender - check sender validity using SPF records */

static int reject_spf_invalid_sender(SMTPD_STATE *state, const char *addr,

			    const char *reply_name, const char *reply_class)

{

    char   *myname = "reject_spf_invalid_sender";

    char   *comment;

    int     action, stat;

    /*

     * Currently, this is the only place where SPF routines are used.

     * It therefore makes little sense to initialize the SPF data

     * before now.

     */

    smtpd_spf_sess_init(state);

    smtpd_spf_set_helo(state, state->helo_name);

    smtpd_spf_set_from(state, state->sender);

    /*

     * Obtain SPF result.

     */

    comment = NULL;

    action = smtpd_spf_result(state,

		(var_spf_rcvd_header ? &state->spf_header : NULL),

		&comment);

    /*

     * Perform actions.

     */

    stat = SMTPD_CHECK_DUNNO;

    switch (action) {

        case SPF_ACTION_REJECT:

            stat = smtpd_check_reject(state, MAIL_ERROR_POLICY,

                    var_spf_reject_code, var_spf_reject_dsn,

                    "<%s>: %s rejected: %s",

                    reply_name, reply_class,

                    (comment ? comment : "SPF policy violation"));

            break;

        case SPF_ACTION_TEMPFAIL:

            /* XXX log error? */

           DEFER_IF_REJECT2(state, MAIL_ERROR_POLICY,

                   450, "4.7.1",

                   "<%s>: %s rejected: Unable to look up SPF information",

                   reply_name, reply_class);

           break;

        default:

           break;

    }

    /*

     * Cleanup.

     */

    if (comment != NULL)

        myfree(comment);

    return (stat);

}

	} else if (strcasecmp(name, REJECT_ILL_SPF_SENDER) == 0) {

	    if (state->sender && *state->sender)

		status = reject_spf_invalid_sender(state, state->sender,

					  state->sender, SMTPD_NAME_SENDER);

/*++

/* NAME

/*	smtpd_spf 3

/* SUMMARY

/*	SMTP server SPF support

/* SYNOPSIS

/*	#include <smtpd.h>

/*	#include <smtpd_spf.h>

/*

/*	void	smtpd_spf_init(state)

/*	SMTPD_STATE *state;

/*

/*	int	smtpd_spf_sess_init(state)

/*	SMTPD_STATE *state;

/*

/*	void	smtpd_spf_sess_reset(state)

/*	SMTPD_STATE *state;

/*

/*	int	smtpd_spf_set_helo(state, name)

/*	SMTPD_STATE *state;

/*	char	*name;

/*

/*	int	smtpd_spf_set_from(state, name)

/*	SMTPD_STATE *state;

/*	char	*name;

/*

/*	int	smtpd_spf_result(state, *header, *comment)

/*	SMTPD_STATE *state;

/*	char	**header;

/*	char	**comment;

/*

/* DESCRIPTION

/*	This modules provides SPF state management functions,

/*	making the other SMTP components independent on the

/*	actual SPF routines used.

/*

/*	smtpd_spf_init() initializes global SPF context.

/*

/*	smtpd_spf_sess_init() initializes SPF session context.

/*

/*	smtpd_spf_sess_reset() cleans up SPF session context.

/*

/*	smtpd_spf_set_helo() passes the client HELO name to

/*	the underlying libspf2 context.

/*

/*	smtpd_spf_set_from() passes the SMTP envelope sender

/*	to the underlying libspf2 context.

/*

/*	smtpd_spf_result() performs (via libspf2) the SPF lookups

/*	and handling, and creates a Received-SPF header.

/*

/*	Arguments:

/* .IP state

/*	Session context.

/* .IP name

/*	The value to set in the low-level SPF context.

/* DIAGNOSTICS

/*	Panic: interface violations. Fatal errors: out of memory.

/*	internal protocol errors.

/* LICENSE

/* .ad

/* .fi

/*	The Secure Mailer license must be distributed with this software.

/* AUTHOR(S)

/* 	Nigel Kukard

/* 	E-mail: <nkukard@lbsd.net>

/* 

/*      Dean C. Strik

/*      Department ICT

/*      Eindhoven University of Technology

/*      P.O. Box 513

/*      5600 MB  Eindhoven, Netherlands

/*      E-mail: <dean@ipnet6.org>

/*--*/

/* System library. */

#include <sys_defs.h>

#include <sys/socket.h>

#include <netinet/in.h>

#include <arpa/inet.h>

#include <arpa/nameser.h>

#include <errno.h>

#include <netdb.h>

#include <string.h>

#include <spf2/spf.h>

#include <spf2/spf_dns_resolv.h>

#include <spf2/spf_dns_cache.h>

/* Global library */

#include <mail_params.h>

#include <msg.h>

#include <mymalloc.h>

/* Application library */

#include "smtpd.h"

#include "smtpd_spf.h"

#define SPF_DNS_CACHE_BITS 8

//static SPF_config_t	spf_global_data;	/* common SPF configuration data */

//static SPF_dns_config_t	spf_resolv_data;	/* SPF DNS resolver data */

//static SPF_dns_config_t	spf_resolv_cache;	/* SPF DNS resolver cache */

//static SPF_c_results_t	spf_local_policy;	/* compiled local policy */

//static SPF_c_results_t	spf_explanation;	/* custom explanation */

static SPF_server_t	*spf_global_server;

/* Initialize global SPF context */

void smtpd_spf_init(SMTPD_STATE *state)

{

	char   *myname = "smtpd_spf_global_init";

	SPF_response_t *spf_response;

	int res;

	/*

	* Initialize libspf2 server

	*/

	spf_global_server = SPF_server_new(SPF_DNS_CACHE, 0);

	if (spf_global_server == NULL)

		msg_fatal("%s: unable to create SPF server", myname);

	if (SPF_server_set_rec_dom(spf_global_server, var_myhostname) != 0)

		msg_fatal("%s: can't set SPF hostname", myname);

	if (var_spf_explanation != NULL && *var_spf_explanation != 0)

	{

		res = SPF_server_set_explanation(spf_global_server, var_spf_explanation, 

				&spf_response);

		SPF_response_free(spf_response);

		if (res != 0)

		{	

			msg_fatal("%s: can't set SPF explanation", myname);

		}

	}

	if (var_spf_local_policy != NULL && *var_spf_local_policy != 0)

	{	

		res = SPF_server_set_localpolicy(spf_global_server, var_spf_local_policy, 0, 

				&spf_response);

		SPF_response_free(spf_response);

		if (res != 0)

		{	

			msg_fatal("%s: can't set SPF local policy", myname);

		}

	}

	/*

	* Clear session-specific data (session init is on-demand)

	*/

	state->spf_sess_data = NULL;

	state->spf_header = NULL;

}

/* Initialize session dependent SPF context */

int smtpd_spf_sess_init(SMTPD_STATE *state)

{

	char   *myname = "smtpd_spf_init_sess_data";

	/*

	 * Sanity checks.

	 */

	if (state->addr == 0)

		msg_panic("%s: client address not initialized", myname);

	if (spf_global_server == NULL)

		msg_panic("%s: spf_global_server not initialized", myname);

	/*

	 * This code is recipient-independent. SPF session data is

	 * already initialized if there have been earlier RCPT TO

	 * commands in this transaction, and we're done.

	 * XXX: make the code recipient-dependent (restriction classes)

	 */

	if (state->spf_sess_data != NULL)

		return 0;

	/*

	 * Initialize session-specific SPF data.

	 */

	state->spf_sess_data = SPF_request_new(spf_global_server);

	if (state->spf_sess_data == NULL)

		msg_fatal("%s: failed to create SPF session data structure",

				myname);

	state->spf_header = NULL;

	/*

	 * Pass client address to libspf2.

	 */

	if (SPF_request_set_ipv4_str(state->spf_sess_data, state->addr) != 0)

		msg_fatal("%s: SPF_request_set_ipv4 failure", myname);

	return 0;

}

/* Cleanup after disconnect */

void smtpd_spf_sess_reset(SMTPD_STATE *state)

{

	char   *myname = "smtpd_spf_sess_reset";

	/*

	 * Sanity checks.

	 */

	if (spf_global_server == NULL)

		msg_panic("%s: no global SPF data initialized", myname);

	if (state->spf_sess_data == NULL)

		return; /* initialisation is only on demand */

	/*

	 * Cleanup SPF session data.

	 */

	if (state->spf_header != NULL)

		myfree(state->spf_header);

	state->spf_header = NULL;

	SPF_request_free(state->spf_sess_data);

	state->spf_sess_data = NULL;

}

/* Pass HELO/EHLO name to libspf2 */

int smtpd_spf_set_helo(SMTPD_STATE *state, const char *name)

{

	char   *myname = "smtpd_spf_set_helo";

	/*

	 * Sanity checks.

	 *

	 * 'name' may be NULL, to unset registered HELO. This may

	 * even happen when SPF is not initialized yet (SPF init

	 * is only on demand).

	 */

	if (state->spf_sess_data == NULL && name == NULL)

		return 0;

	if (state->spf_sess_data == NULL)

		msg_panic("%s: setting SPF HELO with null session",

			myname);

	/*

	 * Pass the HELO name to libspf2.

	 */

	if (SPF_request_set_helo_dom(state->spf_sess_data, name) != 0)

		msg_fatal("%s: error in SPF_request_set_helo_dom", myname); 

	return 0;

}

/* Pass sender (env.from) name to libspf2 */

int smtpd_spf_set_from(SMTPD_STATE *state, const char *name)

{

	char *myname = "smtpd_spf_set_from";

	/*

	 * Pass the envelope sender to libspf2.

	 */

	if (SPF_request_set_env_from(state->spf_sess_data, state->sender) != 0)

		msg_fatal("%s: error in SPF_request_set_env_from", myname);

	return 0;

}

/* Obtain SPF result */

int smtpd_spf_result(SMTPD_STATE *state, char **headerp, char **commentp)

{

	char *myname = "smtpd_spf_result";

	int action = SPF_ACTION_UNKNOWN;

	SPF_response_t *spf_response = NULL;

	int res;

	char *res_received_spf;

	char *res_smtp_comment;

	/*

	 * Obtain SPF result.

	 */

	res = SPF_request_query_mailfrom(state->spf_sess_data, &spf_response);

	if (res != 0)

		goto clean_end;

	res = SPF_response_result(spf_response);

	switch (res) {

		case SPF_RESULT_PASS:

		case SPF_RESULT_SOFTFAIL:

		case SPF_RESULT_NEUTRAL:

		case SPF_RESULT_NONE:

			action = SPF_ACTION_MARK;

			break;

		case SPF_RESULT_FAIL:

			action = var_spf_mark_only ? SPF_ACTION_MARK : SPF_ACTION_REJECT;

			break;

		default:	

			msg_warn("%s: unknown SPF result %d (%s)", myname, res,

					SPF_strresult(res));

			action = SPF_ACTION_ACCEPT;

			break;

	}

	/*

	 * Save the output header/comment.

	 */

	res_received_spf = SPF_response_get_received_spf(spf_response);

	res_smtp_comment = SPF_response_get_smtp_comment(spf_response);

	if (headerp != NULL && res_received_spf != NULL)

		*headerp = mystrdup(res_received_spf);

	if (commentp != NULL && res_smtp_comment != NULL)

		*commentp = mystrdup(res_smtp_comment);

	/*

	 * Cleanup.

	 */

clean_end:		

	SPF_response_free(spf_response);

	return (action);

}

/*++

/* NAME

/*	smtpd_spf 3h

/* SUMMARY

/*	SMTP server SPF support

/* SYNOPSIS

/*	#include <smtpd.h>

/*	#include <smtpd_spf.h>

/* DESCRIPTION

/* .nf

 /*

  * External interface.

  */

extern void smtpd_spf_init(SMTPD_STATE *);

extern int smtpd_spf_sess_init(SMTPD_STATE *);

extern void smtpd_spf_sess_reset(SMTPD_STATE *);

extern int smtpd_spf_set_helo(SMTPD_STATE *, const char *);

extern int smtpd_spf_set_from(SMTPD_STATE *, const char *);

extern int smtpd_spf_result(SMTPD_STATE *, char **, char **);

#define SPF_ACTION_UNKNOWN  0

#define SPF_ACTION_ACCEPT   1

#define SPF_ACTION_REJECT   2

#define SPF_ACTION_MARK     3

#define SPF_ACTION_TEMPFAIL 4

/* LICENSE

/* .ad

/* .fi

/*	The Secure Mailer license must be distributed with this software.

/* AUTHOR(S)

/* 	Nigel Kukard

/* 	E-mail: <nkukard@lbsd.net>

/* 

/*      Dean C. Strik

/*      Department ICT

/*      Eindhoven University of Technology

/*      P.O. Box 513

/*      5600 MB  Eindhoven, Netherlands

/*      E-mail: <dean@ipnet6.org>

/*--*/

#include "smtpd_spf.h"

     * Initialize SPF connection-specific information.

     */

    smtpd_spf_init(state);

    /*

    smtpd_spf_sess_reset(state);