...
And check if the field “global” is “UP”
Administration
| Anchor | ||||
|---|---|---|---|---|
|
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 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 |
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 | ||
|---|---|---|
|
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"
} |
...
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 | ||
|---|---|---|
| ||
curl -i -X DELETE 'http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/server-admin/update-configs' \
--header 'x-api-key: API_KEY' |
...
| Code Block | ||
|---|---|---|
| ||
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 | ||
|---|---|---|
| ||
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 | ||
|---|---|---|
| ||
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 | ||
|---|---|---|
| ||
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 | ||
|---|---|---|
| ||
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: { |
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 | ||
|---|---|---|
| ||
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 | ||
|---|---|---|
| ||
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:
...