Net::S...Socket(3pm)

💖 Net::SSLGlue::Socket — the manual, but make it make sense 💖

okay bestie, so this is the page for Net::SSLGlue::Socket, straight out of the User Contributed Perl Documentation collection — yes, the perl v5.36.0 era, dated 2022-12-06. pull up a chair, grab a boba 🧋, and let's talk about a socket that can be SSL or just plain old IP. it's giving ✨dual citizenship✨.

---

🌸 NAME 🌸

Net::SSLGlue::Socket — a socket which can be either SSL or plain IP (IPv4/IPv6). no cap. it does both. 💅

---

✨ SYNOPSIS ✨

look at the lewk, look at the moves:

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

see how the second one starts plain and then glows up into SSL? that's the whole vibe. 🌈

---

🦋 DESCRIPTION 🦋

okay so first things first, and I'm gonna say this with love: use IO::Socket::SSL directly instead of this module. fr fr. this kind of functionality has been available in IO::Socket::SSL since version 1.994, so this module is basically the older sister who's still iconic but knows you don't need her anymore. 💀

Net::SSLGlue::Socket implements a socket which can be either plain or SSL. and if IO::Socket::IP or IO::Socket::INET6 are installed, it will also transparently handle IPv6 connections. transparently!! like it's not even trying and it ate. 👑

a socket can either start directly with SSL, or it can start plain and later be upgraded to SSL (because of a STARTTLS commando or similar) and also downgraded again. yes, it can go back. growth is not linear bestie. 🎀

⚠️ 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). don't do it casually, I'm begging. 😭

additionally to the usual socket methods, the following methods are defined or extended. let's get into it. 💅

---

💜 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 — no waiting, main character energy, right now. 🔥

if it's not set, any SSL_* args will still be saved and used at a later start_SSL call. they're not gone, they're just chilling in the drafts folder. 📥

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. glow-up complete. ✨

stop_SSL

this will downgrade the socket from SSL to plain. yes, we're taking the heels off. it's a chill night now. 🩴

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. it's giving "let me see your ID" but politely. 🪪

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. it's not lying to you, it's just being honest about the timeline. ⏳

---

🫶 SEE ALSO 🫶

• IO::Socket::SSL — the one, the only, the recommended. go there. 💖

---

🎀 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. slay, legally. ⚖️✨

---

and that's the whole page bestie!! 🦋 this was rendered for perl v5.36.0, dated 2022-12-06 — so if you're reading this way later, the vibes are preserved but check for newer docs. mwah 💋 go forth and socket responsibly 💅🌸