.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Mail::DKIM::Canonicalization::Base 3"
.TH Mail::DKIM::Canonicalization::Base 3 "2012-11-28" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mail::DKIM::Canonicalization::Base \- base class for canonicalization methods
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&  # 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\e015\e012");
\&  $method\->finish_header(Headers => \e@all_headers);
\&
\&  # add body
\&  $method\->add_body("This is the body.\e015\e012");
\&  $method\->add_body("Another two lines\e015\e012of the body.\e015\e012");
\&  $method\->finish_body;
\&
\&  # this adds the signature to the end
\&  $method\->finish_message;
.Ve
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
Use the \fInew()\fR method of the desired canonicalization implementation class
to construct a canonicalization object. E.g.
.PP
.Vb 3
\&  my $method = new Mail::DKIM::Canonicalization::relaxed(
\&                    output_fh => *STDOUT,
\&                    Signature => $dkim_signature);
.Ve
.PP
The constructors accept these arguments:
.IP "Signature" 4
.IX Item "Signature"
(Required) Provide the \s-1DKIM\s0 signature being constructed (if the message is
being signed), or the \s-1DKIM\s0 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).
.IP "output" 4
.IX Item "output"
If specified, the canonicalized message will be passed to this object with
the \s-1PRINT\s0 method.
.IP "output_digest" 4
.IX Item "output_digest"
If specified, the canonicalized message will be added to this digest.
(Uses the \fIadd()\fR method.)
.IP "output_fh" 4
.IX Item "output_fh"
If specified, the canonicalized message will be written to this file
handle.
.PP
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 \fIresult()\fR method.
.SH "METHODS"
.IX Header "METHODS"
.SS "\fIadd_body()\fP \- feeds part of the body into the canonicalization"
.IX Subsection "add_body() - feeds part of the body into the canonicalization"
.Vb 2
\&  $method\->add_body("This is the body.\e015\e012");
\&  $method\->add_body("Another two lines\e015\e012of the body.\e015\e012");
.Ve
.PP
The body should be fed one or more \*(L"lines\*(R" at a time.
I.e. do not feed part of a line.
.SS "\fIfinish_header()\fP \- called when the header has been completely parsed"
.IX Subsection "finish_header() - called when the header has been completely parsed"
.Vb 1
\&  $method\->finish_header(Headers => \e@all_headers);
.Ve
.PP
Formerly the canonicalization object would only get the header data
through successive invocations of \fIadd_header()\fR. 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.
.PP
The headers array is an array of one element per header field, with
the headers not processed/canonicalized in any way.
.SS "\fIresult()\fP"
.IX Subsection "result()"
.Vb 1
\&  my $result = $method\->result;
.Ve
.PP
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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mail::DKIM
.SH "AUTHOR"
.IX Header "AUTHOR"
Jason Long, <jlong@messiah.edu>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2006\-2007 by Messiah College
.PP
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.