Introduction

The purpose of this document is to describe the installation, configuration and management procedures about the Virtual Appliance (VA) named SignEngineWeb (SWS). The VA SWS was created to be manageable and ready-to-use. You should import this virtual machine (".ovf") in her infrastucture and setup (for example set the proxy). With VA SWS is possible to sign, apply timestamp and verify the signature. SWS support different type of signature devices:

• Automatic signature
• Remote signature
• Disposable 
• Lean Disposable
• eSeal (electronic seal)

The types of signature permits are:

• CAdES
• PAdES
• XAdES
• RAW signature (PKCS#1)

And is possible to set the different levels of signature like B, T, LT, LTV ecc... this details are described in the documentation about integration with SWS.

The timestamp applyed are in accordance with RFC 3161 and RFC 5544 standards.

During the verification of the signatures are used certificates issued by all accredited Certification Authority in the Countries of the European Community, is possible to verify signature CAdES, PAdES and XAdES

In this guide will be described how import SWS appliance into VMWare workstation player.

Architectural Elements

SWS is the service machine which is supposed to be closed to the applications that need the signature and verification services. Applications requiring the signature connect and switch the entire file to SWS. SWS calculates the file track and asks for the RSA RAW type signature to the FRA signature system which is in the Namirial management boundaries. FRA is the system who drives HSM and uses RSA signature.

Assuming SWS is inside the LAN (the same LAN hosting the applications requiring the signature services) the documents are exchanged inside a private network. We have the confidentiality of the information contained in the hash that SWS has transmitted to FRA and a low impact on the Internet bandwidth. For each signature between SWS and FRA are used 7KB, regardless of the document size. In the case of submissions of merged requests, the bandwidth usage decreases thanks to TCP, HTTPS and SOAP lower impacts.

Inflows and Outflows

SWS exposes its services via SOAP.
On the other hand, it operates as a client in the following ways:

1. For signing operations it needs to contact the RAW signature services (PKCS#1 format) at https://fra.firmacerta.it
2. For timestamp operations it must be able to contact the Timestamping Authority (TSA) set in the call. In this case the protocols that can be used are HTTP and HTTPS. In the details, Namirial TSA can be reached at http://timestamp.firmacerta.it and at https://timestamp.firmacerta.it
3. For signing verifications it must be able to contact the CA that issued the signer's certificate to prove its validity
4. Update TLS (TrustedList) contacting periodically every EC national agencies that supervises the Certification Authority (in Italy is AgID).

Minimum Requirements

Allocated Resources to the Virtual Machine
For proper operation it is necessary that the virtual machine has assigned, at least, the following resources:

• 4 GB RAM (8 GB are suggested)
• 40 GB Hard Disk
• 2 core
• 1 network interface

Ports and Protocols Usages (firewall rules)

Below the list of port and protocol used by SWS:

Outbound communications to the Namirial FRA service are in HTTPS with a mutual authentication and they take place via an unique TLS certificate that Namirial distributes to every applicant, in order to identify the VA SWS caller.

Here is table with incoming protocols:

High Reliability Implementation

The RAW signature service (PKCS#1) is high reliability provided. The HSM and the FRA element are functional purpose redundants. The VA SWS high reliability can be achieved operating as you usually do for a generic web server: run the VA SWS setup (2 or more) and display the web services via a load balancer. Since SWS does not handle any application session, it is enough to set a load balancer policy with a same-weight Round-Robin type.

Using Apache as Reverse Proxy

A possible configuration consists in using Apache Web Server as reverse proxy and load balancer for SWS. Here is an indication related to the configuration to use:

<Proxy balancer://sws>
	BalancerMember ajp://sws1.localdomain:8009
	BalancerMember ajp://sws2.localdomain:8009
</Proxy>
<VirtualHost *:443>
	ServerName sws.mydomain.it
	SSLEngine on
	LogLevel warn
	ErrorLog logs/sws/ssl_error_log
	CustomLog logs/sws/ssl_request_log "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
	RewriteEngine on
	RewriteRule !^/SignEngineWeb/(.*)$ /SignEngineWeb/ [L,PT]
	ProxyPass /SignEngineWeb balancer://sws/SignEngineWeb
	ProxyPassReverse /SignEngineWeb balancer://sws/SignEngineWeb
</VirtualHost>

Deploy and test

Here are some information about some information for the Appliance deploy via some of the most popular virtualization systems. The virtual machine is released in the Open Virtualization Format (OVF) where the HD are in the VMDK format. In the deploy areas, it is recommended the installation of VA in environment VMware Vsphere*. 

*Namirial S.p.A. does not provide any support for the virtualization areas on which the VA SWS will be installed.

How obtain OVF virtual appliance

You can obtain the OVF at this link:

https://cms.firmacerta.it/download/sws_2.x.zip

Default Credentials

After download and import the OVF the default credentials are:

USER: sws
PASSWORD: sws2015

How import OVF into VMware Workstation Player

For import the OVF, you can follow this step:

1. Download VMware workstation player from this link: https://www.vmware.com/products/workstation-player.html
2. Install VMware workstation player and open
3. Go to: File → Play → Open → select the OVF just downloaded

How import OVF into VirtualBox

For import the OVF you can follow this step:

1. Download VirtualBox from: https://www.virtualbox.org/
2. Install VirtualBox and open
3. Go to: File → ImportVirtual Appliance → select the OVF just downloaded

Menu Console (MC)

After the import has been completed, you start the virtual machine and configure the parameters via "Menu Console".

This menu permits to set parameters like proxy, NTP ecc. The options of this menu are:

• Register: VA registration to our centralized update system (SCM)
• Config: IP ADDRESS, GATEWAY, DNS and ROOT PASSWORD configuration
• Update: Updates installation (system and push updates)
• Proxy: proxy configuration NTLM and port
• Restart_jboss: restart of the application server SWS
• Restart_osad: restart of sync module VA/SCM
• Reboot: VA restart
• Shutdown: VA shutdown
• Logout: exit from Menu Console
• Exit: go to Bash shell*

*This option must be selected under the monitoring of a Namirial operator. Namirial doesn’t give any support about modifications executed without WEB interface or Console Menù

Register: SCM Registration and Updates

The VA SWS has the possibility of being associated to an updates released centralized system. The update modes will be released in two different modes:

• Channel Updates (updates available for all the VA who has signed in)
• Push Updates (updates sent directly to the specified VA)

The registration system provides the VA restart and the resulting hostname changing with the following scheme: NomeDelCertificatoDiFirma_ultime4cifreMacAddress. The maintenance of the hostname* is a prerogative to use the updates centralized systems (SCM).

Changing the hostname will not allow to the SCM system nor release the Push Updates service nor keep track of SWS releases and packs changes inside the VA. It is strongly discouraged to vary this parameter.

From MC it will be possible to launch the operation.

Functional Verification

Appliance SWS offer a GUI for test if signature and verify works correctly.

Try if signature device device works

Make sure that system works: start the virtual machine, open a browser on a workstation able to reach the machine and enter the following url:

http://<IP-APPLIANCE>:8080/SignEngineWeb/index.xhtml

A page as the one below will be shown:

Make sure that the signature system works properly:

Submit any document and drag it in the area below the box “File da firmare”.

Enter the following parameters:

• Dispositivo Assegnato: DEMO
• PIN: foo123

Click on “Firma”. If all is ok, the browser will propose to save the created signature

Check if the signature has been applied

SWS appliance at this link offer the web page dedicated for validate a signature, at this link:

http://IP-APPLIANCE:8080/SignEngineWeb/verify.xhtml

And follow this step for validate the file just signed:

1. Click on "Seleziona file" and choose the file just signed
2. Press on "Verifica"

At the end of validation, in otput will obtain this:

Don't worry about red cross, this caused by certificate associated to device name "demo" not enrolled by trusted Root CA.

The important messegge is: "Firma 1: DEMO NOME DEMO COGNOME" in the yellow rectangle.

Environment SWS

SWS is released with a default configuration that let carry out all necessary tests using a pre-development signature system by Namirial. Obviously the signatures obtained are affixed with certificates NOT issued by a Certification Authority accredited. Any verification of these signatures with third-party tools will report errors for unknown CA. If you  want sign with certificate enrolled by trusted CA you should migrate from TEST to PROD configuration of SWS.

By default SWS is configured with TEST environment. At this link you can see the SWS configuration:

http://<IP-APPLIANCE>:8080/SignEngineWeb/help.xhtml

Like in this figure:

Below the step for migrate from TEST to PROD environment for SWS, is very easy you should upload only on file JKS which contains the certificates for connect to our system of signature.

Migrate from TEST to PROD environment

For migrate from TEST to PROD environment you should have received by mail the zip protected by password contains the JKS, the password zip has been delivered by SMS.

The steps are:

1. Go to link http://IP-APPLIANCE:8080/SignEngineWeb/settings.xhtml
2. Insert the password of SWS (see the section "Default Credentials") and press "Login"
3. Go to tab "Impostazioni generali"
4. Press on "Seleziona file" and select the JKS received by mail
5. Press "Salva"
6. Press "Riavvia server"

If the migration has been completed correctly, go to this link:

http://<IP-APPLIANCE>:8080/SignEngineWeb/help.xhtml

And you will see the label PROD (like in the yellow rectangle):

Service platform operations: Monitoring System

Appliance SWS offer tools for download log files and check if all connection (to namirial services) working correctly.

Log files

Below the list of files used by SWS:

/var/log/wildfly/signengineweb.log
/var/log/wildfly/tsl.log
/var/log/wildfly/server.log
/var/log/wildfly/boot.log
/var/log/wildfly/console.log

To ensure continuity of service, the file older than 4 weeks will be automatically deleted.

Export Log Files

From SWS gui is possible to export the log as a zip. Following this steps:

1. Go to link: http://<IP-APPLIANCE>:8080/SignEngineWeb/help.xhtml
2. Press to "Esporta log"

At the end will download the zip files contains the log

Service probing

The standard checks over the correct operation of the virtual machine (memory usage, processor usage, etc....) will be executed through the management functionalities offered by the virtualization area. However, it is possible to make a further check via http GET function. The string “OK” returns. The link is:

http://<IP-APPLIANCE>:8080/SignEngineWeb/ckeck.jsp