.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 3"
.TH Mail::DKIM::Algorithm::Base 3 2023-10-09 "perl v5.38.0" "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.20230911
.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 DKIM 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 "line" 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 <CRLF> sequences). It terminates with
the <CRLF> 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> (ARC)
.SH THANKS
.IX Header "THANKS"
Work on ensuring that this module passes the ARC 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 LLC
.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.