Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
opendkim-lua(3)		   Library Functions Manual	       opendkim-lua(3)

NAME
       opendkim-lua - Programming the OpenDKIM filter using Lua	scripts

DESCRIPTION
       The  OpenDKIM  filter has hooks to run user-provided scripts for	making
       policy decisions	regarding signatures to	add on	outbound  messages  or
       verification  and  acceptance  of messages inbound.  The	hooks take the
       form of multiple	Lua scripts which, if defined, are  run	 at  important
       points during processing	of a message.

       For  a  full  description  of the Lua language, consult Lua programming
       references (see below for a starting point).  This man  page  only  de-
       scribes	the  use  of  Lua in the context of OpenDKIM, specifically the
       functions and global variables OpenDKIM provides	for use	 in  user-con-
       structed	scripts	beyond what Lua	provides by default.

       Unless  otherwise  noted, all functions described below return a	single
       result; on success they return the requested data, and  on  error  they
       return the Lua constant "nil".

       Four scripting hooks are	provided.  They	are as follows:

       setup  The  setup  script is run	after all headers for the message have
	      been received but	before any DKIM	operations have	 started.   At
	      this  point  the user can	examine	the available header fields to
	      decide whether the message should	 be  signed  or	 verified  (or
	      both) and, if signing, which key(s) should be used to add	signa-
	      tures and	which signature	features are desired.

       screen The screen script	is run after the DKIM verification context has
	      been  established.   The	main purpose of	this script is to give
	      the user an opportunity to examine  the  message	header	fields
	      compared	to  the	available DKIM signatures and determine	which,
	      if any, should be	ignored	during verification.  For example, the
	      user  might  decide  only	 signatures  added  by domains exactly
	      matching that in the From: domain	are acceptable,	and  the  rest
	      should be	ignored.

       statistics
	      The  statistics script is	run after all of the DKIM verification
	      and signing work has been	completed but before any final message
	      handling	is  done.   The	main purpose of	this script is to give
	      the user an opportunity to examine the message or	its signatures
	      and  make	 arbitrary  additional	statistical  observations that
	      should be	recorded by the	statistics module.  (Experimental fea-
	      ture not enabled for this	installation.)

       final  The  final  script is run	after all of the DKIM verification and
	      signing work has been completed.	The user has an	opportunity to
	      examine the results of all of the	signature evaluations and make
	      a	decision about whether or not the message should be  accepted,
	      rejected,	 discarded,  quarantined,  etc.	 If the	message	is ac-
	      cepted, any signatures requested earlier will be	added  to  the
	      messages before it is released.

GLOBAL VARIABLES
       The following global variable(s)	are provided for all user scripts:

       ctx    This  is	a  generic context pointer referring to	the context in
	      which the	filtering operation is being performed.	 It represents
	      a	 single	 message in progress, and the connection that accepted
	      it.

SETUP SCRIPT FUNCTIONS
       These functions are made	available to  Lua  for	processing  a  message
       through the setup script:

       odkim.check_popauth(ctx)
	      Returns  1  if the SMTP client represented by ctx	is coming from
	      an IP address found in the POPAUTH database (if enabled and con-
	      figured),	 and  0	 otherwise.  Returns the Lua constant "nil" if
	      the POPAUTH database is not enabled or not configured.

       odkim.db_check(db, string)
	      Returns 1	if db refers to	 a  valid  database  handle  (see  od-
	      kim.get_dbhandle()  below) and string is found in	that database,
	      and 0 otherwise.	If an error occurs, the	Lua constant "nil"  is
	      returned.

       odkim.db_close(db)
	      Closes  the  specified data set.	Returns	1.  The	current	imple-
	      mentation	will conduct data  set	garbage	 collection  when  the
	      script  terminates,  so  this  is	not strictly necessary,	but is
	      recommended.

       odkim.db_open(name[, icase])
	      Opens the	data set specified by name.  If	icase is provided  and
	      is  "true", then queries into the	database will be case-insensi-
	      tive.  See the opendkim(8) man page for information on  specify-
	      ing a data set.  On success, returns a handle that can be	passed
	      to odkim.db_check(); raises an exception on failure.

       odkim.export(ctx, name, value[, name2, value2[, ...]])
	      Exports variables	named with their corresponding values so  that
	      they will	be available to	later scripts.

       odkim.get_clienthost(ctx)
	      Returns  the  name of the	host on	the other end of the SMTP con-
	      nection sending the current message.  This is  usually  a	 host-
	      name,  but might be an IP	address	in square brackets if the SMTP
	      client's IP address does not have	a name associated with it.

       odkim.get_clientip(ctx)
	      Returns the IP address of	the client on the  other  end  of  the
	      SMTP  connection	sending	the current message as a string.  Both
	      IPv4 and IPv6 addresses are supported.

       odkim.get_dbhandle(ctx, db)
	      Returns a	handle for the requested database that can be used  in
	      later  queries.  The value of db should be one of	DB_MTAS	(data-
	      base of MTA names	whose mail should be signed), DB_MACROS	(data-
	      base  of	MTA macro checks to be done when determining signing),
	      DB_DOMAINS (database of domains to be  signed),  DB_SIGNINGTABLE
	      (database	 of signing table entries), DB_THIRDPARTY (database of
	      third party signatures to	be trusted) and	 DB_DONTSIGNTO	(data-
	      base of recipients whose mail should not be signed).  If the re-
	      quested database is not set in the current configuration file, a
	      Lua "nil"	is returned.

       odkim.get_envfrom(ctx)
	      Retrieves	 the SMTP envelope sender address for the message rep-
	      resented by ctx.

       odkim.get_fromdomain(ctx)
	      Retrieves	the domain name	of the sender of  the  message	repre-
	      sented by	ctx.

       odkim.get_header(ctx, name, n)
	      Retrieves	the string contained in	instance n of the header field
	      called name from the message represented by ctx, or the Lua con-
	      stant  "nil"  if	there  was no such header field.  Header field
	      numbering	starts at 0, so	use 0 for the first  instance,	1  for
	      the second, etc.	For example:

	      fromaddr = odkim.get_header(ctx, "From", 0)

	      This  will  return  the  value of	the first (and hopefully only)
	      "From" header field.  Negative values of n count backwards  from
	      the end of the set of header fields, so:

	      rcvd = odkim.get_header(ctx, "Received", -2)

	      will retrieve the	second-last Received: header field on the mes-
	      sage.

       odkim.get_mtasymbol(ctx,	name)
	      Retrieves	the value of the symbol	called name from the MTA  con-
	      nection represented by ctx, or the Lua constant "nil" if the re-
	      quested symbol was not available at the time of the request.

       odkim.get_rcpt(ctx, n)
	      Returns the nth envelope recipient for the  message  represented
	      by  ctx.	 Recipient numbering starts at 0, so for the first re-
	      cipient, use 0 for n.  If	n references  an  out-of-range	value,
	      the Lua constant "nil" is	returned.

       odkim.get_rcptarray(ctx)
	      Returns  the  envelope recipients	for the	message	represented by
	      ctx in a single Lua array.

       odkim.internal_ip(ctx)
	      Returns 1	if the SMTP client is coming from an internal  IP  ad-
	      dress, and 0 otherwise.

       odkim.log(ctx, log)
	      Logs  the	string log if the current configuration	requested log-
	      ging.  (Checking current configuration is	why the	ctx  parameter
	      is required.)

       odkim.rcpt_count(ctx)
	      Returns the count	of envelope recipients on the message.

       odkim.replace_header(ctx, name, n, newval)
	      Retrieves	the value of in	instance n of header field name	in the
	      message referenced by ctx	and replaces it	 with  the  string  in
	      newval.  See odkim.get_header() above for	more information about
	      possible parameter values	for n.	Note that  this	 only  changes
	      the  content of the header field used when generating or verify-
	      ing the signature; the actual delivered message is not modified.
	      This can be used to anticipate how an intermediate mail transfer
	      agent might alter	the message, thus correcting an	avoidable sig-
	      nature invalidation.

       odkim.resign(ctx)
	      Arranges that the	arriving message will be verified and then re-
	      signed in	a single operation.  Returns 1 on success or  the  Lua
	      constant "nil" on	failure.

       odkim.set_result(ctx, result)
	      Arranges	to  have  the MTA return a specific result code	in re-
	      sponse to	the message represented	by ctx.	 The value  of	result
	      must be one of SMFIS_TEMPFAIL (temporary failure/rejection), SM-
	      FIS_ACCEPT (accept without  further  processing),	 SMFIS_DISCARD
	      (accept  but  discard  the  message) and SMFIS_REJECT (permanent
	      failure/rejection).  Returns 1 on	success	or  the	 Lua  constant
	      "nil"  on	failure.  Note that returning any of these codes indi-
	      cates a final message disposition; the MTA will be told  immedi-
	      ately  to	 take the specified action, and	no further filter pro-
	      cessing will occur.

       odkim.sign(ctx[,	keyname[, signer[, signlen]]])
	      Requests that the	filter sign the	message	represented by ctx us-
	      ing the specified	keyname.  The key name will be translated into
	      an actual	domain,	selector and private key via a	query  to  the
	      KeyTable	(see the opendkim.conf(5) page for details).  The key-
	      name may be omitted if the KeyTable is not defined, meaning  the
	      single  signing domain, selector and key should be used to sign.
	      Returns 1	on success and 0 on failure.  If a  signer  is	speci-
	      fied,  the string	there will be included in the generated	signa-
	      ture's "i=" tag.	If a signlen is	specified, the signature  will
	      cover  that  many	bytes of the message body.  The	order of these
	      last two parameters is interchangeable.

       odkim.signfor(ctx, address[, multi])
	      Applies whatever signatures would	be applied by default  if  the
	      candidate	 message  had  the  specified address in the message's
	      From:  field.   The  multi  parameter,  if  "true"  (default  is
	      "false"),	 allows	 the  application of multiple signatures.  Re-
	      turns the	number of signatures applied, which may	be zero.

       odkim.spam(ctx)
	      Tags the message as spam,	for use	in developing reputation about
	      domains  that signed the message.	 Returns nothing.  (Experimen-
	      tal feature not enabled for this installation.)

       odkim.use_ltag(ctx)
	      Requests that all	signatures added to the	message	represented by
	      ctx  include  "l="  (body	 length) tags.	Always returns the Lua
	      constant "nil".

       odkim.verify(ctx)
	      Requests that the	message	represented by	ctx  be	 subjected  to
	      DKIM  signature verification.  Returns the Lua constant "nil" on
	      success, or an error string on failure.

       odkim.xtag(ctx, tag, value)
	      Requests that all	signatures added to the	message	represented by
	      ctx include the named extension tag and value.  Returns the num-
	      ber of signatures	successfully modified, or -1 on	error.	An er-
	      ror  can	occur  if the named tag	is one already explicitly sup-
	      ported by	the DKIM library, or if	there is a syntax error	in the
	      tag or value.

SCREEN SCRIPT FUNCTIONS
       The  screen  script  has	the following functions	available to it, whose
       descriptions can	be found above:	 odkim.db_check,  odkim.db_close,  od-
       kim.db_open,  odkim.export,  odkim.get_dbhandle,	odkim.get_envfrom, od-
       kim.get_fromdomain,    odkim.get_header,	   odkim.get_mtasymbol,	   od-
       kim.get_rcpt, odkim.get_rcptarray, odkim.log, odkim.rcpt_count, and od-
       kim.spam.

       The following additional	functions are provided for this	script:

       odkim.get_sigarray(ctx)
	      Returns the complete set of signature handles found in the  mes-
	      sage  represented	 by  ctx,  as a	Lua array, or the Lua constant
	      "nil" in case of an error.

       odkim.get_sigcount(ctx)
	      Returns the number of signatures found  in  the  message	repre-
	      sented by	ctx, or	the Lua	constant "nil" in case of an error.

       odkim.get_sighandle(ctx,	n)
	      Returns a	handle representing an internal	copy of	the nth	signa-
	      ture found on the	message	represented by ctx.  n must be a  num-
	      ber greater than or equal	to zero	(representing the first	signa-
	      ture) and	less than the number of	 signatures  on	 the  message,
	      which can	be determined using odkim.get_sigcount above.  The re-
	      quested handle is	returned on success, or	the Lua	constant "nil"
	      is returned on failure.

       odkim.parse_field(string)
	      Parses  the contents of a	header field, provided as string, into
	      user and domain parts, discarding	whitespace and comment	compo-
	      nents.   Returns two strings, the	user part and the domain part,
	      or the Lua constant "nil"	in case	of a parsing error.

       odkim.sig_getdomain(sig)
	      Returns the name of the domain in	the signature handle specified
	      by  sig, previously returned by a	call to	odkim.get_sighandle().
	      This is taken from the signature's "d=" tag.

       odkim.sig_getidentity(sig)
	      Returns the identity of the agent	adding	the  signature	handle
	      specified	  by  sig,  previously	returned  by  a	 call  to  od-
	      kim.get_sighandle().  This is taken from	the  signature's  "i="
	      tag.   This  may be a default value and not one that was explic-
	      itly part	of the signature.  If the identity could not be	deter-
	      mined, the Lua constant "nil" is returned.

       odkim.sig_ignore(sig)
	      Instructs	 the verification code to ignore completely the	signa-
	      ture specified by	sig, previously	returned  by  a	 call  to  od-
	      kim.get_sighandle().   Any  pending  verification	of the message
	      will act as if that signature was	not present  on	 the  message.
	      Always returns the Lua constant "nil".

STATISTICS SCRIPT FUNCTIONS
       The  statistics	script	has  the  following functions available	to it,
       whose descriptions can be found above: odkim.export, odkim.get_envfrom,
       odkim.get_header,  odkim.get_mtasymbol,	odkim.get_rcpt,	odkim.get_rcp-
       tarray,	odkim.get_sigarray,  odkim.get_sigcount,  odkim.get_sighandle,
       odkim.log,  odkim.parse_field,  odkim.rcpt_count,  odkim.sig_getdomain,
       odkim.sig_getidentity, and odkim.spam.

       The following functions are also	available, defined in  the  next  sec-
       tion:   odkim.rbl_check,	  odkim.rcpt_count,   odkim.sig_bhresult,  od-
       kim.sig_bodylength, odkim.sig_canonlength, and odkim.sig_result.

       The following additional	function is provided for this script:

       odkim.stats(ctx,	name, value)
	      Records the additional statistic called name with	its associated
	      value for	the message represented	by ctx.

FINAL SCRIPT FUNCTIONS
       The final script	has the	following functions available to it, whose de-
       scriptions can be found above:  odkim.get_clienthost,  odkim.get_clien-
       tip,  odkim.get_envfrom,	 odkim.get_fromdomain,	odkim.get_header,  od-
       kim.get_mtasymbol,     odkim.get_rcpt,	  odkim.get_rcptarray,	   od-
       kim.get_sigarray,  odkim.get_sigcount,  odkim.get_sighandle, odkim.log,
       odkim.parse_field, odkim.rcpt_count, odkim.set_result, odkim.sig_getdo-
       main, odkim.sig_getidentity, odkim.spam,	and odkim.xtags.

       The following additional	functions are provided for this	script:

       odkim.add_header(ctx, name, value)
	      Adds  a new header field called name with	the specified value to
	      the message represented by ctx.  Returns 1 on  success,  or  the
	      Lua constant "nil" on failure.

       odkim.add_rcpt(ctx, addr)
	      Adds addr	as an envelope recipient to the	message	represented by
	      ctx.  Returns 1 on success, or the Lua constant "nil"  on	 fail-
	      ure.

       odkim.del_header(ctx, name, n)
	      Deletes  the  nth	instance (starting from	0) of the header field
	      called name from the message represented by ctx.	Returns	 1  on
	      success, or the Lua constant "nil" on failure.

       odkim.del_rcpt(ctx, addr)
	      Deletes addr from	the list of envelope recipients	on the message
	      represented by ctx, and adds a new X-Original-Recipient:	header
	      field  containing	the deleted address.  Returns 1	on success, or
	      the Lua constant "nil" on	failure.

       odkim.quarantine(ctx, reason)
	      Asks the MTA to quarantine the message represented by ctx	 using
	      reason  as  a text string	indicating the reason for the request.
	      Returns 1	on success or the Lua constant "nil" on	failure.

       odkim.rbl_check(ctx, query, qroot[, timeout])
	      Makes an RBL query.  The root of the RBL is  assumed  to	be  at
	      qroot  and  the subject of the query is query, so	the query per-
	      formed will be query.qroot .  The	context	handle ctx  must  also
	      be  provided as it contains a handle to the established DNS ser-
	      vice.  The optional timeout parameter is the timeout to use,  in
	      seconds.	 Returns  "nil"	 on  error, no values if the requested
	      record was not present in	the RBL, or the	four octets of the RBL
	      entry  if	 it was.  The octets are returned in big-endian	order.
	      (Experimental feature not	enabled	for this installation.)

       odkim.set_reply(ctx, rcode, xcode, message)
	      Instructs	the MTA	to return the  specified  SMTP	reply  to  the
	      client  sending the message represented by ctx.  rcode must be a
	      three-digit SMTP reply code starting with	4 or 5 (for  temporary
	      or  permanent  failures,	respectively); xcode must be the empty
	      string or	a valid	extended reply	code  (see  RFC2034)  matching
	      rcode; and message must be the text portion of the SMTP reply to
	      be sent.	Returns	1 on success or	 the  Lua  constant  "nil"  on
	      failure.

       odkim.sig_bhresult(sig)
	      Returns  the  result code	corresponding to the body hash evalua-
	      tion of the signature handled specified by sig,  previously  re-
	      turned by	a call to odkim.get_sighandle().  Valid	values are the
	      DKIM_SIGBH_* constants defined in	the  libopendkim  header  file
	      dkim.h.

       odkim.sig_bodylength(sig)
	      Returns  the  total  length of the message signed	by sig,	previ-
	      ously returned by	a call to odkim.get_sighandle(),  or  the  Lua
	      constant "nil" if	this value could not be	determined.

       odkim.sig_canonlength(sig)
	      Returns  the  canonicalized length of the	message	signed by sig,
	      previously returned by a call to odkim.get_sighandle(),  or  the
	      Lua  constant "nil" if this value	could not be determined.  Note
	      that  this  may  be  less	 than  the  value  returned   by   od-
	      kim.get_bodylength()  if	the signature only covered part	of the
	      message.

       odkim.sig_result(sig)
	      Returns the result code corresponding to the  signature  handled
	      specified	  by  sig,  previously	returned  by  a	 call  to  od-
	      kim.get_sighandle().   Valid  values  are	 the  constants	  with
	      DKIM_SIGERROR_  prefixes	as  defined  in	the libopendkim	header
	      file dkim.h.

VERSION
       This man	page covers version 2.10.3 of OpenDKIM.

COPYRIGHT
       Copyright (c) 2009-2014,	The Trusted Domain Project.   All  rights  re-
       served.

SEE ALSO
       opendkim(8), opendkim.conf(5)

       Lua -- http://www.lua.org

			  The Trusted Domain Project	       opendkim-lua(3)

NAME | DESCRIPTION | GLOBAL VARIABLES | SETUP SCRIPT FUNCTIONS | SCREEN SCRIPT FUNCTIONS | STATISTICS SCRIPT FUNCTIONS | FINAL SCRIPT FUNCTIONS | VERSION | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=opendkim-lua&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help