NAME
Mail::Milter::Authentication::Handler - Handler superclass
VERSION
version 3.20240827
DESCRIPTION
Handle the milter requests and pass off to individual handlers
CONSTRUCTOR
new( $thischild )
my $object = Mail::Milter::Authentication::Handler->new( $thischild );
Takes the argument of the current Mail::Milter::Authentication object and creates a new handler object.
METHODS
get_version()
Return the version of this handler
status( $status )
Set the status of the current child as visible by ps.
config()
Return the configuration hashref.
handler_config( $type )
Return the configuration for the current handler.
handler_type()
Return the current handler type.
set_return( $code )
Set the return code to be passed back to the MTA.
get_return()
Get the current return code.
get_reject_mail()
Get the reject mail reason (or undef)
clear_reject_mail()
Clear the reject mail reason
get_defer_mail()
Get the defer mail reason (or undef)
clear_defer_mail()
Clear the defer mail reason
get_quarantine_mail()
Get the quarantine mail reason (or undef)
clear_quarantine_mail()
Clear the quarantine mail reason
get_top_handler()
Return the current top Handler object.
is_handler_loaded( $name )
Check if the named handler is loaded.
get_handler( $name )
Return the named handler object.
get_callbacks( $callback )
Return the list of handlers which have callbacks for the given event in the order they must be called in.
set_object_maker( $name, $ref )
Register an object maker for type 'name'
get_object( $name )
Return the named object from the object store.
Object 'resolver' will be created if it does not already exist.
Object 'spf_server' will be created by the SPF handler if it does not already exist.
Handlers may register makers for other types as required.
set_object( $name, $object, $destroy )
Store the given object in the object store with the given name.
If $destroy then the object will be destroyed when the connection to the child closes
destroy_object( $name )
Remove the reference to the named object from the object store.
destroy_all_objects()
Remove the references to all objects currently stored in the object store.
Certain objects (resolver and spf_server) are not destroyed for performance reasons.
exit_on_close( $error )
Exit this child once it has completed, do not process further requests with this child.
reject_mail( $reason )
Reject mail with the given reason
quarantine_mail( $reason )
Request quarantine mail with the given reason
defer_mail( $reason )
Defer mail with the given reason
clear_all_symbols()
Clear the symbol store.
clear_symbols()
Clear the symbol store but do not remove the Connect symbols.
set_symbol( $code, $key, $value )
Store the key value pair in the symbol store with the given code (event stage).
get_symbol( $searchkey )
Return a value from the symbol store, searches all codes for the given key.
tempfail_on_error()
Returns a TEMP FAIL to the calling MTA if the configuration is set to do so.
Config can be set for all, authenticated, local, and trusted connections.
can_sort_header( $header )
Returns 1 is this handler has a header_sort method capable or sorting entries for $header Returns 0 otherwise
header_sort()
Sorting function for sorting the Authentication-Results headers Calls out to __HANDLER__->header_sort() to sort headers of a particular type if available, otherwise sorts alphabetically.
add_headers()
Send the header changes to the MTA.
add_headers_of_type( $type )
Find and add all Authentication-Results style headers of given type
prepend_header( $field, $value )
Add a trace header to the email.
add_auth_header( $value )
Add a section to the authentication header for this email.
add_c_auth_header( $value )
Add a section to the authentication header for this email, and to any subsequent emails for this connection.
append_header( $field, $value )
Add a normal header to the email.
METRICS METHODS
get_json( $file )
Return json data from external file
metric_register( $id, $help )
Register a metric type
metric_count( $id, $labels, $count )
Increment a metrics counter by $count (defaults to 1 if undef)
metric_set( $id, $labels, $count )
Set a metrics counter to $count
metric_send()
Send metrics to the parent
register_metrics()
Return details of the metrics this module exports.
RBL METHODS
rbl_check_ip( $ip, $list )
Check the given IP address against an rbl list.
Returns true is listed.
rbl_check_domain( $domain, $list )
Check the given domain against an rbl list.
Returns true is listed.
TIMEOUT METHODS
get_microseconds()
Return the current time in microseconds
get_microseconds_since( $time )
Return the number of microseconds since the given time (in microseconds)
is_exception_type( $exception )
Given a Mail::Milter::Authentication::Exception object, this return the exception object type. Otherwise returns undef.
handle_exception( $exception )
Handle exceptions thrown, this method currently handles the timeout type, by re-throwing the exception.
Should be called in Handlers when handling local exceptions, such that the higher level timeout exceptions are properly handled.
get_time_remaining()
Return the time remaining (in microseconds) for the current Handler section level callback timeout.
set_alarm( $microseconds )
Set a timeout alarm for $microseconds, and set the time remaining in the top level handler object.
set_handler_alarm( $microseconds )
Set an alarm for $microseconds, or the current time remaining for the section callback, whichever is the lower. This should be used in Handler timeouts to ensure that a local timeout never goes for longer than the current handler section, or protocol section level timeout.
reset_alarm()
Reset the alarm to the current time remaining in the section or protocol level timeouts.
This should be called in Handlers after local timeouts have completed, to reset the higher level timeout alarm value.
clear_overall_timeout()
Clear the current Handler level timeout, should be called from the Protocol layer, never from the Handler layer.
set_overall_timeout( $microseconds )
Set the time in microseconds after which the Handler layer should timeout, called from the Protocol later, never from the Handler layer.
get_type_timeout( $type )
For a given timeout type, return the configured timeout value, or the current handler level timeout, whichever is lower.
check_timeout()
Manually check the current timeout, and throw if it has passed.
CALLBACK METHODS
top_dequeue_callback()
Top level handler for dequeue.
top_setup_callback()
Top level handler for handler setup.
remap_connect_callback( $hostname, $ip )
Top level handler for the connect event for remapping only.
top_metrics_callback()
Top level handler for the metrics event.
top_connect_callback( $hostname, $ip )
Top level handler for the connect event.
remap_helo_callback( $helo_host )
Top level handler for the HELO event for remapping only.
top_helo_callback( $helo_host )
Top level handler for the HELO event.
top_envfrom_callback( $env_from )
Top level handler for the MAIL FROM event.
top_envrcpt_callback( $env_to )
Top level handler for the RCPT TO event.
top_header_callback( $header, $value, $original )
Top level handler for the BODY header event.
top_eoh_callback()
Top level handler for the BODY end of headers event.
top_body_callback( $body_chunk )
Top level handler for the BODY body chunk event.
top_eom_callback()
Top level handler for the BODY end of message event.
apply_policy()
Apply policy to the message, currently a nop.
top_abort_callback()
Top level handler for the abort event.
top_close_callback()
Top level handler for the close event.
top_addheader_callback()
Top level handler for the add header event.
Called after the Authentication-Results header has been added, but before any other headers.
HELPER METHODS
add_dequeue($key,$data)
Write serialized $data into the queue for later dequeueing
get_dequeue_list($key)
Return an ArrayRef of all queued items for $key
This may be a list of filenames, or may be a list of some other ID, it should not be assumed that this value is useful outside of the dequeue methods.
Used in get_dequeue_object and delete_dequeue_object
get_dequeue($id)
Return a previously queued item
delete_dequeue($id)
Delete a previously queued item
error_dequeue($id)
Mark a previously queued item as errored
add_header_to_sanitize_list($header,$silent)
Add the given to the list of headers removed by the Sanitize handler if loaded
is_local_ip_address()
Is the current connection from a local ip address?
Requires the LocalIP Handler to be loaded.
is_trusted_ip_address()
Is the current connection from a trusted ip address?
Requires the TrustedIP Handler to be loaded.
is_encrypted()
Is the current connection encrypted?
Requires the TLS Handler to be loaded.
In SMTP mode this is only available AFTER the eoh call.
Returns undef if the state is not yet known.
is_authenticated()
Is the current connection authenticated?
Requires the Auth Handler to be loaded.
ip_address()
Return the ip address of the current connection.
format_ctext( $text )
Format text as ctext for use in headers.
Deprecated.
format_ctext_no_space( $text )
Format text as ctext with no spaces for use in headers.
Deprecated.
format_header_comment( $comment )
Format text as a comment for use in headers.
Deprecated.
format_header_entry( $key, $value )
Format text as a key value pair for use in authentication header.
Deprecated.
get_domain_from( $address )
Extract a single domain from an email address.
get_domains_from( $address )
Extract the domains from an email address as an arrayref.
get_address_from( $text )
Extract a single email address from a string.
get_addresses_from( $text )
Extract all email address from a string as an arrayref.
get_my_hostname()
Return the effective hostname of the MTA.
get_my_authserv_id()
Return the effective authserv-id. Defaults to hostname if not explicitly set.
LOGGING METHODS
dbgout( $key, $value, $priority )
Send output to debug and/or Mail Log.
priority is a standard Syslog priority.
log_error( $error )
Log an error.
dbgoutwrite()
Write out logs to disc.
Logs are not written immediately, they are written at the end of a connection so we can include a queue id. This is not available at the start of the process.
LOW LEVEL METHODS
smfis_continue()
Return Continue code.
smfis_tempfail()
Return TempFail code.
smfis_reject()
Return Reject code.
smfis_discard()
Return Discard code.
smfis_accept()
Return Accept code.
write_packet( $type, $data )
Write a packet to the MTA (calls Protocol object)
add_header( $key, $value )
Write an Add Header packet to the MTA (calls Protocol object)
insert_header( $index, $key, $value )
Write an Insert Header packet to the MTA (calls Protocol object)
change_header( $key, $index, $value )
Write a Change Header packet to the MTA (calls Protocol object)
WRITING HANDLERS
tbc
AUTHOR
Marc Bradshaw <marc@marcbradshaw.net>
COPYRIGHT AND LICENSE
This software is copyright (c) 2020 by Marc Bradshaw.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.