1POE::Component::SSLify(U3spemr)Contributed Perl DocumentPaOtEi:o:nComponent::SSLify(3pm)
2
6 POE::Component::SSLify - Makes using SSL in the world of POE easy!
7
9 This document describes v1.012 of POE::Component::SSLify - released November 14, 2014 as part of POE-Component-SSLify.
10
12 # look at the DESCRIPTION for client and server example code
13
15 This component is a method to simplify the SSLification of a socket
16 before it is passed to a POE::Wheel::ReadWrite wheel in your
17 application.
18 Client usage
20 # Import the module
21 use POE::Component::SSLify qw( Client_SSLify );
22 # Create a normal SocketFactory wheel and connect to a SSL-enabled server
24 my $factory = POE::Wheel::SocketFactory->new;
25 # Time passes, SocketFactory gives you a socket when it connects in SuccessEvent
27 # Convert the socket into a SSL socket POE can communicate with
28 my $socket = shift;
29 eval { $socket = Client_SSLify( $socket ) };
30 if ( $@ ) {
31 # Unable to SSLify it...
32 }
33 # Now, hand it off to ReadWrite
35 my $rw = POE::Wheel::ReadWrite->new(
36 Handle => $socket,
37 # other options as usual
38 );
39 Server usage
41 # !!! Make sure you have a public key + certificate
42 # excellent howto: http://www.akadia.com/services/ssh_test_certificate.html
43 # Import the module
45 use POE::Component::SSLify qw( Server_SSLify SSLify_Options );
46 # Set the key + certificate file
48 eval { SSLify_Options( 'server.key', 'server.crt' ) };
49 if ( $@ ) {
50 # Unable to load key or certificate file...
51 }
52 # Create a normal SocketFactory wheel to listen for connections
54 my $factory = POE::Wheel::SocketFactory->new;
55 # Time passes, SocketFactory gives you a socket when it gets a connection in SuccessEvent
57 # Convert the socket into a SSL socket POE can communicate with
58 my $socket = shift;
59 eval { $socket = Server_SSLify( $socket ) };
60 if ( $@ ) {
61 # Unable to SSLify it...
62 }
63 # Now, hand it off to ReadWrite
65 my $rw = POE::Wheel::ReadWrite->new(
66 Handle => $socket,
67 # other options as usual
68 );
69
71 Client_SSLify
72 This function sslifies a client-side socket. You can pass several
73 options to it:
74 my $socket = shift;
76 $socket = Client_SSLify( $socket, $version, $options, $ctx, $callback );
77 $socket is the non-ssl socket you got from somewhere ( required )
78 $version is the SSL version you want to use
79 $options is the SSL options you want to use
80 $ctx is the custom SSL context you want to use
81 $callback is the callback hook on success/failure of sslification
82 # This is an example of the callback and you should pass it as Client_SSLify( $socket, ... , \&callback );
84 sub callback {
85 my( $socket, $status, $errval ) = @_;
86 # $socket is the original sslified socket in case you need to play with it
87 # $status is either 1 or 0; with 1 signifying success and 0 failure
88 # $errval will be defined if $status == 0; it's the numeric SSL error code
89 # check http://www.openssl.org/docs/ssl/SSL_get_error.html for the possible error values ( and import them from Net::SSLeay! )
90 # The return value from the callback is discarded
92 }
93 If $ctx is defined, SSLify will ignore $version and $options.
95 Otherwise, it will be created from the $version and $options
96 parameters. If all of them are undefined, it will follow the defaults
97 in "SSLify_ContextCreate".
98 BEWARE: If you passed in a CTX, SSLify will do Net::SSLeay::CTX_free(
100 $ctx ) when the socket is destroyed. This means you cannot reuse
101 contexts!
102 NOTE: The way to have a client socket with proper certificates set up
104 is:
105 my $socket = shift; # get the socket from somewhere
107 my $ctx = SSLify_ContextCreate( 'server.key', 'server.crt' );
108 $socket = Client_SSLify( $socket, undef, undef, $ctx );
109 NOTE: You can pass the callback anywhere in the arguments, we'll figure
111 it out for you! If you want to call a POE event, please look into the
112 postback/callback stuff in POE::Session.
113 # we got this from POE::Wheel::SocketFactory
115 sub event_SuccessEvent {
116 my $socket = $_[ARG0];
117 $socket = Client_SSLify( $socket, $_[SESSION]->callback( 'sslify_result' ) );
118 $_[HEAP]->{client} = POE::Wheel::ReadWrite->new(
119 Handle => $socket,
120 ...
121 );
122 return;
123 }
124 # the callback event
126 sub event_sslify_result {
127 my ($creation_args, $called_args) = @_[ARG0, ARG1];
128 my( $socket, $status, $errval ) = @$called_args;
129 if ( $status ) {
131 print "Yay, SSLification worked!";
132 } else {
133 print "Aw, SSLification failed with error $errval";
134 }
135 }
136 Server_SSLify
138 This function sslifies a server-side socket. You can pass several
139 options to it:
140 my $socket = shift;
142 $socket = Server_SSLify( $socket, $ctx, $callback );
143 $socket is the non-ssl socket you got from somewhere ( required )
144 $ctx is the custom SSL context you want to use; overrides the global ctx set in SSLify_Options
145 $callback is the callback hook on success/failure of sslification
146 BEWARE: "SSLify_Options" must be called first if you aren't passing a
148 $ctx. If you want to set some options per-connection, do this:
149 my $socket = shift; # get the socket from somewhere
151 my $ctx = SSLify_ContextCreate();
152 # set various options on $ctx as desired
153 $socket = Server_SSLify( $socket, $ctx );
154 NOTE: You can use "SSLify_GetCTX" to modify the global, and avoid doing
156 this on every connection if the options are the same...
157 Please look at "Client_SSLify" for more details on the callback hook.
159 SSLify_ContextCreate
161 Accepts some options, and returns a brand-new Net::SSLeay context
162 object ( $ctx )
163 my $ctx = SSLify_ContextCreate( $key, $cert, $version, $options );
165 $key is the certificate key file
166 $cert is the certificate file
167 $version is the SSL version to use
168 $options is the SSL options to use
169 You can then call various Net::SSLeay methods on the context
171 my $mode = Net::SSLeay::CTX_get_mode( $ctx );
173 By default we don't use the SSL key + certificate files
175 By default we use the version: default. Known versions of the SSL
177 connection - look at <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
178 for more info.
179 * sslv2
181 * sslv3
182 * tlsv1
183 * sslv23
184 * default ( sslv23 )
185 By default we don't set any options - look at
187 <http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html> for more
188 info.
189 SSLify_Options
191 Call this function to initialize the global server-side context object.
192 This will be the default context whenever you call "Server_SSLify"
193 without passing a custom context to it.
194 SSLify_Options( $key, $cert, $version, $options );
196 $key is the certificate key file ( required )
197 $cert is the certificate file ( required )
198 $version is the SSL version to use
199 $options is the SSL options to use
200 By default we use the version: default
202 By default we use the options: Net::SSLeay::OP_ALL
204 Please look at "SSLify_ContextCreate" for more info on the available
206 versions/options.
207 SSLify_GetCTX
209 Returns the actual Net::SSLeay context object in case you wanted to
210 play with it :)
211 If passed in a socket, it will return that socket's $ctx instead of the
213 global.
214 my $ctx = SSLify_GetCTX(); # get the one set via SSLify_Options
216 my $ctx = SSLify_GetCTX( $sslified_sock ); # get the one in the object
217 SSLify_GetCipher
219 Returns the cipher used by the SSLified socket
220 print "SSL Cipher is: " . SSLify_GetCipher( $sslified_sock ) . "\n";
222 NOTE: Doing this immediately after Client_SSLify or Server_SSLify will
224 result in "(NONE)" because the SSL handshake is not done yet. The
225 socket is nonblocking, so you will have to wait a little bit for it to
226 get ready.
227 apoc@blackhole:~/mygit/perl-poe-sslify/examples$ perl serverclient.pl
229 got connection from: 127.0.0.1 - commencing Server_SSLify()
230 SSLified: 127.0.0.1 cipher type: ((NONE))
231 Connected to server, commencing Client_SSLify()
232 SSLified the connection to the server
233 Connected to SSL server
234 Input: hola
235 got input from: 127.0.0.1 cipher type: (AES256-SHA) input: 'hola'
236 Got Reply: hola
237 Input: ^C
238 stopped at serverclient.pl line 126.
239 SSLify_GetSocket
241 Returns the actual socket used by the SSLified socket, useful for stuff
242 like getpeername()/getsockname()
243 print "Remote IP is: " . inet_ntoa( ( unpack_sockaddr_in( getpeername( SSLify_GetSocket( $sslified_sock ) ) ) )[1] ) . "\n";
245 SSLify_GetSSL
247 Returns the actual Net::SSLeay object so you can call methods on it
248 print Net::SSLeay::dump_peer_certificate( SSLify_GetSSL( $sslified_sock ) );
250 SSLify_GetStatus
252 Returns the status of the SSL negotiation/handshake/connection. See
253 <http://www.openssl.org/docs/ssl/SSL_connect.html#RETURN_VALUES> for
254 more info.
255 my $status = SSLify_GetStatus( $socket );
257 -1 = still in negotiation stage ( or error )
258 0 = internal SSL error, connection will be dead
259 1 = negotiation successful
260
262 Socket methods doesn't work
263 The new socket this module gives you actually is tied socket magic, so
264 you cannot do stuff like getpeername() or getsockname(). The only way
265 to do it is to use "SSLify_GetSocket" and then operate on the socket it
266 returns.
267 Dying everywhere...
269 This module will die() if Net::SSLeay could not be loaded or it is not
270 the version we want. So, it is recommended that you check for errors
271 and not use SSL, like so:
272 eval { use POE::Component::SSLify };
274 if ( $@ ) {
275 $sslavailable = 0;
276 } else {
277 $sslavailable = 1;
278 }
279 # Make socket SSL!
281 if ( $sslavailable ) {
282 eval { $socket = POE::Component::SSLify::Client_SSLify( $socket ) };
283 if ( $@ ) {
284 # Unable to SSLify the socket...
285 }
286 }
287 $IGNORE_SSL_ERRORS
289 As of SSLify v1.003 you can override this variable to temporarily
291 ignore some SSL errors. This is useful if you are doing crazy things
292 with the underlying Net::SSLeay stuff and don't want to die. However,
293 it won't ignore all errors as some is still considered fatal. Here's
294 an example:
295 {
297 local $POE::Component::SSLify::IGNORE_SSL_ERRORS=1;
298 my $ctx = SSLify_CreateContext(...);
299 #Some more stuff
300 }
301 OpenSSL functions
303 Theoretically you can do anything that Net::SSLeay exports from the
304 OpenSSL libs on the socket. However, I have not tested every possible
305 function against SSLify, so use them carefully!
306 Net::SSLeay::renegotiate
308 This function has been tested ( it's in "t/2_renegotiate_client.t" )
310 but it doesn't work on FreeBSD! I tracked it down to this security
311 advisory:
312 <http://security.freebsd.org/advisories/FreeBSD-SA-09:15.ssl.asc> which
313 explains it in detail. The test will skip this function if it detects
314 that you're on a broken system. However, if you have the updated
315 OpenSSL library that fixes this you can use it.
316 NOTE: Calling this means the callback function you passed in
318 "Client_SSLify" or "Server_SSLify" will not fire! If you need this
319 please let me know and we can come up with a way to make it work.
320 Upgrading a non-ssl socket to SSL
322 You can have a normal plaintext socket, and convert it to SSL anytime.
323 Just keep in mind that the client and the server must agree to sslify
324 at the same time, or they will be waiting on each other forever! See
325 "t/3_upgrade.t" for an example of how this works.
326 Downgrading a SSL socket to non-ssl
328 As of now this is unsupported. If you need this feature please let us
329 know and we'll work on it together!
330 MSWin32 is not supported
332 This module doesn't work on MSWin32 platforms at all ( XP, Vista, 7,
333 etc ) because of some weird underlying fd issues. Since I'm not a
334 windows developer, I'm unable to fix this. However, it seems like
335 Cygwin on MSWin32 works just fine! Please help me fix this if you can,
336 thanks!
337 LOAD_SSL_ENGINES
339 OpenSSL supports loading ENGINEs to accelerate the crypto algorithms.
340 SSLify v1.004 automatically loaded the engines, but there was some
341 problems on certain platforms that caused coredumps. A big shout-out to
342 BinGOs and CPANTesters for catching this! It's now disabled in v1.007
343 and you would need to explicitly enable it.
344 sub POE::Component::SSLify::LOAD_SSL_ENGINES () { 1 }
346 use POE::Component::SSLify qw( Client::SSLify );
347
349 Stuffs all of the functions in @EXPORT_OK so you have to request them
350 directly.
351
353 Please see those modules/websites for more information related to this
354 module.
355 • POE
357 • Net::SSLeay
359
361 Perldoc
362 You can find documentation for this module with the perldoc command.
363 perldoc POE::Component::SSLify
365 Websites
367 The following websites have more information about this module, and may
368 be of help to you. As always, in addition to those websites please use
369 your favorite search engine to discover more resources.
370 • MetaCPAN
372 A modern, open-source CPAN search engine, useful to view POD in
374 HTML format.
375 <http://metacpan.org/release/POE-Component-SSLify>
377 • Search CPAN
379 The default CPAN search engine, useful to view POD in HTML format.
381 <http://search.cpan.org/dist/POE-Component-SSLify>
383 • RT: CPAN's Bug Tracker
385 The RT ( Request Tracker ) website is the default bug/issue
387 tracking system for CPAN.
388 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Component-SSLify>
390 • AnnoCPAN
392 The AnnoCPAN is a website that allows community annotations of Perl
394 module documentation.
395 <http://annocpan.org/dist/POE-Component-SSLify>
397 • CPAN Ratings
399 The CPAN Ratings is a website that allows community ratings and
401 reviews of Perl modules.
402 <http://cpanratings.perl.org/d/POE-Component-SSLify>
404 • CPAN Forum
406 The CPAN Forum is a web forum for discussing Perl modules.
408 <http://cpanforum.com/dist/POE-Component-SSLify>
410 • CPANTS
412 The CPANTS is a website that analyzes the Kwalitee ( code metrics )
414 of a distribution.
415 <http://cpants.cpanauthors.org/dist/overview/POE-Component-SSLify>
417 • CPAN Testers
419 The CPAN Testers is a network of smokers who run automated tests on
421 uploaded CPAN distributions.
422 <http://www.cpantesters.org/distro/P/POE-Component-SSLify>
424 • CPAN Testers Matrix
426 The CPAN Testers Matrix is a website that provides a visual
428 overview of the test results for a distribution on various
429 Perls/platforms.
430 <http://matrix.cpantesters.org/?dist=POE-Component-SSLify>
432 • CPAN Testers Dependencies
434 The CPAN Testers Dependencies is a website that shows a chart of
436 the test results of all dependencies for a distribution.
437 <http://deps.cpantesters.org/?module=POE::Component::SSLify>
439 Email
441 You can email the author of this module at "APOCAL at cpan.org" asking
442 for help with any problems you have.
443 Internet Relay Chat
445 You can get live help by using IRC ( Internet Relay Chat ). If you
446 don't know what IRC is, please read this excellent guide:
447 <http://en.wikipedia.org/wiki/Internet_Relay_Chat>. Please be courteous
448 and patient when talking to us, as we might be busy or sleeping! You
449 can join those networks/channels and get help:
450 • irc.perl.org
452 You can connect to the server at 'irc.perl.org' and join this
454 channel: #perl-help then talk to this person for help: Apocalypse.
455 • irc.freenode.net
457 You can connect to the server at 'irc.freenode.net' and join this
459 channel: #perl then talk to this person for help: Apocal.
460 • irc.efnet.org
462 You can connect to the server at 'irc.efnet.org' and join this
464 channel: #perl then talk to this person for help: Ap0cal.
465 Bugs / Feature Requests
467 Please report any bugs or feature requests by email to
468 "bug-poe-component-sslify at rt.cpan.org", or through the web interface
469 at
470 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-SSLify>.
471 You will be automatically notified of any progress on the request by
472 the system.
473 Source Code
475 The code is open to the world, and available for you to hack on. Please
476 feel free to browse it and play with it, or whatever. If you want to
477 contribute patches, please send me a diff or prod me to pull from your
478 repository :)
479 <https://github.com/apocalypse/perl-poe-sslify>
481 git clone https://github.com/apocalypse/perl-poe-sslify.git
483
485 Apocalypse <APOCAL@cpan.org>
486
488 Original code is entirely Rocco Caputo ( Creator of POE ) -> I simply
489 packaged up the code into something everyone could use and accepted the burden
490 of maintaining it :)
491 From the PoCo::Client::HTTP code =]
493 # This code should probably become a POE::Kernel method,
494 # seeing as it's rather baroque and potentially useful in a number
495 # of places.
496 ASCENT also helped a lot with the nonblocking mode, without his hard
498 work this module would still be stuck in the stone age :)
499 A lot of people helped add various features/functions - please look at
501 the changelog for more detail.
502
504 This software is copyright (c) 2014 by Apocalypse.
505 This is free software; you can redistribute it and/or modify it under
507 the same terms as the Perl 5 programming language system itself.
508 The full text of the license can be found in the LICENSE file included
510 with this distribution.
511
513 THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
514 APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
515 HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
516 WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
517 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
518 PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE
519 OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU
520 ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
521 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
523 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR
524 CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
525 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
526 ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT
527 NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
528 SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO
529 OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY
530 HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
531perl v5.34.0 2022-01-21 POE::Component::SSLify(3pm)