1IO::Socket::SSL(3)    User Contributed Perl Documentation   IO::Socket::SSL(3)
2
3
4

NAME

6       IO::Socket::SSL -- SSL sockets with IO::Socket interface
7

SYNOPSIS

9           use strict;
10           use IO::Socket::SSL;
11
12           # simple HTTP client -----------------------------------------------
13           my $sock = IO::Socket::SSL->new(
14               # where to connect
15               PeerHost => "www.example.com",
16               PeerPort => "https",
17
18               # certificate verification
19               SSL_verify_mode => SSL_VERIFY_PEER,
20
21               # location of CA store
22               # need only be given if default store should not be used
23               SSL_ca_path => '/etc/ssl/certs', # typical CA path on Linux
24               SSL_ca_file => '/etc/ssl/cert.pem', # typical CA file on BSD
25
26               # easy hostname verification
27               SSL_verifycn_name => 'foo.bar', # defaults to PeerHost
28               SSL_verifycn_schema => 'http',
29
30               # SNI support
31               SSL_hostname => 'foo.bar', # defaults to PeerHost
32
33           ) or die "failed connect or ssl handshake: $!,$SSL_ERROR";
34
35           # send and receive over SSL connection
36           print $client "GET / HTTP/1.0\r\n\r\n";
37           print <$client>;
38
39           # simple server ----------------------------------------------------
40           my $server = IO::Socket::SSL->new(
41               # where to listen
42               LocalAddr => '127.0.0.1',
43               LocalPort => 8080,
44               Listen => 10,
45
46               # which certificate to offer
47               # with SNI support there can be different certificates per hostname
48               SSL_cert_file => 'cert.pem',
49               SSL_key_file => 'key.pem',
50           ) or die "failed to listen: $!";
51
52           # accept client
53           my $client = $server->accept or die
54               "failed to accept or ssl handshake: $!,$SSL_ERROR";
55
56           # Upgrade existing socket to SSL ---------------------------------
57           my $sock = IO::Socket::INET->new('imap.example.com:imap');
58           # ... receive greeting, send STARTTLS, receive ok ...
59           IO::Socket::SSL->start_SSL($sock,
60               SSL_verify_mode => SSL_VERIFY_PEER,
61               SSL_ca_path => '/etc/ssl/certs',
62               ...
63           ) or die "failed to upgrade to SSL: $SSL_ERROR";
64
65           # manual name verification, could also be done in start_SSL with
66           # SSL_verifycn_name etc
67           $client->verify_hostname( 'imap.example.com','imap' )
68               or die "hostname verification failed";
69
70           # all data are now SSL encrypted
71           print $sock ....
72

DESCRIPTION

74       This module provides an interface to SSL sockets, similar to other
75       IO::Socket modules. Because of that, it can be used to make existing
76       programs using IO::Socket::INET or similar modules to provide SSL
77       encryption without much effort.  IO::Socket::SSL supports all the extra
78       features that one needs to write a full-featured SSL client or server
79       application: multiple SSL contexts, cipher selection, certificate
80       verification, Server Name Indication (SNI), Next Protocol Negotiation
81       (NPN), SSL version selection and more.
82
83       If you have never used SSL before, you should read the appendix
84       labelled 'Using SSL' before attempting to use this module.
85
86       If you are trying to use it with threads see the BUGS section.
87

METHODS

89       IO::Socket::SSL inherits from another IO::Socket module.  The choice of
90       the super class depends on the installed modules:
91
92       ·   If IO::Socket::IP with at least version 0.20 is installed it will
93           use this module as super class, transparently providing IPv6 and
94           IPv4 support.
95
96       ·   If IO::Socket::INET6 is installed it will use this module as super
97           class, transparently providing IPv6 and IPv4 support.
98
99       ·   Otherwise it will fall back to IO::Socket::INET, which is a perl
100           core module.  With IO::Socket::INET you only get IPv4 support.
101
102       Please be aware, that with the IPv6 capable super classes, it will
103       lookup first for the IPv6 address of a given hostname. If the resolver
104       provides an IPv6 address, but the host cannot be reached by IPv6, there
105       will be no automatic fallback to IPv4.  To avoid these problems you can
106       either force IPv4 by specifying and AF_INET as "Domain" of the socket
107       or globally enforce IPv4 by loading IO::Socket::SSL with the option
108       'inet4'.
109
110       IO::Socket::SSL will provide all of the methods of its super class, but
111       sometimes it will override them to match the behavior expected from SSL
112       or to provide additional arguments.
113
114       The new or changed methods are described below, but please read also
115       the section about SSL specific error handling.
116
117       new(...)
118           Creates a new IO::Socket::SSL object.  You may use all the friendly
119           options that came bundled with IO::Socket::INET, plus (optionally)
120           the ones that follow:
121
122           SSL_hostname
123             This can be given to specify the hostname used for SNI, which is
124             needed if you have multiple SSL hostnames on the same IP address.
125             If not given it will try to determine hostname from PeerAddr,
126             which will fail if only IP was given or if this argument is used
127             within start_SSL.
128
129             If you want to disable SNI set this argument to ''.
130
131             Currently only supported for the client side and will be ignored
132             for the server side.
133
134             See section "SNI Support" for details of SNI the support.
135
136           SSL_version
137             Sets the version of the SSL protocol used to transmit data.
138             'SSLv23' auto-negotiates between SSLv2 and SSLv3, while 'SSLv2',
139             'SSLv3', 'TLSv1', 'TLSv1_1' or 'TLSv1_2' restrict the protocol to
140             the specified version.  All values are case-insensitive.  Instead
141             of 'TLSv1_1' and 'TLSv1_2' one can also use 'TLSv11' and
142             'TLSv12'.  Support for 'TLSv1_1' and 'TLSv1_2' requires recent
143             versions of Net::SSLeay and openssl.
144
145             You can limit to set of supported protocols by adding !version
146             separated by ':'.
147
148             The default SSL_version is defined by underlying cryptographic
149             library.  E.g. 'SSLv23:!SSLv2' means, that SSLv2, SSLv3 and TLSv1
150             are supported for initial protocol handshakes, but SSLv2 will not
151             be accepted, leaving only SSLv3 and TLSv1. You can also use
152             !TLSv1_1 and !TLSv1_2 to disable TLS versions 1.1 and 1.2 while
153             allowing TLS version 1.0.
154
155             Setting the version instead to 'TLSv1' will probably break
156             interaction with lots of clients which start with SSLv2 and then
157             upgrade to TLSv1. On the other side some clients just close the
158             connection when they receive a TLS version 1.1 request. In this
159             case setting the version to 'SSLv23:!SSLv2:!TLSv1_1:!TLSv1_2'
160             might help.
161
162           SSL_cipher_list
163             If this option is set the cipher list for the connection will be
164             set to the given value, e.g. something like 'ALL:!LOW:!EXP:!ADH'.
165             Look into the OpenSSL documentation
166             (<http://www.openssl.org/docs/apps/ciphers.html#CIPHER_STRINGS>)
167             for more details.
168
169             If this option is not set or is set to '', OpenSSL builtin
170             default (whatever this is) will be used.
171
172           SSL_honor_cipher_order
173             If this option is true the cipher order the server specified is
174             used instead of the order proposed by the client. To mitigate
175             BEAST attack you might use something like
176
177               SSL_honor_cipher_order => 1,
178               SSL_cipher_list => 'RC4-SHA:ALL:!ADH:!LOW',
179
180           SSL_use_cert
181             If this is true, it forces IO::Socket::SSL to use a certificate
182             and key, even if you are setting up an SSL client.  If this is
183             set to 0 (the default), then you will only need a certificate and
184             key if you are setting up a server.
185
186             SSL_use_cert will implicitly be set if SSL_server is set.  For
187             convenience it is also set if it was not given but a cert was
188             given for use (SSL_cert_file or similar).
189
190           SSL_server
191             Set this option to a true value, if the socket should be used as
192             a server.  If this is not explicitly set it is assumed, if the
193             Listen parameter is given when creating the socket.
194
195           SSL_cert_file
196             If your SSL certificate is not in the default place
197             (certs/server-cert.pem for servers, certs/client-cert.pem for
198             clients), then you should use this option to specify the location
199             of your certificate.  A certificate is usually needed for an SSL
200             server, but might also be needed, if the client should authorize
201             itself with a certificate.
202
203             If your SSL server should be able to use different certificates
204             on the same IP address, depending on the name given by SNI, you
205             can use a hash reference instead of a file with "<hostname ="
206             cert_file>>.
207
208             Examples:
209
210              SSL_cert_file => 'mycert.pem'
211
212              SSL_cert_file => {
213                 "foo.example.org" => 'foo.pem',
214                 "bar.example.org" => 'bar.pem',
215                 # used when nothing matches or client does not support SNI
216                 '' => 'default.pem',
217              }
218
219           SSL_cert
220             This option can be used instead of "SSL_cert_file" to specify the
221             certificate.
222
223             Instead with a file the certificate is given as an X509* object
224             or array of X509* objects, where the first X509* is the internal
225             representation of the certificate while the following ones are
226             extra certificates.  The option is useful if you create your
227             certificate dynamically (like in a SSL intercepting proxy) or get
228             it from a string (see openssl PEM_read_bio_X509 etc for getting a
229             X509* from a string).
230
231             For SNI support a hash reference can be given, similar to the
232             "SSL_cert_file" option.
233
234           SSL_key_file
235             If your RSA private key is not in default place
236             (certs/server-key.pem for servers, certs/client-key.pem for
237             clients), then this is the option that you would use to specify a
238             different location.  Keys should be PEM formatted, and if they
239             are encrypted, you will be prompted to enter a password before
240             the socket is formed (unless you specified the SSL_passwd_cb
241             option).
242
243             For SNI support a hash reference can be given, similar to the
244             "SSL_cert_file" option.
245
246           SSL_key
247             This option can be used instead of "SSL_key" to specify the
248             certificate.  Instead of a file an EVP_PKEY* should be given.
249             This option is useful if you don't have your key in a file but
250             create it dynamically or get it from a string (see openssl
251             PEM_read_bio_PrivateKey etc for getting a EVP_PKEY* from a
252             string).
253
254             For SNI support a hash reference can be given, similar to the
255             "SSL_key" option.
256
257           SSL_dh_file
258             If you want Diffie-Hellman key exchange you need to supply a
259             suitable file here or use the SSL_dh parameter. See dhparam
260             command in openssl for more information.  To create a server
261             which provides perfect forward secrecy you need to either give
262             the DH parameters or (better, because faster) the ECDH curve.
263
264           SSL_dh
265             Like SSL_dh_file, but instead of giving a file you use a
266             preloaded or generated DH*.
267
268           SSL_ecdh_curve
269             If you want Elliptic Curve Diffie-Hellmann key exchange you need
270             to supply the OID or NID of a suitable curve (like 'prime256v1')
271             here.  To create a server which provides perfect forward secrecy
272             you need to either give the DH parameters or (better, because
273             faster) the ECDH curve.
274
275           SSL_passwd_cb
276             If your private key is encrypted, you might not want the default
277             password prompt from Net::SSLeay.  This option takes a reference
278             to a subroutine that should return the password required to
279             decrypt your private key.
280
281           SSL_ca_file
282             If you want to verify that the peer certificate has been signed
283             by a reputable certificate authority, then you can use this
284             option to locate the file containing the certificate(s) of the
285             reputable certificate authorities if it is not already in the
286             file certs/my-ca.pem or in a system-wide certificate authority
287             certificates store.  If you definitely want no SSL_ca_file used
288             you should set it to undef.
289
290           SSL_ca_path
291             If you are unusually friendly with the OpenSSL documentation, you
292             might have set yourself up a directory containing several trusted
293             certificates as separate files as well as an index of the
294             certificates.  If you want to use that directory for validation
295             purposes, and that directory is not ca/, then use this option to
296             point IO::Socket::SSL to the right place to look.  If you
297             definitely want no SSL_ca_path used you should set it to undef.
298
299           SSL_verify_mode
300             This option sets the verification mode for the peer certificate.
301             You may combine SSL_VERIFY_PEER (verify_peer),
302             SSL_VERIFY_FAIL_IF_NO_PEER_CERT (fail verification if no peer
303             certificate exists; ignored for clients), SSL_VERIFY_CLIENT_ONCE
304             (verify client once; ignored for clients).  See OpenSSL man page
305             for SSL_CTX_set_verify for more information.
306
307             The default is SSL_VERIFY_NONE for server  (e.g. no check for
308             client certificate).  For historical reasons the default for
309             client is currently also SSL_VERIFY_NONE, but this will change to
310             SSL_VERIFY_PEER in the near future. To aid transition a warning
311             is issued if the client is used with the default SSL_VERIFY_NONE,
312             unless SSL_verify_mode was explicitly set by the application.
313
314           SSL_verify_callback
315             If you want to verify certificates yourself, you can pass a sub
316             reference along with this parameter to do so.  When the callback
317             is called, it will be passed:
318
319             1. a true/false value that indicates what OpenSSL thinks of the
320             certificate,
321             2. a C-style memory address of the certificate store,
322             3. a string containing the certificate's issuer attributes and
323             owner attributes, and
324             4. a string containing any errors encountered (0 if no errors).
325             5. a C-style memory address of the peer's own certificate
326             (convertible to PEM form with
327             Net::SSLeay::PEM_get_string_X509()).
328
329             The function should return 1 or 0, depending on whether it thinks
330             the certificate is valid or invalid.  The default is to let
331             OpenSSL do all of the busy work.
332
333             The callback will be called for each element in the certificate
334             chain.
335
336             See the OpenSSL documentation for SSL_CTX_set_verify for more
337             information.
338
339           SSL_verifycn_scheme
340             Set the scheme used to automatically verify the hostname of the
341             peer.  See the information about the verification schemes in
342             verify_hostname.
343
344             The default is undef, e.g. to not automatically verify the
345             hostname.  If no verification is done the other SSL_verifycn_*
346             options have no effect, but you might still do manual
347             verification by calling verify_hostname.
348
349           SSL_verifycn_name
350             Set the name which is used in verification of hostname. If
351             SSL_verifycn_scheme is set and no SSL_verifycn_name is given it
352             will try to use the PeerHost and PeerAddr settings and fail if no
353             name can be determined.
354
355             Using PeerHost or PeerAddr works only if you create the
356             connection directly with "IO::Socket::SSL->new", if an
357             IO::Socket::INET object is upgraded with start_SSL the name has
358             to be given in SSL_verifycn_name.
359
360           SSL_check_crl
361             If you want to verify that the peer certificate has not been
362             revoked by the signing authority, set this value to true. OpenSSL
363             will search for the CRL in your SSL_ca_path, or use the file
364             specified by SSL_crl_file.  See the Net::SSLeay documentation for
365             more details.  Note that this functionality appears to be broken
366             with OpenSSL < v0.9.7b, so its use with lower versions will
367             result in an error.
368
369           SSL_crl_file
370             If you want to specify the CRL file to be used, set this value to
371             the pathname to be used.  This must be used in addition to
372             setting SSL_check_crl.
373
374           SSL_reuse_ctx
375             If you have already set the above options (SSL_version through
376             SSL_check_crl; this does not include SSL_cipher_list yet) for a
377             previous instance of IO::Socket::SSL, then you can reuse the SSL
378             context of that instance by passing it as the value for the
379             SSL_reuse_ctx parameter.  You may also create a new instance of
380             the IO::Socket::SSL::SSL_Context class, using any context options
381             that you desire without specifying connection options, and pass
382             that here instead.
383
384             If you use this option, all other context-related options that
385             you pass in the same call to new() will be ignored unless the
386             context supplied was invalid.  Note that, contrary to versions of
387             IO::Socket::SSL below v0.90, a global SSL context will not be
388             implicitly used unless you use the set_default_context()
389             function.
390
391           SSL_create_ctx_callback
392             With this callback you can make individual settings to the
393             context after it got created and the default setup was done.  The
394             callback will be called with the CTX object from Net::SSLeay as
395             the single argument.
396
397             Example for limiting the server session cache size:
398
399               SSL_create_ctx_callback => sub {
400                   my $ctx = shift;
401                       Net::SSLeay::CTX_sess_set_cache_size($ctx,128);
402               }
403
404           SSL_session_cache_size
405             If you make repeated connections to the same host/port and the
406             SSL renegotiation time is an issue, you can turn on client-side
407             session caching with this option by specifying a positive cache
408             size.  For successive connections, pass the SSL_reuse_ctx option
409             to the new() calls (or use set_default_context()) to make use of
410             the cached sessions.  The session cache size refers to the number
411             of unique host/port pairs that can be stored at one time; the
412             oldest sessions in the cache will be removed if new ones are
413             added.
414
415             This option does not effect the session cache a server has for
416             it's clients, e.g. it does not affect SSL objects with SSL_server
417             set.
418
419           SSL_session_cache
420             Specifies session cache object which should be used instead of
421             creating a new.  Overrules SSL_session_cache_size.  This option
422             is useful if you want to reuse the cache, but not the rest of the
423             context.
424
425             A session cache object can be created using
426             "IO::Socket::SSL::Session_Cache->new( cachesize )".
427
428             Use set_default_session_cache() to set a global cache object.
429
430           SSL_session_id_context
431             This gives an id for the servers session cache. It's necessary if
432             you want clients to connect with a client certificate. If not
433             given but SSL_verify_mode specifies the need for client
434             certificate a context unique id will be picked.
435
436           SSL_error_trap
437             When using the accept() or connect() methods, it may be the case
438             that the actual socket connection works but the SSL negotiation
439             fails, as in the case of an HTTP client connecting to an HTTPS
440             server.  Passing a subroutine ref attached to this parameter
441             allows you to gain control of the orphaned socket instead of
442             having it be closed forcibly.  The subroutine, if called, will be
443             passed two parameters: a reference to the socket on which the SSL
444             negotiation failed and the full text of the error message.
445
446           SSL_npn_protocols
447             If used on the server side it specifies list of protocols
448             advertised by SSL server as an array ref, e.g.
449             ['spdy/2','http1.1'].  On the client side it specifies the
450             protocols offered by the client for NPN as an array ref.  See
451             also method next_proto_negotiated.
452
453             Next Protocol Negotioation (NPN) is available with Net::SSLeay
454             1.46+ and openssl-1.0.1+.  To check support you might call
455             "IO::Socket::SSL-"can_npn()>.  If you use this option with an
456             unsupported Net::SSLeay/OpenSSL it will throw an error.
457
458       close(...)
459           There are a number of nasty traps that lie in wait if you are not
460           careful about using close().  The first of these will bite you if
461           you have been using shutdown() on your sockets.  Since the SSL
462           protocol mandates that a SSL "close notify" message be sent before
463           the socket is closed, a shutdown() that closes the socket's write
464           channel will cause the close() call to hang.  For a similar reason,
465           if you try to close a copy of a socket (as in a forking server) you
466           will affect the original socket as well.  To get around these
467           problems, call close with an object-oriented syntax (e.g.
468           $socket->close(SSL_no_shutdown => 1)) and one or more of the
469           following parameters:
470
471           SSL_no_shutdown
472             If set to a true value, this option will make close() not use the
473             SSL_shutdown() call on the socket in question so that the close
474             operation can complete without problems if you have used
475             shutdown() or are working on a copy of a socket.
476
477           SSL_fast_shutdown
478             If set to true only a unidirectional shutdown will be done, e.g.
479             only the close_notify (see SSL_shutdown(3)) will be called.
480             Otherwise a bidirectional shutdown will be done. If used within
481             close() it defaults to true, if used within stop_SSL() it
482             defaults to false.
483
484           SSL_ctx_free
485             If you want to make sure that the SSL context of the socket is
486             destroyed when you close it, set this option to a true value.
487
488       peek(...)
489           This function has exactly the same syntax as sysread(), and
490           performs nearly the same task (reading data from the socket) but
491           will not advance the read position so that successive calls to
492           peek() with the same arguments will return the same results.  This
493           function requires OpenSSL 0.9.6a or later to work.
494
495       pending()
496           This function will let you know how many bytes of data are
497           immediately ready for reading from the socket.  This is especially
498           handy if you are doing reads on a blocking socket or just want to
499           know if new data has been sent over the socket.
500
501       get_cipher()
502           Returns the string form of the cipher that the IO::Socket::SSL
503           object is using.
504
505       dump_peer_certificate()
506           Returns a parsable string with select fields from the peer SSL
507           certificate.      This method directly returns the result of the
508           dump_peer_certificate() method of Net::SSLeay.
509
510       peer_certificate($field)
511           If a peer certificate exists, this function can retrieve values
512           from it.  If no field is given the internal representation of
513           certificate from Net::SSLeay is returned.  The following fields can
514           be queried:
515
516           authority (alias issuer)
517                   The certificate authority which signed the certificate.
518
519           owner (alias subject)
520                   The owner of the certificate.
521
522           commonName (alias cn) - only for Net::SSLeay version >=1.30
523                   The common name, usually the server name for SSL
524                   certificates.
525
526           subjectAltNames - only for Net::SSLeay version >=1.33
527                   Alternative names for the subject, usually different names
528                   for the same server, like example.org, example.com,
529                   *.example.com.
530
531                   It returns a list of (typ,value) with typ GEN_DNS,
532                   GEN_IPADD etc (these constants are exported from
533                   IO::Socket::SSL).  See
534                   Net::SSLeay::X509_get_subjectAltNames.
535
536       get_servername
537           This gives the name requested by the client if Server Name
538           Indication (SNI) was used.
539
540       verify_hostname($hostname,$scheme)
541           This verifies the given hostname against the peer certificate using
542           the given scheme. Hostname is usually what you specify within the
543           PeerAddr.
544
545           Verification of hostname against a certificate is different between
546           various applications and RFCs. Some scheme allow wildcards for
547           hostnames, some only in subjectAltNames, and even their different
548           wildcard schemes are possible.
549
550           To ease the verification the following schemes are predefined:
551
552           ldap (rfc4513), pop3,imap,acap (rfc2995), nntp (rfc4642)
553                   Simple wildcards in subjectAltNames are possible, e.g.
554                   *.example.org matches www.example.org but not
555                   lala.www.example.org. If nothing from subjectAltNames match
556                   it checks against the common name, but there are no
557                   wildcards allowed.
558
559           http (rfc2818), alias is www
560                   Extended wildcards in subjectAltNames and common name are
561                   possible, e.g.  *.example.org or even www*.example.org. The
562                   common name will be only checked if no names are given in
563                   subjectAltNames.
564
565           smtp (rfc3207)
566                   This RFC doesn't say much useful about the verification so
567                   it just assumes that subjectAltNames are possible, but no
568                   wildcards are possible anywhere.
569
570           none    No verification will be done.  Actually is does not make
571                   any sense to call verify_hostname in this case.
572
573           The scheme can be given either by specifying the name for one of
574           the above predefined schemes, or by using a hash which can have the
575           following keys and values:
576
577           check_cn:  0|'always'|'when_only'
578                   Determines if the common name gets checked. If 'always' it
579                   will always be checked (like in ldap), if 'when_only' it
580                   will only be checked if no names are given in
581                   subjectAltNames (like in http), for any other values the
582                   common name will not be checked.
583
584           wildcards_in_alt: 0|'leftmost'|'anywhere'
585                   Determines if and where wildcards in subjectAltNames are
586                   possible. If 'leftmost' only cases like *.example.org will
587                   be possible (like in ldap), for 'anywhere' www*.example.org
588                   is possible too (like http), dangerous things like but
589                   www.*.org or even '*' will not be allowed.
590
591           wildcards_in_cn: 0|'leftmost'|'anywhere'
592                   Similar to wildcards_in_alt, but checks the common name.
593                   There is no predefined scheme which allows wildcards in
594                   common names.
595
596           callback: \&coderef
597                   If you give a subroutine for verification it will be called
598                   with the arguments
599                   ($hostname,$commonName,@subjectAltNames), where hostname is
600                   the name given for verification, commonName is the result
601                   from peer_certificate('cn') and subjectAltNames is the
602                   result from peer_certificate('subjectAltNames').
603
604                   All other arguments for the verification scheme will be
605                   ignored in this case.
606
607       next_proto_negotiated()
608           This method returns the name of negotiated protocol - e.g.
609           'http/1.1'. It works for both client and server side of SSL
610           connection.
611
612           NPN support is available with Net::SSLeay 1.46+ and openssl-1.0.1+.
613           To check support you might call "IO::Socket::SSL-"can_npn()>.
614
615       errstr()
616           Returns the last error (in string form) that occurred. If you do
617           not have a real object to perform this method on, call
618           IO::Socket::SSL::errstr() instead.
619
620           For read and write errors on non-blocking sockets, this method may
621           include the string "SSL wants a read first!" or "SSL wants a write
622           first!" meaning that the other side is expecting to read from or
623           write to the socket and wants to be satisfied before you get to do
624           anything. But with version 0.98 you are better comparing the global
625           exported variable $SSL_ERROR against the exported symbols
626           SSL_WANT_READ and SSL_WANT_WRITE.
627
628       opened()
629           This returns false if the socket could not be opened, 1 if the
630           socket could be opened and the SSL handshake was successful done
631           and -1 if the underlying IO::Handle is open, but the SSL handshake
632           failed.
633
634       IO::Socket::SSL->start_SSL($socket, ... )
635           This will convert a glob reference or a socket that you provide to
636           an IO::Socket::SSL object.    You may also pass parameters to
637           specify context or connection options as with a call to new().  If
638           you are using this function on an accept()ed socket, you must set
639           the parameter "SSL_server" to 1, i.e.
640           IO::Socket::SSL->start_SSL($socket, SSL_server => 1).  If you have
641           a class that inherits from IO::Socket::SSL and you want the $socket
642           to be blessed into your own class instead, use
643           MyClass->start_SSL($socket) to achieve the desired effect.
644
645           Note that if start_SSL() fails in SSL negotiation, $socket will
646           remain blessed in its original class.      For non-blocking sockets
647           you better just upgrade the socket to IO::Socket::SSL and call
648           accept_SSL or connect_SSL and the upgraded object. To just upgrade
649           the socket set SSL_startHandshake explicitly to 0. If you call
650           start_SSL w/o this parameter it will revert to blocking behavior
651           for accept_SSL and connect_SSL.
652
653           If given the parameter "Timeout" it will stop if after the timeout
654           no SSL connection was established. This parameter is only used for
655           blocking sockets, if it is not given the default Timeout from the
656           underlying IO::Socket will be used.
657
658       stop_SSL(...)
659           This is the opposite of start_SSL(), e.g. it will shutdown the SSL
660           connection and return to the class before start_SSL(). It gets the
661           same arguments as close(), in fact close() calls stop_SSL() (but
662           without downgrading the class).
663
664           Will return true if it succeeded and undef if failed. This might be
665           the case for non-blocking sockets. In this case $! is set to EAGAIN
666           and the ssl error to SSL_WANT_READ or SSL_WANT_WRITE. In this case
667           the call should be retried again with the same arguments once the
668           socket is ready is until it succeeds.
669
670       IO::Socket::SSL->new_from_fd($fd, ...)
671           This will convert a socket identified via a file descriptor into an
672           SSL socket.  Note that the argument list does not include a "MODE"
673           argument; if you supply one, it will be thoughtfully ignored (for
674           compatibility with IO::Socket::INET).  Instead, a mode of '+<' is
675           assumed, and the file descriptor passed must be able to handle such
676           I/O because the initial SSL handshake requires bidirectional
677           communication.
678
679       IO::Socket::SSL::set_default_context(...)
680           You may use this to make IO::Socket::SSL automatically re-use a
681           given context (unless specifically overridden in a call to new()).
682           It accepts one argument, which should be either an IO::Socket::SSL
683           object or an IO::Socket::SSL::SSL_Context object.   See the
684           SSL_reuse_ctx option of new() for more details.      Note that this
685           sets the default context globally, so use with caution (esp. in
686           mod_perl scripts).
687
688       IO::Socket::SSL::set_default_session_cache(...)
689           You may use this to make IO::Socket::SSL automatically re-use a
690           given session cache (unless specifically overridden in a call to
691           new()).  It accepts one argument, which should be an
692           IO::Socket::SSL::Session_Cache object or similar (e.g something
693           which implements get_session and add_session like
694           IO::Socket::SSL::Session_Cache does).  See the SSL_session_cache
695           option of new() for more details.   Note that this sets the default
696           cache globally, so use with caution.
697
698       IO::Socket::SSL::set_defaults(%args)
699           With this function one can set defaults for all SSL_* parameter
700           used for creation of the context, like the SSL_verify* parameter.
701
702           mode - set default SSL_verify_mode
703           callback - set default SSL_verify_callback
704           scheme - set default SSL_verifycn_scheme
705           name - set default SSL_verifycn_name
706                   If not given and scheme is hash reference with key callback
707                   it will be set to 'unknown'
708
709       The following methods are unsupported (not to mention futile!) and
710       IO::Socket::SSL will emit a large CROAK() if you are silly enough to
711       use them:
712
713       truncate
714       stat
715       ungetc
716       setbuf
717       setvbuf
718       fdopen
719       send/recv
720           Note that send() and recv() cannot be reliably trapped by a tied
721           filehandle (such as that used by IO::Socket::SSL) and so may send
722           unencrypted data over the socket.   Object-oriented calls to these
723           functions will fail, telling you to use the print/printf/syswrite
724           and read/sysread families instead.
725

ERROR HANDLING

727       If an SSL specific error occurs the global variable $SSL_ERROR will be
728       set.  If the error occurred on an existing SSL socket the method
729       "errstr" will give access to the latest socket specific error.  Both
730       $SSL_ERROR and "errstr" method give a dualvar similar to $!, e.g.
731       providing an error number in numeric context or an error description in
732       string context.
733

NON-BLOCKING I/O

735       If you have a non-blocking socket, the expected behavior on read,
736       write, accept or connect is to set $! to EAGAIN if the operation can
737       not be completed immediately.
738
739       With SSL there are cases, like with SSL handshakes, where the write
740       operation can not be completed until it can read from the socket or
741       vice versa.  In these cases $! is set to EGAIN like expected, and
742       additionally $SSL_ERROR is set to either SSL_WANT_READ or
743       SSL_WANT_WRITE.  Thus if you get EAGAIN on a SSL socket you must check
744       $SSL_ERROR for SSL_WANT_* and adapt your event mask accordingly.
745
746       Using readline on non-blocking sockets does not make much sense and I
747       would advise against using it.  And, while the behavior is not
748       documented for other IO::Socket classes, it will try to emulate the
749       behavior seen there, e.g. to return the received data instead of
750       blocking, even if the line is not complete. If an unrecoverable error
751       occurs it will return nothing, even if it already received some data.
752

SNI Support

754       Newer extensions to SSL can distinguish between multiple hostnames on
755       the same IP address using Server Name Indication (SNI).
756
757       Support for SNI on the client side was added somewhere in the OpenSSL
758       0.9.8 series, but only with 1.0 a bug was fixed when the server could
759       not decide about its hostname. Therefore client side SNI is only
760       supported with OpenSSL 1.0 or higher in IO::Socket::SSL.  With a
761       supported version, SNI is used automatically on the client side, if it
762       can determine the hostname from "PeerAddr" or "PeerHost". On
763       unsupported OpenSSL versions it will silently not use SNI.  The
764       hostname can also be given explicitly given with "SSL_hostname", but in
765       this case it will throw in error, if SNI is not supported.  To check
766       for support you might call "IO::Socket::SSL-"can_client_sni()>.
767
768       On the server side earlier versions of OpenSSL are supported, but only
769       together with Net::SSLeay version >= 1.50.  To check for support you
770       might call "IO::Socket::SSL-"can_server_sni()>.  If server side SNI is
771       supported, you might specify different certificates per host with
772       "SSL_cert*" and "SSL_key*", and check the requested name using
773       "get_servername".
774

RETURN VALUES

776       A few changes have gone into IO::Socket::SSL v0.93 and later with
777       respect to return values. The behavior on success remains unchanged,
778       but for all functions, the return value on error is now an empty
779       list.    Therefore, the return value will be false in all contexts, but
780       those who have been using the return values as arguments to subroutines
781       (like "mysub(IO::Socket::SSL(...)-"new, ...)>) may run into problems.
782       The moral of the story: always check the return values of these
783       functions before using them in any way that you consider meaningful.
784

DEBUGGING

786       If you are having problems using IO::Socket::SSL despite the fact that
787       can recite backwards the section of this documentation labelled 'Using
788       SSL', you should try enabling debugging. To specify the debug level,
789       pass 'debug#' (where # is a number from 0 to 3) to IO::Socket::SSL when
790       calling it.  The debug level will also be propagated to
791       Net::SSLeay::trace, see also Net::SSLeay:
792
793       use IO::Socket::SSL qw(debug0);
794           No debugging (default).
795
796       use IO::Socket::SSL qw(debug1);
797           Print out errors from IO::Socket::SSL and ciphers from Net::SSLeay.
798
799       use IO::Socket::SSL qw(debug2);
800           Print also information about call flow from IO::Socket::SSL and
801           progress information from Net::SSLeay.
802
803       use IO::Socket::SSL qw(debug3);
804           Print also some data dumps from IO::Socket::SSL and from
805           Net::SSLeay.
806

EXAMPLES

808       See the 'example' directory.
809

BUGS

811       IO::Socket::SSL depends on Net::SSLeay.  Up to version 1.43 of
812       Net::SSLeay it was not thread safe, although it did probably work if
813       you did not use SSL_verify_callback and SSL_password_cb.
814
815       If you use IO::Socket::SSL together with threads you should load it
816       (e.g. use or require) inside the main thread before creating any other
817       threads which use it.  This way it is much faster because it will be
818       initialized only once. Also there are reports that it might crash the
819       other way.
820
821       Creating an IO::Socket::SSL object in one thread and closing it in
822       another thread will not work.
823
824       IO::Socket::SSL does not work together with
825       Storable::fd_retrieve/fd_store.  See BUGS file for more information and
826       how to work around the problem.
827
828       Non-blocking and timeouts (which are based on non-blocking) are not
829       supported on Win32, because the underlying IO::Socket::INET does not
830       support non-blocking on this platform.
831
832       If you have a server and it looks like you have a memory leak you might
833       check the size of your session cache. Default for Net::SSLeay seems to
834       be 20480, see the example for SSL_create_ctx_callback for how to limit
835       it.
836
837       The default for SSL_verify_mode on the client is currently
838       SSL_VERIFY_NONE, which is a very bad idea, thus the default will change
839       in the near future.  See documentation for SSL_verify_mode for more
840       information.
841

LIMITATIONS

843       IO::Socket::SSL uses Net::SSLeay as the shiny interface to OpenSSL,
844       which is the shiny interface to the ugliness of SSL.   As a result, you
845       will need both Net::SSLeay and OpenSSL on your computer before using
846       this module.
847
848       If you have Scalar::Util (standard with Perl 5.8.0 and above) or
849       WeakRef, IO::Socket::SSL sockets will auto-close when they go out of
850       scope, just like IO::Socket::INET sockets.     If you do not have one
851       of these modules, then IO::Socket::SSL sockets will stay open until the
852       program ends or you explicitly close them.    This is due to the fact
853       that a circular reference is required to make IO::Socket::SSL sockets
854       act simultaneously like objects and glob references.
855

DEPRECATIONS

857       The following functions are deprecated and are only retained for
858       compatibility:
859
860       context_init()
861         use the SSL_reuse_ctx option if you want to re-use a context
862
863       socketToSSL() and socket_to_SSL()
864         use IO::Socket::SSL->start_SSL() instead
865
866       kill_socket()
867         use close() instead
868
869       get_peer_certificate()
870         use the peer_certificate() function instead.  Used to return
871         X509_Certificate with methods subject_name and issuer_name.  Now
872         simply returns $self which has these methods (although deprecated).
873
874       issuer_name()
875         use peer_certificate( 'issuer' ) instead
876
877       subject_name()
878         use peer_certificate( 'subject' ) instead
879

SEE ALSO

881       IO::Socket::INET, IO::Socket::INET6, IO::Socket::IP, Net::SSLeay.
882

AUTHORS

884       Steffen Ullrich, <steffen at genua.de> is the current maintainer.
885
886       Peter Behroozi, <behrooz at fas.harvard.edu> (Note the lack of an "i"
887       at the end of "behrooz")
888
889       Marko Asplund, <marko.asplund at kronodoc.fi>, was the original author
890       of IO::Socket::SSL.
891
892       Patches incorporated from various people, see file Changes.
893
895       The original versions of this module are Copyright (C) 1999-2002 Marko
896       Asplund.
897
898       The rewrite of this module is Copyright (C) 2002-2005 Peter Behroozi.
899
900       Versions 0.98 and newer are Copyright (C) 2006-2013 Steffen Ullrich.
901
902       This module is free software; you can redistribute it and/or modify it
903       under the same terms as Perl itself.
904

Appendix: Using SSL

906       If you are unfamiliar with the way OpenSSL works, good references may
907       be found in both the book "Network Security with OpenSSL" (Oreilly &
908       Assoc.) and the web site
909       <http://www.tldp.org/HOWTO/SSL-Certificates-HOWTO/>.  Read on for a
910       quick overview.
911
912   The Long of It (Detail)
913       The usual reason for using SSL is to keep your data safe.  This means
914       that not only do you have to encrypt the data while it is being
915       transported over a network, but you also have to make sure that the
916       right person gets the data.    To accomplish this with SSL, you have to
917       use certificates.   A certificate closely resembles a Government-issued
918       ID (at least in places where you can trust them).     The ID contains
919       some sort of identifying information such as a name and address, and is
920       usually stamped with a seal of Government Approval.   Theoretically,
921       this means that you may trust the information on the card and do
922       business with the owner of the card.  The same ideas apply to SSL
923       certificates, which have some identifying information and are "stamped"
924       [most people refer to this as signing instead] by someone (a
925       Certificate Authority) who you trust will adequately verify the
926       identifying information.  In this case, because of some clever number
927       theory, it is extremely difficult to falsify the stamping
928       process.  Another useful consequence of number theory is that the
929       certificate is linked to the encryption process, so you may encrypt
930       data (using information on the certificate) that only the certificate
931       owner can decrypt.
932
933       What does this mean for you?  It means that at least one person in the
934       party has to have an ID to get drinks :-).  Seriously, it means that
935       one of the people communicating has to have a certificate to ensure
936       that your data is safe.   For client/server interactions, the server
937       must always have a certificate.      If the server wants to verify that
938       the client is safe, then the client must also have a personal
939       certificate.  To verify that a certificate is safe, one compares the
940       stamped "seal" [commonly called an encrypted digest/hash/signature] on
941       the certificate with the official "seal" of the Certificate Authority
942       to make sure that they are the same.    To do this, you will need the
943       [unfortunately named] certificate of the Certificate Authority.  With
944       all these in hand, you can set up a SSL connection and be reasonably
945       confident that no-one is reading your data.
946
947   The Short of It (Summary)
948       For servers, you will need to generate a cryptographic private key and
949       a certificate request.  You will need to send the certificate request
950       to a Certificate Authority to get a real certificate back, after which
951       you can start serving people. For clients, you will not need anything
952       unless the server wants validation, in which case you will also need a
953       private key and a real certificate.     For more information about how
954       to get these, see <http://www.modssl.org/docs/2.8/ssl_faq.html#ToC24>.
955
956
957
958perl v5.16.3                      2018-04-10                IO::Socket::SSL(3)
Impressum