NAME
    FML::Credential - functions to authenticate the mail sender.

SYNOPSIS
       use FML::Credential;

       # get the mail sender
       my $cred   = new FML::Credential;
       my $sender = $cred->sender;

DESCRIPTION
    This class provides a collection of utilitity functions to authenticate
    the sender of the message which kicks off this process.

  User credential information
    %Credential information is unique in one fml process. So this hash is
    accessible in public.

METHODS
  new()
    constructor. It bind $self to the module internal "\%Credential" hash
    and return the hash reference as an object.

    ASSMPUTION:

    We assume one process has one credential since the mail sender must be
    unique. It must be one credential even if context switching of
    processing mailing list occurs.

ACCESS METHODS
  set_user_part_case_sensitive()
    compare user part case sensitively by default.

  set_user_part_case_insensitive()
    compare user part case insensitively.

  is_same_address($addr1, $addr2, $max_level)
    return 1 (same) or 0 (different). It returns 1 if $addr1 and $addr2
    looks same within some ambiguity. The ambiguity is defined by the
    following rules:

    1. "user" part must be same case-sensitively.

    2. "domain" part is same case-insensitively by definition of "DNS".

    3. "domain" part is same case-insensitively from the top "gTLD" layer to
    $level-th sub domain level.

                .jp
               d.jp
             c.d.jp
               ......

    By default we compare the last (top) 3 level. For example, consider
    these two addresses:

                rudo@nuinui.net
                rudo@sapporo.nuinui.net

    These addresses differ. But the following addresses

                rudo@fml.nuinui.net
                rudo@sapporo.fml.nuinui.net

    are same since the last 3 top level domains are same.

  is_same_domain($xdomain, $ydomain)
    check if $xdomain and $ydomain are same or not case-insensitively.

  is_ml_domain($address)
    check if the domain part of $address matches exact $ml_domain (our
    default domain) or not. return 1 if matched or 0 not.

    XXX o.k. to support only exact match ?

  is_member($address)
    return 1 if the sender <$address> is an ML member. return 0 if not.

  is_privileged_member($address)
    return 1 if the sender <$address> is an ML administrator. return 0 if
    not.

  is_recipient($address)
    return 1 if the sender <$address> is an ML recipient. return 0 if not.

  is_moderator_member($address)
    return 1 if the sender <$address> is an ML moderator. return 0 if not.

  is_spammer($address)
    return 1 if the sender <$address> is a spammer. return 0 if not.

  matched_address()
    return the last matched address.

  match_system_special_accounts($addr)
    check is the specified "addr" matches a system account or not. The
    system accounts are given as

         $curproc->config()->{ system_special_accounts }.

  sender()
    same as get_sender().

  set_sender()
    overwrite sender info in credential object.

  get_sender()
    return the mail address of the mail sender who kicks off this fml
    process.

  set_compare_level( $level )
    set "level", how many sub-domains from top level we compare. This
    parameter is in "in_same_address()" address comparison.

  get_compare_level()
    get level in "in_same_address()" address comparison. return the number
    of "level".

  get(key)
       XXX NUKE THIS ?

  set(key, value)
       XXX NUKE THIS ?

ERROR METHODS
  error_set($message)
    save $message as an error message.

  error()
    return $message which is saved by "error_set($msg)".

  error_clear()
    clear the error message buffer.

CODING STYLE
    See "http://www.fml.org/software/FNF/" on fml coding style guide.

AUTHOR
    Ken'ichi Fukamachi

COPYRIGHT
    Copyright (C) 2001,2002,2003,2004,2005,2006,2008,2011 Ken'ichi Fukamachi

    All rights reserved. This program is free software; you can redistribute
    it and/or modify it under the same terms as Perl itself.

HISTORY
    FML::Credential first appeared in fml8 mailing list driver package. See
    "http://www.fml.org/" for more details.