Table of Contents

style	none

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:

...

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.

...

Code Block
--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:

...

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

Administration
Anchor
47912127-c510-4b78-8fc4-66cdfc1943a7
47912127-c510-4b78-8fc4-66cdfc1943a7

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

...

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:

...

Code Block
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 If you need to enable. you should add this field to docker run:

...

Code Block
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:

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

While the swagger endpoint will be published at this endpoint:

...

Or you can use a dedicated endpoint to enable it:

Description	Allows to enable swagger ui
HttpMethod	PUT
Path	swagger
Header	NAME: “x-api-key” VALUE: “API_KEY”
Response	Return the status code 200

Below you can find an example using curl:

Code Block
curl -i -X PUT 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:

Code Block
upload-keystore

Below you can find the details to execute the method:

Description	Allows to migrate from TEST to PROD environment
HttpMethod	POST
Path	upload-keystore
Header	NAME: “x-api-key” VALUE: “API_KEY”
Body	NAME: “file” VALUE: “JKS keystore”
Response	Return the status code 200 if the keystore was correctly loaded and the instance has been migrated to production environment

Below you can find an example using curl:

Code Block

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 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.

Code Block
check-connection

Below the details to execute the method:

...

Description

...

Allows to check the connection between SWS and Namirial servers

...

HttpMethod

...

GET

...

Path

...

check-connection

...

Response

...

/server-admin/swagger \
-H 'x-api-key: API_KEY'

Once complete the request, you must restart the service (in case on SWS standalone) or restart the docker image

At this link will be published the OPENAPI endpoint:

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

While the swagger endpoint will be published at this endpoint:

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

How can disable opeapi and swagger?

If you need to enable. you should add this field to docker run:

Code Block
-e SPRINGDOC_API_DOCS_ENABLED=true

The run command, will be:

Code Block
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

Or you can use a dedicated endpoint to enable it:

Description	Allows to enable swagger ui
HttpMethod	PUT
Path	swagger
Header	NAME: “x-api-key” VALUE: “API_KEY”
Response	Return the status code 200

Below you can find an example using curl:

Code Block
curl -i -X GETPUT 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:

Code Block
sys-info

Below you can find the details to execute the method:

...

Description

...

Allows to check the configurations of the SWS instance

...

HttpMethod

...

GET

...

Path

...

swagger \
-H 'x-api-key: API_KEY'

Once complete the request, you must restart the service (in case on SWS standalone) or restart the docker image

At this link will be published the OPENAPI endpoint:

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

While the swagger endpoint will be published at this endpoint:

Code Block
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:

Code Block
upload-keystore

Below you can find the details to execute the method:

Description	Allows to migrate from TEST to PROD environment
HttpMethod	POST
Path	upload-keystore
Header	NAME: “x-api-key” VALUE: “API_KEY”
Body	NAME: “file” VALUE: “JKS keystore”
Response	Return the status code 200

and the body with configuration details

NOTE:

The response body will be like this:

...

if the keystore was correctly loaded and the instance has been migrated to production environment

Below you can find an example using curl:

Code Block

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:

Code Block

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:

View file

name	PDF_Sample_HelloWorld.pdf

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.

Code Block
check-connection

Below the details to execute the method:

Description	Allows to check the connection between SWS and Namirial servers
HttpMethod	GET
Path	check-connection
Response	Return the status code 200 if the connection with Namirial environment is correctly established

Below you can find an example using curl:

Code Block
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:

Code Block
sys-info

Below you can find the details to execute the method:

Description	Allows to check the configurations of the SWS instance
HttpMethod	GET
Path	sys-info
Response	Return the status code 200 and the body with configuration details

NOTE:

The response body will be like this:

Code Block

{
    "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"
}

...

Code Block
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:

...

NOTE:

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

Code Block

language	bash

curl -i -X DELETE 'http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/server-admin/update-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:

...

Code Block

language	bash

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:

Code Block

language	bash

curl -i -X DELETE 'http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/server-admin/proxy' \
 }
}'

NOTE:

--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 delete the proxy-config, you can use DELETE action on the same resource as you can see below:

Code Block

language	bash

curl -i -X DELETE 'http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/server-admin/configure-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:

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

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

Code Block
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:

Code Block
/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:

Code Block
export-log

Below the details to execute the method:

Description	Allow to set the proxy configuration
HttpMethod	GET
Path	export-log
Header	NAME: “x-api-key” VALUE: “API_KEY”
Response	Return the status code 200 and a zip files with the log in the body

Below you can find an example using curl:

Code Block

language	bash

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:

Code Block
configure-https

...

Description

...

Allows to expose the service on 8443 port using HTTPS protocol

...

HttpMethod

...

POST

...

Path

...

configure-https

...

Header

...

NAME: “x-api-key”

VALUE: “API_KEY”

...

NAME: “keystore”

VALUE: file with keystore

...

Body

...

NAME: “options”

VALUE:

{
"type": "[PKCS12 | JKS ]",
"password": "password of keystore",
"alias": "key alias to use"
}

...

Response

...

Return the status code 200

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 curlretrieve the log files, first of all you have to enable log on files (re)running the docker instances with the environment variable:

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

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

Code Block
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:

Code Block
/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:

Code Block
export-log

Below the details to execute the method:

Description	Allow to set the proxy configuration
HttpMethod	GET
Path	export-log
Header	NAME: “x-api-key” VALUE: “API_KEY”
Response	Return the status code 200 and a zip files with the log in the body

Below you can find an example using curl:

Code Block

language	bash

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:

Code Block
configure-https

Description	Allows to expose the service on 8443 port using HTTPS protocol
HttpMethod	POST
Path	configure-https
Header	NAME: “x-api-key” VALUE: “API_KEY”
	NAME: “keystore” VALUE: file with keystore
Body	NAME: “options” VALUE: { "type": "[PKCS12 \| JKS ]", "password": "password of keystore", "alias": "key alias to use" }
Response	Return the status code 200

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:

Code Block

language	bash

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:

Code Block

language	bash

curl -i -X POSTDELETE 'http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/server-admin/configure-https' \
--header 'x-api-key: API_KEY' \
--form 'keystore=@SSL_CERTIFICATEhttps' \
--form 'options="{ 
	\"type\": \"KEYSTORE_TYPE\",
	\"password\": \"KEYSTORE_PASSWORD\", 
	\"alias\": \"KEY_ALIAS\" 
}"' -vheader '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:

...

Code Block

language	bash

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:

...

Code Block

language	bash

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:

...

Code Block

language	bash

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:

...

Version	Old Version 1	New Version Current
Changes made by	Lorenzo Cardinali	Lorenzo Cardinali
Saved on	Oct 21, 2024	Nov 27, 2024

Content Comparison

Versions Compared

Key

Installation

How can i obtain the SWS on Docker?

Minimum Requirements

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

Administration Anchor47912127-c510-4b78-8fc4-66cdfc1943a747912127-c510-4b78-8fc4-66cdfc1943a7

How change the api-key (password)?

How can enable opeapi and swagger?

How can I migrate from TEST to PROD environment?

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

How can disable opeapi and swagger?

How can I get the system info?

How can i migrate from TEST to PROD environment?

How can i check if sign works?

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

How can I get the system info?

How can I edit the timestamp configuration?

How can I configure proxy on SWS?

How can I enable the logs on file?

How can I enable the logs on file?

How can i export log on files?

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

How can i export log on files?

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

How can I manage fonts?

How can I add custom font?

How can I delete custom font in SWS?

How can I obtain the latest version?

Administration
Anchor
47912127-c510-4b78-8fc4-66cdfc1943a7
47912127-c510-4b78-8fc4-66cdfc1943a7