[Net-ssleay-devel] [ANNOUNCE] Net::SSLeay::OO 0.01 - Moose interface for OpenSSL

Tue Oct 6 07:40:13 UTC 2009

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hello all,

It is with pleasure that I announce the first release of the
Net::SSLeay::OO module to CPAN.  Don't put up with dealing with raw
pointer refs and explicit namespaces any longer!  It's new, it's
improved, it's old-fashioned!

Get with:

  perl -MCPAN::Github -le 'install "Net::SSLeay::OO-(Any)-CATALYST"'

Actually that's a lie!  But wouldn't it be nice!

However, Net::SSLeay::OO is real software!  It comes with one
example!  And several tests!  And a disclaimer!

So download and install it with real software:

  perl -MCPAN -e 'install "Net::SSLeay::OO"'

Or:

  git clone git://github.com/catalyst/Net-SSLeay-OO.git

But wait!  There's more!  The release announcement even ships with an
embedded copy of the man page so you don't have to do anything to get
a flavour of it!  Yes ladies and gentlemen, by simply reading the rest
of this e-mail you will have read that man page!  So what are you
waiting for?  Scroll down!

NAME
    Net::SSLeay::OO - OO Calling Method for Net::SSLeay

SYNOPSIS
     use Net::SSLeay::OO;

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

     my $ctx = Net::SSLeay::OO::Context->new;
     $ctx->set_options(OP_ALL & OP_NO_TLSv2);
     $ctx->load_verify_locations("", "/etc/ssl/certs");

     # get a socket/stream somehow
     my $socket = IO::Socket::INET->new(...);

     # create a new SSL object, and attach it to the socket
     my $ssl = Net::SSLeay::OO::SSL->new(ctx => $ctx);
     $ssl->set_fd($socket);

     # initiate the SSL connection
     $ssl->connect;

     # exchange data ... be sure to read the man page
     my $wrote = $ssl->write($data, $size);
     my $bytes_read = $ssl->read(\$buf, $size);

     # close...
     $ssl->shutdown;
     $socket->shutdown(1);

DESCRIPTION
    This set of modules adds an OO calling convention to the Net::SSLeay
    module. It steers away from overly abstracting things, or adding new
    behaviour, instead just making the existing functionality easier
to use.

    What does this approach win you over Net::SSLeay?

    Object Orientation
        For a start, you get a blessed object rather than an integer
to work
        with, so you know what you are dealing with. All of the functions
        which were callable with "Net::SSLeay::foo($ssl, @args)" will then
        be callable as plain "$ssl->foo(@args)".

    Namespaces
        The OpenSSL functions use a C-style namespace convention, where
        functions are prefixed by the type of the object that they operate
        on. OpenSSL has several types of objects, such as a "Context"
(this
        is a bit like a bunch of pre-defined connection settings), and
        various classes relating to X509, sessions, etc.

        This module splits up the functions which Net::SSLeay binds into
        Perl based on the naming convention, then sets up wrappers for
them
        so that you can just call methods on objects.

    Exceptions
        If an error is raised by the OpenSSL library, an exception is
        immediately raised (trappable via "eval") which pretty-prints into
        something presented a little less cryptic than OpenSSL's
        ":"-delimited error string format.

    fewer segfaults
        This is currently more of a promise than a reality; but eventually
        each of the access methods for the various objects will be able to
        know their lifetime in a robust fashion, so you should get less
        segfaults. Eg, some SSL functions don't return object references
        which are guaranteed to last very long, so if you wait too long
        before getting properties from them you will get a segfault.

    On the flip side, what does this approach win you over other simpler
    APIs such as IO::Socket::SSL? Well, I guess it comes down to "Make
    things as simple as possible, but no simpler".

    Most SSL socket libraries tend to try to hide complexity from you, but
    there really are things that you should consider; such as,
shouldn't you
    be validating the other end of your SSL connection has a valid
    certificate? Which SSL versions do you wish to allow?

    IO::Socket::SSL lets you specify a lot of this stuff, but it's not a
    very earnest implementation; it's just treated as a few extra options
    passed to the constructor, a bit of magic at socket setup time,
and then
    hope that this will be enough. The support for verifying client
    certificates didn't even work when I tested it.

    On the other hand, using the OpenSSL API fully means you are taken
    through the stages of setup piece by piece. You can easily do things
    like check that your SSL configuration (eg server certificate) is
valid
    *before* you start daemonize or start accepting real sockets.

    I'll try to keep the documentation as complete as possible - there's
    nothing more annoying than thin wrapper libraries which don't help
much
    people trying to use them. But in general, most functions available in
    the OpenSSL manual will be available.

DISTRIBUTION OVERVIEW / PACKAGES
    This is a brief overview of the packages in this module, so that you
    know where to start.

    Net::SSLeay::OO::Context (C: "SSL_CTX*")
        The context object represents an individual configuration of the
        OpenSSL library. Normally, you'll create one of these as you
verify
        the configuration of your program - eg for a server, setting
the CA
        certificates directory, and setting various other bits and bobs.

    Net::SSLeay::OO::SSL (C: "SSL*")
        You have one of these per connection, and when you create one
it is
        tied to a Context object, taking defaults from the Context object.
        Many settings can be made either on the Context object or the SSL
        object. Once you have created this object, you attach it to a
        filehandle/socket and then call either "accept" or "connect",
        depending on which SSL role you are playing in the connection.

    Net::SSLeay::OO::Constants
        This module allows you to explicitly import SSLeay/OpenSSL
constants
        for passing to various API methods, so that you don't have to
        specify the complete namespace to them.

    Net::SSLeay::OO::Error (C: <unsigned long>)
        This class represents an error from OpenSSL, actually a stack of
        errors. These are raised and printed pretty transparently, but if
        you want to pick apart the details of the error you can do so.
There
        is no corresponding C struct, but the "ERR_*" man pages (try
"man -k
        ERR_") handle the integers that OpenSSL passes around
internally as
        error codes.

    Net::SSLeay::OO::X509 (C: "X509*")
        This class represents a certificate. You can't create these with
        this module, because of a lack of bindings in Net::SSLeay, but
        various things will return them.

    Net::SSLeay::OO::X509::Name (C: "X509_NAME*")
        Retrieving things like the "issuer name" from X509 certificates
        returns one of these objects; you can then call "->oneline" on it,
        or print it to your requirements, to get a usable string.

    Net::SSLeay::OO::X509::Store (C: "X509_STORE*")
        This class represents a certificate store. This would normally
        represent a local directory with certificates in it. Currently the
        only way to get one of these is with "get_cert_store" in
        Net::SSLeay::OO::Context.

    Net::SSLeay::OO::X509::Context (C: "X509_STORE_CTX*")
        This is a type of object that you get back during certificate
        verification. You probably don't need to use this class unless you
        want certificate verification to fail based on custom rules during
        the actual handshake.

    Net::SSLeay::OO::Session (C: "SSL_SESSION*")
        This seems to represent an actual SSL session; ie, after
"accept" or
        "connect" has succeeded. This is a pretty uninteresting class.
About
        all you can do with it is pull out or alter the time the SSL
session
        was established, and session timeouts.

    Net::SSLeay::OO::Functions
        This is the internal class which splits up the functions in
        Net::SSLeay into class-specific packages.

    "Net::SSLeay::OO::BIO"
    "Net::SSLeay::OO::Cipher"
    "Net::SSLeay::OO::Compression"
    "Net::SSLeay::OO::PRNG"
    "Net::SSLeay::OO::Engine"
    "Net::SSLeay::OO::PrivateKey"
    "Net::SSLeay::OO::PEM"
    "Net::SSLeay::OO::KeyType::DH"
    "Net::SSLeay::OO::KeyType::RSA"
        These classes are currently all TO-DO. All I've done is earmarked
        these packages in Net::SSLeay::OO::Functions as recipients for the
        corresponding Net::SSLeay functions. There's not a lot of
        boilerplate that has to be implemented to make them work, take a
        look at some of the implementations of some of the X509 classes to
        see how short it can be. If you make them work, with a test suite,
        send them to me and I'll include them in this distribution.

AUTHOR AND LICENCE
    All code in the Net::SSLeay::OO distribution is written by Sam Vilain,
    sam.vilain at catalyst.net.nz. Development commissioned by NZ Registry
    Services.

    Copyright 2009, NZ Registry Services. This module is licensed
under the
    Artistic License v2.0, which permits relicensing under other Free
    Software licenses.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkrK9FsACgkQ/AZAiGayWEM1PwCdGS8Ja9JJJu/K9UTgK81L1vDn
9BgAoMtQDYMTCbPeGiL7IBf7STW7OonG
=j/gJ
-----END PGP SIGNATURE-----