Sometimes I wonder; don't people /read/ API docs? I guess not..

I'm currently in the process to build a webapplication for online
payment and naturally security and encryption will become a major deal
for the whole project. Many examples show you how you need to use the
"-Djavax.net.ssl.trustStore=<keystore file>" java parameter in order to
load your JVM with a keystore to trust. Or they simply set the JVM
system property 'javax.net.ssl.trustStore'
(java.lang.System.setProperty)) to change this value.

I don't want that, my goal was to allow a user to dump a plain
certificate file (plain ASCII file in PEM format) which is then parsed
by the webapplication and used to secure the actual https connection. If
the certificate matches all is well, and if not..  etc.

Although I can find my way around the API docs quite well peeking at
some examples never hurt and so I came across the 'Java Developers
Almanac' website (http://javaalmanac.com/) featuring free example code.

People: BEWARE!!   The author seems unable to read the API docs himself
and as such certain code contains nasty bugs who's cause I can only
conclude to be plain 'PEBCAK' (Problem Exists Between Chair And
Keyboard).

Example...  When working with https its rather easy to use the
'HttpsURLConnection' class which makes working with https enabled
websites a breeze. The only possible "problem" might be the TrustManager
which demands that the "authorizing certificate" (the CA certificate
which tells you that you can trust the other party) needs to be known
somehow. In order to overcome this they show you how to create your own
trustmanager and then assign it to the used HttpsURLConnection.

They do this by setting up an SSLContext, then initializing this using
the new truststore and finally load up the HttpsURLConnection with the
SSLSocketFactory through the SSLContext mentioned earlier.

HOWEVER...  Look at this code example (source:
http://javaalmanac.com/egs/javax.net.ssl/TrustAll.html):

 // Install the all-trusting trust manager
   try {
       SSLContext sc = SSLContext.getInstance("SSL");
       sc.init(null, trustAllCerts, new java.security.SecureRandom());
       HttpsURLConnection.setDefaultSSLSocketFactory(sc.getSocketFactory());
   } catch (Exception e) {
   }
   
   // Now you can access an https URL without having the certificate in
   // the truststore
   try {
       URL url = new URL("https://hostname/index.html");
   } catch (MalformedURLException e) {
   }

Notice the use of the setDefaultSSLSocketFactory() method...  Now read
the API docs for javax.net.ssl.HttpsURLConnection and you'll come
across: "setDefaultSSLSocketFactory - 'Sets the default SSLSocketFactory
inherited by new instances of this class.'".

Reading the description of the method these folks /should/ be using
(setSSLSocketFactory) shows you: "Sets the SSLSocketFactory to be used
when this instance creates sockets for secure https URL connections.".

I don't get it..  Is it really /that/ hard to RTFAD (Read The 'Fine' API
Documentation) ?

Well, I hope I might help some people with this....