/ 
Net-SSLeay-OO-0.01
River stage zero No dependents
/ Net::SSLeay::OO::Context

NAME

Net::SSLeay::OO::Context - OO interface to Net::SSLeay CTX_ methods

SYNOPSIS

use Net::SSLeay::OO::Constants qw(OP_ALL FILETYPE_PEM OP_NO_SSLv2);
use Net::SSLeay::OO::Context;

# create an SSL object, disable SSLv2
my $ctx = Net::SSLeay::OO::Context->new;
$ctx->set_options(OP_ALL & OP_NO_SSLv2);

# specify path to your CA certificates for verifying peer
$ctx->load_verify_locations($ca_filename, $db_dir);

# optional for clients - load our own certificate/key
$ctx->use_certificate_chain_file($cert_filename);
$ctx->use_PrivateKey_file($key_filename, FILETYPE_PEM);

# optional for servers - require peer certificates
$ctx->set_verify(VERIFY_PEER & VERIFY_FAIL_IF_NO_PEER_CERT);

# now make SSL objects with these options!
use Net::SSLeay::OO::SSL;
my $ssl = Net::SSLeay::OO::SSL->new( ctx => $ctx );

# convenience method for the above, plus attach to a socket
my $ssl = $ctx->new_ssl($socket);

DESCRIPTION

Every SSL connection has a context, which specifies various options. You can also specify these options on Net::SSLeay::OO::SSL objects, but you would normally want to set up as much as possible early on, then re-use the context to create new SSL handles.

The OpenSSL library initialization functions are called the first time that a Net::SSLeay::OO::Context object is instantiated.

ATTRIBUTES

ctx : Int

The raw ctx object. Use at your own risk.

ssl_version: ( undef | 2 | 3 | 10 )

Specify the SSL version to allow. 10 means TLSv1, 2 and 3 mean SSLv2 and SSLv3, respectively. No options means 'SSLv23'; if you want to permit the secure protocols only (SSLv3 and TLSv1) you need to use:

use Net::SSLeay::OO::Constants qw(OP_NO_SSLv2);
my $ctx = Net::SSLeay::OO::Context->new();
$ctx->set_options( OP_NO_SSLv2 )

This option must be specified at object creation time.

METHODS

All of the CTX_ methods in Net::SSLeay are converted to methods of the Net::SSLeay::OO::Context 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

set_options(OP_XXX | OP_XXX ...)

Set options that apply to this Context. The valid values and descriptions can be found on SSL_CTX_set_options(3ssl); for this module they must be imported from Net::SSLeay::OO::Constants.

get_options()

Returns the current options bitmask; mask with the option you're interested in to see if it is set:

unless ($ctx->get_options & OP_NO_SSLv2) {
    die "SSL v2 was not disabled!";
}
load_verify_locations($filename, $path)

Specify where CA certificates in PEM format are to be found. $filename is a single file containing one or more certificates. $path refers to a directory with 9d66eef0.1 etc files as would be made by c_rehash. See SSL_CTX_load_verify_locations(3ssl).

set_default_verify_paths()

Sets up system-dependent certificate store location. This is probably quite a good default.

set_verify($mode, [$verify_callback])

Mode should be either VERIFY_NONE, or a combination of VERIFY_PEER, VERIFY_CLIENT_ONCE and/or VERIFY_FAIL_IF_NO_PEER_CERT. If you don't set this as a server, you cannot later call ->get_peer_certificate to find out if the client configured a certificate (though there are references to repeating SSL negotiation, eg in SSL_read(3ssl), not sure how this is performed though).

During the handshake phase, the $verify_callback is called once for every certificate in the chain of the peer, starting with the root certificate. Each time, it is passed two arguments: the first a boolean (1 or 0) which indicates whether the in-built certificate verification passed, and the second argument is the actual certficate which is being verified (a Net::SSLeay::OO::X509 object). Note this is different to the calling convention of OpenSSL and Net::SSLeay, which instead (logically, anyway) pass a Net::SSLeay::OO::X509::Context object. However there is little of interest in this other object, so for convenience the current certificate is passed instead as the second object. The Net::SSLeay::OO::X509::Context is passed as a third argument should you need it.

The passed Net::SSLeay::OO::X509 object will not work outside of the callback; get everything out of it that you need inside it, or use the get_peer_certificate method of Net::SSLeay::OO::SSL later.

Example:

my @names;
$ctx->set_verify(VERIFY_PEER, sub {
    my ($ok, $x509) = @_;
    push @names, $x509->subject_name->cn;
    return $ok;
});

$ssl = $ctx->new_ssl($fd);
$ssl->accept();

print "Client identity chain: @names\n";
use_certificate_file($filename, $type)

$filename is the name of a local file. This becomes your local cert - client or server.

$type may be FILETYPE_PEM or FILETYPE_ASN1.

use_certificate_chain_file($filename)

$filename is the name of a local PEM file, containing a chain of certificates which lead back to a valid root certificate. In general, this is the more useful method of loading a certificate.

use_PrivateKey_file($filename, $type);

If using a certificate, you need to specify the private key of the end of the chain. Specify it here; set $type as with use_certificate_file

Setup methods

set_mode($mode)
get_mode

Sets/gets the mode of SSL objects created from this context. See SSL_set_mode(3ssl). This is documented more fully at "set_mode" in Net::SSLeay::OO::SSL

Handshake/SSL session methods

new_ssl($socket)

Makes a new Net::SSLeay::OO::SSL object using this Context, and attach it to the given socket (if passed).

connect($socket)
accept($socket)

Further convenience methods, which create a new Net::SSLeay::OO::SSL object, wire it up to the passed socket, then call either connect or accept. Returns the Net::SSLeay::OO::SSL object.

Informative methods

get_cert_store()

Returns the Net::SSLeay::OO::X509::Store associated with this context.

un-triaged

The following methods were defined in Net::SSLeay 1.35, and may work via this interface.

v2_new()
v3_new()
v23_new()
tlsv1_new()
new_with_method(meth)
add_session(ctx,ses)
remove_session(ctx,ses)
flush_sessions(ctx,tm)
use_RSAPrivateKey_file(ctx,file,type)
set_cipher_list(s,str)
ctrl(ctx,cmd,larg,parg)
get_options(ctx)
set_options(ctx,op)
sessions(ctx)
sess_number(ctx)
sess_connect(ctx)
sess_connect_good(ctx)
sess_connect_renegotiate(ctx)
sess_accept(ctx)
sess_accept_renegotiate(ctx)
sess_accept_good(ctx)
sess_hits(ctx)
sess_cb_hits(ctx)
sess_misses(ctx)
sess_timeouts(ctx)
sess_cache_full(ctx)
sess_get_cache_size(ctx)
sess_set_cache_size(ctx,size)
add_client_CA(ctx,x)
callback_ctrl(ctx,i,fp)
check_private_key(ctx)
get_ex_data(ssl,idx)
get_quiet_shutdown(ctx)
get_timeout(ctx)
get_verify_depth(ctx)
get_verify_mode(ctx)
set_cert_store(ctx,store)
get_cert_store(ctx)
set_cert_verify_callback(ctx,func,data=NULL)
set_client_CA_list(ctx,list)
set_default_passwd_cb(ctx,func=NULL)
set_default_passwd_cb_userdata(ctx,u=NULL)
set_ex_data(ssl,idx,data)
set_purpose(s,purpose)
set_quiet_shutdown(ctx,mode)
set_ssl_version(ctx,meth)
set_timeout(ctx,t)
set_trust(s,trust)
set_verify_depth(ctx,depth)
use_RSAPrivateKey(ctx,rsa)
get_ex_new_index(argl,argp,new_func,dup_func,free_func)
set_session_id_context(ctx,sid_ctx,sid_ctx_len)
set_tmp_rsa_callback(ctx, cb)
set_tmp_dh_callback(ctx, dh)
add_extra_chain_cert(ctx,x509)
get_app_data(ctx)
get_mode(ctx)
get_read_ahead(ctx)
get_session_cache_mode(ctx)
need_tmp_RSA(ctx)
set_app_data(ctx,arg)
set_mode(ctx,op)
set_read_ahead(ctx,m)
set_session_cache_mode(ctx,m)
set_tmp_dh(ctx,dh)
set_tmp_rsa(ctx,rsa)

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::Constants, Net::SSLeay::SSL, Net::SSLeay::OO::X509, Net::SSLeay::Error