NAME

       Mail::DKIM::Canonicalization::Base - base class for canonicalization methods

VERSION

       version 1.20230212

SYNOPSIS

         # canonicalization results get output to STDOUT
         my $method = new Mail::DKIM::Canonicalization::relaxed(
                           output_fh => *STDOUT,
                           Signature => $dkim_signature);

         # add headers
         $method->add_header("Subject: this is the subject\015\012");
         $method->finish_header(Headers => \@all_headers);

         # add body
         $method->add_body("This is the body.\015\012");
         $method->add_body("Another two lines\015\012of the body.\015\012");
         $method->finish_body;

         # this adds the signature to the end
         $method->finish_message;

CONSTRUCTOR

       Use the new() method of the desired canonicalization implementation class to construct a canonicalization
       object. E.g.

         my $method = new Mail::DKIM::Canonicalization::relaxed(
                           output_fh => *STDOUT,
                           Signature => $dkim_signature);

       The constructors accept these arguments:

       Signature
           (Required) Provide the DKIM signature being constructed (if the message is being signed), or the DKIM
           signature  being  verified  (if  the  message  is being verified). The canonicalization method either
           writes parameters to the signature, or reads parameters from the signature (e.g. the h= tag).

       output
           If specified, the canonicalized message will be passed to this object with the PRINT method.

       output_digest
           If specified, the canonicalized message will be added to this digest.  (Uses the add() method.)

       output_fh
           If specified, the canonicalized message will be written to this file handle.

       If none of the output parameters are specified, then the canonicalized message is appended to an internal
       buffer. The contents of this buffer can be accessed using the result() method.

METHODS

   add_body() - feeds part of the body into the canonicalization
         $method->add_body("This is the body.\015\012");
         $method->add_body("Another two lines\015\012of the body.\015\012");

       The body should be fed one or more "lines" at a time.  I.e. do not feed part of a line.

   finish_header() - called when the header has been completely parsed
         $method->finish_header(Headers => \@all_headers);

       Formerly the canonicalization object would only get the header data  through  successive  invocations  of
       add_header().  However, that required the canonicalization object to store a copy of the entire header so
       that it could choose the order in which headers were fed to the digest object. This is inefficient use of
       memory,  since  a  message  with  many  signatures  may  use  many  canonicalization  objects  and   each
       canonicalization object has its own copy of the header.

       The   headers   array   is   an   array   of   one  element  per  header  field,  with  the  headers  not
       processed/canonicalized in any way.

   result()
         my $result = $method->result;

       If you did not specify an object or handle to send the output to, the result of the  canonicalization  is
       stored in the canonicalization method itself, and can be accessed using this method.

SEE ALSO

       Mail::DKIM

AUTHORS

       •   Jason Long <jason@long.name>

       •   Marc Bradshaw <marc@marcbradshaw.net>

       •   Bron Gondwana <brong@fastmailteam.com> (ARC)

THANKS

       Work  on  ensuring  that  this  module  passes  the  ARC  test suite was generously sponsored by Valimail
       (https://www.valimail.com/)

COPYRIGHT AND LICENSE

       •   Copyright (C) 2013 by Messiah College

       •   Copyright (C) 2010 by Jason Long

       •   Copyright (C) 2017 by Standcore LLC

       •   Copyright (C) 2020 by FastMail Pty Ltd

       This library is free software; you can redistribute it and/or modify it under  the  same  terms  as  Perl
       itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.

perl v5.38.2                                       2024-02-27             Mail::DKIM::Can...alization::Base(3pm)