1Mail::DKIM::ARC::SignerU(s3e)r Contributed Perl DocumentaMtaiioln::DKIM::ARC::Signer(3)
2
3
4

NAME

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

VERSION

9       version 1.20230630
10

SYNOPSIS

12         use Mail::DKIM::ARC::Signer;
13         use Mail::DKIM::TextWrap;  #recommended
14
15         # 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
26         # read an email from a file handle
27         $signer->load(*STDIN);
28
29         # 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
33         # 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
40             # use SMTP line terminators
41             $signer->PRINT("$_\015\012");
42         }
43         $signer->CLOSE;
44
45         die 'Failed' $signer->result_detail() unless $signer->result() eq 'sealed';
46
47         # 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

DESCRIPTION

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
58       You also need to pass the 'Chain' value (pass or fail) from validation
59       of the previous ARC-Seals on the message.
60
61       Next, you feed it the entire message using "PRINT()", completing with
62       "CLOSE()".
63
64       Finally, use the "as_string()" method to get the new ARC headers.
65
66       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
71       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
75   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
80         use Mail::DKIM::TextWrap;
81
82       in your program before generating the signature.
83

CONSTRUCTOR

85   new()
86       Construct an object-oriented signer.
87
88         # 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
99       Key rather than using "KeyFile", use "Key" to use an already-loaded
100           Mail::DKIM::PrivateKey object.
101
102       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
106       SrvId
107           The authserv-id in the Authentication-Results headers, defaults to
108           Domain.
109
110       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
114           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
118           If you require greater control over signed headers please use the
119           extended_headers() method instead.
120
121           The list of headers signed by default is as follows
122
123               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

METHODS

133   PRINT()
134       Feed part of the message to the signer.
135
136         $signer->PRINT("a line of the message\015\012");
137
138       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
142       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
147   CLOSE()
148       Call this when finished feeding in the message.
149
150         $signer->CLOSE;
151
152       This method finishes the canonicalization process, computes a hash, and
153       generates a signature.
154
155   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
159       The method expects a HashRef to be passed in.
160
161       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
164       * will sign ALL headers of that type present in the message.
165
166       + will sign ALL + 1 headers of that type present in the message to
167       prevent additional headers being added.
168
169       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
172       Keys are case insensitive with the values being added upto the highest
173       value.
174
175           Headers => {
176               'X-test'  => '*',
177               'x-test'  => '1',
178               'Subject' => '+',
179               'Sender'  => 0,
180           },
181
182   add_signature()
183       Used by signer policy to create a new signature.
184
185         $signer->add_signature(new Mail::DKIM::Signature(...));
186
187       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
191   algorithm()
192       Get or set the selected algorithm.
193
194         $alg = $signer->algorithm;
195
196         $signer->algorithm('rsa-sha256');
197
198   domain()
199       Get or set the selected domain.
200
201         $alg = $signer->domain;
202
203         $signer->domain('example.org');
204
205   load()
206       Load the entire message from a file handle.
207
208         $signer->load($file_handle);
209
210       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
214   headers()
215       Determine which headers to put in signature.
216
217         my $headers = $signer->headers;
218
219       This is a string containing the names of the header fields that will be
220       signed, separated by colons.
221
222   key()
223       Get or set the private key object.
224
225         my $key = $signer->key;
226
227         $signer->key(Mail::DKIM::PrivateKey->load(File => 'private.key'));
228
229       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
233       If you use this method to specify a private key, do not use
234       "key_file()".
235
236   key_file()
237       Get or set the filename containing the private key.
238
239         my $filename = $signer->key_file;
240
241         $signer->key_file('private.key');
242
243       If you use this method to specify a private key file, do not use
244       "key()".
245
246   message_originator()
247       Access the "From" header.
248
249         my $address = $signer->message_originator;
250
251       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
256       To get just the email address part, do:
257
258         my $email = $signer->message_originator->address;
259
260       See also "message_sender()".
261
262   message_sender()
263       Access the "From" or "Sender" header.
264
265         my $address = $dkim->message_sender;
266
267       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
273       To get just the email address part, do:
274
275         my $email = $dkim->message_sender->address;
276
277       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
282   selector()
283       Get or set the current key selector.
284
285         $alg = $dkim->selector;
286
287         $dkim->selector('alpha');
288
289   signatures()
290       Access list of generated signature objects.
291
292         my @signatures = $dkim->signatures;
293
294       Returns all generated signatures, as a list.
295
296   as_string()
297       Returns the new ARC headers
298
299         my $pre_headers = $signer->as_string();
300
301       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
305   as_strings()
306       Returns the new ARC headers
307
308         my @pre_headers = $signer->as_string();
309
310       The headers are returned as a list so you can add whatever line ending
311       your local MTA prefers.
312

AUTHORS

314       •   Jason Long <jason@long.name>
315
316       •   Marc Bradshaw <marc@marcbradshaw.net>
317
318       •   Bron Gondwana <brong@fastmailteam.com> (ARC)
319

THANKS

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
327       •   Copyright (C) 2010 by Jason Long
328
329       •   Copyright (C) 2017 by Standcore LLC
330
331       •   Copyright (C) 2020 by FastMail Pty Ltd
332
333       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.
336
337
338
339perl v5.38.0                      2023-07-24        Mail::DKIM::ARC::Signer(3)
Impressum