/ 
Net-SSLeay-OO-0.02
River stage zero No dependents
/ Net::SSLeay::OO::SSL

NAME

Net::SSLeay::OO::SSL - OO interface to Net::SSLeay methods

SYNOPSIS

use Net::SSLeay::OO::Constants qw(OP_ALL);
use Net::SSLeay::OO::SSL;

# basic (insecure!) use - see below
my $ssl = Net::SSLeay::OO::SSL->new;
$ssl->set_fd(fileno($socket));
$ssl->connect;

DESCRIPTION

This module adds some OO niceties to using the Net::SSLeay / OpenSSL SSL objects.

This SSL object is a per-connection entity. In general you will create one of these from a Net::SSLeay::OO::Context object which you set up for your process and perhaps configured more fully.

If you do not do that, then you are not certifying the authenticity of the peer. This means that your program will be vulnerable to MITM (man in the middle) attacks.

ATTRIBUTES

ssl : Int

The raw *SSL pointer. Use at your own risk.

ctx : Context

A Net::SSLeay::OO::Context object. Automatically created if not assigned on creation of the Net::SSLeay::OO::SSL.

METHODS

All of the methods in Net::SSLeay which are not obviously a part of some other class are converted to methods of the Net::SSLeay::OO::SSL class.

The documentation that follows is a core set, sufficient for running up a server and verifying client certificates. However most functions from the OpenSSL library are actually imported.

Handshake configuration methods

These options are all intended to control the handshake phase of SSL negotiations.

set_options( OP_XXX & OP_XXX ... )
get_options()
set_verify( $mode, [$verify_callback] )
use_certificate( Net::SSLeay::OO::X509 $cert )
use_certificate_file( $filename, $type )
use_PrivateKey_file( $filename, $type )

These functions are all very much the same as in Net::SSLeay::OO::Context but apply only to this SSL object. Note that some functions are not available, such as use_certificate_chain_file() and set_default_cb_passwd()

Setup methods

These methods set up the SSL object within your process - connecting it to filehandles and so on.

set_fd( fileno($fh) )
get_fd( fileno($fh) )

Sets/Gets the file descriptor number for send and receive.

set_rfd( fileno($fh) )
set_wfd( fileno($fh) )>

Specify the file descriptors for send and receive independently. Useful when dealing with non-socket entities such as pipes.

set_read_ahead( $boolean )
get_read_ahead()

See SSL_set_read_ahead(3ssl)

set_mode( $mode )
get_mode()

Sets/gets the mode of the SSL object. See SSL_set_mode(3ssl). If you want non-blocking use, set:

$ssl->set_mode( MODE_ENABLE_PARTIAL_WRITE |
                MODE_ACCEPT_MOVING_WRITE_BUFFER );

See t/05-non-blocking.t for a more complete example of using this library in non-blocking mode. Note you still need to mark the underlying filehandle as non-blocking.

Handshake/SSL session methods

accept()
connect()

Initiate the SSL session, from the perspective of a server or a client, respectively.

clear()

Forget the current SSL session. You probably don't want to use this.

shutdown()

Sends a "close notify" shutdown alert to the peer. You should do this before you shut down the underlying socket.

IO functions

ssl_read_all
ssl_read_CRLF( $max_length? )
ssl_read_until( $delimit?, $max_length? )

These are Net::SSLeay wrappers to the OpenSSL read methods; use these if you are not sure how to use the other ones. These are blocking calls. Note that ssl_read_all will read from the socket until the remote end shuts down. ssl_read_CRLF and ssl_read_until use the undocumented OpenSSL function SSL_peek to read the entire pending buffer, figure out at what point the delimiter appears and then SSL_read just enough to clear that.

read($max?)

Perform and return read of the rest of the next SSL record, or $max bytes, whichever is smaller. How large that record is depends on the sender, but you need to receive an entire record before you can extract any data from it anyway.

peek($max?)

Like read(), but doesn't clear the data from the session buffer.

ssl_write_all($message)
ssl_write_CRLF($line)

Convenience wrappers for writing a message or a single line to the socket via SSL. Note that ssl_write_CRLF sends the CRLF two-byte sequence to OpenSSL in its own SSL_write function call, with a comment warning that this "uses less memory but might use more network packets".

write($message)

Pretty much a direct method for SSL_write; writes the message and returns the number of bytes written.

write_partial($from, $count, $message)

Writes a substring of the message and returns the number of bytes written.

This interface is probably unnecessary since about Perl 5.8.1, as on those perls substr() can refer to substrings of other strings.

Informative methods

These methods return information about the current SSL object

get_error

Returns the error from the last IO operation, you can match this against various constants as described on SSL_get_error(3ssl).

want

A simpler version of get_error, see SSL_want(3ssl).

get_cipher

The cipher of the current session

get_peer_certificate

Returns a Net::SSLeay::OO::X509 object corresponding to the peer certificate; if you're a client, it's the server certificate. If you're a server, it's the client certificate, if you requested it during handshake with set_verify.

get_session

Returns a Net::SSLeay::OO::Session object corresponding to the SSL session. This actually calls SSL_get1_session to try to help save you from segfaults.

set_session($session)

If for some reason you want to set the session, call this method, passing a Net::SSLeay::OO::Session object.

state_string
state_string_long

Return a codified or human-readable string 'indicating the current state of the SSL object'.

SSL_state_string(3ssl) sez ''Detailed description of possible states to be included later''

rstate_string
rstate_string_long

Return information about the read state. In a blocking environment, this should always return "RD" or "read done". Otherwise, you'll get something else possibly informative.

Un-triaged

The following methods I haven't looked at at all; if you use them in a program, please submit a patch which moves them into one of the above categories. The best information about them will be found on the relevant SSL man page - use man -k or apropros to find a useful man page.

My policy on these is that no function should take an unwrapped pointer argument or return an unwrapped pointer. So long as the function you use doesn't do that, you can reasonably expect its call interface not to change; but of course I place no guarantees should OpenSSL or Net::SSLeay ruin your day.

set_cipher_list($list)
add_client_CA(ssl,x)
alert_desc_string(value)
alert_desc_string_long(value)
alert_type_string(value)
alert_type_string_long(value)
callback_ctrl(ssl,i,fp)
check_private_key(ctx)
do_handshake(s)
dup(ssl)
get_current_cipher(s)
get_default_timeout(s)
get_ex_data(ssl,idx)
get_finished(s,buf,count)
get_peer_finished(s,buf,count)
get_quiet_shutdown(ssl)
get_shutdown(ssl)
get_verify_depth(s)
get_verify_mode(s)
get_verify_result(ssl)
renegotiate(s)
set_accept_state(s)
set_client_CA_list(s,list)
set_connect_state(s)
set_ex_data(ssl,idx,data)
set_info_callback(ssl,cb)
set_purpose(s,purpose)
set_quiet_shutdown(ssl,mode)
set_shutdown(ssl,mode)
set_trust(s,trust)
set_verify_depth(s,depth)
set_verify_result(ssl,v)
version(ssl)
load_client_CA_file(file)
add_file_cert_subjects_to_stack(stackCAs,file)
add_dir_cert_subjects_to_stack(stackCAs,dir)
set_session_id_context(ssl,sid_ctx,sid_ctx_len)
set_tmp_rsa_callback(ssl, cb)
set_tmp_dh_callback(ssl,dh)
get_ex_new_index(argl, argp, new_func, dup_func, free_func)
clear_num_renegotiations(ssl)
get_app_data(s)
get_cipher_bits(s,np)
get_mode(ssl)
get_state(ssl)
need_tmp_RSA(ssl)
num_renegotiations(ssl)
session_reused(ssl)
set_app_data(s,arg)
set_mode(ssl,op)
set_pref_cipher(s,n)
set_tmp_dh(ssl,dh)
set_tmp_rsa(ssl,rsa)
total_renegotiations(ssl)
get_client_random(s)
get_server_random(s)
get_keyblock_size(s)
set_hello_extension(s, type, data)
set_session_secret_cb(s,func,data=NULL)

AUTHOR

Sam Vilain, samv@cpan.org

COPYRIGHT

Copyright (C) 2009 NZ Registry Services

This program is free software: you can redistribute it and/or modify it under the terms of the Artistic License 2.0 or later. You should have received a copy of the Artistic License the file COPYING.txt. If not, see <http://www.perlfoundation.org/artistic_license_2_0>

SEE ALSO

Net::SSLeay::OO, Net::SSLeay::OO::Context, Net::SSLeay::Session