1Mail::DKIM::ARC::SignerU(s3e)r Contributed Perl DocumentaMtaiioln::DKIM::ARC::Signer(3)
2
6 Mail::DKIM::ARC::Signer - generates a DKIM signature for a message
7
9 version 1.20230630
10
12 use Mail::DKIM::ARC::Signer;
13 use Mail::DKIM::TextWrap; #recommended
14 # create a signer object
16 my $signer = Mail::DKIM::ARC::Signer->new(
17 Algorithm => 'rsa-sha256',
18 Chain => 'none', # or pass|fail|ar
19 Domain => 'example.org',
20 SrvId => 'example.org',
21 Selector => 'selector1',
22 KeyFile => 'private.key',
23 Headers => 'x-header:x-header2',
24 );
25 # read an email from a file handle
27 $signer->load(*STDIN);
28 # NOTE: any email being ARC signed must have an Authentication-Results
30 # header so that the ARC seal can cover those results copied into
31 # an ARC-Authentication-Results header.
32 # or read an email and pass it into the signer, one line at a time
34 while (<STDIN>)
35 {
36 # remove local line terminators
37 chomp;
38 s/\015$//;
39 # use SMTP line terminators
41 $signer->PRINT("$_\015\012");
42 }
43 $signer->CLOSE;
44 die 'Failed' $signer->result_detail() unless $signer->result() eq 'sealed';
46 # Get all the signature headers to prepend to the message
48 # ARC-Seal, ARC-Message-Signature and ARC-Authentication-Results
49 # in that order.
50 print $signer->as_string;
51
53 This class is the part of Mail::DKIM responsible for generating ARC
54 Seals for a given message. You create an object of this class,
55 specifying the parameters for the ARC-Message-Signature you wish to
56 create.
57 You also need to pass the 'Chain' value (pass or fail) from validation
59 of the previous ARC-Seals on the message.
60 Next, you feed it the entire message using "PRINT()", completing with
62 "CLOSE()".
63 Finally, use the "as_string()" method to get the new ARC headers.
65 Note: you can only seal a message which has already had an
67 Authentication-Results header added, either by using "PRINT()" to pre-
68 feed it into this module, or by adding a message which has already been
69 authenticated by your inbound scanning mechanisms.
70 It is not necessary to ARC-Seal a message which already has DKIM
72 signatures if you are not modifying the message and hence breaking the
73 existing DKIM-Signature or top ARC-Message-Signature on the email.
74 Pretty Signatures
76 Mail::DKIM includes a signature-wrapping module (which inserts
77 linebreaks into the generated signature so that it looks nicer in the
78 resulting message. To enable this module, simply call
79 use Mail::DKIM::TextWrap;
81 in your program before generating the signature.
83
85 new()
86 Construct an object-oriented signer.
87 # create a signer using the default policy
89 my $signer = Mail::DKIM::ARC::Signer->new(
90 Algorithm => 'rsa-sha256',
91 Chain => 'none', # or pass|fail|ar
92 Domain => 'example.org',
93 SrvId => 'example.org',
94 Selector => 'selector1',
95 KeyFile => 'private.key',
96 Headers => 'x-header:x-header2',
97 );
98 Key rather than using "KeyFile", use "Key" to use an already-loaded
100 Mail::DKIM::PrivateKey object.
101 Chain
103 The cv= value for the Arc-Seal header. "ar" means to copy it from
104 an Authentication-Results header, or use none if there isn't one.
105 SrvId
107 The authserv-id in the Authentication-Results headers, defaults to
108 Domain.
109 Headers
111 A colon separated list of headers to sign, this is added to the
112 list of default headers as shown in in the DKIM specification.
113 For each specified header all headers of that type which are
115 present in the message will be signed, but we will not oversign or
116 sign headers which are not present.
117 If you require greater control over signed headers please use the
119 extended_headers() method instead.
120 The list of headers signed by default is as follows
122 From Sender Reply-To Subject Date
124 Message-ID To Cc MIME-Version
125 Content-Type Content-Transfer-Encoding Content-ID Content-Description
126 Resent-Date Resent-From Resent-Sender Resent-To Resent-cc
127 Resent-Message-ID
128 In-Reply-To References
129 List-Id List-Help List-Unsubscribe List-Subscribe
130 List-Post List-Owner List-Archive
131
133 PRINT()
134 Feed part of the message to the signer.
135 $signer->PRINT("a line of the message\015\012");
137 Feeds content of the message being signed into the signer. The API is
139 designed this way so that the entire message does NOT need to be read
140 into memory at once.
141 Please note that although the PRINT() method expects you to use SMTP-
143 style line termination characters, you should NOT use the SMTP-style
144 dot-stuffing technique described in RFC 2821 section 4.5.2. Nor should
145 you use a <CR><LF>.<CR><LF> sequence to terminate the message.
146 CLOSE()
148 Call this when finished feeding in the message.
149 $signer->CLOSE;
151 This method finishes the canonicalization process, computes a hash, and
153 generates a signature.
154 extended_headers()
156 This method overrides the headers to be signed and allows more control
157 than is possible with the Headers property in the constructor.
158 The method expects a HashRef to be passed in.
160 The Keys are the headers to sign, and the values are either the number
162 of headers of that type to sign, or the special values '*' and '+'.
163 * will sign ALL headers of that type present in the message.
165 + will sign ALL + 1 headers of that type present in the message to
167 prevent additional headers being added.
168 You may override any of the default headers by including them in the
170 hashref, and disable them by giving them a 0 value.
171 Keys are case insensitive with the values being added upto the highest
173 value.
174 Headers => {
176 'X-test' => '*',
177 'x-test' => '1',
178 'Subject' => '+',
179 'Sender' => 0,
180 },
181 add_signature()
183 Used by signer policy to create a new signature.
184 $signer->add_signature(new Mail::DKIM::Signature(...));
186 Signer policies can use this method to specify complete parameters for
188 the signature to add, including what type of signature. For more
189 information, see Mail::DKIM::SignerPolicy.
190 algorithm()
192 Get or set the selected algorithm.
193 $alg = $signer->algorithm;
195 $signer->algorithm('rsa-sha256');
197 domain()
199 Get or set the selected domain.
200 $alg = $signer->domain;
202 $signer->domain('example.org');
204 load()
206 Load the entire message from a file handle.
207 $signer->load($file_handle);
209 Reads a complete message from the designated file handle, feeding it
211 into the signer. The message must use <CRLF> line terminators (same as
212 the SMTP protocol).
213 headers()
215 Determine which headers to put in signature.
216 my $headers = $signer->headers;
218 This is a string containing the names of the header fields that will be
220 signed, separated by colons.
221 key()
223 Get or set the private key object.
224 my $key = $signer->key;
226 $signer->key(Mail::DKIM::PrivateKey->load(File => 'private.key'));
228 The key object can be any object that implements the sign_digest()
230 method. (Providing your own object can be useful if your actual keys
231 are stored out-of-process.)
232 If you use this method to specify a private key, do not use
234 "key_file()".
235 key_file()
237 Get or set the filename containing the private key.
238 my $filename = $signer->key_file;
240 $signer->key_file('private.key');
242 If you use this method to specify a private key file, do not use
244 "key()".
245 message_originator()
247 Access the "From" header.
248 my $address = $signer->message_originator;
250 Returns the "originator address" found in the message, as a
252 Mail::Address object. This is typically the (first) name and email
253 address found in the From: header. If there is no From: header, then an
254 empty Mail::Address object is returned.
255 To get just the email address part, do:
257 my $email = $signer->message_originator->address;
259 See also "message_sender()".
261 message_sender()
263 Access the "From" or "Sender" header.
264 my $address = $dkim->message_sender;
266 Returns the "sender" found in the message, as a Mail::Address object.
268 This is typically the (first) name and email address found in the
269 Sender: header. If there is no Sender: header, it is the first name and
270 email address in the From: header. If neither header is present, then
271 an empty Mail::Address object is returned.
272 To get just the email address part, do:
274 my $email = $dkim->message_sender->address;
276 The "sender" is the mailbox of the agent responsible for the actual
278 transmission of the message. For example, if a secretary were to send a
279 message for another person, the "sender" would be the secretary and the
280 "originator" would be the actual author.
281 selector()
283 Get or set the current key selector.
284 $alg = $dkim->selector;
286 $dkim->selector('alpha');
288 signatures()
290 Access list of generated signature objects.
291 my @signatures = $dkim->signatures;
293 Returns all generated signatures, as a list.
295 as_string()
297 Returns the new ARC headers
298 my $pre_headers = $signer->as_string();
300 The headers are separated by \015\012 (SMTP line separator) including a
302 trailing separator, so can be directly injected in front of the raw
303 message.
304 as_strings()
306 Returns the new ARC headers
307 my @pre_headers = $signer->as_string();
309 The headers are returned as a list so you can add whatever line ending
311 your local MTA prefers.
312
314 • Jason Long <jason@long.name>
315 • Marc Bradshaw <marc@marcbradshaw.net>
317 • Bron Gondwana <brong@fastmailteam.com> (ARC)
319
321 Work on ensuring that this module passes the ARC test suite was
322 generously sponsored by Valimail (https://www.valimail.com/)
323
325 • Copyright (C) 2013 by Messiah College
326 • Copyright (C) 2010 by Jason Long
328 • Copyright (C) 2017 by Standcore LLC
330 • Copyright (C) 2020 by FastMail Pty Ltd
332 This library is free software; you can redistribute it and/or modify it
334 under the same terms as Perl itself, either Perl version 5.8.6 or, at
335 your option, any later version of Perl 5 you may have available.
336perl v5.38.0 2023-07-24 Mail::DKIM::ARC::Signer(3)