1Mail::DKIM::Signature(3U)ser Contributed Perl DocumentatiMoanil::DKIM::Signature(3)
2
3
4

NAME

6       Mail::DKIM::Signature - represents a DKIM-Signature header
7

CONSTRUCTORS

9   new() - create a new signature from parameters
10         my $signature = Mail::DKIM::Signature->new(
11                             [ Algorithm => "rsa-sha1", ]
12                             [ Signature => $base64, ]
13                             [ Method => "relaxed", ]
14                             [ Domain => "example.org", ]
15                             [ Identity => 'user@example.org', ]
16                             [ Headers => "from:subject:date:message-id", ]
17                             [ Query => "dns", ]
18                             [ Selector => "alpha", ]
19                             [ Timestamp => time(), ]
20                             [ Expiration => time() + 86400, ]
21                         );
22
23   parse() - create a new signature from a DKIM-Signature header
24         my $sig = Mail::DKIM::Signature->parse(
25                         "DKIM-Signature: a=rsa-sha1; b=yluiJ7+0=; c=relaxed"
26                   );
27
28       Constructs a signature by parsing the provided DKIM-Signature header
29       content. You do not have to include the header name (i.e. "DKIM-
30       Signature:") but it is recommended, so the header name can be preserved
31       and returned the same way in as_string().
32
33       Note: The input to this constructor is in the same format as the output
34       of the as_string method.
35

METHODS

37   algorithm() - get or set the algorithm (a=) field
38       The algorithm used to generate the signature. Should be either
39       "rsa-sha1", an RSA-signed SHA-1 digest, or "rsa-sha256", an RSA-signed
40       SHA-256 digest.
41
42       See also hash_algorithm().
43
44   as_string() - the signature header as a string
45         print $signature->as_string . "\n";
46
47       outputs
48
49         DKIM-Signature: a=rsa-sha1; b=yluiJ7+0=; c=relaxed
50
51       As shown in the example, the as_string method can be used to generate
52       the DKIM-Signature that gets prepended to a signed message.
53
54   as_string_without_data() - signature without the signature data
55         print $signature->as_string_without_data . "\n";
56
57       outputs
58
59         DKIM-Signature: a=rsa-sha1; b=; c=relaxed
60
61       This is similar to the as_string() method, but it always excludes the
62       "data" part. This is used by the DKIM canonicalization methods, which
63       require incorporating this part of the signature into the signed
64       message.
65
66   body_count() - get or set the body count (l=) field
67         my $i = $signature->body_count;
68
69       Informs the verifier of the number of bytes in the body of the email
70       included in the cryptographic hash, starting from 0 immediately
71       following the CRLF preceding the body. Also known as the l= tag.
72
73       When creating a signature, this tag may be either omitted, or set after
74       the selected canonicalization system has received the entire message
75       body (but before it canonicalizes the DKIM-Signature).
76
77   body_hash() - get or set the body hash (bh=) field
78         my $bh = $signature->body_hash;
79
80       The hash of the body part of the message. Whitespace is ignored in this
81       value. This tag is required.
82
83       When accessing this value, whitespace is stripped from the tag for you.
84
85   canonicalization() - get or set the canonicalization (c=) field
86         $signature->canonicalization("relaxed", "simple");
87
88         ($header, $body) = $signature->canonicalization;
89
90       Message canonicalization (default is "simple/simple"). This informs the
91       verifier of the type of canonicalization used to prepare the message
92       for signing.
93
94       In scalar context, this returns header/body canonicalization as a
95       single string separated by /. In list context, it returns a two element
96       array, containing first the header canonicalization, then the body.
97
98   data() - get or set the signature data (b=) field
99         my $base64 = $signature->data;
100         $signature->data($base64);
101
102       The signature data. Whitespace is automatically stripped from the
103       returned value. The data is Base64-encoded.
104
105   domain() - get or set the domain (d=) field
106         my $d = $signature->domain;          # gets the domain value
107         $signature->domain("example.org");   # sets the domain value
108
109       The domain of the signing entity, as specified in the signature.  This
110       is the domain that will be queried for the public key.
111
112       If using an "internationalized domain name", the domain name must be
113       converted to ASCII (following section 4.1 of RFC 3490) before passing
114       it to this method.
115
116   expiration() - get or set the signature expiration (x=) field
117       Signature expiration (default is undef, meaning no expiration).  The
118       signature expiration, if defined, is an unsigned integer identifying
119       the standard Unix seconds-since-1970 time when the signature will
120       expire.
121
122   get_public_key() - fetches the public key referenced by this signature
123         my $pubkey = $signature->get_public_key;
124
125       Public key to fetch is determined by the protocol, selector, and domain
126       fields.
127
128       This method caches the result of the fetch, so subsequent calls will
129       not require additional DNS queries.
130
131       This method will "die" if an error occurs.
132
133   get_tag() - access the raw value of a tag in this signature
134         my $raw_identity = $signature->get_tag("i");
135
136       Use this method to access a tag not already supported by Mail::DKIM, or
137       if you want to bypass decoding of the value by Mail::DKIM.
138
139       For example, the raw i= (identity) tag is encoded in quoted-printable
140       form. If you use the identity() method, Mail::DKIM will decode from
141       quoted-printable before returning the value. But if you use
142       get_tag("i"), you can access the encoded quoted-printable form of the
143       value.
144
145   hash_algorithm() - access the hash algorithm specified in this signature
146         my $hash = $signature->hash_algorithm;
147
148       Determines what hashing algorithm is used as part of the signature's
149       specified algorithm.
150
151       For algorithm "rsa-sha1", the hash algorithm is "sha1". Likewise, for
152       algorithm "rsa-sha256", the hash algorithm is "sha256". If the
153       algorithm is not recognized, undef is returned.
154
155   headerlist() - get or set the signed header fields (h=) field
156         $signature->headerlist("a:b:c");
157
158         my $headerlist = $signature->headerlist;
159
160         my @headers = $signature->headerlist;
161
162       Signed header fields. A colon-separated list of header field names that
163       identify the header fields presented to the signing algorithm.
164
165       In scalar context, the list of header field names will be returned as a
166       single string, with the names joined together with colons.  In list
167       context, the header field names will be returned as a list.
168
169   identity() - get or set the signing identity (i=) field
170         my $i = $signature->identity;
171
172       Identity of the user or agent on behalf of which this message is
173       signed.  The identity has an optional local part, followed by "@", then
174       a domain name. The domain name should be the same as or a subdomain of
175       the domain returned by the "domain" method.
176
177       Ideally, the identity should match the identity listed in the From:
178       header, or the Sender: header, but this is not required to have a valid
179       signature. Whether the identity used is "authorized" to sign for the
180       given message is not determined here.
181
182       If using an "internationalized domain name", the domain name must be
183       converted to ASCII (following section 4.1 of RFC 3490) before passing
184       it to this method.
185
186       Identity values are encoded in the signature in quoted-printable
187       format.  Using this method will translate to/from quoted-printable as
188       necessary.  If you want the raw quoted-printable version of the
189       identity, use $signature->get_tag("i").
190
191   key() - get or set the private key object
192         my $key = $signature->key;
193
194         $signature->key(Mail::DKIM::PrivateKey->load(File => "private.key"));
195
196       The private key is used for signing messages.  It is not used for
197       verifying messages.
198
199       The key object can be any object that implements the sign_digest()
200       method.  (Providing your own object can be useful if your actual keys
201       are stored out-of-process.)
202
203   method() - get or set the canonicalization (c=) field
204       Message canonicalization (default is "simple"). This informs the
205       verifier of the type of canonicalization used to prepare the message
206       for signing.
207
208   protocol() - get or set the query methods (q=) field
209       A colon-separated list of query methods used to retrieve the public key
210       (default is "dns"). Each query method is of the form "type[/options]",
211       where the syntax and semantics of the options depends on the type.
212
213   result() - get or set the verification result
214         my $result = $signature->result;
215
216         $signature->result("pass");
217
218         # to set the result with details
219         $signature->result("invalid", "no public key");
220
221   result_detail() - access the result, plus details if available
222         my $detail = $signature->result_detail;
223
224       An explanation of possible detail messages can be found in the
225       documentation for "result_detail()" in Mail::DKIM::Verifier.
226
227   selector() - get or set the selector (s=) field
228       The selector subdivides the namespace for the "d=" (domain) tag.
229
230   prettify() - alters the signature to look "nicer" as an email header
231         $signature->prettify;
232
233       This method may alter the signature in a way that breaks signatures, so
234       it should be done ONLY when the signature is being generated, BEFORE
235       being fed to the canonicalization algorithm.
236
237       See also prettify_safe(), which will not break signatures.
238
239   prettify_safe() - same as prettify() but only touches the b= part
240         $signature->prettify_safe;
241
242       This method will not break the signature, but it only affects the b=
243       part of the signature.
244
245   timestamp() - get or set the signature timestamp (t=) field
246       Signature timestamp (default is undef, meaning unknown creation time).
247       This is the time that the signature was created. The value is an
248       unsigned integer identifying the number of standard Unix
249       seconds-since-1970.
250
251   version() - get or set the DKIM specification version (v=) field
252       This is the version of the DKIM specification that applies to this
253       signature record.
254

SEE ALSO

256       Mail::DKIM::DkSignature for DomainKey-Signature headers
257

AUTHOR

259       Jason Long, <jlong@messiah.edu>
260
262       Copyright (C) 2006-2007 by Messiah College
263
264       This library is free software; you can redistribute it and/or modify it
265       under the same terms as Perl itself, either Perl version 5.8.6 or, at
266       your option, any later version of Perl 5 you may have available.
267
268
269
270perl v5.16.3                      2010-11-14          Mail::DKIM::Signature(3)
Impressum