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

SYNOPSIS

9         use Mail::DKIM::ARC::Signer;
10         use Mail::DKIM::TextWrap;  #recommended
11
12         # create a signer object
13         my $signer = Mail::DKIM::ARC::Signer->new(
14                         Algorithm => 'rsa-sha256',
15                         Chain => 'none',    # or pass|fail|ar
16                         Domain => 'example.org',
17                         SrvId => 'example.org',
18                         Selector => 'selector1',
19                         KeyFile => 'private.key',
20                         Headers => 'x-header:x-header2',
21                    );
22
23         # read an email from a file handle
24         $signer->load(*STDIN);
25
26         # NOTE: any email being ARC signed must have an Authentication-Results
27         # header so that the ARC seal can cover those results copied into
28         # an ARC-Authentication-Results header.
29
30         # or read an email and pass it into the signer, one line at a time
31         while (<STDIN>)
32         {
33             # remove local line terminators
34             chomp;
35             s/\015$//;
36
37             # use SMTP line terminators
38             $signer->PRINT("$_\015\012");
39         }
40         $signer->CLOSE;
41
42         die 'Failed' $signer->result_details() unless $signer->result() eq 'sealed';
43
44         # Get all the signature headers to prepend to the message
45         # ARC-Seal, ARC-Message-Signature and ARC-Authentication-Results
46         # in that order.
47         print $signer->as_string;
48

DESCRIPTION

50       This class is the part of Mail::DKIM responsible for generating ARC
51       Seals for a given message. You create an object of this class,
52       specifying the parameters for the ARC-Message-Signature you wish to
53       create.
54
55       You also need to pass the 'Chain' value (pass or fail) from validation
56       of the previous ARC-Seals on the message.
57
58       Next, you feed it the entire message using "PRINT()", completing with
59       "CLOSE()".
60
61       Finally, use the "as_string()" method to get the new ARC headers.
62
63       Note: you can only seal a message which has already had an
64       Authentication-Results header added, either by using "PRINT()" to pre-
65       feed it into this module, or by adding a message which has already been
66       authenticated by your inbound scanning mechanisms.
67
68       It is not necessary to ARC-Seal a message which already has DKIM
69       signatures if you are not modifying the message and hence breaking the
70       existing DKIM-Signature or top ARC-Message-Signature on the email.
71
72   Pretty Signatures
73       Mail::DKIM includes a signature-wrapping module (which inserts
74       linebreaks into the generated signature so that it looks nicer in the
75       resulting message. To enable this module, simply call
76
77         use Mail::DKIM::TextWrap;
78
79       in your program before generating the signature.
80

CONSTRUCTOR

82   new()
83       Construct an object-oriented signer.
84
85         # create a signer using the default policy
86         my $signer = Mail::DKIM::ARC::Signer->new(
87                         Algorithm => 'rsa-sha256',
88                         Chain => 'none',    # or pass|fail|ar
89                         Domain => 'example.org',
90                         SrvId => 'example.org',
91                         Selector => 'selector1',
92                         KeyFile => 'private.key',
93                         Headers => 'x-header:x-header2',
94                    );
95
96       Key rather than using "KeyFile", use "Key" to use an already-loaded
97           Mail::DKIM::PrivateKey object.
98
99       Chain
100           The cv= value for the Arc-Seal header.  "ar" means to copy it from
101           an Authentication-Results header, or use none if there isn't one.
102
103       SrvId
104           The authserv-id in the Authentication-Results headers, defaults to
105           Domain.
106
107       Headers
108           A colon separated list of headers to sign, this is added to the
109           list of default headers as shown in in the DKIM specification.
110
111           For each specified header all headers of that type which are
112           present in the message will be signed, but we will not oversign or
113           sign headers which are not present.
114
115           If you require greater control over signed headers please use the
116           extended_headers() method instead.
117
118           The list of headers signed by default is as follows
119
120               From Sender Reply-To Subject Date
121               Message-ID To Cc MIME-Version
122               Content-Type Content-Transfer-Encoding Content-ID Content-Description
123               Resent-Date Resent-From Resent-Sender Resent-To Resent-cc
124               Resent-Message-ID
125               In-Reply-To References
126               List-Id List-Help List-Unsubscribe List-Subscribe
127               List-Post List-Owner List-Archive
128

METHODS

130   PRINT()
131       Feed part of the message to the signer.
132
133         $signer->PRINT("a line of the message\015\012");
134
135       Feeds content of the message being signed into the signer.  The API is
136       designed this way so that the entire message does NOT need to be read
137       into memory at once.
138
139       Please note that although the PRINT() method expects you to use SMTP-
140       style line termination characters, you should NOT use the SMTP-style
141       dot-stuffing technique described in RFC 2821 section 4.5.2.  Nor should
142       you use a <CR><LF>.<CR><LF> sequence to terminate the message.
143
144   CLOSE()
145       Call this when finished feeding in the message.
146
147         $signer->CLOSE;
148
149       This method finishes the canonicalization process, computes a hash, and
150       generates a signature.
151
152   extended_headers()
153       This method overrides the headers to be signed and allows more control
154       than is possible with the Headers property in the constructor.
155
156       The method expects a HashRef to be passed in.
157
158       The Keys are the headers to sign, and the values are either the number
159       of headers of that type to sign, or the special values '*' and '+'.
160
161       * will sign ALL headers of that type present in the message.
162
163       + will sign ALL + 1 headers of that type present in the message to
164       prevent additional headers being added.
165
166       You may override any of the default headers by including them in the
167       hashref, and disable them by giving them a 0 value.
168
169       Keys are case insensitive with the values being added upto the highest
170       value.
171
172           Headers => {
173               'X-test'  => '*',
174               'x-test'  => '1',
175               'Subject' => '+',
176               'Sender'  => 0,
177           },
178
179   add_signature()
180       Used by signer policy to create a new signature.
181
182         $signer->add_signature(new Mail::DKIM::Signature(...));
183
184       Signer policies can use this method to specify complete parameters for
185       the signature to add, including what type of signature. For more
186       information, see Mail::DKIM::SignerPolicy.
187
188   algorithm()
189       Get or set the selected algorithm.
190
191         $alg = $signer->algorithm;
192
193         $signer->algorithm('rsa-sha256');
194
195   domain()
196       Get or set the selected domain.
197
198         $alg = $signer->domain;
199
200         $signer->domain('example.org');
201
202   load()
203       Load the entire message from a file handle.
204
205         $signer->load($file_handle);
206
207       Reads a complete message from the designated file handle, feeding it
208       into the signer.  The message must use <CRLF> line terminators (same as
209       the SMTP protocol).
210
211   headers()
212       Determine which headers to put in signature.
213
214         my $headers = $signer->headers;
215
216       This is a string containing the names of the header fields that will be
217       signed, separated by colons.
218
219   key()
220       Get or set the private key object.
221
222         my $key = $signer->key;
223
224         $signer->key(Mail::DKIM::PrivateKey->load(File => 'private.key'));
225
226       The key object can be any object that implements the sign_digest()
227       method.  (Providing your own object can be useful if your actual keys
228       are stored out-of-process.)
229
230       If you use this method to specify a private key, do not use
231       "key_file()".
232
233   key_file()
234       Get or set the filename containing the private key.
235
236         my $filename = $signer->key_file;
237
238         $signer->key_file('private.key');
239
240       If you use this method to specify a private key file, do not use
241       "key()".
242
243   message_originator()
244       Access the "From" header.
245
246         my $address = $signer->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 = $signer->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   signatures()
287       Access list of generated signature objects.
288
289         my @signatures = $dkim->signatures;
290
291       Returns all generated signatures, as a list.
292
293   as_string()
294       Returns the new ARC headers
295
296         my $pre_headers = $signer->as_string();
297
298       The headers are separated by \015\012 (SMTP line separator) including a
299       trailing separator, so can be directly injected in front of the raw
300       message.
301
302   as_strings()
303       Returns the new ARC headers
304
305         my @pre_headers = $signer->as_string();
306
307       The headers are returned as a list so you can add whatever line ending
308       your local MTA prefers.
309

AUTHOR

311       Bron Gondwana, <brong@fastmailteam.com>
312

314       Copyright (C) 2017 FastMail Pty Ltd
315
316       This library is free software; you can redistribute it and/or modify it
317       under the same terms as Perl itself, either Perl version 5.8.6 or, at
318       your option, any later version of Perl 5 you may have available.
319
320
321
322perl v5.28.1                      2018-10-13        Mail::DKIM::ARC::Signer(3)
Impressum