NAME

       Mail::DKIM::DkSignature - represents a DomainKeys-Signature header

VERSION

       version 1.20230212

CONSTRUCTORS

   new()
       Create a new DomainKey signature from parameters

         my $signature = Mail::DKIM::DkSignature->new(
                             [ Algorithm => 'rsa-sha1', ]
                             [ Signature => $base64, ]
                             [ Method => 'simple', ]
                             [ Domain => 'example.org', ]
                             [ Headers => 'from:subject:date:message-id', ]
                             [ Query => 'dns', ]
                             [ Selector => 'alpha', ]
                             [ Key => $private_key, ]
                         );

   parse()
       Create a new signature from a DomainKey-Signature header

         my $sig = Mail::DKIM::DkSignature->parse(
                         'DomainKey-Signature: a=rsa-sha1; b=yluiJ7+0=; c=nofws'
                   );

       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 "as_string()".

       Note: The input to this constructor is in the same format as the output of the as_string method.

METHODS

   as_string()
       Convert the signature header as a string.

         print $signature->as_string . "\n";

       outputs

         DomainKey-Signature: a=rsa-sha1; b=yluiJ7+0=; c=nofws

       As shown in the example, the as_string method can be used to generate the DomainKey-Signature that gets
       prepended to a signed message.

   algorithm()
       Get or set the algorithm (a=) field

       The algorithm used to generate the signature.  Defaults to "rsa-sha1", an RSA-signed SHA-1 digest.

   canonicalization()
       Get or set the canonicalization (c=) field.

         $signature->canonicalization('nofws');
         $signature->canonicalization('simple');

         $method = $signature->canonicalization;

       Message canonicalization (default is "simple"). This informs the verifier of the type of canonicalization
       used to prepare the message for signing.

   domain()
       Get or set the domain (d=) field.

         my $d = $signature->domain;          # gets the domain value
         $signature->domain('example.org');   # sets the domain value

       The domain of the signing entity, as specified in the signature.  This is the domain that will be queried
       for the public key.

   headerlist()
       Get or set the signed header fields (h=) field.

         $signature->headerlist('a:b:c');

         my $headerlist = $signature->headerlist;

         my @headers = $signature->headerlist;

       Signed header fields. A colon-separated list of header field names that identify the header fields
       presented to the signing algorithm.

       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.

   identity()
       Get the signing identity.

         my $i = $signature->identity;

       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.

   identity_source()
       Determine which header had the identity.

         my $source = $signature->identity_source;

       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".

   protocol()
       Get or set the query methods (q=) field.

       A colon-separated list of query methods used to retrieve the public key (default is "dns").

   selector()
       Get or set the selector (s=) field.

       The selector subdivides the namespace for the "d=" (domain) tag.

   signature()
       Get or set the signature data (b=) field.

       The signature data. Whitespace is automatically stripped from the returned value.

SEE ALSO

       Mail::DKIM::Signature for DKIM-Signature headers

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::DkSignature(3pm)