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" | "TLSv1_1" | "TLSv1_2" |
74 "any"
75 The protocol parser to use. "SSLv2", "SSLv3", "TLSv1",
76 "TLSv1_1" and "TLSv1_2" will use a parser for those protocols
77 only (so will not accept or create connections with/to other
78 protocol versions), while "any" (the default) uses a parser
79 capable of all three protocols.
80 The default is to use "any" but disable SSLv2. This has the
82 effect of sending a SSLv2 hello, indicating the support for
83 SSLv3 and TLSv1, but not actually negotiating an (insecure)
84 SSLv2 connection.
85 Specifying a specific version is almost always wrong to use for
87 a server speaking to a wide variety of clients (e.g. web
88 browsers), and often wrong for a client. If you only want to
89 allow a specific protocol version, use the "sslv2", "sslv3",
90 "tlsv1", "tlsv1_1" or "tlsv1_2" arguments instead.
91 For new services it is usually a good idea to enforce a "TLSv1"
93 method from the beginning.
94 "TLSv1_1" and "TLSv1_2" require Net::SSLeay >= 1.55 and OpenSSL
96 >= 1.0.1. Check the Net::SSLeay and OpenSSL documentations for
97 more details.
98 sslv2 => $enabled
100 Enable or disable SSLv2 (normally disabled).
101 sslv3 => $enabled
103 Enable or disable SSLv3 (normally enabled).
104 tlsv1 => $enabled
106 Enable or disable TLSv1 (normally enabled).
107 tlsv1_1 => $enabled
109 Enable or disable TLSv1_1 (normally enabled).
110 This requires Net::SSLeay >= 1.55 and OpenSSL >= 1.0.1. Check
112 the Net::SSLeay and OpenSSL documentations for more details.
113 tlsv1_2 => $enabled
115 Enable or disable TLSv1_2 (normally enabled).
116 This requires Net::SSLeay >= 1.55 and OpenSSL >= 1.0.1. Check
118 the Net::SSLeay and OpenSSL documentations for more details.
119 verify => $enable
121 Enable or disable peer certificate checking (default is
122 disabled, which is not recommended).
123 This is the "master switch" for all verify-related parameters
125 and functions.
126 If it is disabled, then no peer certificate verification will
128 be done - the connection will be encrypted, but the peer
129 certificate won't be verified against any known CAs, or whether
130 it is still valid or not. No peername verification or custom
131 verification will be done either.
132 If enabled, then the peer certificate (required in client mode,
134 optional in server mode, see "verify_require_client_cert") will
135 be checked against its CA certificate chain - that means there
136 must be a signing chain from the peer certificate to any of the
137 CA certificates you trust locally, as specified by the
138 "ca_file" and/or "ca_path" and/or "ca_cert" parameters (or the
139 system default CA repository, if all of those parameters are
140 missing - see also the AnyEvent manpage for the description of
141 PERL_ANYEVENT_CA_FILE).
142 Other basic checks, such as checking the validity period, will
144 also be done, as well as optional peername/hostname/common name
145 verification "verify_peername".
146 An optional "verify_cb" callback can also be set, which will be
148 invoked with the verification results, and which can override
149 the decision.
150 verify_require_client_cert => $enable
152 Enable or disable mandatory client certificates (default is
153 disabled). When this mode is enabled, then a client certificate
154 will be required in server mode (a server certificate is
155 mandatory, so in client mode, this switch has no effect).
156 verify_peername => $scheme | $callback->($tls, $cert, $peername)
158 TLS only protects the data that is sent - it cannot
159 automatically verify that you are really talking to the right
160 peer. The reason is that certificates contain a "common name"
161 (and a set of possible alternative "names") that need to be
162 checked against the peername (usually, but not always, the DNS
163 name of the server) in a protocol-dependent way.
164 This can be implemented by specifying a callback that has to
166 verify that the actual $peername matches the given certificate
167 in $cert.
168 Since this can be rather hard to implement, AnyEvent::TLS
170 offers a variety of predefined "schemes" (lifted from
171 IO::Socket::SSL) that are named like the protocols that use
172 them:
173 ldap (rfc4513), pop3,imap,acap (rfc2995), nntp (rfc4642)
175 Simple wildcards in subjectAltNames are possible, e.g.
176 *.example.org matches www.example.org but not
177 lala.www.example.org. If nothing from subjectAltNames
178 matches, it checks against the common name, but there are
179 no wildcards allowed.
180 http (rfc2818)
182 Extended wildcards in subjectAltNames are possible, e.g.
183 *.example.org or even www*.example.org. Wildcards in the
184 common name are not allowed. The common name will be only
185 checked if no host names are given in subjectAltNames.
186 smtp (rfc3207)
188 This RFC isn't very useful in determining how to do
189 verification so it just assumes that subjectAltNames are
190 possible, but no wildcards are possible anywhere.
191 [$wildcards_in_alt, $wildcards_in_cn, $check_cn]
193 You can also specify a scheme yourself by using an array
194 reference with three integers.
195 $wildcards_in_alt and $wildcards_in_cn specify whether and
197 where wildcards ("*") are allowed in subjectAltNames and
198 the common name, respectively. 0 means no wildcards are
199 allowed, 1 means they are allowed only as the first
200 component ("*.example.org"), and 2 means they can be used
201 anywhere ("www*.example.org"), except that very dangerous
202 matches will not be allowed ("*.org" or "*").
203 $check_cn specifies if and how the common name field is
205 checked: 0 means it will be completely ignored, 1 means it
206 will only be used if no host names have been found in the
207 subjectAltNames, and 2 means the common name will always be
208 checked against the peername.
209 You can specify either the name of the parent protocol
211 (recommended, e.g. "http", "ldap"), the protocol name as
212 usually used in URIs (e.g. "https", "ldaps") or the RFC (not
213 recommended, e.g. "rfc2995", "rfc3920").
214 This verification will only be done when verification is
216 enabled ("verify => 1").
217 verify_cb => $callback->($tls, $ref, $cn, $depth, $preverify_ok,
219 $x509_store_ctx, $cert)
220 Provide a custom peer verification callback used by TLS
221 sessions, which is called with the result of any other
222 verification ("verify", "verify_peername").
223 This callback will only be called when verification is enabled
225 ("verify => 1").
226 $tls is the "AnyEvent::TLS" object associated with the session,
228 while $ref is whatever the user associated with the session
229 (usually an AnyEvent::Handle object when used by
230 AnyEvent::Handle).
231 $depth is the current verification depth - "$depth = 0" means
233 the certificate to verify is the peer certificate, higher
234 levels are its CA certificate and so on. In most cases, you can
235 just return $preverify_ok if the $depth is non-zero:
236 verify_cb => sub {
238 my ($tls, $ref, $cn, $depth, $preverify_ok, $x509_store_ctx, $cert) = @_;
239 return $preverify_ok
241 if $depth;
242 # more verification
244 },
245 $preverify_ok is true iff the basic verification of the
247 certificates was successful (a valid CA chain must exist, the
248 certificate has passed basic validity checks, peername
249 verification succeeded).
250 $x509_store_ctx is the Net::SSLeay::X509_CTX> object.
252 $cert is the "Net::SSLeay::X509" object representing the peer
254 certificate, or zero if there was an error. You can call
255 "AnyEvent::TLS::certname $cert" to get a nice user-readable
256 string to identify the certificate.
257 The callback must return either 0 to indicate failure, or 1 to
259 indicate success.
260 verify_client_once => $enable
262 Enable or disable skipping the client certificate verification
263 on renegotiations (default is disabled, the certificate will
264 always be checked). Only makes sense in server mode.
265 ca_file => $path
267 If this parameter is specified and non-empty, it will be the
268 path to a file with (server) CA certificates in PEM format that
269 will be loaded. Each certificate will look like:
270 -----BEGIN CERTIFICATE-----
272 ... (CA certificate in base64 encoding) ...
273 -----END CERTIFICATE-----
274 You have to enable verify mode ("verify => 1") for this
276 parameter to have any effect.
277 ca_path => $path
279 If this parameter is specified and non-empty, it will be the
280 path to a directory with hashed CA certificate files in PEM
281 format. When the ca certificate is being verified, the
282 certificate will be hashed and looked up in that directory (see
283 <http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html>
284 for details)
285 The certificates specified via "ca_file" take precedence over
287 the ones found in "ca_path".
288 You have to enable verify mode ("verify => 1") for this
290 parameter to have any effect.
291 ca_cert => $string
293 In addition or instead of using "ca_file" and/or "ca_path", you
294 can also use "ca_cert" to directly specify the CA certificates
295 (there can be multiple) in PEM format, in a string.
296 check_crl => $enable
298 Enable or disable certificate revocation list checking. If
299 enabled, then peer certificates will be checked against a list
300 of revoked certificates issued by the CA. The revocation lists
301 will be expected in the "ca_path" directory.
302 certificate verification will fail if this is enabled but no
304 revocation list was found.
305 This requires OpenSSL >= 0.9.7b. Check the OpenSSL
307 documentation for more details.
308 key_file => $path
310 Path to the local private key file in PEM format (might be a
311 combined certificate/private key file).
312 The local certificate is used to authenticate against the peer
314 - servers mandatorily need a certificate and key, clients can
315 use a certificate and key optionally to authenticate, e.g. for
316 log-in purposes.
317 The key in the file should look similar this:
319 -----BEGIN RSA PRIVATE KEY-----
321 ...header data
322 ... (key data in base64 encoding) ...
323 -----END RSA PRIVATE KEY-----
324 key => $string
326 The private key string in PEM format (see "key_file", only one
327 of "key_file" or "key" can be specified).
328 The idea behind being able to specify a string is to avoid
330 blocking in I/O. Unfortunately, Net::SSLeay fails to implement
331 any interface to the needed OpenSSL functionality, this is
332 currently implemented by writing to a temporary file.
333 cert_file => $path
335 The path to the local certificate file in PEM format (might be
336 a combined certificate/private key file, including chained
337 certificates).
338 The local certificate (and key) are used to authenticate
340 against the peer - servers mandatorily need a certificate and
341 key, clients can use certificate and key optionally to
342 authenticate, e.g. for log-in purposes.
343 The certificate in the file should look like this:
345 -----BEGIN CERTIFICATE-----
347 ... (certificate in base64 encoding) ...
348 -----END CERTIFICATE-----
349 If the certificate file or string contain both the certificate
351 and private key, then there is no need to specify a separate
352 "key_file" or "key".
353 Additional signing certifiates to send to the peer (in SSLv3
355 and newer) can be specified by appending them to the
356 certificate proper: the order must be from issuer certificate
357 over any intermediate CA certificates to the root CA.
358 So the recommended ordering for a combined key/cert/chain file,
360 specified via "cert_file" or "cert" looks like this:
361 certificate private key
363 client/server certificate
364 ca 1, signing client/server certficate
365 ca 2, signing ca 1
366 ...
367 cert => $string
369 The local certificate in PEM format (might be a combined
370 certificate/private key file). See "cert_file".
371 The idea behind being able to specify a string is to avoid
373 blocking in I/O. Unfortunately, Net::SSLeay fails to implement
374 any interface to the needed OpenSSL functionality, this is
375 currently implemented by writing to a temporary file.
376 cert_password => $string | $callback->($tls)
378 The certificate password - if the certificate is password-
379 protected, then you can specify its password here.
380 Instead of providing a password directly (which is not so
382 recommended), you can also provide a password-query callback.
383 The callback will be called whenever a password is required to
384 decode a local certificate, and is supposed to return the
385 password.
386 dh_file => $path
388 Path to a file containing Diffie-Hellman parameters in PEM
389 format, for use in servers. See also "dh" on how to specify
390 them directly, or use a pre-generated set.
391 Diffie-Hellman key exchange generates temporary encryption keys
393 that are not transferred over the connection, which means that
394 even if the certificate key(s) are made public at a later time
395 and a full dump of the connection exists, the key still cannot
396 be deduced.
397 These ciphers are only available with SSLv3 and later (which is
399 the default with AnyEvent::TLS), and are only used in
400 server/accept mode. Anonymous DH protocols are usually disabled
401 by default, and usually not even compiled into the underlying
402 library, as they provide no direct protection against man-in-
403 the-middle attacks. The same is true for the common practise of
404 self-signed certificates that you have to accept first, of
405 course.
406 dh => $string
408 Specify the Diffie-Hellman parameters in PEM format directly as
409 a string (see "dh_file"), the default is "ffdhe3072" unless
410 "dh_file" was specified.
411 AnyEvent::TLS supports supports a number of precomputed DH
413 parameters, since computing them is expensive. They are:
414 # from RFC 7919 - recommended
416 ffdhe2048, ffdhe3072, ffdhe4096, ffdhe6144, ffdhe8192
417 # from "Assigned Number for SKIP Protocols"
419 skip512, skip1024, skip2048, skip4096
420 # from schmorp
422 schmorp1024, schmorp1539, schmorp2048, schmorp4096, schmorp8192
423 It is said that 2048 bit DH parameters are safe till 2030, and
425 DH parameters shorter than 900 bits are totally insecure.
426 To disable DH protocols completely, specify "undef" as "dh"
428 parameter.
429 dh_single_use => $enable
431 Enables or disables "use only once" mode when using Diffie-
432 Hellman key exchange. When enabled (default), each time a new
433 key is exchanged a new Diffie-Hellman key is generated, which
434 improves security as each key is only used once. When disabled,
435 the key will be created as soon as the AnyEvent::TLS object is
436 created and will be reused.
437 All the DH parameters supplied with AnyEvent::TLS should be
439 safe with "dh_single_use" switched off, but YMMV.
440 cipher_list => $string
442 The list of ciphers to use, as a string (example:
443 "AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH"). The format of this
444 string and its default value is documented at
445 <http://www.openssl.org/docs/apps/ciphers.html#CIPHER_STRINGS>.
446 session_ticket => $enable
448 Enables or disables RC5077 support (Session Resumption without
449 Server-Side State). The default is disabled for clients, as
450 many (buggy) TLS/SSL servers choke on it, but enabled for
451 servers.
452 When enabled and supported by the server, a session ticket will
454 be provided to the client, which allows fast resuming of
455 connections.
456 prepare => $coderef->($tls)
458 If this argument is present, then it will be called with the
459 new AnyEvent::TLS object after any other initialisation has bee
460 done, in case you wish to fine-tune something...
461 $tls = new_from_ssleay AnyEvent::TLS $ctx
463 This constructor takes an existing Net::SSLeay SSL_CTX object
464 (which is just an integer) and converts it into an "AnyEvent::TLS"
465 object. This only works because AnyEvent::TLS is currently
466 implemented using Net::SSLeay. As this is such a horrible perl
467 module and OpenSSL has such an annoying license, this might change
468 in the future, in which case this method might vanish.
469 $ctx = $tls->ctx
471 Returns the actual Net::SSLeay::CTX object (just an integer).
472 AnyEvent::TLS::init
474 AnyEvent::TLS does on-demand initialisation, and normally there is
475 no need to call an initialise function.
476 As initialisation might take some time (to read e.g.
478 "/dev/urandom"), this could be annoying in some highly interactive
479 programs. In that case, you can call "AnyEvent::TLS::init" to make
480 sure there will be no costly initialisation later. It is harmless
481 to call "AnyEvent::TLS::init" multiple times.
482 $certname = AnyEvent::TLS::certname $x509
484 Utility function that returns a user-readable string identifying
485 the X509 certificate object.
486
488 Here are some quick facts about TLS/SSL that might help you:
489 • A certificate is the public key part, a key is the private key
491 part.
492 While not strictly true, certificates are the things you can hand
494 around publicly as a kind of identity, while keys should really be
495 kept private, as proving that you have the private key is usually
496 interpreted as being the entity behind the certificate.
497 • A certificate is signed by a CA (Certificate Authority).
499 By signing, the CA basically claims that the certificate it signs
501 really belongs to the identity named in it, verified according to
502 the CA policies. For e.g. HTTPS, the CA usually makes some checks
503 that the hostname mentioned in the certificate really belongs to
504 the company/person that requested the signing and owns the domain.
505 • CAs can be certified by other CAs.
507 Or by themselves - a certificate that is signed by a CA that is
509 itself is called a self-signed certificate, a trust chain of length
510 zero. When you find a certificate signed by another CA, which is in
511 turn signed by another CA you trust, you have a trust chain of
512 depth two.
513 • "Trusting" a CA means trusting all certificates it has signed.
515 If you "trust" a CA certificate, then all certificates signed by it
517 are automatically considered trusted as well.
518 • A successfully verified certificate means that you can be
520 reasonably sure that whoever you are talking with really is who he
521 claims he is.
522 By verifying certificates against a number of CAs that you trust
524 (meaning it is signed directly or indirectly by such a CA), you can
525 find out that the other side really is whoever he claims, according
526 to the CA policies, and your belief in the integrity of the CA.
527 • Verifying the certificate signature is not everything.
529 Even when the certificate is correct, it might belong to somebody
531 else: if www.attacker.com can make your computer believe that it is
532 really called www.mybank.com (by making your DNS server believe
533 this for example), then it could send you the certificate for
534 www.attacker.com that your software trusts because it is signed by
535 a CA you trust, and intercept all your traffic that you think goes
536 to www.mybank.com. This works because your software sees that the
537 certificate is correctly signed (for www.attacker.com) and you
538 think you are talking to your bank.
539 To thwart this attack vector, peername verification should be used,
541 which basically checks that the certificate (for www.attacker.com)
542 really belongs to the host you are trying to talk to
543 (www.mybank.com), which in this example is not the case, as
544 www.attacker.com (from the certificate) doesn't match
545 www.mybank.com (the hostname used to create the connection).
546 So peername verification is almost as important as checking the CA
548 signing. Unfortunately, every protocol implements this differently,
549 if at all...
550 • Switching off verification is sometimes reasonable.
552 You can switch off verification. You still get an encrypted
554 connection that is protected against eavesdropping and injection -
555 you just lose protection against man in the middle attacks, i.e.
556 somebody else with enough abilities to intercept all traffic can
557 masquerade herself as the other side.
558 For many applications, switching off verification is entirely
560 reasonable. Downloading random stuff from websites using HTTPS for
561 no reason is such an application. Talking to your bank and entering
562 TANs is not such an application.
563 • A SSL/TLS server always needs a certificate/key pair to operate,
565 for clients this is optional.
566 Apart from (usually disabled) anonymous cipher suites, a server
568 always needs a certificate/key pair to operate.
569 Clients almost never use certificates, but if they do, they can be
571 used to authenticate the client, just as server certificates can be
572 used to authenticate the server.
573 • SSL version 2 is very insecure.
575 SSL version 2 is old and not only has it some security issues,
577 SSLv2-only implementations are usually buggy, too, due to their
578 age.
579 • Sometimes, even losing your "private" key might not expose all your
581 data.
582 With Diffie-Hellman ephemeral key exchange, you can lose the DH
584 parameters (the "keys"), but all your connections are still
585 protected. Diffie-Hellman needs special set-up (done by default by
586 AnyEvent::TLS).
587
589 When you use any of the options that pass in keys or certificates as
590 strings (e.g. "ca_cert"), then, due to serious shortcomings in
591 Net::SSLeay, this module creates a temporary file to store the string -
592 see File::Temp and possibly its "safe_level" setting for more details
593 on what to watch out for.
594
596 Due to the abysmal code quality of Net::SSLeay, this module will leak
597 small amounts of memory per TLS connection (currently at least one perl
598 scalar).
599
601 Marc Lehmann <schmorp@schmorp.de>.
602 Some of the API, documentation and implementation (verify_hostname),
604 and a lot of ideas/workarounds/knowledge have been taken from the
605 IO::Socket::SSL module. Care has been taken to keep the API similar to
606 that and other modules, to the extent possible while providing a
607 sensible API for AnyEvent.
608perl v5.38.0 2023-07-20 AnyEvent::TLS(3)