bionic (3) Net::SSLGlue::Socket.3pm.gz

Provided by: libnet-sslglue-perl_1.057-1_all bug

NAME
       Net::SSLGlue::Socket - socket which can be either SSL or plain IP (IPv4/IPv6)


SYNOPSIS
           use Net::SSLGlue::Socket;
           # SSL right from start
           my $ssl = Net::SSLGlue::Socket->new(
               PeerHost => ...,  # IPv4|IPv6 address
               PeerPort => ...,
               SSL => 1,
               SSL_ca_path => ...
           );

           # SSL through upgrade of plain connection
           my $plain = Net::SSLGlue::Socket->new(...);
           $plain->start_SSL( SSL_ca_path => ... );
           ...
           $plain->stop_SSL


DESCRIPTION
       First, it is recommended to use IO::Socket::SSL directly instead of this module, since this kind of
       functionality is available in IO::Socket::SSL since version 1.994.

       Net::SSLGlue::Socket implements a socket which can be either plain or SSL.  If IO::Socket::IP or
       IO::Socket::INET6 are installed it will also transparently handle IPv6 connections.

       A socket can be either start directly with SSL or it can be start plain and later be upgraded to SSL
       (because of a STARTTLS commando or similar) and also downgraded again.

       It is possible but not recommended to use the socket in non-blocking mode, because in this case special
       care must be taken with SSL (see documentation of IO::Socket::SSL).

       Additionally to the usual socket methods the following methods are defined or extended:


METHODS
       new The method "new" of Net::SSLGlue::Socket can have the argument SSL. If this is true the SSL upgrade
           will be done immediately. If not set any SSL_* args will still be saved and used at a later start_SSL
           call.

       start_SSL
           This will upgrade the plain socket to SSL. See IO::Socket::SSL  for arguments to "start_SSL". Any
           SSL_* arguments given to new will be applied here too.

       stop_SSL
           This will downgrade the socket from SSL to plain.

       peer_certificate ...
           Once the SSL connection is established you can use this method to get information about the
           certificate. See the IO::Socket::SSL documentation.

       can_read(timeout)
           This will check for available data. For a plain socket this will only use "select" to check the
           socket, but for SSL it will check if there are any pending data before trying a select.  Because SSL
           needs to read the whole frame before decryption can be done, a successful return of can_read is no
           guarantee that data can be read immediately, only that new data are either available or in the
           process of arriving.


SEE ALSO
       IO::Socket::SSL


       This module is copyright (c) 2013..2015, Steffen Ullrich.  All Rights Reserved.  This module is free
       software. It may be used, redistributed and/or modified under the same terms as Perl itself.