Mail::DKIM::Signer(3pm)

1Mail::DKIM::Signer(3) User Contributed Perl DocumentationMail::DKIM::Signer(3)
2
3
4

NAME

6       Mail::DKIM::Signer - generates a DKIM signature for a message
7

VERSION

9       version 1.20200907
10

SYNOPSIS

12         use Mail::DKIM::Signer;
13         use Mail::DKIM::TextWrap;  #recommended
14
15         # create a signer object
16         my $dkim = Mail::DKIM::Signer->new(
17                         Algorithm => 'rsa-sha1',
18                         Method => 'relaxed',
19                         Domain => 'example.org',
20                         Selector => 'selector1',
21                         KeyFile => 'private.key',
22                         Headers => 'x-header:x-header2',
23                    );
24
25         # read an email from a file handle
26         $dkim->load(*STDIN);
27
28         # or read an email and pass it into the signer, one line at a time
29         while (<STDIN>)
30         {
31             # remove local line terminators
32             chomp;
33             s/\015$//;
34
35             # use SMTP line terminators
36             $dkim->PRINT("$_\015\012");
37         }
38         $dkim->CLOSE;
39
40         # what is the signature result?
41         my $signature = $dkim->signature;
42         print $signature->as_string;
43

DESCRIPTION

45       This class is the part of Mail::DKIM responsible for generating
46       signatures for a given message. You create an object of this class,
47       specifying the parameters of the signature you wish to create, or
48       specifying a callback function so that the signature parameters can be
49       determined later. Next, you feed it the entire message using "PRINT()",
50       completing with "CLOSE()". Finally, use the "signatures()" method to
51       access the generated signatures.
52
53   Pretty Signatures
54       Mail::DKIM includes a signature-wrapping module (which inserts
55       linebreaks into the generated signature so that it looks nicer in the
56       resulting message. To enable this module, simply call
57
58         use Mail::DKIM::TextWrap;
59
60       in your program before generating the signature.
61

CONSTRUCTOR

63   new()
64       Construct an object-oriented signer.
65
66         # create a signer using the default policy
67         my $dkim = Mail::DKIM::Signer->new(
68                         Algorithm => 'rsa-sha1',
69                         Method => 'relaxed',
70                         Domain => 'example.org',
71                         Selector => 'selector1',
72                         KeyFile => 'private.key',
73                         Headers => 'x-header:x-header2',
74                    );
75
76         # create a signer using a custom policy
77         my $dkim = Mail::DKIM::Signer->new(
78                         Policy => $policyfn,
79                    );
80
81       The "default policy" is to create a DKIM signature using the specified
82       parameters, but only if the message's sender matches the domain.  The
83       following parameters can be passed to this new() method to influence
84       the resulting signature: Algorithm, Method, Domain, Selector, KeyFile,
85       Identity, Timestamp.
86
87       If you want different behavior, you can provide a "signer policy"
88       instead. A signer policy is a subroutine or class that determines
89       signature parameters after the message's headers have been parsed.  See
90       the section "SIGNER POLICIES" below for more information.
91
92       See Mail::DKIM::SignerPolicy for more information about policy objects.
93
94       In addition to the parameters demonstrated above, the following are
95       recognized:
96
97       Key rather than using "KeyFile", use "Key" to use an already-loaded
98           Mail::DKIM::PrivateKey object.
99
100       Headers
101           A colon separated list of headers to sign, this is added to the
102           list of default headers as shown in in the DKIM specification.
103
104           For each specified header all headers of that type which are
105           present in the message will be signed, but we will not oversign or
106           sign headers which are not present.
107
108           If you require greater control over signed headers please use the
109           extended_headers() method instead.
110
111           The list of headers signed by default is as follows
112
113               From Sender Reply-To Subject Date
114               Message-ID To Cc MIME-Version
115               Content-Type Content-Transfer-Encoding Content-ID Content-Description
116               Resent-Date Resent-From Resent-Sender Resent-To Resent-cc
117               Resent-Message-ID
118               In-Reply-To References
119               List-Id List-Help List-Unsubscribe List-Subscribe
120               List-Post List-Owner List-Archive
121

METHODS

123   PRINT()
124       Feed part of the message to the signer.
125
126         $dkim->PRINT("a line of the message\015\012");
127
128       Feeds content of the message being signed into the signer.  The API is
129       designed this way so that the entire message does NOT need to be read
130       into memory at once.
131
132       Please note that although the PRINT() method expects you to use SMTP-
133       style line termination characters, you should NOT use the SMTP-style
134       dot-stuffing technique described in RFC 2821 section 4.5.2.  Nor should
135       you use a <CR><LF>.<CR><LF> sequence to terminate the message.
136
137   CLOSE()
138       Call this when finished feeding in the message.
139
140         $dkim->CLOSE;
141
142       This method finishes the canonicalization process, computes a hash, and
143       generates a signature.
144
145   extended_headers()
146       This method overrides the headers to be signed and allows more control
147       than is possible with the Headers property in the constructor.
148
149       The method expects a HashRef to be passed in.
150
151       The Keys are the headers to sign, and the values are either the number
152       of headers of that type to sign, or the special values '*' and '+'.
153
154       * will sign ALL headers of that type present in the message.
155
156       + will sign ALL + 1 headers of that type present in the message to
157       prevent additional headers being added.
158
159       You may override any of the default headers by including them in the
160       hashref, and disable them by giving them a 0 value.
161
162       Keys are case insensitive with the values being added upto the highest
163       value.
164
165           Headers => {
166               'X-test'  => '*',
167               'x-test'  => '1',
168               'Subject' => '+',
169               'Sender'  => 0,
170           },
171
172   add_signature()
173       Used by signer policy to create a new signature.
174
175         $dkim->add_signature(new Mail::DKIM::Signature(...));
176
177       Signer policies can use this method to specify complete parameters for
178       the signature to add, including what type of signature. For more
179       information, see Mail::DKIM::SignerPolicy.
180
181   algorithm()
182       Get or set the selected algorithm.
183
184         $alg = $dkim->algorithm;
185
186         $dkim->algorithm('rsa-sha1');
187
188   domain()
189       Get or set the selected domain.
190
191         $alg = $dkim->domain;
192
193         $dkim->domain('example.org');
194
195   load()
196       Load the entire message from a file handle.
197
198         $dkim->load($file_handle);
199
200       Reads a complete message from the designated file handle, feeding it
201       into the signer.  The message must use <CRLF> line terminators (same as
202       the SMTP protocol).
203
204   headers()
205       Determine which headers to put in signature.
206
207         my $headers = $dkim->headers;
208
209       This is a string containing the names of the header fields that will be
210       signed, separated by colons.
211
212   key()
213       Get or set the private key object.
214
215         my $key = $dkim->key;
216
217         $dkim->key(Mail::DKIM::PrivateKey->load(File => 'private.key'));
218
219       The key object can be any object that implements the sign_digest()
220       method.  (Providing your own object can be useful if your actual keys
221       are stored out-of-process.)
222
223       If you use this method to specify a private key, do not use
224       "key_file()".
225
226   key_file()
227       Get or set the filename containing the private key.
228
229         my $filename = $dkim->key_file;
230
231         $dkim->key_file('private.key');
232
233       If you use this method to specify a private key file, do not use
234       "key()".
235
236   method()
237       Get or set the selected canonicalization method.
238
239         $alg = $dkim->method;
240
241         $dkim->method('relaxed');
242
243   message_originator()
244       Access the "From" header.
245
246         my $address = $dkim->message_originator;
247
248       Returns the "originator address" found in the message, as a
249       Mail::Address object.  This is typically the (first) name and email
250       address found in the From: header. If there is no From: header, then an
251       empty Mail::Address object is returned.
252
253       To get just the email address part, do:
254
255         my $email = $dkim->message_originator->address;
256
257       See also "message_sender()".
258
259   message_sender()
260       Access the "From" or "Sender" header.
261
262         my $address = $dkim->message_sender;
263
264       Returns the "sender" found in the message, as a Mail::Address object.
265       This is typically the (first) name and email address found in the
266       Sender: header. If there is no Sender: header, it is the first name and
267       email address in the From: header. If neither header is present, then
268       an empty Mail::Address object is returned.
269
270       To get just the email address part, do:
271
272         my $email = $dkim->message_sender->address;
273
274       The "sender" is the mailbox of the agent responsible for the actual
275       transmission of the message. For example, if a secretary were to send a
276       message for another person, the "sender" would be the secretary and the
277       "originator" would be the actual author.
278
279   selector()
280       Get or set the current key selector.
281
282         $alg = $dkim->selector;
283
284         $dkim->selector('alpha');
285
286   signature()
287       Access the generated signature object.
288
289         my $signature = $dkim->signature;
290
291       Returns the generated signature. The signature is an object of type
292       Mail::DKIM::Signature. If multiple signatures were generated, this
293       method returns the last one.
294
295       The signature (as text) should be prepended to the message to make the
296       resulting message. At the very least, it should precede any headers
297       that were signed.
298
299   signatures()
300       Access list of generated signature objects.
301
302         my @signatures = $dkim->signatures;
303
304       Returns all generated signatures, as a list.
305

SIGNER POLICIES

307       The new() constructor takes an optional Policy argument. This can be a
308       Perl object or class with an apply() method, or just a simple
309       subroutine reference. The method/subroutine will be called with the
310       signer object as an argument. The policy is responsible for checking
311       the message and specifying signature parameters. The policy must return
312       a nonzero value to create the signature, otherwise no signature will be
313       created. E.g.,
314
315         my $policyfn = sub {
316             my $dkim = shift;
317
318             # specify signature parameters
319             $dkim->algorithm('rsa-sha1');
320             $dkim->method('relaxed');
321             $dkim->domain('example.org');
322             $dkim->selector('mx1');
323
324             # return true value to create the signature
325             return 1;
326         };
327
328       Or the policy object can actually create the signature, using the
329       add_signature method within the policy object.  If you add a signature,
330       you do not need to return a nonzero value.  This mechanism can be
331       utilized to create multiple signatures, or to create the older
332       DomainKey-style signatures.
333
334         my $policyfn = sub {
335             my $dkim = shift;
336             $dkim->add_signature(
337                     new Mail::DKIM::Signature(
338                             Algorithm => 'rsa-sha1',
339                             Method => 'relaxed',
340                             Headers => $dkim->headers,
341                             Domain => 'example.org',
342                             Selector => 'mx1',
343                     ));
344             $dkim->add_signature(
345                     new Mail::DKIM::DkSignature(
346                             Algorithm => 'rsa-sha1',
347                             Method => 'nofws',
348                             Headers => $dkim->headers,
349                             Domain => 'example.org',
350                             Selector => 'mx1',
351                     ));
352             return;
353         };
354
355       If no policy is specified, the default policy is used. The default
356       policy signs every message using the domain, algorithm, method, and
357       selector specified in the new() constructor.
358

AUTHORS

363       •   Jason Long <jason@long.name>
364
365       •   Marc Bradshaw <marc@marcbradshaw.net>
366
367       •   Bron Gondwana <brong@fastmailteam.com> (ARC)
368

THANKS

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

COPYRIGHT AND LICENSE

374       •   Copyright (C) 2013 by Messiah College
375
376       •   Copyright (C) 2010 by Jason Long
377
378       •   Copyright (C) 2017 by Standcore LLC
379
380       •   Copyright (C) 2020 by FastMail Pty Ltd
381
382       This library is free software; you can redistribute it and/or modify it
383       under the same terms as Perl itself, either Perl version 5.8.6 or, at
384       your option, any later version of Perl 5 you may have available.
385
386
387
388perl v5.34.0                      2021-07-22             Mail::DKIM::Signer(3)