Debian Codegraph @

README

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