.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Net::SSLGlue::Socket 3pm"
.TH Net::SSLGlue::Socket 3pm "2018-04-10" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::SSLGlue::Socket \- socket which can be either SSL or plain IP (IPv4/IPv6)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 8
\&    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
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
Net::SSLGlue::Socket implements a socket which can be either plain or \s-1SSL.\s0
If IO::Socket::IP or IO::Socket::INET6 are installed it will also transparently
handle IPv6 connections.
.PP
A socket can be either start directly with \s-1SSL\s0 or it can be start plain and
later be upgraded to \s-1SSL\s0 (because of a \s-1STARTTLS\s0 commando or similar) and also
downgraded again.
.PP
It is possible but not recommended to use the socket in non-blocking
mode, because in this case special care must be taken with \s-1SSL\s0 (see
documentation of IO::Socket::SSL).
.PP
Additionally to the usual socket methods the following methods are defined or
extended:
.SH "METHODS"
.IX Header "METHODS"
.IP "new" 4
.IX Item "new"
The method \f(CW\*(C`new\*(C'\fR of Net::SSLGlue::Socket can have the argument \s-1SSL.\s0 If this
is true the \s-1SSL\s0 upgrade will be done immediately. If not set any SSL_* args will
still be saved and used at a later start_SSL call.
.IP "start_SSL" 4
.IX Item "start_SSL"
This will upgrade the plain socket to \s-1SSL.\s0 See IO::Socket::SSL  for
arguments to \f(CW\*(C`start_SSL\*(C'\fR. Any SSL_* arguments given to new will be applied
here too.
.IP "stop_SSL" 4
.IX Item "stop_SSL"
This will downgrade the socket from \s-1SSL\s0 to plain.
.IP "peer_certificate ..." 4
.IX Item "peer_certificate ..."
Once the \s-1SSL\s0 connection is established you can use this method to get
information about the certificate. See the IO::Socket::SSL documentation.
.IP "can_read(timeout)" 4
.IX Item "can_read(timeout)"
This will check for available data. For a plain socket this will only use
\&\f(CW\*(C`select\*(C'\fR to check the socket, but for \s-1SSL\s0 it will check if there are any
pending data before trying a select.
Because \s-1SSL\s0 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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
IO::Socket::SSL
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
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.