.\" -*- 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::DkSignature 3"
.TH Mail::DKIM::DkSignature 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::DkSignature \- represents a DomainKeys\-Signature header
.SH VERSION
.IX Header "VERSION"
version 1.20230911
.SH CONSTRUCTORS
.IX Header "CONSTRUCTORS"
.SS \fBnew()\fP
.IX Subsection "new()"
Create a new DomainKey signature from parameters
.PP
.Vb 10
\&  my $signature = Mail::DKIM::DkSignature\->new(
\&                      [ Algorithm => \*(Aqrsa\-sha1\*(Aq, ]
\&                      [ Signature => $base64, ]
\&                      [ Method => \*(Aqsimple\*(Aq, ]
\&                      [ Domain => \*(Aqexample.org\*(Aq, ]
\&                      [ Headers => \*(Aqfrom:subject:date:message\-id\*(Aq, ]
\&                      [ Query => \*(Aqdns\*(Aq, ]
\&                      [ Selector => \*(Aqalpha\*(Aq, ]
\&                      [ Key => $private_key, ]
\&                  );
.Ve
.SS \fBparse()\fP
.IX Subsection "parse()"
Create a new signature from a DomainKey-Signature header
.PP
.Vb 3
\&  my $sig = Mail::DKIM::DkSignature\->parse(
\&                  \*(AqDomainKey\-Signature: a=rsa\-sha1; b=yluiJ7+0=; c=nofws\*(Aq
\&            );
.Ve
.PP
Constructs a signature by parsing the provided DomainKey-Signature header
content. You do not have to include the header name
(i.e. "DomainKey-Signature:")
but it is recommended, so the header name can be preserved and returned
the same way in "\fBas_string()\fR".
.PP
Note: The input to this constructor is in the same format as the output
of the as_string method.
.SH METHODS
.IX Header "METHODS"
.SS \fBas_string()\fP
.IX Subsection "as_string()"
Convert the signature header as a string.
.PP
.Vb 1
\&  print $signature\->as_string . "\en";
.Ve
.PP
outputs
.PP
.Vb 1
\&  DomainKey\-Signature: a=rsa\-sha1; b=yluiJ7+0=; c=nofws
.Ve
.PP
As shown in the example, the as_string method can be used to generate
the DomainKey-Signature that gets prepended to a signed message.
.SS \fBalgorithm()\fP
.IX Subsection "algorithm()"
Get or set the algorithm (a=) field
.PP
The algorithm used to generate the signature.
Defaults to "rsa\-sha1", an RSA-signed SHA\-1 digest.
.SS \fBcanonicalization()\fP
.IX Subsection "canonicalization()"
Get or set the canonicalization (c=) field.
.PP
.Vb 2
\&  $signature\->canonicalization(\*(Aqnofws\*(Aq);
\&  $signature\->canonicalization(\*(Aqsimple\*(Aq);
\&
\&  $method = $signature\->canonicalization;
.Ve
.PP
Message canonicalization (default is "simple"). This informs the
verifier of the type of canonicalization used to prepare the message for
signing.
.SS \fBdomain()\fP
.IX Subsection "domain()"
Get or set the domain (d=) field.
.PP
.Vb 2
\&  my $d = $signature\->domain;          # gets the domain value
\&  $signature\->domain(\*(Aqexample.org\*(Aq);   # sets the domain value
.Ve
.PP
The domain of the signing entity, as specified in the signature.
This is the domain that will be queried for the public key.
.SS \fBheaderlist()\fP
.IX Subsection "headerlist()"
Get or set the signed header fields (h=) field.
.PP
.Vb 1
\&  $signature\->headerlist(\*(Aqa:b:c\*(Aq);
\&
\&  my $headerlist = $signature\->headerlist;
\&
\&  my @headers = $signature\->headerlist;
.Ve
.PP
Signed header fields. A colon-separated list of header field names
that identify the header fields presented to the signing algorithm.
.PP
In scalar context, the list of header field names will be returned
as a single string, with the names joined together with colons.
In list context, the header field names will be returned as a list.
.SS \fBidentity()\fP
.IX Subsection "identity()"
Get the signing identity.
.PP
.Vb 1
\&  my $i = $signature\->identity;
.Ve
.PP
In DomainKey signatures, the signing identity is the first address
found in the Sender header or the From header. This field is
populated by the Verifier when processing a DomainKey signature.
.SS \fBidentity_source()\fP
.IX Subsection "identity_source()"
Determine which header had the identity.
.PP
.Vb 1
\&  my $source = $signature\->identity_source;
.Ve
.PP
If the message is being verified, this method will tell you which
of the message headers was used to determine the signature identity.
Possible values are "header.sender" and "header.from".
.SS \fBprotocol()\fP
.IX Subsection "protocol()"
Get or set the query methods (q=) field.
.PP
A colon-separated list of query methods used to retrieve the public
key (default is "dns").
.SS \fBselector()\fP
.IX Subsection "selector()"
Get or set the selector (s=) field.
.PP
The selector subdivides the namespace for the "d=" (domain) tag.
.SS \fBsignature()\fP
.IX Subsection "signature()"
Get or set the signature data (b=) field.
.PP
The signature data. Whitespace is automatically stripped from the
returned value.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mail::DKIM::Signature for DKIM-Signature headers
.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.