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
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.
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_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.
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.
read(), but doesn't clear the data from the session buffer.
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".
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.
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
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
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.
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.
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, email@example.com
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>