This document gives a general overview on how to integrate a Morphon T-o-M into a PDF processing/generation system. Furthermore some security considerations are discussed. This document is intended for use by developers wanting to integrate T-o-M into their existing systems. It is assumed that the reader has technical knowledge about the HTTP protocol and security issues.
T-o-M offers a simple HTTP/HTTPS interface to integrate PDF signing into your existing business processes. Once T-o-M has been set-up, other applications can be extended to submit their PDF documents, and receive a fully signed PDF back in response.
You submit a document to a T-o-M by using either a PUT or a POST HTTP request. They have identical functionality. Your choice should depend on the tools you have available on your client side. We recommend using PUT as it has some minor additional security features (passing parameters separately) and it is a more pure HTTP REST design.
T-o-M is accessed through one base URL. This URL typically looks like:
https://host.yourdomain.com/morphon-tom
However, this may vary in your set-up as the exact location is at the discretion of your system administrator who installed T-o-M. To this URL you submit your PDF and optionally some parameters and you will get a signed PDF in return. For example, the following request shows what a POST to the T-o-M may look like:
POST /morphon-tom HTTP/1.1 Host: host.yourdomain.com Accept: application/pdf,application/xml Accept-Encoding: gzip,deflate Content-Type: multipart/form-data; boundary=---------------------------308409824598593549256148101 Content-Length: 22785 -----------------------------308409824598593549256148101 Content-Disposition: form-data; name="document"; filename="pdf-to-sign.pdf" Content-Type: application/pdf [... PDF DATA GOES HERE ...] -----------------------------308409824598593549256148101 Content-Disposition: form-data; name="graphic"; filename="company-certified.png" Content-Type: image/png [... PNG DATA GOES HERE ...] -----------------------------308409824598593549256148101 Content-Disposition: form-data; name="profile" accounting/invoice -----------------------------308409824598593549256148101--
The following table explains which parameters may/should be sent in each request. Note that since a template can specify default values for each parameter (except document and template), any required parameters are only required in the request if they have not been set in the template, if one has been chosen in the request.
| Name | Required | Default | Values | Description |
|---|---|---|---|---|
| document | yes | undefined | PDF data | The PDF document to sign. |
| template | no | undefined | string, template name | Any of the preconfigured templates. A template may specify default values for the parameters below, which can be overriden by specifying the corresponding parameters in the request. |
| profile | yes | possibly defined by template | string | An optional parameter indicating a specific server configured identity to sign with. If not specified, the default profile will be used by the server. |
| username | depends on profile | possibly defined by template | string | In some cases the T-o-M may require a client to provide additional credentials to identify itself to a HSM. The username parameter will be passed on to such a HSM. |
| password | depends on profile | possibly defined by template | string | Similar to the username parameter. The password parameter will be passed on to the HSM. |
| author | no | possibly defined by template | string | The name of the person or authority signing the document. |
| reason | no | possibly defined by template | string | The reason for the signing, such as (I agree...). |
| location | no | possibly defined by template | string | The physical location of the signing, such as (London, England). |
| visible | no | "false" or defined by template | string, either "true" or "false" | Specifies whether to use a visible signature, which is configured by the graphic parameters below. Note that a template may specify a default of "false" but still have defaults for the graphic parameters, these can then be used by simply specifying "true" in the request. |
| graphic | when visible set to "true" | possibly defined by template | PNG data | The graphic shown to the user by Acrobat Reader when the user views a document whose signature is valid. |
| graphic-page | when visible set to "true" | possibly defined by template | integer | Optional, the page number on which the graphic should be shown. |
| graphic-coord | when visible set to "true" | possibly defined by template | integer "," integer "," integer "," integer | Optional, the XY coordinates and width and height at which the graphic will be shown. |
During normal operations the T-o-M will return the signed PDF as the HTTP response. For example:
HTTP/1.1 200 OK Date: Sat, 19 May 2007 12:25:57 GMT Server: Apache-Coyote/1.1 X-Powered-By: Servlet 2.4; JBoss-4.0.3SP1 (build: CVSTag=JBoss_4_0_3_SP1 date=200510231054)/Tomcat-5.5 Content-Length: 53515 Connection: close Content-Type: application/pdf %PDF-1.6 ... ...
In the case of any errors, T-o-M will return a different response code and will not sign the PDF. Note that since T-o-M runs on an application server, the server may generate other errors that use the same codes (ie. if there is a typo in the url, the server may generate a 404 error).
| Code | Description | Explanation |
|---|---|---|
| 400 | Bad Request | The request has errors (eg. missing required parameters, letters in numerical fields, etc). See the "Request parameters" paragraph about the proper format of the request. |
| 401 | Unauthorized | Authentication has failed or user (possibly identified by client-side certificate is not authorized to use this T-o-M profile ortemplate. |
| 404 | Not Found | The specified profile or template has not been found in the configuration of this T-o-M. |
| 415 | Unsupported Media Type | The file format of the graphic that was uploaded, can not be handled by T-o-M. |
| 500 | Internal Server Error | A general failure occurred. |
A more detailed error can be found in the body of the response. Depending on the Accept header of the client's HTTP request, the response will have either text/plain, text/html or application/xml MIME type.
A T-o-M personality can be protected from use by a number of authentication mechanisms. A client may therefore have to authenticate itself first before being able to sign documents. Depending on how your systems administrator has configured T-o-M you may have to support one of the following:
Note that your systems administrator may have imposed additional authentication or security mechanisms out of the realms of T-o-M.
Using the credentials the client provides, T-o-M will use a pre-configured identity. Note that in some cases you will also have to provide additional credentials to get access to the underlying HSM. Again, contact your systems administrator for your set-up.
As input, T-o-M supports all PDF versions to date. At the time of writing, PDF version 1.6 is the latest. Note that, on output, T-o-M will always upgrade your PDF to the latest version.