Net::SSLeay::OO::SSL - OO interface to Net::SSLeay methods
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;
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.
The raw *SSL pointer. Use at your own risk.
A Net::SSLeay::OO::Context object. Automatically created if not assigned on creation of the Net::SSLeay::OO::SSL.
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.
These options are all intended to control the handshake phase of SSL negotiations.
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()
Net::SSLeay::OO::Context
use_certificate_chain_file()
set_default_cb_passwd()
These methods set up the SSL object within your process - connecting it to filehandles and so on.
Sets/Gets the file descriptor number for send and receive.
Specify the file descriptors for send and receive independently. Useful when dealing with non-socket entities such as pipes.
See SSL_set_read_ahead(3ssl)
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.
Initiate the SSL session, from the perspective of a server or a client, respectively.
Forget the current SSL session. You probably don't want to use this.
Sends a "close notify" shutdown alert to the peer. You should do this before you shut down the underlying socket.
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.
ssl_read_all
ssl_read_CRLF
ssl_read_until
SSL_peek
SSL_read
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.
$max
Like read(), but doesn't clear the data from the session buffer.
read()
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".
ssl_write_CRLF
SSL_write
Pretty much a direct method for SSL_write; writes the message and returns the number of bytes written.
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.
substr()
These methods return information about the current SSL object
Returns the error from the last IO operation, you can match this against various constants as described on SSL_get_error(3ssl).
A simpler version of get_error, see SSL_want(3ssl).
get_error
SSL_want(3ssl)
The cipher of the current session
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.
set_verify
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.
SSL_get1_session
If for some reason you want to set the session, call this method, passing a Net::SSLeay::OO::Session object.
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''
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.
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.
man -k
apropros
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)
Sam Vilain, samv@cpan.org
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>
Net::SSLeay::OO, Net::SSLeay::OO::Context, Net::SSLeay::Session
To install Net::SSLeay::OO, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::SSLeay::OO
CPAN shell
perl -MCPAN -e shell install Net::SSLeay::OO
For more information on module installation, please visit the detailed CPAN module installation guide.