# Sign Web Services (SWS)

## Table of Contents

- [Introduction](#introduction)
  - [Supported Devices](#supported-devices)
  - [Supported Signature Formats](#supported-signature-formats)
- [How SWS Works During the Signing Flow](#how-sws-works-during-the-signing-flow)
  - [Network and Bandwidth Considerations](#network-and-bandwidth-considerations)
  - [External Services Used](#external-services-used)
    - [RAW Signature Service (PKCS#1)](#1-raw-signature-service-pkcs1)
    - [Timestamping Authority (TSA)](#2-timestamping-authority-tsa)
    - [Certification Authorities (CA)](#3-certification-authorities-ca)
    - [Trusted List (TLS) Updates](#4-trusted-list-tls-updates)
  - [High Availability](#high-availability)
- [How SWS Works During the Verify Flow](#how-sws-works-during-the-verify-flow)
- [Type of Distributions](#type-of-distributions)
  - [On-Premise](#1-on-premise)
  - [SaaS](#2-saas)
- [Best Practice](#best-practice)
- [Recommendations](#recommendations)
- [License](#license)


## Introduction

SWS (Sign Web Services) allows signing and verifying different document types. The application can be used only with devices enrolled by Namirial.

### Supported Devices

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


### Supported Signature Formats

- **CAdES**
- **PAdES**
- **XAdES**
- **JAdES**
- **RAW signature (PKCS#1)**


It is also possible to set different signature levels such as:

- B
- T
- LT
- LTV


These details are described in the official documentation about integration with SWS.

The timestamps applied are compliant with:

- **RFC 3161**
- **RFC 5544**


During verification, SWS can validate certificates issued by all accredited Certification Authorities in the European Community. It supports verification for:

- CAdES
- PAdES
- XAdES


You can see a SWS like a blackbox like in this image:

This is the flow during the signing process
While during the verify, this is the flow:

Naturally SWS contact external services to complete the flow of signing and verify. Below will be described the external services used.

# How SWS Works During the Signing Flow

When SWS receives a file to sign:

1. **Hash Calculation**
  - SWS calculates the hash of the file.
2. **Hash Transmission to FRA**
  - The hash is sent to the **FRA component**, located in the Namirial CA datacenter.
  - FRA manages the **HSMs (Hardware Security Modules)**.
  - The signature algorithm used is **RSA**.
3. **Signature Generation**
  - FRA signs the hash (RAW PKCS#1 signature).
  - The signed hash is returned to SWS.
4. **Signature Composition**
  - SWS embeds the RAW signature into the requested format (CAdES, PAdES, XAdES, etc.).
  - If required, a timestamp is added.


## Network and Bandwidth Considerations

If SWS is deployed inside the same LAN as the client applications:

- Document exchange happens over a private network.
- Only the **hash** is transmitted to FRA.
- Approximately **7 KB per signature** are exchanged, regardless of document size.
- Merged requests reduce bandwidth usage thanks to:
  - TCP optimization
  - HTTPS efficiency
  - SOAP protocol efficiency


## External Services Used

SWS exposes services via:

- **SOAP**
- **REST**


SWS acts as a client toward the following services:

### 1. RAW Signature Service (PKCS#1)

- Endpoint: `https://fra.firmacerta.it`
- High reliability service.
- HSM and FRA components are functionally redundant.


### 2. Timestamping Authority (TSA)

Supported protocols:

- HTTP
- HTTPS


Namirial TSA endpoints:

- `http://timestamp.firmacerta.it`
- `https://timestamp.firmacerta.it`


### 3. Certification Authorities (CA)

For verification of signatures, SWS contacts:

- The CA that issued the signer’s certificate
- To validate certificate status (revocation checks, validity)


### 4. Trusted List (TLS) Updates

SWS periodically contacts:

- National supervisory bodies of EU Certification Authorities
  - In Italy: **AgID**


## High Availability

SWS is stateless.

To ensure high reliability:

- Deploy **2 or more SWS instances**
- Use a **Load Balancer**
- Configure a **Round-Robin policy with same weight**


Since SWS does not manage sessions:

- No sticky sessions are required.


# How SWS Works During the Verify Flow

# Type of Distributions

SWS can be distributed in two modes:

## 1. On-Premise

- The customer receives:
  - A **Docker image**
- Deployment is managed within the customer infrastructure.


## 2. SaaS

- The customer receives:
  - An integration endpoint
  - An SSL certificate
- Infrastructure and maintenance are managed by Namirial.


# Best Practice

Namirial recommends:

- Deploying **at least 2 active SWS instances**
- Configuring them behind a **load balancer**
- Ensuring proper monitoring of:
  - Connectivity to FRA
  - Connectivity to TSA
  - CA reachability


Each instance is:

- Stateless
- Independent
- Not sharing sessions


# Recommendations

⚠ **The SWS appliance must NOT be publicly exposed to the Internet.**

Namirial does not assume responsibility for improper exposure.

SWS should be:

- Deployed inside a protected network (LAN or secured environment)
- Accessible only by authorized internal applications


# License

Below is the list of libraries/frameworks used in SWS:

| Library / Framework | License |
|  --- | --- |
| DSS (Digital Signature Service) | [LGPL-3.0](https://www.gnu.org/licenses/lgpl-3.0.en.html) |
| BouncyCastle | [BouncyCastle License](https://www.bouncycastle.org/licence.html) |
| Apache Commons | [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) |
| CXF | [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) |
| PDFBox | [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) |
| Xerces | [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) |
| Xalan | [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) |
| xml-apis | [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) |
| xmlschema-core | [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) |
| xmlsec | [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) |