Introduction

The purpose of this document is to describe the installation, configuration and management procedures for 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 your infrastructure and then do the setup (for example, set up the proxy). With VA SWS, it is possible to sign, apply timestamps and verify the signature. SWS supports different types of signature devices:

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

The supported signature standards are:

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

Additionally, it is possible to set the different levels of signature such as B, T, LT, LTV etc... These details are described in the documentation about integration with SWS.

The timestamps applied are in accordance with RFC 3161 and RFC 5544 standards.

During the verification of the signatures, SWS can verify certificates issued by all accredited Certification Authorities in the Countries of the European Community. Also, it is possible to verify signatures in any of the CAdES, PAdES and XAdES formats. 

In this guide will be described how to import the 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 timestamping 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 in order to prove its validity
4. For Updating TLS (TrustedList), it contacts periodically every EC national agency that supervises the Certification Authority (in Italy, this 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 communication to the Namirial FRA service are done through HTTPS, with a mutual authentication and take place via a unique TLS certificate that Namirial distributes to every applicant, in order to identify the virtual appliance 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 is some information about the Appliance deployment 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 deployment environments, it is recommended the installation of the virtual appliance in VMware vSphere*. 

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

How to 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 to 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

How import OVF in Amazon Web Services (AWS) EC2

Below the steps to load SWS appliance on Amazon Cloud:

1) Dowload and install AWS CLI from this link (https://docs.aws.amazon.com/en_us/cli/latest/userguide/cli-chap-install.html)

2) Execute AWS CLI with the command aws configure

3) Load the virtual machine disk (.vmdk) on S3 bucket using this command of AWS CLI:

aws s3 cp "<vmdk-path>" s3://<nome-bucket-S3>/

Example → aws s3 cp "C:\Users\utente\Desktop\SWS\Disk.vmdk" s3://my-bucket-S3/

4) When the loading is complete, create the AMI with this command:

aws ec2 import-image --description "SWS AMI" --disk-containers "Format=vmdk,UserBucket={S3Bucket=<nome-bucket-S3>,S3Key=<vmdk-path>}"

Example -> aws ec2 import-image --description "SWS AMI" --disk-containers "Format=vmdk,UserBucket={S3Bucket=il-mio-bucket-S3,S3Key=Disk.vmdk}"

5) Now is possible to monitore the AMI creation with this command:

aws ec2 describe-import-image-tasks

6) When the AMI creation is complete, will be available at this path:

EC2 Section → Images → AMIs

Now is possible deploy EC2 istance.

At step 1 and 2 describe how install aws  client on the workstation that will be used for all the import activity of the application solution. The aws client just created will be used for next steps.

At step 3 the data disk (vmdk file) of the sws appliance is loaded. Usually the data disk is called "swsappliance-release-number-sws-1.vmdk" the disk in order to be imported must be loaded on an s3 bucket of the customer who can freely choose among those he has or can create at the moment. The latter will be used to convert the data disk from vmdk files to the native AWS format

At step 4 the disk conversion takes place and the values between <...> must be replaced with those that the customer has chosen to use:

aws ec2 import-image --description "SWS AMI" --disk-containers "Format=vmdk,UserBucket={S3Bucket=<S3-bucket-name>,S3Key=<vmdk-path>}"

Exampe ->  aws ec2 import-image --description "SWS AMI" --disk-containers "Format=vmdk,UserBucket={S3Bucket=swsrocks,S3Key=swsappliance-2-5-33-1.vmdk}" 

At this step the vmdk file remains in the bucket, but an AMI with description SWS AMI is created in the default region with which aws cli has been configured (it is set when the client configuration is carried out at step 2)

At step 5 is possible to monitor the procedure started at step 4 (because this step is very slow)

At step 6 is possible to monitor from AWS panel console if the AMI has been imported correctly and is ready to be used.

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 Testing

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