Please take a look at "not-yet-commons-ssl", currently hosted here:


This java library was developed over the last year with Apache Commons
in mind.  I've been hanging out on the httpclient mailing list for 2
years, learning about https and ssl and java thanks to the
EasySSLProtocolSocketFactory and AuthSSLProtocolSocketFactory written
by Oleg Kalnichevski and Adrian Sutton.

If you google for "java ssl" you'll notice that HTTPClient is actually
the first "*.apache.org" site to appear (sometimes 2nd page, sometimes
3rd page of results):


Meanwhile if you just google for "ssl", you'll notice that "www.modssl.org" and
"www.apache-ssl.org" are on the first page of results.  Both of those
sites contain (probably older?) versions of this documentation:


As a Java developer I found these two different "ways" of setting up
SSL to be a source of confusion.  The OpenSSL/Apache documentation
about setting up SSL is very good, very handy.  But it just doesn't
work with Java, because Java only understands "JKS" files created by
"keytool".  (Oh wait...  months later I discover that Java can also
handle "PKCS #12" by pretending the file is a special type of JKS

Once I finally started to understand these two different "ways", I
started trying to build an easier way to work with both ways.  The
goal of "commons-ssl" is bridge that gap.  I also tried to make SSL
and Java easier to work with by not requiring the user to know so

With Commons-SSL the user no longer needs to know:

1.  What kind of keystore file is this?  JKS or PKCS #12?  Commons-SSL
will just figure this out on its own.  (We should probably also start
considering these newer JCEKS files, but that's not in place yet.)

2.  The user created a PKCS #12 file using "openssl" but forgot to say
"-outform DER".  Commons-SSL can still deal with that file.

3.  The user created a "Traditional SSLeay" private key instead of
PKCS8 by accident.  Commons-SSL doesn't mind.

If Commons-SSL could have a motto, I think it would be this:  "You
bring the files and the password, I'll do the rest."  Perhaps add this
sub-title:  "If your password is wrong I'll throw a

Whereas pre-Commons-SSL, Java's motto would be:  "You bring the files,
the password, make sure you know the type, and if it's PKCS #12, make
sure it's in DER.  If your RSA private key and associated X509 chain
are in separate files, you're going to have to transform them into
PEM, start up Windows Notepad to cut & paste them into a single file,
and then use 'openssl pkcs12' to get them into DER."

Perhaps add this sub-title:  "If your password is wrong I might throw
a PaddingException or a DigestException.  Depends on the vendor and
version of Java.".

That's the highest goal:  Make SSL easier for the users.  Make it
easier for those courageous souls downloading our software and running
it on their machines.

The next goal:  Make SSL easier for the developer.  In Java changing
aspects of an SSLSocketFactory or SSLServerSocketFactory is quite
awkward.  Many of the approaches in use today end up polluting the
entire JVM.  You want to connect to "https://MySelfSignedSite.com/";
and suddenly all your LDAPS and RMI-SSL and JDBC-SSL calls aren't
checking the server certificate either!  The HTTPClient group came up
with a very novel solution:  "https-easy://".

Commons-SSL tried to take this further and generalize it.  The
developer can now create a single isolated SSLSocketFactory very easy
(SSLClient extends SSLSocketFactory).

SSLClient client = new SSLCLient();

[Notice how I'm borrowing from HttpClient's own usage pattern:
HTTPClient client = new HttpClient();]

The developer can then modify that SSLSocketFactory to suit their needs:

client.setCheckHostname( false );
client.setCheckCRL( false );
client.setCheckExpiry( true );
client.setMaxTrustChainDepth( 6 );  // not yet implemented

client.addTrustMaterial( new TrustMaterial( "/path/to/cert.pem" ) );
client.setKeyMaterial( new KeyMaterial( "/path/to/key.pem",
"/path/to/certs.pem", "secret".toCharArray() ) );

That's the library!  Now some details about this "PROPOSAL" and how it
might fit in with Apache:

Meritocracy, Community:
So far, yes, it's just been me committing whenever I like.  This has
been convenient to try and get the library into a useable state.  I
think the library has good coherency because only one person has been
working on it so far.  But on the other hand, SSL is touchy stuff, and
it needs eyes looking at it.  I will never be able to declare that
"yes, this library doesn't compromise your security" by myself.  I
think I'm ready to let go now, and let others extend this in exciting

The flip side of this requirement:  I like to think I would make a
good member of the Apache Community!  I generally try to post helpful
emails to some of the mailing lists.  So while Commons-SSL doesn't
have much of a community around it yet, HttpClient and other projects
might enjoy having me around!  [Mind you, I'm staying around on those
mailing lists whether you accept this code or not.  So it's not much
of an argument for accepting the code.  :-p]

Core Developers:
Definitely a weak spot with Commons-SSL right now.  There's only me.
Some people hanging out on the HTTPClient mailing list have shown
interest in *using* the library, but no-one has time to start writing

Still, SSL is a fun little niche.  I imagine a few people will show up
eventually, whether I'm around or not!  I'm a shameless optimist.

Alignment with existing Apache subprojects
Here's where Commons-SSL is very strong.  It's actually allowing all
these server-socket-creating Java applications so point to the Apache
httpd TLS FAQ!  We're actually bridging an old split, between OpenSSL
and Sun's Java, perhaps like the Pope's visit to Turkey right now?

In terms of code use:   we're using code from directory.apache.org,
we've also using code from commons-codec.  In terms of helping other
projects:  Commons-SSL has lots of hooks in place for HTTPClient, and
anyone who uses SSLSocketFactory or SSLServerSocketFactory can drop
Commons-SSL into their project quite seamlessly.

I think Commons-SSL would be good for many open-source projects.  Here
are a few ideas:

http://directory.apache.org/  (to help when being an ldaps:// server)
http://tomcat.apache.org/  (so support APR-SSL config when APR isn't around)

That's just the server side.  It's very handy on the client side, too.
Already two open source projects (that I know of) are using


There's one last topic to address in this proposal:

Where Should Commons-SSL Ultimately Live?
First there's the question of Incubation, or Sandbox.  I quite like
Incubation because it provides an ideal "software project template".
That's my way of understanding it.  Incubation shoots for perfection.
While I don't think I can achieve perfection, I like to try.

Sandbox, on the other hand, seems to be a quicker way to bring the
code into the family.  It's probably more suitable for small projects
like this, whereas Incubation is more geared for larger projects like
"directory.apache.org" (congratulations on their graduation!).  But
even a small project can benefit from implementing the many high goals
and excellent thinking that's been put into Incubation.  Personally I
don't really know which I prefer.  I guess the fact that I'm just a
single developer makes me lean towards sandbox.  Suddenly a lot of
apache people will be able to commit to Commons-SSL!  That's exciting.

Unless I attract some pretty motivated people to this project quite
soon, incubation will take a long time.  I have a day job, a family.
Like all of us, I don't have as much time as I would like for
Commons-SSL.  But it's just a mild leaning towards sandbox.  I'm very
happy with either.

Aside from the question of Sandbox or Incubation, there's also the
question of final destination.

I can think of three places:

#1.  commons

#2.  http-components

#3.  commons-net

#1 - Commons seems the most obvious place to me, but #2 -
Http-Components also seems like a very interesting chioce.  I don't
know enough about #3 - commons-net to really comment, but it seems
worth including in the list.

#2 - http-components is especially interesting because two features of
SSL depend strongly on HTTP:   CRL checking and OCSP.  It would be
weird to have people downloading http-components so that they can
create SSLServerSockets!  But there is a lot of overlap, and "https"
is definitely the most varied and uhh... "exciting" arena for
interesting SSL problems these days.

Probably if we're shooting for purity-of-design, commons is the safe
bet.  But lumping in with http-components like a good old-fashioned
"static linking" good make for an interesting experiment.  We could
unwind it at a future date if we didn't like it.  (Famous last words.
Note:  I didn't say we could unwind it "easily"!).

I'm going to just leave this email as a "PROPOSAL" for now, and let
people on [EMAIL PROTECTED] transform this into the many votes it
probably needs.  I guess it needs at least these three separate votes:

1.  Vote to accept the code in some fashion.

2.  Vote for Incubation or Sandbox.

3.  Vote for final destination.

Oh, one final note.  If this gets sandboxed, I don't need to be a
committer at this time.  I'm more than happy to just email patches.


Julius Davies

To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]

Reply via email to