1POE::Component::SSLify(U3spemr)Contributed Perl DocumentPaOtEi:o:nComponent::SSLify(3pm)
2
3
4

NAME

6       POE::Component::SSLify - Makes using SSL in the world of POE easy!
7

VERSION

9         This document describes v1.012 of POE::Component::SSLify - released November 14, 2014 as part of POE-Component-SSLify.
10

SYNOPSIS

12               # look at the DESCRIPTION for client and server example code
13

DESCRIPTION

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
19   Client usage
20               # Import the module
21               use POE::Component::SSLify qw( Client_SSLify );
22
23               # Create a normal SocketFactory wheel and connect to a SSL-enabled server
24               my $factory = POE::Wheel::SocketFactory->new;
25
26               # 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
34               # Now, hand it off to ReadWrite
35               my $rw = POE::Wheel::ReadWrite->new(
36                       Handle  =>      $socket,
37                       # other options as usual
38               );
39
40   Server usage
41               # !!! Make sure you have a public key + certificate
42               # excellent howto: http://www.akadia.com/services/ssh_test_certificate.html
43
44               # Import the module
45               use POE::Component::SSLify qw( Server_SSLify SSLify_Options );
46
47               # 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
53               # Create a normal SocketFactory wheel to listen for connections
54               my $factory = POE::Wheel::SocketFactory->new;
55
56               # 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
64               # Now, hand it off to ReadWrite
65               my $rw = POE::Wheel::ReadWrite->new(
66                       Handle  =>      $socket,
67                       # other options as usual
68               );
69

FUNCTIONS

71   Client_SSLify
72       This function sslifies a client-side socket. You can pass several
73       options to it:
74
75               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
83                       # 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
91                               # The return value from the callback is discarded
92                       }
93
94       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
99       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
103       NOTE: The way to have a client socket with proper certificates set up
104       is:
105
106               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
110       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
114               # 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
125               # the callback event
126               sub event_sslify_result {
127                       my ($creation_args, $called_args) = @_[ARG0, ARG1];
128                       my( $socket, $status, $errval ) = @$called_args;
129
130                       if ( $status ) {
131                               print "Yay, SSLification worked!";
132                       } else {
133                               print "Aw, SSLification failed with error $errval";
134                       }
135               }
136
137   Server_SSLify
138       This function sslifies a server-side socket. You can pass several
139       options to it:
140
141               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
147       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
150               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
155       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
158       Please look at "Client_SSLify" for more details on the callback hook.
159
160   SSLify_ContextCreate
161       Accepts some options, and returns a brand-new Net::SSLeay context
162       object ( $ctx )
163
164               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
170       You can then call various Net::SSLeay methods on the context
171
172               my $mode = Net::SSLeay::CTX_get_mode( $ctx );
173
174       By default we don't use the SSL key + certificate files
175
176       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
180               * sslv2
181               * sslv3
182               * tlsv1
183               * sslv23
184               * default ( sslv23 )
185
186       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
190   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
195               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
201       By default we use the version: default
202
203       By default we use the options: Net::SSLeay::OP_ALL
204
205       Please look at "SSLify_ContextCreate" for more info on the available
206       versions/options.
207
208   SSLify_GetCTX
209       Returns the actual Net::SSLeay context object in case you wanted to
210       play with it :)
211
212       If passed in a socket, it will return that socket's $ctx instead of the
213       global.
214
215               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
218   SSLify_GetCipher
219       Returns the cipher used by the SSLified socket
220
221               print "SSL Cipher is: " . SSLify_GetCipher( $sslified_sock ) . "\n";
222
223       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
228               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
240   SSLify_GetSocket
241       Returns the actual socket used by the SSLified socket, useful for stuff
242       like getpeername()/getsockname()
243
244               print "Remote IP is: " . inet_ntoa( ( unpack_sockaddr_in( getpeername( SSLify_GetSocket( $sslified_sock ) ) ) )[1] ) . "\n";
245
246   SSLify_GetSSL
247       Returns the actual Net::SSLeay object so you can call methods on it
248
249               print Net::SSLeay::dump_peer_certificate( SSLify_GetSSL( $sslified_sock ) );
250
251   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
256               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

NOTES

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
268   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
273               eval { use POE::Component::SSLify };
274               if ( $@ ) {
275                       $sslavailable = 0;
276               } else {
277                       $sslavailable = 1;
278               }
279
280               # 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
288       $IGNORE_SSL_ERRORS
289
290       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
296               {
297                       local $POE::Component::SSLify::IGNORE_SSL_ERRORS=1;
298                       my $ctx = SSLify_CreateContext(...);
299                       #Some more stuff
300               }
301
302   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
307       Net::SSLeay::renegotiate
308
309       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
317       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
321   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
327   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
331   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
338   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
345               sub POE::Component::SSLify::LOAD_SSL_ENGINES () { 1 }
346               use POE::Component::SSLify qw( Client::SSLify );
347

EXPORT

349       Stuffs all of the functions in @EXPORT_OK so you have to request them
350       directly.
351

SEE ALSO

353       Please see those modules/websites for more information related to this
354       module.
355
356       •   POE
357
358       •   Net::SSLeay
359

SUPPORT

361   Perldoc
362       You can find documentation for this module with the perldoc command.
363
364         perldoc POE::Component::SSLify
365
366   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
371       •   MetaCPAN
372
373           A modern, open-source CPAN search engine, useful to view POD in
374           HTML format.
375
376           <http://metacpan.org/release/POE-Component-SSLify>
377
378       •   Search CPAN
379
380           The default CPAN search engine, useful to view POD in HTML format.
381
382           <http://search.cpan.org/dist/POE-Component-SSLify>
383
384       •   RT: CPAN's Bug Tracker
385
386           The RT ( Request Tracker ) website is the default bug/issue
387           tracking system for CPAN.
388
389           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Component-SSLify>
390
391       •   AnnoCPAN
392
393           The AnnoCPAN is a website that allows community annotations of Perl
394           module documentation.
395
396           <http://annocpan.org/dist/POE-Component-SSLify>
397
398       •   CPAN Ratings
399
400           The CPAN Ratings is a website that allows community ratings and
401           reviews of Perl modules.
402
403           <http://cpanratings.perl.org/d/POE-Component-SSLify>
404
405       •   CPAN Forum
406
407           The CPAN Forum is a web forum for discussing Perl modules.
408
409           <http://cpanforum.com/dist/POE-Component-SSLify>
410
411       •   CPANTS
412
413           The CPANTS is a website that analyzes the Kwalitee ( code metrics )
414           of a distribution.
415
416           <http://cpants.cpanauthors.org/dist/overview/POE-Component-SSLify>
417
418       •   CPAN Testers
419
420           The CPAN Testers is a network of smokers who run automated tests on
421           uploaded CPAN distributions.
422
423           <http://www.cpantesters.org/distro/P/POE-Component-SSLify>
424
425       •   CPAN Testers Matrix
426
427           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
431           <http://matrix.cpantesters.org/?dist=POE-Component-SSLify>
432
433       •   CPAN Testers Dependencies
434
435           The CPAN Testers Dependencies is a website that shows a chart of
436           the test results of all dependencies for a distribution.
437
438           <http://deps.cpantesters.org/?module=POE::Component::SSLify>
439
440   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
444   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
451       •   irc.perl.org
452
453           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
456       •   irc.freenode.net
457
458           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
461       •   irc.efnet.org
462
463           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
466   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
474   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
480       <https://github.com/apocalypse/perl-poe-sslify>
481
482         git clone https://github.com/apocalypse/perl-poe-sslify.git
483

AUTHOR

485       Apocalypse <APOCAL@cpan.org>
486

ACKNOWLEDGEMENTS

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
492               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
497       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
500       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
506       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
509       The full text of the license can be found in the LICENSE file included
510       with this distribution.
511

DISCLAIMER OF WARRANTY

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
522       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.
531
532
533
534perl v5.34.0                      2022-01-21       POE::Component::SSLify(3pm)
Impressum