22

✏️ Editing: Net::SSL.3pm

.\" Automatically generated by Pod::Man 4.11 (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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::SSL 3"
.TH Net::SSL 3 "2014-04-24" "perl v5.26.3" "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::SSL \- support for Secure Sockets Layer
.SH "METHODS"
.IX Header "METHODS"
.IP "new" 4
.IX Item "new"
Creates a new \f(CW\*(C`Net::SSL\*(C'\fR object.
.IP "configure" 4
.IX Item "configure"
Configures a \f(CW\*(C`Net::SSL\*(C'\fR socket for operation.
.IP "configure_certs" 4
.IX Item "configure_certs"
Sets up a certificate file to use for communicating with on
the socket.
.IP "connect" 4
.IX Item "connect"
.PD 0
.IP "die_with_error" 4
.IX Item "die_with_error"
.IP "get_cipher" 4
.IX Item "get_cipher"
.IP "get_lwp_object" 4
.IX Item "get_lwp_object"
.PD
Walks up the caller stack and looks for something blessed into
the \f(CW\*(C`LWP::UserAgent\*(C'\fR namespace and returns it. Vaguely deprecated.
.IP "get_peer_certificate" 4
.IX Item "get_peer_certificate"
Gets the peer certificate from the underlying \f(CW\*(C`Crypt::SSLeay::Conn\*(C'\fR
object.
.IP "get_peer_verify" 4
.IX Item "get_peer_verify"
.PD 0
.IP "get_shared_ciphers" 4
.IX Item "get_shared_ciphers"
.IP "getchunk" 4
.IX Item "getchunk"
.PD
Attempts to read up to 32KiB of data from the socket. Returns
\&\f(CW\*(C`undef\*(C'\fR if nothing was read, otherwise returns the data as
a scalar.
.IP "pending" 4
.IX Item "pending"
Provides access to OpenSSL's \f(CW\*(C`pending\*(C'\fR attribute on the \s-1SSL\s0 connection
object.
.IP "getline" 4
.IX Item "getline"
Reads one character at a time until a newline is encountered,
and returns the line, including the newline. Grossly
inefficient.
.IP "print" 4
.IX Item "print"
Concatenates the input parameters and writes them to the socket.
Does not honour \f(CW$,\fR nor \f(CW$/\fR. Returns the number of bytes written.
.IP "printf" 4
.IX Item "printf"
Performs a \f(CW\*(C`sprintf\*(C'\fR of the input parameters (thus, the first
parameter must be the format), and writes the result to the socket.
Returns the number of bytes written.
.IP "proxy" 4
.IX Item "proxy"
Returns the hostname of an https proxy server, as specified by the
\&\f(CW\*(C`HTTPS_PROXY\*(C'\fR environment variable.
.IP "proxy_connect_helper" 4
.IX Item "proxy_connect_helper"
Helps set up a connection through a proxy.
.IP "read" 4
.IX Item "read"
Performs a read on the socket and returns the result.
.IP "ssl_context" 4
.IX Item "ssl_context"
.PD 0
.IP "sysread" 4
.IX Item "sysread"
.PD
Is an alias of \f(CW\*(C`read\*(C'\fR.
.IP "timeout" 4
.IX Item "timeout"
Returns the timeout value of the socket as defined by the implementing
class or 60 seconds by default.
.IP "blocking" 4
.IX Item "blocking"
Returns a boolean indicating whether the underlying socket is in
blocking mode. By default, Net::SSL sockets are in blocking mode.
.Sp
.Vb 1
\&    $sock\->blocking(0); # set to non\-blocking mode
.Ve
.Sp
This method simply calls the underlying \f(CW\*(C`blocking\*(C'\fR method of the
IO::Socket object.
.IP "write" 4
.IX Item "write"
Writes the parameters passed in (thus, a list) to the socket. Returns
the number of bytes written.
.IP "syswrite" 4
.IX Item "syswrite"
Is an alias of \f(CW\*(C`write\*(C'\fR.
.IP "accept" 4
.IX Item "accept"
Not yet implemented. Will die if called.
.IP "getc" 4
.IX Item "getc"
Not yet implemented. Will die if called.
.IP "getlines" 4
.IX Item "getlines"
Not yet implemented. Will die if called.
.IP "ungetc" 4
.IX Item "ungetc"
Not yet implemented. Will die if called.
.IP "send_useragent_to_proxy" 4
.IX Item "send_useragent_to_proxy"
By default (as of version 2.80 of \f(CW\*(C`Net::SSL\*(C'\fR in the 0.54 distribution
of Crypt::SSLeay), the user agent string is no longer sent to the
proxy (but will continue to be sent to the remote host).
.Sp
The previous behaviour was of marginal benefit, and could cause
fatal errors in certain scenarios (see \s-1CPAN\s0 bug #4759) and so no
longer happens by default.
.Sp
To reinstate the old behaviour, call \f(CW\*(C`Net::SSL::send_useragent_to_proxy\*(C'\fR
with a true value (usually 1).
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.Vb 1
\&  "no port given for proxy server <proxy>"
.Ve
.PP
A proxy was specified for configuring a socket, but no port number
was given. Ensure that the proxy is specified as a host:port pair,
such as \f(CW\*(C`proxy.example.com:8086\*(C'\fR.
.PP
.Vb 1
\&  "configure certs failed: <contents of $@>; <contents of $!>"
\&
\&  "proxy connect failed: <contents of $@>; <contents of $!>"
\&
\&  "Connect failed: <contents of $@>; <contents of $!>"
.Ve
.PP
During \fBconnect()\fR.
.SS "\s-1SEE ALSO\s0"
.IX Subsection "SEE ALSO"
.IP "IO::Socket::INET" 4
.IX Item "IO::Socket::INET"
\&\f(CW\*(C`Net::SSL\*(C'\fR is implemented by subclassing \f(CW\*(C`IO::Socket::INET\*(C'\fR, hence
methods not specifically overridden are defined by that package.
.IP "Net::SSLeay" 4
.IX Item "Net::SSLeay"
A package that provides a Perl-level interface to the \f(CW\*(C`openssl\*(C'\fR
secure sockets layer library.

MR SKB