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 "schmorp1539" 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 "Assigned Number for SKIP Protocols"
416                  skip512, skip1024, skip2048, skip4096
417
418                  # from schmorp
419                  schmorp1024, schmorp1539, schmorp2048, schmorp4096, schmorp8192
420
421               The default was chosen as a trade-off between security and
422               speed, and should be secure for a few years. It is said that
423               2048 bit DH parameters are safe till 2030, and DH parameters
424               shorter than 900 bits are totally insecure.
425
426               To disable DH protocols completely, specify "undef" as "dh"
427               parameter.
428
429           dh_single_use => $enable
430               Enables or disables "use only once" mode when using Diffie-
431               Hellman key exchange. When enabled (default), each time a new
432               key is exchanged a new Diffie-Hellman key is generated, which
433               improves security as each key is only used once. When disabled,
434               the key will be created as soon as the AnyEvent::TLS object is
435               created and will be reused.
436
437               All the DH parameters supplied with AnyEvent::TLS should be
438               safe with "dh_single_use" switched off, but YMMV.
439
440           cipher_list => $string
441               The list of ciphers to use, as a string (example:
442               "AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH"). The format of this
443               string and its default value is documented at
444               <http://www.openssl.org/docs/apps/ciphers.html#CIPHER_STRINGS>.
445
446           session_ticket => $enable
447               Enables or disables RC5077 support (Session Resumption without
448               Server-Side State). The default is disabled for clients, as
449               many (buggy) TLS/SSL servers choke on it, but enabled for
450               servers.
451
452               When enabled and supported by the server, a session ticket will
453               be provided to the client, which allows fast resuming of
454               connections.
455
456           prepare => $coderef->($tls)
457               If this argument is present, then it will be called with the
458               new AnyEvent::TLS object after any other initialisation has bee
459               done, in case you wish to fine-tune something...
460
461       $tls = new_from_ssleay AnyEvent::TLS $ctx
462           This constructor takes an existing Net::SSLeay SSL_CTX object
463           (which is just an integer) and converts it into an "AnyEvent::TLS"
464           object. This only works because AnyEvent::TLS is currently
465           implemented using Net::SSLeay. As this is such a horrible perl
466           module and OpenSSL has such an annoying license, this might change
467           in the future, in which case this method might vanish.
468
469       $ctx = $tls->ctx
470           Returns the actual Net::SSLeay::CTX object (just an integer).
471
472       AnyEvent::TLS::init
473           AnyEvent::TLS does on-demand initialisation, and normally there is
474           no need to call an initialise function.
475
476           As initialisation might take some time (to read e.g.
477           "/dev/urandom"), this could be annoying in some highly interactive
478           programs. In that case, you can call "AnyEvent::TLS::init" to make
479           sure there will be no costly initialisation later. It is harmless
480           to call "AnyEvent::TLS::init" multiple times.
481
482       $certname = AnyEvent::TLS::certname $x509
483           Utility function that returns a user-readable string identifying
484           the X509 certificate object.
485

SSL/TLS QUICK FACTS

487       Here are some quick facts about TLS/SSL that might help you:
488
489       ·   A certificate is the public key part, a key is the private key
490           part.
491
492           While not strictly true, certificates are the things you can hand
493           around publicly as a kind of identity, while keys should really be
494           kept private, as proving that you have the private key is usually
495           interpreted as being the entity behind the certificate.
496
497       ·   A certificate is signed by a CA (Certificate Authority).
498
499           By signing, the CA basically claims that the certificate it signs
500           really belongs to the identity named in it, verified according to
501           the CA policies. For e.g. HTTPS, the CA usually makes some checks
502           that the hostname mentioned in the certificate really belongs to
503           the company/person that requested the signing and owns the domain.
504
505       ·   CAs can be certified by other CAs.
506
507           Or by themselves - a certificate that is signed by a CA that is
508           itself is called a self-signed certificate, a trust chain of length
509           zero. When you find a certificate signed by another CA, which is in
510           turn signed by another CA you trust, you have a trust chain of
511           depth two.
512
513       ·   "Trusting" a CA means trusting all certificates it has signed.
514
515           If you "trust" a CA certificate, then all certificates signed by it
516           are automatically considered trusted as well.
517
518       ·   A successfully verified certificate means that you can be
519           reasonably sure that whoever you are talking with really is who he
520           claims he is.
521
522           By verifying certificates against a number of CAs that you trust
523           (meaning it is signed directly or indirectly by such a CA), you can
524           find out that the other side really is whoever he claims, according
525           to the CA policies, and your belief in the integrity of the CA.
526
527       ·   Verifying the certificate signature is not everything.
528
529           Even when the certificate is correct, it might belong to somebody
530           else: if www.attacker.com can make your computer believe that it is
531           really called www.mybank.com (by making your DNS server believe
532           this for example), then it could send you the certificate for
533           www.attacker.com that your software trusts because it is signed by
534           a CA you trust, and intercept all your traffic that you think goes
535           to www.mybank.com. This works because your software sees that the
536           certificate is correctly signed (for www.attacker.com) and you
537           think you are talking to your bank.
538
539           To thwart this attack vector, peername verification should be used,
540           which basically checks that the certificate (for www.attacker.com)
541           really belongs to the host you are trying to talk to
542           (www.mybank.com), which in this example is not the case, as
543           www.attacker.com (from the certificate) doesn't match
544           www.mybank.com (the hostname used to create the connection).
545
546           So peername verification is almost as important as checking the CA
547           signing. Unfortunately, every protocol implements this differently,
548           if at all...
549
550       ·   Switching off verification is sometimes reasonable.
551
552           You can switch off verification. You still get an encrypted
553           connection that is protected against eavesdropping and injection -
554           you just lose protection against man in the middle attacks, i.e.
555           somebody else with enough abilities to intercept all traffic can
556           masquerade herself as the other side.
557
558           For many applications, switching off verification is entirely
559           reasonable. Downloading random stuff from websites using HTTPS for
560           no reason is such an application. Talking to your bank and entering
561           TANs is not such an application.
562
563       ·   A SSL/TLS server always needs a certificate/key pair to operate,
564           for clients this is optional.
565
566           Apart from (usually disabled) anonymous cipher suites, a server
567           always needs a certificate/key pair to operate.
568
569           Clients almost never use certificates, but if they do, they can be
570           used to authenticate the client, just as server certificates can be
571           used to authenticate the server.
572
573       ·   SSL version 2 is very insecure.
574
575           SSL version 2 is old and not only has it some security issues,
576           SSLv2-only implementations are usually buggy, too, due to their
577           age.
578
579       ·   Sometimes, even losing your "private" key might not expose all your
580           data.
581
582           With Diffie-Hellman ephemeral key exchange, you can lose the DH
583           parameters (the "keys"), but all your connections are still
584           protected. Diffie-Hellman needs special set-up (done by default by
585           AnyEvent::TLS).
586

SECURITY CONSIDERATIONS

588       When you use any of the options that pass in keys or certificates as
589       strings (e.g. "ca_cert"), then, due to serious shortcomings in
590       Net::SSLeay, this module creates a temporary file to store the string -
591       see File::Temp and possibly its "safe_level" setting for more details
592       on what to watch out for.
593

BUGS

595       Due to the abysmal code quality of Net::SSLeay, this module will leak
596       small amounts of memory per TLS connection (currently at least one perl
597       scalar).
598

AUTHORS

600       Marc Lehmann <schmorp@schmorp.de>.
601
602       Some of the API, documentation and implementation (verify_hostname),
603       and a lot of ideas/workarounds/knowledge have been taken from the
604       IO::Socket::SSL module. Care has been taken to keep the API similar to
605       that and other modules, to the extent possible while providing a
606       sensible API for AnyEvent.
607
608
609
610perl v5.28.0                      2016-07-21                  AnyEvent::TLS(3)
Impressum