How-To Increase Security with Java Keystore to Embed the DocuSign Electronic Signature Experience In Your Application

If you want to embed the DocuSign esigning experience into your application, your web service calls to DocuSign API will require a tighter level of security. In addition to the user name token in the SOAP headers, you will need to provide an X509 signature. For an example of a SOAP call with an X509 signature, please see Chapter 1 of DocuSign3.0API.doc - the DocuSign developer guide.

Step 1 - Procure an X509 Certificate

• To get BinarySecurityToken working with Java, procure an X509 Certificate. While getting an X509 certificate is beyond the scope of this blog post - you might want to try searching for “SSL Certificates”. SSL transport protocol uses X.509 certificates for encryption.
• DocuSign supports certificates issued by certificate authorities included in Windows2003 servers. The most widely used certificate authorities are Thawte and VeriSign. Additionally, our Demo server farm support CACert.org certificate authority, which enables you to get a certificate without having to pay for it.
• Keys are generally distributed in PEM, PFX or CRT files. You will need one of these files prior to proceeding with this walkthrough.

Step 2 - Generate a Java KeyStore

• Java has its own keystore format which requires the use of its own tool - keytool. In my experience, I had started with a PFX file. To convert to the Java Keystore format, I had to go through a number of cumbersome steps. Then, one of our customers, Gloria Zhang, pointed me to a blog post about a very nifty tool: http://erlend.oftedal.no/blog/?blogid=68
• Using the steps in that tutorial, I created an esign.jks file.

Step 3 - Configure Axis2 to generate electronic signatures

• We've prepackaged samples to generate the right configuration files when you want to use XML signatures. I suggest that you start with working code from the DocuSign SDK and plug in your keystore file. This minimizes the number of things that can go wrong.
• You will need to plug in some important information about your keystore into the build.properties.x509 file. Once you plug in the (1) keystore path, (2) alias of the certificate and (3) password, you will need to issue “ant war-x509” command to build the web archive for deployment.
• If you were to examine the build configuration, you should see the following things in your axis2.xml config file:
• <items>Signature UsernameToken Timestamp</items>
• Elements such as ≤signatureCrypto> in the OutflowSecurity portion of the configuration.
• A cert.properties file that seemingly has a set of information that is already provided in axis2.xml. This may be there for historical reasons.

Step 4 - Testing

• Once you have established that the application is still functioning and making web service calls, the next thing to examine is the SOAP calls. LoanSample comes pre-packaged with log4j integration that dumps out the HTTP wire calls. You can find the SOAP requests and responses there.
• In my experience, opening the SOAP requests and responses in an external editor and cutting and pasting the appropriate sections makes them easier to read. After all the edits, you should see your requests to DocuSign web services. Those requests will have the UserNameToken and also BinarySecurityToken element in the headers. The BinarySecurityToken will have signature information and signature value.
• The final test is contacting your DocuSign representative and asking them to turn on XML signature validation on your account. This request should be accompanied by a public export of your certificate. Make sure you do not include the private key in your request.

While configuring XML signatures in Java is an advanced topic that requires that you master servlets, axis (or a similar framework), and PKI file manipulation, you can also work with DocuSign to ensure the correct configuration.

After all the settings are correctly configured, DocuSign will know that the web service calls were generated only by an application that had access to the X.509 certificate file. Enterprise IT operations put a lot of emphasis on the security of the certificate files, so you can enjoy the benefits from the internal infrastructure.