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 use Mail::DKIM::Signer;
10 use Mail::DKIM::TextWrap; #recommended
11 # 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 # read an email from a file handle
22 $dkim->load(*STDIN);
23 # 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 # use SMTP line terminators
32 $dkim->PRINT("$_\015\012");
33 }
34 $dkim->CLOSE;
35 # what is the signature result?
37 my $signature = $dkim->signature;
38 print $signature->as_string;
39
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 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 use Mail::DKIM::TextWrap;
55 in your program before generating the signature.
57
59 new()
60 Construct an object-oriented signer.
61 # 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 # create a signer using a custom policy
72 my $dkim = Mail::DKIM::Signer->new(
73 Policy => $policyfn,
74 );
75 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 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 See Mail::DKIM::SignerPolicy for more information about policy objects.
88 In addition to the parameters demonstrated above, the following are
90 recognized:
91 Key rather than using "KeyFile", use "Key" to use an already-loaded
93 Mail::DKIM::PrivateKey object.
94
96 PRINT()
97 Feed part of the message to the signer.
98 $dkim->PRINT("a line of the message\015\012");
100 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 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 CLOSE()
111 Call this when finished feeding in the message.
112 $dkim->CLOSE;
114 This method finishes the canonicalization process, computes a hash, and
116 generates a signature.
117 add_signature()
119 Used by signer policy to create a new signature.
120 $dkim->add_signature(new Mail::DKIM::Signature(...));
122 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 algorithm()
128 Get or set the selected algorithm.
129 $alg = $dkim->algorithm;
131 $dkim->algorithm("rsa-sha1");
133 domain()
135 Get or set the selected domain.
136 $alg = $dkim->domain;
138 $dkim->domain("example.org");
140 load()
142 Load the entire message from a file handle.
143 $dkim->load($file_handle);
145 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 headers()
151 Determine which headers to put in signature.
152 my $headers = $dkim->headers;
154 This is a string containing the names of the header fields that will be
156 signed, separated by colons.
157 key()
159 Get or set the private key object.
160 my $key = $dkim->key;
162 $dkim->key(Mail::DKIM::PrivateKey->load(File => "private.key"));
164 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 If you use this method to specify a private key, do not use
170 "key_file()".
171 key_file()
173 Get or set the filename containing the private key.
174 my $filename = $dkim->key_file;
176 $dkim->key_file("private.key");
178 If you use this method to specify a private key file, do not use
180 "key()".
181 method()
183 Get or set the selected canonicalization method.
184 $alg = $dkim->method;
186 $dkim->method("relaxed");
188 message_originator()
190 Access the "From" header.
191 my $address = $dkim->message_originator;
193 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 To get just the email address part, do:
200 my $email = $dkim->message_originator->address;
202 See also "message_sender()".
204 message_sender()
206 Access the "From" or "Sender" header.
207 my $address = $dkim->message_sender;
209 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 To get just the email address part, do:
217 my $email = $dkim->message_sender->address;
219 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 selector()
226 Get or set the current key selector.
227 $alg = $dkim->selector;
229 $dkim->selector("alpha");
231 signature()
233 Access the generated signature object.
234 my $signature = $dkim->signature;
236 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 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 signatures()
246 Access list of generated signature objects.
247 my @signatures = $dkim->signatures;
249 Returns all generated signatures, as a list.
251
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 my $policyfn = sub {
262 my $dkim = shift;
263 # specify signature parameters
265 $dkim->algorithm("rsa-sha1");
266 $dkim->method("relaxed");
267 $dkim->domain("example.org");
268 $dkim->selector("mx1");
269 # return true value to create the signature
271 return 1;
272 };
273 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 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 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
306 Mail::DKIM::SignerPolicy
307
309 Jason Long, <jlong@messiah.edu>
310
312 Copyright (C) 2006-2007 by Messiah College
313 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.
317perl v5.12.2 2010-11-14 Mail::DKIM::Signer(3)