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 # create a signer object
12 my $dkim = Mail::DKIM::Signer->new(
13 Algorithm => "rsa-sha1",
14 Method => "relaxed",
15 Domain => "example.org",
16 Selector => "selector1",
17 KeyFile => "private.key",
18 );
19 # read an email from a file handle
21 $dkim->load(*STDIN);
22 # or read an email and pass it into the signer, one line at a time
24 while (<STDIN>)
25 {
26 # remove local line terminators
27 chomp;
28 s/\015$//;
29 # use SMTP line terminators
31 $dkim->PRINT("$_\015\012");
32 }
33 $dkim->CLOSE;
34 # what is the signature result?
36 my $signature = $dkim->signature;
37
39 new()
40 Construct an object-oriented signer.
41 # create a signer using the default policy
43 my $dkim = Mail::DKIM::Signer->new(
44 Algorithm => "rsa-sha1",
45 Method => "relaxed",
46 Domain => "example.org",
47 Selector => "selector1",
48 KeyFile => "private.key",
49 );
50 # create a signer using a custom policy
52 my $dkim = Mail::DKIM::Signer->new(
53 Policy => $policyfn,
54 );
55 The "default policy" is to create a DKIM signature using the specified
57 parameters, but only if the message's sender matches the domain. The
58 following parameters can be passed to this new() method to influence
59 the resulting signature: Algorithm, Method, Domain, Selector, KeyFile,
60 Identity, Timestamp.
61 If you want different behavior, you can provide a "signer policy"
63 instead. A signer policy is a subroutine or class that determines
64 signature parameters after the message's headers have been parsed. See
65 the section "SIGNER POLICIES" below for more information.
66 See Mail::DKIM::SignerPolicy for more information about policy objects.
68 In addition to the parameters demonstrated above, the following are
70 recognized:
71 Key rather than using "KeyFile", use "Key" to use an already-loaded
73 Mail::DKIM::PrivateKey object.
74
76 PRINT()
77 Feed part of the message to the signer.
78 $dkim->PRINT("a line of the message\015\012");
80 Feeds content of the message being signed into the signer. The API is
82 designed this way so that the entire message does NOT need to be read
83 into memory at once.
84 CLOSE()
86 Call this when finished feeding in the message.
87 $dkim->CLOSE;
89 This method finishes the canonicalization process, computes a hash, and
91 generates a signature.
92 add_signature()
94 Used by signer policy to create a new signature.
95 $dkim->add_signature(new Mail::DKIM::Signature(...));
97 Signer policies can use this method to specify complete parameters for
99 the signature to add, including what type of signature. For more
100 information, see Mail::DKIM::SignerPolicy.
101 algorithm()
103 Get or set the selected algorithm.
104 $alg = $dkim->algorithm;
106 $dkim->algorithm("rsa-sha1");
108 domain()
110 Get or set the selected domain.
111 $alg = $dkim->domain;
113 $dkim->domain("example.org");
115 load()
117 Load the entire message from a file handle.
118 $dkim->load($file_handle);
120 Reads a complete message from the designated file handle, feeding it
122 into the signer. The message must use <CRLF> line terminators (same as
123 the SMTP protocol).
124 headers()
126 Determine which headers to put in signature.
127 my $headers = $dkim->headers;
129 This is a string containing the names of the header fields that will be
131 signed, separated by colons.
132 key()
134 Get or set the private key object.
135 my $key = $dkim->key;
137 $dkim->key(Mail::DKIM::PrivateKey->load(File => "private.key"));
139 If you use this method to specify a private key, do not use
141 "key_file()".
142 key_file()
144 Get or set the filename containing the private key.
145 my $filename = $dkim->key_file;
147 $dkim->key_file("private.key");
149 If you use this method to specify a private key file, do not use
151 "key()".
152 method()
154 Get or set the selected canonicalization method.
155 $alg = $dkim->method;
157 $dkim->method("relaxed");
159 message_originator()
161 Access the "From" header.
162 my $address = $dkim->message_originator;
164 Returns the "originator address" found in the message, as a
166 Mail::Address object. This is typically the (first) name and email
167 address found in the From: header. If there is no From: header, then an
168 empty Mail::Address object is returned.
169 To get just the email address part, do:
171 my $email = $dkim->message_originator->address;
173 See also "message_sender()".
175 message_sender()
177 Access the "From" or "Sender" header.
178 my $address = $dkim->message_sender;
180 Returns the "sender" found in the message, as a Mail::Address object.
182 This is typically the (first) name and email address found in the
183 Sender: header. If there is no Sender: header, it is the first name and
184 email address in the From: header. If neither header is present, then
185 an empty Mail::Address object is returned.
186 To get just the email address part, do:
188 my $email = $dkim->message_sender->address;
190 The "sender" is the mailbox of the agent responsible for the actual
192 transmission of the message. For example, if a secretary were to send a
193 message for another person, the "sender" would be the secretary and the
194 "originator" would be the actual author.
195 selector()
197 Get or set the current key selector.
198 $alg = $dkim->selector;
200 $dkim->selector("alpha");
202 signature()
204 Access the generated signature object.
205 my $signature = $dkim->signature;
207 Returns the generated signature. The signature is an object of type
209 Mail::DKIM::Signature. If multiple signatures were generated, this
210 method returns the last one.
211 The signature should be prepended to the message to make the resulting
213 message. At the very least, it should precede any headers that were
214 signed.
215 signatures()
217 Access list of generated signature objects.
218 my @signatures = $dkim->signatures;
220 Returns all generated signatures, as a list.
222
224 The new() constructor takes an optional Policy argument. This can be a
225 Perl object or class with an apply() method, or just a simple
226 subroutine reference. The method/subroutine will be called with the
227 signer object as an argument. The policy is responsible for checking
228 the message and specifying signature parameters. The policy must return
229 a nonzero value to create the signature, otherwise no signature will be
230 created. E.g.,
231 my $policyfn = sub {
233 my $dkim = shift;
234 # specify signature parameters
236 $dkim->algorithm("rsa-sha1");
237 $dkim->method("relaxed");
238 $dkim->domain("example.org");
239 $dkim->selector("mx1");
240 # return true value to create the signature
242 return 1;
243 };
244 Or the policy object can actually create the signature, using the
246 add_signature method within the policy object. If you add a signature,
247 you do not need to return a nonzero value. This mechanism can be
248 utilized to create multiple signatures, or to create the older
249 DomainKey-style signatures.
250 my $policyfn = sub {
252 my $dkim = shift;
253 $dkim->add_signature(
254 new Mail::DKIM::Signature(
255 Algorithm => "rsa-sha1",
256 Method => "relaxed",
257 Headers => $dkim->headers,
258 Domain => "example.org",
259 Selector => "mx1",
260 ));
261 $dkim->add_signature(
262 new Mail::DKIM::DkSignature(
263 Algorithm => "rsa-sha1",
264 Method => "nofws",
265 Headers => $dkim->headers,
266 Domain => "example.org",
267 Selector => "mx1",
268 ));
269 return;
270 };
271 If no policy is specified, the default policy is used. The default
273 policy signs every message using the domain, algorithm, method, and
274 selector specified in the new() constructor.
275
277 Mail::DKIM::SignerPolicy
278
280 Jason Long, <jlong@messiah.edu>
281
283 Copyright (C) 2006-2007 by Messiah College
284 This library is free software; you can redistribute it and/or modify it
286 under the same terms as Perl itself, either Perl version 5.8.6 or, at
287 your option, any later version of Perl 5 you may have available.
288perl v5.10.1 2009-07-30 Mail::DKIM::Signer(3)