1AnyEvent::TLS(3) User Contributed Perl Documentation AnyEvent::TLS(3)
2
6 AnyEvent::TLS - SSLv2/SSLv3/TLSv1 contexts for use in AnyEvent::Handle
7
9 # via AnyEvent::Handle
10 use AnyEvent;
12 use AnyEvent::Handle;
13 use AnyEvent::Socket;
14 # simple https-client
16 my $handle = new AnyEvent::Handle
17 connect => [$host, $port],
18 tls => "connect",
19 tls_ctx => { verify => 1, verify_peername => "https" },
20 ...
21 # simple ssl-server
23 tcp_server undef, $port, sub {
24 my ($fh) = @_;
25 my $handle = new AnyEvent::Handle
27 fh => $fh,
28 tls => "accept",
29 tls_ctx => { cert_file => "my-server-keycert.pem" },
30 ...
31 # directly
33 my $tls = new AnyEvent::TLS
35 verify => 1,
36 verify_peername => "ldaps",
37 ca_file => "/etc/cacertificates.pem";
38
40 This module is a helper module that implements TLS/SSL (Transport Layer
41 Security/Secure Sockets Layer) contexts. A TLS context is a common set
42 of configuration values for use in establishing TLS connections.
43 For some quick facts about SSL/TLS, see the section of the same name
45 near the end of the document.
46 A single TLS context can be used for any number of TLS connections that
48 wish to use the same certificates, policies etc.
49 Note that this module is inherently tied to Net::SSLeay, as this
51 library is used to implement it. Since that perl module is rather ugly,
52 and OpenSSL has a rather ugly license, AnyEvent might switch TLS
53 providers at some future point, at which this API will change
54 dramatically, at least in the Net::SSLeay-specific parts (most
55 constructor arguments should still work, though).
56 Although this module does not require a specific version of
58 Net::SSLeay, many features will gradually stop working, or bugs will be
59 introduced with old versions (verification might succeed when it
60 shouldn't - this is a real security issue). Version 1.35 is
61 recommended, 1.33 should work, 1.32 might, and older versions are yours
62 to keep.
63
65 See the AnyEvent::Handle manpage, NONFREQUENTLY ASKED QUESTIONS, for
66 some actual usage examples.
67
69 $tls = new AnyEvent::TLS key => value...
70 The constructor supports these arguments (all as key => value
71 pairs).
72 method => "SSLv2" | "SSLv3" | "TLSv1" | "any"
74 The protocol parser to use. "SSLv2", "SSLv3" and "TLSv1" will
75 use a parser for those protocols only (so will not accept or
76 create connections with/to other protocol versions), while
77 "any" (the default) uses a parser capable of all three
78 protocols.
79 The default is to use "any" but disable SSLv2. This has the
81 effect of sending a SSLv2 hello, indicating the support for
82 SSLv3 and TLSv1, but not actually negotiating an (insecure)
83 SSLv2 connection.
84 Specifying a specific version is almost always wrong to use for
86 a server speaking to a wide variety of clients (e.g. web
87 browsers), and often wrong for a client. If you only want to
88 allow a specific protocol version, use the "sslv2", "sslv3" or
89 "tlsv1" arguments instead.
90 For new services it is usually a good idea to enforce a "TLSv1"
92 method from the beginning.
93 sslv2 => $enabled
95 Enable or disable SSLv2 (normally disabled).
96 sslv3 => $enabled
98 Enable or disable SSLv3 (normally enabled).
99 tlsv1 => $enabled
101 Enable or disable TLSv1 (normally enabled).
102 verify => $enable
104 Enable or disable peer certificate checking (default is
105 disabled, which is not recommended).
106 This is the "master switch" for all verify-related parameters
108 and functions.
109 If it is disabled, then no peer certificate verification will
111 be done - the connection will be encrypted, but the peer
112 certificate won't be verified against any known CAs, or whether
113 it is still valid or not. No peername verification or custom
114 verification will be done either.
115 If enabled, then the peer certificate (required in client mode,
117 optional in server mode, see "verify_require_client_cert") will
118 be checked against its CA certificate chain - that means there
119 must be a signing chain from the peer certificate to any of the
120 CA certificates you trust locally, as specified by the
121 "ca_file" and/or "ca_path" and/or "ca_cert" parameters (or the
122 system default CA repository, if all of those parameters are
123 missing - see also the AnyEvent manpage for the description of
124 PERL_ANYEVENT_CA_FILE).
125 Other basic checks, such as checking the validity period, will
127 also be done, as well as optional peername/hostname/common name
128 verification "verify_peername".
129 An optional "verify_cb" callback can also be set, which will be
131 invoked with the verification results, and which can override
132 the decision.
133 verify_require_client_cert => $enable
135 Enable or disable mandatory client certificates (default is
136 disabled). When this mode is enabled, then a client certificate
137 will be required in server mode (a server certificate is
138 mandatory, so in client mode, this switch has no effect).
139 verify_peername => $scheme | $callback->($tls, $cert, $peername)
141 TLS only protects the data that is sent - it cannot
142 automatically verify that you are really talking to the right
143 peer. The reason is that certificates contain a "common name"
144 (and a set of possible alternative "names") that need to be
145 checked against the peername (usually, but not always, the DNS
146 name of the server) in a protocol-dependent way.
147 This can be implemented by specifying a callback that has to
149 verify that the actual $peername matches the given certificate
150 in $cert.
151 Since this can be rather hard to implement, AnyEvent::TLS
153 offers a variety of predefined "schemes" (lifted from
154 IO::Socket::SSL) that are named like the protocols that use
155 them:
156 ldap (rfc4513), pop3,imap,acap (rfc2995), nntp (rfc4642)
158 Simple wildcards in subjectAltNames are possible, e.g.
159 *.example.org matches www.example.org but not
160 lala.www.example.org. If nothing from subjectAltNames
161 matches, it checks against the common name, but there are
162 no wildcards allowed.
163 http (rfc2818)
165 Extended wildcards in subjectAltNames are possible, e.g.
166 *.example.org or even www*.example.org. Wildcards in the
167 common name are not allowed. The common name will be only
168 checked if no host names are given in subjectAltNames.
169 smtp (rfc3207)
171 This RFC isn't very useful in determining how to do
172 verification so it just assumes that subjectAltNames are
173 possible, but no wildcards are possible anywhere.
174 [$check_cn, $wildcards_in_alt, $wildcards_in_cn]
176 You can also specify a scheme yourself by using an array
177 reference with three integers.
178 $check_cn specifies if and how the common name field is
180 used: 0 means it will be completely ignored, 1 means it
181 will only be used if no host names have been found in the
182 subjectAltNames, and 2 means the common name will always be
183 checked against the peername.
184 $wildcards_in_alt and $wildcards_in_cn specify whether and
186 where wildcards ("*") are allowed in subjectAltNames and
187 the common name, respectively. 0 means no wildcards are
188 allowed, 1 means they are allowed only as the first
189 component ("*.example.org"), and 2 means they can be used
190 anywhere ("www*.example.org"), except that very dangerous
191 matches will not be allowed ("*.org" or "*").
192 You can specify either the name of the parent protocol
194 (recommended, e.g. "http", "ldap"), the protocol name as
195 usually used in URIs (e.g. "https", "ldaps") or the RFC (not
196 recommended, e.g. "rfc2995", "rfc3920").
197 This verification will only be done when verification is
199 enabled ("verify => 1").
200 verify_cb => $callback->($tls, $ref, $cn, $depth, $preverify_ok,
202 $x509_store_ctx, $cert)
203 Provide a custom peer verification callback used by TLS
204 sessions, which is called with the result of any other
205 verification ("verify", "verify_peername").
206 This callback will only be called when verification is enabled
208 ("verify => 1").
209 $tls is the "AnyEvent::TLS" object associated with the session,
211 while $ref is whatever the user associated with the session
212 (usually an AnyEvent::Handle object when used by
213 AnyEvent::Handle).
214 $depth is the current verification depth - "$depth = 0" means
216 the certificate to verify is the peer certificate, higher
217 levels are its CA certificate and so on. In most cases, you can
218 just return $preverify_ok if the $depth is non-zero:
219 verify_cb => sub {
221 my ($tls, $ref, $cn, $depth, $preverify_ok, $x509_store_ctx, $cert) = @_;
222 return $preverify_ok
224 if $depth;
225 # more verification
227 },
228 $preverify_ok is true iff the basic verification of the
230 certificates was successful (a valid CA chain must exist, the
231 certificate has passed basic validity checks, peername
232 verification succeeded).
233 $x509_store_ctx is the Net::SSLeay::X509_CTX> object.
235 $cert is the "Net::SSLeay::X509" object representing the peer
237 certificate, or zero if there was an error. You can call
238 "AnyEvent::TLS::certname $cert" to get a nice user-readable
239 string to identify the certificate.
240 The callback must return either 0 to indicate failure, or 1 to
242 indicate success.
243 verify_client_once => $enable
245 Enable or disable skipping the client certificate verification
246 on renegotiations (default is disabled, the certificate will
247 always be checked). Only makes sense in server mode.
248 ca_file => $path
250 If this parameter is specified and non-empty, it will be the
251 path to a file with (server) CA certificates in PEM format that
252 will be loaded. Each certificate will look like:
253 -----BEGIN CERTIFICATE-----
255 ... (CA certificate in base64 encoding) ...
256 -----END CERTIFICATE-----
257 You have to enable verify mode ("verify => 1") for this
259 parameter to have any effect.
260 ca_path => $path
262 If this parameter is specified and non-empty, it will be the
263 path to a directory with hashed CA certificate files in PEM
264 format. When the ca certificate is being verified, the
265 certificate will be hashed and looked up in that directory (see
266 <http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html>
267 for details)
268 The certificates specified via "ca_file" take precedence over
270 the ones found in "ca_path".
271 You have to enable verify mode ("verify => 1") for this
273 parameter to have any effect.
274 ca_cert => $string
276 In addition or instead of using "ca_file" and/or "ca_path", you
277 can also use "ca_cert" to directly specify the CA certificates
278 (there can be multiple) in PEM format, in a string.
279 check_crl => $enable
281 Enable or disable certificate revocation list checking. If
282 enabled, then peer certificates will be checked against a list
283 of revoked certificates issued by the CA. The revocation lists
284 will be expected in the "ca_path" directory.
285 certificate verification will fail if this is enabled but no
287 revocation list was found.
288 This requires OpenSSL >= 0.9.7b. Check the OpenSSL
290 documentation for more details.
291 key_file => $path
293 Path to the local private key file in PEM format (might be a
294 combined certificate/private key file).
295 The local certificate is used to authenticate against the peer
297 - servers mandatorily need a certificate and key, clients can
298 use a certificate and key optionally to authenticate, e.g. for
299 log-in purposes.
300 The key in the file should look similar this:
302 -----BEGIN RSA PRIVATE KEY-----
304 ...header data
305 ... (key data in base64 encoding) ...
306 -----END RSA PRIVATE KEY-----
307 key => $string
309 The private key string in PEM format (see "key_file", only one
310 of "key_file" or "key" can be specified).
311 The idea behind being able to specify a string is to avoid
313 blocking in I/O. Unfortunately, Net::SSLeay fails to implement
314 any interface to the needed OpenSSL functionality, this is
315 currently implemented by writing to a temporary file.
316 cert_file => $path
318 The path to the local certificate file in PEM format (might be
319 a combined certificate/private key file, including chained
320 certificates).
321 The local certificate (and key) are used to authenticate
323 against the peer - servers mandatorily need a certificate and
324 key, clients can use certificate and key optionally to
325 authenticate, e.g. for log-in purposes.
326 The certificate in the file should look like this:
328 -----BEGIN CERTIFICATE-----
330 ... (certificate in base64 encoding) ...
331 -----END CERTIFICATE-----
332 If the certificate file or string contain both the certificate
334 and private key, then there is no need to specify a separate
335 "key_file" or "key".
336 Additional signing certifiates to send to the peer (in SSLv3
338 and newer) can be specified by appending them to the
339 certificate proper: the order must be from issuer certificate
340 over any intermediate CA certificates to the root CA.
341 So the recommended ordering for a combined key/cert/chain file,
343 specified via "cert_file" or "cert" looks like this:
344 certificate private key
346 client/server certificate
347 ca 1, signing client/server certficate
348 ca 2, signing ca 1
349 ...
350 cert => $string
352 The local certificate in PEM format (might be a combined
353 certificate/private key file). See "cert_file".
354 The idea behind being able to specify a string is to avoid
356 blocking in I/O. Unfortunately, Net::SSLeay fails to implement
357 any interface to the needed OpenSSL functionality, this is
358 currently implemented by writing to a temporary file.
359 cert_password => $string | $callback->($tls)
361 The certificate password - if the certificate is password-
362 protected, then you can specify its password here.
363 Instead of providing a password directly (which is not so
365 recommended), you can also provide a password-query callback.
366 The callback will be called whenever a password is required to
367 decode a local certificate, and is supposed to return the
368 password.
369 dh_file => $path
371 Path to a file containing Diffie-Hellman parameters in PEM
372 format, for use in servers. See also "dh" on how to specify
373 them directly, or use a pre-generated set.
374 Diffie-Hellman key exchange generates temporary encryption keys
376 that are not transferred over the connection, which means that
377 even if the certificate key(s) are made public at a later time
378 and a full dump of the connection exists, the key still cannot
379 be deduced.
380 These ciphers are only available with SSLv3 and later (which is
382 the default with AnyEvent::TLS), and are only used in
383 server/accept mode. Anonymous DH protocols are usually disabled
384 by default, and usually not even compiled into the underlying
385 library, as they provide no direct protection against man-in-
386 the-middle attacks. The same is true for the common practise of
387 self-signed certificates that you have to accept first, of
388 course.
389 dh => $string
391 Specify the Diffie-Hellman parameters in PEM format directly as
392 a string (see "dh_file"), the default is "schmorp1539" unless
393 "dh_file" was specified.
394 AnyEvent::TLS supports supports a number of precomputed DH
396 parameters, since computing them is expensive. They are:
397 # from "Assigned Number for SKIP Protocols"
399 skip512, skip1024, skip2048, skip4096
400 # from schmorp
402 schmorp1024, schmorp1539, schmorp2048, schmorp4096, schmorp8192
403 The default was chosen as a trade-off between security and
405 speed, and should be secure for a few years. It is said that
406 2048 bit DH parameters are safe till 2030, and DH parameters
407 shorter than 900 bits are totally insecure.
408 To disable DH protocols completely, specify "undef" as "dh"
410 parameter.
411 dh_single_use => $enable
413 Enables or disables "use only once" mode when using Diffie-
414 Hellman key exchange. When enabled (default), each time a new
415 key is exchanged a new Diffie-Hellman key is generated, which
416 improves security as each key is only used once. When disabled,
417 the key will be created as soon as the AnyEvent::TLS object is
418 created and will be reused.
419 All the DH parameters supplied with AnyEvent::TLS should be
421 safe with "dh_single_use" switched off, but YMMV.
422 cipher_list => $string
424 The list of ciphers to use, as a string (example:
425 "AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH"). The format of this
426 string and its default value is documented at
427 <http://www.openssl.org/docs/apps/ciphers.html#CIPHER_STRINGS>.
428 session_ticket => $enable
430 Enables or disables RC5077 support (Session Resumption without
431 Server-Side State). The default is disabled for clients, as
432 many (buggy) TLS/SSL servers choke on it, but enabled for
433 servers.
434 When enabled and supported by the server, a session ticket will
436 be provided to the client, which allows fast resuming of
437 connections.
438 prepare => $coderef->($tls)
440 If this argument is present, then it will be called with the
441 new AnyEvent::TLS object after any other initialisation has bee
442 done, in case you wish to fine-tune something...
443 $tls = new_from_ssleay AnyEvent::TLS $ctx
445 This constructor takes an existing Net::SSLeay SSL_CTX object
446 (which is just an integer) and converts it into an "AnyEvent::TLS"
447 object. This only works because AnyEvent::TLS is currently
448 implemented using Net::SSLeay. As this is such a horrible perl
449 module and OpenSSL has such an annoying license, this might change
450 in the future, in which case this method might vanish.
451 $ctx = $tls->ctx
453 Returns the actual Net::SSLeay::CTX object (just an integer).
454 AnyEvent::TLS::init
456 AnyEvent::TLS does on-demand initialisation, and normally there is
457 no need to call an initialise function.
458 As initialisation might take some time (to read e.g.
460 "/dev/urandom"), this could be annoying in some highly interactive
461 programs. In that case, you can call "AnyEvent::TLS::init" to make
462 sure there will be no costly initialisation later. It is harmless
463 to call "AnyEvent::TLS::init" multiple times.
464 $certname = AnyEvent::TLS::certname $x509
466 Utility function that returns a user-readable string identifying
467 the X509 certificate object.
468
470 Here are some quick facts about TLS/SSL that might help you:
471 · A certificate is the public key part, a key is the private key
473 part.
474 While not strictly true, certificates are the things you can hand
476 around publicly as a kind of identity, while keys should really be
477 kept private, as proving that you have the private key is usually
478 interpreted as being the entity behind the certificate.
479 · A certificate is signed by a CA (Certificate Authority).
481 By signing, the CA basically claims that the certificate it signs
483 really belongs to the identity named in it, verified according to
484 the CA policies. For e.g. HTTPS, the CA usually makes some checks
485 that the hostname mentioned in the certificate really belongs to
486 the company/person that requested the signing and owns the domain.
487 · CAs can be certified by other CAs.
489 Or by themselves - a certificate that is signed by a CA that is
491 itself is called a self-signed certificate, a trust chain of length
492 zero. When you find a certificate signed by another CA, which is in
493 turn signed by another CA you trust, you have a trust chain of
494 depth two.
495 · "Trusting" a CA means trusting all certificates it has signed.
497 If you "trust" a CA certificate, then all certificates signed by it
499 are automatically considered trusted as well.
500 · A successfully verified certificate means that you can be
502 reasonably sure that whoever you are talking with really is who he
503 claims he is.
504 By verifying certificates against a number of CAs that you trust
506 (meaning it is signed directly or indirectly by such a CA), you can
507 find out that the other side really is whoever he claims, according
508 to the CA policies, and your belief in the integrity of the CA.
509 · Verifying the certificate signature is not everything.
511 Even when the certificate is correct, it might belong to somebody
513 else: if www.attacker.com can make your computer believe that it is
514 really called www.mybank.com (by making your DNS server believe
515 this for example), then it could send you the certificate for
516 www.attacker.com that your software trusts because it is signed by
517 a CA you trust, and intercept all your traffic that you think goes
518 to www.mybank.com. This works because your software sees that the
519 certificate is correctly signed (for www.attacker.com) and you
520 think you are talking to your bank.
521 To thwart this attack vector, peername verification should be used,
523 which basically checks that the certificate (for www.attacker.com)
524 really belongs to the host you are trying to talk to
525 (www.mybank.com), which in this example is not the case, as
526 www.attacker.com (from the certificate) doesn't match
527 www.mybank.com (the hostname used to create the connection).
528 So peername verification is almost as important as checking the CA
530 signing. Unfortunately, every protocol implements this differently,
531 if at all...
532 · Switching off verification is sometimes reasonable.
534 You can switch off verification. You still get an encrypted
536 connection that is protected against eavesdropping and injection -
537 you just lose protection against man in the middle attacks, i.e.
538 somebody else with enough abilities to to intercept all traffic can
539 masquerade herself as the other side.
540 For many applications, switching off verification is entirely
542 reasonable. Downloading random stuff from websites using HTTPS for
543 no reason is such an application. Talking to your bank and entering
544 TANs is not such an application.
545 · A SSL/TLS server always needs a certificate/key pair to operate,
547 for clients this is optional.
548 Apart from (usually disabled) anonymous cipher suites, a server
550 always needs a certificate/key pair to operate.
551 Clients almost never use certificates, but if they do, they can be
553 used to authenticate the client, just as server certificates can be
554 used to authenticate the server.
555 · SSL version 2 is very insecure.
557 SSL version 2 is old and not only has it some security issues,
559 SSLv2-only implementations are usually buggy, too, due to their
560 age.
561 · Sometimes, even losing your "private" key might not expose all your
563 data.
564 With Diffie-Hellman ephemeral key exchange, you can lose the DH
566 parameters (the "keys"), but all your connections are still
567 protected. Diffie-Hellman needs special set-up (done by default by
568 AnyEvent::TLS).
569
571 To to the abysmal code quality of Net::SSLeay, this module will leak
572 small amounts of memory per TLS connection (currently at least one perl
573 scalar).
574
576 Marc Lehmann <schmorp@schmorp.de>.
577 Some of the API, documentation and implementation (verify_hostname),
579 and a lot of ideas/workarounds/knowledge have been taken from the
580 IO::Socket::SSL module. Care has been taken to keep the API similar to
581 that and other modules, to the extent possible while providing a
582 sensible API for AnyEvent.
583perl v5.12.1 2009-08-20 AnyEvent::TLS(3)