1Mail::DKIM::Signature(3U)ser Contributed Perl DocumentatiMoanil::DKIM::Signature(3)
2
6 Mail::DKIM::Signature - represents a DKIM-Signature header
7
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 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 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 Note: The input to this constructor is in the same format as the output
34 of the as_string method.
35
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 See also hash_algorithm().
43 as_string() - the signature header as a string
45 print $signature->as_string . "\n";
46 outputs
48 DKIM-Signature: a=rsa-sha1; b=yluiJ7+0=; c=relaxed
50 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 as_string_without_data() - signature without the signature data
55 print $signature->as_string_without_data . "\n";
56 outputs
58 DKIM-Signature: a=rsa-sha1; b=; c=relaxed
60 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 body_count() - get or set the body count (l=) field
67 my $i = $signature->body_count;
68 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 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 body_hash() - get or set the body hash (bh=) field
78 my $bh = $signature->body_hash;
79 The hash of the body part of the message. Whitespace is ignored in this
81 value. This tag is required.
82 When accessing this value, whitespace is stripped from the tag for you.
84 canonicalization() - get or set the canonicalization (c=) field
86 $signature->canonicalization("relaxed", "simple");
87 ($header, $body) = $signature->canonicalization;
89 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 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 data() - get or set the signature data (b=) field
99 my $base64 = $signature->data;
100 $signature->data($base64);
101 The signature data. Whitespace is automatically stripped from the
103 returned value. The data is Base64-encoded.
104 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 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 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 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 get_public_key() - fetches the public key referenced by this signature
123 my $pubkey = $signature->get_public_key;
124 Public key to fetch is determined by the protocol, selector, and domain
126 fields.
127 This method caches the result of the fetch, so subsequent calls will
129 not require additional DNS queries.
130 This method will "die" if an error occurs.
132 get_tag() - access the raw value of a tag in this signature
134 my $raw_identity = $signature->get_tag("i");
135 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 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 hash_algorithm() - access the hash algorithm specified in this signature
146 my $hash = $signature->hash_algorithm;
147 Determines what hashing algorithm is used as part of the signature's
149 specified algorithm.
150 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 headerlist() - get or set the signed header fields (h=) field
156 $signature->headerlist("a:b:c");
157 my $headerlist = $signature->headerlist;
159 my @headers = $signature->headerlist;
161 Signed header fields. A colon-separated list of header field names that
163 identify the header fields presented to the signing algorithm.
164 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 identity() - get or set the signing identity (i=) field
170 my $i = $signature->identity;
171 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 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 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 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 key() - get or set the key object
192 my $key = $signature->key;
193 $signature->key(Mail::DKIM::PrivateKey->load(File => "private.key"));
195 method() - get or set the canonicalization (c=) field
197 Message canonicalization (default is "simple"). This informs the
198 verifier of the type of canonicalization used to prepare the message
199 for signing.
200 protocol() - get or set the query methods (q=) field
202 A colon-separated list of query methods used to retrieve the public key
203 (default is "dns"). Each query method is of the form "type[/options]",
204 where the syntax and semantics of the options depends on the type.
205 result() - get or set the verification result
207 my $result = $signature->result;
208 $signature->result("pass");
210 # to set the result with details
212 $signature->result("invalid", "no public key");
213 result_detail() - access the result, plus details if available
215 my $detail = $signature->result_detail;
216 An explanation of possible detail messages can be found in the
218 documentation for "result_detail" in Mail::DKIM::Verifier.
219 selector() - get or set the selector (s=) field
221 The selector subdivides the namespace for the "d=" (domain) tag.
222 prettify() - alters the signature to look "nicer" as an email header
224 $signature->prettify;
225 This method may alter the signature in a way that breaks signatures, so
227 it should be done ONLY when the signature is being generated, BEFORE
228 being fed to the canonicalization algorithm.
229 See also prettify_safe(), which will not break signatures.
231 prettify_safe() - same as prettify() but only touches the b= part
233 $signature->prettify_safe;
234 This method will not break the signature, but it only affects the b=
236 part of the signature.
237 timestamp() - get or set the signature timestamp (t=) field
239 Signature timestamp (default is undef, meaning unknown creation time).
240 This is the time that the signature was created. The value is an
241 unsigned integer identifying the number of standard Unix
242 seconds-since-1970.
243 version() - get or set the DKIM specification version (v=) field
245 This is the version of the DKIM specification that applies to this
246 signature record.
247
249 Mail::DKIM::DkSignature for DomainKey-Signature headers
250
252 Jason Long, <jlong@messiah.edu>
253
255 Copyright (C) 2006-2007 by Messiah College
256 This library is free software; you can redistribute it and/or modify it
258 under the same terms as Perl itself, either Perl version 5.8.6 or, at
259 your option, any later version of Perl 5 you may have available.
260perl v5.10.1 2009-07-30 Mail::DKIM::Signature(3)