1AnyEvent::TLS(3)      User Contributed Perl Documentation     AnyEvent::TLS(3)
2
3
4

NAME

6       AnyEvent::TLS - SSLv2/SSLv3/TLSv1 contexts for use in AnyEvent::Handle
7

SYNOPSIS

9          # via AnyEvent::Handle
10
11          use AnyEvent;
12          use AnyEvent::Handle;
13          use AnyEvent::Socket;
14
15          # 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
22          # simple ssl-server
23          tcp_server undef, $port, sub {
24             my ($fh) = @_;
25
26             my $handle = new AnyEvent::Handle
27                fh       => $fh,
28                tls      => "accept",
29                tls_ctx  => { cert_file => "my-server-keycert.pem" },
30                ...
31
32          # directly
33
34          my $tls = new AnyEvent::TLS
35             verify => 1,
36             verify_peername => "ldaps",
37             ca_file => "/etc/cacertificates.pem";
38

DESCRIPTION

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
44       For some quick facts about SSL/TLS, see the section of the same name
45       near the end of the document.
46
47       A single TLS context can be used for any number of TLS connections that
48       wish to use the same certificates, policies etc.
49
50       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
57       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

USAGE EXAMPLES

65       See the AnyEvent::Handle manpage, NONFREQUENTLY ASKED QUESTIONS, for
66       some actual usage examples.
67

PUBLIC METHODS AND FUNCTIONS

69       $tls = new AnyEvent::TLS key => value...
70           The constructor supports these arguments (all as key => value
71           pairs).
72
73           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
81               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
86               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
92               For new services it is usually a good idea to enforce a "TLSv1"
93               method from the beginning.
94
95               "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
99           sslv2 => $enabled
100               Enable or disable SSLv2 (normally disabled).
101
102           sslv3 => $enabled
103               Enable or disable SSLv3 (normally enabled).
104
105           tlsv1 => $enabled
106               Enable or disable TLSv1 (normally enabled).
107
108           tlsv1_1 => $enabled
109               Enable or disable TLSv1_1 (normally enabled).
110
111               This requires Net::SSLeay >= 1.55 and OpenSSL >= 1.0.1. Check
112               the Net::SSLeay and OpenSSL documentations for more details.
113
114           tlsv1_2 => $enabled
115               Enable or disable TLSv1_2 (normally enabled).
116
117               This requires Net::SSLeay >= 1.55 and OpenSSL >= 1.0.1. Check
118               the Net::SSLeay and OpenSSL documentations for more details.
119
120           verify => $enable
121               Enable or disable peer certificate checking (default is
122               disabled, which is not recommended).
123
124               This is the "master switch" for all verify-related parameters
125               and functions.
126
127               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
133               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
143               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
147               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
151           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
157           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
165               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
169               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
174               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
181               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
187               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
192               [$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
196                   $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
204                   $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
210               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
215               This verification will only be done when verification is
216               enabled ("verify => 1").
217
218           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
224               This callback will only be called when verification is enabled
225               ("verify => 1").
226
227               $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
232               $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
237                  verify_cb => sub {
238                     my ($tls, $ref, $cn, $depth, $preverify_ok, $x509_store_ctx, $cert) = @_;
239
240                     return $preverify_ok
241                        if $depth;
242
243                     # more verification
244                  },
245
246               $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
251               $x509_store_ctx is the Net::SSLeay::X509_CTX> object.
252
253               $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
258               The callback must return either 0 to indicate failure, or 1 to
259               indicate success.
260
261           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
266           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
271                  -----BEGIN CERTIFICATE-----
272                  ... (CA certificate in base64 encoding) ...
273                  -----END CERTIFICATE-----
274
275               You have to enable verify mode ("verify => 1") for this
276               parameter to have any effect.
277
278           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
286               The certificates specified via "ca_file" take precedence over
287               the ones found in "ca_path".
288
289               You have to enable verify mode ("verify => 1") for this
290               parameter to have any effect.
291
292           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
297           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
303               certificate verification will fail if this is enabled but no
304               revocation list was found.
305
306               This requires OpenSSL >= 0.9.7b. Check the OpenSSL
307               documentation for more details.
308
309           key_file => $path
310               Path to the local private key file in PEM format (might be a
311               combined certificate/private key file).
312
313               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
318               The key in the file should look similar this:
319
320                  -----BEGIN RSA PRIVATE KEY-----
321                  ...header data
322                  ... (key data in base64 encoding) ...
323                  -----END RSA PRIVATE KEY-----
324
325           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
329               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
334           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
339               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
344               The certificate in the file should look like this:
345
346                  -----BEGIN CERTIFICATE-----
347                  ... (certificate in base64 encoding) ...
348                  -----END CERTIFICATE-----
349
350               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
354               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
359               So the recommended ordering for a combined key/cert/chain file,
360               specified via "cert_file" or "cert" looks like this:
361
362                 certificate private key
363                 client/server certificate
364                 ca 1, signing client/server certficate
365                 ca 2, signing ca 1
366                 ...
367
368           cert => $string
369               The local certificate in PEM format (might be a combined
370               certificate/private key file). See "cert_file".
371
372               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
377           cert_password => $string | $callback->($tls)
378               The certificate password - if the certificate is password-
379               protected, then you can specify its password here.
380
381               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
387           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
392               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
398               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
407           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
412               AnyEvent::TLS supports supports a number of precomputed DH
413               parameters, since computing them is expensive. They are:
414
415                  # from RFC 7919 - recommended
416                  ffdhe2048, ffdhe3072, ffdhe4096, ffdhe6144, ffdhe8192
417
418                  # from "Assigned Number for SKIP Protocols"
419                  skip512, skip1024, skip2048, skip4096
420
421                  # from schmorp
422                  schmorp1024, schmorp1539, schmorp2048, schmorp4096, schmorp8192
423
424               It is said that 2048 bit DH parameters are safe till 2030, and
425               DH parameters shorter than 900 bits are totally insecure.
426
427               To disable DH protocols completely, specify "undef" as "dh"
428               parameter.
429
430           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
438               All the DH parameters supplied with AnyEvent::TLS should be
439               safe with "dh_single_use" switched off, but YMMV.
440
441           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
447           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
453               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
457           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
462       $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
470       $ctx = $tls->ctx
471           Returns the actual Net::SSLeay::CTX object (just an integer).
472
473       AnyEvent::TLS::init
474           AnyEvent::TLS does on-demand initialisation, and normally there is
475           no need to call an initialise function.
476
477           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
483       $certname = AnyEvent::TLS::certname $x509
484           Utility function that returns a user-readable string identifying
485           the X509 certificate object.
486

SSL/TLS QUICK FACTS

488       Here are some quick facts about TLS/SSL that might help you:
489
490       •   A certificate is the public key part, a key is the private key
491           part.
492
493           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
498       •   A certificate is signed by a CA (Certificate Authority).
499
500           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
506       •   CAs can be certified by other CAs.
507
508           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
514       •   "Trusting" a CA means trusting all certificates it has signed.
515
516           If you "trust" a CA certificate, then all certificates signed by it
517           are automatically considered trusted as well.
518
519       •   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
523           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
528       •   Verifying the certificate signature is not everything.
529
530           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
540           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
547           So peername verification is almost as important as checking the CA
548           signing. Unfortunately, every protocol implements this differently,
549           if at all...
550
551       •   Switching off verification is sometimes reasonable.
552
553           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
559           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
564       •   A SSL/TLS server always needs a certificate/key pair to operate,
565           for clients this is optional.
566
567           Apart from (usually disabled) anonymous cipher suites, a server
568           always needs a certificate/key pair to operate.
569
570           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
574       •   SSL version 2 is very insecure.
575
576           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
580       •   Sometimes, even losing your "private" key might not expose all your
581           data.
582
583           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

SECURITY CONSIDERATIONS

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

BUGS

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

AUTHORS

601       Marc Lehmann <schmorp@schmorp.de>.
602
603       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.
608
609
610
611perl v5.36.0                      2022-07-22                  AnyEvent::TLS(3)
Impressum