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

AUTHORS

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

THANKS

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

COPYRIGHT AND LICENSE

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