Installation

SWS has been released on Docker image. SWS on Docker require the volume to share the configuration between all instances of SWS executed on orchestrator (like Kubernetes)

How can i obtain the SWS on Docker?

Namiral publish the docker images of SWS on this repository:

https://hub.docker.com/repository/docker/namirial/sws/general

Before running the SWS docker image, you should create a volume by the following command (it will be used to save a custom configuration and to share it with other SWS instances):

docker volume create VOLUME_NAME

After the creation of dedicated volume has been completed, you can run the docker image:

docker run -d --name NAME_OF_ISTANCE -v VOLUME_NAME:/opt/sws/custom -p 8080:8080 namirial/sws:latest

At the end of this command, the SWS will be available on 8080 port.

NOTE: Once the installation has been completed, the SWS is ready to communicate with Namirial environment

Minimum Requirements

For proper operation it is necessary that the virtual machine has allocated at least the following resources. By default sws docker image, use the 70% of the memory available.

In the previous command to execute, you should add this properties:

--memory=1024m --cpus=2

How can I check if the installation has been completed succesfully?

To check if the docker instance has been executed without erros, you can open this link from browser:

http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/ready

And the output will be like this:

And check if the field “global” is “UP”

Administration

Below will be described the methods used to manage the configurations.

All administration methods are defined on this path:

http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/server-admin/

Some administration methods require the authentication key (api-key). The default api key is “foo123”

Namirial reccomends to change this key.

The next command require to use a curl, if you are not a friendly with this tool or prefer to use a gui interface, you can use a postman.

The collection can be obtained from this link

How change the api-key (password)?

The method used to change the authentication key is exposed at this path:

change-apikey

Below you can find the details to execute the method:

Below you can find an example using curl:

curl -i -X PUT http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/server-admin/change-apikey?newApiKey=NEW_API_KEY \
-H 'x-api-key: OLD_API_KEY'

How can enable opeapi and swagger?

By default, for security reason openapi and swagger are disabled. if you need to enable. you should add this field to docker run:

-e SPRINGDOC_API_DOCS_ENABLED=true

The run command, will be:

docker run -d --name NAME_OF_ISTANCE -v VOLUME_NAME:/opt/sws/custom -e SPRINGDOC_API_DOCS_ENABLED=true -p 8080:8080 namirial/sws:latest

At this link will be published the OPENAPI endpoint:

 http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/openapi

While the swagger endpoint will be published at this endpoint:

http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/openapi-ui.html

How can i migrate from TEST to PROD environment?

When you install the docker image, the instance is configured to communicate with Namirial TEST environment. To migrate from TEST to PROD environment, you can use this method:

upload-keystore

Below you can find the details to execute the method:

Below you can find an example using curl:

curl -i -X POST http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/server-admin/upload-keystore \
-H 'x-api-key: API_KEY' \
--header 'Content-Type: multipart/form-data' \
--form 'file=@/PATH_OF_SSL_CERTIFICATE/prod_sws_namirial.jks'

How can i check if sign works?

After installation, we can try to to make a Pades signature (to check if the system has been configured correctly). Using this command:

curl -X POST 'http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/sign/signPades' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/octet-stream' \
--form 'credentials="{
\"username\":\"@USERNAME@\",
\"password\":\"@PASSWORD@\"
}"' \
--form 'padesPreferences="{
  \"level\": \"B\"
}"' \
--form 'buffer=@/PATH_OF_PDF/PDF_Sample_HelloWorld.pdf' -i -o pdfSigned.pdf

Below the PDF to sign:

REPLACE the placeholder (“@USERNAME@” and “@PASSWORD@”) with a device assigned.

How can I check the connection between SWS and Namirial servers?

SWS application use external servers (managed by Namirial) to perform the hash signature (PKCS#1). This method allows to check if the comunication between SWS and Namirial servers correctly works.

check-connection

Below the details to execute the method:

Below you can find an example using curl:

curl -i -X GET http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/server-admin/check-connection

How can I get the system info?

If you need to know the configurations used by Docker like: environment, version ecc.., you can use this resource:

sys-info

Below you can find the details to execute the method:

NOTE:

The response body will be like this:

{
    "instanceId": "7ab517b3-e9f7-44a8-8465-32eda841c271",
    "version": "3.0.0",
    "environment": "TEST",
    "authCertificate": {
        "subjectCN": "SWSSB_TEST",
        "certSerialNumber": 6648983911921208713,
        "notBefore": "09/09/2024 16:28:21",
        "notAfter": "27/10/2042 08:54:06"
    },
    "refreshTslIntervalInSeconds": 6000,
    "tsaUrl": "http://timestamp.test.firmacerta.it",
    "tsaUsername": "no_tsa_user",
    "proxyConfig": {
        "http": {
            "host": "",
            "port": 0,
            "username": "",
            "password": "********"
        },
        "https": {
            "host": "",
            "port": 0,
            "username": "",
            "password": "********"
        }
    },
    "retrievedAt": "10/10/2024 12:59:35"
}

Below you can find an example using curl:

curl -i -X GET http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/server-admin/sys-info

How can I edit the timestamp configuration?

If you need to set the custom configurations about timestamp (RFC3161) and the TSL (Trusted List) refresh period, you can specify the following fields:

• tsaUrl

• tsaUsername

• tsaPassword

• tlsRefresh

and use the following resource:

update-configs

Below you can find the details to execute the method:

Below the example using a curl:

curl -i -X PUT 'http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/server-admin/update-configs' \
--header 'x-api-key: API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "refreshTslIntervalInSeconds": 36000,
    "tsaUrl": "http://",
    "tsaUsername": "user",
    "tsaPassword": "passwrd"
}'

NOTE:

If you need to delete (restore to default configuration), you can use the action DELETE as you can see below:

curl -i -X DELETE 'http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/server-admin/configs' \
--header 'x-api-key: API_KEY'

How can I configure proxy on SWS?

By default SWS doesn’t use proxy, but it is possible to configure it using the following resource:

configure-proxy

Below you can find the details to execute the method:

Below you can find an example using curl:

curl -i -X POST 'http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/server-admin/configure-proxy' \
--header 'Accept: application/json' \
--header 'x-api-key: API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "http": {
        "host": "String",
        "port": integer,
        "username": "String",
        "password": "String"
    },
    "https": {
        "host": "String",
        "port": integer,
        "username": "String",
        "password": "String"
    }
}'

NOTE:

If you need to delete the proxy-config, you can use DELETE action on the same resource as you can see below:

curl -i -X DELETE 'http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/server-admin/proxy' \
--header 'x-api-key: API_KEY'

How can I enable the logs on file?

By default SWS log on console, therefore it’s not possible to download the files with logs. If you need to retrieve the log files, first of all you have to enable log on files (re)running the docker instances with the environment variable:

-e LOGGING_CONFIG=/opt/sws/default/log4j2-rolling-file.xml

Below you can find the docker command used to specify the log file

docker run -d --name NAME_OF_INSTANCE -v VOLUME_NAME:/opt/sws/custom -p 8080:8080 -e LOGGING_CONFIG=/opt/sws/default/log4j2-rolling-file.xml namirial/sws:latest

NOTE: the log files will be saved in:

/opt/sws/log/${DOCKER_UUID}

How can i export log on files?

If you need to export log, SWS offer a specific resource to download the files.

IMPORTANT: before to download log on files → you must enable “log on files”

The resource to download the logs is:

export-log

Below the details to execute the method:

Below you can find an example using curl:

curl -i -X GET 'http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/server-admin/export-log' \
--header 'x-api-key: API_KEY' -o path/file_with_log.zip

How can I expose SWS services on 8443 port using HTTPS protocol?

By default SWS is exposed on 8080 port using HTTP protocol, but if you want to expose SWS services on 443 port using HTTPS protocol, you have to provide a keystore containing SSL private key and certificate by the following resoruce:

configure-https

After the execution you should restart the docker SWS and finally will be exposed on port 443 (https protocol)

Below you can find an example using curl:

curl -i -X POST 'http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/server-admin/configure-https' \
--header 'x-api-key: API_KEY' \
--form 'keystore=@SSL_CERTIFICATE' \
--form 'options="{ 
	\"type\": \"KEYSTORE_TYPE\",
	\"password\": \"KEYSTORE_PASSWORD\", 
	\"alias\": \"KEY_ALIAS\" 
}"' -v

If you need remove https configuration, you can use the action “DELETE”, below the example:

curl -i -X DELETE 'http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/server-admin/https' \
--header 'x-api-key: API_KEY'

How can I manage fonts?

When you perform PAdES signatures using appereance, you can specify the font name (padesPreferences.signerImage.fontName). SWS offers some font name that you can see by the following resource:

fonts

You can see the font name availables.

Below you can find the example using curl:

curl -i -X GET 'http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/server-admin/fonts' \
--header 'x-api-key: API_KEY'

How can I add custom font?

Sometimes can happen a customer need to use a specific font. If it is not present, is possible to add manually providing the “ttf” file related to the font, using this resource:

fonts

You can see the font name availables.

NOTE: after the request success, you can use the new font specifying the filename. For example, if you have uploaded the file: “MY_FONTS1.ttf”, to use this font you should specify in the signing request:

padesPreferences.signerImage.fontName=MY_FONTS1.ttf

Below you can find an example using curl:

curl -i -X POST 'http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/server-admin/upload-fonts' \
--header 'x-api-key: API_KEY' \
--form 'font=@FONT_FILENAME.ttf'

How can I delete custom font in SWS?

If you have uploaded a font by mistake or want remove a font unused, you can use this resource:

fonts

You can see the font name availables.

{
  "fontNames": [
    "FONTNAME1.ttf", "FONTNAME2.ttf"
  ]
}

For example if you want delete the font files “MY_CUSTOM1_FONT.ttf” and “MYCUSTOM2_FONT.ttf”, the body request will be:

{
  "fontNames": [
    "MY_CUSTOM1_FONT.ttf",
    "MY_CUSTOM2_FONT.ttf"
  ]
}

If the second font doesn’t exist, the response body will be:

{
    "details": [
        {
            "name": "MY_CUSTOM1_FONT.ttf",
            "deleted": true
        },
        {
            "name": "MY_CUSTOM2_FONT.ttf",
            "deleted": false
        }
    ],
    "deletedCount": 1
}

So only the “MY_CUSTOM1_FONT.ttf” font was deleted.

Below you can find an example using curl:

curl -X DELETE 'http://localhost:8080/SignEngineWeb/rest/server-admin/fonts' \
--header 'x-api-key: foo123' \
--header 'Content-Type: application/json' \
--data '{
  "fontNames": [
    "A_DejaVuSansMono.ttf",
    "ffff.ttf"
  ]
}'

How can I obtain the latest version?

If you want updated sws to latest version, you can do:

docker pull namirial/sws:latest