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

SYNOPSIS

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

DESCRIPTION

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

CONSTRUCTOR

59   new()
60       Construct an object-oriented signer.
61
62         # create a signer using the default policy
63         my $dkim = Mail::DKIM::Signer->new(
64                         Algorithm => "rsa-sha1",
65                         Method => "relaxed",
66                         Domain => "example.org",
67                         Selector => "selector1",
68                         KeyFile => "private.key",
69                    );
70
71         # create a signer using a custom policy
72         my $dkim = Mail::DKIM::Signer->new(
73                         Policy => $policyfn,
74                    );
75
76       The "default policy" is to create a DKIM signature using the specified
77       parameters, but only if the message's sender matches the domain.  The
78       following parameters can be passed to this new() method to influence
79       the resulting signature: Algorithm, Method, Domain, Selector, KeyFile,
80       Identity, Timestamp.
81
82       If you want different behavior, you can provide a "signer policy"
83       instead. A signer policy is a subroutine or class that determines
84       signature parameters after the message's headers have been parsed.  See
85       the section "SIGNER POLICIES" below for more information.
86
87       See Mail::DKIM::SignerPolicy for more information about policy objects.
88
89       In addition to the parameters demonstrated above, the following are
90       recognized:
91
92       Key rather than using "KeyFile", use "Key" to use an already-loaded
93           Mail::DKIM::PrivateKey object.
94

METHODS

96   PRINT()
97       Feed part of the message to the signer.
98
99         $dkim->PRINT("a line of the message\015\012");
100
101       Feeds content of the message being signed into the signer.  The API is
102       designed this way so that the entire message does NOT need to be read
103       into memory at once.
104
105       Please note that although the PRINT() method expects you to use SMTP-
106       style line termination characters, you should NOT use the SMTP-style
107       dot-stuffing technique described in RFC 2821 section 4.5.2.  Nor should
108       you use a <CR><LF>.<CR><LF> sequence to terminate the message.
109
110   CLOSE()
111       Call this when finished feeding in the message.
112
113         $dkim->CLOSE;
114
115       This method finishes the canonicalization process, computes a hash, and
116       generates a signature.
117
118   add_signature()
119       Used by signer policy to create a new signature.
120
121         $dkim->add_signature(new Mail::DKIM::Signature(...));
122
123       Signer policies can use this method to specify complete parameters for
124       the signature to add, including what type of signature. For more
125       information, see Mail::DKIM::SignerPolicy.
126
127   algorithm()
128       Get or set the selected algorithm.
129
130         $alg = $dkim->algorithm;
131
132         $dkim->algorithm("rsa-sha1");
133
134   domain()
135       Get or set the selected domain.
136
137         $alg = $dkim->domain;
138
139         $dkim->domain("example.org");
140
141   load()
142       Load the entire message from a file handle.
143
144         $dkim->load($file_handle);
145
146       Reads a complete message from the designated file handle, feeding it
147       into the signer.  The message must use <CRLF> line terminators (same as
148       the SMTP protocol).
149
150   headers()
151       Determine which headers to put in signature.
152
153         my $headers = $dkim->headers;
154
155       This is a string containing the names of the header fields that will be
156       signed, separated by colons.
157
158   key()
159       Get or set the private key object.
160
161         my $key = $dkim->key;
162
163         $dkim->key(Mail::DKIM::PrivateKey->load(File => "private.key"));
164
165       The key object can be any object that implements the sign_digest()
166       method.  (Providing your own object can be useful if your actual keys
167       are stored out-of-process.)
168
169       If you use this method to specify a private key, do not use
170       "key_file()".
171
172   key_file()
173       Get or set the filename containing the private key.
174
175         my $filename = $dkim->key_file;
176
177         $dkim->key_file("private.key");
178
179       If you use this method to specify a private key file, do not use
180       "key()".
181
182   method()
183       Get or set the selected canonicalization method.
184
185         $alg = $dkim->method;
186
187         $dkim->method("relaxed");
188
189   message_originator()
190       Access the "From" header.
191
192         my $address = $dkim->message_originator;
193
194       Returns the "originator address" found in the message, as a
195       Mail::Address object.  This is typically the (first) name and email
196       address found in the From: header. If there is no From: header, then an
197       empty Mail::Address object is returned.
198
199       To get just the email address part, do:
200
201         my $email = $dkim->message_originator->address;
202
203       See also "message_sender()".
204
205   message_sender()
206       Access the "From" or "Sender" header.
207
208         my $address = $dkim->message_sender;
209
210       Returns the "sender" found in the message, as a Mail::Address object.
211       This is typically the (first) name and email address found in the
212       Sender: header. If there is no Sender: header, it is the first name and
213       email address in the From: header. If neither header is present, then
214       an empty Mail::Address object is returned.
215
216       To get just the email address part, do:
217
218         my $email = $dkim->message_sender->address;
219
220       The "sender" is the mailbox of the agent responsible for the actual
221       transmission of the message. For example, if a secretary were to send a
222       message for another person, the "sender" would be the secretary and the
223       "originator" would be the actual author.
224
225   selector()
226       Get or set the current key selector.
227
228         $alg = $dkim->selector;
229
230         $dkim->selector("alpha");
231
232   signature()
233       Access the generated signature object.
234
235         my $signature = $dkim->signature;
236
237       Returns the generated signature. The signature is an object of type
238       Mail::DKIM::Signature. If multiple signatures were generated, this
239       method returns the last one.
240
241       The signature (as text) should be prepended to the message to make the
242       resulting message. At the very least, it should precede any headers
243       that were signed.
244
245   signatures()
246       Access list of generated signature objects.
247
248         my @signatures = $dkim->signatures;
249
250       Returns all generated signatures, as a list.
251

SIGNER POLICIES

253       The new() constructor takes an optional Policy argument. This can be a
254       Perl object or class with an apply() method, or just a simple
255       subroutine reference. The method/subroutine will be called with the
256       signer object as an argument. The policy is responsible for checking
257       the message and specifying signature parameters. The policy must return
258       a nonzero value to create the signature, otherwise no signature will be
259       created. E.g.,
260
261         my $policyfn = sub {
262             my $dkim = shift;
263
264             # specify signature parameters
265             $dkim->algorithm("rsa-sha1");
266             $dkim->method("relaxed");
267             $dkim->domain("example.org");
268             $dkim->selector("mx1");
269
270             # return true value to create the signature
271             return 1;
272         };
273
274       Or the policy object can actually create the signature, using the
275       add_signature method within the policy object.  If you add a signature,
276       you do not need to return a nonzero value.  This mechanism can be
277       utilized to create multiple signatures, or to create the older
278       DomainKey-style signatures.
279
280         my $policyfn = sub {
281             my $dkim = shift;
282             $dkim->add_signature(
283                     new Mail::DKIM::Signature(
284                             Algorithm => "rsa-sha1",
285                             Method => "relaxed",
286                             Headers => $dkim->headers,
287                             Domain => "example.org",
288                             Selector => "mx1",
289                     ));
290             $dkim->add_signature(
291                     new Mail::DKIM::DkSignature(
292                             Algorithm => "rsa-sha1",
293                             Method => "nofws",
294                             Headers => $dkim->headers,
295                             Domain => "example.org",
296                             Selector => "mx1",
297                     ));
298             return;
299         };
300
301       If no policy is specified, the default policy is used. The default
302       policy signs every message using the domain, algorithm, method, and
303       selector specified in the new() constructor.
304

SEE ALSO

306       Mail::DKIM::SignerPolicy
307

AUTHOR

309       Jason Long, <jlong@messiah.edu>
310
312       Copyright (C) 2006-2007 by Messiah College
313
314       This library is free software; you can redistribute it and/or modify it
315       under the same terms as Perl itself, either Perl version 5.8.6 or, at
316       your option, any later version of Perl 5 you may have available.
317
318
319
320perl v5.12.2                      2010-11-14             Mail::DKIM::Signer(3)
Impressum