This Morphon T-o-M Installation Guide is for system administrators that need to install and configure a T-o-M instance.
The T-o-M is a software application that runs on a server and enables clients to digitally sign PDF documents. The keys and certificates used in this process can either be software or hardware based (by using a hardware token such as a PCI card or USB dongle).
The Morphon T-o-M version 1.0 is packaged as a Java .war file and can be deployed in the more popular servlet containers. The servlet container must be running at least a Sun Java 5 JDK. These include:
If you do not have an application server up and running yet, and have no preference, we suggest choosing either Jetty or Apache Tomcat as they are simple to install and do not require many resources.
Note that the T-o-M works most securely in a servlet container that supports HTTPS connections, although this is not required. We recommend using HTTPS however. In addition to wire-security, using HTTPS will enable you to authenticate the T-o-M you are communicating with by examining its (server-side) certificate. Similarly, the T-o-M will be able to verify your client application by examining its (client-side) certificate. See the Security section below for more information.
T-o-M is supported on Intel, AMD and SPARC based platforms. Running it in other environments should not be a problem though. Furthermore, it requires:
Installation of T-o-M depends on the application container you are using. Refer to their documentation on .war file deployment to determine how to install T-o-M.
In most containers installing the T-o-M is as easy as copying the the file morphon-tom.war to your servlet container's deploy directory. Deploying the .ear file is similar, but requires an application server rather than "just" a container.
Before installation you will need to configure your Morphon T-o-M. This includes:
The T-o-M will look for the file named morphon-tom.properties in the classpath of your application container. A good place for an admin to put this file would be in the application server's "conf" directory. When found, the system will extract the settings for keys and templates (see following sections for more info). If this configuration file cannot be found, T-o-M will be unable to continue and will throw an error.
Note that T-o-M will work with cryptographic keys and certificates that are accessible through the Java Cryptographic Architecture (JCA). These will have to be configured seperately of any T-o-M configuration and need somehow to be made available by the application server to T-o-M. Although the precise configuration depends on the type of cryptographic solution used, we have a few simple guides available here for the most common cases and hardware.
The Morphon T-o-M requires a license key to fully function. You should have received it on purchase and will have to be configured in the morphon-tom.properties configuration file. For example:
license = HHE432A6...
Note that the license key may be a considerably long text string. Still, it needs to be provided on one line only and cannot be wrapped.
The configuration file will contain sets of settings for different keys. Each of these sets will refer to a cryptographic key and certificate configured through the JCA. The T-o-M will look for a property named 'keys' and parse this as a comma separated list of key names. For each of the key names that were found, the system will load the settings for each key. Below is an example:
keys = hr-key, is-key hr-key.type = jks hr-key.path = /etc/... hr-key.alias = mykey hr-key.storepw = qwerty hr-key.keypw = 123456 is-key.type = pkcs11 is-key.name = hwkey1 is-key.library = C:/WINDOWS/system32/dkck201.dll is-key.slot = 10 is-key.alias = iskey is-key.storepw = uiop is-key.keypw = 7890 ...
Note that the settings are of the format <key-name>.<key-property> = <property-value>. Since different types of keys need different settings (e.g. 'path' might not make sense for a hardware token), different settings may or may not be required. Currently the following properties are supported:
| Property | Description |
|---|---|
| type | The type of key. Currently supported are:
|
| path | The path to the keystore. This applies to keys of type jks only. |
| config | The path to the PKCS#11 config file. This applies to keys of type pkcs11 only. If this property is not specified, the name property must be present. If both properties are present, config takes precedence. |
| name | The name of the pkcs11 provider. The provider must either already be configured in your Java environment, or the library and slot properties must be present. This property applies to keys of type pkcs11 only. |
| library | The path to your PKCS11 library. If this property is present, the name and slot properties must also be present. This property applies to keys of type pkcs11 only. |
| slot | The slot to your PKCS11 token. If this property is present, the name and library properties must also be present. This property applies to keys of type pkcs11 only. |
| alias | The alias to access the correct key in the store. |
| storepw | The password with which to access the store, if it is password protected. |
| keypw | The password with which to access the key inside the store. This is also called a pin. |
Note that the config property may overrule the name, library and slot properties.
Also, make sure that all filepaths contain forward slashes (/) rather than backslashes (\), even on Windows systems.
During testing with certain hardware tokens we have run into an incompatability issue between the hardware and the Sun PKCS#11 libraries. Fortunately, there's a workaround. Should you see the message CKR_MECHANISM_INVALID appear in the logs, create the following config file and set the config property to use it.
name=<your token name>
library=<path to your library>
slot=<your token's slot number>
disabledMechanisms={ CKM_MD5_RSA_PKCS CKM_SHA1_RSA_PKCS }
See Sun's PKCS#11 documentation for more information about configuring a PKCS#11 Provider
A template is a preconfigured set of properties that can be applied to a document during signing. This includes which key to use for signing and whether to create a visible signature or not. These settings can be overriden in each sign request, provided that you have an Enterprise license. See the example below:
... templates = template1, template2 template1.name = "Morphon Press Agency" template1.key = hr-key template1.author = true template1.reason = For official release template1.location = New York template1.visible = true template1.page = 1 template1.graphic = /usr/local/morphon-tom/hr1.png template1.x = 100 template1.y = 100 template1.width = 400 template1.height = 100 template1.auth-methods = ocsp,crl,fail template1.tsp = required template2.key = is-key ...
The various properties here can be configured as follows:
| Property | Required | Description |
|---|---|---|
| key | yes | Which of the configured keys to use, see the paragraph above. |
| author | yes | Whether the signature should be an author ('true') signature or a recipient ('false') signature. |
| reason | no | The reason for the signing, such as (I agree...). |
| location | no | The physical location of the signing, such as (London, England). |
| visible | yes | Specifies whether to use a visible signature, which is configured by the graphic, page, x, y, width and height properties. |
| graphic | no | Path to a PNG format graphic to be used for the visible signature. You get a default graphic if you use a visible signature and this is not set. |
| page | no | The page number on which the graphic should be shown, starting at 1. |
| x | no | X coordinate of the visible signature, as counted in pixels from the left of the page. |
| y | no | Y coordinate of the visible signature, as counted in pixels from the bottom of the page. |
| width | no | Width in pixels of the visible signature. |
| height | no | Height in pixels of the visible signature. |
| ocsp | no |
This property has been deprecated, use auth-methods instead. Indicates whether to do OCSP checking and to embed the OCSP in the document. Also determines what happens when the OCSP response is invalid or the OCSP responder is not available.
|
| auth-methods | yes |
Specifies which authorization checks to try (and which order) for each and every relevant certificate. Morphon T-o-M will try to perform an authorization check for each certificate in the order specified and either report an error and stop (fail) or just continue (ignore). This property should contain a comma-separated list of the following (with either fail or ignore as the last one):
|
| tsp | no |
Indicates whether to embed an official timestamp in the document. Also determines the T-o-M behaviour when one is not available. Possible values:
|
If your license supports a TimeStamp Authority (TSA) server, you will need to specify which key to use for signing the timestamp responses. Configure a key as described above, but use the tsakey property, instead of adding the name to the keys list:
tsakey = tsa-key tsa-key.type = jks tsa-key.path = /etc/... tsa-key.alias = mykey tsa-key.storepw = qwerty tsa-key.keypw = 123456 ...
The TSA server checks the system time with an NTP server. If the difference between the two exceeds a maximum, the timestamp requests are rejected. The following optional configuration values are available:
| Property | Default | Description |
|---|---|---|
| ntphostname | pool.ntp.org | The hostname of the NTP server to use for clock checks |
| ntpinterval | 15 | The minimum interval, in minutes, between NTP checks |
| maxclockdrift | 1 | The maximum number of seconds difference between the system clock and the NTP server response |
You may only want to make the Morphon T-o-M available through an HTTPS connection. Refer to the documentation of your application server on how to accomplish this. Using HTTPS, clients can check the authenticity of your T-o-M installation, but the server is also able to determine whether the client is authentic.
If you do not want to configure HTTPS in your application server it is possible to accomplish the same by using an Apache front-proxy server. For more information, look here.
You may want to restrict access to the Morphon T-o-M by applying one of many authentication mechanisms. At the least, we always recommend restricting access to T-o-M based on IP address of the client. You may however also want to restrict access through username and password or tie access to your Windows Domain. All these
If you do not want to configure authentication in your application server it is possible to accomplish the same by using an Apache front-proxy server. For more information, look here.
The next few paragraphs discuss specific instructions per application container.
these installation instructions assume that you are running apache tomcat version 6, or newer. the morphon t-o-m will run just fine under tomcat 5, but there are some subtle differences in configuration (the classloader works differently). therefore we recommend you get tomcat 6 and follow these instructions.
JBoss comes with several different configurations in the server directory in JBoss' installation location. These instructions describe paths that start at the configuration directory that you are using.
After installing jetty, follow the instructions below.