.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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 >0, 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::Algorithm::Base 3pm"
.TH Mail::DKIM::Algorithm::Base 3pm "2020-09-11" "perl v5.30.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::Algorithm::Base \- base class for DKIM "algorithms"
.SH "VERSION"
.IX Header "VERSION"
version 1.20200907
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  my $algorithm = new Mail::DKIM::Algorithm::rsa_sha1(
\&                      Signature => $dkim_signature
\&                  );
\&
\&  # add headers
\&  $algorithm\->add_header("Subject: this is the subject\e015\e012");
\&  $algorithm\->finish_header;
\&
\&  # add body
\&  $algorithm\->add_body("This is the body.\e015\e012");
\&  $algorithm\->add_body("Another line of the body.\e015\e012");
\&  $algorithm\->finish_body;
\&
\&  # now sign or verify...
\&  # TODO...
.Ve
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
You should not create an object of this class directly. Instead, use one
of the \s-1DKIM\s0 algorithm implementation classes, such as rsa_sha1:
.PP
.Vb 3
\&  my $algorithm = new Mail::DKIM::Algorithm::rsa_sha1(
\&                      Signature => $dkim_signature
\&                  );
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "\fBadd_body()\fP \- feeds part of the body into the algorithm/canonicalization"
.IX Subsection "add_body() - feeds part of the body into the algorithm/canonicalization"
.Vb 2
\&  $algorithm\->add_body("This is the body.\e015\e012");
\&  $algorithm\->add_body("Another line of the body.\e015\e012");
.Ve
.PP
The body should be fed one \*(L"line\*(R" at a time.
.SS "\fBadd_header()\fP \- feeds a header field into the algorithm/canonicalization"
.IX Subsection "add_header() - feeds a header field into the algorithm/canonicalization"
.Vb 1
\&  $algorithm\->add_header("Subject: this is the subject\e015\e012");
.Ve
.PP
The header must start with the header field name and continue through any
folded lines (including the embedded <\s-1CRLF\s0> sequences). It terminates with
the <\s-1CRLF\s0> at the end of the header field.
.SS "\fBfinish_body()\fP \- signals the end of the message body"
.IX Subsection "finish_body() - signals the end of the message body"
.Vb 1
\&  $algorithm\->finish_body
.Ve
.PP
Call this method when all lines from the body have been submitted.
After calling this method, use \fBsign()\fR or \fBverify()\fR to get the results
from the algorithm.
.SS "\fBfinish_header()\fP \- signals the end of the header field block"
.IX Subsection "finish_header() - signals the end of the header field block"
.Vb 1
\&  $algorithm\->finish_header;
.Ve
.PP
Call this method when all the headers have been submitted.
.SS "\fBsign()\fP \- generates a signature using a private key"
.IX Subsection "sign() - generates a signature using a private key"
.Vb 1
\&  $base64 = $algorithm\->sign($private_key);
.Ve
.SS "\fBsignature()\fP \- get/set the signature worked on by this algorithm"
.IX Subsection "signature() - get/set the signature worked on by this algorithm"
.Vb 2
\&  my $old_signature = $algorithm\->signature;
\&  $algorithm\->signature($new_signature);
.Ve
.SS "\fBverify()\fP \- verifies a signature"
.IX Subsection "verify() - verifies a signature"
.Vb 1
\&  $result = $algorithm\->verify();
.Ve
.PP
Must be called after \fBfinish_body()\fR.
.PP
The result is a true/false value: true indicates the signature data
is valid, false indicates it is invalid.
.PP
For an invalid signature, details may be obtained from
\&\f(CW$algorithm\fR\->{verification_details} or $@.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mail::DKIM
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Jason Long <jason@long.name>
.IP "\(bu" 4
Marc Bradshaw <marc@marcbradshaw.net>
.IP "\(bu" 4
Bron Gondwana <brong@fastmailteam.com> (\s-1ARC\s0)
.SH "THANKS"
.IX Header "THANKS"
Work on ensuring that this module passes the \s-1ARC\s0 test suite was
generously sponsored by Valimail (https://www.valimail.com/)
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
.IP "\(bu" 4
Copyright (C) 2013 by Messiah College
.IP "\(bu" 4
Copyright (C) 2010 by Jason Long
.IP "\(bu" 4
Copyright (C) 2017 by Standcore \s-1LLC\s0
.IP "\(bu" 4
Copyright (C) 2020 by FastMail Pty Ltd
.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.