Mail::DKIM::Signature(3pm)

1Mail::DKIM::Signature(3U)ser Contributed Perl DocumentatiMoanil::DKIM::Signature(3)
2
3
4

NAME

6       Mail::DKIM::Signature - represents a DKIM-Signature header
7

VERSION

9       version 1.20220520
10

CONSTRUCTORS

12   new() - create a new signature from parameters
13         my $signature = Mail::DKIM::Signature->new(
14                             [ Algorithm => 'rsa-sha1', ]
15                             [ Signature => $base64, ]
16                             [ Method => 'relaxed', ]
17                             [ Domain => 'example.org', ]
18                             [ Identity => 'user@example.org', ]
19                             [ Headers => 'from:subject:date:message-id', ]
20                             [ Query => 'dns', ]
21                             [ Selector => 'alpha', ]
22                             [ Timestamp => time(), ]
23                             [ Expiration => time() + 86400, ]
24                         );
25
26   parse() - create a new signature from a DKIM-Signature header
27         my $sig = Mail::DKIM::Signature->parse(
28                         'DKIM-Signature: a=rsa-sha1; b=yluiJ7+0=; c=relaxed'
29                   );
30
31       Constructs a signature by parsing the provided DKIM-Signature header
32       content. You do not have to include the header name (i.e. "DKIM-
33       Signature:") but it is recommended, so the header name can be preserved
34       and returned the same way in as_string().
35
36       Note: The input to this constructor is in the same format as the output
37       of the as_string method.
38

METHODS

40   algorithm() - get or set the algorithm (a=) field
41       The algorithm used to generate the signature. Should be either
42       "rsa-sha1", an RSA-signed SHA-1 digest, or "rsa-sha256", an RSA-signed
43       SHA-256 digest.
44
45       See also hash_algorithm().
46
47   as_string() - the signature header as a string
48         print $signature->as_string . "\n";
49
50       outputs
51
52         DKIM-Signature: a=rsa-sha1; b=yluiJ7+0=; c=relaxed
53
54       As shown in the example, the as_string method can be used to generate
55       the DKIM-Signature that gets prepended to a signed message.
56
57   as_string_without_data() - signature without the signature data
58         print $signature->as_string_without_data . "\n";
59
60       outputs
61
62         DKIM-Signature: a=rsa-sha1; b=; c=relaxed
63
64       This is similar to the as_string() method, but it always excludes the
65       "data" part. This is used by the DKIM canonicalization methods, which
66       require incorporating this part of the signature into the signed
67       message.
68
69   body_count() - get or set the body count (l=) field
70         my $i = $signature->body_count;
71
72       Informs the verifier of the number of bytes in the body of the email
73       included in the cryptographic hash, starting from 0 immediately
74       following the CRLF preceding the body. Also known as the l= tag.
75
76       When creating a signature, this tag may be either omitted, or set after
77       the selected canonicalization system has received the entire message
78       body (but before it canonicalizes the DKIM-Signature).
79
80   body_hash() - get or set the body hash (bh=) field
81         my $bh = $signature->body_hash;
82
83       The hash of the body part of the message. Whitespace is ignored in this
84       value. This tag is required.
85
86       When accessing this value, whitespace is stripped from the tag for you.
87
88   canonicalization() - get or set the canonicalization (c=) field
89         $signature->canonicalization('relaxed', 'simple');
90
91         ($header, $body) = $signature->canonicalization;
92
93       Message canonicalization (default is "simple/simple"). This informs the
94       verifier of the type of canonicalization used to prepare the message
95       for signing.
96
97       In scalar context, this returns header/body canonicalization as a
98       single string separated by /. In list context, it returns a two element
99       array, containing first the header canonicalization, then the body.
100
101   data() - get or set the signature data (b=) field
102         my $base64 = $signature->data;
103         $signature->data($base64);
104
105       The signature data. Whitespace is automatically stripped from the
106       returned value. The data is Base64-encoded.
107
108   domain() - get or set the domain (d=) field
109         my $d = $signature->domain;          # gets the domain value
110         $signature->domain('example.org');   # sets the domain value
111
112       The domain of the signing entity, as specified in the signature.  This
113       is the domain that will be queried for the public key.
114
115       If using an "internationalized domain name", the domain name must be
116       converted to ASCII (following section 4.1 of RFC 3490) before passing
117       it to this method.
118
119   expiration() - get or set the signature expiration (x=) field
120       Signature expiration (default is undef, meaning no expiration).  The
121       signature expiration, if defined, is an unsigned integer identifying
122       the standard Unix seconds-since-1970 time when the signature will
123       expire.
124
125   get_public_key() - fetches the public key referenced by this signature
126         my $pubkey = $signature->get_public_key;
127
128       Public key to fetch is determined by the protocol, selector, and domain
129       fields.
130
131       This method caches the result of the fetch, so subsequent calls will
132       not require additional DNS queries.
133
134       This method will "die" if an error occurs.
135
136   get_tag() - access the raw value of a tag in this signature
137         my $raw_identity = $signature->get_tag('i');
138
139       Use this method to access a tag not already supported by Mail::DKIM, or
140       if you want to bypass decoding of the value by Mail::DKIM.
141
142       For example, the raw i= (identity) tag is encoded in quoted-printable
143       form. If you use the identity() method, Mail::DKIM will decode from
144       quoted-printable before returning the value. But if you use
145       get_tag('i'), you can access the encoded quoted-printable form of the
146       value.
147
148   hash_algorithm() - access the hash algorithm specified in this signature
149         my $hash = $signature->hash_algorithm;
150
151       Determines what hashing algorithm is used as part of the signature's
152       specified algorithm.
153
154       For algorithm "rsa-sha1", the hash algorithm is "sha1". Likewise, for
155       algorithm "rsa-sha256", the hash algorithm is "sha256". If the
156       algorithm is not recognized, undef is returned.
157
158   headerlist() - get or set the signed header fields (h=) field
159         $signature->headerlist('a:b:c');
160
161         my $headerlist = $signature->headerlist;
162
163         my @headers = $signature->headerlist;
164
165       Signed header fields. A colon-separated list of header field names that
166       identify the header fields presented to the signing algorithm.
167
168       In scalar context, the list of header field names will be returned as a
169       single string, with the names joined together with colons.  In list
170       context, the header field names will be returned as a list.
171
172   identity() - get or set the signing identity (i=) field
173         my $i = $signature->identity;
174
175       Identity of the user or agent on behalf of which this message is
176       signed.  The identity has an optional local part, followed by "@", then
177       a domain name. The domain name should be the same as or a subdomain of
178       the domain returned by the "domain" method.
179
180       Ideally, the identity should match the identity listed in the From:
181       header, or the Sender: header, but this is not required to have a valid
182       signature. Whether the identity used is "authorized" to sign for the
183       given message is not determined here.
184
185       If using an "internationalized domain name", the domain name must be
186       converted to ASCII (following section 4.1 of RFC 3490) before passing
187       it to this method.
188
189       Identity values are encoded in the signature in quoted-printable
190       format.  Using this method will translate to/from quoted-printable as
191       necessary.  If you want the raw quoted-printable version of the
192       identity, use $signature->get_tag('i').
193
194   key() - get or set the private key object
195         my $key = $signature->key;
196
197         $signature->key(Mail::DKIM::PrivateKey->load(File => 'private.key'));
198
199       The private key is used for signing messages.  It is not used for
200       verifying messages.
201
202       The key object can be any object that implements the sign_digest()
203       method.  (Providing your own object can be useful if your actual keys
204       are stored out-of-process.)
205
206   method() - get or set the canonicalization (c=) field
207       Message canonicalization (default is "simple"). This informs the
208       verifier of the type of canonicalization used to prepare the message
209       for signing.
210
211   protocol() - get or set the query methods (q=) field
212       A colon-separated list of query methods used to retrieve the public key
213       (default is "dns"). Each query method is of the form "type[/options]",
214       where the syntax and semantics of the options depends on the type.
215
216   result() - get or set the verification result
217         my $result = $signature->result;
218
219         $signature->result('pass');
220
221         # to set the result with details
222         $signature->result('invalid', 'no public key');
223
224   result_detail() - access the result, plus details if available
225         my $detail = $signature->result_detail;
226
227       An explanation of possible detail messages can be found in the
228       documentation for "result_detail()" in Mail::DKIM::Verifier.
229
230   selector() - get or set the selector (s=) field
231       The selector subdivides the namespace for the "d=" (domain) tag.
232
233   prettify() - alters the signature to look "nicer" as an email header
234         $signature->prettify;
235
236       This method may alter the signature in a way that breaks signatures, so
237       it should be done ONLY when the signature is being generated, BEFORE
238       being fed to the canonicalization algorithm.
239
240       See also prettify_safe(), which will not break signatures.
241
242   prettify_safe() - same as prettify() but only touches the b= part
243         $signature->prettify_safe;
244
245       This method will not break the signature, but it only affects the b=
246       part of the signature.
247
248   timestamp() - get or set the signature timestamp (t=) field
249       Signature timestamp (default is undef, meaning unknown creation time).
250       This is the time that the signature was created. The value is an
251       unsigned integer identifying the number of standard Unix
252       seconds-since-1970.
253
254   version() - get or set the DKIM specification version (v=) field
255       This is the version of the DKIM specification that applies to this
256       signature record.
257

AUTHORS

262       •   Jason Long <jason@long.name>
263
264       •   Marc Bradshaw <marc@marcbradshaw.net>
265
266       •   Bron Gondwana <brong@fastmailteam.com> (ARC)
267

THANKS

269       Work on ensuring that this module passes the ARC test suite was
270       generously sponsored by Valimail (https://www.valimail.com/)
271

COPYRIGHT AND LICENSE

273       •   Copyright (C) 2013 by Messiah College
274
275       •   Copyright (C) 2010 by Jason Long
276
277       •   Copyright (C) 2017 by Standcore LLC
278
279       •   Copyright (C) 2020 by FastMail Pty Ltd
280
281       This library is free software; you can redistribute it and/or modify it
282       under the same terms as Perl itself, either Perl version 5.8.6 or, at
283       your option, any later version of Perl 5 you may have available.
284
285
286
287perl v5.36.0                      2022-07-22          Mail::DKIM::Signature(3)