incubator-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <>
Subject [Incubator Wiki] Update of "CommonsSSLProposal" by JuliusDavies
Date Fri, 09 Mar 2007 14:44:56 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Incubator Wiki" for change notification.

The following page has been changed by JuliusDavies:

New page:
= Abstract =

Commons-SSL makes SSL and Java easier.

Target:    Jakarta Commons
Sponsor:   Incubator
Champion:  Martin van den Bemt <>
Mentor:    Martin van den Bemt <>
Resources: SVN:
           Mailing lists:

Initial committers:
           Julius Davies <>,
           Oleg Kalnichevski <>

Initial source:     

Technologies:       Java 1.3, Java 1.4, Java 5, Java 6, JSSE, JCE

= Proposal =

Commons-SSL gives developers control over many TLS/SSL options, including:

 * Client Authentication (using PKCS 12, Java Keystore, or OpenSSL private key formats).
 * Managing trust without touching Java's {{{jre/lib/security/cacerts}}} file.
 * Enable/Disable Hostname Checking (CN, and subjectAlt, with or without wildcards).
 * Enable/Disable Certificate Expiry Checking.
 * Enable/Disable CRL checking.
 * Enable/Disable OCSP checking.
 * Enable/Disable Weak Ciphers.

Commons-SSL generates SSL``Socket``Factory, SSL``Server``Socket``Factory, and SSL``Context
objects for consumers to drop into their existing code bases.

Commons-SSL also includes some command-line utilities to help people with common problems:

||org.apache.commons.ssl.Ping||''Modeled on {{{openssl s_client}}} for debugging SSL issues.''||
||org.apache.commons.ssl.Key``Store``Builder||''Utility to convert OpenSSL private keys to
Java keystore format, and vice versa.''||

Commons-SSL is also able to encrypt/decrypt files in a way that is compatible with the OpenSSL
{{{enc}}} command.

= Background =

This java library was developed over the last year with Apache Commons
in mind.  The original idea was inspired by the
EasySSLProtocolSocketFactory and AuthSSLProtocolSocketFactory examples written
by Oleg Kalnichevski and Adrian Sutton.

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

Meanwhile if you just google for "ssl", you'll notice that "" and
"" are on the first page of results.  Both of those
sites contain versions of this documentation:

Java developers find 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 one discovers that Java can also
handle "PKCS #12" by pretending the file is a special type of JKS

Commons-SSL attempts to make it possible to work in both ways.
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, 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.".

Once the private key is loaded, SSL can start happening.  But there
are still many options and advanced usages of SSL that a developer
might want to use.  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 "";
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 easily
(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:

char[] pwd = "secret".toCharArray();

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", pwd ) );

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message