Mail::Milter::Authentication::Client(3)

NAME
Mail::Milter::Authentication::Client - A client to the Perl Mail Authentication Milter

DESCRIPTION
Client to the Authentication Milter

SYNOPSIS
Connect to the Authentication Milter and pass it email, returning the result.

CONSTRUCTOR

new($args)
    Instantiate a new Client object

        my $client = Mail::Milter::Authentication::Client->new({
            'mailer_name'   => 'test.mta.yoga.fastmail.com',
            'connect_ip'    => '66.111.4.148',
            'connect_name'  => 'test.fastmail.com',
            'connect_port'  => '54321',
            'connect_type'  => 'tcp4',
            'helo_host'     => 'test.helo.fastmail.com',
            'mail_from'     => 'test@marc.fastmail.com',
            'rcpt_to'       => 'marc@yoga',
            'mail_data'     => $email_content,
            'mail_file'     => '/path/to/email.txt',
        });

  Arguments

mailer_name
    The name (fqdn) of the MTA

connect_ip
    The IP address of the host connecting to the mailer.

connect_name
    The name of the host connecting to the mailer.

connect_port
    The port of the connection to the mailer.

connect_type
    The type of connection to the mailer (eg tcp4).

helo_host
    The string passed in the HELO stage of the SMTP transaction.

mail_from
    The string passed in the MAIL FROM stage of the SMTP transaction.

rcpt_to
    The string passed in the RCPT TO stage of the SMTP transaction.

mail_data
    The EMail body as a string.

mail_file
    The EMail body can also be passed as a filename.

PUBLIC METHODS

process()
    Send the email to the milter and process the result.

result()
    Return the result.

PRIVATE METHODS

r()
insert_header()
replace_header()
add_header()
load_mail()

AUTHORS
Marc Bradshaw <marc@marcbradshaw.net>

COPYRIGHT
Copyright 2015

This library is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

Net::Milter
This module includes a modified copy of Net::Milter which is imported into the Mail::Milter::Authentication::Net::Milter namespace.

The included module has been modified to support all of the features required by Authentication Milter.

If these required features are ever merged back into Net::Milter then we may just use it instead, however at this point the modified version does the job.

The full documentation of Net::Milter will follow this paragraph.

NAME
Net::Milter - Masquerade as the MTA to communicate with email filters through a milter interface.

SYNOPSIS
    use Net::Milter;
    my $milter = new Net::Milter;
    $milter->open('127.0.0.1',5513,'tcp');

    my ($milter_version,$returned_actions_ref,$returned_protocol_ref) =
    $milter->protocol_negotiation();

    my (@results) = $milter->send_header('From','martin@localhost');
    foreach (@results) {
      if ($$_{action} eq 'reject')  {exit;}
    }

Also see example in scripts directory.

DESCRIPTION
Perl module to provide a pure Perl implementation of the MTA part the milter interface. The goal of this module is to allow other email systems to easily integrate with the various email filters that accept content via milter.

This implementation of milter is developed from the description provided by Todd Vierling, cvs.sourceforge.net/viewcvs.py/pmilter/pmilter/doc/milter-protocol.txt?rev=1.2 and from examining the tcp output from Sendmail.

  Attributes

action_types
    Reference to an array of the set of actions defined within Sendmail's milter code.

content_types
    Reference to an array of the set of content types which may be witheld.

  Methods

new Constructor, creates a new blank Net::Milter object.

open
    Open a socket to a milter filter. Takes three arguments, the last argument, can be 'tcp' or 'unix' depending if the connection is to be made to a TCP socket or through a UNIX file system socket. For TCP sockets, the first two argument are the IP address and the port number; for UNIX sockets the first argument is the file path, the second the timeout value. Accepted synonyms for tcp and unix are inet and local respecively.

    e.g.

        $milter->open('127.0.0.1',5513,'tcp');

    to open a connection to port 5513 on address 127.0.0.1, or

        $milter->open('/tmp/file.sck',10,'unix');

    to open a connection to /tmp/file.sck with a timeout of 10 seconds.

    The method creates the attribute, 'socket' containing an IO::Handle object.

protocol_negotiation
    Talk to the milter filter, describing the list of actions it may perform, and any email content that wont be sent. Accepts as argument the hash of allowable actions and withheld content. The hash keys are : Allowable actions by the filter :

    SMFIF_ADDHDRS - Add message headers.
    SMFIF_CHGBODY - Alter the message body.
    SMFIF_ADDRCPT - Add recipients to the message.
    SMFIF_DELRCPT - Delete recipients from the message.
    SMFIF_CHGHDRS - Change or delete message headers.

    The default is to allow all actions, setting the value to be '0' of any of these keys in the argument hash informs the filter not perform the action.

    e.g.

        $milter->protocol_negotiation(
            SMFIF_ADDHDRS => 0,
            SMFIF_CHGBODY => 1
            );

    informs the filter it is able to change the contents of the message body, but it may not add message headers.

    Withheld content :

    SMFIP_NOCONNECT - Do not expect the connection details.
    SMFIP_NOHELO - Do not expect the HELO string.
    SMFIP_NOMAIL - Do not expect the MAIL FROM string.
    SMFIP_NORCPT - Do not expect the RCPT TO string.
    SMFIP_NOBODY - Do not expect the email body.
    SMFIP_NOHDRS - Do not expect any email headers.
    SMFIP_NOEOH - Do not expect an end of headers signal.

    The default is to inform the filter to expect everything, setting the value of the key to '1' informs the filter to not expect the content.

    e.g.

        $milter->protocol_negotiation(
            SMFIF_ADDHDRS => 0,
            SMFIF_CHGBODY => 1,
            SMFIP_NOEHO => 1,
            SMFIP_NOCONNECT => 1
        );

    informs the filter it is able to change the contents of the message body, but it may not add message headers, it will not receive an end of headers signal, nor will it receive the conection details.

    The method returns three parameters, the protocol version, an array reference containing all the names of the actions the filter understands it is able to perform, and an array reference containing the names of the content it understands it wont be sent.

send_abort
    Send an abort signal to the mail filter. Accepts nothing, returns nothing.

send_body
    Send the body of the email to the mail filter. NOTE the filter will only accept upto 65535 bytes of body at a time. Feed the body to the filter piece by piece by repeat calls to send_body with each body chunk until all the body is sent. Accepts the message body, returns reference to an array of return codes (see RETURN CODE section).

send_end_body
    Send an end of body signal, i.e. no more body information will follow. Returns a reference to an array of return codes (see RETURN CODE section).

send_connect
    Send the SMTP connect information to the mail filter. Accepts the hostname, the family ('unix' for file sockets, 'tcp4' for tcp connections (v4), 'tcp6' for version 6 tcp connections), the sending connection port, the IP address of the sender. Returns a reference to an array of return codes (see RETURN CODE section).

    e.g.

        $milter->send_connect(
                              'host.domain',
                              'tcp4',
                              '12345',
                              '127.0.0.1'
                              );

    The machine host.domain with IP address 127.0.0.1 connected to us from port 12345 using TCP version 4.

send_helo
    Send the HELO (or EHLO) string provided by the connecting computer. Accepts the HELO string as an argument. Returns a reference to an array of return codes (see RETURN CODE section).

send_header
    Send a single header name and contents to the filter, accepts two arguments, the header name and the header contents. Returns a reference to an array of return codes (see RETURN CODE section).

send_mail_from
    Send the MAIL FROM string to the filter, accepts the MAIL FROM data as an argument. Returns a reference to an array of return codes (see RETURN CODE section).

send_end_headers
    Send an end of headers signal, i.e. no more header information will follow. Returns a reference to an array of return codes (see RETURN CODE section).

send_rcpt_to
    Send the RCPT TO string to the filter, accepts an array of RCPT TO recipients as argument. Returns a reference to an array of return codes (see RETURN CODE section).

send_quit
    Quit the milter communication, accepts nothing, returns nothing.

send_macros
    Send Sendmail macro information to the filter. The method accepts a hash of the Sendmail macro names, returns a reference to an array of return codes (see RETURN CODE section).

    The potential macro names (hash keys) are :

    _              - email address of the Sendmail user.
    j              - canonical hostname of the recipeint machine.
    {daemon_name}  - name of the daemon from DaemonPortOptions.
    {if_name}      - hostname of the incoming connection.
    {if_addr}      - IP address of the incoming connection.
    {tls_version}  - TLS/SSL version used for connection.
    {cipher}       - cipher suite used for the connection.
    {cipher_bits}  - keylength of the encryption algorith.
    {cert_subject} - distinguished name of the presented certificate.
    {cert_issuer}  - name of the certificate authority.
    i              - queue ID.
    {auth_type}    - SMTP authentication mechanism.
    {auth_authen}  - client's authenticated username.
    {auth_ssf}     - keylength of encryption algorithm.
    {auth_author}  - authorization identity.
    {mail_mailer}  - mailer from SMTP MAIL command.
    {mail_host}    - host from SMTP MAIL command.
    {mail_addr}    - address from SMTP MAIL command.
    {rcpt_mailer}  - mailer from SMTP RCPT command.
    {rcpt_host}    - host from SMTP RCPT command.
    {rcpt_addr}    - address from SMTP RCPT command.

    Yes I know most of this is redundant, since other methods repeat this information, but this is what the spec says.

    e.g.
        $milter->send_macros(
            mail_addr => '127.0.0.1',
            mail_host => 'localhost',
            rcpt_addr => '127.0.0.1',
            rcpt_addr => 'postmaster@localhost.localdomain'
        );

    For further explanation of macros see :

    http://people.freenet.de/slgig/op_en/macros.html and http://www.sendmail.com/idemo/prod_guide/switch/switchdemo/helplets/en/Macros.html

RETURN CODES
Many methods return an array of hash references. Each hash describes one response from the filter, a filter may return more than one response to any sent data, such as 'add a header','modify body', 'continue'. The hash keys are :

command - the response from the filter
explanation - verbose explanation of the required action
action - action to perform, may be add, delete, accept, replace, continue or reject
header - the name of header the action refers to (may be equal to 'body' to refer to the message body)
value - the value relating to the action

TIPS
Call the various methods in the order that they would be called if accepting a SMTP stream, ie send_connect(), send_helo(), send_mail_from(), send_rcpt_to(), send_header(), send_end_headers(), send_body(). Some milter filters expect this and refuse to return values when expected. Equally continuing to send data when a filter has rejected or accepted a message may confuse it, and refuse to return values for subsequent data, so always check the codes returned.

In some circumstantes 'read' has not worked, now replaced by 'sysread' which is reported to fix the problem. If this doesn't work, change 'sysread' to 'read' and email me please.

Some filters appear to expect a bitwise negation of the protocol field. This is now disabled as default. If you wish to enable this, please set PROTOCOL_NEGATION => 1

SEE ALSO
This module is the Yang to Ying's Sendmail::Milter, which can act as the other end of the communication.

NAMING
I choose not to put this module in the Sendmail namespace, as it has nothing to do with Sendmail itself, neither is it anything to do with SMTP, its a net protocol, hence the Net namespace.

AUTHOR
Martin Lee, MessageLabs Ltd. (mlee@messagelabs.com)

Copyright (c) 2003 Star Technology Group Ltd / 2004 MessageLabs Ltd.