* The current implementation of the web toolkit is a java based implementation and can be integrated into J2EE compliant web applications. Consequently, you must download and install the latest version of the JDK. Note that the toolkit requires JDK 1.6.x or greater.
* Download and install the servlet container of your choice. The beta version of the toolkit was tested on Apache Tomcat Version 6.0.18. Tomcat downloads and installation instructions can be found here.
* In addition to programming to the API's, the MashSSL Web Toolkit integration requires that it be assimilated into your build process. The current implementation of the toolkit relies upon a Maven plugin to perform the integration. The Maven software, installation instructions and a usage instructions can be found here. Note that the steps required to configure the MashSSL maven plugin can be found below within the usage section.
* The MashSSL protocol requires that you have an SSL certificate that chains up to a MashSSL approved Certificate Authority. If you do not have a compliant SSL certificate, instructions on how to obtain one can be found within the community section of our site.
The maven pom.xml file defines your project specific configuration. Injecting the MashSSL Web Toolkit into your application requires that you add the following snippets to your pom file.
The latest versions of the MashSSL Web Toolkit and all required dependencies, including the core MashSSL library are released to the SafeMashups repository. To access the repository, you must add the repository to your maven configuration. Configure the following repository within your projects pom.xml file:
<repositories>
...
<repository>
<releases>
<enabled>true</enabled>
<updatePolicy>never</updatePolicy>
<checksumPolicy>fail</checksumPolicy>
</releases>
<snapshots>
<enabled>false</enabled>
</snapshots>
<id>safemashups.releases</id>
<name>SafeMashups Release Repository</name>
<url>dav:http://downloads.safemashups.com:8085/archiva/repository/releases/</url>
<layout>default</layout>
</repository>
...
</repositories>
The latest versions of the MashSSL Web Toolkit Plugin is released to the SafeMashups repository. To access the repository, you must add the following to your maven configuration. Configure the plugin repository within your projects pom.xml file:
<pluginRepositories>
<pluginRepository>
<id>safemashups.plugins</id>
<url>dav:http://downloads.safemashups.com:8085/archiva/repository/releases/</url>
</pluginRepository>
</pluginRepositories>
We've created a MashSSL specific Maven plugin which injects the MashSSL Web Toolkit into your web application. It copies required classes and resources into the target directory of your web project and adds a few required entries to your web.xml file (the source version of your web.xml file is not altered.)
To enable the plugin, add the following plugin entry to your project's pom.xml file:
<pluginRepositories>
<pluginRepository>
<id>safemashups.plugins</id>
<url>dav:http://downloads.safemashups.com:8085/archiva/repository/releases/</url>
</pluginRepository>
</pluginRepositories>
Following is a comprehensive list of the plugin configuration parameters, all of which have a sensible default, but which can be tailored to your specific project's requirements.
| Name | Description | Default |
|---|---|---|
| wtkVersion | Defines the MashSSL Web Toolkit version injected into project. We recommend pegging this to a specific version before releasing your project. | RELEASE |
| mashSSLConfigDir | Identifies location within which required MashSSL artifacts, e.g. certificates and keys, are located. Implied scheme is file. | ~/.mashssl |
| serverCertificateFile | Name of PEM encoded SSL certificate file used by your application within context of the MashSSL handshake. | certificate.pem |
| serverKeyFile | Name of PEM/DER encoded private key file used by your application within context of the MashSSL handshake. | privateKey.pem |
| serverKeyPwd | Optional password required to decrypt a pem encoded private key file (der encoded keys must not be encrypted) | None |
| scramblerImpl | Implementation of 'edu.utsa.ics.spi.mashssl.web.Scrambler' used to scramble client hello random or server hello random. | None |
| aclManagerImpl | Implementation of 'edu.utsa.ics.spi.mashssl.core.ACLManager' to which toolkit defers decision as to whether or not partner is trusted. | edu.utsa.ics.spi.mashssl.core.util.DefaultACLManager |
| responseHandlers | An ordered list of 'edu.utsa.ics.spi.mashssl.web.util.ResponseHandler' implementations. | None |
| requestHandlers | An ordered list of 'edu.utsa.ics.spi.mashssl.web.util.RequestHandler' implementations. | None |
| verifyHostNames | Indicates whether or not value of hostname retrieved from partner url is compared with hostname in partner certificate. | true |
| loginPageURI | Identifies classpath location of login page which will handle unscrambling within browser. Ignored if no scrambler impl defined. | None |
| enablePreemptiveCertification | Indicates whether or not client certificate is sent preemptively within the client hello message | true |
| destroyCompletedWebSSLSessions | Indicates whether completed WebSSLSession objects on server-side of mashssl handshake are destroyed automatically | true |
| httpClientTimeout | Timeout in milliseconds before which http client will timeout when making server-to-server connections to partner and/or safemashups service. | 6000 |
The snippet listed above within the section on plugin enablement is acceptable for most use cases. Following is an example which demonstrates how to override the default ACLManager implementation provided by the toolkit:
<plugin>
<groupId>edu.utsa.ics.spi</groupId>
<artifactId>maven-mashssl-plugin</artifactId>
<version>1.3</version>
<executions>
<execution>
<goals>
<goal>configure</goal>
</goals>
<configuration>
<aclManagerImpl>edu.utsa.ics.spi.mashssl.core.util.PermissiveACLManager</aclManagerImpl>
</configuration>
</execution>
</executions>
</plugin>
To initiate the MashSSL handshake from within your application requires that you code to the Web Toolkit's API. The javadoc for the API is referenced above. Note that each toolkit instance is capable of responding to MashSSL handshake requests without any coding on your part.
Here's a code snippet which demonstrates how to invoke the handshake and how to inspect the results. Note that we have provided several examples which you can download here and run through your debugger. If you need additional help, please check our user forum.
// retrieve webSSLSession instance. if request is new request, as indicated by
// the request parameter 'mashssl.request.id', a new session is returned ready
// for authentication. otherwise an existing session is returned
WebSSLSession webSSLSession = webSSLSessionManager.getSession(request, response);
// if the authentication status is null, then a new session was returned in the
// previous step. invoke the mashssl handshake. note the no additional processing
// can be performed following invocation - hence the return statement
AuthenticationStatus authenticationStatus = webSSLSession.getAuthenticationStatus();
if (authenticationStatus == null) {
logInitialMessage(request, webSSLSession);
webSSLSession.authenticate();
return;
}
// if authentication status is not null, the mashssl handshake is complete. check
// to see if the partner was authenticated. if not, we return a 401 error. if,
// yes, we return content in response to the original request
if (authenticationStatus.isAuthenticated()) {
response.setContentType("text/plain; charset=UTF-8");
response.setStatus(HttpServletResponse.SC_OK);
response.setHeader("Access-Control-Allow-Origin", "*");
String responseContent = getResponseContent();
response.getOutputStream().write(responseContent.getBytes("UTF-8"));
webSSLSessionManager.destroySession(webSSLSession);
} else {
response.sendError(401, "MashSSL authentication failed.");
}
The following entries reference the javadoc for the most recently released version of the MashSSL Web Toolkit. Older versions, although not listed, will remain on our servers.
| Project | Description | JAVADOC |
|---|---|---|
| MashSSL Core | An implementation of the core MashSSL specification used by the Web Toolkit to execute and manage the MashSSL handshake. | javadoc |
| MashSSL Web Toolkit API | Defines abstract classes and interfaces used by third parties to interact with the MashSSL Web Toolkit. | javadoc |