1Mail::DKIM::Signer(3) User Contributed Perl DocumentationMail::DKIM::Signer(3)
2
6 Mail::DKIM::Signer - generates a DKIM signature for a message
7
9 version 1.20230630
10
12 use Mail::DKIM::Signer;
13 use Mail::DKIM::TextWrap; #recommended
14 # 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 # read an email from a file handle
26 $dkim->load(*STDIN);
27 # 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 # use SMTP line terminators
36 $dkim->PRINT("$_\015\012");
37 }
38 $dkim->CLOSE;
39 # what is the signature result?
41 my $signature = $dkim->signature;
42 print $signature->as_string;
43
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 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 use Mail::DKIM::TextWrap;
59 in your program before generating the signature.
61
63 new()
64 Construct an object-oriented signer.
65 # 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 # create a signer using a custom policy
77 my $dkim = Mail::DKIM::Signer->new(
78 Policy => $policyfn,
79 );
80 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, Expiration.
86 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 See Mail::DKIM::SignerPolicy for more information about policy objects.
93 In addition to the parameters demonstrated above, the following are
95 recognized:
96 Key rather than using "KeyFile", use "Key" to use an already-loaded
98 Mail::DKIM::PrivateKey object.
99 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 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 If you require greater control over signed headers please use the
109 extended_headers() method instead.
110 The list of headers signed by default is as follows
112 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 Tags
123 An optional hashref of additional tags to be added to the DKIM
124 signature generated.
125
127 PRINT()
128 Feed part of the message to the signer.
129 $dkim->PRINT("a line of the message\015\012");
131 Feeds content of the message being signed into the signer. The API is
133 designed this way so that the entire message does NOT need to be read
134 into memory at once.
135 Please note that although the PRINT() method expects you to use SMTP-
137 style line termination characters, you should NOT use the SMTP-style
138 dot-stuffing technique described in RFC 2821 section 4.5.2. Nor should
139 you use a <CR><LF>.<CR><LF> sequence to terminate the message.
140 CLOSE()
142 Call this when finished feeding in the message.
143 $dkim->CLOSE;
145 This method finishes the canonicalization process, computes a hash, and
147 generates a signature.
148 extended_headers()
150 This method overrides the headers to be signed and allows more control
151 than is possible with the Headers property in the constructor.
152 The method expects a HashRef to be passed in.
154 The Keys are the headers to sign, and the values are either the number
156 of headers of that type to sign, or the special values '*' and '+'.
157 * will sign ALL headers of that type present in the message.
159 + will sign ALL + 1 headers of that type present in the message to
161 prevent additional headers being added.
162 You may override any of the default headers by including them in the
164 hashref, and disable them by giving them a 0 value.
165 Keys are case insensitive with the values being added upto the highest
167 value.
168 Headers => {
170 'X-test' => '*',
171 'x-test' => '1',
172 'Subject' => '+',
173 'Sender' => 0,
174 },
175 add_signature()
177 Used by signer policy to create a new signature.
178 $dkim->add_signature(new Mail::DKIM::Signature(...));
180 Signer policies can use this method to specify complete parameters for
182 the signature to add, including what type of signature. For more
183 information, see Mail::DKIM::SignerPolicy.
184 algorithm()
186 Get or set the selected algorithm.
187 $alg = $dkim->algorithm;
189 $dkim->algorithm('rsa-sha1');
191 domain()
193 Get or set the selected domain.
194 $alg = $dkim->domain;
196 $dkim->domain('example.org');
198 load()
200 Load the entire message from a file handle.
201 $dkim->load($file_handle);
203 Reads a complete message from the designated file handle, feeding it
205 into the signer. The message must use <CRLF> line terminators (same as
206 the SMTP protocol).
207 headers()
209 Determine which headers to put in signature.
210 my $headers = $dkim->headers;
212 This is a string containing the names of the header fields that will be
214 signed, separated by colons.
215 key()
217 Get or set the private key object.
218 my $key = $dkim->key;
220 $dkim->key(Mail::DKIM::PrivateKey->load(File => 'private.key'));
222 The key object can be any object that implements the sign_digest()
224 method. (Providing your own object can be useful if your actual keys
225 are stored out-of-process.)
226 If you use this method to specify a private key, do not use
228 "key_file()".
229 key_file()
231 Get or set the filename containing the private key.
232 my $filename = $dkim->key_file;
234 $dkim->key_file('private.key');
236 If you use this method to specify a private key file, do not use
238 "key()".
239 method()
241 Get or set the selected canonicalization method.
242 $alg = $dkim->method;
244 $dkim->method('relaxed');
246 message_originator()
248 Access the "From" header.
249 my $address = $dkim->message_originator;
251 Returns the "originator address" found in the message, as a
253 Mail::Address object. This is typically the (first) name and email
254 address found in the From: header. If there is no From: header, then an
255 empty Mail::Address object is returned.
256 To get just the email address part, do:
258 my $email = $dkim->message_originator->address;
260 See also "message_sender()".
262 message_sender()
264 Access the "From" or "Sender" header.
265 my $address = $dkim->message_sender;
267 Returns the "sender" found in the message, as a Mail::Address object.
269 This is typically the (first) name and email address found in the
270 Sender: header. If there is no Sender: header, it is the first name and
271 email address in the From: header. If neither header is present, then
272 an empty Mail::Address object is returned.
273 To get just the email address part, do:
275 my $email = $dkim->message_sender->address;
277 The "sender" is the mailbox of the agent responsible for the actual
279 transmission of the message. For example, if a secretary were to send a
280 message for another person, the "sender" would be the secretary and the
281 "originator" would be the actual author.
282 selector()
284 Get or set the current key selector.
285 $alg = $dkim->selector;
287 $dkim->selector('alpha');
289 signature()
291 Access the generated signature object.
292 my $signature = $dkim->signature;
294 Returns the generated signature. The signature is an object of type
296 Mail::DKIM::Signature. If multiple signatures were generated, this
297 method returns the last one.
298 The signature (as text) should be prepended to the message to make the
300 resulting message. At the very least, it should precede any headers
301 that were signed.
302 signatures()
304 Access list of generated signature objects.
305 my @signatures = $dkim->signatures;
307 Returns all generated signatures, as a list.
309
311 The new() constructor takes an optional Policy argument. This can be a
312 Perl object or class with an apply() method, or just a simple
313 subroutine reference. The method/subroutine will be called with the
314 signer object as an argument. The policy is responsible for checking
315 the message and specifying signature parameters. The policy must return
316 a nonzero value to create the signature, otherwise no signature will be
317 created. E.g.,
318 my $policyfn = sub {
320 my $dkim = shift;
321 # specify signature parameters
323 $dkim->algorithm('rsa-sha1');
324 $dkim->method('relaxed');
325 $dkim->domain('example.org');
326 $dkim->selector('mx1');
327 # return true value to create the signature
329 return 1;
330 };
331 Or the policy object can actually create the signature, using the
333 add_signature method within the policy object. If you add a signature,
334 you do not need to return a nonzero value. This mechanism can be
335 utilized to create multiple signatures, or to create the older
336 DomainKey-style signatures.
337 my $policyfn = sub {
339 my $dkim = shift;
340 $dkim->add_signature(
341 new Mail::DKIM::Signature(
342 Algorithm => 'rsa-sha1',
343 Method => 'relaxed',
344 Headers => $dkim->headers,
345 Domain => 'example.org',
346 Selector => 'mx1',
347 ));
348 $dkim->add_signature(
349 new Mail::DKIM::DkSignature(
350 Algorithm => 'rsa-sha1',
351 Method => 'nofws',
352 Headers => $dkim->headers,
353 Domain => 'example.org',
354 Selector => 'mx1',
355 ));
356 return;
357 };
358 If no policy is specified, the default policy is used. The default
360 policy signs every message using the domain, algorithm, method, and
361 selector specified in the new() constructor.
362
364 Mail::DKIM::SignerPolicy
365
367 • Jason Long <jason@long.name>
368 • Marc Bradshaw <marc@marcbradshaw.net>
370 • Bron Gondwana <brong@fastmailteam.com> (ARC)
372
374 Work on ensuring that this module passes the ARC test suite was
375 generously sponsored by Valimail (https://www.valimail.com/)
376
378 • Copyright (C) 2013 by Messiah College
379 • Copyright (C) 2010 by Jason Long
381 • Copyright (C) 2017 by Standcore LLC
383 • Copyright (C) 2020 by FastMail Pty Ltd
385 This library is free software; you can redistribute it and/or modify it
387 under the same terms as Perl itself, either Perl version 5.8.6 or, at
388 your option, any later version of Perl 5 you may have available.
389perl v5.38.0 2023-07-24 Mail::DKIM::Signer(3)