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