Introduction

The purpose of this document is to describe how to use the OpenSign applets. The document contains all information that you will need to use an OpenSign applet on a website.

Please note that this document is work-in-progress, and therefore not yet complete.

Sometimes, you can learn much from just an example. We would therefore like to turn your attention on the demonstration setupthat we have implemented. All html pages and source code used in the demonstration setup is included in the OpenSign source distribution. The files in the following directories of the source distribution provide a good starting point for learning how the demonstration example works.

         opensign-<version>/src/org/openoces/opensign/demo/servlets/
	 opensign-<version>/data/demo/html/
      

The rest of this guide is divided into three logically separate parts. The first part describes how the OpenSign applets being executed on a client communicates with the server, that is, it describes the flow of information to and from the applets in general terms. The next part deals with all the gory details of how to pass information to the applets and how the applets pass information back to the server. This part describes three different modes in which the OpenSign applets can operate. The last part of the guide contains two reference sections listing all parameters that can be passed to the applets and describing the structure of the xml document returned by the applets respectively.

Flow of information

It is crucial to understand how information flows between the server and the OpenSign applets. The OpenSign applets can operate in two different modes, commonly referred to as

• 2-step mode, and
• 3-step mode

When operating in 2-step mode the second and last step is initiated when the user either signs or refuses to sign the text. In this step the signed document or an indication of that the user refused to sign the text is transferred to the server and the server responds with a new html page based on the information being passed.

When operating in 3-step mode the second step is also initiated when the user either signs or refuses to sign the text. If the user refuses to sign the text, he is simply redirected to an URL that was passed to the applet in the first step. If however, the user signs the text, the signed text is posted to another configurable URL commonly referred to as the verification URL.

The third and last step is started immediately after the signed text has been posted to the verification URL. In this step the user is simply redirected to one of two different URLs. Both URLs are configurable and have been defined in step 1. The URLs are commonly referred to as the verified-ok URL and verified-error URL. Which of the two is chosen depends on whether the result returned by the post to the verification URL was positive or negative.

Make sure that you noticed the crucial difference between the two modes. In 2-step mode the signed document and the redirection of the user happened at the same time. The user was redirected to an URL that also received the signed document if it existed. This is different from the 3-step mode, where the signed document is sent to the server in the 2nd step and control then is returned to the applet. Then afterwards, in the 3rd step, the user is redirected to an URL, but this URL is not being passed the signed document.

The 2-step mode is the original mode that has been supported from the beginning, whereas the 3-step mode was introduced in the v1.1.x series. The 3-step mode is supported by more browsers than the 2-step mode, as it does not depend on the live-connect technology being supported by the browser executing the applet. Because of this, it is generally recommended that you use 3-step mode.

Using the 3-step mode

In this mode, the implementation is naturally divided into 3 individual components. The first component launches the applet by generating a html document that launches the OpenSign applet. The second component is the serverside component that receives the signed document after it has been properly signed. The third component is the webpage to which the user is directed when the applet is exited. A description of how each of these components is implemented is described in the following subsections.

	  <html>
	    <body>
	      <applet 
	        name="openoces_opensign_applet" 
	        code="org.openoces.opensign.client.applet.Logon" 
		width="500" 
		height="200" 
		codebase="/demo" 
		archive="/demo/applet/OpenSign.jar"> 
		<param name="locale" value="en,US">
		<param name="cabbase" value="/demo/applet/OpenSign.cab">
		<param name="opensign.doappletrequest" value="true">
		<param name="opensign.verifieruri" value="/demo/servlet/Verifier?id=42">
		<param name="opensign.canceluri" value="/demo/servlet/Display?result=cancel">
		<param name="opensign.erroruri" value="/demo/servlet/Display?result=error">
		<param name="opensign.alerturi" value="/demo/servlet/Display?result=alert">
		<param name="opensign.verifiedokuri" value="/demo/servlet/Display?result=ok&id=42">
		<param name="opensign.verifiederroruri" value="/demo/servlet/Display?result=error">
	      </applet>
	    </body>
	  </html>	    
	

            <param name="signtext" value="Zm9vYmFy">
	  

          package org.openoces.opensign.demo.servlets;

          import org.openoces.opensign.utils.Base64;
          import org.openoces.opensign.demo.utils.XML;
          import org.w3c.dom.Document;
          import javax.servlet.http.HttpServlet;
          import javax.servlet.http.HttpServletRequest;
          import javax.servlet.http.HttpServletResponse;
          import javax.servlet.ServletException;
          import java.io.IOException;
          import java.io.File;
          import java.io.FileWriter;

          public class Verifier extends HttpServlet {
            public void doPost(HttpServletRequest request,
                         HttpServletResponse response)
              throws IOException, ServletException {

              try {
                String xmldoc, xmldoc_b64;
                xmldoc_b64 = request.getParameter("message");

                xmldoc = new String(Base64.decode(xmldoc_b64.getBytes("UTF-8")), "UTF-8");
                Document doc = XML.getDocument(xmldoc);

                if (XML.verifySignature(doc)) {
                  // make the fact that the signature has been verified persistent
                } else {
                  // we were unable to verify the signature
                  throw new Exception();
                }
              } catch (Exception e) {
                throw new ServletException();
              }
            }
          }
        

Using the 2-step mode

<html>
<head>
<title></title>
</head>
<body bgcolor="white">
<applet name="signing_applet"
        code="org.openoces.opensign.client.applet.Sign"
        width="600"
        height="400"
        codebase="/archive/opensign/opensign-1.2.2-bin"
        archive="/archive/opensign/opensign-1.2.2-bin/OpenSign.jar"
        mayscript>
        <param name="locale" value="en,US">
        <param name="cabbase"
value="/archive/opensign/opensign-1.2.2-bin/OpenSign.cab">
        <param name="signtext" value="INSERT TEXT TO BE SIGNED HERE">
</applet>

<form name="signedForm" method="post" action="INSERT URL HERE">
        <input type="hidden" name="signature">
        <input type="hidden" name="result">
</form>

<script language="JavaScript">
        function onSignOK(signature) {
                document.signedForm.signature.value=signature;
                document.signedForm.result.value='ok';
                document.signedForm.submit();
        }
        function onSignCancel() {
                document.signedForm.result.value='cancel';
                document.signedForm.submit();
        }
        function onSignError(msg) {
                document.signedForm.result.value=msg;
                document.signedForm.submit();
        }
</script>

</body>
</html>
	

Using a hybrid of 2-step and 3-step mode

To be written.

Appendix: Handling of cookies

To be written.

Appendix: Certificate filtering

To be written.

Reference: Applet parameters

This section describes all parameters that can be passed to the applets

This section is currently work-in-progress.

Reference: Structure of the signed document

This section describes the xmldsig document returned by the OpenSign applets.

To be written.

Credits

We would like the following individuals for their contributions to this documentation:

• Jesper Skagerberg