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)?

...

How can enable opeapi and swagger?

By default, for security reason openapi and swagger are disabled. if you need to 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 if sign works?

...

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 POSTPUT 'http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/sign/signPades'server-admin/swagger \
--headerH 'Contentx-api-Typekey: 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

...

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 if the

connection with Namirial environment is correctly established

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 GETPOST 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",
        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"
}

...

If you need to delete (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'

...

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,
        "httpusername": {"String",
        "hostpassword": "String",
    },
    "porthttps": integer,{
        "usernamehost": "String",
        "passwordport": "String"integer,
    },     "httpsusername": {"String",
        "hostpassword": "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/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)

...

}
}'

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' \
--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 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_CERTIFICATE/https' \
--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:

...

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

Versions Compared

Key

Administration
Anchor
47912127-c510-4b78-8fc4-66cdfc1943a7
47912127-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 if sign works?

How can disable opeapi and swagger?

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

How can i migrate from TEST to PROD environment?

How can I get the system info?

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 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 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 manage fonts?

Content Comparison

Versions Compared

Key

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 if sign works?

How can disable opeapi and swagger?

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

How can i migrate from TEST to PROD environment?

How can I get the system info?

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 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 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 manage fonts?

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